gfx_glyph integration redux

[Ratysz]

This is a work in progress; I feel that having specific diffs in front of us makes it easier to discuss exact implementation of #132 (start of discussion can be found there).

(Side note: trying to adopt verbose commit messages, instead of post-factum dissection in comments.)

[Ratysz]

I think I've reached a point where I'll have to start adding (even more) code that's trivial and/or will be removed if we absorb TextCached into Text (or outright replace latter with the former).

It's functional as it is, though I'm not completely sure the transforms in TextCached::draw_ex() all work as they should, or if there's a better way to do that entirely.

Summary:

• Added a pub(crate) glyph_brush: GlyphBrush field to GraphicsContext; it initializes with the same data as Font::default_font() (which had to be slightly rewritten to hopefully avoid duplication).

• Added a Font::GlyphFont variant. It can be created by loading a file with Font::new_glyph_font(), or re-created (retrieved from the brush) from a usize ID via Font::get_glyph_font_by_id(). Don't think there's any (significant) overhead for re-creation. Said font variants's scale information is stored within it, as with current ones (there is no hard reason for it, other than keeping it out of TextCached API).

• Added TextCached drawable. API is nearly identical to Text - the getter methods for width and texture and whatnot are missing; most of them don't make sense in the context.

• Added an (undocumented, but straightforward) example for experimenting with said TextCached.

There are a few standing questions:

• General API. Might be worthwhile to review what methods Text actually needs before we start merging/replacing it; that depends on if we're keeping the rendered Font variants (and if we're not, there will be a lot of dead code in text.rs).

• TextCached bounds, and everything to do with them. From what I understand, gfx_glyph offers automatic wrapping, done via Section::bounds (and Section::layout) field - this can probably be used by/as TextCached::width() and TextCached::height().

• Performance. Two things to investigate: whether or not having separate Font::GlyphFonts for separate font scales is faster than using the same Font::GlyphFont with different scales; and, how much overhead is calling glyph_brush.draw_queued() in every TextCached::draw_ex(), over just once, somewhere, somehow.

• The example. If we end up seamlessly integrating TextCached into Text, it will be entirely pointless.

[Ratysz]

I think I've reached a point where I'll have to start adding (even more) code that's trivial and/or will be removed if we absorb TextCached into Text (or outright replace latter with the former).

It's functional as it is, though I'm not completely sure the transforms in TextCached::draw_ex() all work as they should, or if there's a better way to do that entirely.

Summary:

• Added a pub(crate) glyph_brush: GlyphBrush field to GraphicsContext; it initializes with the same data as Font::default_font() (which had to be slightly rewritten to hopefully avoid duplication).

• Added a Font::GlyphFont variant. It can be created by loading a file with Font::new_glyph_font(), or re-created (retrieved from the brush) from a usize ID via Font::get_glyph_font_by_id(). Don't think there's any (significant) overhead for re-creation. Said font variants's scale information is stored within it, as with current ones (there is no hard reason for it, other than keeping it out of TextCached API).

• Added TextCached drawable. API is nearly identical to Text - the getter methods for width and texture and whatnot are missing; most of them don't make sense in the context.

• Added an (undocumented, but straightforward) example for experimenting with said TextCached.

There are a few standing questions:

• General API. Might be worthwhile to review what methods Text actually needs before we start merging/replacing it; that depends on if we're keeping the rendered Font variants (and if we're not, there will be a lot of dead code in text.rs).

• TextCached bounds, and everything to do with them. From what I understand, gfx_glyph offers automatic wrapping, done via Section::bounds (and Section::layout) field - this can probably be used by/as TextCached::width() and TextCached::height().

• Performance. Two things to investigate: whether or not having separate Font::GlyphFonts for separate font scales is faster than using the same Font::GlyphFont with different scales; and, how much overhead is calling glyph_brush.draw_queued() in every TextCached::draw_ex(), over just once, somewhere, somehow.

• The example. If we end up seamlessly integrating TextCached into Text, it will be entirely pointless.

[icefoxen]

Sorry, took me a couple days to find time to take a good look at this.

I like it.

Only note, you should probably use DrawParam::into_matrix() to set up the transform for TextCached::draw_ex(). Hopefully that makes it all work out correctly.

On to pondering questions...

• General API. I really want to be able to just remove the pre-rendered Text and TTFFont entirely and use gfx_glyph for everything. I want to make an 0.5.0 release that does that, pretty much; my hope is that gfx_glyph will be entirely superior. We can also deal with #268 in the process.
• Bounds, I haven't looked at yet. gfx_glyph definitely has a richer API for text drawing than ggez currently does, and we should take full advantage of that. Love2D isn't quite much guidance because it hides all the Cool Formatting Stuff behind print and printf functions that allow coloring and wrapping of strings; we should probably use something like the TextParam type from dettalant's PR. #92 and #108 would get solved by this. Maybe theoretically #211 someday... Should look at that more.
• Performance I think we have to look at empirically. I will whip up some benchmarks when I have time.
• The example is good for a) profiling, and b) showing off how shiny our stuff is now.

So what I'm imagining now is something that looks sort of like this...

