Field API group
The field group is additive to the base ABI and is discovered through GX3DE_API_GROUP_FIELD. dev-40 reports Field API version 1 with capabilities for lines, slices, volume transfer, pathlines and unstructured interpolation support.
Streamlines / field lines
gx3de_field_lines_create integrates the normalized vector direction with RK4. Seeds can be explicit points, an arithmetic line or an arithmetic plane in field-local coordinates. The operation is bounded by step size, low-vector threshold, per-direction step count, total output points and temporary memory.
| Source | Supported behavior |
|---|---|
| Structured image/VTI | Trilinear spatial interpolation. |
| Unstructured | Tetrahedral/hexahedral cells supported by current implementation; inspect support with gx3de_field_source_info_get. |
The result is an ordinary immutable scientific polyline object, parented to the source field. Optional scalar sampling travels with the output for coloring. Regenerate when source values or seed definitions change.
Scalar slices
gx3de_field_slice_create samples a rectangular plane from a structured image scalar field. Every requested point must be in-domain; an out-of-domain sample rejects the entire result. The returned object is an ordinary scientific triangle surface with sampled scalar data.
Time-dependent pathlines
gx3de_field_pathlines_create integrates dx/dt = v(x,t) across two or more strictly increasing samples. Frames can be borrowed objects, callback-loaded objects, or a mixture. Structured frames must share grid geometry; unstructured frames must share cell topology, point coordinates and connectivity; all samples must share local-to-world transform. The implementation linearly interpolates vector values in time and applies RK4 integration with a caller-bounded time step.
Volume transfer
gx3de_field_volume_style_set/get configures VTI/image volume rendering without modifying arrays. Up to 16 strictly ordered scalar→RGBA transfer points are supported, together with an explicit positive ray sample distance. Isosurfaces, slices, point/glyph clouds and volume presentation can coexist as separate objects/layers.
Animation API group
An animation timeline is scene-owned and deterministic. Frames have strictly increasing numeric times and UTF-8 time-unit metadata. A frame may borrow an existing object or lazily create one through a synchronous callback. Named layers provide stable logical identities independent of changing active objects.
Interpolation semantics
- Nearest sample selection is deterministic; time ties select the earlier frame.
- No interpolation of topology, point arrays, scalar arrays, vector arrays, radii or source-object identity is implied.
- Linear keyed-object mode interpolates translation and opacity only when adjacent rotation/scale parts match.
- Visibility and camera keys are discrete.
- A conflicting rotation/scale pair returns
GX3DE_UNSUPPORTEDbefore committing the seek.
Playback and rendering
play/pause/stop/step/advance support once, loop and ping-pong. advance(elapsed_seconds) uses caller-supplied elapsed time; no event loop or wall clock is required. Frame rendering uses ordinary view rendering at explicit dimensions, and PNG sequences use six-digit frame indices.
Multilayer derived fields
Named layers can bind native derived streamlines, slices, isosurfaces and pathlines to a source layer. Derived content is regenerated when the active source changes. For pathlines, frame zero intentionally has no trajectory; frame i contains the path through samples 0…i.
Timeline cache
The lazy-frame cache defaults to two resident objects and 256 MiB estimated CPU payload. LRU eviction never removes the currently displayed object. Renderer GPU/display budgets are independent from timeline CPU-byte limits.