Class TextMesh
Builds solid 3D lettering from a MeshFont: each glyph's outline is triangulated, holes and all, and extruded along Z with a front cap, a back cap and flat-shaded walls, with a rounded edge between them when Bevel asks for one.
public static class TextMesh- Inheritance
-
TextMesh
Remarks
The result is real geometry: it is lit and shadowed, takes any material, casts a shadow, and can
carry a physics body (Primitive3D.Text gives it one through CreatePrimitive). For
ordinary text, labels and HUDs, EntityTextComponent and WorldTextComponent
draw a font far more cheaply; this is for lettering that is meant to be a thing in the world.
Vertices carry a position, a normal and texture coordinates: the caps are mapped across the text's block (0..1 left to right, 0..1 top to bottom), each wall runs 0..1 along its contour and 0..1 from the front to the back, so a texture or a shader can follow the lettering.
Layout is by the font's metrics: the first baseline at y = 0, lines LineHeight apart going down, the pen advancing by each glyph's advance plus the letter spacing, kerned when the font allows. Anchor moves the block so a chosen corner or centre sits at the origin.
All the geometry is worked out in the font's EM units and scaled on the way out, so a word a centimetre across is triangulated exactly as one a metre across. Within one build each distinct glyph is prepared once, however often it occurs. A glyph whose contours cross or overlap, which a few fonts have, is reported by font and code point rather than built wrong.
Methods
Create(MeshFont, string, TextMeshOptions?)
Builds the lettering as one mesh.
public static GeometricMeshData<VertexPositionNormalTexture> Create(MeshFont font, string text, TextMeshOptions? options = null)Parameters
fontMeshFontThe font.
textstringThe text;
\nstarts a new line. Characters the font lacks draw its "missing glyph" box.optionsTextMeshOptionsSize, depth, layout; the defaults are one unit per EM and a depth of 0.25.
Returns
- GeometricMeshData<VertexPositionNormalTexture>
The mesh data; ToMesh(GeometricMeshData<VertexPositionNormalTexture>, GraphicsDevice, int) uploads it with bounds. Empty when the text has nothing to draw, which a GPU upload refuses.
Exceptions
- ArgumentNullException
The font or the text is null.
- ArgumentOutOfRangeException
An option is not a positive finite number where it has to be.
- InvalidOperationException
A glyph cannot be built: its contours cross or overlap, or the bevel folds it; the message names the font and the code point.
CreateGlyphs(MeshFont, string, TextMeshOptions?)
Builds the lettering one glyph at a time, each centred on itself and told where it belongs: for a body per letter, or letters that move on their own.
public static IReadOnlyList<GlyphMesh> CreateGlyphs(MeshFont font, string text, TextMeshOptions? options = null)Parameters
fontMeshFontThe font.
textstringThe text;
\nstarts a new line.optionsTextMeshOptionsSize, depth, layout; the anchor applies to the whole block, as in Create(MeshFont, string, TextMeshOptions?).
Returns
- IReadOnlyList<GlyphMesh>
One mesh per glyph that draws something, in text order; spaces are left out.
Exceptions
- ArgumentNullException
The font or the text is null.
- ArgumentOutOfRangeException
An option is not a positive finite number where it has to be.
- InvalidOperationException
A glyph cannot be built; the message names the font and the code point.
CreateMesh(GraphicsDevice, MeshFont, string, TextMeshOptions?, int)
Builds the lettering, uploads it and wraps it in a Mesh with its bounds, which the renderer needs to cull it when it is off screen.
public static Mesh CreateMesh(GraphicsDevice device, MeshFont font, string text, TextMeshOptions? options = null, int materialIndex = 0)Parameters
deviceGraphicsDeviceThe graphics device the buffers are created on.
fontMeshFontThe font.
textstringThe text;
\nstarts a new line.optionsTextMeshOptionsSize, depth, layout.
materialIndexintThe index of the material the mesh uses in its model.
Returns
- Mesh
The mesh; the caller owns its draw's buffers.
Exceptions
- ArgumentNullException
The device, the font or the text is null.
- ArgumentException
The text has nothing to draw.
CreateMeshDraw(GraphicsDevice, MeshFont, string, TextMeshOptions?)
Builds the lettering and uploads it.
public static MeshDraw CreateMeshDraw(GraphicsDevice device, MeshFont font, string text, TextMeshOptions? options = null)Parameters
deviceGraphicsDeviceThe graphics device the buffers are created on.
fontMeshFontThe font.
textstringThe text;
\nstarts a new line.optionsTextMeshOptionsSize, depth, layout.
Returns
- MeshDraw
A draw for a Mesh; the caller owns its buffers, see ToMeshDraw(GeometricMeshData<VertexPositionNormalTexture>, GraphicsDevice). CreateMesh(GraphicsDevice, MeshFont, string, TextMeshOptions?, int) adds the bounds.
Exceptions
- ArgumentNullException
The device, the font or the text is null.
- ArgumentException
The text has nothing to draw (empty, spaces, line breaks): a GPU buffer cannot be empty, so remove the mesh instead.
CreateModel(GraphicsDevice, Material, MeshFont, string, TextMeshOptions?)
Builds the lettering as a complete Model: one mesh with its bounds, one material.
public static Model CreateModel(GraphicsDevice device, Material material, MeshFont font, string text, TextMeshOptions? options = null)Parameters
deviceGraphicsDeviceThe graphics device the buffers are created on.
materialMaterialThe material the lettering is drawn with.
fontMeshFontThe font.
textstringThe text;
\nstarts a new line.optionsTextMeshOptionsSize, depth, layout.
Returns
- Model
The model, ready for a
ModelComponent; the caller owns the mesh's buffers.
Exceptions
- ArgumentNullException
The device, the material, the font or the text is null.
- ArgumentException
The text has nothing to draw.
Measure(MeshFont, string, TextMeshOptions?)
The box the lettering occupies, in world units, without building it: the font's ascent to its descent over every line, the widest line across, the depth through, moved by the anchor.
public static BoundingBox Measure(MeshFont font, string text, TextMeshOptions? options = null)Parameters
fontMeshFontThe font.
textstringThe text.
optionsTextMeshOptionsSize, depth, layout.
Returns
- BoundingBox
The box.
Exceptions
- ArgumentNullException
The font or the text is null.
- ArgumentOutOfRangeException
An option is not a positive finite number where it has to be.