struct TextCached;
impl Drawable for TextCached { 
    fn draw_ex(self, ctx: &mut Context, param: DrawParams) -> GameResult<()> {
        let text_params = param.into(); // Makes a TextParams with reasonable defaults where needed
        self.queue(ctx, params);
        self.draw_queued(ctx);
    }
}
impl TextCached {
    pub fn queue(&self, ctx: &mut Context, params: &TextParams) {
        ctx.glyph_brush.queue(params.into());
    }

    pub fn draw_queued(&self, ctx: &mut Context) {
        ctx.glyph_brush.draw_queued();
    }
}

I think this would let users both do the simple thing easily, and also access the full power of the API... a little like how Mesh and MeshBuilder do about the same thing but one is quick and easy while the other is more powerful.

[icefoxen]

Sorry, took me a couple days to find time to take a good look at this.

I like it.

Only note, you should probably use DrawParam::into_matrix() to set up the transform for TextCached::draw_ex(). Hopefully that makes it all work out correctly.

On to pondering questions...

• General API. I really want to be able to just remove the pre-rendered Text and TTFFont entirely and use gfx_glyph for everything. I want to make an 0.5.0 release that does that, pretty much; my hope is that gfx_glyph will be entirely superior. We can also deal with #268 in the process.
• Bounds, I haven't looked at yet. gfx_glyph definitely has a richer API for text drawing than ggez currently does, and we should take full advantage of that. Love2D isn't quite much guidance because it hides all the Cool Formatting Stuff behind print and printf functions that allow coloring and wrapping of strings; we should probably use something like the TextParam type from dettalant's PR. #92 and #108 would get solved by this. Maybe theoretically #211 someday... Should look at that more.
• Performance I think we have to look at empirically. I will whip up some benchmarks when I have time.
• The example is good for a) profiling, and b) showing off how shiny our stuff is now.

So what I'm imagining now is something that looks sort of like this...

struct TextCached;
impl Drawable for TextCached { 
    fn draw_ex(self, ctx: &mut Context, param: DrawParams) -> GameResult<()> {
        let text_params = param.into(); // Makes a TextParams with reasonable defaults where needed
        self.queue(ctx, params);
        self.draw_queued(ctx);
    }
}
impl TextCached {
    pub fn queue(&self, ctx: &mut Context, params: &TextParams) {
        ctx.glyph_brush.queue(params.into());
    }

    pub fn draw_queued(&self, ctx: &mut Context) {
        ctx.glyph_brush.draw_queued();
    }
}

I think this would let users both do the simple thing easily, and also access the full power of the API... a little like how Mesh and MeshBuilder do about the same thing but one is quick and easy while the other is more powerful.

[icefoxen]

Hilarious benchmark results, from here: https://github.com/icefoxen/ggez/blob/gfx_glyph_integration_too/examples/glyph_bench.rs . It draws 2500 copies of a single text object, either with the current Text::draw(), with the TextCached::draw() from this PR, and with a trivial TextCached::queue() queue'ing up all the copies and TextCached::draw_queued() drawing them all at once.

• Drawing nothing: 880 fps debug, 12,000 fps release
• Drawing with Text::draw(): 2 fps debug mode, 81 fps release mode.
• Drawing with TextCached::draw(): 2 fps debug mode, 265 fps release mode.
• Drawing with TextCached::queue() and TextCached::draw_queued(): 30 fps debug mode, 884 fps release mode.

So, there's basically no reason NOT to use GlyphBrush for everything.

[icefoxen]

Hilarious benchmark results, from here: https://github.com/icefoxen/ggez/blob/gfx_glyph_integration_too/examples/glyph_bench.rs . It draws 2500 copies of a single text object, either with the current Text::draw(), with the TextCached::draw() from this PR, and with a trivial TextCached::queue() queue'ing up all the copies and TextCached::draw_queued() drawing them all at once.

• Drawing nothing: 880 fps debug, 12,000 fps release
• Drawing with Text::draw(): 2 fps debug mode, 81 fps release mode.
• Drawing with TextCached::draw(): 2 fps debug mode, 265 fps release mode.
• Drawing with TextCached::queue() and TextCached::draw_queued(): 30 fps debug mode, 884 fps release mode.

So, there's basically no reason NOT to use GlyphBrush for everything.

[Ratysz]

This is pretty much done, now. Summary, details, and everything else should be apparent from documentation and example.

There are still a few bits to tighten (all marked with TODO) and verify (how well does pixel sizing actually work, etc - mostly things that happened while I was working on this), but it's quite serviceable now.

I'll check up on my other projects, and start working on fully supplanting current Text with this. In a new PR, of course; probably after 0.4.3. Hoping to see any and all criticism, thoughts, and insights well before that!

[Ratysz]

This is pretty much done, now. Summary, details, and everything else should be apparent from documentation and example.

There are still a few bits to tighten (all marked with TODO) and verify (how well does pixel sizing actually work, etc - mostly things that happened while I was working on this), but it's quite serviceable now.

I'll check up on my other projects, and start working on fully supplanting current Text with this. In a new PR, of course; probably after 0.4.3. Hoping to see any and all criticism, thoughts, and insights well before that!