OCCT-Light 0.1
C ABI and C++ veneer for multi-language CAD workflows
Loading...
Searching...
No Matches
occtl_core.h File Reference

OCCT-Light: core public API. More...

#include <stddef.h>
#include <stdint.h>
Include dependency graph for occtl_core.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

struct  occtl_rep_id
 
struct  occtl_uid
 
struct  occtl_error
 
struct  occtl_runtime_init_info
 

Macros

#define OCCTL_PI   3.14159265358979323846
 
#define OCCTL_TWO_PI   (2.0 * OCCTL_PI)
 
#define OCCTL_PI_OVER_TWO   (0.5 * OCCTL_PI)
 
#define OCCTL_RAD_PER_DEG   (OCCTL_PI / 180.0)
 
#define OCCTL_ANGLE_1_DEG_RAD   OCCTL_RAD_PER_DEG
 
#define OCCTL_ANGLE_5_DEG_RAD   (5.0 * OCCTL_RAD_PER_DEG)
 
#define OCCTL_ANGLE_20_DEG_RAD   (20.0 * OCCTL_RAD_PER_DEG)
 
#define OCCTL_ANGLE_30_DEG_RAD   (30.0 * OCCTL_RAD_PER_DEG)
 
#define OCCTL_ANGLE_90_DEG_RAD   OCCTL_PI_OVER_TWO
 
#define OCCTL_VERSION_MAJOR   0
 
#define OCCTL_VERSION_MINOR   0
 
#define OCCTL_VERSION_PATCH   0
 
#define OCCTL_ABI_VERSION   1
 
#define OCCTL_API
 
#define OCCTL_CALL
 
#define OCCTL_FAILED(status)   ((status) != OCCTL_OK)
 
#define OCCTL_SUCCEEDED(status)   ((status) == OCCTL_OK)
 
#define OCCTL_REP_ID_INVALID   ((occtl_rep_id_t){0})
 
#define OCCTL_UID_INVALID   ((occtl_uid_t){0})
 
#define OCCTL_RUNTIME_INIT_INFO_VERSION_1   1u
 
#define OCCTL_RUNTIME_INIT_INFO_INIT   {OCCTL_RUNTIME_INIT_INFO_VERSION_1, NULL}
 
#define OCCTL_UID_WIRE_SIZE   16u
 

Typedefs

typedef enum occtl_status occtl_status_t
 
typedef enum occtl_node_kind occtl_node_kind_t
 
typedef enum occtl_ref_kind occtl_ref_kind_t
 
typedef enum occtl_rep_kind occtl_rep_kind_t
 
typedef struct occtl_rep_id occtl_rep_id_t
 
typedef struct occtl_uid occtl_uid_t
 
typedef struct occtl_error occtl_error_t
 
typedef struct occtl_runtime_init_info occtl_runtime_init_info_t
 

Enumerations

enum  occtl_status {
  OCCTL_OK = 0 , OCCTL_ERROR = 1 , OCCTL_INVALID_ARGUMENT = 2 , OCCTL_INVALID_HANDLE = 3 ,
  OCCTL_NOT_FOUND = 4 , OCCTL_OUT_OF_MEMORY = 5 , OCCTL_OUT_OF_RANGE = 6 , OCCTL_NOT_DONE = 7 ,
  OCCTL_GEOMETRY_INVALID = 8 , OCCTL_TOPOLOGY_INVALID = 9 , OCCTL_IO_ERROR = 10 , OCCTL_FORMAT_ERROR = 11 ,
  OCCTL_UNSUPPORTED = 12 , OCCTL_CANCELLED = 13 , OCCTL_BUFFER_TOO_SMALL = 14 , OCCTL_VERSION_MISMATCH = 15 ,
  OCCTL_INTERNAL = 16 , OCCTL_WRONG_KIND = 17 , OCCTL_STATUS_RESERVED_FUTURE = 0x7fffffff
}
 
