occtl_text.h File Reference

OCCT-Light: text-to-shape module public API. More...

#include <stddef.h>
#include <stdint.h>
#include "occtl_core.h"
#include "occtl_geom.h"
#include "occtl_topo.h"

Include dependency graph for occtl_text.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	occtl_text_info
struct	occtl_text_layout_options
struct	occtl_text_metrics

Macros
#define	OCCTL_TEXT_INFO_VERSION_1   1u
#define	OCCTL_TEXT_LAYOUT_OPTIONS_VERSION_1   1u
#define	OCCTL_TEXT_METRICS_VERSION_1   1u
#define	OCCTL_TEXT_INFO_INIT
#define	OCCTL_TEXT_LAYOUT_OPTIONS_INIT   {OCCTL_TEXT_LAYOUT_OPTIONS_VERSION_1, NULL, 0.0, 1}
#define	OCCTL_TEXT_METRICS_INIT    {OCCTL_TEXT_METRICS_VERSION_1, NULL, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0}

Typedefs
typedef enum occtl_text_font_aspect	occtl_text_font_aspect_t
typedef enum occtl_text_halign	occtl_text_halign_t
typedef enum occtl_text_valign	occtl_text_valign_t
typedef struct occtl_text_info	occtl_text_info_t
typedef struct occtl_text_layout_options	occtl_text_layout_options_t
typedef struct occtl_text_metrics	occtl_text_metrics_t

Enumerations
enum	occtl_text_font_aspect {   OCCTL_TEXT_FONT_ASPECT_REGULAR = 0 , OCCTL_TEXT_FONT_ASPECT_BOLD = 1 , OCCTL_TEXT_FONT_ASPECT_ITALIC = 2 , OCCTL_TEXT_FONT_ASPECT_BOLD_ITALIC = 3 ,   OCCTL_TEXT_FONT_ASPECT_RESERVED_FUTURE = 0x7fffffff }
enum	occtl_text_halign { OCCTL_TEXT_HALIGN_LEFT = 0 , OCCTL_TEXT_HALIGN_CENTER = 1 , OCCTL_TEXT_HALIGN_RIGHT = 2 , OCCTL_TEXT_HALIGN_RESERVED_FUTURE = 0x7fffffff }
enum	occtl_text_valign {   OCCTL_TEXT_VALIGN_BOTTOM = 0 , OCCTL_TEXT_VALIGN_BASELINE = 1 , OCCTL_TEXT_VALIGN_CENTER = 2 , OCCTL_TEXT_VALIGN_TOP = 3 ,   OCCTL_TEXT_VALIGN_RESERVED_FUTURE = 0x7fffffff }

Functions
void	occtl_text_info_init (occtl_text_info_t *info)
void	occtl_text_layout_options_init (occtl_text_layout_options_t *options)
void	occtl_text_metrics_init (occtl_text_metrics_t *metrics)
occtl_status_t	occtl_text_measure (const occtl_text_info_t *info, occtl_text_metrics_t *out_metrics)
occtl_status_t	occtl_text_make_faces (occtl_graph_t *graph, const occtl_text_info_t *info, occtl_node_id_t *out_compound)
occtl_status_t	occtl_text_make_wires (occtl_graph_t *graph, const occtl_text_info_t *info, occtl_node_id_t *out_compound)

Detailed Description

OCCT-Light: text-to-shape module public API.

Measures formatted UTF-8 text, or converts it into a Compound of planar faces (filled glyphs) / wires (glyph outlines) and inserts the topology into a graph as a single root node. The topology result is suitable for use as a profile in subsequent operations: feed it to occtl_prim_make_prism to obtain an extruded solid, engraved label, or outline-only curve set.

