One was a Doxygen workaround that shouldn't be needed anymore and an
API reference missing from e1c9c4d007, the
other was an inconsistency in a test that was just weird but shouldn't
affect anything.
I'm going to make a new Renderer class that's unlike the old one, and
isn't templated anymore either, so gotta make room for it first. I assume
that all existing code used the Renderer2D / Renderer3D typedefs so this
should be pretty much painless.
Ultimately this class will be gone, with only (then deprecated)
AbstractRenderer left, and Renderer2D / Renderer3D being aliases to it
-- internally it doesn't actually do anything dfferent, even the
positions are two-component in both cases.
The naming was adopted from CSS direction-aware alignment and it took me
quite a while to realize it feels alien, since everything else is using
"begin" and "end", not "start" and "end". So I'm renaming for
consistency.
These enums were originally introduced about 8 months ago but I don't
think anyone is using these yet, since they're not really advertised
anywhere and the existing to-be-deprecated high-level text renderer API
is so shitty that I don't expect it to be used for BIDI text and such,
at all. Sorry if you do, heh.
Now it's less code, and it also no longer results in random edge
artifacts because the padding area wasn't correctly uploaded. I'm going
to do the same change in the FreeTypeFont and StbTrueTypeFont next.
Because otherwise the users likely have to do something similar on their
end to perform a texture upload etc., which means they'll either take
the easy path and upload everything including the unused area, or they
introduce various bugs in the process, leading to random artifacts,
especially when it comes to padding.
Which is exactly what I think is causing random test failures in the Ui
library text rendering, because the glyph cache filling process in
plugins is calculating the rectangle too tight, without considering
padding. Gonna fix that now.
They're not parsed since 6b22a11170
(2020), so there's no point in keeping those workarounds. They're only
kept in utility application sources as they're parsed for pages, and in
tweakable implementations where it's easier to just copypaste the whole
ifdef expression from the header every time instead of modifying it to
not include DOXYGEN_GENERATING_OUTPUT.
Neither a driver bug nor something wrong with the code. It's just
that with a tight flush rectangle the target texture may have some random
garbage left around the edges, causing the comparison to fail, so it's
now explicitly cleared upfront.
Doesn't happen when running the offending test alone (because I suppose
the memory is coming fresh from the driver, being zeroed out for security
purposes), only when running after the others (where I suspect it's now
reusing previous partially-filled memory which it didn't before). Doesn't
happen on NVidia either.
Compared to Corrade, the improvement in compile time is about a minute
cumulative across all cores, or about 8 seconds on an 8-core system (~2
minutes before, ~1:52 after). Not bad at all. And this is with a
deprecated build, the non-deprecated build is 1:48 -> 1:41.
So the users don't accidentally create an instance with the processed
format / size being different only to get greeted by a nasty bounds or
format assertion inside flushImage() / doSetImage().
Now it's only allowed to be done by a subclass (such as
DistanceFieldGlyphCacheGL, or, ahem, MagnumFont), and doSetImage()
additionally has an assert to notify the implementer that a subclass
needs to provide its own override.
This also feels kind of messy, honestly. It's as if the
DistanceFieldGlyphCache should never have been a subclass, maybe?
Now, instead of accessing the texture directly, it uses the public
setProcessedImage() API. For which it needs to subclass the cache in
order to advertise ImageProcessing, which means the class can no longer
have the implementations private.
I don't really like this, ideally none of this would be needed and
MagnumFont would implement fillGlyphCache() instead. Not sure how to do
that yet tho as there's still the issue with DistanceFieldGlyphCacheGL
being RGBA, so this is a half-assed solution until a better one is
found... or the plugin gets ditched completely.
They don't have anything specific to DistanceFieldGlyphCacheGL and on
the other hand contain special-casing for Luminance vs Red on ES2 that's
specific to GlyphCacheGL internals.
Additionally, in DistanceFieldGlyphCacheGL the code could assume that
the pixel format is either R8 with EXT_texture_rg present or RGBA8
without, here it has to check for EXT_texture_rg presence as
GlyphCacheGL can use R8 even without EXT_texture_rg.
Like with TextureTools::DistanceField, to make room for non-GL
implementations. Old names are deprecated aliases, same for headers. The
only remaining bit in the Text library is the Renderer class, but for
that one I first need to invent a non-shitty API so I can just deprecate
the old thing as a whole and create something reasonable from scratch in
RendererGL.
Along with the bits in Text library this is one of the last things that
still assume OpenGL present by default.
As usual, the old name and header is now a deprecated typedef.
The internal GL texture format (especially the R8 vs Luminance mess on
ES2) is now considered an implementation detail and shouldn't affect
common use in any way.
The format is now required always, in order to prepare for use cases
where colored glyphs are a thing as well. Additionally, to match the
recent change in AbstractGlyphCache, the processed format is specified
separately, allowing the input and processed formats to be decoupled.
Which ultimately fixes the regression on ES2 and WebGL 1 where it was no
longer possible to call font.fillyGlyphCache() on a
DistanceFieldGlyphCache.
Also, as there's now a generic format on input, another ES2-specific
issue is now fixed as well, in particular a case where a GL error
would be emitted on drivers with EXT_texture_storage because an unsized
format is passed to setStorage(). This was a problem since a long time
ago, but I ignored it because it didn't affect WebGL 1 and all drivers
that exposed EXT_texture_storage exposed EXT_texture_rg, effectively
circumventing this issue. Or so I think, at least.
The constructors taking either a GL::TextureFormat or no format at all
are now deprecated aliases to the new functionality.
RGB was a hopeful intention that never really worked in practice. Or, if
it worked, it couldn't be queried back, and the driver used RGBA
internally anyway.
The refactor in 6707534ce6 somehow didn't
account for the need to have a different pixel format for the input and
the processed texture, which is needed on ES2 / WebGL 1 because there's
no renderable single-channel format. Which means distance field text
rendering was broken since then.
This commit is the first part of fixing that regression. It makes the
AbstractGlyphCache aware of the processing being done, decoupling the
input and processed format and size. Which also allows the base
implementation to provide interfaces that so far were only limited to
DistanceFieldGlyphCache, thus eventually making it possible for font
plugins to supply a pregenerated distance field image through
fillGlyphCache() and not just through createGlyphCache().
The two DistanceFieldGlyphCache APIs that are now directly on the
AbstractGlyphCache are now deprecated aliases to the new functionality.
The actual fix for the ES2 / WebGL 1 regression will come in the next
commit, as it's pretty much a separate step that involves updating the
GlyphCache as well.
Which is good, those are all either anchors in the theme itself, or are
group names for which Doxygen doesn't make anchors anymore (but m.css
does). Plain HTML link still works as before, so let's do that instead.
This name isn't known to it at the time it parses the header (because no
such header gets included for it), which in turn causes Doxygen 1.12 to
generate a dummy ::Platform namespace. Which then gets a priority over
Magnum::Platform when linked to, and because it's dummy, it's reported
as an error because it's not allowed to link to undocumented stuff.
Doxygen 1.12 has no longer a completely insane matcher and discards
those as it should. With 1.8.17 classes had to be referenced with
Corrade:: but functions, typedefs and variables didn't need to be and it
was a complete utter chaos.
Essential for text selection and editing in cases where mapping from the
input text to the actual shaped glyphs is nontrivial. I.e., in case of
HarfBuzzFont; both FreeTypeFont and StbTrueTypeFont perform a 1:1
translation from input (UTF-8) characters to glyphs so there it isn't
as important.
Having it next to AbstractShaper didn't make sense, as there's various
use cases where font features are specified but the caller code doesn't
even know there's any shaper involved. Such as in the UI library.
Based on the actual text direction (either explicitly set or detected),
these resolve to either *Left or *Right. For the Text::Renderer it's
done automatically inside (and there's no way to actually set the
direction from outside due to the API being ancient and limited), for
the align*() utils the alignment has to be explicitly resolved using a
new alignmentForDirection() utility.
There shouldn't be any other values passed to these. Compilers, don't
even attempt to say that the alignment value is now maybe uninitialized,
I'm watching you!
Vladimír Vondruš