enum  occtl_node_kind {
  OCCTL_KIND_INVALID = 0 , OCCTL_KIND_SOLID = 1 , OCCTL_KIND_SHELL = 2 , OCCTL_KIND_FACE = 3 ,
  OCCTL_KIND_WIRE = 4 , OCCTL_KIND_EDGE = 5 , OCCTL_KIND_VERTEX = 6 , OCCTL_KIND_COMPOUND = 7 ,
  OCCTL_KIND_COMPSOLID = 8 , OCCTL_KIND_COEDGE = 9 , OCCTL_KIND_PRODUCT = 10 , OCCTL_KIND_OCCURRENCE = 11 ,
  OCCTL_NODE_KIND_RESERVED_FUTURE = 0x7fffffff
}
 
enum  occtl_ref_kind {
  OCCTL_REF_KIND_INVALID = 0 , OCCTL_REF_KIND_SHELL = 1 , OCCTL_REF_KIND_FACE = 2 , OCCTL_REF_KIND_WIRE = 3 ,
  OCCTL_REF_KIND_COEDGE = 4 , OCCTL_REF_KIND_VERTEX = 5 , OCCTL_REF_KIND_SOLID = 6 , OCCTL_REF_KIND_CHILD = 7 ,
  OCCTL_REF_KIND_OCCURRENCE = 8 , OCCTL_REF_KIND_RESERVED_FUTURE = 0x7fffffff
}
 
enum  occtl_rep_kind {
  OCCTL_REP_KIND_INVALID = 0 , OCCTL_REP_KIND_SURFACE = 1 , OCCTL_REP_KIND_CURVE3D = 2 , OCCTL_REP_KIND_CURVE2D = 3 ,
  OCCTL_REP_KIND_TRIANGULATION = 4 , OCCTL_REP_KIND_POLYGON3D = 5 , OCCTL_REP_KIND_POLYGON2D = 6 , OCCTL_REP_KIND_POLYGON_ON_TRI = 7 ,
  OCCTL_REP_KIND_RESERVED_FUTURE = 0x7fffffff
}
 

Functions

const char * occtl_status_to_string (occtl_status_t status)
 
const occtl_error_tocctl_error_last (void)
 
void occtl_error_clear (void)
 
occtl_status_t occtl_runtime_init (const occtl_runtime_init_info_t *info)
 
occtl_status_t occtl_runtime_init_info_init (occtl_runtime_init_info_t *info)
 
void occtl_runtime_shutdown (void)
 
void occtl_runtime_version (uint32_t *out_major, uint32_t *out_minor, uint32_t *out_patch)
 
uint32_t occtl_runtime_abi_version (void)
 
const char * occtl_runtime_occt_version (void)
 
occtl_status_t occtl_uid_to_bytes (occtl_uid_t uid, uint8_t *out_bytes)
 
occtl_status_t occtl_uid_from_bytes (const uint8_t *in_bytes, occtl_uid_t *out_uid)
 
int32_t occtl_uid_equal (occtl_uid_t a, occtl_uid_t b)
 

Detailed Description

OCCT-Light: core public API.

Status codes, thread-local error reporting, runtime lifecycle, version queries. The base every other OCCT-Light module depends on.

See also
../../docs/design/ABI_PATTERNS.md for ABI conventions.
../../docs/design/ARCHITECTURE.md for the layered design.

Macro Definition Documentation

◆ OCCTL_ABI_VERSION

#define OCCTL_ABI_VERSION   1

ABI version. Bumped only on hard breakage. Independent of SemVer.

Consumers may compare this against occtl_runtime_abi_version at load time and refuse to proceed on mismatch.

◆ OCCTL_ANGLE_1_DEG_RAD

#define OCCTL_ANGLE_1_DEG_RAD   OCCTL_RAD_PER_DEG

1 degree in radians.

◆ OCCTL_ANGLE_20_DEG_RAD

#define OCCTL_ANGLE_20_DEG_RAD   (20.0 * OCCTL_RAD_PER_DEG)

20 degrees in radians.

◆ OCCTL_ANGLE_30_DEG_RAD

#define OCCTL_ANGLE_30_DEG_RAD   (30.0 * OCCTL_RAD_PER_DEG)

30 degrees in radians.

◆ OCCTL_ANGLE_5_DEG_RAD

#define OCCTL_ANGLE_5_DEG_RAD   (5.0 * OCCTL_RAD_PER_DEG)

5 degrees in radians.

◆ OCCTL_ANGLE_90_DEG_RAD

#define OCCTL_ANGLE_90_DEG_RAD   OCCTL_PI_OVER_TWO

90 degrees in radians.

