Top 10 API changes that you will hate

[tinne26]

I'm publicly listing some planned API changes in case people have any opinions. If you have any opinions regarding other parts of the library that you also consider relevant, now it's a good time to speak so I can consider them.

• Merge NewStdRenderer() and NewRenderer(rast) into NewRenderer(arguments ...any). This is the most controversial change as it affects almost all users of the library, and using variadic args is not particularly loved by the community, but it allows shorter init, I'll add a special flag Cache16MiB for simpler automatic cache initialization, can pass the rasterizer, sizer, font, color, size, align and more right away, etc. May not be very type safe, may not be very beautiful, but it's practical. Worst case, you keep using it without arguments and then use the manual setters.
• Remove NewDefaultCache() given the new Cache16MiB flag, and leave only the ecache.NewDefaultCache() version.
• Replace QuantizationMode with a Renderer.SetQuantizeStep(), so we don't only have full or no quantization, but can compromise at any value in between.
• Due to the new quantization mode, when compromising, we will need SelectionRectAt(text, x, y), because we need to allow passing the exact fractional positioning or precision losses can easily accumulate after each glyph advance + quantization. I'm also considering renaming SelectionRect to Measure. I preferred SelectionRect due to being more technically accurate and explicit, but at the end of the day it may not matter and we may prefer a shorter name. Also, renderer.Fract.MeasureAt() sounds better to me than renderer.Fract.SelectionRectAt(), which starts to get just a bit too long.
• Hide fixed.Int26_6 values under a new fract.Pixel and fract.Rect model. Basically, etxt/fract will replace etxt/efixed, but will become much more prominent too. Since the ugly internal-sounding names will be gone, I think this will make more sense to everyone.
• With the arrival of fract.Rect, that will become the return value of SelectionRect / Measure, and RectSize will disappear.
• Two "modules" will be made public on Renderer: Renderer.Fract and Renderer.Glyph. These will have their own types and will provide access to fractional-pixel and glyph index operations respectively. Instead of Renderer.Draw() and Renderer.DrawFract(), we will have Renderer.Draw() and Renderer.Fract.Draw(). Same for size, traverse, selectionRect/measure and a few others. For glyphs, this will also be much cleaner, and some of the most internal-sounding operations like LoadGlyphMask and DefaultDrawFunc will become renderer.Glyph.LoadMask() and renderer.Glyph.DrawGlyph(). I think the organization of the documentation should be significantly improved, and these more advanced operations will clutter the main Renderer documentation much less. Also, glyphs will have a proper place and I can delete the eglyr subpackage, which I don't love.
• Line height and others will be moved into the Sizer, which will deal with both horizontal and vertical text spacing tasks instead. This will remove quite a few methods that are currently mostly polluting the renderer's documentation.
• Probably will expose font metrics and a few others more readily on the renderer.
• Rename SetSizePx() to simply SetSize(). I don't know why, but under the more structured model I like it more.
• Add SetScaling() and have display scaling support be directly provided in the renderer. This will allow using SetSize() with logical sizes and have to do less conversions when working, creating a simple path for people to do HiDPI right. Two display scaling modes, ScaleFract (fract.Pixel based) and ScaleNear (int based) will be added and supported in NewRenderer(...). So, proper cached, HiDPI rendering will be more easily available by simply calling NewRenderer(etxt.Cache16MiB, etxt.ScaleFract).
• Better support for shaders with the addition of GlyphShader, LineShader and BlockShader under a new subpackage, which will make rendering text with shaders applied significantly more straightforward. Also, multiple kage shaders will be embedded and ready to use.
• There are plans / concepts for a more complete renderer that can process strings that include format (\color[args]{content}, \bold{content}, \size[args]{content}, \italics{content}, etc), do basic line wrapping and that stuff, but this won't happen for the initial big change yet.

[tinne26]

A few more ideas:

