docs/sphinx/reference-canvases.rst
.. danger::
Canvases are still in their early stages of implementation and the API will evolve as they are gradually integrated across OBS Studio.
The Canvas API should be considered unstable and may be changed without warning. This documentation serves to aid in their iterative development within OBS Studio.
If you are developing a plugin that utilizes canvases, proceed with great caution.
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 <obs.h>
.. _canvas_signal_handler_reference:
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.
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:
Additionally, the following preset combinations of flags are defined:
ACTIVATE | MIX_AUDIO | SCENE_REFEPHEMERALACTIVATE | EPHEMERAL.. 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
.. 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
.. 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
.. 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.
.. 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.
.. 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.