Picking & manipulation — GX-TXT Native 3D CORE API

Picking

gx3de_viewport_pick takes top-left viewport pixels and returns a gx3de_pick_hit: borrowed object, world/local hit point, optional normal, transient display cell/point IDs and—when uniquely resolved—exact immutable B-Rep face topology plus normalized UV. Geometry kind distinguishes mesh, B-Rep display, scientific and repeat presentation.

Persist the right identity

Persist object/layer identity and local/topological references. Renderer display cell and point IDs are transient. A repeated-instance pick may intentionally become a world-point snapshot because one prototype display cell cannot name stable source topology for every occurrence.

Converting a pick into an anchor

gx3de_pick_make_anchor converts the hit into a scene-owned API anchor when a stable anchor interpretation exists. The resulting anchor can drive selection, markers, measurements, axes, constraints and gizmo pivots.

Camera-space helpers

gx3de_viewport_world_to_screen, gx3de_viewport_screen_to_world and gx3de_viewport_ray keep projection math in CORE. Consumers therefore do not need to reimplement camera transforms in Tcl/Tk or another GUI.

Object transform gizmo

A view-owned gx3de_gizmo attaches to one object. It supports world/local spaces, object/explicit/anchor pivots, axis/plane/free translation and X/Y/Z rotation. Gizmo begin snapshots scene poses. Updates derive proposals from the original pose and transactionally solve scene constraints that reference the moving object.

Mode	Behavior
Live (`preview_only=0`)	Update applies temporary solved poses for rendering; `end(accept)` commits or restores the snapshot.
Data-only preview	Update returns a proposed local matrix but restores all scene poses before returning; end does not commit scene mutation.

Sheared/nonorthogonal local frames are rejected for local manipulation.
Ray-plane intersections behind the pointer are rejected.
An axis exactly aligned with the pointer ray is geometrically ambiguous and returns GX3DE_DEGENERATE.
No geometry buffer is modified by manipulation; only object poses change.

Working-plane / clip manipulation

gx3de_view_manipulation_begin/update/end handles working-plane origin/orientation, clip-plane origin/orientation and individual clip-box faces. Like the object gizmo, the interaction snapshots starting state and supports cancel/rollback.

View interaction descriptor

gx3de_view_interaction_set/get is a small explicit descriptor for NONE/POINT/DRAG with world positions and pointer ID. It is view-local and independent of the authoritative scene.