264 lines
15 KiB
C
264 lines
15 KiB
C
/***
|
|
|
|
Oak - Non-Linear Video Editor
|
|
Copyright (C) 2026 Oak Team
|
|
|
|
This program is free software: you can redistribute it and/or modify
|
|
it under the terms of the GNU General Public License as published by
|
|
the Free Software Foundation, either version 3 of the License, or
|
|
(at your option) any later version.
|
|
|
|
This program is distributed in the hope that it will be useful,
|
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
GNU General Public License for more details.
|
|
|
|
You should have received a copy of the GNU General Public License
|
|
along with this program. If not, see <http://www.gnu.org/licenses/>.
|
|
|
|
***/
|
|
|
|
#ifndef OAKENGINE_EVENTS_H
|
|
#define OAKENGINE_EVENTS_H
|
|
|
|
#include <stdint.h>
|
|
|
|
#include "export.h"
|
|
#include "init.h"
|
|
#include "project.h"
|
|
#include "timeline.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/**
|
|
* @file events.h
|
|
* @brief C ABI for engine change notifications (the signal/slot replacement)
|
|
*
|
|
* The engine's C++ API notifies observers through Qt signals (Project::
|
|
* modified_changed, Folder::begin_insert_item, Track::block_added, the
|
|
* sequence's track/marker/workarea notifications, ...). This family exposes
|
|
* the same notifications to C consumers as a subscription/callback
|
|
* mechanism, so the application never needs to connect() to an engine
|
|
* QObject directly.
|
|
*
|
|
* Usage:
|
|
*
|
|
* int64_t sub = oakengine_event_subscribe(handle, OAKENGINE_EVENT_..., fn,
|
|
* userdata);
|
|
* ...
|
|
* oakengine_event_unsubscribe(sub);
|
|
*
|
|
* `handle` is a borrowed facade handle whose static type depends on the
|
|
* event family (see the table below); a mismatch or NULL handle fails with
|
|
* 0 (an invalid subscription id). Subscribing the same (handle, event)
|
|
* twice is allowed and returns two independent subscription ids.
|
|
*
|
|
* Thread semantics: callbacks are invoked SYNCHRONOUSLY on the thread that
|
|
* emits the change (the equivalent of Qt::DirectConnection) before the
|
|
* engine's own emission returns, exactly like the C++ connections they
|
|
* replace. The callback runs under whatever locks the engine holds at the
|
|
* emission site; it must not call back into editing primitives that mutate
|
|
* the same object. All engine objects live on the GUI thread, so callbacks
|
|
* normally fire there.
|
|
*
|
|
* Lifetime: the registry drops the subscription automatically when the
|
|
* observed engine object is destroyed, so a stale subscription id is never
|
|
* a use-after-free; oakengine_event_unsubscribe() on an id whose object
|
|
* died is a harmless no-op returning OAKENGINE_E_NOT_FOUND. The inverse is
|
|
* NOT tracked: `userdata` ownership stays with the subscriber, which must
|
|
* unsubscribe (or tolerate callbacks) until its own teardown.
|
|
*
|
|
* Event payloads use POD fields only. Timestamps are frame numbers in the
|
|
* owning sequence's frame-rate timebase (same convention as timeline.h);
|
|
* `handle`/`source` are borrowed pointers the callee may use during the
|
|
* callback only.
|
|
*/
|
|
|
|
/**
|
|
* @brief Event ids for oakengine_event_subscribe().
|
|
*
|
|
* handle column: the facade handle to pass for that event.
|
|
* payload column: oakengine_event field contents on delivery.
|
|
*/
|
|
#define OAKENGINE_EVENT_PROJECT_MODIFIED_CHANGED 1 /**< handle: OakEngineProject*. a = new modified flag (0/1). */
|
|
#define OAKENGINE_EVENT_PROJECT_NAME_CHANGED 2 /**< handle: OakEngineProject*. no payload. */
|
|
|
|
#define OAKENGINE_EVENT_FOLDER_BEGIN_INSERT_ITEM 10 /**< handle: OakEngineNode* (a folder). handle field = child OakEngineNode*, a = insertion index. */
|
|
#define OAKENGINE_EVENT_FOLDER_END_INSERT_ITEM 11 /**< handle: OakEngineNode* (a folder). no payload. */
|
|
#define OAKENGINE_EVENT_FOLDER_BEGIN_REMOVE_ITEM 12 /**< handle: OakEngineNode* (a folder). handle field = child OakEngineNode*, a = child index. */
|
|
#define OAKENGINE_EVENT_FOLDER_END_REMOVE_ITEM 13 /**< handle: OakEngineNode* (a folder). no payload. */
|
|
|
|
#define OAKENGINE_EVENT_SEQUENCE_TRACK_ADDED 20 /**< handle: OakEngineSequence*. handle field = OakEngineTrack*, a = track type (OAKENGINE_TRACK_TYPE_*). */
|
|
#define OAKENGINE_EVENT_SEQUENCE_TRACK_REMOVED 21 /**< handle: OakEngineSequence*. handle field = OakEngineTrack*, a = track type. */
|
|
#define OAKENGINE_EVENT_SEQUENCE_TRACK_LIST_CHANGED 22 /**< handle: OakEngineSequence*. a = track type. Fired on TrackList::track_list_changed (order/label-affecting changes). */
|
|
#define OAKENGINE_EVENT_SEQUENCE_TRACK_HEIGHT_CHANGED 23 /**< handle: OakEngineSequence*. handle field = OakEngineTrack*, a = track type, b = new height in PIXELS (TrackList::track_height_changed). */
|
|
#define OAKENGINE_EVENT_SEQUENCE_SUBTITLES_CHANGED 24 /**< handle: OakEngineSequence*. a/b = changed range in/out (ts). */
|
|
|
|
#define OAKENGINE_EVENT_TRACK_BLOCK_ADDED 30 /**< handle: OakEngineTrack*. handle field = OakEngineBlock*, a = block in-point (ts), b = block out-point (ts). */
|
|
#define OAKENGINE_EVENT_TRACK_BLOCK_REMOVED 31 /**< handle: OakEngineTrack*. handle field = OakEngineBlock*, a = in (ts), b = out (ts) at removal time. */
|
|
#define OAKENGINE_EVENT_TRACK_INDEX_CHANGED 32 /**< handle: OakEngineTrack*. a = old index, b = new index. */
|
|
#define OAKENGINE_EVENT_TRACK_HEIGHT_CHANGED 33 /**< handle: OakEngineTrack*. a = int64 bit-cast of the new height (double, internal units; memcpy to decode). */
|
|
#define OAKENGINE_EVENT_TRACK_BLOCKS_REFRESHED 34 /**< handle: OakEngineTrack*. no payload (Track::blocks_refreshed). */
|
|
#define OAKENGINE_EVENT_TRACK_MUTED_CHANGED 35 /**< handle: OakEngineTrack*. a = muted 0/1. */
|
|
|
|
#define OAKENGINE_EVENT_BLOCK_ENABLED_CHANGED 36 /**< handle: OakEngineBlock*. no payload (Block::enabled_changed; re-read via oakengine_block_is_enabled). */
|
|
#define OAKENGINE_EVENT_BLOCK_PREVIEW_CHANGED 37 /**< handle: OakEngineBlock*. no payload (Block::preview_changed). */
|
|
|
|
#define OAKENGINE_EVENT_SEQUENCE_MARKER_ADDED 40 /**< handle: OakEngineSequence*. a = marker in-point (ts). */
|
|
#define OAKENGINE_EVENT_SEQUENCE_MARKER_REMOVED 41 /**< handle: OakEngineSequence*. a = marker in-point (ts). */
|
|
#define OAKENGINE_EVENT_SEQUENCE_MARKER_MODIFIED 42 /**< handle: OakEngineSequence*. a = marker in-point (ts). */
|
|
|
|
#define OAKENGINE_EVENT_SEQUENCE_WORKAREA_RANGE_CHANGED 50 /**< handle: OakEngineSequence*. a = in (ts), b = out (ts). */
|
|
#define OAKENGINE_EVENT_SEQUENCE_WORKAREA_ENABLED_CHANGED 51 /**< handle: OakEngineSequence*. a = enabled flag (0/1). */
|
|
|
|
#define OAKENGINE_EVENT_COLOR_MANAGER_CONFIG_CHANGED 60 /**< handle: OakEngineColorManager*. no payload. Fired when the OCIO config changes (ColorManager::config_changed). */
|
|
#define OAKENGINE_EVENT_COLOR_MANAGER_REFERENCE_SPACE_CHANGED 61 /**< handle: OakEngineColorManager*. no payload (ColorManager::reference_space_changed). */
|
|
|
|
/* Node family (handle: OakEngineNode*). `s` carries the input id where
|
|
* noted; frame timestamps use the same timebase as oakengine_node_frame_
|
|
* time_base() (the project's first sequence's frame rate). */
|
|
#define OAKENGINE_EVENT_NODE_LABEL_CHANGED 70 /**< s = new label. */
|
|
#define OAKENGINE_EVENT_NODE_INPUT_VALUE_CHANGED 71 /**< s = input id, a = element, b = range in (ts), c = range out (ts). */
|
|
#define OAKENGINE_EVENT_NODE_INPUT_CONNECTED 72 /**< handle = connected output OakEngineNode*, s = input id, a = element. */
|
|
#define OAKENGINE_EVENT_NODE_INPUT_DISCONNECTED 73 /**< handle = former output OakEngineNode*, s = input id, a = element. */
|
|
#define OAKENGINE_EVENT_NODE_INPUT_FLAGS_CHANGED 74 /**< s = input id, a = new flags (OAKENGINE_NODE_INPUT_FLAG_*). */
|
|
#define OAKENGINE_EVENT_NODE_INPUT_PROPERTY_CHANGED 75 /**< s = input id (property key/value intentionally omitted; re-read through the node family getters). */
|
|
#define OAKENGINE_EVENT_NODE_INPUT_DATA_TYPE_CHANGED 76 /**< s = input id, a = new oak_node_value_type. */
|
|
#define OAKENGINE_EVENT_NODE_INPUT_ARRAY_SIZE_CHANGED 77 /**< s = input id, a = old size, b = new size. */
|
|
#define OAKENGINE_EVENT_NODE_KEYFRAME_ENABLE_CHANGED 78 /**< s = input id, a = element, b = enabled (0/1). */
|
|
#define OAKENGINE_EVENT_NODE_KEYFRAME_ADDED 79 /**< handle = OakEngineKeyframe*, s = input id, a = element, b = track. */
|
|
#define OAKENGINE_EVENT_NODE_KEYFRAME_REMOVED 80 /**< handle = OakEngineKeyframe* (about to die; use the s/a/b fields, do not dereference), s = input id, a = element, b = track. */
|
|
#define OAKENGINE_EVENT_NODE_KEYFRAME_TIME_CHANGED 81 /**< handle = OakEngineKeyframe*. */
|
|
#define OAKENGINE_EVENT_NODE_KEYFRAME_TYPE_CHANGED 82 /**< handle = OakEngineKeyframe*. */
|
|
#define OAKENGINE_EVENT_NODE_KEYFRAME_VALUE_CHANGED 83 /**< handle = OakEngineKeyframe*. */
|
|
#define OAKENGINE_EVENT_NODE_NODE_ADDED_TO_CONTEXT 84 /**< handle = OakEngineNode* added to this context. */
|
|
#define OAKENGINE_EVENT_NODE_NODE_REMOVED_FROM_CONTEXT 85 /**< handle = OakEngineNode* removed from this context. */
|
|
#define OAKENGINE_EVENT_NODE_MESSAGE_COUNT_CHANGED 86 /**< no payload. */
|
|
|
|
/* Group family (handle: OakEngineNode*, must be a group). For 87/88 the
|
|
* handle field carries the passthrough's inner node, `s` its input id and
|
|
* `a` its element. */
|
|
#define OAKENGINE_EVENT_GROUP_INPUT_PASSTHROUGH_ADDED 87 /**< handle = inner OakEngineNode*, s = input id, a = element. */
|
|
#define OAKENGINE_EVENT_GROUP_INPUT_PASSTHROUGH_REMOVED 88 /**< handle = inner OakEngineNode*, s = input id, a = element. */
|
|
#define OAKENGINE_EVENT_GROUP_OUTPUT_PASSTHROUGH_CHANGED 89 /**< handle = new output OakEngineNode*. */
|
|
|
|
/**
|
|
* handle = OakEngineNode* whose position in this context changed; `a`/`b`
|
|
* carry the new x/y scene coordinates as int64 bit-casts of double (use
|
|
* memcpy to decode). */
|
|
#define OAKENGINE_EVENT_NODE_CONTEXT_POSITION_CHANGED 90
|
|
|
|
#define OAKENGINE_EVENT_NODE_LINKS_CHANGED 91 /**< no payload (Node::links_changed). */
|
|
#define OAKENGINE_EVENT_NODE_COLOR_CHANGED 92 /**< no payload (Node::color_changed). */
|
|
#define OAKENGINE_EVENT_NODE_INPUT_ADDED 93 /**< s = input id (Node::input_added). */
|
|
#define OAKENGINE_EVENT_NODE_INPUT_REMOVED 94 /**< s = input id (Node::input_removed). */
|
|
#define OAKENGINE_EVENT_NODE_REMOVED_FROM_GRAPH 95 /**< handle = project OakEngineNode* (Node::removed_from_graph). */
|
|
|
|
/* Viewer family (handle: OakEngineNode*, must be a viewer -- validate with
|
|
* oakengine_viewer_from_node()). Rational payloads (seconds) are carried
|
|
* as a = numerator, b = denominator. */
|
|
#define OAKENGINE_EVENT_VIEWER_LENGTH_CHANGED 100 /**< a/b = new length. */
|
|
#define OAKENGINE_EVENT_VIEWER_PLAYHEAD_CHANGED 101 /**< a/b = new playhead. */
|
|
#define OAKENGINE_EVENT_VIEWER_FRAME_RATE_CHANGED 102 /**< a/b = new frame rate (NOT flipped). */
|
|
#define OAKENGINE_EVENT_VIEWER_SIZE_CHANGED 103 /**< a = width, b = height. */
|
|
#define OAKENGINE_EVENT_VIEWER_PIXEL_ASPECT_CHANGED 104 /**< a/b = new pixel aspect. */
|
|
#define OAKENGINE_EVENT_VIEWER_INTERLACING_CHANGED 105 /**< a = olive::VideoParams::Interlacing. */
|
|
#define OAKENGINE_EVENT_VIEWER_VIDEO_PARAMS_CHANGED 106 /**< no payload. */
|
|
#define OAKENGINE_EVENT_VIEWER_AUDIO_PARAMS_CHANGED 107 /**< no payload. */
|
|
#define OAKENGINE_EVENT_VIEWER_TEXTURE_INPUT_CHANGED 108 /**< no payload. */
|
|
#define OAKENGINE_EVENT_VIEWER_SAMPLE_RATE_CHANGED 109 /**< a = new sample rate. */
|
|
#define OAKENGINE_EVENT_VIEWER_CONNECTED_WAVEFORM_CHANGED 110 /**< no payload. */
|
|
|
|
/* Marker list family (handle: OakEngineMarkerList*, from
|
|
* oakengine_viewer_get_marker_list()). handle field = the OakEngineMarker*
|
|
* (for REMOVED it is about to die; do not dereference). */
|
|
#define OAKENGINE_EVENT_MARKER_LIST_MARKER_ADDED 111
|
|
#define OAKENGINE_EVENT_MARKER_LIST_MARKER_REMOVED 112
|
|
#define OAKENGINE_EVENT_MARKER_LIST_MARKER_MODIFIED 113
|
|
|
|
/* Workarea family (handle: OakEngineWorkarea*, borrowed from
|
|
* oakengine_viewer_get_workarea_handle() or owned from
|
|
* oakengine_workarea_create()). */
|
|
#define OAKENGINE_EVENT_WORKAREA_RANGE_CHANGED 114 /**< no payload; re-read via oakengine_workarea_get(). */
|
|
#define OAKENGINE_EVENT_WORKAREA_ENABLED_CHANGED 115 /**< a = enabled 0/1. */
|
|
|
|
/* Task manager family (handle: oakengine_task_manager_handle(), see
|
|
* oakengine/task.h). The handle field carries the OakEngineTask* (for
|
|
* REMOVED it is about to die; do not dereference). */
|
|
#define OAKENGINE_EVENT_TASK_MANAGER_TASK_ADDED 120 /**< handle = OakEngineTask*, s = task title. */
|
|
#define OAKENGINE_EVENT_TASK_MANAGER_TASK_REMOVED 121 /**< handle = OakEngineTask* (about to die; do not dereference). */
|
|
#define OAKENGINE_EVENT_TASK_MANAGER_TASK_FAILED 122 /**< handle = OakEngineTask*. */
|
|
#define OAKENGINE_EVENT_TASK_MANAGER_LIST_CHANGED 123 /**< no payload. */
|
|
|
|
/* Task family (handle: OakEngineTask*, see oakengine/task.h). Delivered
|
|
* synchronously on the thread the task runs on. */
|
|
#define OAKENGINE_EVENT_TASK_STARTED 125 /**< a = start time (msecs since epoch). */
|
|
#define OAKENGINE_EVENT_TASK_PROGRESS 126 /**< a = int64 bit-cast of the progress double 0..1 (memcpy to decode). */
|
|
#define OAKENGINE_EVENT_TASK_FINISHED 127 /**< a = succeeded 0/1. */
|
|
|
|
/* Undo stack family (handle: oakengine_undo_handle(), see
|
|
* oakengine/undo.h). Fires after every stack mutation (push/undo/redo/
|
|
* jump/clear); re-read the command list through the oakengine_undo_*
|
|
* accessors. */
|
|
#define OAKENGINE_EVENT_UNDO_INDEX_CHANGED 130 /**< a = new index (done-command count). */
|
|
|
|
/* AudioManager family (handle: oakengine_audio_manager_handle(), see
|
|
* oakengine/audio.h). Fired when the output device or format changes. */
|
|
#define OAKENGINE_EVENT_AUDIO_MANAGER_OUTPUT_PARAMS_CHANGED 140 /**< no payload. */
|
|
#define OAKENGINE_EVENT_AUDIO_MANAGER_OUTPUT_NOTIFY 144 /**< no payload; emitted after each notify interval of audio has been consumed. */
|
|
|
|
/* ---- Playback cache / frame cache (B9c) ----------------------------------- */
|
|
#define OAKENGINE_EVENT_PLAYBACK_CACHE_INVALIDATED 141
|
|
#define OAKENGINE_EVENT_PLAYBACK_CACHE_VALIDATED 142
|
|
#define OAKENGINE_EVENT_FRAME_CACHE_INVALIDATED 143
|
|
|
|
/**
|
|
* @brief POD event payload delivered to oakengine_event_fn.
|
|
*/
|
|
typedef struct oakengine_event {
|
|
int32_t id; /**< Event id (OAKENGINE_EVENT_*). */
|
|
int32_t reserved; /**< Alignment padding; 0. */
|
|
int64_t a; /**< Event-specific integer payload (see the event table). */
|
|
int64_t b; /**< Event-specific second integer payload. */
|
|
int64_t c; /**< Event-specific third integer payload. */
|
|
void *source; /**< The subscribed handle the event was delivered for (borrowed). */
|
|
void *handle; /**< Related object, event-specific (borrowed; NULL when none). */
|
|
const char *s; /**< Event-specific string payload (valid only during the callback; NULL when none). */
|
|
} oakengine_event;
|
|
|
|
/**
|
|
* @brief Change-notification callback. Invoked synchronously on the
|
|
* emitting thread; `event` is valid only for the duration of the call.
|
|
*/
|
|
typedef void (*oakengine_event_fn)(const oakengine_event *event,
|
|
void *userdata);
|
|
|
|
/**
|
|
* @brief Subscribe to `event_id` on `handle` (an OakEngineProject*,
|
|
* OakEngineSequence*, OakEngineTrack* or OakEngineNode* per the event
|
|
* table) and return a subscription id (> 0).
|
|
*
|
|
* Returns 0 on failure: NULL handle/callback, unknown event id, or a
|
|
* handle whose engine object does not match the event's family. The
|
|
* callback starts firing with the next matching change; there is no
|
|
* replay of past state.
|
|
*/
|
|
OAKENGINE_API int64_t oakengine_event_subscribe(void *handle, int32_t event_id,
|
|
oakengine_event_fn fn,
|
|
void *userdata);
|
|
|
|
/**
|
|
* @brief Cancel a subscription. OAKENGINE_OK on success,
|
|
* OAKENGINE_E_INVALID for `id` <= 0, OAKENGINE_E_NOT_FOUND for an id that
|
|
* was never registered or whose engine object has since been destroyed.
|
|
*/
|
|
OAKENGINE_API int oakengine_event_unsubscribe(int64_t id);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* OAKENGINE_EVENTS_H */
|