Discuss text printing

Ok, let me propose a design based on the latest discussion.

public sealed class TextOptions
{
    Color Color { get; set; }
    Font Font  { get; set; }
    TextAlignment Alignment  { get; set; }
    TextDirection Direction  { get; set; }
}
 
public sealed class TextPrinter
{
    public TextExtents Measure(string text, TextOptions options, Vector2 boundingBox, ref Vector2 advance);
    public void Print(string text, TextOptions options, Vector2 boundingBox, ref Vector2 advance, ref Matrix4 modelview, ref Matrix4 projection);
}

Both Measure and Print operate on text runs. A text run is defined as a continuous part of the text that uses the same TextOptions. Text may consist of one text run (which can be measured or drawn in a single call) or multiple runs (which must be drawn or measured in multiple calls).

Conceptually, it is:

public sealed class TextRun
{
    string Text { get; }
    TextOptions Options { get; }
}
 
public sealed class Text : IEnumerable<TextRun>
{ }

It is the user's responsibility to split text into text runs.

Parameters

"text" is the string for the current text run. If text is null, an ArgumentNullException shall be thrown. If text.Length is 0, Measure shall return an empty TextExtents instance. If text.Length is 0, Print shall return without rendering. In both cases, the advance position shall remain unchanged.

"options" is the TextOptions instance for the current text run. If options is null, an ArgumentNullException shall be thrown.

"boundingBox" is an optional parameter that specifies the maximum width and height of the text. It is used to perform word wrapping and clipping. If this parameter is omitted, the text shall not be wrapped or clipped. If Vector2.X or Vector2.Y is negative or zero, no wrapping or clipping will take place in the relevant direction.

"advance" is an optional parameter that specifies the advance position of the text run inside the bounding box. If TextDirection is left-to-right, advance defines the top-left corner of the first visible glyph. If TextDirection is right-to-left, advance defines the top-right corner of the first visible glyph. When the method returns, advance shall contain the advance position of the next text run.

"modelview" is an optional parameter that can be used to translate, rotate or shear the text run. It is applied after text layout, during text rendering. If modelview is omitted, text shall be transformed by the identity matrix. If modelview is specified, text shall be transformed by the specified matrix. If modelview is specified and the deprecated OpenGL matrix stack is in use, the resulting transformation is undefined. For compatibility reasons, the deprecated OpenGL matrix stack shall be used, if available, when modelview is omitted. In all cases, the state of the OpenGL matrix stack shall be retained.

"projection" is an optional parameter that can be used to specify a custom text projection. It is applied after text layout, during text rendering. For compatibility reasons, the deprecated OpenGL matrix stack shall be used, if available, when projection is omitted. If projection is omitted and the OpenGL matrix stack is not available, the following orthographic projection shall be used: (top, left, right, bottom, zNear, zFar) = (0, 0, viewport width, viewport height, -256, 256). If projection is not omitted, text will be projected by the specified matrix. In all cases, the state of the OpenGL matrix stack shall be retained.

Questions

1. Should text layout and measurements take place in logical or ink space?

Good catch.

• Word wrapping: occurs when the text run touches or crosses over the edge of the boundingBox. The exact details details are script-, OS- and implementation-specific. Because the exact line count of a text run may differ when word wrapping is employed, user interfaces should be designed to adapt dynamically, for example by expanding or displaying scrollbars as necessary.
• Clipping: the TextPrinter guarantees that a text run will not overflow the specified boundingBox. Overflowing text shall not be rendered. A ellipsis marker may be placed to indicate the existence of overflowing text; this is an implementation detail.

The above design is a slightly more flexible version of System.Drawing.Graphics.[Draw|Measure]String API. While low-level, it should allow you to render formatted text (with colors, fonts, styles, etc) with relatively little work. That's the idea, at least.

How do you use the API?

I wonder if just taking a texture to print on and returning the bounding box for the text positioning on that texture would be a good addition to the text printer function.

I'm thinking something like:

public TextExtents PrintToTexture(int textureHandle, string text, TextOptions options, Vector2 boundingBox, ref Vector2 advance);

This would allow the user to then draw the text as a quad anywhere they wished, in any manner they wished, applying blending and matrix translations however they desired.
Obviously boundingBox would have to be <= the size of the texture, which would expect some common sense from the user.
The returned TextExtents should allow the user to easily create any texture coordinates, and indeed taken to an extreme the TextPrinter class could be used to create a sheet of characters for the user to create their own text printing techniques from, using the returned GlyphExtents (unless I'm reading the TextExtents class wrong).

Good/bad idea?

@Inertia: great memory!

Other than decals, the new API covers everything else. Decals can be done in two steps: render to texture and use the texture as a decal.

@Mincus: Just use a regular FBO:

GL.BindFramebuffer(FramebufferTarget.Framebuffer, fbo_id);
TextPrinter.Print(...);
GL.BindFramebuffer(FramebufferTarget.Framebuffer, 0);

Trying to add render-to-texture support to the TextPrinter would introduce a host of new problems that have nothing to do with text printing itself:

• What if you've bound a different FBO? Should we save and restore it?
• What if FBOs are not even supported? PBuffers? No way!
• What if you are using code GL3.0 FBOs and the TextPrinter is using EXT_framebuffer_object? They should be compatible, but you never know...
• What if textureHandle is not valid?
• What if textureHandle is not renderable?

Nope, won't work. If you need render-to-texture, just redirect the TextPrinter to a FBO. :)

@Fiddler: Ok, that's all good then. :o)
I just thought if the text was rendered to a texture internally anyway then that was placed on the screen, in which case providing the user with that texture directly would be an easy solution, I see now that's not the case and the FBO idea makes more sense.

That means that objarni's list (as it currently stands) all seem to be covered. Once you have the text in a format like that you can do anything you want with it from what I can see.

What dependencies would Pango bring in..? A native .dll/.so for each operating system? Or is it .NET based? Maybe even open source so it could be compiled into OpenTK.Utilities.dll?

Regarding tutorials we have a FBO example in OpenTK and the book contains a rather verbose description of the FBO extension. If this is not sufficient to get you to print some text - instead of the random triangles - into the texture it would help if you tell where you got stuck, so either the example or the tutorial can be enhanced.

Just for the record, I totally agree that TextPrinter should not deal with FBOs or PBOs. Binding a framebuffer is a rather expensive operation (which does not mean it should not be done, but rather it should be done as seldom as possible) and the application programmer can usually chose a logic that suits his application alot better than a generic solution could. Afaik the best course of action is to bind multiple (target) textures to the FBO color attachments at the same time and use GL.DrawBuffers() to select them one after the other to write text into them.

Hmm, it seems Pango and .Net itemize strings differently (the measured TextExtents contain a different number of clusters than the string they originated from). Nice.

We could go down to the character level where the counts match, but this only works for simple latin scripts. The other solution is to refactor the data structures and move glyph/cluster information to the TextExtents - which means a lot of duplication. Even nicer.

The TextPrinter project will be spun off from the main OpenTK distribution. Maintainers wanted.