◆ OCCTL_API

#define OCCTL_API

Symbol export macro. Applied to every public function declaration.

  • Building shared on Windows : __declspec(dllexport)
  • Consuming shared on Windows : __declspec(dllimport)
  • Building or consuming static: empty
  • All non-Windows platforms : __attribute__((visibility("default")))

◆ OCCTL_FAILED

#define OCCTL_FAILED (   status)    ((status) != OCCTL_OK)
Returns
non-zero if status indicates failure.

◆ OCCTL_PI

#define OCCTL_PI   3.14159265358979323846

Mathematical constants shared across public C headers.

These macros are used by options INIT defaults so callers and bindings can refer to one named source of truth instead of repeating magic literals.

◆ OCCTL_PI_OVER_TWO

#define OCCTL_PI_OVER_TWO   (0.5 * OCCTL_PI)

OCCTL_PI / 2.

◆ OCCTL_RAD_PER_DEG

#define OCCTL_RAD_PER_DEG   (OCCTL_PI / 180.0)

Radians in one degree.

◆ OCCTL_RUNTIME_INIT_INFO_INIT

#define OCCTL_RUNTIME_INIT_INFO_INIT   {OCCTL_RUNTIME_INIT_INFO_VERSION_1, NULL}

Static initializer for occtl_runtime_init_info_t.

◆ OCCTL_RUNTIME_INIT_INFO_VERSION_1

#define OCCTL_RUNTIME_INIT_INFO_VERSION_1   1u

Init info versioning constant. New fields are appended under new version constants in future releases.

◆ OCCTL_SUCCEEDED

#define OCCTL_SUCCEEDED (   status)    ((status) == OCCTL_OK)
Returns
non-zero if status indicates success.

◆ OCCTL_TWO_PI

#define OCCTL_TWO_PI   (2.0 * OCCTL_PI)

2 * OCCTL_PI.

◆ OCCTL_UID_INVALID

#define OCCTL_UID_INVALID   ((occtl_uid_t){0})

Invalid UID sentinel. Equivalent to (occtl_uid_t){0}.

Defined as a C99 compound literal in C and as a C++ braced initialiser in C++; this avoids compound-literal warnings on MSVC and pedantic C++ modes.

◆ OCCTL_UID_WIRE_SIZE

#define OCCTL_UID_WIRE_SIZE   16u

Number of bytes in the wire-format encoding of an occtl_uid_t.

The wire format is a fixed-width opaque blob; do not parse it. The top 8 bytes carry the current 64-bit packed identity in big-endian order; the bottom 8 bytes are reserved (always zero today) so that future widening of the kind tag or counter field can re-key existing stored UIDs without breaking persistence.

◆ OCCTL_VERSION_MAJOR

#define OCCTL_VERSION_MAJOR   0

Library SemVer. Refer at compile time; for runtime checks use occtl_runtime_version.

These are defined by the build system. Defaults are zero-or-fallback if a non-CMake build forgets to set them.

Typedef Documentation

◆ occtl_error_t

typedef struct occtl_error occtl_error_t

Thread-local description of the most recent failure.

Populated automatically when any public function returns a non-OK status. Read it with occtl_error_last; clear it with occtl_error_clear.

The message pointer is library-owned and is only valid until the next OCCT-Light call on this thread. Copy it out if you need to retain it.

◆ occtl_node_kind_t

Node kind discriminator.

Applies to occtl_node_id_t, occtl_uid_t, and occtl_ref_id_t payloads. Values are stable forever; new kinds are appended before OCCTL_NODE_KIND_RESERVED_FUTURE. OCCTL_KIND_INVALID = 0 is the zero sentinel so calloc / memset-zero IDs are naturally invalid.

◆ occtl_ref_kind_t

Reference-entry kind discriminator for occtl_ref_id_t.

Reference entries express usages of a node (e.g. a Face used inside a Shell). Zero is reserved as the universal invalid sentinel.

◆ occtl_rep_id_t

typedef struct occtl_rep_id occtl_rep_id_t

Identity of a representation (geometry / mesh data) in the graph.

The all-zero value (OCCTL_REP_ID_INVALID) is the invalid sentinel.

◆ occtl_rep_kind_t

Representation kind discriminator for occtl_rep_id_t.

