Sections

Node

What every object in a document can do.

Symbols in this group are spelled otio_node_…. An SDK drops that prefix, which is why the name beside each call is the short one.

child_at

method

Returns one of an object's children.

OtioStatus otio_node_child_at(
    const OtioDocument *source,
    OtioNode parent,
    size_t index,
    OtioNode *out_child,
    OtioBuffer *out_error);

Parameter	Type	Role
source ?	document	the document, borrowed
parent	node	what the call is about
index	size	input
out_child	node	written through, not read
out_error	text	why the call failed, or null to skip it

child_count

getter

Returns how many children an object holds.

Tracks, stacks, bare compositions and serializable collections hold children; anything else reports `OTIO_STATUS_WRONG_KIND`.

OtioStatus otio_node_child_count(
    const OtioDocument *source,
    OtioNode parent,
    size_t *out_count,
    OtioBuffer *out_error);

Parameter	Type	Role
source ?	document	the document, borrowed
parent	node	what the call is about
out_count	size	written through, not read
out_error	text	why the call failed, or null to skip it

children

getter

Returns an object's children.

OtioStatus otio_node_children(
    const OtioDocument *source,
    OtioNode parent,
    OtioNode *out_nodes,
    size_t capacity,
    size_t *out_count,
    OtioBuffer *out_error);

Parameter	Type	Role
source ?	document	the document, borrowed
parent	node	what the call is about
out_nodes	list<node>	a list written through, sized by the count
capacity	size	how many the buffer can hold
out_count	size	how many the call had to give
out_error	text	why the call failed, or null to skip it

equals

method

Returns whether two handles have the same value.

Within one document that is object identity: two handles are equal only if they were issued for the same occupant of the same slot. Handles from two different documents can be equal without naming the same object, since a handle is scoped to the document that issued it.

bool otio_node_equal(OtioNode left, OtioNode right);

Parameter	Type	Role
left	node	what the call is about
right	node	input

find_clips

getter

Returns every clip at or below an object, in order.

 *     otio_node_find_clips(document, timeline, NULL, 0, &count, NULL);

Parameter	Type	Role
source ?	document	the document, borrowed
node_handle	node	what the call is about
out_nodes	list<node>	a list written through, sized by the count
capacity	size	how many the buffer can hold
out_count	size	how many the call had to give
out_error	text	why the call failed, or null to skip it

highest_ancestor

getter

Returns the outermost object above this one.

OtioStatus otio_node_highest_ancestor(
    const OtioDocument *source,
    OtioNode node_handle,
    OtioNode *out_ancestor,
    OtioBuffer *out_error);

Parameter	Type	Role
source ?	document	the document, borrowed
node_handle	node	what the call is about
out_ancestor	node	written through, not read
out_error	text	why the call failed, or null to skip it

is_none

getter

Returns whether a handle names no object.

bool otio_node_is_none(OtioNode node);

Parameter	Type	Role
node	node	what the call is about

schema_kind

getter

Returns what kind of object a handle names.

The answer is the most specific kind the library knows: a clip reports `OTIO_NODE_KIND_CLIP`, never `OTIO_NODE_KIND_ITEM`, and a linear time warp `OTIO_NODE_KIND_LINEAR_TIME_WARP`, never `OTIO_NODE_KIND_TIME_EFFECT`. An object read from a schema the library does not know reports `OTIO_NODE_KIND_UNKNOWN_SCHEMA`.

OtioStatus otio_node_kind(
    const OtioDocument *source,
    OtioNode node_handle,
    OtioNodeKind *out_kind,
    OtioBuffer *out_error);

Parameter	Type	Role
source ?	document	the document, borrowed
node_handle	node	what the call is about
out_kind	OtioNodeKind	written through, not read
out_error	text	why the call failed, or null to skip it

name

getter

Returns an object's name, which is empty for an object that has none.

OtioStatus otio_node_name(
    const OtioDocument *source,
    OtioNode node_handle,
    OtioBuffer *out_name,
    OtioBuffer *out_error);

Parameter	Type	Role
source ?	document	the document, borrowed
node_handle	node	what the call is about
out_name	text	written through, not read
out_error	text	why the call failed, or null to skip it

none

constructor

Returns the handle that names no object.

Fields that may be absent, such as a timeline's tracks before one is set, report this. Compare against it with `otio_node_is_none`.

 * one, or `otio_node_none()` to leave the clip as it is. It returns
 * `OTIO_STATUS_OK`, or any other status to stop the read or write, having
 * written a NUL-terminated sentence to `message`, which has room for
 * `message_capacity` bytes, saying why. The call that ran it then fails with
 * `OTIO_STATUS_PLUGIN_ERROR` and that sentence.
 *
 * The registry is process-wide, so a plugin must be safe to call from any
 * thread that reads or writes.
 */
typedef OtioStatus (*OtioPluginFn)(
    void *context,
    OtioDocument *document,
    OtioNode target,
    OtioNode arguments,
    OtioNode *out_result,
    char *message,
    size_t message_capacity);

