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,186 @@
|
||||
/***
|
||||
|
||||
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_DISPLAY_H
|
||||
#define OAKENGINE_DISPLAY_H
|
||||
|
||||
#include "export.h"
|
||||
#include "init.h"
|
||||
|
||||
#ifdef __cplusplus
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
/**
|
||||
* @file display.h
|
||||
* @brief C ABI for the GPU display renderer used by viewer/scope widgets
|
||||
*
|
||||
* This family wraps the engine's interactive display renderer
|
||||
* (olive::Renderer and its OpenGLRenderer/DynamicRenderer implementations,
|
||||
* engine/render/renderer.h) plus the GPU texture (olive::Texture) and the
|
||||
* CPU frame buffer (olive::Frame) that viewer/scope widgets use to move
|
||||
* pixels between the CPU and the GPU.
|
||||
*
|
||||
* It is distinct from the sequence-rendering facade in oakengine/renderer.h
|
||||
* (OakEngineRenderer), which pulls finished CPU frames out of the async
|
||||
* render pipeline. This family drives the *on-screen* paint path instead:
|
||||
* a widget creates a renderer, initializes it with the widget's GL context,
|
||||
* uploads/downloads textures, and blits color-managed images each paint.
|
||||
*
|
||||
* Conventions (matching the other facade families):
|
||||
* - All object pointers are opaque. `renderer` is an olive::Renderer*,
|
||||
* `texture` an olive::Texture*, `frame` an olive::Frame*.
|
||||
* - `out_texture` / `out_frame` are pointers to caller-owned
|
||||
* olive::TexturePtr / olive::FramePtr (std::shared_ptr) storage; the
|
||||
* callee assigns a newly created smart pointer into them, releasing any
|
||||
* previously held object. This keeps shared-pointer ownership/deleter
|
||||
* bookkeeping entirely on the engine side.
|
||||
* - `video_params` is a `const olive::VideoParams*`; `color_job` is a
|
||||
* `const olive::ColorTransformJob*`. These are passed as opaque pointers
|
||||
* because they are C++ types; both the caller (app) and the callee
|
||||
* (engine) are compiled as C++ against the same headers.
|
||||
* - `gl_context` is a `QOpenGLContext*` or NULL.
|
||||
* - `parent` is the owning `QObject*` (the display widget); the created
|
||||
* renderer is a QObject child of it and is destroyed by Qt ownership.
|
||||
* Do NOT call oakengine_display_renderer_destroy() and then also rely on
|
||||
* Qt deletion of the same renderer's GPU resources -- destroy() releases
|
||||
* GPU state, Qt deletion releases the object.
|
||||
*/
|
||||
|
||||
/* ---- Display renderer lifecycle ---------------------------------------- */
|
||||
|
||||
/**
|
||||
* @brief Create a dynamic-backend renderer (olive::DynamicRenderer) for
|
||||
* `backend_name` and load() it.
|
||||
*
|
||||
* @return The renderer (olive::Renderer*), or NULL if the backend library
|
||||
* could not be loaded (the failed renderer is deleted internally and
|
||||
* the caller should fall back to
|
||||
* oakengine_display_renderer_create_opengl()). NULL is also returned
|
||||
* when the engine was built without dynamic-backend support.
|
||||
*/
|
||||
OAKENGINE_API void *
|
||||
oakengine_display_renderer_create_dynamic(const char *backend_name,
|
||||
void *parent);
|
||||
|
||||
/**
|
||||
* @brief Create the built-in OpenGL renderer (olive::OpenGLRenderer).
|
||||
*
|
||||
* @return The renderer (olive::Renderer*), never NULL.
|
||||
*/
|
||||
OAKENGINE_API void *oakengine_display_renderer_create_opengl(void *parent);
|
||||
|
||||
/**
|
||||
* @brief Initialize a display renderer and run its post-init step.
|
||||
*
|
||||
* If `gl_context` is non-NULL the OpenGL/dynamic path is taken (the renderer
|
||||
* is initialized against the widget's shared QOpenGLContext); otherwise the
|
||||
* backend-neutral path (Renderer::init()/post_init()) is used.
|
||||
*
|
||||
* @return OAKENGINE_OK on success, OAKENGINE_E_INVALID for a NULL renderer.
|
||||
*/
|
||||
OAKENGINE_API int oakengine_display_renderer_init(void *renderer,
|
||||
void *gl_context);
|
||||
|
||||
/**
|
||||
* @brief Release a display renderer's GPU resources (Renderer::destroy()
|
||||
* followed by post_destroy()). The renderer object itself remains owned by
|
||||
* its Qt parent.
|
||||
*/
|
||||
OAKENGINE_API void oakengine_display_renderer_destroy(void *renderer);
|
||||
|
||||
/* ---- Texture creation and pixel transfer -------------------------------- */
|
||||
|
||||
/**
|
||||
* @brief Create a GPU texture on `renderer` (Renderer::create_texture()).
|
||||
*
|
||||
* @param renderer olive::Renderer*.
|
||||
* @param video_params const olive::VideoParams* describing the texture.
|
||||
* @param pixels Initial pixel data, or NULL for an empty texture.
|
||||
* @param linesize Line stride of `pixels` (ignored when NULL).
|
||||
* @param out_texture Pointer to an olive::TexturePtr to receive the result.
|
||||
*/
|
||||
OAKENGINE_API void
|
||||
oakengine_display_renderer_create_texture(void *renderer,
|
||||
const void *video_params,
|
||||
const void *pixels, int linesize,
|
||||
void *out_texture);
|
||||
|
||||
/**
|
||||
* @brief Blit a color-managed image (Renderer::blit_color_managed()).
|
||||
*
|
||||
* @param renderer olive::Renderer*.
|
||||
* @param color_job const olive::ColorTransformJob*.
|
||||
* @param dst_texture Destination olive::Texture*, or NULL to blit to the
|
||||
* current output destination.
|
||||
* @param video_params const olive::VideoParams* for the destination, or NULL
|
||||
* to use dst_texture's own parameters (in which case
|
||||
* dst_texture must be non-NULL).
|
||||
*/
|
||||
OAKENGINE_API void
|
||||
oakengine_display_renderer_blit_color_managed(void *renderer,
|
||||
const void *color_job,
|
||||
void *dst_texture,
|
||||
const void *video_params);
|
||||
|
||||
/**
|
||||
* @brief Upload CPU pixels into a GPU texture (Texture::upload()).
|
||||
*/
|
||||
OAKENGINE_API void oakengine_display_texture_upload(void *texture,
|
||||
void *pixels, int linesize);
|
||||
|
||||
/**
|
||||
* @brief Download GPU texture pixels into CPU memory (Texture::download()).
|
||||
*/
|
||||
OAKENGINE_API void oakengine_display_texture_download(void *texture,
|
||||
void *pixels,
|
||||
int linesize);
|
||||
|
||||
/* ---- CPU frame buffer --------------------------------------------------- */
|
||||
|
||||
/**
|
||||
* @brief Create an empty CPU frame (olive::Frame::create()).
|
||||
*
|
||||
* @param out_frame Pointer to an olive::FramePtr to receive the new frame.
|
||||
*/
|
||||
OAKENGINE_API void oakengine_codec_frame_create(void *out_frame);
|
||||
|
||||
/**
|
||||
* @brief Set a frame's video parameters (Frame::set_video_params()).
|
||||
*
|
||||
* @param frame olive::Frame*.
|
||||
* @param video_params const olive::VideoParams*.
|
||||
*/
|
||||
OAKENGINE_API void oakengine_codec_frame_set_video_params(void *frame,
|
||||
const void
|
||||
*video_params);
|
||||
|
||||
/**
|
||||
* @brief Allocate the frame's pixel buffer (Frame::allocate()).
|
||||
*
|
||||
* @return 1 on success, 0 on failure or NULL frame.
|
||||
*/
|
||||
OAKENGINE_API int oakengine_codec_frame_allocate(void *frame);
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif
|
||||
|
||||
#endif /* OAKENGINE_DISPLAY_H */
|
||||
Reference in New Issue
Block a user