Representations are the data attached to a node — geometry (Surface, Curve3D, Curve2D) or mesh (Triangulation, Polygon3D, Polygon2D, PolygonOnTri). Unrecognised representation kinds are surfaced as OCCTL_REP_KIND_INVALID by the current ABI.

◆ occtl_runtime_init_info_t

Options for occtl_runtime_init.

Construct with OCCTL_RUNTIME_INIT_INFO_INIT or by zero-initialising and setting struct_version explicitly.

◆ occtl_status_t

Status code returned by every OCCT-Light public function.

OCCTL_OK is 0; idiomatic checks if (occtl_xxx(...) != OCCTL_OK) and if (s) goto fail; both work.

The numeric values listed here are stable forever; new values may be appended in future versions. Consumers that switch on the code must default unknown values to a generic-failure code path.

◆ occtl_uid_t

typedef struct occtl_uid occtl_uid_t

Persistent unique identity of a graph entity.

Survives compact and most node removals, unlike occtl_node_id_t which is session-local. The all-zero value (OCCTL_UID_INVALID) is the invalid sentinel — compare with uid.bits == 0.

To query the kind of a UID, call occtl_graph_uid_kind() (declared in occtl_topo.h when OCCTL_HAS_TOPO is defined).

Enumeration Type Documentation

◆ occtl_node_kind

Node kind discriminator.

Applies to occtl_node_id_t, occtl_uid_t, and occtl_ref_id_t payloads. Values are stable forever; new kinds are appended before OCCTL_NODE_KIND_RESERVED_FUTURE. OCCTL_KIND_INVALID = 0 is the zero sentinel so calloc / memset-zero IDs are naturally invalid.

Enumerator
OCCTL_KIND_INVALID 

Invalid / zero sentinel.

OCCTL_KIND_SOLID 

Solid.

OCCTL_KIND_SHELL 

Shell.

OCCTL_KIND_FACE 

Face.

OCCTL_KIND_WIRE 

Wire.

OCCTL_KIND_EDGE 

Edge.

OCCTL_KIND_VERTEX 

Vertex.

OCCTL_KIND_COMPOUND 

Compound.

OCCTL_KIND_COMPSOLID 

CompSolid.

OCCTL_KIND_COEDGE 

CoEdge (half-edge).

OCCTL_KIND_PRODUCT 

Product (assembly root).

OCCTL_KIND_OCCURRENCE 

Occurrence (assembly instance).

◆ occtl_ref_kind

Reference-entry kind discriminator for occtl_ref_id_t.

Reference entries express usages of a node (e.g. a Face used inside a Shell). Zero is reserved as the universal invalid sentinel.

Enumerator
OCCTL_REF_KIND_INVALID 

Invalid / zero sentinel.

OCCTL_REF_KIND_SHELL 

Usage of a Shell definition.

OCCTL_REF_KIND_FACE 

Usage of a Face definition.

OCCTL_REF_KIND_WIRE 

Usage of a Wire definition.

OCCTL_REF_KIND_COEDGE 

Usage of a CoEdge definition.

OCCTL_REF_KIND_VERTEX 

Usage of a Vertex definition.

OCCTL_REF_KIND_SOLID 

Usage of a Solid definition.

OCCTL_REF_KIND_CHILD 

Generic mixed-kind child reference.

OCCTL_REF_KIND_OCCURRENCE 

Usage of an Occurrence.

◆ occtl_rep_kind

Representation kind discriminator for occtl_rep_id_t.

Representations are the data attached to a node — geometry (Surface, Curve3D, Curve2D) or mesh (Triangulation, Polygon3D, Polygon2D, PolygonOnTri). Unrecognised representation kinds are surfaced as OCCTL_REP_KIND_INVALID by the current ABI.

Enumerator
OCCTL_REP_KIND_INVALID 

Invalid / zero sentinel.

OCCTL_REP_KIND_SURFACE 

3D surface geometry.

OCCTL_REP_KIND_CURVE3D 

3D curve geometry.

OCCTL_REP_KIND_CURVE2D 

2D parametric curve on a face (PCurve).

OCCTL_REP_KIND_TRIANGULATION 

Surface triangulation.

OCCTL_REP_KIND_POLYGON3D 

3D polyline along an edge.

OCCTL_REP_KIND_POLYGON2D 

