Animation API reference

GX3DE_API gx3de_result gx3de_animation_create(gx3de_scene *scene,const char *time_unit_utf8,gx3de_animation **out);

Timeline lifetime is nested in scene lifetime. Referenced external objects must outlive timeline. Destroy timeline before scene. Unit is UTF-8 text. No wall-clock or event loop is required; advance() takes caller elapsed time.

GX3DE_API gx3de_result gx3de_animation_frame_add(gx3de_animation *timeline,double time_value, gx3de_object *source_object,gx3de_animation_frame_loader loader,void *loader_user,uint64_t *frame_index);

Times must be strictly increasing; source object is borrowed. A NULL source requires a loader. Lazy loaded objects are timeline-owned and LRU-evicted.

GX3DE_API gx3de_result gx3de_animation_time_add(gx3de_animation *timeline,double time_value,uint64_t *frame_index);

A time-only frame supports timelines whose content lives in named layers.

GX3DE_API gx3de_result gx3de_animation_layer_create(gx3de_animation *timeline,const char *id_utf8,gx3de_animation_layer **out);

UTF-8 layer IDs are stable logical identities. Sources can be supplied or loaded lazily; borrowed sources must outlive the timeline. Frame slots can be sparse. All sources remain immutable.

GX3DE_API gx3de_result gx3de_animation_layer_bind_lines(gx3de_animation_layer *layer, gx3de_animation_layer *source,const gx3de_field_line_spec *spec);

Native derived layers rebuild on active frame changes. Their source layer must precede them; seed arrays are copied when the binding is set.

GX3DE_API gx3de_result gx3de_animation_layer_bind_pathlines(gx3de_animation_layer *layer, gx3de_animation_layer *source,const gx3de_field_pathline_spec *spec);

Bind pathlines to successive source-track frames. At active frame i the derived object contains the trajectory through samples [0,i]; frame zero intentionally has no line. The source track must provide every frame. The binding copies seeds and integration settings; times and source frames come from the parent timeline. Derived objects participate in normal LRU, resident-frame and estimated-memory limits.

GX3DE_API gx3de_result gx3de_animation_playback_range_set(gx3de_animation *timeline,uint64_t first_frame,uint64_t last_frame);

Inclusive playback frame range. Explicit seek/render may still address all frames; play, stop, step and advance use this sub-range.

GX3DE_API gx3de_result gx3de_animation_active_object_get(gx3de_animation *timeline,gx3de_object **out);

Borrowed current source for inspection/provenance; may change on seek and must never be retained across a seek or timeline destruction.

GX3DE_API gx3de_result gx3de_animation_object_key_set(gx3de_animation *timeline,uint64_t frame_index, gx3de_object *object,const gx3de_mat4 *local_pose,uint32_t visible,double opacity);

A keyed object track controls local pose, visibility and opacity. Each key belongs to one frame; linear policy interpolates opacity/translation only when adjacent rotation/scale matrices match. Visibility remains discrete.

GX3DE_API gx3de_result gx3de_animation_cancel(gx3de_animation *timeline);

Sets a cancellation flag checked before/after a lazy loader and between sequence frames. A blocking loader must implement its own finer cancellation.

GX3DE_API gx3de_result gx3de_animation_cancel_requested(gx3de_animation *timeline,uint32_t *requested);

Safe to call from a synchronous frame loader to cooperate with cancellation.

GX3DE_API gx3de_result gx3de_animation_render_frame_rgba(gx3de_animation *timeline,gx3de_view *view, uint64_t frame_index,uint32_t width,uint32_t height,uint8_t *pixels,uint64_t capacity,uint64_t *required_bytes);

Seeks exactly before ordinary explicit-resolution rendering. PNG sequence names are prefix + zero-padded 6-digit frame index + ".png". Caller owns target directory. On failure, subsequent frames are not attempted.