• Remove some cache implementation utility methods and simplify the cache signature mechanism. No need for custom user bytes; just leave some space, anyone really interested can do wrapping on its own with minimal hassle anyway.
• Add a Shaper interface and consider support for multiple fonts at the same time (though this does also have impact on Sizers and may complicate other stuff, may require a separate renderer type).
• Considering consecutive line breaks as x1.5 and similar may be relevant and I may want to support it on the move to more complete Sizers, but negative line spacing didn't end up being relevant at all, so maybe I could stop caring about it and simplify some code that currently takes that possibility into account.
• Integrate new Ebitengine composite modes (Blend).
• I don't think the experimental outline renderer will ever work as I originally intended, so start looking into expanding outlines directly. There's quite a bit of overlap, but the resolution when multiple line fragments intersect, specially around curves, is properly solved in other libraries like libass, and my approach, despite the success on basic cases, has already hit a wall with those trickier situations.
• Consider QuantStepPixelHalf, QuantStepPixelThird, QuantStepPixelFourth, QuantStepPixelFifth, ..., QuantStepPixel32th, QuantStepPixel64th constants? I'm still not sold on SetQuantizeStep().
• Consider utils for etxtutil.DrawWithin(*Renderer, image.Rectangle), etxtutil.MaxTextSize(*Renderer, string, image.Rectangle) fract.Pixel? (EDIT: it seems like SetMaxLineLength() and others are more appropriate, and then I should optimize based on target subimage if necessary, but there are a lot of questions surrounding the algorithm (raw line breaking, good for text edition boxes, vs knuth-plass, better for direct presentation) and overflow (horz: allow-cut, omit-letter, omit-word, vert: allow-cut, dont-allow-cut). Tricky stuff. It's like a whole "overflow" configuration.)
• Remove emetric too and end up with etxt/cache, etxt/mask, etxt/sizer, etxt/fract and etxt/utils? For emetric, I could consider adding utils.RuneGlyph(*Renderer, rune), utils.GlyphSegments(...), utils.GlyphCBox(*Renderer, GlyphIndex), utils.CBox(*Renderer, text string)...? I don't know...

[tinne26]

Progress update

I've made some progress in the last months, so I'm writing an update as an exercise for myself. My memory is terrible and this helps me know where I am. The docs for the still incomplete alpha can be previewed at https://pkg.go.dev/github.com/tinne26/[email protected]. There have been multiple interesting decisions and changes from what I initially planned:

• I ended up going simply for NewRenderer() and allowing lazy init of properties to better solve the NewStdRenderer() vs NewRenderer(args ...any) situation. This means some getters and setters have a bit of overhead, but it does feel like the cleaner solution.
• I ended up with multiple "submodules": Renderer.Fract(), Renderer.Complex(), Renderer.Glyph() and Renderer.Utils(). This will be controversial, but I like how main functionality is kept under Renderer and all the strange and advanced things get their own places. The cache issue has been solved with Renderer.Utils().SetCache8MiB().
• We don't need SelectionRectAt(). Or, we would if we allowed non-equidistant quantization partitions, but I prefer to keep things simple. Non-equidistant quantizations are not technically forbidden, but they aren't recommended, as text centering and a few other things become very tricky, both for me and the public API. With equidistant quantization configurations, which are given as QtNone, Qt32th, Qt16th, Qt8th, Qt4th, QtHalf and QtFull, everything remains friendlier.
• The Sizer transformation is done, and now the interface is significantly beefier, carrying more responsibilities. The compromise for vertical spacing is a LineAdvance() method that as a last argument receives an int indicating how many consecutive line breaks we are getting. This allows for "smart/elegant paragraph interspacing". Font metrics are also accessible here now, though they still require a sfnt.Buffer manually passed, which is somewhat uncomfortably low level.
• All other subpackages have been rewritten too. The fract package has not only become a cool and nice abstraction over fixed values, it's also gotten more functions and non-trivial performance improvements.
• The path for markup and more flexible formatting has been set. I've created a new Text type that's just a []byte under the hood and can handle some custom formatting directives, raw glyph indices, utf8, etc. It's all encoded in that single type, which I think is really neat. That being said... implementing the rendering and measuring algorithms for this is not easy, so it will take me a while to get there.
• One of the reasons implementation is getting trickier is the addition of DrawWithWrap() methods. These allow doing very basic and lazy line wrapping automatically when drawing, which was a very common request. For regular string rendering it should be fairly simple to implement, but for Text it may get painful. To be seen, I still have to do the basic string version.
• I have removed Traverse. It felt a bit too low level, mixing fixed point values and being a higher order function. I'm still trying to figure out if feeds and others are good enough substitutes. One big reason for having traverse exposed in the previous versions was that I was implementing the rendering algorithms directly on top of that. Now, I've been optimizing and just copy-pasting code, making the algorithms less dynamic in nature, avoiding closures and all that. I haven't measured the performance yet, but I hope it will make etxt slightly faster (not like it was ever slow, though). The main alternative for the moment is Renderer.Glyph().SetDrawFunc(), which should be even more flexible and it feels more perpendicular, despite being more stateful.
• The Shaper interface remains unclear, but I think Text is flexible enough to make it not necessary. But a lot of work will have to go into this at some point in the future. We will see.