CORE C ABI vs GX-TXT public workflow APIs
The Native 3D engine is protected CORE infrastructure. A module should choose the highest public abstraction that matches its job instead of binding directly to renderer internals.
| Layer | Primary responsibility | When to use |
|---|---|---|
| Native 3D CORE C ABI | Geometry/CAD/scientific scene model, renderer, picking/manipulation, field/animation primitives | Native viewer/provider code, CORE-native services, bounded scientific/geometry operations that require these primitives. |
| Viewer Provider API | Session-owned viewer documents/layers and persistence | Normal GX-TXT Viewer integration; persist scene definitions, source identity and presentation. |
| Plot Dataset API v3 / Plot Dataset 3D API v1 | Turn canonical Dataset bindings into persistent static/interactive XYZ representations | Scientific modules that already publish canonical tabular Datasets. |
| Plot 3D API v2 (Octave) | Static line3/scatter3/surface/mesh/contour/trisurf rendering with framework axis/view/color policy | Analysis modules producing normal plot artifacts rather than a full interactive native scene. |
Acquisition handler acq.geometry_3d | Import supported 3D file formats into GX-TXT artifacts/contracts | User-facing geometry acquisition workflow. |
Viewer Provider adapter in dev-40
The temporary viewer.engine_3d adapter is the most complete integration example. Its C++ Tcl extension creates an engine/scene/view/target/viewport, maps Viewer Provider layer descriptors into Native 3D objects, applies graphics policy, restores camera/presentation state, performs CORE picking/navigation/gizmo operations, and writes pixels back to the Tk host. The GUI does not own authoritative 3D geometry.
Session persistence guidance
- Persist source artifact/Dataset identity and SHA-256/fingerprint.
- Persist stable logical layer IDs, camera, clipping, lighting, background, object transforms and scientific presentation definitions.
- For animation, persist frame times, logical layer IDs, source paths/fingerprints and derived-layer definitions; do not serialize native handles.
- Do not persist transient VTK/display cell IDs.
- When a source changes, use explicit synchronization/rebuild semantics; existing interactive representations may deliberately remain frozen until Sync.
Plot Dataset 3D bridge
The dedicated Plot Dataset 3D API follows: canonical Dataset → persistent plot.dataset.xyz Variant/bindings → static preparation → independent Viewer representation + VTP artifacts → Native 3D renderer. A source graph can have several interactive representations. Source fingerprint and representation identity are intentionally separate.
Build/link boundary
The native library is C++17 internally but exports a C ABI. The CMake target is gx3de; public includes are under core/native3d/include. The implementation links VTK 9, OpenSSL Crypto and threads; OCCT support is conditional at build time. Consumers should include the public headers and link to libgx3de, not include files from core/native3d/src.
#include "native_3d_engine_api_v1.h"
#include "native_3d_field_api_v1.h"
#include "native_3d_animation_api_v1.h"
/* Link against libgx3de; never include VTK/OCCT implementation headers
merely to use the public GX3DE ABI. */Windows boundary
The ABI itself is platform-neutral and includes import/export annotations. A D3D11 probe and source path exist, but dev-40’s own architecture record states that the Windows D3D11 presentation path still requires real Windows compilation/runtime validation. Code should capability-check instead of assuming parity from source presence alone.