overlapping

getter

Returns whether an object sits over its neighbours rather than beside them.

Only a transition does, which is why one does not advance the playhead when a track is laid out.

OtioStatus otio_node_overlapping(
    const OtioDocument *source,
    OtioNode node_handle,
    bool *out_overlapping,
    OtioBuffer *out_error);

Parameter	Type	Role
source ?	document	the document, borrowed
node_handle	node	what the call is about
out_overlapping	bool	written through, not read
out_error	text	why the call failed, or null to skip it

parent

gettermay answer nothing

Returns the composition an object sits in.

Reports `OTIO_STATUS_NO_VALUE` for an object that is in none, which is what a freshly created one is.

OtioStatus otio_node_parent(
    const OtioDocument *source,
    OtioNode node_handle,
    OtioNode *out_parent,
    OtioBuffer *out_error);

Parameter	Type	Role
source ?	document	the document, borrowed
node_handle	node	what the call is about
out_parent	node	written through, not read
out_error	text	why the call failed, or null to skip it

run_hook

method

Runs every script attached to the hook `hook` on an object, each on what the one before returned, and writes what the last returned to `out_result`: upstream's `hooks.run`.

`arguments` is the scripts' argument map as a JSON object, or null for an empty one. With no script attached, the object itself comes back. A hook that was never declared, by an attachment or as one of the four every read and write runs, is `OTIO_STATUS_PLUGIN_ERROR`, as is a script that fails or is not registered.

OtioStatus otio_node_run_hook(
    OtioDocument *document,
    OtioNode node_handle,
    const char *hook,
    const char *arguments,
    OtioNode *out_result,
    OtioBuffer *out_error);

Parameter	Type	Role
document	document	the document, changed
node_handle	node	what the call is about
hook	text	input
arguments ?	text	input
out_result	node	written through, not read
out_error	text	why the call failed, or null to skip it

schema_name

getter

Returns the schema name an object serializes as, such as `"Clip"`.

OtioStatus otio_node_schema_name(
    const OtioDocument *source,
    OtioNode node_handle,
    OtioBuffer *out_name,
    OtioBuffer *out_error);

Parameter	Type	Role
source ?	document	the document, borrowed
node_handle	node	what the call is about
out_name	text	written through, not read
out_error	text	why the call failed, or null to skip it

schema_version

getter

Returns the schema version an object serializes as.

OtioStatus otio_node_schema_version(
    const OtioDocument *source,
    OtioNode node_handle,
    uint32_t *out_version,
    OtioBuffer *out_error);

Parameter	Type	Role
source ?	document	the document, borrowed
node_handle	node	what the call is about
out_version	uint32	written through, not read
out_error	text	why the call failed, or null to skip it

set_name

setter

Sets an object's name.

OtioStatus otio_node_set_name(
    OtioDocument *target,
    OtioNode node_handle,
    const char *name,
    OtioBuffer *out_error);

Parameter	Type	Role
target	document	the document, changed
node_handle	node	what the call is about
name	text	input
out_error	text	why the call failed, or null to skip it

to_json

method

Writes one object of a document as OTIO JSON.

Upstream's `write_to_string` takes any object, not only a timeline, so this does too.

OtioStatus otio_node_to_json(
    const OtioDocument *source,
    OtioNode node,
    size_t indent,
    OtioBuffer *out_json,
    OtioBuffer *out_error);

Parameter	Type	Role
source ?	document	the document, borrowed
node	node	what the call is about
indent	size	input
out_json	text	written through, not read
out_error	text	why the call failed, or null to skip it

transformed_time

method

Restates an instant from one object's clock in another's.

OtioStatus otio_node_transformed_time(
    const OtioDocument *source,
    OtioRationalTime time,
    OtioNode from,
    OtioNode to,
    OtioRationalTime *out_time,
    OtioBuffer *out_error);

Parameter	Type	Role
source ?	document	the document, borrowed
time	OtioRationalTime	input
from	node	what the call is about
to	node	input
out_time	OtioRationalTime	written through, not read
out_error	text	why the call failed, or null to skip it

transformed_time_range

method

Restates a span from one object's clock in another's.

OtioStatus otio_node_transformed_time_range(
    const OtioDocument *source,
    OtioTimeRange range,
    OtioNode from,
    OtioNode to,
    OtioTimeRange *out_range,
    OtioBuffer *out_error);

Parameter	Type	Role
source ?	document	the document, borrowed
range	OtioTimeRange	input
from	node	what the call is about
to	node	input
out_range	OtioTimeRange	written through, not read
out_error	text	why the call failed, or null to skip it

visible

getter

Returns whether an object covers what is beneath it when its composition is flattened.

OtioStatus otio_node_visible(
    const OtioDocument *source,
    OtioNode node_handle,
    bool *out_visible,
    OtioBuffer *out_error);

Parameter	Type	Role
source ?	document	the document, borrowed
node_handle	node	what the call is about
out_visible	bool	written through, not read
out_error	text	why the call failed, or null to skip it