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.

#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.