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!
This is going to get called from fillGlyphCache() that takes a string,
and thus should be better than one virtual call per character. The
single-character variant still stays, as it's a nice convenience API.
Eventually glyphSize() will get a similar treatment as well.
Took me quite a while to realize what was going on, but in retrospect
it's obvious -- the rasterizer just *rounds* the sub-pixel-positioned
glyph quads to nearest pixels. Which then can cause the neighboring
glyph data to leak to it (because the texture is then sampled not
directly on the edge pixel, but slightly outside of it), or it can also
cut away the edge, when it gets rounded in the other direction.
This was a problem with the original -- laughably inefficient -- atlas
packer as well, but because that packer had excessive padding around
everything, only the second edge-cutting artifact manifested, and that
one is rather subtle unless you know what to look for.
This means the packing is now slightly worse than before and sizes that
previously worked may no longer fit anymore. But since the new atlas
packer is relatively new (well, from September, time sure flies
different here), and the improvement compared to the original packer is
still quite massive, I don't think this is a problem.
Want to construct them without a GL context present, and Optional is too
wasteful. Also adding it to the AbstractGlyphCache base, where it skips
also allocating the internal PIMPL state, because it's not going to get
used for anything in a NoCreate'd instance anyway.
If Magnum and Corrade get installed into the same directory,
target_include_directories() or target_link_libraries() with Corrade
before Magnum will result in the (usually stale) installed Magnum
headers being picked over the local ones. Which is unwanted, so try to
always put the local Magnum include path first.
Tested manually by installing to an arbitrary location and editing
configure.h to contain an #error. That failed for the Text library, and
with these changes it now doesn't fail anymore, but that's not a
guarantee that I managed to fix all such cases.
Especially given that nullptr causes an assert. All call sites basically
ended up passing a &font and all that extra annoyance just doesn't make
sense.
Given this API is still relatively recent, I'm not bothering with
backwards compatibility.
Which also allows the internals to be a bit simpler / potentially more
efficient, as the implementation can now access the glyph cache contents
directly, without a getter.
The new API makes it possible to alias storage for the glyph offsets,
advances and IDs (20 bytes per glyph) directly with the output positions
+ texcoords (16 bytes per glyph, times four) by splitting the retrieval
in two steps.
I wonder how long will it take before this bites back, heh.
In basically all cases it's two independent operations so forcing them
to be done together doesn't really bring any potential efficiency
advantages. On the other hand, splitting them allows allows the caller
to better make use of available memory, as the new
renderGlyphQuadsInto() allows the input and output arrays to be aliased.
Bumping AbstractFont plugin interface versions as this is a breaking
change.
Vladimír Vondruš