Fonts are resolved either by family name (the host's font registry is scanned at first use) or by explicit absolute path to a .ttf/.otf file. When a glyph cannot be rendered by the chosen font, a fallback font is substituted silently; the operation still succeeds.

Macro Definition Documentation

OCCTL_TEXT_INFO_INIT

#define OCCTL_TEXT_INFO_INIT

Value:

  {OCCTL_TEXT_INFO_VERSION_1,                                                                      \
   NULL,                                                                                           \
   {{0.0, 0.0, 0.0}, {0.0, 0.0, 1.0}, {1.0, 0.0, 0.0}},                                            \
   NULL,                                                                                           \
   NULL,                                                                                           \
   NULL,                                                                                           \
   OCCTL_TEXT_FONT_ASPECT_REGULAR,                                                                 \
   0.0,                                                                                            \
   OCCTL_TEXT_HALIGN_LEFT,                                                                         \
   OCCTL_TEXT_VALIGN_BASELINE}

Typedef Documentation

occtl_text_font_aspect_t

typedef enum occtl_text_font_aspect occtl_text_font_aspect_t

Font style aspect.

occtl_text_halign_t

typedef enum occtl_text_halign occtl_text_halign_t

Horizontal alignment of multi-line text relative to placement.location.

occtl_text_info_t

typedef struct occtl_text_info occtl_text_info_t

Info for occtl_text_measure, occtl_text_make_faces, and occtl_text_make_wires.

Lays out utf8_text on the XY plane of placement (Z up, X along the writing direction) at the given glyph height. Lines are separated by newline characters and aligned according to horizontal_align / vertical_align. Exactly one of font_family / font_path must be non-NULL; font_path wins when both are set.

occtl_text_layout_options_t

typedef struct occtl_text_layout_options occtl_text_layout_options_t

Optional layout extension for occtl_text_info_t::p_next.

Enables OCCT text wrapping while preserving the v1 text-info ABI. When present, pass a pointer to this struct in occtl_text_info_t::p_next.

occtl_text_metrics_t

typedef struct occtl_text_metrics occtl_text_metrics_t

Formatted text metrics returned by occtl_text_measure.

Initialise with OCCTL_TEXT_METRICS_INIT or occtl_text_metrics_init before passing to occtl_text_measure. The caller-owned version field lets future OCCT-Light releases append fields without changing the ABI contract.

occtl_text_valign_t

typedef enum occtl_text_valign occtl_text_valign_t

Vertical alignment of the text block relative to placement.location.

Enumeration Type Documentation

occtl_text_font_aspect

enum occtl_text_font_aspect

Font style aspect.

Enumerator
OCCTL_TEXT_FONT_ASPECT_REGULAR	Default.

occtl_text_halign

enum occtl_text_halign

Horizontal alignment of multi-line text relative to placement.location.

Enumerator
OCCTL_TEXT_HALIGN_LEFT	Default. Pen-x = placement.location.x.

occtl_text_valign

enum occtl_text_valign

Vertical alignment of the text block relative to placement.location.

Enumerator
OCCTL_TEXT_VALIGN_BASELINE	Default. Baseline of the first line.

Function Documentation

occtl_text_info_init()

void occtl_text_info_init

(

occtl_text_info_t *

info

)

Runtime initialiser for occtl_text_info_t.

Sets all fields to OCCTL_TEXT_INFO_INIT.

Parameters

[out]

info

Borrows it. NULL-tolerant; no-op when NULL.

\par Thread Safety Yes.

See also

occtl_text_make_faces

occtl_text_make_wires

occtl_text_measure

occtl_text_layout_options_init()

void occtl_text_layout_options_init

(

occtl_text_layout_options_t *

options

)

Runtime initialiser for occtl_text_layout_options_t.

Sets all fields to OCCTL_TEXT_LAYOUT_OPTIONS_INIT.

Parameters

[out]

options

Borrows it. NULL-tolerant; no-op when NULL.

\par Thread Safety Yes.

See also

occtl_text_measure

occtl_text_make_faces

occtl_text_make_wires

occtl_text_make_faces()

occtl_status_t occtl_text_make_faces	(	occtl_graph_t *	graph,
		const occtl_text_info_t *	info,
		occtl_node_id_t *	out_compound
	)

Produces a Compound of planar faces from a string and inserts it into graph as a single root node.

Multi-line input (newline-separated) is laid out with the alignment specified in info. When font_family does not match any installed font, or when individual glyphs are unsupported by the chosen face, the host's default fallback font is substituted without failing the call (a warning may be emitted to stderr by the font manager). Use font_path when you need a hard guarantee that a specific file is used; a missing file is reported as OCCTL_GEOMETRY_INVALID.

Combine the result with occtl_prim_make_prism to extrude the text into a solid.

Parameters

[in,out]	graph	Borrows it. Must be non-NULL.
[in]	info	Borrows it. Must be non-NULL with a recognised struct_version, non-empty utf8_text, strictly positive height, and at least one of font_family / font_path set.
[out]	out_compound	Borrows it (caller-allocated slot). Must be non-NULL. On success receives the new Compound NodeId; on failure set to OCCTL_NODE_ID_INVALID.

Return values

OCCTL_OK	On success.
OCCTL_INVALID_ARGUMENT	Any pointer argument is NULL, utf8_text is empty, height is non-positive, both font selectors are NULL, layout options are invalid, or an alignment enum is out of range.
OCCTL_VERSION_MISMATCH	struct_version is unrecognised.
OCCTL_GEOMETRY_INVALID	Font could not be loaded, or the layout produced no usable geometry.
OCCTL_INTERNAL	An unexpected internal error occurred.

\par Thread Safety No. Mutates graph.

See also

occtl_text_make_wires

occtl_prim_make_prism

occtl_text_make_wires()

occtl_status_t occtl_text_make_wires	(	occtl_graph_t *	graph,
		const occtl_text_info_t *	info,
		occtl_node_id_t *	out_compound
	)

Produces a Compound of glyph outline wires from a string and inserts it into graph as a single root node.

Layout, font selection, fallback behaviour, and placement match occtl_text_make_faces. The returned Compound contains the generated glyph wires without filling them into Faces, which is useful for laser/CNC paths, engraving curves, and custom downstream profile processing.

Parameters

[in,out]	graph	Borrows it. Must be non-NULL.
[in]	info	Borrows it. Must be non-NULL with a recognised struct_version, non-empty utf8_text, strictly positive height, and at least one of font_family / font_path set.
[out]	out_compound	Borrows it (caller-allocated slot). Must be non-NULL. On success receives the new Compound NodeId; on failure set to OCCTL_NODE_ID_INVALID.

Return values

OCCTL_OK	On success.
OCCTL_INVALID_ARGUMENT	Any pointer argument is NULL, utf8_text is empty, height is non-positive, both font selectors are NULL, layout options are invalid, or an alignment enum is out of range.
OCCTL_VERSION_MISMATCH	struct_version is unrecognised.
OCCTL_GEOMETRY_INVALID	Font could not be loaded, or the layout produced no usable outline wires.
OCCTL_INTERNAL	An unexpected internal error occurred.

\par Thread Safety No. Mutates graph.

See also

occtl_text_make_faces

occtl_prim_make_prism

occtl_text_measure()

occtl_status_t occtl_text_measure	(	const occtl_text_info_t *	info,
		occtl_text_metrics_t *	out_metrics
	)

Measures formatted text without inserting topology into a graph.

Layout, font selection, fallback behaviour, and alignment match occtl_text_make_faces. Metrics are reported in the local XY text coordinate system before info->placement is applied to generated topology. Use this to size labels, drawing annotations, engraving pockets, or downstream layout before creating faces or wires.

Parameters

[in]	info	Borrows it. Must be non-NULL with a recognised struct_version, non-empty utf8_text, strictly positive height, and at least one of font_family / font_path set.
[out]	out_metrics	Borrows it. Must be non-NULL, initialised with a recognised struct_version, and receives the measured values on success.

Return values

OCCTL_OK	On success.
OCCTL_INVALID_ARGUMENT	info or out_metrics is NULL, utf8_text is empty, height is non-positive, both font selectors are NULL, out_metrics->p_next is non-NULL, layout options are invalid, or an alignment enum is out of range.
OCCTL_VERSION_MISMATCH	An input or output struct_version is unrecognised.
OCCTL_GEOMETRY_INVALID	Font could not be loaded.
OCCTL_INTERNAL	An unexpected internal error occurred.

\par Thread Safety Yes.

See also

occtl_text_make_faces

occtl_text_make_wires

occtl_text_metrics_init()

void occtl_text_metrics_init

(

occtl_text_metrics_t *

metrics

)

Runtime initialiser for occtl_text_metrics_t.

Sets all fields to OCCTL_TEXT_METRICS_INIT.

Parameters

[out]

metrics

Borrows it. NULL-tolerant; no-op when NULL.

\par Thread Safety Yes.

See also

occtl_text_measure