Mike-Solar
eaa301b755
- keyframed state, count, read (time in sequence timebase + mapped values), add/remove, easing read/write (linear/bezier/hold with control points), and clear - all undoable with full undo/redo assertions - easing set commands are minimal capi-local UndoCommands matching the app-layer semantics (engine has none of its own); same-time duplicates are rejected with E_STATE instead of hitting the engine's debug assert
355 lines
13 KiB
C
355 lines
13 KiB
C
/***
|
|
|
|
Oak - Non-Linear Video Editor
|
|
Copyright (C) 2026 Oak Team
|
|
|
|
This program is free software: you can redistribute it and/or modify
|
|
it under the terms of the GNU General Public License as published by
|
|
the Free Software Foundation, either version 3 of the License, or
|
|
(at your option) any later version.
|
|
|
|
This program is distributed in the hope that it will be useful,
|
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
GNU General Public License for more details.
|
|
|
|
You should have received a copy of the GNU General Public License
|
|
along with this program. If not, see <http://www.gnu.org/licenses/>.
|
|
|
|
***/
|
|
|
|
#ifndef OAKENGINE_NODE_H
|
|
#define OAKENGINE_NODE_H
|
|
|
|
#include <stdint.h>
|
|
|
|
#include "export.h"
|
|
#include "init.h"
|
|
#include "project.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/**
|
|
* @file node.h
|
|
* @brief C ABI for the node graph: enumeration, metadata, input
|
|
* introspection, parameter access and edge editing
|
|
*
|
|
* An OakEngineNode wraps the engine's olive::Node (engine/node/node.h).
|
|
* Handles are borrowed views of nodes owned by their project (QObject
|
|
* parent chain); they become invalid when the project is freed or the node
|
|
* is removed (e.g. by undoing oakengine_project_add_node()).
|
|
*
|
|
* Parameter values cross the boundary as the small POD oak_node_value;
|
|
* which of its fields are meaningful depends on the oak_node_value_type
|
|
* (see the enum). String-typed inputs (NodeValue::k_file) do not fit the
|
|
* POD and use the dedicated oakengine_node_get/set_input_string() pair
|
|
* (buf/size convention).
|
|
*
|
|
* Every mutating call is undoable through the global undo stack, like the
|
|
* timeline editing primitives (direct non-undoable application when the
|
|
* engine is not initialized). Errors follow the family model: negative
|
|
* OAKENGINE_E_* codes, NULL handles as no-ops, and a thread-local
|
|
* human-readable reason via oakengine_node_last_error().
|
|
*/
|
|
|
|
/**
|
|
* @brief Value type of an oak_node_value / a node input.
|
|
*
|
|
* Mirrors the data-carrying subset of olive::NodeValue::Type
|
|
* (engine/node/value.h): combo maps to k_combo, STRING maps to k_file
|
|
* (string-typed inputs handled by the dedicated string functions). Input
|
|
* types without a POD representation (texture, samples, params, bezier,
|
|
* binary, ...) report as OAK_NODE_VALUE_NONE.
|
|
*/
|
|
typedef enum oak_node_value_type {
|
|
OAK_NODE_VALUE_NONE = 0,
|
|
OAK_NODE_VALUE_INT, /**< num (olive k_int) */
|
|
OAK_NODE_VALUE_FLOAT, /**< f[0] (olive k_float) */
|
|
OAK_NODE_VALUE_BOOL, /**< num 0/1 (olive k_boolean) */
|
|
OAK_NODE_VALUE_RATIONAL, /**< num/den (olive k_rational) */
|
|
OAK_NODE_VALUE_COLOR, /**< f[0..3] = r,g,b,a (olive k_color) */
|
|
OAK_NODE_VALUE_VEC2, /**< f[0..1] (olive k_vec2) */
|
|
OAK_NODE_VALUE_VEC3, /**< f[0..2] (olive k_vec3) */
|
|
OAK_NODE_VALUE_VEC4, /**< f[0..3] (olive k_vec4) */
|
|
OAK_NODE_VALUE_COMBO, /**< num = selected index (olive k_combo) */
|
|
OAK_NODE_VALUE_STRING /**< k_file; string APIs only, never in the POD */
|
|
} oak_node_value_type;
|
|
|
|
/**
|
|
* @brief POD parameter value. Only the fields documented for the value's
|
|
* `type` are meaningful.
|
|
*/
|
|
typedef struct oak_node_value {
|
|
int type; /**< oak_node_value_type. */
|
|
int64_t num; /**< INT/COMBO value, BOOL 0/1, RATIONAL numerator. */
|
|
int64_t den; /**< RATIONAL denominator. */
|
|
double f[4]; /**< FLOAT f[0]; VEC2/3/4 f[0..n-1]; COLOR r,g,b,a. */
|
|
} oak_node_value;
|
|
|
|
/**
|
|
* @brief Opaque node handle (borrowed from the owning project).
|
|
*/
|
|
typedef struct OakEngineNode OakEngineNode;
|
|
|
|
/**
|
|
* @brief Human-readable reason for the last failed node call on this
|
|
* thread (buf/size convention).
|
|
*/
|
|
OAKENGINE_API int oakengine_node_last_error(char *buf, int buf_size);
|
|
|
|
/* ---- Enumeration --------------------------------------------------------- */
|
|
|
|
/**
|
|
* @brief Number of nodes in the project's graph (Project::nodes()).
|
|
*/
|
|
OAKENGINE_API int oakengine_project_node_count(const OakEngineProject *self);
|
|
|
|
/**
|
|
* @brief Borrowed handle of the node at `index`, or NULL when out of range.
|
|
*/
|
|
OAKENGINE_API OakEngineNode *
|
|
oakengine_project_node_at(const OakEngineProject *self, int index);
|
|
|
|
/* ---- Metadata -------------------------------------------------------------- */
|
|
|
|
/**
|
|
* @brief The node's type id (Node::id(), e.g.
|
|
* "org.olivevideoeditor.Olive.solidgenerator"). buf/size convention.
|
|
*/
|
|
OAKENGINE_API int oakengine_node_get_type_id(const OakEngineNode *self,
|
|
char *buf, int buf_size);
|
|
|
|
/**
|
|
* @brief The node's display name (Node::name(), translated).
|
|
* buf/size convention.
|
|
*/
|
|
OAKENGINE_API int oakengine_node_get_name(const OakEngineNode *self,
|
|
char *buf, int buf_size);
|
|
|
|
/**
|
|
* @brief The node's user label (Node::get_label()). buf/size convention.
|
|
*/
|
|
OAKENGINE_API int oakengine_node_get_label(const OakEngineNode *self,
|
|
char *buf, int buf_size);
|
|
|
|
/**
|
|
* @brief Set the node's user label (undoable, olive::NodeRenameCommand).
|
|
*/
|
|
OAKENGINE_API int oakengine_node_set_label(OakEngineNode *self,
|
|
const char *label);
|
|
|
|
/* ---- Input introspection ---------------------------------------------------- */
|
|
|
|
/**
|
|
* @brief Number of declared inputs (Node::inputs(); array elements are not
|
|
* counted separately).
|
|
*/
|
|
OAKENGINE_API int oakengine_node_input_count(const OakEngineNode *self);
|
|
|
|
/**
|
|
* @brief The input id at `index` (Node::inputs()). buf/size convention;
|
|
* returns OAKENGINE_E_NOT_FOUND for an out-of-range index.
|
|
*/
|
|
OAKENGINE_API int oakengine_node_input_id(const OakEngineNode *self,
|
|
int index, char *buf, int buf_size);
|
|
|
|
/**
|
|
* @brief The input's value type as oak_node_value_type.
|
|
*
|
|
* Unknown ids and inputs whose NodeValue::Type has no POD representation
|
|
* (texture, samples, params, ...) report OAK_NODE_VALUE_NONE; k_file
|
|
* reports OAK_NODE_VALUE_STRING.
|
|
*/
|
|
OAKENGINE_API int oakengine_node_input_get_type(const OakEngineNode *self,
|
|
const char *input_id);
|
|
|
|
/**
|
|
* @brief 1 if the input currently has a connected edge
|
|
* (Node::is_input_connected()).
|
|
*/
|
|
OAKENGINE_API int oakengine_node_input_is_connected(
|
|
const OakEngineNode *self, const char *input_id);
|
|
|
|
/* ---- Parameter access -------------------------------------------------------- */
|
|
|
|
/**
|
|
* @brief Read an input's standard value (Node::get_standard_value())
|
|
* mapped into `out`.
|
|
*
|
|
* String (k_file) inputs fail with OAKENGINE_E_INVALID -- use
|
|
* oakengine_node_get_input_string(). Types without a POD representation
|
|
* fail with OAKENGINE_E_NOT_FOUND; a missing input id fails with
|
|
* OAKENGINE_E_NOT_FOUND as well.
|
|
*/
|
|
OAKENGINE_API int oakengine_node_get_input(const OakEngineNode *self,
|
|
const char *input_id,
|
|
oak_node_value *out);
|
|
|
|
/**
|
|
* @brief Write an input's standard value (undoable,
|
|
* olive::NodeParamSetStandardValueCommand).
|
|
*
|
|
* `v->type` must equal the input's declared type (STRING is rejected --
|
|
* use oakengine_node_set_input_string()); a type mismatch or an unknown
|
|
* input id returns OAKENGINE_E_INVALID / OAKENGINE_E_NOT_FOUND.
|
|
*/
|
|
OAKENGINE_API int oakengine_node_set_input(OakEngineNode *self,
|
|
const char *input_id,
|
|
const oak_node_value *v);
|
|
|
|
/**
|
|
* @brief Read a string-typed (k_file) input's value (buf/size convention).
|
|
*/
|
|
OAKENGINE_API int oakengine_node_get_input_string(const OakEngineNode *self,
|
|
const char *input_id,
|
|
char *buf, int buf_size);
|
|
|
|
/**
|
|
* @brief Write a string-typed (k_file) input's value (undoable).
|
|
*/
|
|
OAKENGINE_API int oakengine_node_set_input_string(OakEngineNode *self,
|
|
const char *input_id,
|
|
const char *s);
|
|
|
|
/* ---- Graph editing ------------------------------------------------------------- */
|
|
|
|
/**
|
|
* @brief Create a node of `type_id` in the project (undoable:
|
|
* NodeFactory::create_from_id() + olive::NodeAddCommand).
|
|
*
|
|
* Returns the borrowed node handle, or NULL when `type_id` is not a
|
|
* registered node id (see oakengine_node_last_error()).
|
|
*/
|
|
OAKENGINE_API OakEngineNode *
|
|
oakengine_project_add_node(OakEngineProject *project, const char *type_id);
|
|
|
|
/**
|
|
* @brief Remove a node from the project, disconnecting its edges
|
|
* (undoable, olive::NodeRemoveAndDisconnectCommand).
|
|
*/
|
|
OAKENGINE_API int oakengine_project_remove_node(OakEngineProject *project,
|
|
OakEngineNode *node);
|
|
|
|
/**
|
|
* @brief Connect `output_node`'s output into `input_node`'s `input_id`
|
|
* (undoable, olive::NodeEdgeAddCommand).
|
|
*
|
|
* Fails with OAKENGINE_E_INVALID when the input is not connectable or the
|
|
* id is unknown, and with OAKENGINE_E_STATE when the input is already
|
|
* connected (disconnect first).
|
|
*/
|
|
OAKENGINE_API int oakengine_node_connect(OakEngineNode *output_node,
|
|
OakEngineNode *input_node,
|
|
const char *input_id);
|
|
|
|
/**
|
|
* @brief Remove the edge feeding `input_node`'s `input_id` (undoable,
|
|
* olive::NodeEdgeRemoveCommand). OAKENGINE_E_NOT_FOUND when not connected.
|
|
*/
|
|
OAKENGINE_API int oakengine_node_disconnect(OakEngineNode *input_node,
|
|
const char *input_id);
|
|
|
|
/* ---- Parameter animation (keyframes) --------------------------------------
|
|
*
|
|
* Keyframes live on an input's keyframe tracks (olive::NodeKeyframe). All
|
|
* functions of this family operate on TRACK 0 only: for single-track types
|
|
* (FLOAT, INT, BOOL, RATIONAL, COMBO, STRING) that is the whole value; for
|
|
* split-track types (COLOR, VEC2/3/4) it is the FIRST component only (e.g.
|
|
* red / x) -- multi-component keyframe editing is a later milestone.
|
|
*
|
|
* Keyframe times cross the boundary as frame timestamps (int64) in the
|
|
* timebase of the project's first sequence's frame rate; projects without a
|
|
* sequence fall back to the engine's default frame rate (1001/30000 s per
|
|
* frame). The facade easing type is 0 = linear, 1 = bezier, 2 = hold (the
|
|
* engine's NodeKeyframe::Type in a different order). Bezier control points
|
|
* are the in-handle (x1, y1) and out-handle (x2, y2) in curve space; they
|
|
* are only meaningful for bezier keyframes.
|
|
*
|
|
* All mutating calls are undoable like the other editing primitives.
|
|
* Errors follow the family model (oakengine_node_last_error()).
|
|
*/
|
|
|
|
/**
|
|
* @brief 1 if the input is keyframing-enabled (Node::is_input_keyframing()).
|
|
*/
|
|
OAKENGINE_API int oakengine_node_input_is_keyframed(const OakEngineNode *self,
|
|
const char *input_id);
|
|
|
|
/**
|
|
* @brief Number of keyframes on track 0 of the input.
|
|
*/
|
|
OAKENGINE_API int oakengine_node_keyframe_count(const OakEngineNode *self,
|
|
const char *input_id);
|
|
|
|
/**
|
|
* @brief Read the keyframe at `index` (time-ordered): its time as a frame
|
|
* timestamp (`time_ts`, may be NULL) and its value mapped like
|
|
* oakengine_node_get_input() (`value`, may be NULL; split-track types get
|
|
* their first component in f[0]/num).
|
|
*/
|
|
OAKENGINE_API int oakengine_node_keyframe_at(const OakEngineNode *self,
|
|
const char *input_id, int index,
|
|
int64_t *time_ts,
|
|
oak_node_value *value);
|
|
|
|
/**
|
|
* @brief Read the easing of the keyframe at `index`: facade type into
|
|
* `type` (0 = linear, 1 = bezier, 2 = hold; may be NULL) and the bezier
|
|
* in/out control points into (x1, y1, x2, y2) -- zeroed for non-bezier
|
|
* keyframes. Any pointer may be NULL.
|
|
*/
|
|
OAKENGINE_API int oakengine_node_keyframe_get_easing(
|
|
const OakEngineNode *self, const char *input_id, int index, float *x1,
|
|
float *y1, float *x2, float *y2, int *type);
|
|
|
|
/**
|
|
* @brief Add a keyframe at `time_ts` (undoable; enables keyframing on the
|
|
* input first when needed).
|
|
*
|
|
* `value` maps like oakengine_node_set_input() and must match the input's
|
|
* declared type (for split-track types, the first component is used).
|
|
* `type` is the facade easing type; the four control floats only apply to
|
|
* bezier (type 1). Fails with OAKENGINE_E_STATE when a keyframe already
|
|
* exists at that exact time.
|
|
*/
|
|
OAKENGINE_API int oakengine_node_keyframe_add(OakEngineNode *self,
|
|
const char *input_id,
|
|
int64_t time_ts,
|
|
const oak_node_value *value,
|
|
int type, float x1, float y1,
|
|
float x2, float y2);
|
|
|
|
/**
|
|
* @brief Remove the keyframe at `time_ts` (undoable).
|
|
* OAKENGINE_E_NOT_FOUND when no keyframe exists at that exact time.
|
|
*/
|
|
OAKENGINE_API int oakengine_node_keyframe_remove(OakEngineNode *self,
|
|
const char *input_id,
|
|
int64_t time_ts);
|
|
|
|
/**
|
|
* @brief Change the easing of the keyframe at `time_ts` (undoable; set type
|
|
* plus bezier control points, mirroring the application's keyframe view
|
|
* commands). OAKENGINE_E_NOT_FOUND when no keyframe exists at that time;
|
|
* OAKENGINE_E_INVALID for an unknown easing type.
|
|
*/
|
|
OAKENGINE_API int oakengine_node_keyframe_set_easing(
|
|
OakEngineNode *self, const char *input_id, int64_t time_ts, int type,
|
|
float x1, float y1, float x2, float y2);
|
|
|
|
/**
|
|
* @brief Remove all keyframes from the input (undoable,
|
|
* olive::NodeImmediateRemoveAllKeyframesCommand). A no-op (OAKENGINE_OK)
|
|
* when the input has no keyframes.
|
|
*/
|
|
OAKENGINE_API int oakengine_node_keyframes_clear(OakEngineNode *self,
|
|
const char *input_id);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* OAKENGINE_NODE_H */
|