engine: complete C ABI facade (liboakengine oakengine_* surface)
The full pure-C facade used by the app: node/project/timeline/viewer/ undo/task/events/serializer/playback/preview/renderer/gizmo/color/ audio/footage/proxy/encoding/exporter/config/disk/ipc/plugin/worker families, plus undo-group semantics, display renderer handles, NodeFactory accessors, and per-family pure-C engine tests.
This commit is contained in:
@@ -0,0 +1,254 @@
|
||||
/***
|
||||
|
||||
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_SERIALIZER_H
|
||||
#define OAKENGINE_SERIALIZER_H
|
||||
|
||||
#include "export.h"
|
||||
#include "init.h"
|
||||
#include "node.h"
|
||||
#include "project.h"
|
||||
|
||||
#ifdef __cplusplus
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
/**
|
||||
* @file serializer.h
|
||||
* @brief C ABI for project serialization / copy-paste (olive::ProjectSerializer)
|
||||
*
|
||||
* A thin facade over ProjectSerializer's load/save/copy/paste primitives. The
|
||||
* opaque OakEngineClipboard handle bundles a SaveData object (for copy/save)
|
||||
* or the LoadData result of the last paste operation. Clipboard handles are
|
||||
* owned by the caller and must be released with oakengine_clipboard_free().
|
||||
*
|
||||
* Conventions match the other facade families:
|
||||
* - 0 (OAKENGINE_OK) / negative OAKENGINE_E_* codes.
|
||||
* - String output uses the buf/size convention.
|
||||
*/
|
||||
|
||||
/** @brief Opaque clipboard context. */
|
||||
typedef struct OakEngineClipboard OakEngineClipboard;
|
||||
|
||||
/** @brief Marker handle (defined in oakengine/timeline.h). */
|
||||
typedef struct OakEngineMarker OakEngineMarker;
|
||||
|
||||
#define OAKENGINE_CLIPBOARD_PROJECT 0
|
||||
#define OAKENGINE_CLIPBOARD_NODES 1
|
||||
#define OAKENGINE_CLIPBOARD_CLIPS 2
|
||||
#define OAKENGINE_CLIPBOARD_MARKERS 3
|
||||
#define OAKENGINE_CLIPBOARD_KEYFRAMES 4
|
||||
|
||||
#define OAKENGINE_SERIALIZER_OK 0
|
||||
#define OAKENGINE_SERIALIZER_TOO_OLD 1
|
||||
#define OAKENGINE_SERIALIZER_TOO_NEW 2
|
||||
#define OAKENGINE_SERIALIZER_UNKNOWN_VERSION 3
|
||||
#define OAKENGINE_SERIALIZER_FILE_ERROR 4
|
||||
#define OAKENGINE_SERIALIZER_XML_ERROR 5
|
||||
#define OAKENGINE_SERIALIZER_OVERWRITE_ERROR 6
|
||||
#define OAKENGINE_SERIALIZER_NO_DATA 7
|
||||
|
||||
/**
|
||||
* @brief Returns 1 if `filename` is a compressed project file, 0 otherwise.
|
||||
*/
|
||||
OAKENGINE_API int oakengine_serializer_check_compressed(const char *filename);
|
||||
|
||||
/**
|
||||
* @brief Create a clipboard context for copy/save operations.
|
||||
*
|
||||
* `load_type` is one of OAKENGINE_CLIPBOARD_*. `project` may be NULL for
|
||||
* load types that do not require it. `filename` may be NULL.
|
||||
*/
|
||||
OAKENGINE_API OakEngineClipboard *oakengine_clipboard_create(
|
||||
int load_type, OakEngineProject *project, const char *filename);
|
||||
|
||||
/**
|
||||
* @brief Set the nodes to serialize on this clipboard.
|
||||
*
|
||||
* Replaces any previously set nodes. `nodes` is an array of `count` borrowed
|
||||
* OakEngineNode handles. Returns OAKENGINE_OK or an error code.
|
||||
*/
|
||||
OAKENGINE_API int oakengine_clipboard_set_nodes(OakEngineClipboard *cb,
|
||||
const OakEngineNode *const *nodes,
|
||||
int count);
|
||||
|
||||
/**
|
||||
* @brief Set the markers to serialize on this clipboard.
|
||||
*/
|
||||
OAKENGINE_API int oakengine_clipboard_set_markers(
|
||||
OakEngineClipboard *cb, const OakEngineMarker *const *markers, int count);
|
||||
|
||||
/**
|
||||
* @brief Set the keyframes to serialize on this clipboard.
|
||||
*/
|
||||
OAKENGINE_API int oakengine_clipboard_set_keyframes(
|
||||
OakEngineClipboard *cb, const OakEngineKeyframe *const *keyframes,
|
||||
int count);
|
||||
|
||||
/**
|
||||
* @brief Set a serialized property attached to a node.
|
||||
*
|
||||
* Properties are free-form (key, value) strings attached to pasted nodes; the
|
||||
* editor uses them for clip in-points/track-refs and node graph positions.
|
||||
* Replaces the value if the same (node, key) pair is set twice. Returns
|
||||
* OAKENGINE_OK or an error code.
|
||||
*/
|
||||
OAKENGINE_API int oakengine_clipboard_set_property(OakEngineClipboard *cb,
|
||||
OakEngineNode *node,
|
||||
const char *key,
|
||||
const char *value);
|
||||
|
||||
/**
|
||||
* @brief Copy this clipboard's data to the system clipboard.
|
||||
*
|
||||
* Returns OAKENGINE_OK or an error code.
|
||||
*/
|
||||
OAKENGINE_API int oakengine_clipboard_copy(OakEngineClipboard *cb);
|
||||
|
||||
/**
|
||||
* @brief Serialize this clipboard's data to XML (buf/size convention).
|
||||
*
|
||||
* Returns the string length on success, or a negative OAKENGINE_E_* code on
|
||||
* error.
|
||||
*/
|
||||
OAKENGINE_API int oakengine_clipboard_save_to_xml(OakEngineClipboard *cb,
|
||||
char *buf, int buf_size);
|
||||
|
||||
/**
|
||||
* @brief Paste data from the system clipboard into `project`.
|
||||
*
|
||||
* `load_type` selects what kind of data to paste. On success `*result_code`
|
||||
* receives OAKENGINE_SERIALIZER_OK and the clipboard is populated with the
|
||||
* paste result (accessible through the oakengine_clipboard_get_loaded_*
|
||||
* accessors). On failure `*result_code` receives one of the
|
||||
* OAKENGINE_SERIALIZER_* error codes and a human-readable detail string is
|
||||
* written to `details_buf` (may be NULL). Returns OAKENGINE_OK on success or
|
||||
* an error code.
|
||||
*/
|
||||
OAKENGINE_API int oakengine_clipboard_paste(OakEngineClipboard *cb,
|
||||
int load_type,
|
||||
OakEngineProject *project,
|
||||
int *result_code,
|
||||
char *details_buf,
|
||||
int details_buf_size);
|
||||
|
||||
/**
|
||||
* @brief Paste data from the system clipboard, invoking `map_fn` for each
|
||||
* original->new node mapping.
|
||||
*
|
||||
* The callback is called once per (original node pointer, pasted node pointer)
|
||||
* pair found in the paste result. The app can use it to build an existing-node
|
||||
* map without exposing C++ containers across the boundary. Returning non-zero
|
||||
* from the callback stops iteration early. Other semantics match
|
||||
* oakengine_clipboard_paste().
|
||||
*/
|
||||
OAKENGINE_API int oakengine_clipboard_paste_with_map(
|
||||
OakEngineClipboard *cb, int load_type, OakEngineProject *project,
|
||||
int (*map_fn)(OakEngineNode *old, OakEngineNode *new_node, void *userdata),
|
||||
void *userdata, int *result_code, char *details_buf,
|
||||
int details_buf_size);
|
||||
|
||||
/**
|
||||
* @brief Destroy a clipboard context.
|
||||
*/
|
||||
OAKENGINE_API void oakengine_clipboard_free(OakEngineClipboard *cb);
|
||||
|
||||
/* ---- Paste result accessors (valid after a successful paste) -------------- */
|
||||
|
||||
/**
|
||||
* @brief Number of nodes loaded by the last paste operation.
|
||||
*/
|
||||
OAKENGINE_API int oakengine_clipboard_get_loaded_node_count(
|
||||
OakEngineClipboard *cb);
|
||||
|
||||
/**
|
||||
* @brief Borrowed node handle loaded at `index`.
|
||||
*/
|
||||
OAKENGINE_API OakEngineNode *oakengine_clipboard_get_loaded_node_at(
|
||||
OakEngineClipboard *cb, int index);
|
||||
|
||||
/**
|
||||
* @brief Number of markers loaded by the last paste operation.
|
||||
*/
|
||||
OAKENGINE_API int oakengine_clipboard_get_loaded_marker_count(
|
||||
OakEngineClipboard *cb);
|
||||
|
||||
/**
|
||||
* @brief Borrowed marker handle loaded at `index`.
|
||||
*/
|
||||
OAKENGINE_API OakEngineMarker *oakengine_clipboard_get_loaded_marker_at(
|
||||
OakEngineClipboard *cb, int index);
|
||||
|
||||
/**
|
||||
* @brief Number of keyframes loaded by the last paste operation.
|
||||
*/
|
||||
OAKENGINE_API int oakengine_clipboard_get_loaded_keyframe_count(
|
||||
OakEngineClipboard *cb);
|
||||
|
||||
/**
|
||||
* @brief Borrowed keyframe handle loaded at `index`.
|
||||
*/
|
||||
OAKENGINE_API OakEngineKeyframe *oakengine_clipboard_get_loaded_keyframe_at(
|
||||
OakEngineClipboard *cb, int index);
|
||||
|
||||
/**
|
||||
* @brief Iterate over the serialized properties attached to pasted nodes.
|
||||
*
|
||||
* For each (node, key, value) triple `fn` is called. Returning non-zero stops
|
||||
* iteration early. Returns OAKENGINE_OK or an error code.
|
||||
*/
|
||||
OAKENGINE_API int oakengine_clipboard_foreach_property(
|
||||
OakEngineClipboard *cb,
|
||||
int (*fn)(OakEngineNode *node, const char *key, const char *value,
|
||||
void *userdata),
|
||||
void *userdata);
|
||||
|
||||
/**
|
||||
* @brief Iterate over keyframes loaded by the last paste operation.
|
||||
*
|
||||
* For each keyframe `fn` is called with the node id string it belongs to and
|
||||
* the keyframe handle. Returning non-zero stops iteration early. The app can
|
||||
* group keyframes by node id and route them to the correct destination node.
|
||||
* Returns OAKENGINE_OK or an error code.
|
||||
*/
|
||||
OAKENGINE_API int oakengine_clipboard_foreach_keyframe(
|
||||
OakEngineClipboard *cb,
|
||||
int (*fn)(const char *node_id, OakEngineKeyframe *keyframe,
|
||||
void *userdata),
|
||||
void *userdata);
|
||||
|
||||
/**
|
||||
* @brief Iterate over promised connections from the paste result.
|
||||
*
|
||||
* For each promised edge `fn` is called with the output node, input node,
|
||||
* input id and element index. Returning non-zero stops iteration early.
|
||||
* Returns OAKENGINE_OK or an error code.
|
||||
*/
|
||||
OAKENGINE_API int oakengine_clipboard_foreach_connection(
|
||||
OakEngineClipboard *cb,
|
||||
int (*fn)(OakEngineNode *output_node, OakEngineNode *input_node,
|
||||
const char *input_id, int element, void *userdata),
|
||||
void *userdata);
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif
|
||||
|
||||
#endif /* OAKENGINE_SERIALIZER_H */
|
||||
Reference in New Issue
Block a user