LDK_KEYFRAME_PROPERTY_NAME_CAPACITY
#define LDK_KEYFRAME_PROPERTY_NAME_CAPACITY 96ldk_keyframe_animation.h
homeKeyframe animations
Code-authored keyframe clips, relative target bindings, and TML I/O.
LDKKeyframe
typedef struct LDKKeyframe{
float time;
LDKPropertyValue value;
}LDKKeyframe;LDKKeyframeTrack
typedef struct LDKKeyframeTrack{
u64 target_path;
u32 component_type;
char property_name[LDK_KEYFRAME_PROPERTY_NAME_CAPACITY];
LDKFieldType value_type;
LDKKeyframe *keys;
u32 count;
u32 capacity;
}LDKKeyframeTrack;LDKKeyframeEventValueType
typedef enum LDKKeyframeEventValueType{
LDK_KEYFRAME_EVENT_INTEGER=0,
LDK_KEYFRAME_EVENT_STRING
}LDKKeyframeEventValueType;LDKKeyframeEvent
typedef struct LDKKeyframeEvent{
float time;
LDKKeyframeEventValueType type;
i32 number;
char *text;
}LDKKeyframeEvent;LDKKeyframeAnimation
typedef struct LDKKeyframeAnimation{
float duration;
LDKKeyframeTrack *tracks;
u32 track_count;
u32 track_capacity;
LDKKeyframeEvent *events;
u32 event_count;
u32 event_capacity;
}LDKKeyframeAnimation;LDKKeyframeEventFn
Called synchronously for an animation marker.
typedef void(*LDKKeyframeEventFn)(LDKEntity root, const LDKKeyframeEvent *event, void *user);Parameters
root- Entity driving the animation.
event- Marker payload; pointer is valid only during the callback.
user- Opaque callback context.
ldk_keyframe_path_root
Return the reserved path hash of an animation source root.
LDK_API u64 ldk_keyframe_path_root(void);Returns
Stable root hash used for relative track bindings.
ldk_keyframe_path_child
Extend a relative hierarchy path with a child name hash.
LDK_API u64 ldk_keyframe_path_child(
u64 parent_path,
u64 name_hash
);Parameters
u64 parent_path- Existing hash relative to the animation source.
u64 name_hash- Nonzero persistent entity name hash.
Returns
Deterministic path hash, or zero for invalid inputs.
ldk_keyframe_entity_path
Compute the path of a descendant relative to an animation root.
LDK_API bool ldk_keyframe_entity_path(
LDKEntity root,
LDKEntity target,
u64 *out_path
);Parameters
Returns
True if target belongs to the transform subtree rooted at root.
ldk_keyframe_target_resolve
Resolve a relative path hash to exactly one descendant.
LDK_API bool ldk_keyframe_target_resolve(
LDKEntity root,
u64 path,
LDKEntity *out
);Parameters
Returns
True if the path resolves unambiguously. Duplicate matching paths fail.
ldk_keyframe_animation_init
Initialize a clip to an empty, one-second animation.
LDK_API void ldk_keyframe_animation_init(LDKKeyframeAnimation *clip);Parameters
LDKKeyframeAnimation *clip- Animation clip instance.
Returns
Nothing. Call before any other clip operation.
ldk_keyframe_animation_clear
Free a clip and reset it to the initialized state.
LDK_API void ldk_keyframe_animation_clear(LDKKeyframeAnimation *clip);Parameters
LDKKeyframeAnimation *clip- Animation clip instance.
Returns
Nothing. Invalidates pointers into tracks, keys, and events.
ldk_keyframe_animation_validate
Validate a clip independently of the ECS and reflected metadata.
LDK_API bool ldk_keyframe_animation_validate(const LDKKeyframeAnimation *clip);Parameters
const LDKKeyframeAnimation *clip- Animation clip instance.
Returns
True if the duration, tracks, keys and events are structurally valid.
ldk_keyframe_animation_copy
Deep-copy all tracks, keys, events and owned event strings.
LDK_API bool ldk_keyframe_animation_copy(
LDKKeyframeAnimation *destination,
const LDKKeyframeAnimation *source
);Parameters
LDKKeyframeAnimation *destination- Initialized destination clip.
const LDKKeyframeAnimation *source- Initialized source clip.
Returns
True on success; otherwise destination remains unchanged.
ldk_keyframe_animation_duration_set
Set duration without discarding keys or events.
LDK_API bool ldk_keyframe_animation_duration_set(
LDKKeyframeAnimation *clip,
float duration
);Parameters
LDKKeyframeAnimation *clip- Animation clip instance.
float duration- Requested clip length in seconds.
Returns
False if invalid or any key/event would lie beyond duration.
ldk_keyframe_animation_track_find
Find a track identified by relative path and reflected field.
LDK_API i32 ldk_keyframe_animation_track_find(
const LDKKeyframeAnimation *clip,
u64 path,
u32 component_type,
const char *property_name
);Parameters
const LDKKeyframeAnimation *clip- Animation clip instance.
u64 path- Hash relative to the animation source root.
u32 component_type- Runtime ECS component type.
const char *property_name- Persistent reflected field identifier.
Returns
Zero-based track index, or -1 if not found.
ldk_keyframe_animation_track_add
Create a track for an editable reflected component field.
LDK_API i32 ldk_keyframe_animation_track_add(
LDKKeyframeAnimation *clip,
u64 path,
u32 component_type,
const char *property_name
);Parameters
LDKKeyframeAnimation *clip- Animation clip instance.
u64 path- Hash relative to the animation source root.
u32 component_type- Runtime ECS component type.
const char *property_name- Persistent reflected field identifier.
Returns
Track index; existing track is reused, -1 if unavailable or unsupported. Note: Reflected component metadata must be registered when authoring.
ldk_keyframe_animation_track_remove
Remove a track and all of its keyframes.
LDK_API bool ldk_keyframe_animation_track_remove(
LDKKeyframeAnimation *clip,
u32 track
);Parameters
LDKKeyframeAnimation *clip- Animation clip instance.
u32 track- Zero-based track index or track description.
Returns
True if the track existed. Later track indices shift.
ldk_keyframe_animation_key_set
Insert or update a typed keyframe at the specified second.
LDK_API bool ldk_keyframe_animation_key_set(
LDKKeyframeAnimation *clip,
u32 track,
float time,
LDKPropertyValue value
);Parameters
LDKKeyframeAnimation *clip- Animation clip instance.
u32 track- Zero-based track index or track description.
float time- Time in seconds.
LDKPropertyValue value- Type-tagged property value.
Returns
True on success; may extend clip duration. Requires available component metadata. Note: Reflected component metadata must be registered when authoring.
ldk_keyframe_animation_key_remove
Remove a keyframe from a track.
LDK_API bool ldk_keyframe_animation_key_remove(
LDKKeyframeAnimation *clip,
u32 track,
u32 key
);Parameters
LDKKeyframeAnimation *clip- Animation clip instance.
u32 track- Zero-based track index or track description.
u32 key- Zero-based keyframe index.
Returns
True if removed. Subsequent key indices shift.
ldk_keyframe_animation_key_move
Move a keyframe in time while keeping its value and chronological order.
LDK_API bool ldk_keyframe_animation_key_move(
LDKKeyframeAnimation *clip,
u32 track,
u32 key,
float new_time,
u32 *out_index
);Parameters
LDKKeyframeAnimation *clip- Animation clip instance.
u32 track- Zero-based track index or track description.
u32 key- Zero-based keyframe index.
float new_time- Requested new timestamp in seconds.
u32 *out_index- Optional output for the moved item index.
Returns
True on success. Rejects collisions and times beyond duration.
ldk_keyframe_animation_sample
Evaluate a single track at the requested time without changing entities.
LDK_API bool ldk_keyframe_animation_sample(
const LDKKeyframeAnimation *clip,
u32 track,
float time,
LDKPropertyValue *out_value
);Parameters
const LDKKeyframeAnimation *clip- Animation clip instance.
u32 track- Zero-based track index or track description.
float time- Time in seconds.
LDKPropertyValue *out_value- Receives the sampled property value.
Returns
True if the track has keys and its values can be evaluated.
ldk_keyframe_animation_apply
Sample and write all nonempty tracks to the subtree of a root entity.
LDK_API bool ldk_keyframe_animation_apply(
const LDKKeyframeAnimation *clip,
LDKEntity root,
float time
);Parameters
const LDKKeyframeAnimation *clip- Animation clip instance.
LDKEntity root- Entity used as the root for relative bindings.
float time- Time in seconds.
Returns
True if all tracks applied successfully; missing bindings are reported by false.
ldk_keyframe_animation_value_from_entity
Read the current component value addressed by a track.
LDK_API bool ldk_keyframe_animation_value_from_entity(
LDKEntity entity,
const LDKKeyframeTrack *track,
LDKPropertyValue *out_value
);Parameters
LDKEntity entity- Target ECS entity.
const LDKKeyframeTrack *track- Zero-based track index or track description.
LDKPropertyValue *out_value- Receives the sampled property value.
Returns
True if the editable reflected field exists and can be read.
ldk_keyframe_animation_event_add_integer
Insert an integer event marker at the specified second.
LDK_API bool ldk_keyframe_animation_event_add_integer(
LDKKeyframeAnimation *clip,
float time,
i32 number
);Parameters
LDKKeyframeAnimation *clip- Animation clip instance.
float time- Time in seconds.
i32 number- Integer event payload.
Returns
True on success; extends duration if needed.
ldk_keyframe_animation_event_add_string
Insert a string event marker, copying the supplied text.
LDK_API bool ldk_keyframe_animation_event_add_string(
LDKKeyframeAnimation *clip,
float time,
const char *text
);Parameters
LDKKeyframeAnimation *clip- Animation clip instance.
float time- Time in seconds.
const char *text- NUL-terminated event string.
Returns
True on success; extends duration if needed.
ldk_keyframe_animation_event_remove
Delete an event marker and its owned string.
LDK_API bool ldk_keyframe_animation_event_remove(
LDKKeyframeAnimation *clip,
u32 event_index
);Parameters
LDKKeyframeAnimation *clip- Animation clip instance.
u32 event_index- Zero-based event index.
Returns
True if removed. Later event indices shift.
ldk_keyframe_animation_event_move
Change an event timestamp while preserving event ordering.
LDK_API bool ldk_keyframe_animation_event_move(
LDKKeyframeAnimation *clip,
u32 event_index,
float new_time,
u32 *out_index
);Parameters
LDKKeyframeAnimation *clip- Animation clip instance.
u32 event_index- Zero-based event index.
float new_time- Requested new timestamp in seconds.
u32 *out_index- Optional output for the moved item index.
Returns
True on success; times beyond duration are rejected.
ldk_keyframe_animation_event_set_integer
Replace an event payload with an integer.
LDK_API bool ldk_keyframe_animation_event_set_integer(
LDKKeyframeAnimation *clip,
u32 event_index,
i32 number
);Parameters
LDKKeyframeAnimation *clip- Animation clip instance.
u32 event_index- Zero-based event index.
i32 number- Integer event payload.
Returns
True if the event existed.
ldk_keyframe_animation_event_set_string
Replace an event payload with a copied string.
LDK_API bool ldk_keyframe_animation_event_set_string(
LDKKeyframeAnimation *clip,
u32 event_index,
const char *text
);Parameters
LDKKeyframeAnimation *clip- Animation clip instance.
u32 event_index- Zero-based event index.
const char *text- NUL-terminated event string.
Returns
True on success; the old payload remains if allocation fails.
ldk_keyframe_animation_events_dispatch
Synchronously deliver all events crossed in (previous_time, current_time].
LDK_API void ldk_keyframe_animation_events_dispatch(
const LDKKeyframeAnimation *clip,
LDKEntity root,
float previous_time,
float current_time,
LDKKeyframeEventFn fn,
void *user
);Parameters
const LDKKeyframeAnimation *clip- Animation clip instance.
LDKEntity root- Root entity containing the animation source.
float previous_time- Exclusive lower time bound in seconds.
float current_time- Inclusive upper time bound in seconds.
LDKKeyframeEventFn fn- Event callback.
void *user- Opaque callback context.
Returns
Nothing. Event payloads are temporary snapshots valid during each callback. Note: Callbacks may mutate or destroy the source; do not keep event pointers.
ldk_keyframe_animation_from_tml
Parse a version-2 TML animation into an initialized clip.
LDK_API bool ldk_keyframe_animation_from_tml(
LDKKeyframeAnimation *clip,
const char *source
);Parameters
LDKKeyframeAnimation *clip- Animation clip instance.
const char *source- NUL-terminated TML input.
Returns
True on success; clip remains unchanged on failure.
ldk_keyframe_animation_to_tml
Serialize a structurally valid clip to TML version 2.
LDK_API bool ldk_keyframe_animation_to_tml(
const LDKKeyframeAnimation *clip,
char **out_source
);Parameters
const LDKKeyframeAnimation *clip- Animation clip instance.
char **out_source- Receives a newly allocated NUL-terminated TML buffer.
Returns
True on success. Caller must free *out_source.
ldk_keyframe_animation_load
Load a clip from the configured asset source.
LDK_API bool ldk_keyframe_animation_load(
LDKKeyframeAnimation *clip,
const char *asset_path
);Parameters
LDKKeyframeAnimation *clip- Animation clip instance.
const char *asset_path- Logical .anim asset path.
Returns
True on success; existing clip remains unchanged on failure.
ldk_keyframe_animation_save
Save a clip as TML through the configured asset source.
LDK_API bool ldk_keyframe_animation_save(
const LDKKeyframeAnimation *clip,
const char *asset_path
);Parameters
const LDKKeyframeAnimation *clip- Animation clip instance.
const char *asset_path- Logical .anim asset path.
Returns
True if successfully serialized and written.