Architecture & ownership — GX-TXT Native 3D CORE API

Ownership graph

Ownership is explicit and hierarchical. Destroying an owner invalidates its owned handles. The most important rule is that handles are process-local opaque pointers; persist logical IDs and source identity, never raw handles.

Owner	Owned state	Important exceptions / notes
`gx3de_engine`	Scenes, render targets, STEP documents, jobs, in-memory cache/policy state	Calls on one engine are serialized by the caller; independent engines do not share mutable state.
`gx3de_scene`	Objects, groups, planes, anchors, sections, profiles, measurements, constraints, views, timelines	Scene teardown destroys remaining timelines before views/objects.
`gx3de_target`	Viewport regions and backend rendering resources	Target/OpenGL context is owned by the creating thread.
`gx3de_animation`	Lazy-loader-created frame objects, layers and derived animation state	Borrowed external objects remain caller-owned and must outlive the timeline.
`gx3de_step_document`	Imported assembly/XDE document representation	Objects instantiated from a document retain independent immutable B-Rep prototypes and may outlive the document.
`gx3de_repeat_result`	Prototype/remainder analysis snapshot and captured placements	Destroy explicitly when finished.

Authoritative state vs presentation

Meshes and scientific arrays are immutable source data. Display LOD, glyphs, tubes, colormaps, textures, shadows and clipping are presentation choices.
Derived operations such as clip, projection, isosurface, B-Rep mesh conversion, LOD and field tracing publish new objects rather than editing the source.
View-local state—camera, clipping, selection, background, lights, navigation cube, working plane and gizmos—does not alter scene geometry.
Viewer Provider Session metadata should store source IDs/fingerprints and compact presentation definitions, not renderer-internal cell IDs or C handles.

Transforms and coordinate spaces

Matrices are affine, double-precision, column-major gx3de_mat4. Object-local geometry is transformed through parent/group hierarchy into world space. Planes and field seed definitions explicitly state whether coordinates are local or world in their descriptors. B-Rep topology queries refer to the immutable local shape; transforms do not change topology indices.

Stable vs transient identity

A source mesh triangle index is stable for that immutable mesh. A B-Rep topology index is stable only for the exact immutable shape. Renderer display cell IDs are transient across rerender, tessellation, LOD and rebuild; never persist them.

Destruction semantics

Destroying an object freezes dependent anchors at their last world position.
Deleted required measurement/constraint references cause GX3DE_NOT_FOUND on later evaluation.
Projection/profile/section snapshots may survive source destruction where documented, but explicit refresh then fails if the source is gone.
Lazy animation loader objects are owned by the timeline only when created successfully in the correct scene; a wrong-scene object remains caller-owned.

Threading model

The base API is not an arbitrary concurrent scene graph. Target rendering and mutators are intended for the creating/owner thread. Only documented job poll/progress/cancel style operations are designed for concurrent observation. A prepared background job works on private input/result state; the owner thread takes the resulting object/document.