scimesh::TextLayer Struct Reference

A batch of text labels drawn together, in one coordinate space. More...

#include <text.h>

Collaboration diagram for scimesh::TextLayer:

Public Member Functions
size_t	count () const
	Number of labels in this layer.
bool	empty () const
	Whether this layer holds no label with a position and a string.
Color	color_or (size_t i, const Color &fallback) const
	Color of label i, falling back to fallback when the layer holds no colors at all.
Vec3	position_or (size_t i) const
	Position of label i (origin when out of range).
const std::string &	string_or (size_t i) const
	String of label i (empty when out of range).

Public Attributes
std::vector< Vec3 >	positions
	Anchor positions, in world space or in screen pixels.
std::vector< std::string >	strings
	One string per entry in positions (UTF-8; \n for line breaks).
std::vector< Color >	colors
	One color per label; may be empty (then the renderer uses RenderOptions::default_color) or shorter than positions (the last entry is reused for the remaining labels).
std::string	font_file
	Path to the .ttf file to use, or an empty string for the bundled default font (see default_font_path()).
float	size = 16.0f
	Text height ("em" size) in output pixels (default: 16).
TextSpace	space = TextSpace::WORLD
	Coordinate space of positions (default: TextSpace::WORLD).
Vec2	adj = Vec2(0.5f, 0.5f)
	Where the position sits relative to the text box, in [0, 1].
Vec2	offset = Vec2(0.0f, 0.0f)
	Extra offset applied after anchoring, in output pixels (positive x = right, positive y = down).
float	line_spacing = 1.2f
	Distance between two lines of a multi-line string, as a multiple of the height of the font's glyph box (default: 1.2).
float	rotation = 0.0f
	Rotation of the label in degrees, counter-clockwise, about the anchor position (default: 0).
bool	depth_test = true
	Whether the label is hidden by geometry in front of its anchor (default: true).
Color	halo_color = Color(0.0f, 0.0f, 0.0f, 0.0f)
	Color of the halo (outline) drawn behind the glyphs.
float	halo_width = 1.0f
	Halo thickness in output pixels (default: 1).

Detailed Description

A batch of text labels drawn together, in one coordinate space.

A text layer belongs to a Scene (see Scene::add_texts()) and is drawn by the Renderer after the meshes and the line layers, so labels appear on top of the geometry — except when depth_test is on and the annotated point is behind the geometry.

Text layers are deliberately not meshes:

• Scene::compute_bounding_box() ignores them, so adding labels never changes the camera framing.
• The mesh exporters (write_gltf(), write_stl(), ...) skip them.

Example

TextLayer layer;
layer.strings = {"C", "N"};
layer.positions = {Vec3(1, 0, 0), Vec3(0, 2, 0)};
layer.colors = {Color(0.1f, 0.1f, 0.1f, 1.0f), Color(0, 0, 1, 1)};
layer.size = 14.0f;
layer.halo_color = Color(1, 1, 1, 1);   // white outline for dark scenes
scene.add_texts(layer);

See also

Font, TextSpace, draw_text(), Scene::add_texts()

Definition at line 208 of file text.h.

Member Function Documentation

color_or()

Color scimesh::TextLayer::color_or ( size_t  i, const Color &  fallback  ) const

inline

Color of label i, falling back to fallback when the layer holds no colors at all.

Definition at line 297 of file text.h.

count()

size_t scimesh::TextLayer::count ( ) const

inline

Number of labels in this layer.

The positions and strings arrays are expected to have the same length; if they differ, the shorter one limits the number of labels.

Definition at line 290 of file text.h.

empty()

bool scimesh::TextLayer::empty ( ) const

inline

Whether this layer holds no label with a position and a string.

Definition at line 293 of file text.h.

position_or()

Vec3 scimesh::TextLayer::position_or ( size_t  i ) const

inline

Position of label i (origin when out of range).

Definition at line 305 of file text.h.

string_or()

const std::string & scimesh::TextLayer::string_or ( size_t  i ) const

inline

String of label i (empty when out of range).

Definition at line 310 of file text.h.

Member Data Documentation

adj

Vec2 scimesh::TextLayer::adj = Vec2(0.5f, 0.5f)

Where the position sits relative to the text box, in [0, 1].

(0, 0) places the position at the bottom left of the text box, (1, 1) at the top right, and the default (0.5, 0.5) centres the text box on the position — the same idea as adj in R graphics and rgl.

Definition at line 244 of file text.h.

colors

std::vector<Color> scimesh::TextLayer::colors

One color per label; may be empty (then the renderer uses RenderOptions::default_color) or shorter than positions (the last entry is reused for the remaining labels).

Definition at line 221 of file text.h.

depth_test

bool scimesh::TextLayer::depth_test = true

Whether the label is hidden by geometry in front of its anchor (default: true).

When true, a label whose anchor point is behind the rendered surfaces (e.g. an atom label on the far side of a protein) is skipped, which is what makes labels look like they belong to the scene. Set to false to always draw the labels on top of everything, which is useful for annotating a point that lies on a surface.

Only meaningful for TextSpace::WORLD.

Definition at line 276 of file text.h.

font_file

std::string scimesh::TextLayer::font_file

Path to the .ttf file to use, or an empty string for the bundled default font (see default_font_path()).

This makes the typeface replaceable: point it at any .ttf on the system, or at the bundled font.

Definition at line 228 of file text.h.

halo_color

Color scimesh::TextLayer::halo_color = Color(0.0f, 0.0f, 0.0f, 0.0f)

Color of the halo (outline) drawn behind the glyphs.

Alpha 0 (the default) disables the halo.

Definition at line 281 of file text.h.

halo_width

float scimesh::TextLayer::halo_width = 1.0f

Halo thickness in output pixels (default: 1).

Definition at line 284 of file text.h.

line_spacing

float scimesh::TextLayer::line_spacing = 1.2f

Distance between two lines of a multi-line string, as a multiple of the height of the font's glyph box (default: 1.2).

Definition at line 252 of file text.h.

offset

Vec2 scimesh::TextLayer::offset = Vec2(0.0f, 0.0f)

Extra offset applied after anchoring, in output pixels (positive x = right, positive y = down).

Definition at line 248 of file text.h.

positions

std::vector<Vec3> scimesh::TextLayer::positions

Anchor positions, in world space or in screen pixels.

Interpreted according to space. For TextSpace::SCREEN only x and y are used (z is ignored).

Definition at line 213 of file text.h.

rotation

float scimesh::TextLayer::rotation = 0.0f

Rotation of the label in degrees, counter-clockwise, about the anchor position (default: 0).

The anchor is the position after adj and offset have been applied, so a rotated label keeps that point fixed. The rotation happens in the image plane (in screen space) for world-space labels as well, which is all a billboard can do. Use 90 to write along a vertical axis (the usual orientation of a y-axis label), 180 for an upside-down label, or any other angle to follow an annotation line; glyphs are resampled with bilinear interpolation.

Definition at line 264 of file text.h.

size

float scimesh::TextLayer::size = 16.0f

Text height ("em" size) in output pixels (default: 16).

The renderer scales this internally by the supersampling factor, so the physical size of a label does not change with RenderOptions::aa_samples.

Definition at line 234 of file text.h.

space

TextSpace scimesh::TextLayer::space = TextSpace::WORLD

Coordinate space of positions (default: TextSpace::WORLD).

Definition at line 237 of file text.h.

strings

std::vector<std::string> scimesh::TextLayer::strings

One string per entry in positions (UTF-8; \n for line breaks).

Definition at line 216 of file text.h.

---

The documentation for this struct was generated from the following file:

• src/core/scimesh/text.h