Canvas API Reference (obs_canvas_t)

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.

#include <obs.h>

Canvas Signals

The following signals are defined for canvases:

remove (ptr canvas)

Called when the 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 obs_reset_video() or 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

obs_canvas_t *obs_get_main_canvas()

Get a strong reference to the main OBS canvas.

obs_canvas_t *obs_canvas_create(const char *name, struct obs_video_info *ovi, uint32_t flags)

Creates a new canvas.

Parameters:

  • name – Name, will be deduplicated if necessary

  • ovi – Video configuration to use for this canvas’s video output

  • flags – Canvas flags

Returns:

Canvas object

obs_canvas_t *obs_canvas_create_private(const char *name, struct obs_video_info *ovi, uint32_t flags)

Creates a new private canvas.

Parameters:

  • name – Name, will not be deduplicated

  • ovi – Video configuration to use for this canvas’s video output

  • flags – Canvas flags

Returns:

Canvas object

void obs_canvas_remove(obs_canvas_t *canvas)

Signal that references to canvas should be released and mark the canvas as removed.

bool obs_canvas_removed(obs_canvas_t *canvas)

Returns if a canvas is marked as removed (i.e., should no longer be used).

void obs_canvas_set_name(obs_canvas_t *canvas, const char *name)

Set canvas name

const char *obs_canvas_get_name(const obs_canvas_t *canvas)

Get canvas name

const char *obs_canvas_get_uuid(const obs_canvas_t *canvas)

Get canvas UUID

uint32_t obs_canvas_get_flags(const obs_canvas_t *canvas)

Gets flags set on a canvas

Saving/Loading Functions

obs_data_t *obs_save_canvas(obs_canvas_t *source)

Saves a canvas to settings data

obs_canvas_t *obs_load_canvas(obs_data_t *data)

Loads a canvas from settings data

Reference Counting Functions

obs_canvas_t *obs_canvas_get_ref(obs_canvas_t *canvas)

Add strong reference to a canvas

void obs_canvas_release(obs_canvas_t *canvas)

Release strong reference

void obs_weak_canvas_addref(obs_weak_canvas_t *weak)

Add weak reference

void obs_weak_canvas_release(obs_weak_canvas_t *weak)

Release weak reference

obs_weak_canvas_t *obs_canvas_get_weak_canvas(obs_canvas_t *canvas)

Get weak reference from strong reference

obs_canvas_t *obs_weak_canvas_get_canvas(obs_weak_canvas_t *weak)

Get strong reference from weak reference

Canvas Channel Functions

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.

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

obs_scene_t *obs_canvas_scene_create(obs_canvas_t *canvas, const char *name)

Create scene attached to a canvas.

void obs_canvas_scene_remove(obs_scene_t *scene)

Remove a scene from a canvas.

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.

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.

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 obs_source_release() to release it when complete.

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 obs_scene_release() to release it when complete.

Canvas Video Functions

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.

bool obs_canvas_has_video(obs_canvas_t *canvas)

Returns true if the canvas video is configured.

video_t *obs_canvas_get_video(const obs_canvas_t *canvas)

Get canvas video output

bool obs_canvas_get_video_info(const obs_canvas_t *canvas, struct obs_video_info *ovi)

Get canvas video info (if any)

void obs_canvas_render(obs_canvas_t *canvas)

Render the canvas’s view. Must be called on the graphics thread.