From 3fc119190e9d9f1ca5af01bc2b994d03ae3af896 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dennis=20S=C3=A4dtler?= Date: Tue, 4 Feb 2025 12:25:03 +0100 Subject: [PATCH] docs: Add canvases documentation --- docs/sphinx/reference-canvases.rst | 292 +++++++++++++++++++++++++++++ docs/sphinx/reference-core.rst | 56 ++++++ docs/sphinx/reference-sources.rst | 7 + 3 files changed, 355 insertions(+) create mode 100644 docs/sphinx/reference-canvases.rst diff --git a/docs/sphinx/reference-canvases.rst b/docs/sphinx/reference-canvases.rst new file mode 100644 index 000000000..1edf7be08 --- /dev/null +++ b/docs/sphinx/reference-canvases.rst @@ -0,0 +1,292 @@ +Canvas API Reference (obs_canvas_t) +=================================== + +Canvases are reference-counted objects that contain scenes and define how those are rendered. +They provide a video object which can be used with encoders or raw outputs. + +libobs maintains a main canvas that exists at all times and is used for the default video outputs. + +.. type:: obs_canvas_t + + A reference-counted canvas. + +.. type:: obs_weak_canvas_t + + A weak reference to a canvas. + +.. code:: cpp + + #include + +.. _canvas_signal_handler_reference: + +Canvas Signals +-------------- + +The following signals are defined for canvases: + +**remove** (ptr canvas) + + Called when the :c:func:`obs_canvas_remove()` function is called on the canvas. + +**destroy** (ptr canvas) + + Called when a canvas is about to be destroyed. + +**video_reset** (ptr canvas) + + Called when the canvas's video mix has been reset after a call to + :c:func:`obs_reset_video()` or :c:func:`obs_canvas_reset_video()`. + +**source_add** (ptr canvas, ptr source) + + Called when a source has been added to the canvas. + +**source_remove** (ptr canvas, ptr source) + + Called when a source has been removed from the canvas. + +**rename** (ptr canvas, string new_name, string prev_name) + + Called when the canvas has been renamed. + +**channel_change** (ptr canvas, int channel, in out ptr source, ptr prev_source) + + Called when a channel source has been changed. + +Canvas Flags +------------ + +Canvases can have different behaviors, these can be controlled via the **flags** parameter when creating a canvas. + +Flags may be `0` or a bitwise `OR` combination of the following values: + +- **MAIN** - Main canvas, cannot be renamed or reset, cannot be set by user +- **ACTIVATE** - Canvas's sources will become active when they are visible +- **MIX_AUDIO** - Audio from channels in this canvas will be mixed into the audio output +- **SCENE_REF** - Canvas will hold references for scene sources +- **EPHEMERAL** - Indicates this canvas is not supposed to be saved + +Additionally, the following preset combinations of flags are defined: + +- **PROGRAM** which equals `ACTIVATE | MIX_AUDIO | SCENE_REF` +- **PREVIEW** which equals `EPHEMERAL` +- **DEVICE** which equals `ACTIVATE | EPHEMERAL` + +General Canvas Functions +------------------------ + +.. function:: obs_canvas_t *obs_get_main_canvas() + + Get a strong reference to the main OBS canvas. + +--------------------- + +.. function:: obs_canvas_t *obs_canvas_create(const char *name, struct obs_video_info *ovi, uint32_t flags) + + Creates a new canvas. + + :param name: Name, will be deduplicated if necessary + :param ovi: Video configuration to use for this canvas's video output + :param flags: Canvas flags + :return: Canvas object + +--------------------- + +.. function:: obs_canvas_t *obs_canvas_create_private(const char *name, struct obs_video_info *ovi, uint32_t flags) + + Creates a new private canvas. + + :param name: Name, will **not** be deduplicated + :param ovi: Video configuration to use for this canvas's video output + :param flags: Canvas flags + :return: Canvas object + +--------------------- + +.. function:: void obs_canvas_remove(obs_canvas_t *canvas) + + Signal that references to canvas should be released and mark the canvas as removed. + +--------------------- + +.. function:: bool obs_canvas_removed(obs_canvas_t *canvas) + + Returns if a canvas is marked as removed (i.e., should no longer be used). + +--------------------- + +.. function:: void obs_canvas_set_name(obs_canvas_t *canvas, const char *name) + + Set canvas name + +--------------------- + +.. function:: const char *obs_canvas_get_name(const obs_canvas_t *canvas) + + Get canvas name + +--------------------- + +.. function:: const char *obs_canvas_get_uuid(const obs_canvas_t *canvas) + + Get canvas UUID + +--------------------- + +.. function:: uint32_t obs_canvas_get_flags(const obs_canvas_t *canvas) + + Gets flags set on a canvas + +--------------------- + +Saving/Loading Functions +------------------------ + +.. function:: obs_data_t *obs_save_canvas(obs_canvas_t *source) + + Saves a canvas to settings data + +--------------------- + +.. function:: obs_canvas_t *obs_load_canvas(obs_data_t *data) + + Loads a canvas from settings data + +--------------------- + +Reference Counting Functions +---------------------------- + +.. function:: obs_canvas_t *obs_canvas_get_ref(obs_canvas_t *canvas) + + Add strong reference to a canvas + +--------------------- + +.. function:: void obs_canvas_release(obs_canvas_t *canvas) + + Release strong reference + +--------------------- + +.. function:: void obs_weak_canvas_addref(obs_weak_canvas_t *weak) + + Add weak reference + +--------------------- + +.. function:: void obs_weak_canvas_release(obs_weak_canvas_t *weak) + + Release weak reference + +--------------------- + +.. function:: obs_weak_canvas_t *obs_canvas_get_weak_canvas(obs_canvas_t *canvas) + + Get weak reference from strong reference + +--------------------- + +.. function:: obs_canvas_t *obs_weak_canvas_get_canvas(obs_weak_canvas_t *weak) + + Get strong reference from weak reference + +--------------------- + +Canvas Channel Functions +------------------------ + +.. function:: void obs_canvas_set_channel(obs_canvas_t *canvas, uint32_t channel, obs_source_t *source) + + Sets the source to be used for a canvas channel. + +--------------------- + +.. function:: obs_source_t *obs_canvas_get_channel(obs_canvas_t *canvas, uint32_t channel) + + Gets the source currently in use for a canvas channel. + +--------------------- + +Canvas Source List Functions +---------------------------- + +.. function:: obs_scene_t *obs_canvas_scene_create(obs_canvas_t *canvas, const char *name) + + Create scene attached to a canvas. + +--------------------- + +.. function:: void obs_canvas_scene_remove(obs_scene_t *scene) + + Remove a scene from a canvas. + +--------------------- + +.. function:: void obs_canvas_move_scene(obs_scene_t *scene, obs_canvas_t *dst) + + Move scene to another canvas, detaching it from the previous one and deduplicating the name if needed. + +--------------------- + +.. function:: void obs_canvas_enum_scenes(obs_canvas_t *canvas, bool (*enum_proc)(void *, obs_source_t *), void *param) + + Enumerates scenes belonging to a canvas. + + Callback function returns true to continue enumeration, or false to end enumeration. + +--------------------- + +.. function:: obs_source_t *obs_canvas_get_source_by_name(const char *name) + + Gets a canvas source by its name. + + Increments the source reference counter, use + :c:func:`obs_source_release()` to release it when complete. + +--------------------- + +.. function:: obs_scene_t *obs_canvas_get_scene_by_name(const char *name) + + Gets a canvas scene by its name. + + Increments the source reference counter, use + :c:func:`obs_scene_release()` to release it when complete. + +--------------------- + +Canvas Video Functions +---------------------- + +.. function:: bool obs_canvas_reset_video(obs_canvas_t *canvas, struct obs_video_info *ovi) + + Reset a canvas's video configuration. + + Note that the frame rate property is ignored and the global rendering frame rate is used instead. + +--------------------- + +.. function:: bool obs_canvas_has_video(obs_canvas_t *canvas) + + Returns true if the canvas video is configured. + +--------------------- + +.. function:: video_t *obs_canvas_get_video(const obs_canvas_t *canvas) + + Get canvas video output + +--------------------- + +.. function:: bool obs_canvas_get_video_info(const obs_canvas_t *canvas, struct obs_video_info *ovi) + + Get canvas video info (if any) + +--------------------- + +.. function:: void obs_canvas_render(obs_canvas_t *canvas) + + Render the canvas's view. Must be called on the graphics thread. + +--------------------- diff --git a/docs/sphinx/reference-core.rst b/docs/sphinx/reference-core.rst index ac5f9c445..31370c3e1 100644 --- a/docs/sphinx/reference-core.rst +++ b/docs/sphinx/reference-core.rst @@ -324,6 +324,19 @@ Libobs Objects --------------------- +.. function:: void obs_enum_canvases(bool (*enum_proc)(void*, obs_canvas_t*), void *param) + + Enumerates canvases. + + Callback function returns true to continue enumeration, or false to end + enumeration. + + Use :c:func:`obs_canvas_get_ref()` or + :c:func:`obs_canvas_get_weak_encoder()` if you want to retain a + reference after obs_enum_canvases finishes. + +--------------------- + .. function:: obs_source_t *obs_get_source_by_name(const char *name) Gets a source by its name. @@ -406,6 +419,24 @@ Libobs Objects --------------------- +.. function:: obs_canvas_t *obs_get_canvas_by_name(const char *name) + + Get a canvas by its name. + + Increments the canvas reference counter, use + :c:func:`obs_canvas_release()` to release it when complete. + +--------------------- + +.. function:: obs_canvas_t *obs_get_canvas_by_uuid(const char *uuid) + + Get a canvas by its UUID. + + Increments the canvas reference counter, use + :c:func:`obs_canvas_release()` to release it when complete. + +--------------------- + .. function:: obs_data_t *obs_save_source(obs_source_t *source) :return: A new reference to a source's saved data. Use @@ -724,6 +755,31 @@ Core OBS Signals Called when a hotkey's bindings has changed. +**canvas_create** (ptr canvas) + + Called when a new public canvas has been created. + +**canvas_remove** (ptr canvas) + + Called when the :c:func:`obs_canvas_remove()` function is called on a public canvas. + +**canvas_destroy** (ptr canvas) + + Called when a public canvas is about to be destroyed. + +**canvas_video_reset** (ptr canvas) + + Called when a public canvas's video mix has been reset after a call to + :c:func:`obs_reset_video()` or :c:func:`obs_canvas_reset_video()`. + +**canvas_rename** (ptr canvas, string new_name, string prev_name) + + Called when a public canvas has been renamed. + +**video_reset** () + + Called when a the main OBS video has been reset. + --------------------- diff --git a/docs/sphinx/reference-sources.rst b/docs/sphinx/reference-sources.rst index 4729e055d..a6e7aed33 100644 --- a/docs/sphinx/reference-sources.rst +++ b/docs/sphinx/reference-sources.rst @@ -176,6 +176,8 @@ Source Definition Structure (obs_source_info) to have its properties shown on creation (prefers to rely on defaults first) + - **OBS_SOURCE_REQUIRES_CANVAS** - Source type requires a canvas. + .. member:: const char *(*obs_source_info.get_name)(void *type_data) Get the translated name of the source type. @@ -1500,6 +1502,11 @@ General Source Functions --------------------- +.. function:: obs_canvas_t *obs_source_get_canvas(const obs_source_t *source) + + Get canvas this source belongs to (reference incremented) + +--------------------- Functions used by sources -------------------------