2D polyline.

OCCTL_REP_KIND_POLYGON_ON_TRI 

Polyline indexed onto a triangulation.

◆ occtl_status

Status code returned by every OCCT-Light public function.

OCCTL_OK is 0; idiomatic checks if (occtl_xxx(...) != OCCTL_OK) and if (s) goto fail; both work.

The numeric values listed here are stable forever; new values may be appended in future versions. Consumers that switch on the code must default unknown values to a generic-failure code path.

Enumerator
OCCTL_OK 

Success.

OCCTL_ERROR 

Generic failure; see occtl_error_last.

OCCTL_INVALID_ARGUMENT 

A required pointer was NULL or an argument was malformed.

OCCTL_INVALID_HANDLE 

A handle was NULL or had been freed.

OCCTL_NOT_FOUND 

Requested entity does not exist.

OCCTL_OUT_OF_MEMORY 

Allocation failed.

OCCTL_OUT_OF_RANGE 

A numeric argument was outside the valid range.

OCCTL_NOT_DONE 

An OCCT operation reported IsDone()==false.

OCCTL_GEOMETRY_INVALID 

Input geometry was not well-formed.

OCCTL_TOPOLOGY_INVALID 

Input topology was not well-formed.

OCCTL_IO_ERROR 

Filesystem or I/O failure.

OCCTL_FORMAT_ERROR 

File contents were malformed.

OCCTL_UNSUPPORTED 

Operation not supported in this build/configuration.

OCCTL_CANCELLED 

A cooperative cancellation was honoured.

OCCTL_BUFFER_TOO_SMALL 

Two-call pattern: caller buffer was too small.

OCCTL_VERSION_MISMATCH 

Options struct_version is not supported.

OCCTL_INTERNAL 

C++ exception caught at the ABI boundary.

OCCTL_WRONG_KIND 

Handle holds a different kind than the extractor expects.

OCCTL_STATUS_RESERVED_FUTURE 

Reserved sentinel forces the storage to int32_t and reserves space for new values.

Function Documentation

◆ occtl_error_clear()

void occtl_error_clear ( void  )

Clears the thread-local last error.

Calling this is optional — every public function that returns OCCTL_OK already clears the slot. Use it explicitly when you want to assert "no prior failure" before a sequence of calls.

\par Thread Safety Yes (per-thread).

See also
occtl_error_last

◆ occtl_error_last()

const occtl_error_t * occtl_error_last ( void  )

Returns the thread-local last error.

Always returns a non-NULL pointer; an all-zero status field means "no error pending on this thread."

Returns
Borrowed pointer to thread-local storage. Valid until the next OCCT-Light call on this thread.

\par Thread Safety Yes (per-thread).

See also
occtl_error_clear, occtl_status_to_string

◆ occtl_runtime_abi_version()

uint32_t occtl_runtime_abi_version ( void  )

Returns the runtime ABI version.

Compare to OCCTL_ABI_VERSION at load time and refuse to load if they differ — that protects against mixing a newer header with an older binary.

Returns
The ABI version compiled into this build.

\par Thread Safety Yes.

See also
occtl_runtime_version

◆ occtl_runtime_init()

occtl_status_t occtl_runtime_init ( const occtl_runtime_init_info_t info)

Initialises the OCCT-Light runtime.

Calling this is optional: every entry point lazy-initialises with defaults if needed.

Calling more than once is a programming error; subsequent calls return OCCTL_INVALID_ARGUMENT and have no effect.

Parameters
[in]infoBorrows it. Optional. NULL = use defaults. When non-NULL, info->struct_version must be a recognised value.
Return values
OCCTL_OKOn success or if defaults already applied.
OCCTL_VERSION_MISMATCHinfo->struct_version is unsupported.
OCCTL_INVALID_ARGUMENTAlready initialised, or an invalid combination.

\par Thread Safety No (call before any other thread issues OCCT-Light calls).

See also
occtl_runtime_shutdown, occtl_runtime_version

◆ occtl_runtime_init_info_init()

occtl_status_t occtl_runtime_init_info_init ( occtl_runtime_init_info_t info)

Initialises an occtl_runtime_init_info_t to the default values.

Equivalent to #OCCTL_RUNTIME_INIT_INFO_INIT but callable from binding languages that cannot use C macros.

