Mike-Solar
67176281d9
- 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
268 lines
8.6 KiB
C
268 lines
8.6 KiB
C
/***
|
|
|
|
Oak Video Editor - 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 OAK_EDITOR_NODE_PROJECT_H
|
|
#define OAK_EDITOR_NODE_PROJECT_H
|
|
|
|
#include <stdint.h>
|
|
|
|
#include "node/error.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/**
|
|
* @file project.h
|
|
* @brief C ABI for olive::Project (oaknode)
|
|
*
|
|
* 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 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
|
|
* failure.
|
|
* - String getters are two-stage: pass buf == NULL (or a short buffer) to
|
|
* 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.
|
|
* - 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 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 {
|
|
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 Node handle (defined by the node family; forward-declared
|
|
* here so the headers can be included in any order).
|
|
*/
|
|
typedef struct OakNodeNode OakNodeNode;
|
|
|
|
/**
|
|
* @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;
|
|
|
|
/**
|
|
* @brief Create an empty project shell.
|
|
*
|
|
* The project has no root folder until oaknode_project_initialize() is
|
|
* called (mirrors Project::initialize()).
|
|
*
|
|
* @return Project handle with reference count 1 (release with
|
|
* oaknode_project_free()); ctx is NULL on allocation failure.
|
|
*/
|
|
OakNodeProject oaknode_project_init(void);
|
|
|
|
/**
|
|
* @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);
|
|
|
|
/**
|
|
* @brief Initialize the project: create the root folder (Project::initialize()).
|
|
*
|
|
* @return OAKNODE_OK, or OAKNODE_E_STATE if already initialized.
|
|
*/
|
|
int oaknode_project_initialize(OakNodeProject project);
|
|
|
|
/**
|
|
* @brief Destructively destroy all nodes in the graph (Project::clear()).
|
|
*
|
|
* The project shell stays usable; oaknode_project_initialize() may be called
|
|
* again afterwards.
|
|
*
|
|
* @return OAKNODE_OK or a negative OAKNODE_E_* error code.
|
|
*/
|
|
int oaknode_project_clear(OakNodeProject project);
|
|
|
|
/**
|
|
* @brief Borrowed handle of the project's root folder (Project::root()).
|
|
*
|
|
* 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);
|
|
|
|
/**
|
|
* @brief Project display name (Project::name(): the filename's base name, or
|
|
* "(untitled)"). Two-stage string getter.
|
|
*
|
|
* @return Required buffer size in bytes including the NUL, or a negative
|
|
* OAKNODE_E_* error code.
|
|
*/
|
|
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(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(OakNodeProject project, char *buf,
|
|
int buf_size);
|
|
|
|
/**
|
|
* @brief Set the project's filename (Project::set_filename()).
|
|
*
|
|
* @return OAKNODE_OK or a negative OAKNODE_E_* error code.
|
|
*/
|
|
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 an empty handle.
|
|
*/
|
|
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);
|
|
|
|
/**
|
|
* @brief 1 if the project is new (untitled and unmodified, Project::is_new()).
|
|
* Negative OAKNODE_E_* code on an empty handle.
|
|
*/
|
|
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(OakNodeProject project, char *buf,
|
|
int buf_size);
|
|
|
|
/**
|
|
* @brief Copy all project settings (Project::copy_settings()).
|
|
*/
|
|
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 an
|
|
* empty handle.
|
|
*/
|
|
int oaknode_project_get_cache_location_setting(OakNodeProject project);
|
|
|
|
/**
|
|
* @brief Set the cache location setting (0/1/2, see
|
|
* oaknode_project_get_cache_location_setting()).
|
|
*
|
|
* @return OAKNODE_OK or a negative OAKNODE_E_* error code.
|
|
*/
|
|
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(OakNodeProject project,
|
|
char *buf, int buf_size);
|
|
|
|
/**
|
|
* @brief Set a custom cache directory (Project::set_custom_cache_path()).
|
|
* NULL clears it.
|
|
*
|
|
* @return OAKNODE_OK or a negative OAKNODE_E_* error code.
|
|
*/
|
|
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(OakNodeProject project, char *buf,
|
|
int buf_size);
|
|
|
|
/**
|
|
* @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);
|
|
|
|
/**
|
|
* @brief Detach a node from the graph without deleting it
|
|
* (Project::remove_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);
|
|
|
|
/**
|
|
* @brief Number of nodes belonging to the graph (Project::nodes().size()).
|
|
* Negative OAKNODE_E_* code on an empty handle.
|
|
*/
|
|
int oaknode_project_node_count(OakNodeProject project);
|
|
|
|
/**
|
|
* @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(OakNodeProject project, int index);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif //OAK_EDITOR_NODE_PROJECT_H
|