API Reference · Overlays and labels

TextOptions

Namespace: Ava3D

public sealed record class TextOptions

How a string becomes a texture. See Texture.FromText.

Deliberately small. This is not a text layout engine and must not become one: one string, one face, one size, optional wrapping at a width. Rich text, bidi reordering beyond what the shaper does for free, inline runs and flow layout all belong to a UI framework, and a scene that needs them wants Ava3DOverlay and a real TextBlock rather than a quad.

Properties

MemberDescription
bool Bold { get; set; }

Whether the face is asked for in its bold weight. Ignored when TextOptions.Typeface is set.

Vector4 Color { get; set; }

The ink, as it should appear — sRGB, 0..1, with alpha. White by default.

As it should appear rather than as linear radiance, because that is what a texture is: the same bytes a PNG of this text would have carried, decoded by the shader like any other base-colour or emissive map.

string Family { get; set; }

A family name to ask the platform for, when TextOptions.Typeface is not supplied. Null takes the platform default. See TextOptions.Typeface for what either costs.

float LineSpacing { get; set; }

Space between lines, as a multiple of the face's own. One by default.

float MaxWidth { get; set; }

Wrap at this many texture pixels. Zero — the default — sets the whole string on one line.

float Outline { get; set; }

Width of an outline drawn behind the ink, in texture pixels. Zero — the default — draws none.

Worth having on anything that has to stay legible over a scene rather than over a panel: a label in a room passes over light walls and dark ones as the viewer moves, and an outline is what stops it disappearing into one of them. This is Godot's Label3D.outline_size under its own name.

Vector4 OutlineColor { get; set; }

The outline's colour, sRGB with alpha. Opaque black by default.

float Size { get; set; }

Font size (em height) in texture pixels — the resolution of the image, not a size in the scene.

byte[] Typeface { get; set; }

The face's own bytes — a .ttf or .otf as it came off disk or out of a resource.

This is the only option that renders the same everywhere, and on a library that runs the same code on desktop, in a browser, on Android and on iOS that matters more than it sounds. With it null and TextOptions.Family unset the glyphs come from whatever the platform offers, which is four different answers and no way to know which one a viewer is looking at; with a family name it is still a request that a machine without that face answers differently.

See also