Mike-Solar
e9f173916f
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.
187 lines
7.0 KiB
C++
187 lines
7.0 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_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 */
|