Parameters
[out]infoOwns it (caller-allocated). Must be non-NULL.
Return values
OCCTL_OKOn success.
OCCTL_INVALID_ARGUMENTinfo is NULL.

\par Thread Safety Yes.

See also
occtl_runtime_init

◆ occtl_runtime_occt_version()

const char * occtl_runtime_occt_version ( void  )

Returns the OCCT version OCCT-Light was built against.

Diagnostic only; not part of OCCT-Light's ABI promise.

Returns
Borrowed pointer to a NUL-terminated UTF-8 string of the form "7.x.y". Library-owned, valid for the process lifetime.

\par Thread Safety Yes.

See also
occtl_runtime_version

◆ occtl_runtime_shutdown()

void occtl_runtime_shutdown ( void  )

Releases process-wide runtime state allocated by occtl_runtime_init.

After this returns, OCCT-Light entry points may still be called — they will lazy-initialise again with defaults. Call this only at process teardown when you want a clean state.

\par Thread Safety No (no other thread may issue OCCT-Light calls during shutdown).

See also
occtl_runtime_init

◆ occtl_runtime_version()

void occtl_runtime_version ( uint32_t *  out_major,
uint32_t *  out_minor,
uint32_t *  out_patch 
)

Returns the runtime SemVer.

Out parameters may individually be NULL if the caller doesn't want a particular field; pass NULL for all three to get a no-op call.

Parameters
[out]out_majorBorrows it. Optional.
[out]out_minorBorrows it. Optional.
[out]out_patchBorrows it. Optional.

\par Thread Safety Yes.

See also
OCCTL_VERSION_MAJOR, occtl_runtime_abi_version

◆ occtl_status_to_string()

const char * occtl_status_to_string ( occtl_status_t  status)

Returns a human-readable name for a status code.

Useful for logging. The string is library-owned and valid for the lifetime of the process; do not free it.

Parameters
[in]statusA status code.
Returns
Borrowed pointer to a NUL-terminated UTF-8 string. Returns "OCCTL_UNKNOWN" if status is not a recognised value.

\par Thread Safety Yes.

See also
occtl_error_last

◆ occtl_uid_equal()

int32_t occtl_uid_equal ( occtl_uid_t  a,
occtl_uid_t  b 
)

Tests two UIDs for equality.

Parameters
[in]aFirst UID.
[in]bSecond UID.
Return values
1UIDs are equal.
0UIDs differ.

\par Thread Safety Yes.

See also
occtl_uid_to_bytes, occtl_uid_from_bytes

◆ occtl_uid_from_bytes()

occtl_status_t occtl_uid_from_bytes ( const uint8_t *  in_bytes,
occtl_uid_t out_uid 
)

Decodes a 16-byte wire-format UID back into an occtl_uid_t.

Rejects payloads whose reserved bytes are non-zero (returns OCCTL_FORMAT_ERROR) — those signal a future wider encoding that this build does not understand. An all-zero input returns OCCTL_UID_INVALID with OCCTL_OK.

Parameters
[in]in_bytesBorrows it. Must point to a readable buffer of at least OCCTL_UID_WIRE_SIZE bytes.
[out]out_uidBorrows it. Must be non-NULL.
Return values
OCCTL_OKOn success.
OCCTL_INVALID_ARGUMENTin_bytes or out_uid is NULL.
OCCTL_FORMAT_ERRORReserved bytes are non-zero.

\par Thread Safety Yes.

See also
occtl_uid_to_bytes

◆ occtl_uid_to_bytes()

occtl_status_t occtl_uid_to_bytes ( occtl_uid_t  uid,
uint8_t *  out_bytes 
)

Encodes a UID into its 16-byte wire format.

Round-trips losslessly through occtl_uid_from_bytes for any valid or invalid UID. Byte order is fixed at big-endian and stable across future ABI versions.

Parameters
[in]uidUID to encode (may be OCCTL_UID_INVALID).
[out]out_bytesBorrows it. Must point to a writable buffer of at least OCCTL_UID_WIRE_SIZE bytes.
Return values
OCCTL_OKOn success.
OCCTL_INVALID_ARGUMENTout_bytes is NULL.

\par Thread Safety Yes.

See also
occtl_uid_from_bytes