oak-team/oak-editor
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(node): switch oaknode to refcounted value handles, migrate consumers

Browse Source 
- all 15 OakNode* handle types become neutral by-value structs
  {ctx, addref, release, abi_version}; shared box in
  src/node/c_api/nodehandle.h with owns flag (borrowed accessors
  return non-owning boxes; graph insertion flips owns off)
- oaktimeline/oaktask/oakrender call sites and their own public
  headers migrated to value handles; identity comparisons in
  timeline/task now compare native pointers
- regressions green: oaknode 96, oaktimeline 117, oaktask 106,
  oakrender 44, oakcommon 193, oakcodec 18, oakaudio 36
This commit is contained in:
Mike-Solar
2026-08-07 17:20:42 +08:00
parent 295ea1bfe5
commit 67176281d9
87 changed files with 4499 additions and 3431 deletions
Download Patch File Download Diff File Expand all files Collapse all files
include/node/block.h
+87 -63
View File
@@ -25,6 +25,8 @@
#include <stdbool.h>
#endif
#include <stdint.h>
#include "node/error.h"
#ifdef __cplusplus
@@ -32,25 +34,40 @@ extern "C" {
#endif
/**
* @brief Opaque handle to a timeline block (olive::Block).
* @brief Reference-counted handle to a timeline block (olive::Block).
*
* Covers the whole Block family: ClipBlock, GapBlock and the concrete
* TransitionBlock subclasses. The handle IS the C++ object pointer; no
* wrapper is allocated. Concrete instances are created through the
* oaknode_block_*_create() factories below; callers never touch C++
* subclasses directly.
* TransitionBlock subclasses. The object never leaves the library that
* created it; every external reference is one of these handles.
* Semantics are shared_ptr-like: the oaknode_block_*_create() factories
* below return a handle with count 1, addref(ctx) takes another
* reference, release(ctx) drops one and the library destroys the object
* when the count reaches zero. Callers never touch C++ subclasses
* directly.
*
* Placing a block on a track (the oaknode_track_*_block() primitives)
* transfers ownership to the track; handles obtained from accessors
* (neighbours, lookups) are borrowed and never destroy the underlying
* object.
*/
typedef struct OakNodeBlock OakNodeBlock;
typedef struct OakNodeBlock {
void *ctx; /**< Opaque pointer to the reference-counted object. */
void (*addref)(void *ctx); /**< Atomically increments the count. */
void (*release)(void *ctx); /**< Decrements the count, destroys at 0. */
uint32_t abi_version; /**< OAKNODE_ABI_VERSION. */
} OakNodeBlock;
/**
* @brief Opaque handle to a track (olive::Track), see node/track.h.
* @brief Reference-counted handle to a track (olive::Track), see
* node/track.h.
*
* Re-declared here so block.h is self-contained; the typedef is identical.
*/
typedef struct OakNodeTrack OakNodeTrack;
/**
* @brief Opaque handle to a node (olive::Node), see node/node.h.
* @brief Reference-counted handle to a node (olive::Node), see
* node/node.h.
*
* Re-declared here so block.h is self-contained; the typedef is identical.
*/
@@ -79,27 +96,33 @@ enum OakNodeTransitionKind {
* a project; a block that was never placed must be released with
* oaknode_block_free().
*
* @return Block handle, or NULL on allocation failure.
* @return Block handle with reference count 1; ctx is NULL on allocation
* failure.
*/
OakNodeBlock *oaknode_block_clip_create(void);
OakNodeBlock oaknode_block_clip_create(void);
/**
* @brief Create a GapBlock. Ownership as oaknode_block_clip_create().
*
* @return Block handle, or NULL on allocation failure.
* @return Block handle with reference count 1; ctx is NULL on allocation
* failure.
*/
OakNodeBlock *oaknode_block_gap_create(void);
OakNodeBlock oaknode_block_gap_create(void);
/**
* @brief Create a concrete TransitionBlock.
*
* @param kind One of the OakNodeTransitionKind values.
* @return Block handle, or NULL on invalid kind / allocation failure.
* @return Block handle with reference count 1; ctx is NULL on invalid
* kind / allocation failure.
*/
OakNodeBlock *oaknode_block_transition_create(int kind);
OakNodeBlock oaknode_block_transition_create(int kind);
/**
* @brief Destroy a block. No-op on NULL.
* @brief Release one reference to a block handle.
*
* Destroys the block when the reference count reaches zero. NULL handle
* or NULL ctx is a no-op; clears `block->ctx` after releasing.
*
* The block must not be placed on a track or linked to other nodes; the
* caller is responsible for detaching it first.
@@ -116,32 +139,33 @@ enum OakNodeBlockKind {
/**
* @brief Concrete kind of a block (dynamic_cast query).
*/
int oaknode_block_get_kind(OakNodeBlock *block, int *out_kind);
int oaknode_block_get_kind(OakNodeBlock block, int *out_kind);
/**
* @brief Borrowed cast from a block handle to its node handle.
*
* Every Block is a Node; the result must not be freed. NULL for NULL.
* Every Block is a Node; releasing the result never destroys the block.
* Empty handle for an empty handle.
*/
OakNodeNode *oaknode_block_as_node(OakNodeBlock *block);
OakNodeNode oaknode_block_as_node(OakNodeBlock block);
/**
* @brief Borrowed cast from a node handle to a block handle.
*
* Returns NULL if the node is not a Block (or for NULL).
* Returns an empty handle if the node is not a Block (or is empty).
*/
OakNodeBlock *oaknode_block_from_node(OakNodeNode *node);
OakNodeBlock oaknode_block_from_node(OakNodeNode node);
/**
* @brief Rational getters/setters use numerator/denominator out pairs.
*
* @return OAKNODE_OK or OAKNODE_E_INVALID.
*/
int oaknode_block_get_in(OakNodeBlock *block, int *numerator, int *denominator);
int oaknode_block_set_in(OakNodeBlock *block, int numerator, int denominator);
int oaknode_block_get_out(OakNodeBlock *block, int *numerator, int *denominator);
int oaknode_block_set_out(OakNodeBlock *block, int numerator, int denominator);
int oaknode_block_get_length(OakNodeBlock *block, int *numerator,
int oaknode_block_get_in(OakNodeBlock block, int *numerator, int *denominator);
int oaknode_block_set_in(OakNodeBlock block, int numerator, int denominator);
int oaknode_block_get_out(OakNodeBlock block, int *numerator, int *denominator);
int oaknode_block_set_out(OakNodeBlock block, int numerator, int denominator);
int oaknode_block_get_length(OakNodeBlock block, int *numerator,
int *denominator);
/**
@@ -150,9 +174,9 @@ int oaknode_block_get_length(OakNodeBlock *block, int *numerator,
*
* @return OAKNODE_OK or OAKNODE_E_INVALID.
*/
int oaknode_block_set_length_and_media_out(OakNodeBlock *block, int numerator,
int oaknode_block_set_length_and_media_out(OakNodeBlock block, int numerator,
int denominator);
int oaknode_block_set_length_and_media_in(OakNodeBlock *block, int numerator,
int oaknode_block_set_length_and_media_in(OakNodeBlock block, int numerator,
int denominator);
/**
@@ -160,18 +184,18 @@ int oaknode_block_set_length_and_media_in(OakNodeBlock *block, int numerator,
*
* @return OAKNODE_OK or OAKNODE_E_INVALID.
*/
int oaknode_block_get_enabled(OakNodeBlock *block, int *enabled);
int oaknode_block_set_enabled(OakNodeBlock *block, int enabled);
int oaknode_block_get_enabled(OakNodeBlock block, int *enabled);
int oaknode_block_set_enabled(OakNodeBlock block, int enabled);
/**
* @brief Adjacency accessors. `out` receives a borrowed handle (NULL when
* @brief Adjacency accessors. `out` receives a borrowed handle (empty when
* there is no neighbour / the block is not on a track).
*
* @return OAKNODE_OK or OAKNODE_E_INVALID.
*/
int oaknode_block_get_previous(OakNodeBlock *block, OakNodeBlock **out);
int oaknode_block_get_next(OakNodeBlock *block, OakNodeBlock **out);
int oaknode_block_get_track(OakNodeBlock *block, OakNodeTrack **out);
int oaknode_block_get_previous(OakNodeBlock block, OakNodeBlock *out);
int oaknode_block_get_next(OakNodeBlock block, OakNodeBlock *out);
int oaknode_block_get_track(OakNodeBlock block, OakNodeTrack *out);
/**
* @brief Link two blocks (olive::Node::link/unlink/are_linked).
@@ -181,24 +205,24 @@ int oaknode_block_get_track(OakNodeBlock *block, OakNodeTrack **out);
* @return OAKNODE_OK, OAKNODE_E_INVALID or OAKNODE_E_FAILED (already
* linked / not linked).
*/
int oaknode_block_link(OakNodeBlock *a, OakNodeBlock *b);
int oaknode_block_unlink(OakNodeBlock *a, OakNodeBlock *b);
int oaknode_block_are_linked(OakNodeBlock *a, OakNodeBlock *b, int *linked);
int oaknode_block_link(OakNodeBlock a, OakNodeBlock b);
int oaknode_block_unlink(OakNodeBlock a, OakNodeBlock b);
int oaknode_block_are_linked(OakNodeBlock a, OakNodeBlock b, int *linked);
/**
* @brief Number of blocks linked to `block` (olive::Node::links()).
*
* @return OAKNODE_OK or OAKNODE_E_INVALID.
*/
int oaknode_block_get_link_count(OakNodeBlock *block, int *count);
int oaknode_block_get_link_count(OakNodeBlock block, int *count);
/**
* @brief Borrowed handle to the linked block at `index`.
*
* @return OAKNODE_OK, OAKNODE_E_INVALID or OAKNODE_E_NOT_FOUND.
*/
int oaknode_block_get_link_at(OakNodeBlock *block, int index,
OakNodeBlock **out);
int oaknode_block_get_link_at(OakNodeBlock block, int index,
OakNodeBlock *out);
/* ---------------------------------------------------------------- Clip */
@@ -206,41 +230,41 @@ int oaknode_block_get_link_at(OakNodeBlock *block, int index,
* @brief Media in/out accessors (olive::ClipBlock). Non-clip blocks return
* OAKNODE_E_INVALID.
*/
int oaknode_clip_get_media_in(OakNodeBlock *clip, int *numerator,
int oaknode_clip_get_media_in(OakNodeBlock clip, int *numerator,
int *denominator);
int oaknode_clip_set_media_in(OakNodeBlock *clip, int numerator,
int oaknode_clip_set_media_in(OakNodeBlock clip, int numerator,
int denominator);
/**
* @brief Playback speed factor, 1.0 = normal (olive::ClipBlock speed input).
*/
int oaknode_clip_get_speed(OakNodeBlock *clip, double *speed);
int oaknode_clip_set_speed(OakNodeBlock *clip, double speed);
int oaknode_clip_get_speed(OakNodeBlock clip, double *speed);
int oaknode_clip_set_speed(OakNodeBlock clip, double speed);
/**
* @brief Reverse playback flag.
*/
int oaknode_clip_get_reverse(OakNodeBlock *clip, int *reverse);
int oaknode_clip_set_reverse(OakNodeBlock *clip, int reverse);
int oaknode_clip_get_reverse(OakNodeBlock clip, int *reverse);
int oaknode_clip_set_reverse(OakNodeBlock clip, int reverse);
/**
* @brief Maintain-audio-pitch flag.
*/
int oaknode_clip_get_maintain_audio_pitch(OakNodeBlock *clip, int *maintain);
int oaknode_clip_set_maintain_audio_pitch(OakNodeBlock *clip, int maintain);
int oaknode_clip_get_maintain_audio_pitch(OakNodeBlock clip, int *maintain);
int oaknode_clip_set_maintain_audio_pitch(OakNodeBlock clip, int maintain);
/**
* @brief Loop mode, one of the OakLoopMode values
* (olive::ClipBlock::loop_mode/set_loop_mode).
*/
int oaknode_clip_get_loop_mode(OakNodeBlock *clip, int *loop_mode);
int oaknode_clip_set_loop_mode(OakNodeBlock *clip, int loop_mode);
int oaknode_clip_get_loop_mode(OakNodeBlock clip, int *loop_mode);
int oaknode_clip_set_loop_mode(OakNodeBlock clip, int loop_mode);
/**
* @brief Type of the track the clip sits on (OakNodeTrackType values,
* OAKNODE_TRACK_TYPE_NONE when trackless).
*/
int oaknode_clip_get_track_type(OakNodeBlock *clip, int *type);
int oaknode_clip_get_track_type(OakNodeBlock clip, int *type);
/* ----------------------------------------------------------- Transition */
@@ -248,39 +272,39 @@ int oaknode_clip_get_track_type(OakNodeBlock *clip, int *type);
* @brief Transition offsets (olive::TransitionBlock). Non-transition blocks
* return OAKNODE_E_INVALID.
*/
int oaknode_transition_get_in_offset(OakNodeBlock *transition, int *numerator,
int oaknode_transition_get_in_offset(OakNodeBlock transition, int *numerator,
int *denominator);
int oaknode_transition_get_out_offset(OakNodeBlock *transition, int *numerator,
int oaknode_transition_get_out_offset(OakNodeBlock transition, int *numerator,
int *denominator);
int oaknode_transition_get_offset_center(OakNodeBlock *transition,
int oaknode_transition_get_offset_center(OakNodeBlock transition,
int *numerator, int *denominator);
int oaknode_transition_set_offset_center(OakNodeBlock *transition,
int oaknode_transition_set_offset_center(OakNodeBlock transition,
int numerator, int denominator);
int oaknode_transition_set_offsets_and_length(OakNodeBlock *transition,
int oaknode_transition_set_offsets_and_length(OakNodeBlock transition,
int in_num, int in_den,
int out_num, int out_den);
/**
* @brief Whether both sides of the transition are connected to clips.
*/
int oaknode_transition_is_dual(OakNodeBlock *transition, int *dual);
int oaknode_transition_is_dual(OakNodeBlock transition, int *dual);
/**
* @brief Borrowed handles to the connected out/in side blocks (NULL when
* @brief Borrowed handles to the connected out/in side blocks (empty when
* unconnected).
*/
int oaknode_transition_get_connected_out_block(OakNodeBlock *transition,
OakNodeBlock **out);
int oaknode_transition_get_connected_in_block(OakNodeBlock *transition,
OakNodeBlock **out);
int oaknode_transition_get_connected_out_block(OakNodeBlock transition,
OakNodeBlock *out);
int oaknode_transition_get_connected_in_block(OakNodeBlock transition,
OakNodeBlock *out);
/**
* @brief Forward cache passthroughs from another clip
* (ClipBlock::add_cache_passthrough_from()). Used after splitting a
* clip so the new part shares the render caches.
*/
int oaknode_clip_add_cache_passthrough_from(OakNodeBlock *clip,
OakNodeBlock *other);
int oaknode_clip_add_cache_passthrough_from(OakNodeBlock clip,
OakNodeBlock other);
#ifdef __cplusplus
}
include/node/colormanager.h
+43 -36
View File
@@ -25,28 +25,31 @@
#include <stdbool.h>
#endif
#include <stdint.h>
#include "common/colortransform.h"
#include "node/error.h"
#include "node/project.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* @brief Opaque handle to a color manager (olive::ColorManager).
* @brief Reference-counted handle to a color manager
* (olive::ColorManager).
*
* Unlike node handles this one IS a wrapper allocation (ColorManager is
* not a Node); release with oaknode_colormanager_free().
* Semantics are shared_ptr-like: oaknode_colormanager_init() returns a
* handle whose object has reference count 1, addref(ctx) takes another
* reference, and release(ctx) (or oaknode_colormanager_free()) drops
* one; the library destroys the object when the count reaches zero.
*/
typedef struct OakNodeColorManager OakNodeColorManager;
/**
* @brief Opaque borrowed handle to a project (olive::Project).
*
* Owned by the project family; re-declared here so this header is
* self-contained.
*/
typedef struct OakNodeProject OakNodeProject;
typedef struct OakNodeColorManager {
void *ctx; /**< Opaque pointer to the reference-counted object. */
void (*addref)(void *ctx); /**< Atomically increments the count. */
void (*release)(void *ctx); /**< Decrements the count, destroys at 0. */
uint32_t abi_version; /**< OAKNODE_ABI_VERSION. */
} OakNodeColorManager;
/**
* @brief Create a color manager bound to `project` (borrowed).
@@ -56,12 +59,16 @@ typedef struct OakNodeProject OakNodeProject;
* oaknode_colormanager_update_config_from_filename()) before using the
* config-dependent queries.
*
* @return Manager handle, or NULL on NULL project / allocation failure.
* @return Manager handle with reference count 1 (release with
* oaknode_colormanager_free()); ctx is NULL on an empty project
* handle or allocation failure.
*/
OakNodeColorManager *oaknode_colormanager_init(OakNodeProject *project);
OakNodeColorManager oaknode_colormanager_init(OakNodeProject project);
/**
* @brief Destroy a color manager. No-op on NULL.
* @brief Release the caller's reference to the color manager and null
* out the handle. No-op on NULL or an empty handle; the object is
* destroyed when its reference count reaches zero.
*/
void oaknode_colormanager_free(OakNodeColorManager *manager);
@@ -72,7 +79,7 @@ void oaknode_colormanager_free(OakNodeColorManager *manager);
* @return OAKNODE_OK, OAKNODE_E_INVALID or OAKNODE_E_FAILED (the OCIO
* config could not be created).
*/
int oaknode_colormanager_initialize(OakNodeColorManager *manager);
int oaknode_colormanager_initialize(OakNodeColorManager manager);
/**
* @brief (Re)build the process-wide default OCIO config
@@ -87,9 +94,9 @@ int oaknode_colormanager_set_up_default_config(void);
* returns the required buffer size in bytes including NUL; pass
* buf == NULL or a too-small buffer to query the size.
*/
int oaknode_colormanager_get_config_filename(OakNodeColorManager *manager,
int oaknode_colormanager_get_config_filename(OakNodeColorManager manager,
char *buf, int buf_size);
int oaknode_colormanager_set_config_filename(OakNodeColorManager *manager,
int oaknode_colormanager_set_config_filename(OakNodeColorManager manager,
const char *filename);
/**
@@ -98,21 +105,21 @@ int oaknode_colormanager_set_config_filename(OakNodeColorManager *manager,
* olive::ColorManager::update_config_from_filename().
*/
int oaknode_colormanager_update_config_from_filename(
OakNodeColorManager *manager);
OakNodeColorManager manager);
/**
* @brief Default input colorspace. Two-stage string accessor.
*/
int oaknode_colormanager_get_default_input_color_space(
OakNodeColorManager *manager, char *buf, int buf_size);
OakNodeColorManager manager, char *buf, int buf_size);
int oaknode_colormanager_set_default_input_color_space(
OakNodeColorManager *manager, const char *colorspace);
OakNodeColorManager manager, const char *colorspace);
/**
* @brief Reference (working) colorspace. Two-stage string getter.
*/
int oaknode_colormanager_get_reference_color_space(
OakNodeColorManager *manager, char *buf, int buf_size);
OakNodeColorManager manager, char *buf, int buf_size);
/**
* @brief Return `colorspace` when the active config lists it, otherwise the
@@ -120,7 +127,7 @@ int oaknode_colormanager_get_reference_color_space(
* (OAKNODE_E_STATE when none is loaded).
*/
int oaknode_colormanager_get_compliant_color_space(
OakNodeColorManager *manager, const char *colorspace, char *buf,
OakNodeColorManager manager, const char *colorspace, char *buf,
int buf_size);
/**
@@ -130,7 +137,7 @@ int oaknode_colormanager_get_compliant_color_space(
* (OAKNODE_E_STATE when none is loaded).
*/
int oaknode_colormanager_get_colorspace_for_ffmpeg_tags(
OakNodeColorManager *manager, int primaries, int trc, char *buf,
OakNodeColorManager manager, int primaries, int trc, char *buf,
int buf_size);
/**
@@ -138,27 +145,27 @@ int oaknode_colormanager_get_colorspace_for_ffmpeg_tags(
* All require a loaded config (OAKNODE_E_STATE otherwise); index out of
* range yields OAKNODE_E_NOT_FOUND.
*/
int oaknode_colormanager_get_display_count(OakNodeColorManager *manager,
int oaknode_colormanager_get_display_count(OakNodeColorManager manager,
int *count);
int oaknode_colormanager_get_display_at(OakNodeColorManager *manager,
int oaknode_colormanager_get_display_at(OakNodeColorManager manager,
int index, char *buf, int buf_size);
int oaknode_colormanager_get_default_display(OakNodeColorManager *manager,
int oaknode_colormanager_get_default_display(OakNodeColorManager manager,
char *buf, int buf_size);
int oaknode_colormanager_get_view_count(OakNodeColorManager *manager,
int oaknode_colormanager_get_view_count(OakNodeColorManager manager,
const char *display, int *count);
int oaknode_colormanager_get_view_at(OakNodeColorManager *manager,
int oaknode_colormanager_get_view_at(OakNodeColorManager manager,
const char *display, int index, char *buf,
int buf_size);
int oaknode_colormanager_get_default_view(OakNodeColorManager *manager,
int oaknode_colormanager_get_default_view(OakNodeColorManager manager,
const char *display, char *buf,
int buf_size);
int oaknode_colormanager_get_look_count(OakNodeColorManager *manager,
int oaknode_colormanager_get_look_count(OakNodeColorManager manager,
int *count);
int oaknode_colormanager_get_look_at(OakNodeColorManager *manager, int index,
int oaknode_colormanager_get_look_at(OakNodeColorManager manager, int index,
char *buf, int buf_size);
int oaknode_colormanager_get_colorspace_count(OakNodeColorManager *manager,
int oaknode_colormanager_get_colorspace_count(OakNodeColorManager manager,
int *count);
int oaknode_colormanager_get_colorspace_at(OakNodeColorManager *manager,
int oaknode_colormanager_get_colorspace_at(OakNodeColorManager manager,
int index, char *buf,
int buf_size);
@@ -166,7 +173,7 @@ int oaknode_colormanager_get_colorspace_at(OakNodeColorManager *manager,
* @brief Default luma coefficients of the active config into rgb[3].
* Requires a loaded config (OAKNODE_E_STATE otherwise).
*/
int oaknode_colormanager_get_default_luma_coefs(OakNodeColorManager *manager,
int oaknode_colormanager_get_default_luma_coefs(OakNodeColorManager manager,
double rgb[3]);
/**
@@ -179,7 +186,7 @@ int oaknode_colormanager_get_default_luma_coefs(OakNodeColorManager *manager,
* loaded config (OAKNODE_E_STATE otherwise).
*/
int oaknode_colormanager_get_compliant_color_transform(
OakNodeColorManager *manager, OakColorTransform transform,
OakNodeColorManager manager, OakColorTransform transform,
int force_display, OakColorTransform *out);
#ifdef __cplusplus
include/node/error.h
+10
View File
@@ -29,6 +29,16 @@
* failure. String getters return the required buffer size in bytes
* (including the terminating NUL) as a non-negative value instead.
*/
/**
* @brief Current ABI version stamped into every oaknode handle.
*
* Bump whenever a handle layout or the semantics of any exported
* function change incompatibly. Consumers should compare a handle's
* abi_version field against the value they were compiled with before
* dereferencing ctx.
*/
#define OAKNODE_ABI_VERSION 1
#define OAKNODE_OK 0 /**< Success. */
#define OAKNODE_E_INVALID (-1) /**< NULL handle or invalid argument. */
#define OAKNODE_E_STATE (-2) /**< Call not valid in the current state. */
include/node/factory.h
+12 -8
View File
@@ -34,9 +34,11 @@ extern "C" {
* internal node-type library.
*
* The library must be populated with oaknode_factory_initialize() before
* any other call; oaknode_factory_destroy() releases it. Prototype nodes
* from oaknode_factory_node_at() are owned by the library: read-only
* metadata queries only, never free them or add them to a graph.
* any other call; oaknode_factory_destroy() releases it. The factory is
* a process-wide singleton (static olive::NodeFactory), so there is no
* OakNodeFactory handle type. Prototype nodes from
* oaknode_factory_node_at() are owned by the library: read-only metadata
* queries only, never add them to a graph.
*/
/**
@@ -77,17 +79,19 @@ int oaknode_factory_name_from_id(const char *type_id, char *buf,
/**
* @brief Create a node of `type_id` WITHOUT adding it to any graph
* (NodeFactory::create_from_id()). The caller owns the returned node
* and must release it with oaknode_node_free() while it is still
* orphaned. Returns NULL when the id is unknown or not initialized.
* (reference count 1) and must release it with oaknode_node_free() while
* it is still orphaned. ctx is NULL when the id is unknown or not
* initialized.
*/
OakNodeNode *oaknode_factory_create_from_id(const char *type_id);
OakNodeNode oaknode_factory_create_from_id(const char *type_id);
/**
* @brief Borrow the prototype node at `index` in the library.
* @brief Borrow the prototype node at `index` in the library (non-owning
* handle written to `out_node`; release it with oaknode_node_free()).
* OAKNODE_E_NOT_FOUND for an out-of-range index, OAKNODE_E_STATE when
* not initialized.
*/
int oaknode_factory_node_at(int index, OakNodeNode **out_node);
int oaknode_factory_node_at(int index, OakNodeNode *out_node);
#ifdef __cplusplus
}
include/node/folder.h
+58 -25
View File
@@ -21,6 +21,8 @@
#ifndef OAK_EDITOR_NODE_FOLDER_H
#define OAK_EDITOR_NODE_FOLDER_H
#include <stdint.h>
#include "node/error.h"
#include "undo/undocommand.h"
#include "node/project.h"
@@ -42,50 +44,76 @@ extern "C" {
* facade layer's job, not this layer's.
*/
/**
* @brief Reference-counted handle to a folder node (olive::Folder).
*
* Semantics are shared_ptr-like (see OakNodeProject): addref(ctx) takes a
* reference, release(ctx) drops one. Folder handles handed out by this API
* are borrowed views into the owning project's graph: releasing them only
* releases the handle itself, never the folder.
*/
typedef struct OakNodeFolder {
void *ctx; /**< Opaque pointer to the reference-counted object. */
void (*addref)(void *ctx); /**< Atomically increments the count. */
void (*release)(void *ctx); /**< Decrements the count, destroys at 0. */
uint32_t abi_version; /**< OAKNODE_ABI_VERSION. */
} OakNodeFolder;
/**
* @brief Create a folder node owned by `project`.
*
* The folder is added to the project's graph (Project::add_node()) but is
* NOT attached under any parent folder; use oaknode_folder_add_child() to
* place it. The handle is borrowed: the project owns the folder.
* place it. The returned handle is borrowed: the project owns the folder,
* so releasing the handle only releases the handle itself.
*
* @return Folder handle, or NULL on failure.
* @return Folder handle; ctx is NULL on failure.
*/
OakNodeFolder *oaknode_folder_create(OakNodeProject *project);
OakNodeFolder oaknode_folder_create(OakNodeProject project);
/**
* @brief Number of direct item children (Folder::item_child_count()).
* Negative OAKNODE_E_* code on NULL.
* Negative OAKNODE_E_* code on an empty handle.
*/
int oaknode_folder_child_count(const OakNodeFolder *folder);
int oaknode_folder_child_count(OakNodeFolder folder);
/**
* @brief Borrowed node handle of the item child at `index`
* (Folder::item_child()). NULL when out of range.
* (Folder::item_child()).
*
* The returned handle only releases the handle itself. Empty handle
* (ctx == NULL) when out of range.
*/
OakNodeNode *oaknode_folder_child_at(const OakNodeFolder *folder, int index);
OakNodeNode oaknode_folder_child_at(OakNodeFolder folder, int index);
/**
* @brief Add `child` as a direct item child of `folder` (live, non-undoable;
* executes FolderAddChild::redo()).
*
* After a successful call the graph owns `child`: releasing the child
* handle only releases the handle itself.
*
* @return OAKNODE_OK, OAKNODE_E_STATE if `child` already belongs to a
* folder, or another negative OAKNODE_E_* error code.
*/
int oaknode_folder_add_child(OakNodeFolder *folder, OakNodeNode *child);
int oaknode_folder_add_child(OakNodeFolder folder, OakNodeNode child);
/**
* @brief Borrowed cast from a folder handle to its node handle.
* NULL for NULL.
*
* The returned handle only releases the handle itself. Empty handle for an
* empty handle.
*/
OakNodeNode *oaknode_folder_as_node(OakNodeFolder *folder);
OakNodeNode oaknode_folder_as_node(OakNodeFolder folder);
/**
* @brief Create an undoable FolderAddChild command. Owned; free with
* oakundo_command_free().
* @brief Create an undoable FolderAddChild command.
*
* @return Command handle with reference count 1 (release with
* oakundo_command_free()); ctx is NULL on failure.
*/
OakUndoCommand oaknode_command_create_folder_add_child(
OakNodeFolder *folder, OakNodeNode *child);
OakNodeFolder folder, OakNodeNode child);
/**
* @brief Remove `child` from `folder` without deleting it (live,
@@ -94,41 +122,46 @@ OakUndoCommand oaknode_command_create_folder_add_child(
* @return OAKNODE_OK, OAKNODE_E_NOT_FOUND if `child` is not a direct child,
* or another negative OAKNODE_E_* error code.
*/
int oaknode_folder_remove_child(OakNodeFolder *folder, OakNodeNode *child);
int oaknode_folder_remove_child(OakNodeFolder folder, OakNodeNode child);
/**
* @brief Move several nodes into `dest_folder` (live, non-undoable).
*
* Each node is removed from its current folder (if any) and appended to
* `dest_folder`. Nodes already directly inside `dest_folder` are skipped.
* `dest_folder`; the graph assumes the lifetime of every moved node. Nodes
* already directly inside `dest_folder` are skipped.
*
* @return OAKNODE_OK or a negative OAKNODE_E_* error code.
*/
int oaknode_folder_move_children(OakNodeNode *const *nodes, int count,
OakNodeFolder *dest_folder);
int oaknode_folder_move_children(const OakNodeNode *nodes, int count,
OakNodeFolder dest_folder);
/**
* @brief 1 if `folder` recursively contains `child`, 0 otherwise
* (Folder::has_child_recursive()). Negative OAKNODE_E_* code on NULL args.
* (Folder::has_child_recursive()). Negative OAKNODE_E_* code on empty
* handles.
*/
int oaknode_folder_has_child_recursive(const OakNodeFolder *folder,
const OakNodeNode *child);
int oaknode_folder_has_child_recursive(OakNodeFolder folder,
OakNodeNode child);
/**
* @brief Index of `child` in `folder`'s direct children
* (Folder::index_of_child()).
*
* @return The index, OAKNODE_E_NOT_FOUND if not a direct child, or
* OAKNODE_E_INVALID on NULL args.
* OAKNODE_E_INVALID on empty handles.
*/
int oaknode_folder_index_of_child(const OakNodeFolder *folder,
const OakNodeNode *child);
int oaknode_folder_index_of_child(OakNodeFolder folder,
OakNodeNode child);
/**
* @brief Borrowed handle of the folder a node currently belongs to
* (Node::folder()), or NULL if the node is not in any folder.
* (Node::folder()).
*
* The returned handle only releases the handle itself. Empty handle
* (ctx == NULL) if the node is not in any folder.
*/
OakNodeFolder *oaknode_folder_parent_of(const OakNodeNode *node);
OakNodeFolder oaknode_folder_parent_of(OakNodeNode node);
#ifdef __cplusplus
}
include/node/footage.h
+52 -36
View File
@@ -50,26 +50,41 @@ extern "C" {
*/
/**
* @brief Opaque footage handle. Borrowed from the owning project.
* @brief Reference-counted handle to a footage node (olive::Footage).
*
* Semantics are shared_ptr-like (see OakNodeProject): addref(ctx) takes a
* reference, release(ctx) drops one. Footage handles handed out by this
* API are borrowed views into the owning project's graph: releasing them
* only releases the handle itself, never the footage.
*/
typedef struct OakNodeFootage OakNodeFootage;
typedef struct OakNodeFootage {
void *ctx; /**< Opaque pointer to the reference-counted object. */
void (*addref)(void *ctx); /**< Atomically increments the count. */
void (*release)(void *ctx); /**< Decrements the count, destroys at 0. */
uint32_t abi_version; /**< OAKNODE_ABI_VERSION. */
} OakNodeFootage;
/**
* @brief Create a footage node owned by `project` (added to the project's
* graph, not attached to any folder).
*
* The returned handle is borrowed: the project owns the footage, so
* releasing the handle only releases the handle itself.
*
* @param filename Initial media path, may be NULL/empty.
*
* @return Footage handle, or NULL on failure.
* @return Footage handle; ctx is NULL on failure.
*/
OakNodeFootage *oaknode_footage_create(OakNodeProject *project,
const char *filename);
OakNodeFootage oaknode_footage_create(OakNodeProject project,
const char *filename);
/**
* @brief Borrowed cast from a footage handle to its node handle.
* NULL for NULL.
*
* The returned handle only releases the handle itself. Empty handle for an
* empty handle.
*/
OakNodeNode *oaknode_footage_as_node(OakNodeFootage *footage);
OakNodeNode oaknode_footage_as_node(OakNodeFootage footage);
/**
* @brief Current media path (Footage::filename()). Two-stage string getter.
@@ -77,7 +92,7 @@ OakNodeNode *oaknode_footage_as_node(OakNodeFootage *footage);
* @return Required buffer size in bytes including the NUL, or a negative
* OAKNODE_E_* error code.
*/
int oaknode_footage_filename(const OakNodeFootage *footage, char *buf,
int oaknode_footage_filename(OakNodeFootage footage, char *buf,
int buf_size);
/**
@@ -86,13 +101,14 @@ int oaknode_footage_filename(const OakNodeFootage *footage, char *buf,
*
* @return OAKNODE_OK or a negative OAKNODE_E_* error code.
*/
int oaknode_footage_set_filename(OakNodeFootage *footage, const char *filename);
int oaknode_footage_set_filename(OakNodeFootage footage, const char *filename);
/**
* @brief 1 if the footage was successfully probed and is ready for use
* (Footage::is_valid()), 0 otherwise. Negative OAKNODE_E_* code on NULL.
* (Footage::is_valid()), 0 otherwise. Negative OAKNODE_E_* code on an
* empty handle.
*/
int oaknode_footage_is_valid(const OakNodeFootage *footage);
int oaknode_footage_is_valid(OakNodeFootage footage);
/**
* @brief Last-modified timestamp of the media file in milliseconds since the
@@ -102,7 +118,7 @@ int oaknode_footage_is_valid(const OakNodeFootage *footage);
*
* @return OAKNODE_OK or a negative OAKNODE_E_* error code.
*/
int oaknode_footage_timestamp(const OakNodeFootage *footage,
int oaknode_footage_timestamp(OakNodeFootage footage,
int64_t *out_timestamp);
/**
@@ -110,38 +126,38 @@ int oaknode_footage_timestamp(const OakNodeFootage *footage,
*
* @return OAKNODE_OK or a negative OAKNODE_E_* error code.
*/
int oaknode_footage_set_timestamp(OakNodeFootage *footage, int64_t timestamp);
int oaknode_footage_set_timestamp(OakNodeFootage footage, int64_t timestamp);
/**
* @brief Decoder ID recorded when the footage was probed
* (Footage::decoder()). Two-stage string getter.
*/
int oaknode_footage_decoder(const OakNodeFootage *footage, char *buf,
int oaknode_footage_decoder(OakNodeFootage footage, char *buf,
int buf_size);
/**
* @brief Total number of streams (Footage::get_total_stream_count()).
* Negative OAKNODE_E_* code on NULL.
* Negative OAKNODE_E_* code on an empty handle.
*/
int oaknode_footage_total_stream_count(const OakNodeFootage *footage);
int oaknode_footage_total_stream_count(OakNodeFootage footage);
/**
* @brief Number of video streams (ViewerOutput::get_video_stream_count()).
* Negative OAKNODE_E_* code on NULL.
* Negative OAKNODE_E_* code on an empty handle.
*/
int oaknode_footage_video_stream_count(const OakNodeFootage *footage);
int oaknode_footage_video_stream_count(OakNodeFootage footage);
/**
* @brief Number of audio streams (ViewerOutput::get_audio_stream_count()).
* Negative OAKNODE_E_* code on NULL.
* Negative OAKNODE_E_* code on an empty handle.
*/
int oaknode_footage_audio_stream_count(const OakNodeFootage *footage);
int oaknode_footage_audio_stream_count(OakNodeFootage footage);
/**
* @brief Number of subtitle streams (ViewerOutput::get_subtitle_stream_count()).
* Negative OAKNODE_E_* code on NULL.
* Negative OAKNODE_E_* code on an empty handle.
*/
int oaknode_footage_subtitle_stream_count(const OakNodeFootage *footage);
int oaknode_footage_subtitle_stream_count(OakNodeFootage footage);
/**
* @brief Footage duration as a rational number of seconds
@@ -152,34 +168,34 @@ int oaknode_footage_subtitle_stream_count(const OakNodeFootage *footage);
*
* @return OAKNODE_OK or a negative OAKNODE_E_* error code.
*/
int oaknode_footage_duration(const OakNodeFootage *footage,
int *out_numerator, int *out_denominator);
int oaknode_footage_duration(OakNodeFootage footage, int *out_numerator,
int *out_denominator);
/**
* @brief 1 if proxy playback is enabled (Footage::proxy_enabled()).
* Negative OAKNODE_E_* code on NULL.
* Negative OAKNODE_E_* code on an empty handle.
*/
int oaknode_footage_proxy_enabled(const OakNodeFootage *footage);
int oaknode_footage_proxy_enabled(OakNodeFootage footage);
/**
* @brief Enable/disable proxy playback (Footage::set_proxy_enabled()).
*
* @return OAKNODE_OK or a negative OAKNODE_E_* error code.
*/
int oaknode_footage_set_proxy_enabled(OakNodeFootage *footage, int enabled);
int oaknode_footage_set_proxy_enabled(OakNodeFootage footage, int enabled);
/**
* @brief Proxy file path, or "" when none (Footage::proxy_path()).
* Two-stage string getter.
*/
int oaknode_footage_proxy_path(const OakNodeFootage *footage, char *buf,
int oaknode_footage_proxy_path(OakNodeFootage footage, char *buf,
int buf_size);
/**
* @brief Proxy state enum value (Footage::proxy_state():
* ProxyManager::ProxyState). Negative OAKNODE_E_* code on NULL.
* ProxyManager::ProxyState). Negative OAKNODE_E_* code on an empty handle.
*/
int oaknode_footage_proxy_state(const OakNodeFootage *footage);
int oaknode_footage_proxy_state(OakNodeFootage footage);
/**
* @brief Set all proxy fields at once (Footage::set_proxy()).
@@ -192,7 +208,7 @@ int oaknode_footage_proxy_state(const OakNodeFootage *footage);
*
* @return OAKNODE_OK or a negative OAKNODE_E_* error code.
*/
int oaknode_footage_set_proxy(OakNodeFootage *footage, const char *path,
int oaknode_footage_set_proxy(OakNodeFootage footage, const char *path,
int state, int video_stream_index,
int preset_version, int enabled);
@@ -201,7 +217,7 @@ int oaknode_footage_set_proxy(OakNodeFootage *footage, const char *path,
*
* @return OAKNODE_OK or a negative OAKNODE_E_* error code.
*/
int oaknode_footage_clear_proxy(OakNodeFootage *footage);
int oaknode_footage_clear_proxy(OakNodeFootage footage);
/**
* @brief Video stream parameters as an oakcommon video-params handle
@@ -209,20 +225,20 @@ int oaknode_footage_clear_proxy(OakNodeFootage *footage);
* reference count 1 (release with oakcommon_videoparams_free()).
* OAKNODE_E_NOT_FOUND for an out-of-range index.
*/
int oaknode_footage_get_video_params(OakNodeFootage *footage, int index,
int oaknode_footage_get_video_params(OakNodeFootage footage, int index,
OakVideoParams *out);
/**
* @brief Set a video stream's parameters from an oakcommon handle
* (ViewerOutput::set_video_params()).
*/
int oaknode_footage_set_video_params(OakNodeFootage *footage, int index,
int oaknode_footage_set_video_params(OakNodeFootage footage, int index,
const OakVideoParams *params);
/**
* @brief Video length as a rational pair (ViewerOutput::get_video_length()).
*/
int oaknode_footage_get_video_length(OakNodeFootage *footage,
int oaknode_footage_get_video_length(OakNodeFootage footage,
int64_t *out_num, int64_t *out_den);
/**
@@ -230,7 +246,7 @@ int oaknode_footage_get_video_length(OakNodeFootage *footage,
* (Footage::set_cancel_pointer()). `atom` may be an empty OakCancelAtom
* (ctx == NULL) to clear.
*/
int oaknode_footage_set_cancel_atom(OakNodeFootage *footage,
int oaknode_footage_set_cancel_atom(OakNodeFootage footage,
OakCancelAtom atom);
#ifdef __cplusplus
include/node/group.h
+60 -37
View File
@@ -21,6 +21,8 @@
#ifndef OAK_EDITOR_NODE_GROUP_H
#define OAK_EDITOR_NODE_GROUP_H
#include <stdint.h>
#include "node/error.h"
#include "node/node.h"
#include "undo/undocommand.h"
@@ -34,33 +36,51 @@ extern "C" {
* @brief C ABI for olive::NodeGroup (src/node/src/group/group.h):
* input passthrough management and input resolution.
*
* An OakNodeGroup is a reinterpreted olive::NodeGroup (a Node subclass);
* group handles borrow the same lifetime rules as OakNodeNode.
* An OakNodeGroup wraps an olive::NodeGroup (a Node subclass); group
* handles share the reference-counted lifetime rules of OakNodeNode.
*/
/**
* @brief Opaque group handle (olive::NodeGroup).
* @brief Reference-counted handle to a node group (olive::NodeGroup).
*
* The object never leaves the library that created it; every external
* reference is one of these handles. Semantics are shared_ptr-like:
* oaknode_group_create() returns a handle with count 1, addref(ctx)
* takes another reference, release(ctx) drops one and the library
* destroys the object when the count reaches zero. Handles returned by
* oaknode_group_cast() are borrowed views of a node: releasing them
* never destroys the underlying group.
*/
typedef struct OakNodeGroup OakNodeGroup;
typedef struct OakNodeGroup {
void *ctx; /**< Opaque pointer to the reference-counted object. */
void (*addref)(void *ctx); /**< Atomically increments the count. */
void (*release)(void *ctx); /**< Decrements the count, destroys at 0. */
uint32_t abi_version; /**< OAKNODE_ABI_VERSION. */
} OakNodeGroup;
/**
* @brief Create a standalone NodeGroup (owned; release with
* oaknode_node_free() on the OakNodeNode view or oaknode_group_free()
* while still orphaned).
* oaknode_group_free() while still orphaned).
*
* @return Group handle, or NULL on allocation failure.
* @return Group handle with count 1; ctx is NULL on allocation failure.
*/
OakNodeGroup *oaknode_group_create(void);
OakNodeGroup oaknode_group_create(void);
/**
* @brief Borrow a group view of a node, or NULL when the node is not a
* NodeGroup (dynamic_cast).
* @brief Borrow a group view of a node (dynamic_cast). The returned
* handle is non-owning; release it with oaknode_group_free().
*
* @return Borrowed group handle; ctx is NULL when the node is not a
* NodeGroup.
*/
OakNodeGroup *oaknode_group_cast(OakNodeNode *node);
OakNodeGroup oaknode_group_cast(OakNodeNode node);
/**
* @brief Destroy an OWNED group (same rules as oaknode_node_free()).
* NULL is a no-op.
* @brief Release one reference to a group handle.
*
* Convenience wrapper around handle.release(handle.ctx): destroys the
* group when the count reaches zero and the handle owns it. NULL handle
* or NULL ctx is a no-op; clears `group->ctx` after releasing.
*/
void oaknode_group_free(OakNodeGroup *group);
@@ -72,8 +92,8 @@ void oaknode_group_free(OakNodeGroup *group);
* @return Required buffer size in bytes including the terminating NUL
* (non-negative), or a negative OAKNODE_E_* error code.
*/
int oaknode_group_add_input_passthrough(OakNodeGroup *group,
OakNodeNode *node,
int oaknode_group_add_input_passthrough(OakNodeGroup group,
OakNodeNode node,
const char *input_id, int element,
char *buf, int buf_size);
@@ -84,8 +104,8 @@ int oaknode_group_add_input_passthrough(OakNodeGroup *group,
*
* @return OAKNODE_OK or a negative OAKNODE_E_* error code.
*/
int oaknode_group_add_input_passthrough_undoable(OakNodeGroup *group,
OakNodeNode *node,
int oaknode_group_add_input_passthrough_undoable(OakNodeGroup group,
OakNodeNode node,
const char *input_id,
int element,
OakUndoCommand *out_command);
@@ -94,66 +114,69 @@ int oaknode_group_add_input_passthrough_undoable(OakNodeGroup *group,
* @brief Remove the passthrough for (`node`, `input_id`, `element`)
* (live). OAKNODE_E_NOT_FOUND when no such passthrough exists.
*/
int oaknode_group_remove_input_passthrough(OakNodeGroup *group,
OakNodeNode *node,
int oaknode_group_remove_input_passthrough(OakNodeGroup group,
OakNodeNode node,
const char *input_id, int element);
/**
* @brief Number of registered input passthroughs.
*/
int oaknode_group_passthrough_count(const OakNodeGroup *group, int *out_count);
int oaknode_group_passthrough_count(OakNodeGroup group, int *out_count);
/**
* @brief The passthrough id at `index`. Two-stage getter;
* OAKNODE_E_NOT_FOUND for an out-of-range index.
*/
int oaknode_group_passthrough_id_at(const OakNodeGroup *group, int index,
int oaknode_group_passthrough_id_at(OakNodeGroup group, int index,
char *buf, int buf_size);
/**
* @brief The inner input behind passthrough `index`: node (borrowed
* handle), input id (two-stage string) and element.
* handle written to `out_node` when non-NULL; release it with
* oaknode_node_free()), input id (two-stage string) and element.
* OAKNODE_E_NOT_FOUND for an out-of-range index.
*/
int oaknode_group_passthrough_input_at(const OakNodeGroup *group, int index,
OakNodeNode **out_node, char *buf,
int oaknode_group_passthrough_input_at(OakNodeGroup group, int index,
OakNodeNode *out_node, char *buf,
int buf_size, int *out_element);
/**
* @brief The output passthrough node (borrowed handle), or NULL when
* @brief The output passthrough node (borrowed handle written to
* `out_node`; release it with oaknode_node_free()), an empty handle when
* unset. OAKNODE_OK is returned either way.
*/
int oaknode_group_get_output_passthrough(const OakNodeGroup *group,
OakNodeNode **out_node);
int oaknode_group_get_output_passthrough(OakNodeGroup group,
OakNodeNode *out_node);
/**
* @brief Set the output passthrough node directly (live).
* @brief Set the output passthrough node directly (live). `node` may be
* an empty handle to clear the passthrough.
*/
int oaknode_group_set_output_passthrough(OakNodeGroup *group,
OakNodeNode *node);
int oaknode_group_set_output_passthrough(OakNodeGroup group,
OakNodeNode node);
/**
* @brief Create a set-output-passthrough command
* (olive::NodeGroupSetOutputPassthrough).
*/
int oaknode_group_set_output_passthrough_undoable(
OakNodeGroup *group, OakNodeNode *node, OakUndoCommand *out_command);
OakNodeGroup group, OakNodeNode node, OakUndoCommand *out_command);
/**
* @brief Resolve an input through group passthroughs
* (NodeGroup::resolve_input()): follows a group's passthrough id to the
* inner node input. Non-group inputs resolve to themselves.
*
* `out_node` (may be NULL) receives a borrowed handle; the resolved input
* id uses the two-stage string convention; `out_element` (may be NULL)
* receives the element. OAKNODE_E_NOT_FOUND when the input does not
* resolve to a valid target.
* `out_node` (may be NULL) receives a borrowed handle (release it with
* oaknode_node_free()); the resolved input id uses the two-stage string
* convention; `out_element` (may be NULL) receives the element.
* OAKNODE_E_NOT_FOUND when the input does not resolve to a valid target.
*
* @return Required buffer size in bytes including the terminating NUL
* (non-negative), or a negative OAKNODE_E_* error code.
*/
int oaknode_group_resolve_input(OakNodeNode *node, const char *input_id,
int element, OakNodeNode **out_node,
int oaknode_group_resolve_input(OakNodeNode node, const char *input_id,
int element, OakNodeNode *out_node,
char *buf, int buf_size, int *out_element);
#ifdef __cplusplus
include/node/keyframe.h
+54 -38
View File
@@ -35,10 +35,10 @@ extern "C" {
* @file keyframe.h
* @brief C ABI for olive::NodeKeyframe (src/node/src/keyframe.h).
*
* An OakNodeKeyframe is a reinterpreted olive::NodeKeyframe. Handles
* created by oaknode_keyframe_create() are owned and must be released
* with oaknode_keyframe_free(); keyframes attached to a node input's
* track are owned by the node.
* An OakNodeKeyframe wraps an olive::NodeKeyframe. Handles created by
* oaknode_keyframe_create() are owned and must be released with
* oaknode_keyframe_free(); keyframes attached to a node input's track
* are owned by the node.
*
* Every setter comes in a live variant and an undoable variant (suffix
* _undoable) returning an owned, un-executed OakUndoCommand.
@@ -63,9 +63,20 @@ typedef enum oaknode_keyframe_bezier {
} oaknode_keyframe_bezier;
/**
* @brief Opaque keyframe handle (olive::NodeKeyframe).
* @brief Reference-counted handle to a keyframe (olive::NodeKeyframe).
*
* The object never leaves the library that created it; every external
* reference is one of these handles. Semantics are shared_ptr-like:
* oaknode_keyframe_create() returns a handle with count 1, addref(ctx)
* takes another reference, release(ctx) drops one and the library
* destroys the object when the count reaches zero.
*/
typedef struct OakNodeKeyframe OakNodeKeyframe;
typedef struct OakNodeKeyframe {
void *ctx; /**< Opaque pointer to the reference-counted object. */
void (*addref)(void *ctx); /**< Atomically increments the count. */
void (*release)(void *ctx); /**< Decrements the count, destroys at 0. */
uint32_t abi_version; /**< OAKNODE_ABI_VERSION. */
} OakNodeKeyframe;
/**
* @brief Create a standalone keyframe (owned; release with
@@ -73,20 +84,24 @@ typedef struct OakNodeKeyframe OakNodeKeyframe;
*
* `value` may be NULL (null variant); OAKNODE_VALUE_STRING is rejected
* (use oaknode_keyframe_set_value_string() after creation). `type` is an
* oaknode_keyframe_type. `parent_or_null` may be NULL.
* oaknode_keyframe_type. `parent_or_null` may be an empty handle.
*
* @return Keyframe handle, or NULL on invalid argument or allocation
* failure.
* @return Keyframe handle with count 1; ctx is NULL on invalid argument
* or allocation failure.
*/
OakNodeKeyframe *oaknode_keyframe_create(int64_t time_num, int64_t time_den,
const oaknode_value *value, int type,
int track, int element,
const char *input_id,
OakNodeNode *parent_or_null);
OakNodeKeyframe oaknode_keyframe_create(int64_t time_num, int64_t time_den,
const oaknode_value *value, int type,
int track, int element,
const char *input_id,
OakNodeNode parent_or_null);
/**
* @brief Destroy an OWNED keyframe. NULL is a no-op. Never free a
* keyframe that is attached to a node's track.
* @brief Release one reference to a keyframe handle.
*
* Convenience wrapper around handle.release(handle.ctx): destroys the
* keyframe when the count reaches zero and the handle owns it. NULL
* handle or NULL ctx is a no-op; clears `keyframe->ctx` after releasing.
* Never free a keyframe that is attached to a node's track.
*/
void oaknode_keyframe_free(OakNodeKeyframe *keyframe);
@@ -95,19 +110,19 @@ void oaknode_keyframe_free(OakNodeKeyframe *keyframe);
*
* @return OAKNODE_OK or a negative OAKNODE_E_* error code.
*/
int oaknode_keyframe_get_time(const OakNodeKeyframe *keyframe,
int oaknode_keyframe_get_time(OakNodeKeyframe keyframe,
int64_t *out_num, int64_t *out_den);
/**
* @brief Set the keyframe's time directly (live).
*/
int oaknode_keyframe_set_time(OakNodeKeyframe *keyframe, int64_t time_num,
int oaknode_keyframe_set_time(OakNodeKeyframe keyframe, int64_t time_num,
int64_t time_den);
/**
* @brief Create a set-time command (olive::NodeParamSetKeyframeTimeCommand).
*/
int oaknode_keyframe_set_time_undoable(OakNodeKeyframe *keyframe,
int oaknode_keyframe_set_time_undoable(OakNodeKeyframe keyframe,
int64_t time_num, int64_t time_den,
OakUndoCommand *out_command);
@@ -115,7 +130,7 @@ int oaknode_keyframe_set_time_undoable(OakNodeKeyframe *keyframe,
* @brief Read the keyframe's value mapped into `out`. Values without a
* POD representation fail with OAKNODE_E_FAILED.
*/
int oaknode_keyframe_get_value(const OakNodeKeyframe *keyframe,
int oaknode_keyframe_get_value(OakNodeKeyframe keyframe,
oaknode_value *out);
/**
@@ -123,14 +138,14 @@ int oaknode_keyframe_get_value(const OakNodeKeyframe *keyframe,
* OAKNODE_VALUE_STRING is rejected (use
* oaknode_keyframe_set_value_string()).
*/
int oaknode_keyframe_set_value(OakNodeKeyframe *keyframe,
int oaknode_keyframe_set_value(OakNodeKeyframe keyframe,
const oaknode_value *v);
/**
* @brief Create a set-value command
* (olive::NodeParamSetKeyframeValueCommand).
*/
int oaknode_keyframe_set_value_undoable(OakNodeKeyframe *keyframe,
int oaknode_keyframe_set_value_undoable(OakNodeKeyframe keyframe,
const oaknode_value *v,
OakUndoCommand *out_command);
@@ -140,84 +155,85 @@ int oaknode_keyframe_set_value_undoable(OakNodeKeyframe *keyframe,
* @return Required buffer size in bytes including the terminating NUL
* (non-negative), or a negative OAKNODE_E_* error code.
*/
int oaknode_keyframe_get_value_string(const OakNodeKeyframe *keyframe,
int oaknode_keyframe_get_value_string(OakNodeKeyframe keyframe,
char *buf, int buf_size);
/**
* @brief Set a string value directly (live).
*/
int oaknode_keyframe_set_value_string(OakNodeKeyframe *keyframe,
int oaknode_keyframe_set_value_string(OakNodeKeyframe keyframe,
const char *value);
/**
* @brief Create a set-string-value command.
*/
int oaknode_keyframe_set_value_string_undoable(OakNodeKeyframe *keyframe,
int oaknode_keyframe_set_value_string_undoable(OakNodeKeyframe keyframe,
const char *value,
OakUndoCommand *out_command);
/**
* @brief The keyframe's interpolation type (oaknode_keyframe_type).
*/
int oaknode_keyframe_get_type(const OakNodeKeyframe *keyframe, int *out_type);
int oaknode_keyframe_get_type(OakNodeKeyframe keyframe, int *out_type);
/**
* @brief Set the interpolation type directly (live,
* NodeKeyframe::set_type(), which adjusts neighbouring bezier handles).
*/
int oaknode_keyframe_set_type(OakNodeKeyframe *keyframe, int type);
int oaknode_keyframe_set_type(OakNodeKeyframe keyframe, int type);
/**
* @brief Create a set-type command (same semantics as the live variant).
*/
int oaknode_keyframe_set_type_undoable(OakNodeKeyframe *keyframe, int type,
int oaknode_keyframe_set_type_undoable(OakNodeKeyframe keyframe, int type,
OakUndoCommand *out_command);
/**
* @brief A bezier control point (`handle` is an
* oaknode_keyframe_bezier).
*/
int oaknode_keyframe_get_bezier_control(const OakNodeKeyframe *keyframe,
int oaknode_keyframe_get_bezier_control(OakNodeKeyframe keyframe,
int handle, double *out_x,
double *out_y);
/**
* @brief Set a bezier control point directly (live).
*/
int oaknode_keyframe_set_bezier_control(OakNodeKeyframe *keyframe, int handle,
int oaknode_keyframe_set_bezier_control(OakNodeKeyframe keyframe, int handle,
double x, double y);
/**
* @brief Create a set-bezier-control command.
*/
int oaknode_keyframe_set_bezier_control_undoable(OakNodeKeyframe *keyframe,
int oaknode_keyframe_set_bezier_control_undoable(OakNodeKeyframe keyframe,
int handle, double x, double y,
OakUndoCommand *out_command);
/**
* @brief The keyframe's track index.
*/
int oaknode_keyframe_get_track(const OakNodeKeyframe *keyframe,
int oaknode_keyframe_get_track(OakNodeKeyframe keyframe,
int *out_track);
/**
* @brief The keyframe's element index.
*/
int oaknode_keyframe_get_element(const OakNodeKeyframe *keyframe,
int oaknode_keyframe_get_element(OakNodeKeyframe keyframe,
int *out_element);
/**
* @brief The id of the input this keyframe belongs to. Two-stage getter.
*/
int oaknode_keyframe_get_input(const OakNodeKeyframe *keyframe, char *buf,
int oaknode_keyframe_get_input(OakNodeKeyframe keyframe, char *buf,
int buf_size);
/**
* @brief The node this keyframe belongs to (borrowed handle), or NULL
* when orphaned. OAKNODE_OK either way.
* @brief The node this keyframe belongs to (borrowed handle written to
* `out_node`; release it with oaknode_node_free()), an empty handle when
* orphaned. OAKNODE_OK either way.
*/
int oaknode_keyframe_get_parent(const OakNodeKeyframe *keyframe,
OakNodeNode **out_node);
int oaknode_keyframe_get_parent(OakNodeKeyframe keyframe,
OakNodeNode *out_node);
#ifdef __cplusplus
}
include/node/node.h
+134 -124
View File
@@ -35,13 +35,15 @@ extern "C" {
* @file node.h
* @brief C ABI for olive::Node (src/node/src/node.h).
*
* The handle IS the C++ object pointer (M3 handle convention 3): an
* OakNodeNode is a reinterpreted olive::Node, no wrapper allocation.
* Handles borrowed from a graph become invalid when the owning project or
* node is destroyed. Owned handles (from oaknode_factory_create_from_id()
* or oaknode_node_create_copy()) must be released with
* oaknode_node_free() while still orphaned; once a node lives in a project
* graph its lifetime belongs to the graph.
* Handles are by-value reference-counted structs (see
* include/common/handle.h): every OakNodeNode carries ctx/addref/release/
* abi_version and behaves like a shared_ptr at the ABI level. Factory
* functions return a handle with reference count 1; release it with
* oaknode_node_free(). Handles borrowed from a graph only release the
* handle itself when freed; once a node lives in a project graph its
* lifetime belongs to the graph (the implementation flips ownership
* internally), and borrowed handles become invalid when the owning project
* or node is destroyed.
*
* Parameter values cross the boundary as the POD oaknode_value; the
* meaningful fields depend on its type (oaknode_value_type). String-typed
@@ -96,9 +98,21 @@ typedef struct oaknode_value {
} oaknode_value;
/**
* @brief Opaque node handle (olive::Node).
* @brief Reference-counted handle to a node (olive::Node).
*
* The object never leaves the library that created it; every external
* reference is one of these handles. Semantics are shared_ptr-like:
* init/factory functions return a handle with reference count 1,
* addref(ctx) takes another reference, release(ctx) drops one; release a
* handle with oaknode_node_free(). Borrowed handles into graph-owned
* objects only release the handle itself.
*/
typedef struct OakNodeNode OakNodeNode;
typedef struct OakNodeNode {
void *ctx; /**< Opaque pointer to the reference-counted object. */
void (*addref)(void *ctx); /**< Atomically increments the count. */
void (*release)(void *ctx); /**< Decrements the count, destroys at 0. */
uint32_t abi_version; /**< OAKNODE_ABI_VERSION. */
} OakNodeNode;
/* Re-declared here so node.h is self-contained; see node/project.h. */
typedef struct OakNodeProject OakNodeProject;
@@ -141,26 +155,26 @@ int oaknode_debug_alive_count(void);
* @return Required buffer size in bytes including the terminating NUL
* (non-negative), or a negative OAKNODE_E_* error code.
*/
int oaknode_node_get_id(const OakNodeNode *node, char *buf, int buf_size);
int oaknode_node_get_id(OakNodeNode node, char *buf, int buf_size);
/**
* @brief The node's display name (Node::name()). Two-stage getter,
* same return convention as oaknode_node_get_id().
*/
int oaknode_node_get_name(const OakNodeNode *node, char *buf, int buf_size);
int oaknode_node_get_name(OakNodeNode node, char *buf, int buf_size);
/**
* @brief The node's user label (Node::get_label()). Two-stage getter,
* same return convention as oaknode_node_get_id().
*/
int oaknode_node_get_label(const OakNodeNode *node, char *buf, int buf_size);
int oaknode_node_get_label(OakNodeNode node, char *buf, int buf_size);
/**
* @brief Set the node's user label directly (Node::set_label(), live).
*
* @return OAKNODE_OK or a negative OAKNODE_E_* error code.
*/
int oaknode_node_set_label(OakNodeNode *node, const char *label);
int oaknode_node_set_label(OakNodeNode node, const char *label);
/**
* @brief Create a label-change command (olive::NodeRenameCommand).
@@ -170,7 +184,7 @@ int oaknode_node_set_label(OakNodeNode *node, const char *label);
*
* @return OAKNODE_OK or a negative OAKNODE_E_* error code.
*/
int oaknode_node_set_label_undoable(OakNodeNode *node, const char *label,
int oaknode_node_set_label_undoable(OakNodeNode node, const char *label,
OakUndoCommand *out_command);
/**
@@ -181,21 +195,21 @@ int oaknode_node_set_label_undoable(OakNodeNode *node, const char *label,
*
* @return OAKNODE_OK or a negative OAKNODE_E_* error code.
*/
int oaknode_node_get_override_color(const OakNodeNode *node, int *out_value);
int oaknode_node_get_override_color(OakNodeNode node, int *out_value);
/**
* @brief Set the override color index directly (-1 = none; live).
*
* @return OAKNODE_OK or a negative OAKNODE_E_* error code.
*/
int oaknode_node_set_override_color(OakNodeNode *node, int index);
int oaknode_node_set_override_color(OakNodeNode node, int index);
/**
* @brief Create an override-color command (olive::NodeOverrideColorCommand).
*
* @return OAKNODE_OK or a negative OAKNODE_E_* error code.
*/
int oaknode_node_set_override_color_undoable(OakNodeNode *node, int index,
int oaknode_node_set_override_color_undoable(OakNodeNode node, int index,
OakUndoCommand *out_command);
/**
@@ -204,14 +218,14 @@ int oaknode_node_set_override_color_undoable(OakNodeNode *node, int index,
*
* @return OAKNODE_OK or a negative OAKNODE_E_* error code.
*/
int oaknode_node_is_enabled(const OakNodeNode *node, int *out_value);
int oaknode_node_is_enabled(OakNodeNode node, int *out_value);
/**
* @brief Set the node's enabled state directly (live).
*
* @return OAKNODE_OK or a negative OAKNODE_E_* error code.
*/
int oaknode_node_set_enabled(OakNodeNode *node, int enabled);
int oaknode_node_set_enabled(OakNodeNode node, int enabled);
/**
* @brief Create an enabled-state command
@@ -219,7 +233,7 @@ int oaknode_node_set_enabled(OakNodeNode *node, int enabled);
*
* @return OAKNODE_OK or a negative OAKNODE_E_* error code.
*/
int oaknode_node_set_enabled_undoable(OakNodeNode *node, int enabled,
int oaknode_node_set_enabled_undoable(OakNodeNode node, int enabled,
OakUndoCommand *out_command);
/* ---- Input introspection ------------------------------------------------ */
@@ -230,13 +244,13 @@ int oaknode_node_set_enabled_undoable(OakNodeNode *node, int enabled,
*
* @return OAKNODE_OK or a negative OAKNODE_E_* error code.
*/
int oaknode_node_input_count(const OakNodeNode *node, int *out_count);
int oaknode_node_input_count(OakNodeNode node, int *out_count);
/**
* @brief The input id at `index` (Node::inputs()). Two-stage getter;
* returns OAKNODE_E_NOT_FOUND for an out-of-range index.
*/
int oaknode_node_input_id(const OakNodeNode *node, int index, char *buf,
int oaknode_node_input_id(OakNodeNode node, int index, char *buf,
int buf_size);
/**
@@ -244,38 +258,39 @@ int oaknode_node_input_id(const OakNodeNode *node, int index, char *buf,
* pinned mapping on oaknode_value_type). OAKNODE_E_NOT_FOUND for an
* unknown input id.
*/
int oaknode_node_input_get_type(const OakNodeNode *node, const char *input_id,
int oaknode_node_input_get_type(OakNodeNode node, const char *input_id,
int *out_type);
/**
* @brief 1 if the input currently has a connected edge
* (Node::is_input_connected()). OAKNODE_E_NOT_FOUND for an unknown id.
*/
int oaknode_node_input_is_connected(const OakNodeNode *node,
const char *input_id, int *out_value);
int oaknode_node_input_is_connected(OakNodeNode node, const char *input_id,
int *out_value);
/**
* @brief 1 if the input accepts connections (Node::is_input_connectable()).
* OAKNODE_E_NOT_FOUND for an unknown id.
*/
int oaknode_node_input_is_connectable(const OakNodeNode *node,
const char *input_id, int *out_value);
int oaknode_node_input_is_connectable(OakNodeNode node, const char *input_id,
int *out_value);
/**
* @brief The human-readable name of the input (Node::get_input_name()).
* Two-stage getter; OAKNODE_E_NOT_FOUND for an unknown id.
*/
int oaknode_node_get_input_name(const OakNodeNode *node, const char *input_id,
int oaknode_node_get_input_name(OakNodeNode node, const char *input_id,
char *buf, int buf_size);
/**
* @brief The node feeding this input, or NULL when not connected
* (Node::get_connected_output(), element -1). `out_node` receives a
* borrowed handle. OAKNODE_E_NOT_FOUND for an unknown input id.
* @brief The node feeding this input (Node::get_connected_output(),
* element -1). `out_node` receives a borrowed handle (empty, ctx == NULL,
* when not connected; releasing it only releases the handle).
* OAKNODE_E_NOT_FOUND for an unknown input id.
*/
int oaknode_node_input_get_connected_node(const OakNodeNode *node,
int oaknode_node_input_get_connected_node(OakNodeNode node,
const char *input_id,
OakNodeNode **out_node);
OakNodeNode *out_node);
/* ---- Parameter access ----------------------------------------------------- */
@@ -288,7 +303,7 @@ int oaknode_node_input_get_connected_node(const OakNodeNode *node,
* fail with OAKNODE_E_FAILED; an unknown input id fails with
* OAKNODE_E_NOT_FOUND.
*/
int oaknode_node_get_input(const OakNodeNode *node, const char *input_id,
int oaknode_node_get_input(OakNodeNode node, const char *input_id,
oaknode_value *out);
/**
@@ -298,7 +313,7 @@ int oaknode_node_get_input(const OakNodeNode *node, const char *input_id,
* `v->type` must match the input's declared type; OAKNODE_VALUE_STRING is
* rejected (use oaknode_node_set_input_string()).
*/
int oaknode_node_set_input(OakNodeNode *node, const char *input_id,
int oaknode_node_set_input(OakNodeNode node, const char *input_id,
const oaknode_value *v);
/**
@@ -308,27 +323,26 @@ int oaknode_node_set_input(OakNodeNode *node, const char *input_id,
*
* Same type rules as oaknode_node_set_input().
*/
int oaknode_node_set_input_undoable(OakNodeNode *node, const char *input_id,
int oaknode_node_set_input_undoable(OakNodeNode node, const char *input_id,
const oaknode_value *v,
OakUndoCommand *out_command);
/**
* @brief Read a string-family input's standard value. Two-stage getter.
*/
int oaknode_node_get_input_string(const OakNodeNode *node,
const char *input_id, char *buf,
int buf_size);
int oaknode_node_get_input_string(OakNodeNode node, const char *input_id,
char *buf, int buf_size);
/**
* @brief Write a string-family input's standard value directly (live).
*/
int oaknode_node_set_input_string(OakNodeNode *node, const char *input_id,
int oaknode_node_set_input_string(OakNodeNode node, const char *input_id,
const char *value);
/**
* @brief Create a set-standard-value command for a string-family input.
*/
int oaknode_node_set_input_string_undoable(OakNodeNode *node,
int oaknode_node_set_input_string_undoable(OakNodeNode node,
const char *input_id,
const char *value,
OakUndoCommand *out_command);
@@ -344,7 +358,7 @@ int oaknode_node_set_input_string_undoable(OakNodeNode *node,
* OAKNODE_E_STATE when the input is already connected or the nodes belong
* to different graphs.
*/
int oaknode_node_connect(OakNodeNode *output_node, OakNodeNode *input_node,
int oaknode_node_connect(OakNodeNode output_node, OakNodeNode input_node,
const char *input_id);
/**
@@ -353,8 +367,8 @@ int oaknode_node_connect(OakNodeNode *output_node, OakNodeNode *input_node,
* different-graph check (the command may legitimately be redone after
* graph changes).
*/
int oaknode_node_connect_undoable(OakNodeNode *output_node,
OakNodeNode *input_node,
int oaknode_node_connect_undoable(OakNodeNode output_node,
OakNodeNode input_node,
const char *input_id,
OakUndoCommand *out_command);
@@ -363,44 +377,43 @@ int oaknode_node_connect_undoable(OakNodeNode *output_node,
* (live, Node::disconnect_edge(), element -1). OAKNODE_E_NOT_FOUND when
* the input is unknown or not connected.
*/
int oaknode_node_disconnect(OakNodeNode *input_node, const char *input_id);
int oaknode_node_disconnect(OakNodeNode input_node, const char *input_id);
/**
* @brief Create an edge-remove command (olive::NodeEdgeRemoveCommand,
* element -1). OAKNODE_E_NOT_FOUND when not connected.
*/
int oaknode_node_disconnect_undoable(OakNodeNode *input_node,
int oaknode_node_disconnect_undoable(OakNodeNode input_node,
const char *input_id,
OakUndoCommand *out_command);
/**
* @brief Number of outgoing edges (Node::output_connections()).
*/
int oaknode_node_output_connection_count(const OakNodeNode *node,
int *out_count);
int oaknode_node_output_connection_count(OakNodeNode node, int *out_count);
/**
* @brief The node at the input end of outgoing edge `index`
* (borrowed handle). OAKNODE_E_NOT_FOUND for an out-of-range index.
* @brief The node at the input end of outgoing edge `index` (borrowed
* handle; releasing it only releases the handle). OAKNODE_E_NOT_FOUND for
* an out-of-range index.
*/
int oaknode_node_output_connection_node_at(const OakNodeNode *node, int index,
OakNodeNode **out_node);
int oaknode_node_output_connection_node_at(OakNodeNode node, int index,
OakNodeNode *out_node);
/**
* @brief The input id at the input end of outgoing edge `index`.
* Two-stage getter; OAKNODE_E_NOT_FOUND for an out-of-range index.
*/
int oaknode_node_output_connection_input_id_at(const OakNodeNode *node,
int index, char *buf,
int buf_size);
int oaknode_node_output_connection_input_id_at(OakNodeNode node, int index,
char *buf, int buf_size);
/**
* @brief The input element at the input end of outgoing edge `index`
* (-1 for non-array inputs). OAKNODE_E_NOT_FOUND for an out-of-range
* index.
*/
int oaknode_node_output_connection_element_at(const OakNodeNode *node,
int index, int *out_element);
int oaknode_node_output_connection_element_at(OakNodeNode node, int index,
int *out_element);
/* ---- Links --------------------------------------------------------------- */
@@ -409,73 +422,72 @@ int oaknode_node_output_connection_element_at(const OakNodeNode *node,
* receives 1 on success, 0 when the link was rejected (e.g. either node
* rejects links). `out_linked` may be NULL.
*/
int oaknode_node_link(OakNodeNode *a, OakNodeNode *b, int *out_linked);
int oaknode_node_link(OakNodeNode a, OakNodeNode b, int *out_linked);
/**
* @brief Unlink two nodes directly (live, Node::unlink()).
* `out_unlinked` receives 1 on success, 0 otherwise; may be NULL.
*/
int oaknode_node_unlink(OakNodeNode *a, OakNodeNode *b, int *out_unlinked);
int oaknode_node_unlink(OakNodeNode a, OakNodeNode b, int *out_unlinked);
/**
* @brief Create a link/unlink command (olive::NodeLinkCommand;
* `link` != 0 links, 0 unlinks).
*/
int oaknode_node_link_undoable(OakNodeNode *a, OakNodeNode *b, int link,
int oaknode_node_link_undoable(OakNodeNode a, OakNodeNode b, int link,
OakUndoCommand *out_command);
/**
* @brief 1 if the two nodes are linked (Node::are_linked()).
*/
int oaknode_node_are_linked(const OakNodeNode *a, const OakNodeNode *b,
int *out_value);
int oaknode_node_are_linked(OakNodeNode a, OakNodeNode b, int *out_value);
/**
* @brief Number of linked nodes (Node::links()).
*/
int oaknode_node_link_count(const OakNodeNode *node, int *out_count);
int oaknode_node_link_count(OakNodeNode node, int *out_count);
/**
* @brief The linked node at `index` (borrowed handle).
* OAKNODE_E_NOT_FOUND for an out-of-range index.
* @brief The linked node at `index` (borrowed handle; releasing it only
* releases the handle). OAKNODE_E_NOT_FOUND for an out-of-range index.
*/
int oaknode_node_link_at(const OakNodeNode *node, int index,
OakNodeNode **out_node);
int oaknode_node_link_at(OakNodeNode node, int index,
OakNodeNode *out_node);
/* ---- Context positions ---------------------------------------------------- */
/**
* @brief Number of context entries (Node::get_context_positions()).
*/
int oaknode_node_context_count(const OakNodeNode *node, int *out_count);
int oaknode_node_context_count(OakNodeNode node, int *out_count);
/**
* @brief The context node at `index` (borrowed handle).
* OAKNODE_E_NOT_FOUND for an out-of-range index.
* @brief The context node at `index` (borrowed handle; releasing it only
* releases the handle). OAKNODE_E_NOT_FOUND for an out-of-range index.
*/
int oaknode_node_context_node_at(const OakNodeNode *node, int index,
OakNodeNode **out_node);
int oaknode_node_context_node_at(OakNodeNode node, int index,
OakNodeNode *out_node);
/**
* @brief The node's position in `context` (any out pointer may be NULL).
* OAKNODE_E_NOT_FOUND when the context does not contain this node.
*/
int oaknode_node_get_context_position(const OakNodeNode *node,
OakNodeNode *context, double *out_x,
double *out_y, int *out_expanded);
int oaknode_node_get_context_position(OakNodeNode node, OakNodeNode context,
double *out_x, double *out_y,
int *out_expanded);
/**
* @brief Set the node's position in `context` directly (live,
* Node::set_node_position_in_context() + set_node_expanded_in_context()).
*/
int oaknode_node_set_context_position(OakNodeNode *node, OakNodeNode *context,
int oaknode_node_set_context_position(OakNodeNode node, OakNodeNode context,
double x, double y, int expanded);
/**
* @brief Create a set-position command (olive::NodeSetPositionCommand).
*/
int oaknode_node_set_context_position_undoable(OakNodeNode *node,
OakNodeNode *context, double x,
int oaknode_node_set_context_position_undoable(OakNodeNode node,
OakNodeNode context, double x,
double y, int expanded,
OakUndoCommand *out_command);
@@ -483,16 +495,17 @@ int oaknode_node_set_context_position_undoable(OakNodeNode *node,
* @brief Remove the node from `context` directly (live).
* OAKNODE_E_NOT_FOUND when not contained.
*/
int oaknode_node_remove_from_context(OakNodeNode *node, OakNodeNode *context);
int oaknode_node_remove_from_context(OakNodeNode node, OakNodeNode context);
/* ---- Lifetime --------------------------------------------------------------- */
/**
* @brief Create a standalone copy of the node (Node::copy()). The copy is
* NOT added to any graph; the caller owns it and must release it with
* oaknode_node_free() while it is still orphaned. Returns NULL for NULL.
* NOT added to any graph; the returned handle has reference count 1 and
* must be released with oaknode_node_free() while it is still orphaned.
* Returns an empty handle (ctx == NULL) for an empty handle or on failure.
*/
OakNodeNode *oaknode_node_create_copy(const OakNodeNode *node);
OakNodeNode oaknode_node_create_copy(OakNodeNode node);
/**
* @brief Copy a node inside its graph (Node::copy_node_in_graph()),
@@ -501,44 +514,44 @@ OakNodeNode *oaknode_node_create_copy(const OakNodeNode *node);
* `*out_command` receives an owned undo command handle (free with
* oakundo_command_free()). The copy is inserted into the graph only when
* the returned command is redone; treat it as owned (oaknode_node_free())
* until then. Returns NULL on failure.
* until then. Returns an empty handle (ctx == NULL) on failure.
*/
OakNodeNode *oaknode_node_copy_in_graph(OakNodeNode *node,
OakUndoCommand *out_command);
OakNodeNode oaknode_node_copy_in_graph(OakNodeNode node,
OakUndoCommand *out_command);
/**
* @brief Get the project this node belongs to (borrowed). *out may be
* NULL if the node is orphaned.
* @brief Get the project this node belongs to. `out` receives a borrowed
* handle (empty, ctx == NULL, if the node is orphaned; releasing it only
* releases the handle).
*/
int oaknode_node_get_project(const OakNodeNode *node,
OakNodeProject **out);
int oaknode_node_get_project(OakNodeNode node, OakNodeProject *out);
/**
* @brief Insert/remove an element in an input array (live,
* Node::input_array_insert/remove()). OAKNODE_E_NOT_FOUND for an
* unknown input id.
*/
int oaknode_node_input_array_insert(OakNodeNode *node,
const char *input_id, int index);
int oaknode_node_input_array_remove(OakNodeNode *node,
const char *input_id, int index);
int oaknode_node_input_array_insert(OakNodeNode node, const char *input_id,
int index);
int oaknode_node_input_array_remove(OakNodeNode node, const char *input_id,
int index);
/**
* @brief Element-aware variants of oaknode_node_connect()/disconnect()
* (NodeInput element != -1, e.g. Sequence's track_in_N array inputs).
*/
int oaknode_node_connect_element(OakNodeNode *output_node,
OakNodeNode *input_node,
int oaknode_node_connect_element(OakNodeNode output_node,
OakNodeNode input_node,
const char *input_id, int element);
int oaknode_node_disconnect_element(OakNodeNode *input_node,
int oaknode_node_disconnect_element(OakNodeNode input_node,
const char *input_id, int element);
/**
* @brief Create a command that adds a node to a project's graph
* (olive::NodeAddCommand). Owned; free with oakundo_command_free().
*/
OakUndoCommand oaknode_command_create_add_node(OakNodeProject *graph,
OakNodeNode *node);
OakUndoCommand oaknode_command_create_add_node(OakNodeProject graph,
OakNodeNode node);
/**
* @brief Create a command that sets a node's position in a context and
@@ -546,22 +559,20 @@ OakUndoCommand oaknode_command_create_add_node(OakNodeProject *graph,
* (olive::NodeSetPositionAndDependenciesRecursivelyCommand). Owned.
*/
OakUndoCommand oaknode_command_create_set_position_recursive(
OakNodeNode *node, OakNodeNode *context, double x, double y);
OakNodeNode node, OakNodeNode context, double x, double y);
/**
* @brief Borrowed marker list / work area of a viewer node. *out is NULL
* when the node is not a viewer (or for NULL input).
* when the node is not a viewer (or for an empty handle).
*/
int oaknode_node_get_markers(const OakNodeNode *node,
OakNodeMarkerList **out);
int oaknode_node_get_work_area(const OakNodeNode *node,
OakNodeWorkArea **out);
int oaknode_node_get_markers(OakNodeNode node, OakNodeMarkerList **out);
int oaknode_node_get_work_area(OakNodeNode node, OakNodeWorkArea **out);
/**
* @brief Borrowed video frame cache of a node (NULL when the node has
* none or for NULL input).
* none or for an empty handle).
*/
int oaknode_node_get_video_frame_cache(const OakNodeNode *node,
int oaknode_node_get_video_frame_cache(OakNodeNode node,
OakNodeFrameCache **out);
/**
@@ -569,7 +580,7 @@ int oaknode_node_get_video_frame_cache(const OakNodeNode *node,
* (Node::copy_inputs()). include_connections != 0 also copies
* input connections.
*/
int oaknode_node_copy_inputs(OakNodeNode *dst, const OakNodeNode *src,
int oaknode_node_copy_inputs(OakNodeNode dst, OakNodeNode src,
int include_connections);
/**
@@ -577,8 +588,7 @@ int oaknode_node_copy_inputs(OakNodeNode *dst, const OakNodeNode *src,
* (Node::set_value_hint_for_input() with a single texture type
* and a Track::Reference string).
*/
int oaknode_node_set_value_hint_track(OakNodeNode *node,
const char *input_id,
int oaknode_node_set_value_hint_track(OakNodeNode node, const char *input_id,
int track_type, int track_index);
/**
@@ -586,37 +596,37 @@ int oaknode_node_set_value_hint_track(OakNodeNode *node,
* set_video_params/set_audio_params, stream index 0). `params` is an
* oakcommon handle (video) or borrowed oakcore handle (audio).
*/
int oaknode_viewer_set_video_params(OakNodeNode *viewer,
int oaknode_viewer_set_video_params(OakNodeNode viewer,
const OakVideoParams *params);
int oaknode_viewer_set_audio_params(OakNodeNode *viewer,
int oaknode_viewer_set_audio_params(OakNodeNode viewer,
const OakAudioParams *params);
/**
* @brief Find a footage node upstream of this node's inputs
* (Node::find_input_nodes<Footage>(), first match). *out is a
* borrowed handle or NULL when none.
* (Node::find_input_nodes<Footage>(), first match). `out` receives
* a borrowed handle (empty, ctx == NULL, when none; releasing it
* only releases the handle).
*/
int oaknode_node_find_input_footage(const OakNodeNode *node,
OakNodeFootage **out);
int oaknode_node_find_input_footage(OakNodeNode node, OakNodeFootage *out);
/**
* @brief Create a command that removes a node from its graph together
* with its exclusive dependencies and disconnects its edges
* (NodeRemoveWithExclusiveDependenciesAndDisconnect).
*
* Owned command handle; free with oakundo_command_free(). Returns NULL
* on failure.
* Owned command handle; free with oakundo_command_free(). Returns an
* empty handle (ctx == NULL) on failure.
*/
OakUndoCommand oaknode_command_create_remove_node(OakNodeNode *node);
OakUndoCommand oaknode_command_create_remove_node(OakNodeNode node);
/**
* @brief Destroy an OWNED node immediately (C++ delete). NULL is a no-op.
* @brief Release one reference to a node handle.
*
* ONLY valid for owned handles that were never added to a graph: the
* products of oaknode_factory_create_from_id(),
* oaknode_node_create_copy() and oaknode_group_create() while still
* orphaned. Freeing a graph-owned node, or freeing twice, is a
* use-after-free.
* Convenience wrapper around handle.release(handle.ctx): the underlying
* node is destroyed only when the last reference of an OWNED handle is
* released; releasing a borrowed handle into a graph-owned object only
* destroys the handle itself. NULL handle or NULL ctx is a no-op; clears
* `node->ctx` after releasing.
*/
void oaknode_node_free(OakNodeNode *node);
include/node/project.h
+68 -44
View File
@@ -21,6 +21,8 @@
#ifndef OAK_EDITOR_NODE_PROJECT_H
#define OAK_EDITOR_NODE_PROJECT_H
#include <stdint.h>
#include "node/error.h"
#ifdef __cplusplus
@@ -33,9 +35,9 @@ extern "C" {
*
* An OakNodeProject owns its whole node graph: nodes added with
* oaknode_project_add_node() (directly, or indirectly through the folder and
* footage families) are deleted by oaknode_project_free(). Handles to nodes,
* folders and footage obtained from a project are borrowed views and must not
* be freed.
* footage families) are deleted when the project's last reference is
* released. Handles to nodes, folders and footage obtained from a project
* are borrowed views: releasing them only releases the handle itself.
*
* Conventions (shared by all oaknode C API families):
* - Return codes: 0 (OAKNODE_OK) on success, a negative OAKNODE_E_* code on
@@ -44,27 +46,37 @@ extern "C" {
* query the required size; the return value is the required buffer size in
* bytes INCLUDING the terminating NUL. The output is NUL-terminated
* whenever buf_size > 0.
* - NULL handles yield OAKNODE_E_INVALID (or a no-op for free()).
* - Empty handles (ctx == NULL) yield OAKNODE_E_INVALID (or a no-op for
* free()).
* - Disk save/load of project files is NOT part of this layer; it belongs to
* oakstorage (milestone M10).
*/
/**
* @brief Opaque project handle. Owned by the caller; release with
* oaknode_project_free().
* @brief Reference-counted handle to a project (olive::Project).
*
* Semantics are shared_ptr-like: oaknode_project_init() returns a handle
* whose underlying object has reference count 1, addref(ctx) takes another
* reference, and release(ctx) (or oaknode_project_free()) drops one; the
* project and every node it owns are destroyed when the count reaches zero.
*/
typedef struct OakNodeProject OakNodeProject;
typedef struct OakNodeProject {
void *ctx; /**< Opaque pointer to the reference-counted object. */
void (*addref)(void *ctx); /**< Atomically increments the count. */
void (*release)(void *ctx); /**< Decrements the count, destroys at 0. */
uint32_t abi_version; /**< OAKNODE_ABI_VERSION. */
} OakNodeProject;
/**
* @brief Opaque node handle (defined by the node family; forward-declared
* @brief Node handle (defined by the node family; forward-declared
* here so the headers can be included in any order).
*/
typedef struct OakNodeNode OakNodeNode;
/**
* @brief Opaque folder handle (defined in node/folder.h; forward-declared
* here so the headers can be included in any order). Borrowed from the
* owning project.
* @brief Folder handle (defined in node/folder.h; forward-declared
* here so the headers can be included in any order). Handles obtained from
* a project are borrowed from it.
*/
typedef struct OakNodeFolder OakNodeFolder;
@@ -74,12 +86,16 @@ typedef struct OakNodeFolder OakNodeFolder;
* The project has no root folder until oaknode_project_initialize() is
* called (mirrors Project::initialize()).
*
* @return Project handle, or NULL on allocation failure.
* @return Project handle with reference count 1 (release with
* oaknode_project_free()); ctx is NULL on allocation failure.
*/
OakNodeProject *oaknode_project_init(void);
OakNodeProject oaknode_project_init(void);
/**
* @brief Destroy a project and every node it owns. NULL is a no-op.
* @brief Release one reference to a project handle.
*
* Destroys the project and every node it owns when the count reaches zero.
* NULL handle or NULL ctx is a no-op; clears `project->ctx` after releasing.
*/
void oaknode_project_free(OakNodeProject *project);
@@ -88,7 +104,7 @@ void oaknode_project_free(OakNodeProject *project);
*
* @return OAKNODE_OK, or OAKNODE_E_STATE if already initialized.
*/
int oaknode_project_initialize(OakNodeProject *project);
int oaknode_project_initialize(OakNodeProject project);
/**
* @brief Destructively destroy all nodes in the graph (Project::clear()).
@@ -98,14 +114,16 @@ int oaknode_project_initialize(OakNodeProject *project);
*
* @return OAKNODE_OK or a negative OAKNODE_E_* error code.
*/
int oaknode_project_clear(OakNodeProject *project);
int oaknode_project_clear(OakNodeProject project);
/**
* @brief Borrowed handle of the project's root folder (Project::root()).
*
* NULL if the project has not been initialized.
* The returned handle only releases the handle itself; the project owns the
* folder. Empty handle (ctx == NULL) if the project has not been
* initialized.
*/
OakNodeFolder *oaknode_project_root(OakNodeProject *project);
OakNodeFolder oaknode_project_root(OakNodeProject project);
/**
* @brief Project display name (Project::name(): the filename's base name, or
@@ -114,20 +132,20 @@ OakNodeFolder *oaknode_project_root(OakNodeProject *project);
* @return Required buffer size in bytes including the NUL, or a negative
* OAKNODE_E_* error code.
*/
int oaknode_project_name(const OakNodeProject *project, char *buf, int buf_size);
int oaknode_project_name(OakNodeProject project, char *buf, int buf_size);
/**
* @brief Full path the project was saved as, or "" if untitled
* (Project::filename()). Two-stage string getter.
*/
int oaknode_project_filename(const OakNodeProject *project, char *buf,
int oaknode_project_filename(OakNodeProject project, char *buf,
int buf_size);
/**
* @brief Display name safe for window titles (Project::pretty_filename()).
* Two-stage string getter.
*/
int oaknode_project_pretty_filename(const OakNodeProject *project, char *buf,
int oaknode_project_pretty_filename(OakNodeProject project, char *buf,
int buf_size);
/**
@@ -135,46 +153,47 @@ int oaknode_project_pretty_filename(const OakNodeProject *project, char *buf,
*
* @return OAKNODE_OK or a negative OAKNODE_E_* error code.
*/
int oaknode_project_set_filename(OakNodeProject *project, const char *filename);
int oaknode_project_set_filename(OakNodeProject project, const char *filename);
/**
* @brief 1 if the project has unsaved changes, 0 otherwise
* (Project::is_modified()). Negative OAKNODE_E_* code on NULL.
* (Project::is_modified()). Negative OAKNODE_E_* code on an empty handle.
*/
int oaknode_project_is_modified(const OakNodeProject *project);
int oaknode_project_is_modified(OakNodeProject project);
/**
* @brief Set the modified flag (Project::set_modified()).
*
* @return OAKNODE_OK or a negative OAKNODE_E_* error code.
*/
int oaknode_project_set_modified(OakNodeProject *project, int modified);
int oaknode_project_set_modified(OakNodeProject project, int modified);
/**
* @brief 1 if the project is new (untitled and unmodified, Project::is_new()).
* Negative OAKNODE_E_* code on NULL.
* Negative OAKNODE_E_* code on an empty handle.
*/
int oaknode_project_is_new(const OakNodeProject *project);
int oaknode_project_is_new(OakNodeProject project);
/**
* @brief Effective cache directory (Project::cache_path(), honoring the cache
* location setting). Two-stage string getter.
*/
int oaknode_project_cache_path(const OakNodeProject *project, char *buf,
int oaknode_project_cache_path(OakNodeProject project, char *buf,
int buf_size);
/**
* @brief Copy all project settings (Project::copy_settings()).
*/
int oaknode_project_copy_settings(OakNodeProject *dst,
const OakNodeProject *src);
int oaknode_project_copy_settings(OakNodeProject dst,
OakNodeProject src);
/**
* @brief Cache location setting enum value
* (Project::get_cache_location_setting(): 0 = default location,
* 1 = alongside project, 2 = custom path). Negative OAKNODE_E_* code on NULL.
* 1 = alongside project, 2 = custom path). Negative OAKNODE_E_* code on an
* empty handle.
*/
int oaknode_project_get_cache_location_setting(const OakNodeProject *project);
int oaknode_project_get_cache_location_setting(OakNodeProject project);
/**
* @brief Set the cache location setting (0/1/2, see
@@ -182,14 +201,14 @@ int oaknode_project_get_cache_location_setting(const OakNodeProject *project);
*
* @return OAKNODE_OK or a negative OAKNODE_E_* error code.
*/
int oaknode_project_set_cache_location_setting(OakNodeProject *project,
int oaknode_project_set_cache_location_setting(OakNodeProject project,
int setting);
/**
* @brief Custom cache directory, or "" when none is set
* (Project::get_custom_cache_path()). Two-stage string getter.
*/
int oaknode_project_get_custom_cache_path(const OakNodeProject *project,
int oaknode_project_get_custom_cache_path(OakNodeProject project,
char *buf, int buf_size);
/**
@@ -198,22 +217,25 @@ int oaknode_project_get_custom_cache_path(const OakNodeProject *project,
*
* @return OAKNODE_OK or a negative OAKNODE_E_* error code.
*/
int oaknode_project_set_custom_cache_path(OakNodeProject *project,
int oaknode_project_set_custom_cache_path(OakNodeProject project,
const char *path);
/**
* @brief Project UUID string (Project::get_uuid()). Two-stage string getter.
*/
int oaknode_project_get_uuid(const OakNodeProject *project, char *buf,
int oaknode_project_get_uuid(OakNodeProject project, char *buf,
int buf_size);
/**
* @brief Add a node to the graph; the project takes ownership
* @brief Add a node to the graph; the graph assumes the node's lifetime
* (Project::add_node()).
*
* After a successful call the graph owns the node: releasing `node` only
* releases the handle itself.
*
* @return OAKNODE_OK or a negative OAKNODE_E_* error code.
*/
int oaknode_project_add_node(OakNodeProject *project, OakNodeNode *node);
int oaknode_project_add_node(OakNodeProject project, OakNodeNode node);
/**
* @brief Detach a node from the graph without deleting it
@@ -222,19 +244,21 @@ int oaknode_project_add_node(OakNodeProject *project, OakNodeNode *node);
* @return OAKNODE_OK, OAKNODE_E_NOT_FOUND if the node is not in the graph, or
* another negative OAKNODE_E_* error code.
*/
int oaknode_project_remove_node(OakNodeProject *project, OakNodeNode *node);
int oaknode_project_remove_node(OakNodeProject project, OakNodeNode node);
/**
* @brief Number of nodes belonging to the graph (Project::nodes().size()).
* Negative OAKNODE_E_* code on NULL.
* Negative OAKNODE_E_* code on an empty handle.
*/
int oaknode_project_node_count(const OakNodeProject *project);
int oaknode_project_node_count(OakNodeProject project);
/**
* @brief Borrowed handle of the graph node at `index`, or NULL when out of
* range.
* @brief Borrowed handle of the graph node at `index`.
*
* The returned handle only releases the handle itself. Empty handle
* (ctx == NULL) when out of range.
*/
OakNodeNode *oaknode_project_node_at(const OakNodeProject *project, int index);
OakNodeNode oaknode_project_node_at(OakNodeProject project, int index);
#ifdef __cplusplus
}
include/node/sequence.h
+64 -42
View File
@@ -25,6 +25,8 @@
#include <stdbool.h>
#endif
#include <stdint.h>
#include "common/videoparams.h"
#include "node/error.h"
#include "olive/core/oakcore/audioparams.h"
@@ -46,109 +48,129 @@ extern "C" {
typedef struct OakNodeNode OakNodeNode;
/**
* @brief Opaque handle to a sequence (olive::Sequence).
* @brief Reference-counted handle to a sequence (olive::Sequence).
*
* The handle IS the C++ object pointer; no wrapper is allocated.
* The object never leaves the library that created it; every external
* reference is one of these handles. Semantics are shared_ptr-like:
* oaknode_sequence_create() returns a handle with count 1, addref(ctx)
* takes another reference, release(ctx) drops one and the library
* destroys the object when the count reaches zero.
*
* Handles obtained from accessors (track lists, tracks) are borrowed:
* releasing them does not destroy the underlying object, which stays
* owned by the sequence graph.
*/
typedef struct OakNodeSequence OakNodeSequence;
typedef struct OakNodeSequence {
void *ctx; /**< Opaque pointer to the reference-counted object. */
void (*addref)(void *ctx); /**< Atomically increments the count. */
void (*release)(void *ctx); /**< Decrements the count, destroys at 0. */
uint32_t abi_version; /**< OAKNODE_ABI_VERSION. */
} OakNodeSequence;
/**
* @brief Opaque handle to a track list (olive::TrackList), see node/track.h.
* @brief Reference-counted handle to a track list (olive::TrackList),
* see node/track.h.
*/
typedef struct OakNodeTrackList OakNodeTrackList;
/**
* @brief Opaque handle to a track (olive::Track), see node/track.h.
* @brief Reference-counted handle to a track (olive::Track), see
* node/track.h.
*/
typedef struct OakNodeTrack OakNodeTrack;
/**
* @brief Create an empty sequence with zero tracks.
*
* @return Sequence handle, or NULL on allocation failure.
* @return Sequence handle with reference count 1 (release with
* oaknode_sequence_free()); ctx is NULL on allocation failure.
*/
OakNodeSequence *oaknode_sequence_create(void);
OakNodeSequence oaknode_sequence_create(void);
/**
* @brief Destroy a sequence and its track lists. No-op on NULL.
* @brief Release one reference to a sequence handle.
*
* Destroys the sequence (and its owned track lists) when the reference
* count reaches zero. NULL handle or NULL ctx is a no-op; clears
* `sequence->ctx` after releasing.
*
* Tracks and blocks connected to the sequence are owned by the graph and
* are not deleted here; the caller must have torn them down first.
*/
void oaknode_sequence_free(OakNodeSequence *sequence);
/**
* @brief Apply the default video/audio parameters
* (ViewerOutput::set_default_parameters()).
*/
int oaknode_sequence_set_default_parameters(OakNodeSequence sequence);
/**
* @brief Borrowed cast from a sequence handle to its node handle.
* Empty handle for an empty handle.
*/
OakNodeNode oaknode_sequence_as_node(OakNodeSequence sequence);
/**
* @brief Borrowed handle to the per-type track list.
*
* @param type One of OAKNODE_TRACK_TYPE_VIDEO / _AUDIO / _SUBTITLE.
* @return OAKNODE_OK, OAKNODE_E_INVALID or OAKNODE_E_NOT_FOUND (bad type).
*/
/**
* @brief Apply the default video/audio parameters
* (ViewerOutput::set_default_parameters()).
*/
int oaknode_sequence_set_default_parameters(OakNodeSequence *sequence);
/**
* @brief Borrowed cast from a sequence handle to its node handle.
* NULL for NULL.
*/
OakNodeNode *oaknode_sequence_as_node(OakNodeSequence *sequence);
int oaknode_sequence_get_track_list(OakNodeSequence *sequence, int type,
OakNodeTrackList **out);
int oaknode_sequence_get_track_list(OakNodeSequence sequence, int type,
OakNodeTrackList *out);
/**
* @brief Number of connected tracks of the given type.
*/
int oaknode_sequence_get_track_count(OakNodeSequence *sequence, int type,
int oaknode_sequence_get_track_count(OakNodeSequence sequence, int type,
int *count);
/**
* @brief Borrowed handle to the track of `type` at `index`.
*/
int oaknode_sequence_get_track_at(OakNodeSequence *sequence, int type,
int index, OakNodeTrack **out);
int oaknode_sequence_get_track_at(OakNodeSequence sequence, int type,
int index, OakNodeTrack *out);
/**
* @brief Flat track cache across all types (olive::Sequence::get_tracks()).
*/
int oaknode_sequence_get_all_track_count(OakNodeSequence *sequence, int *count);
int oaknode_sequence_get_all_track_at(OakNodeSequence *sequence, int index,
OakNodeTrack **out);
int oaknode_sequence_get_all_track_count(OakNodeSequence sequence, int *count);
int oaknode_sequence_get_all_track_at(OakNodeSequence sequence, int index,
OakNodeTrack *out);
/**
* @brief Playhead position in sequence time.
*/
int oaknode_sequence_get_playhead(OakNodeSequence *sequence, int *numerator,
int oaknode_sequence_get_playhead(OakNodeSequence sequence, int *numerator,
int *denominator);
int oaknode_sequence_set_playhead(OakNodeSequence *sequence, int numerator,
int oaknode_sequence_set_playhead(OakNodeSequence sequence, int numerator,
int denominator);
/**
* @brief Cached overall/video/audio lengths (olive::ViewerOutput).
*/
int oaknode_sequence_get_length(OakNodeSequence *sequence, int *numerator,
int oaknode_sequence_get_length(OakNodeSequence sequence, int *numerator,
int *denominator);
int oaknode_sequence_get_video_length(OakNodeSequence *sequence,
int oaknode_sequence_get_video_length(OakNodeSequence sequence,
int *numerator, int *denominator);
int oaknode_sequence_get_audio_length(OakNodeSequence *sequence,
int oaknode_sequence_get_audio_length(OakNodeSequence sequence,
int *numerator, int *denominator);
/**
* @brief Recompute the cached lengths from the track lists
* (olive::ViewerOutput::verify_length()).
*/
int oaknode_sequence_verify_length(OakNodeSequence *sequence);
int oaknode_sequence_verify_length(OakNodeSequence sequence);
/* --------------------------------------------------- Video/audio params */
/**
* @brief Number of video/audio parameter slots.
*/
int oaknode_sequence_get_video_stream_count(OakNodeSequence *sequence,
int oaknode_sequence_get_video_stream_count(OakNodeSequence sequence,
int *count);
int oaknode_sequence_get_audio_stream_count(OakNodeSequence *sequence,
int oaknode_sequence_get_audio_stream_count(OakNodeSequence sequence,
int *count);
/**
@@ -159,29 +181,29 @@ int oaknode_sequence_get_audio_stream_count(OakNodeSequence *sequence,
* @return OAKNODE_OK, OAKNODE_E_INVALID, OAKNODE_E_NOT_FOUND or
* OAKNODE_E_NOMEM.
*/
int oaknode_sequence_get_video_params(OakNodeSequence *sequence, int index,
int oaknode_sequence_get_video_params(OakNodeSequence sequence, int index,
OakVideoParams *out);
/**
* @brief Replace the video parameters at `index` with a copy of `params`.
*
* @return OAKNODE_E_INVALID if sequence is NULL, params.ctx is NULL, or
* index is negative.
* @return OAKNODE_E_INVALID if the sequence handle is empty, params.ctx is
* NULL, or index is negative.
*/
int oaknode_sequence_set_video_params(OakNodeSequence *sequence, int index,
int oaknode_sequence_set_video_params(OakNodeSequence sequence, int index,
OakVideoParams params);
/**
* @brief Audio parameters at `index` as a NEW handle owned by the caller
* (release with oakcore_audioparams_free()).
*/
int oaknode_sequence_get_audio_params(OakNodeSequence *sequence, int index,
int oaknode_sequence_get_audio_params(OakNodeSequence sequence, int index,
OakAudioParams **out);
/**
* @brief Replace the audio parameters at `index` with a copy of `params`.
*/
int oaknode_sequence_set_audio_params(OakNodeSequence *sequence, int index,
int oaknode_sequence_set_audio_params(OakNodeSequence sequence, int index,
const OakAudioParams *params);
#ifdef __cplusplus
include/node/serializer.h
+64 -39
View File
@@ -21,7 +21,10 @@
#ifndef OAK_EDITOR_NODE_SERIALIZER_H
#define OAK_EDITOR_NODE_SERIALIZER_H
#include <stdint.h>
#include "node/error.h"
#include "node/node.h"
#include "node/project.h"
#ifdef __cplusplus
@@ -73,17 +76,33 @@ extern "C" {
#define OAKNODE_SERIALIZER_NO_DATA 7
/**
* @brief Opaque save descriptor (wraps ProjectSerializer::SaveData).
* Owned by the caller; release with oaknode_serializer_savedata_free().
* @brief Reference-counted save descriptor (wraps
* olive::ProjectSerializer::SaveData).
*
* oaknode_serializer_savedata_create() returns a handle whose object has
* reference count 1; release it with oaknode_serializer_savedata_free().
*/
typedef struct OakNodeSerializerSaveData OakNodeSerializerSaveData;
typedef struct OakNodeSerializerSaveData {
void *ctx; /**< Opaque pointer to the reference-counted object. */
void (*addref)(void *ctx); /**< Atomically increments the count. */
void (*release)(void *ctx); /**< Decrements the count, destroys at 0. */
uint32_t abi_version; /**< OAKNODE_ABI_VERSION. */
} OakNodeSerializerSaveData;
/**
* @brief Opaque load result (wraps ProjectSerializer::LoadData).
* Owned by the caller; release with oaknode_serializer_loaddata_free().
* @brief Reference-counted load result (wraps
* olive::ProjectSerializer::LoadData).
*
* The handle returned through oaknode_serializer_load_from_xml() has
* reference count 1; release it with oaknode_serializer_loaddata_free().
* Node handles obtained from it are borrowed from the target project.
*/
typedef struct OakNodeSerializerLoadData OakNodeSerializerLoadData;
typedef struct OakNodeSerializerLoadData {
void *ctx; /**< Opaque pointer to the reference-counted object. */
void (*addref)(void *ctx); /**< Atomically increments the count. */
void (*release)(void *ctx); /**< Decrements the count, destroys at 0. */
uint32_t abi_version; /**< OAKNODE_ABI_VERSION. */
} OakNodeSerializerLoadData;
/**
* @brief Register the versioned serializers and initialize the node factory.
@@ -104,16 +123,19 @@ void oaknode_serializer_shutdown(void);
*
* @param load_type One of OAKNODE_SERIALIZER_LOAD_*; use
* OAKNODE_SERIALIZER_LOAD_ONLY_NODES for clipboard-style node copies.
* @param project Context project (borrowed), may be NULL for load types
* that do not require it.
* @param project Context project (borrowed), may be an empty handle for
* load types that do not require it.
*
* @return Save-data handle, or NULL on failure.
* @return Save-data handle with reference count 1 (release with
* oaknode_serializer_savedata_free()); ctx is NULL on failure.
*/
OakNodeSerializerSaveData *oaknode_serializer_savedata_create(
int load_type, OakNodeProject *project);
OakNodeSerializerSaveData oaknode_serializer_savedata_create(
int load_type, OakNodeProject project);
/**
* @brief Destroy a save descriptor. NULL is a no-op.
* @brief Release the caller's reference to the save descriptor and null
* out the handle. NULL and empty handles are a no-op; the object is
* destroyed when its reference count reaches zero.
*/
void oaknode_serializer_savedata_free(OakNodeSerializerSaveData *save_data);
@@ -125,7 +147,7 @@ void oaknode_serializer_savedata_free(OakNodeSerializerSaveData *save_data);
* @return OAKNODE_OK or a negative OAKNODE_E_* error code.
*/
int oaknode_serializer_savedata_set_nodes(
OakNodeSerializerSaveData *save_data, OakNodeNode *const *nodes, int count);
OakNodeSerializerSaveData save_data, const OakNodeNode *nodes, int count);
/**
* @brief Attach a free-form (key, value) property to a node in the
@@ -135,7 +157,7 @@ int oaknode_serializer_savedata_set_nodes(
* @return OAKNODE_OK or a negative OAKNODE_E_* error code.
*/
int oaknode_serializer_savedata_set_property(
OakNodeSerializerSaveData *save_data, OakNodeNode *node, const char *key,
OakNodeSerializerSaveData save_data, OakNodeNode node, const char *key,
const char *value);
/**
@@ -146,21 +168,22 @@ int oaknode_serializer_savedata_set_property(
* OAKNODE_E_* error code (OAKNODE_E_STATE if the serializers have
* not been initialized).
*/
int oaknode_serializer_save_to_xml(OakNodeSerializerSaveData *save_data,
int oaknode_serializer_save_to_xml(OakNodeSerializerSaveData save_data,
char *buf, int buf_size);
/**
* @brief Parse an in-memory XML document into `project` ("paste").
*
* @param project Target project (borrowed), may be NULL for load types that
* do not attach nodes to a project.
* @param project Target project (borrowed), may be an empty handle for
* load types that do not attach nodes to a project.
* @param xml Complete XML document text. Must not be NULL.
* @param load_type One of OAKNODE_SERIALIZER_LOAD_*.
* @param out_result Receives one of the OAKNODE_SERIALIZER_* result codes.
* Must not be NULL.
* @param out_load_data Receives the load result on OAKNODE_SERIALIZER_OK
* (caller-owned, may be NULL if the caller does not need it;
* receives NULL on failure).
* (reference count 1, release with oaknode_serializer_loaddata_free();
* may be NULL if the caller does not need it; receives an empty
* handle on failure).
* @param details_buf Optional human-readable error detail buffer
* (two-stage convention is NOT used; truncation is silent). May be
* NULL.
@@ -169,13 +192,14 @@ int oaknode_serializer_save_to_xml(OakNodeSerializerSaveData *save_data,
* @return OAKNODE_OK if the call itself succeeded (inspect *out_result for
* the serializer outcome), or a negative OAKNODE_E_* error code.
*/
int oaknode_serializer_load_from_xml(OakNodeProject *project, const char *xml,
int oaknode_serializer_load_from_xml(OakNodeProject project, const char *xml,
int load_type, int *out_result,
OakNodeSerializerLoadData **out_load_data,
OakNodeSerializerLoadData *out_load_data,
char *details_buf, int details_buf_size);
/**
* @brief Destroy a load result. NULL is a no-op.
* @brief Release the caller's reference to the load result and null out
* the handle. NULL and empty handles are a no-op.
*
* Does not delete the loaded nodes: they are newly created objects owned by
* the CALLER until adopted into a project with oaknode_project_add_node()
@@ -185,17 +209,17 @@ void oaknode_serializer_loaddata_free(OakNodeSerializerLoadData *load_data);
/**
* @brief Number of nodes created by the load. Negative OAKNODE_E_* code on
* NULL.
* an empty handle.
*/
int oaknode_serializer_loaddata_node_count(
const OakNodeSerializerLoadData *load_data);
OakNodeSerializerLoadData load_data);
/**
* @brief Borrowed handle of the loaded node at `index`, or NULL when out of
* range.
* @brief Borrowed handle of the loaded node at `index`, or an empty handle
* when out of range.
*/
OakNodeNode *oaknode_serializer_loaddata_node_at(
const OakNodeSerializerLoadData *load_data, int index);
OakNodeNode oaknode_serializer_loaddata_node_at(
OakNodeSerializerLoadData load_data, int index);
/**
* @brief Look up a serialized property attached to a loaded node.
@@ -206,15 +230,15 @@ OakNodeNode *oaknode_serializer_loaddata_node_at(
* negative OAKNODE_E_* error code.
*/
int oaknode_serializer_loaddata_get_property(
const OakNodeSerializerLoadData *load_data, OakNodeNode *node,
const char *key, char *buf, int buf_size);
OakNodeSerializerLoadData load_data, OakNodeNode node, const char *key,
char *buf, int buf_size);
/**
* @brief Number of promised (deferred) connections in the load result.
* Negative OAKNODE_E_* code on NULL.
* Negative OAKNODE_E_* code on an empty handle.
*/
int oaknode_serializer_loaddata_connection_count(
const OakNodeSerializerLoadData *load_data);
OakNodeSerializerLoadData load_data);
/**
* @brief Read the promised connection at `index`.
@@ -223,8 +247,8 @@ int oaknode_serializer_loaddata_connection_count(
* `input_id_buf` follows the two-stage string convention inside a
* fixed call: pass NULL/0 to skip copying the id.
*
* @param out_output_node Receives the output (source) node.
* @param out_input_node Receives the input (destination) node.
* @param out_output_node Receives the output (source) node (borrowed).
* @param out_input_node Receives the input (destination) node (borrowed).
* @param input_id_buf Receives the input id string, may be NULL.
* @param input_id_buf_size Size of input_id_buf.
* @param out_element Receives the input element index.
@@ -233,8 +257,8 @@ int oaknode_serializer_loaddata_connection_count(
* negative OAKNODE_E_* error code.
*/
int oaknode_serializer_loaddata_connection_at(
const OakNodeSerializerLoadData *load_data, int index,
OakNodeNode **out_output_node, OakNodeNode **out_input_node,
OakNodeSerializerLoadData load_data, int index,
OakNodeNode *out_output_node, OakNodeNode *out_input_node,
char *input_id_buf, int input_id_buf_size, int *out_element);
#ifdef __cplusplus
@@ -268,9 +292,10 @@ enum OakNodeSerializerResultCode {
* string (e.g. the fallback filename on overwrite errors).
* @return OAKNODE_OK when the result code is
* OAKNODE_SERIALIZER_RESULT_SUCCESS, OAKNODE_E_FAILED otherwise
* (details in out_code/details), OAKNODE_E_INVALID for NULL args.
* (details in out_code/details), OAKNODE_E_INVALID for empty
* handles/NULL args.
*/
int oaknode_serializer_save_to_file(OakNodeProject *project,
int oaknode_serializer_save_to_file(OakNodeProject project,
const char *filename, int use_compression, int *out_code,
char *details, int details_size);
@@ -280,6 +305,6 @@ int oaknode_serializer_save_to_file(OakNodeProject *project,
*
* Same return/out-param convention as oaknode_serializer_save_to_file().
*/
int oaknode_serializer_load_from_file(OakNodeProject *project,
int oaknode_serializer_load_from_file(OakNodeProject project,
const char *filename, int *out_code, char *details,
int details_size);
include/node/track.h
+101 -70
View File
@@ -25,6 +25,8 @@
#include <stdbool.h>
#endif
#include <stdint.h>
#include "node/error.h"
#ifdef __cplusplus
@@ -32,27 +34,49 @@ extern "C" {
#endif
/**
* @brief Opaque handle to a track (olive::Track).
* @brief Reference-counted handle to a track (olive::Track).
*
* The handle IS the C++ object pointer; no wrapper is allocated.
* The object never leaves the library that created it; every external
* reference is one of these handles. Semantics are shared_ptr-like:
* oaknode_track_create() returns a handle with count 1, addref(ctx)
* takes another reference, release(ctx) drops one and the library
* destroys the object when the count reaches zero.
*
* Adding a track to a track list (oaknode_tracklist_add_track())
* transfers ownership to the graph; handles obtained from accessors
* (sequence/track-list lookups) are borrowed and never destroy the
* underlying object.
*/
typedef struct OakNodeTrack OakNodeTrack;
typedef struct OakNodeTrack {
void *ctx; /**< Opaque pointer to the reference-counted object. */
void (*addref)(void *ctx); /**< Atomically increments the count. */
void (*release)(void *ctx); /**< Decrements the count, destroys at 0. */
uint32_t abi_version; /**< OAKNODE_ABI_VERSION. */
} OakNodeTrack;
/**
* @brief Opaque handle to a per-type track container (olive::TrackList).
* @brief Reference-counted handle to a per-type track container
* (olive::TrackList).
*
* Borrowed from oaknode_sequence_get_track_list(); invalidated when the
* owning sequence is destroyed.
* Always borrowed from oaknode_sequence_get_track_list(); releasing the
* handle never destroys the list, which stays owned by its sequence.
*/
typedef struct OakNodeTrackList OakNodeTrackList;
typedef struct OakNodeTrackList {
void *ctx; /**< Opaque pointer to the reference-counted object. */
void (*addref)(void *ctx); /**< Atomically increments the count. */
void (*release)(void *ctx); /**< Decrements the count, destroys at 0. */
uint32_t abi_version; /**< OAKNODE_ABI_VERSION. */
} OakNodeTrackList;
/**
* @brief Opaque handle to a block (olive::Block), see node/block.h.
* @brief Reference-counted handle to a block (olive::Block), see
* node/block.h.
*/
typedef struct OakNodeBlock OakNodeBlock;
/**
* @brief Opaque handle to a sequence (olive::Sequence), see node/sequence.h.
* @brief Reference-counted handle to a sequence (olive::Sequence), see
* node/sequence.h.
*/
typedef struct OakNodeSequence OakNodeSequence;
@@ -72,9 +96,9 @@ typedef struct OakNodeNode OakNodeNode;
/**
* @brief Borrowed cast from a track handle to its node handle.
* NULL for NULL.
* Empty handle for an empty handle.
*/
OakNodeNode *oaknode_track_as_node(OakNodeTrack *track);
OakNodeNode oaknode_track_as_node(OakNodeTrack track);
/* ---------------------------------------------------------------- Track */
@@ -84,12 +108,16 @@ OakNodeNode *oaknode_track_as_node(OakNodeTrack *track);
* The caller owns the track until it is added to a track list; a track
* that was never added must be released with oaknode_track_free().
*
* @return Track handle, or NULL on invalid type / allocation failure.
* @return Track handle with reference count 1; ctx is NULL on invalid
* type / allocation failure.
*/
OakNodeTrack *oaknode_track_create(int type);
OakNodeTrack oaknode_track_create(int type);
/**
* @brief Destroy a track. No-op on NULL.
* @brief Release one reference to a track handle.
*
* Destroys the track when the reference count reaches zero. NULL handle
* or NULL ctx is a no-op; clears `track->ctx` after releasing.
*
* The track must have been removed from its track list first.
*/
@@ -100,20 +128,20 @@ void oaknode_track_free(OakNodeTrack *track);
*
* @return OAKNODE_OK or OAKNODE_E_INVALID.
*/
int oaknode_track_get_type(OakNodeTrack *track, int *type);
int oaknode_track_set_type(OakNodeTrack *track, int type);
int oaknode_track_get_type(OakNodeTrack track, int *type);
int oaknode_track_set_type(OakNodeTrack track, int type);
/**
* @brief Track height in internal units (olive::Track::get/set_track_height).
*/
int oaknode_track_get_height(OakNodeTrack *track, double *height);
int oaknode_track_set_height(OakNodeTrack *track, double height);
int oaknode_track_get_height(OakNodeTrack track, double *height);
int oaknode_track_set_height(OakNodeTrack track, double height);
/**
* @brief Track height in pixels (converted through the default font height).
*/
int oaknode_track_get_height_in_pixels(OakNodeTrack *track, int *height);
int oaknode_track_set_height_in_pixels(OakNodeTrack *track, int height);
int oaknode_track_get_height_in_pixels(OakNodeTrack track, int *height);
int oaknode_track_set_height_in_pixels(OakNodeTrack track, int height);
/**
* @brief Default / minimum track heights in pixels (static).
@@ -124,47 +152,47 @@ int oaknode_track_get_minimum_height_in_pixels(void);
/**
* @brief Index of the track inside its track list.
*/
int oaknode_track_get_index(OakNodeTrack *track, int *index);
int oaknode_track_set_index(OakNodeTrack *track, int index);
int oaknode_track_get_index(OakNodeTrack track, int *index);
int oaknode_track_set_index(OakNodeTrack track, int index);
/**
* @brief Mute / lock flags.
*/
int oaknode_track_get_muted(OakNodeTrack *track, int *muted);
int oaknode_track_set_muted(OakNodeTrack *track, int muted);
int oaknode_track_get_locked(OakNodeTrack *track, int *locked);
int oaknode_track_set_locked(OakNodeTrack *track, int locked);
int oaknode_track_get_muted(OakNodeTrack track, int *muted);
int oaknode_track_set_muted(OakNodeTrack track, int muted);
int oaknode_track_get_locked(OakNodeTrack track, int *locked);
int oaknode_track_set_locked(OakNodeTrack track, int locked);
/**
* @brief Track reference as a (type, index) pair (olive::Track::Reference).
*/
int oaknode_track_get_reference(OakNodeTrack *track, int *type, int *index);
int oaknode_track_get_reference(OakNodeTrack track, int *type, int *index);
/**
* @brief Total length of the track (end of the last block).
*/
int oaknode_track_get_length(OakNodeTrack *track, int *numerator,
int oaknode_track_get_length(OakNodeTrack track, int *numerator,
int *denominator);
/**
* @brief Owning sequence as a borrowed handle (NULL when trackless).
* @brief Owning sequence as a borrowed handle (empty when trackless).
*/
int oaknode_track_get_sequence(OakNodeTrack *track, OakNodeSequence **out);
int oaknode_track_get_sequence(OakNodeTrack track, OakNodeSequence *out);
/* ------------------------------------------------------- Track blocks */
/**
* @brief Number of blocks on the track.
*/
int oaknode_track_get_block_count(OakNodeTrack *track, int *count);
int oaknode_track_get_block_count(OakNodeTrack track, int *count);
/**
* @brief Borrowed handle to the block at `index`.
*
* @return OAKNODE_OK, OAKNODE_E_INVALID or OAKNODE_E_NOT_FOUND.
*/
int oaknode_track_get_block_at(OakNodeTrack *track, int index,
OakNodeBlock **out);
int oaknode_track_get_block_at(OakNodeTrack track, int index,
OakNodeBlock *out);
/**
* @brief Append/prepend/insert primitives (olive::Track::*_block).
@@ -174,54 +202,54 @@ int oaknode_track_get_block_at(OakNodeTrack *track, int index,
*
* @return OAKNODE_OK or OAKNODE_E_INVALID.
*/
int oaknode_track_append_block(OakNodeTrack *track, OakNodeBlock *block);
int oaknode_track_prepend_block(OakNodeTrack *track, OakNodeBlock *block);
int oaknode_track_insert_block_at_index(OakNodeTrack *track,
OakNodeBlock *block, int index);
int oaknode_track_insert_block_after(OakNodeTrack *track, OakNodeBlock *block,
OakNodeBlock *before);
int oaknode_track_insert_block_before(OakNodeTrack *track, OakNodeBlock *block,
OakNodeBlock *after);
int oaknode_track_append_block(OakNodeTrack track, OakNodeBlock block);
int oaknode_track_prepend_block(OakNodeTrack track, OakNodeBlock block);
int oaknode_track_insert_block_at_index(OakNodeTrack track,
OakNodeBlock block, int index);
int oaknode_track_insert_block_after(OakNodeTrack track, OakNodeBlock block,
OakNodeBlock before);
int oaknode_track_insert_block_before(OakNodeTrack track, OakNodeBlock block,
OakNodeBlock after);
/**
* @brief Remove `block` and shift all subsequent blocks earlier
* (olive::Track::ripple_remove_block). The block is NOT deleted; ownership
* returns to the caller.
*/
int oaknode_track_ripple_remove_block(OakNodeTrack *track, OakNodeBlock *block);
int oaknode_track_ripple_remove_block(OakNodeTrack track, OakNodeBlock block);
/**
* @brief Replace `old_block` with `new_block`; both must have equal lengths.
*/
int oaknode_track_replace_block(OakNodeTrack *track, OakNodeBlock *old_block,
OakNodeBlock *new_block);
int oaknode_track_replace_block(OakNodeTrack track, OakNodeBlock old_block,
OakNodeBlock new_block);
/**
* @brief Index of `block` in the track's block array, or OAKNODE_E_NOT_FOUND.
*/
int oaknode_track_get_block_index(OakNodeTrack *track, OakNodeBlock *block,
int oaknode_track_get_block_index(OakNodeTrack track, OakNodeBlock block,
int *index);
/**
* @brief Block strictly containing `time` (in < time < out), or
* OAKNODE_E_NOT_FOUND.
*/
int oaknode_track_get_block_containing_time(OakNodeTrack *track, int numerator,
int oaknode_track_get_block_containing_time(OakNodeTrack track, int numerator,
int denominator,
OakNodeBlock **out);
OakNodeBlock *out);
/**
* @brief Block visible at `time` (in <= time < out), or OAKNODE_E_NOT_FOUND.
*/
int oaknode_track_get_visible_block_at_time(OakNodeTrack *track, int numerator,
int oaknode_track_get_visible_block_at_time(OakNodeTrack track, int numerator,
int denominator,
OakNodeBlock **out);
OakNodeBlock *out);
/**
* @brief Whether the [in, out) range holds no block or only a gap
* (olive::Track::is_range_free). `is_free` receives 1/0.
*/
int oaknode_track_is_range_free(OakNodeTrack *track, int in_num, int in_den,
int oaknode_track_is_range_free(OakNodeTrack track, int in_num, int in_den,
int out_num, int out_den, int *is_free);
/* ------------------------------------------------------------ TrackList */
@@ -231,66 +259,66 @@ int oaknode_track_is_range_free(OakNodeTrack *track, int in_num, int in_den,
*/
/**
* @brief Nearest block lookups (Track::nearest_block_before_or_at /
* nearest_block_after_or_at). *out is a borrowed handle or NULL.
* nearest_block_after_or_at). *out is a borrowed handle (empty when none).
*/
int oaknode_track_get_nearest_block_before_or_at(OakNodeTrack *track,
int numerator, int denominator, OakNodeBlock **out);
int oaknode_track_get_nearest_block_after_or_at(OakNodeTrack *track,
int numerator, int denominator, OakNodeBlock **out);
int oaknode_track_get_nearest_block_before_or_at(OakNodeTrack track,
int numerator, int denominator, OakNodeBlock *out);
int oaknode_track_get_nearest_block_after_or_at(OakNodeTrack track,
int numerator, int denominator, OakNodeBlock *out);
/**
* @brief Borrowed sequence owning this track list.
*/
int oaknode_tracklist_get_sequence(OakNodeTrackList *list,
OakNodeSequence **out);
int oaknode_tracklist_get_sequence(OakNodeTrackList list,
OakNodeSequence *out);
/**
* @brief The list's track input id on the parent sequence
* (e.g. "track_in_0"). Two-stage string getter.
*/
int oaknode_tracklist_get_track_input_id(OakNodeTrackList *list,
int oaknode_tracklist_get_track_input_id(OakNodeTrackList list,
char *buf, int buf_size);
/**
* @brief Live input-array append/remove on the parent sequence for this
* list's track input (TrackList::array_append/array_remove_last()).
*/
int oaknode_tracklist_array_append(OakNodeTrackList *list);
int oaknode_tracklist_array_remove_last(OakNodeTrackList *list);
int oaknode_tracklist_array_append(OakNodeTrackList list);
int oaknode_tracklist_array_remove_last(OakNodeTrackList list);
/**
* @brief Map a cached track index to the input-array element index
* (TrackList::get_array_index_from_cache_index()).
*/
int oaknode_tracklist_get_array_index_from_cache_index(
OakNodeTrackList *list, int cache_index, int *out_index);
OakNodeTrackList list, int cache_index, int *out_index);
int oaknode_tracklist_get_type(OakNodeTrackList *list, int *type);
int oaknode_tracklist_get_type(OakNodeTrackList list, int *type);
/**
* @brief Number of connected tracks.
*/
int oaknode_tracklist_get_track_count(OakNodeTrackList *list, int *count);
int oaknode_tracklist_get_track_count(OakNodeTrackList list, int *count);
/**
* @brief Borrowed handle to the track at `index`.
*
* @return OAKNODE_OK, OAKNODE_E_INVALID or OAKNODE_E_NOT_FOUND.
*/
int oaknode_tracklist_get_track_at(OakNodeTrackList *list, int index,
OakNodeTrack **out);
int oaknode_tracklist_get_track_at(OakNodeTrackList list, int index,
OakNodeTrack *out);
/**
* @brief Combined length of the longest track in the list.
*/
int oaknode_tracklist_get_total_length(OakNodeTrackList *list, int *numerator,
int oaknode_tracklist_get_total_length(OakNodeTrackList list, int *numerator,
int *denominator);
/**
* @brief Size of the underlying input array (>= track count; may contain
* disconnected slots).
*/
int oaknode_tracklist_get_array_size(OakNodeTrackList *list, int *size);
int oaknode_tracklist_get_array_size(OakNodeTrackList list, int *size);
/**
* @brief Add `track` to the list (non-undoable primitive).
@@ -301,9 +329,12 @@ int oaknode_tracklist_get_array_size(OakNodeTrackList *list, int *size);
* the track is connected to it. The sequence's flat track cache and
* lengths are refreshed before returning.
*
* The list takes ownership of the track on success; the caller's handle
* becomes a non-owning reference.
*
* @return OAKNODE_OK or OAKNODE_E_INVALID.
*/
int oaknode_tracklist_add_track(OakNodeTrackList *list, OakNodeTrack *track);
int oaknode_tracklist_add_track(OakNodeTrackList list, OakNodeTrack track);
/**
* @brief Remove `track` from the list (non-undoable primitive).
@@ -314,8 +345,8 @@ int oaknode_tracklist_add_track(OakNodeTrackList *list, OakNodeTrack *track);
*
* @return OAKNODE_OK, OAKNODE_E_INVALID or OAKNODE_E_NOT_FOUND.
*/
int oaknode_tracklist_remove_track(OakNodeTrackList *list,
OakNodeTrack *track);
int oaknode_tracklist_remove_track(OakNodeTrackList list,
OakNodeTrack track);
#ifdef __cplusplus
}
include/node/traverser.h
+43 -19
View File
@@ -41,26 +41,46 @@ extern "C" {
*/
/**
* @brief Opaque traverser handle (olive::NodeTraverser).
* @brief Reference-counted handle to a traverser (olive::NodeTraverser).
*
* Semantics are shared_ptr-like: oaknode_traverser_init() returns a
* handle with count 1, addref(ctx) takes another reference, release(ctx)
* drops one and the library destroys the object when the count reaches
* zero.
*/
typedef struct OakNodeTraverser OakNodeTraverser;
typedef struct OakNodeTraverser {
void *ctx; /**< Opaque pointer to the reference-counted object. */
void (*addref)(void *ctx); /**< Atomically increments the count. */
void (*release)(void *ctx); /**< Decrements the count, destroys at 0. */
uint32_t abi_version; /**< OAKNODE_ABI_VERSION. */
} OakNodeTraverser;
/**
* @brief Opaque value-database handle (an owned copy of an
* olive::NodeValueDatabase). Release with
* oaknode_traverser_database_free().
* @brief Reference-counted handle to an owned copy of an
* olive::NodeValueDatabase. Same reference-counting rules as
* OakNodeTraverser; release with oaknode_traverser_database_free().
*/
typedef struct OakNodeValueDatabase OakNodeValueDatabase;
typedef struct OakNodeValueDatabase {
void *ctx; /**< Opaque pointer to the reference-counted object. */
void (*addref)(void *ctx); /**< Atomically increments the count. */
void (*release)(void *ctx); /**< Decrements the count, destroys at 0. */
uint32_t abi_version; /**< OAKNODE_ABI_VERSION. */
} OakNodeValueDatabase;
/**
* @brief Create a traverser.
*
* @return Traverser handle, or NULL on allocation failure.
* @return Traverser handle with count 1; ctx is NULL on allocation
* failure.
*/
OakNodeTraverser *oaknode_traverser_init(void);
OakNodeTraverser oaknode_traverser_init(void);
/**
* @brief Destroy a traverser. NULL is a no-op.
* @brief Release one reference to a traverser handle.
*
* Convenience wrapper around handle.release(handle.ctx): destroys the
* traverser when the count reaches zero. NULL handle or NULL ctx is a
* no-op; clears `traverser->ctx` after releasing.
*/
void oaknode_traverser_free(OakNodeTraverser *traverser);
@@ -69,39 +89,43 @@ void oaknode_traverser_free(OakNodeTraverser *traverser);
* [`in_num`/`in_den`, `out_num`/`out_den`) seconds
* (NodeTraverser::generate_database()).
*
* `out_db` receives an owned database handle.
* `out_db` receives an owned database handle with count 1.
*
* @return OAKNODE_OK or a negative OAKNODE_E_* error code.
*/
int oaknode_traverser_generate_database(OakNodeTraverser *traverser,
OakNodeNode *node, int64_t in_num,
int oaknode_traverser_generate_database(OakNodeTraverser traverser,
OakNodeNode node, int64_t in_num,
int64_t in_den, int64_t out_num,
int64_t out_den,
OakNodeValueDatabase **out_db);
OakNodeValueDatabase *out_db);
/**
* @brief Destroy a database handle. NULL is a no-op.
* @brief Release one reference to a database handle.
*
* Convenience wrapper around handle.release(handle.ctx): destroys the
* database when the count reaches zero. NULL handle or NULL ctx is a
* no-op; clears `db->ctx` after releasing.
*/
void oaknode_traverser_database_free(OakNodeValueDatabase *db);
/**
* @brief Number of rows (input tables) in the database.
*/
int oaknode_traverser_database_row_count(const OakNodeValueDatabase *db,
int oaknode_traverser_database_row_count(OakNodeValueDatabase db,
int *out_count);
/**
* @brief The input id (key) of the row at `index`. Two-stage getter;
* OAKNODE_E_NOT_FOUND for an out-of-range index.
*/
int oaknode_traverser_database_row_key_at(const OakNodeValueDatabase *db,
int oaknode_traverser_database_row_key_at(OakNodeValueDatabase db,
int index, char *buf, int buf_size);
/**
* @brief Number of values in the row named `key`.
* OAKNODE_E_NOT_FOUND for an unknown key.
*/
int oaknode_traverser_database_row_value_count(const OakNodeValueDatabase *db,
int oaknode_traverser_database_row_value_count(OakNodeValueDatabase db,
const char *key,
int *out_count);
@@ -110,7 +134,7 @@ int oaknode_traverser_database_row_value_count(const OakNodeValueDatabase *db,
* Values without a POD representation fail with OAKNODE_E_FAILED;
* OAKNODE_E_NOT_FOUND for an unknown key or out-of-range index.
*/
int oaknode_traverser_database_value_at(const OakNodeValueDatabase *db,
int oaknode_traverser_database_value_at(OakNodeValueDatabase db,
const char *key, int index,
oaknode_value *out);
@@ -119,7 +143,7 @@ int oaknode_traverser_database_value_at(const OakNodeValueDatabase *db,
* (NodeValue::value_to_string()). Two-stage getter;
* OAKNODE_E_NOT_FOUND for an unknown key or out-of-range index.
*/
int oaknode_traverser_database_value_string_at(const OakNodeValueDatabase *db,
int oaknode_traverser_database_value_string_at(OakNodeValueDatabase db,
const char *key, int index,
char *buf, int buf_size);