|
OCCT-Light 0.1
C ABI and C++ veneer for multi-language CAD workflows
|
OCCT-Light: core public API. More...
#include <stddef.h>#include <stdint.h>

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 |
Functions | |
| const char * | occtl_status_to_string (occtl_status_t status) |
| const occtl_error_t * | occtl_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) |
OCCT-Light: core public API.
Status codes, thread-local error reporting, runtime lifecycle, version queries. The base every other OCCT-Light module depends on.
| #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.
| #define OCCTL_ANGLE_1_DEG_RAD OCCTL_RAD_PER_DEG |
1 degree in radians.
| #define OCCTL_ANGLE_20_DEG_RAD (20.0 * OCCTL_RAD_PER_DEG) |
20 degrees in radians.
| #define OCCTL_ANGLE_30_DEG_RAD (30.0 * OCCTL_RAD_PER_DEG) |
30 degrees in radians.
| #define OCCTL_ANGLE_5_DEG_RAD (5.0 * OCCTL_RAD_PER_DEG) |
5 degrees in radians.
| #define OCCTL_ANGLE_90_DEG_RAD OCCTL_PI_OVER_TWO |
90 degrees in radians.
| #define OCCTL_API |
Symbol export macro. Applied to every public function declaration.
__declspec(dllexport)__declspec(dllimport)__attribute__((visibility("default"))) | #define OCCTL_FAILED | ( | status | ) | ((status) != OCCTL_OK) |
status indicates failure. | #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.
| #define OCCTL_RAD_PER_DEG (OCCTL_PI / 180.0) |
Radians in one degree.
| #define OCCTL_RUNTIME_INIT_INFO_INIT {OCCTL_RUNTIME_INIT_INFO_VERSION_1, NULL} |
Static initializer for occtl_runtime_init_info_t.
| #define OCCTL_RUNTIME_INIT_INFO_VERSION_1 1u |
Init info versioning constant. New fields are appended under new version constants in future releases.
| #define OCCTL_SUCCEEDED | ( | status | ) | ((status) == OCCTL_OK) |
status indicates success. | #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.
| #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.
| #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 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.
| typedef enum occtl_node_kind 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.
| typedef enum occtl_ref_kind 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.
| 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.
| typedef enum occtl_rep_kind 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.
| typedef struct occtl_runtime_init_info 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.
| typedef enum occtl_status 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.
| 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).
| enum 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.
| enum 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.
| enum 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.
| enum 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 |
| 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. |
| 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).
| 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."
\par Thread Safety Yes (per-thread).
| 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.
\par Thread Safety Yes.
| 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.
| [in] | info | Borrows it. Optional. NULL = use defaults. When non-NULL, info->struct_version must be a recognised value. |
| OCCTL_OK | On success or if defaults already applied. |
| OCCTL_VERSION_MISMATCH | info->struct_version is unsupported. |
| OCCTL_INVALID_ARGUMENT | Already initialised, or an invalid combination. |
\par Thread Safety No (call before any other thread issues OCCT-Light calls).
| 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.
| [out] | info | Owns it (caller-allocated). Must be non-NULL. |
| OCCTL_OK | On success. |
| OCCTL_INVALID_ARGUMENT | info is NULL. |
\par Thread Safety Yes.
| 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.
"7.x.y". Library-owned, valid for the process lifetime.\par Thread Safety Yes.
| 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).
| 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.
| [out] | out_major | Borrows it. Optional. |
| [out] | out_minor | Borrows it. Optional. |
| [out] | out_patch | Borrows it. Optional. |
\par Thread Safety Yes.
| 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.
| [in] | status | A status code. |
status is not a recognised value.\par Thread Safety Yes.
| int32_t occtl_uid_equal | ( | occtl_uid_t | a, |
| occtl_uid_t | b | ||
| ) |
Tests two UIDs for equality.
| [in] | a | First UID. |
| [in] | b | Second UID. |
| 1 | UIDs are equal. |
| 0 | UIDs differ. |
\par Thread Safety Yes.
| 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.
| [in] | in_bytes | Borrows it. Must point to a readable buffer of at least OCCTL_UID_WIRE_SIZE bytes. |
| [out] | out_uid | Borrows it. Must be non-NULL. |
| OCCTL_OK | On success. |
| OCCTL_INVALID_ARGUMENT | in_bytes or out_uid is NULL. |
| OCCTL_FORMAT_ERROR | Reserved bytes are non-zero. |
\par Thread Safety Yes.
| 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.
| [in] | uid | UID to encode (may be OCCTL_UID_INVALID). |
| [out] | out_bytes | Borrows it. Must point to a writable buffer of at least OCCTL_UID_WIRE_SIZE bytes. |
| OCCTL_OK | On success. |
| OCCTL_INVALID_ARGUMENT | out_bytes is NULL. |
\par Thread Safety Yes.