Scene API Reference (obs_scene_t)

A scene is a source which contains and renders other sources using specific transforms and/or filtering

type obs_scene_t: A reference-counted scene object.

type obs_sceneitem_t: A reference-counted scene item object.

#include <obs.h>

Scene Item Transform Structure (obs_transform_info)

struct obs_transform_info: Scene item transform structure.

struct vec2 obs_transform_info.pos: Position.

float obs_transform_info.rot: Rotation (degrees).

struct vec2 obs_transform_info.scale: Scale.

uint32_t obs_transform_info.alignment

The alignment of the scene item relative to its position.

Can be 0 or a bitwise OR combination of one of the following values:

OBS_ALIGN_CENTER
OBS_ALIGN_LEFT
OBS_ALIGN_RIGHT
OBS_ALIGN_TOP
OBS_ALIGN_BOTTOM

enum obs_bounds_type obs_transform_info.bounds_type

Can be one of the following values:

OBS_BOUNDS_NONE - No bounding box
OBS_BOUNDS_STRETCH - Stretch to the bounding box without preserving aspect ratio
OBS_BOUNDS_SCALE_INNER - Scales with aspect ratio to inner bounding box rectangle
OBS_BOUNDS_SCALE_OUTER - Scales with aspect ratio to outer bounding box rectangle
OBS_BOUNDS_SCALE_TO_WIDTH - Scales with aspect ratio to the bounding box width
OBS_BOUNDS_SCALE_TO_HEIGHT - Scales with aspect ratio to the bounding box height
OBS_BOUNDS_MAX_ONLY - Scales with aspect ratio, but only to the size of the source maximum

uint32_t obs_transform_info.bounds_alignment

The alignment of the source within the bounding box.

Can be 0 or a bitwise OR combination of one of the following values:

OBS_ALIGN_CENTER
OBS_ALIGN_LEFT
OBS_ALIGN_RIGHT
OBS_ALIGN_TOP
OBS_ALIGN_BOTTOM

struct vec2 obs_transform_info.bounds: The bounding box (if a bounding box is enabled).

Scene Item Crop Structure (obs_sceneitem_crop)

struct obs_sceneitem_crop: Scene item crop structure.

int obs_sceneitem_crop.left: Left crop value.

int obs_sceneitem_crop.top: Top crop value.

int obs_sceneitem_crop.right: Right crop value.

int obs_sceneitem_crop.bottom: Bottom crop value.

Scene Item Order Info Structure (*obs_sceneitem_order_info)

struct obs_sceneitem_order_info: Scene item order info structure.

obs_sceneitem_t *obs_sceneitem_order_info.group: Specifies the group this scene item belongs to, or NULL if none.

obs_sceneitem_t *obs_sceneitem_order_info.item: Specifies the scene item.

Scene Signals

item_add (ptr scene, ptr item)

Called when a scene item has been added to the scene.

item_remove (ptr scene, ptr item)

Called when a scene item has been removed from the scene.

reorder (ptr scene)

Called when scene items have been reordered in the scene.

refresh (ptr scene)

Called when the entire scene item list needs to be refreshed. Usually this is only used when groups have changed.

item_visible (ptr scene, ptr item, bool visible)

Called when a scene item’s visibility state changes.

item_locked (ptr scene, ptr item, bool locked)

Called when a scene item has been locked or unlocked.

item_select (ptr scene, ptr item)

item_deselect (ptr scene, ptr item)

Called when a scene item has been selected/deselected.

(Author’s note: These should be replaced)

item_transform (ptr scene, ptr item)

Called when a scene item’s transform has changed.

General Scene Functions

obs_scene_t *obs_scene_create(const char *name)

Parameters:

name – Name of the scene source. If it’s not unique, it will be made unique

Returns:

A reference to a scene

obs_scene_t *obs_scene_create_private(const char *name)

Parameters:

name – Name of the scene source. Does not have to be unique, or can be NULL

Returns:

A reference to a private scene

obs_scene_t *obs_scene_duplicate(obs_scene_t *scene, const char *name, enum obs_scene_duplicate_type type)

Duplicates a scene. When a scene is duplicated, its sources can be just referenced, or fully duplicated.

Parameters:

name – Name of the new scene source
type –

Type of duplication:

OBS_SCENE_DUP_REFS - Duplicates the scene, but scene items are only duplicated with references

OBS_SCENE_DUP_COPY - Duplicates the scene, and scene items are also fully duplicated when possible

OBS_SCENE_DUP_PRIVATE_REFS - Duplicates with references, but the scene is a private source

OBS_SCENE_DUP_PRIVATE_COPY - Fully duplicates scene items when possible, but the scene and duplicates sources are private sources

Returns:

A reference to a new scene

obs_scene_t *obs_scene_get_ref(obs_scene_t *scene): Returns an incremented reference if still valid, otherwise returns NULL. Release with obs_scene_release().

void obs_scene_release(obs_scene_t *scene): Releases a reference to a scene.

obs_sceneitem_t *obs_scene_add(obs_scene_t *scene, obs_source_t *source)

Returns:: A new scene item for a source within a scene. Does not increment the reference

obs_source_t *obs_scene_get_source(const obs_scene_t *scene)

Returns:: The scene’s source. Does not increment the reference

obs_scene_t *obs_scene_from_source(const obs_source_t *source)

Returns:: The scene context, or NULL if not a scene. Does not increase the reference

obs_sceneitem_t *obs_scene_find_source(obs_scene_t *scene, const char *name)

Parameters:

name – The name of the source to find

Returns:

The scene item if found, otherwise NULL if not found

obs_sceneitem_t *obs_scene_find_source_recursive(obs_scene_t *scene, const char *name)

Same as obs_scene_find_source, but also searches groups within the scene.

Parameters:

name – The name of the source to find

Returns:

The scene item if found, otherwise NULL if not found

obs_sceneitem_t *obs_scene_find_sceneitem_by_id(obs_scene_t *scene, int64_t id)

Parameters:

id – The unique numeric identifier of the scene item

Returns:

The scene item if found, otherwise NULL if not found

void obs_scene_enum_items(obs_scene_t *scene, bool (*callback)(obs_scene_t*, obs_sceneitem_t*, void*), void *param)

Enumerates scene items within a scene in order of the bottommost scene item to the topmost scene item.

Callback function returns true to continue enumeration, or false to end enumeration.

Use obs_sceneitem_addref() if you want to retain a reference after obs_scene_enum_items finishes.

For scripting, use obs_scene_enum_items().

bool obs_scene_reorder_items(obs_scene_t *scene, obs_sceneitem_t *const *item_order, size_t item_order_size): Reorders items within a scene.

bool obs_scene_reorder_items2(obs_scene_t *scene, struct obs_sceneitem_order_info *item_order, size_t item_order_size): Reorders items within a scene with groups and group sub-items.

void obs_scene_prune_sources(obs_scene_t *scene): Releases all sources from a scene that have been marked as removed by obs_source_remove.

Scene Item Functions

void obs_sceneitem_addref(obs_sceneitem_t *item)
void obs_sceneitem_release(obs_sceneitem_t *item): Adds/releases a reference to a scene item.

void obs_sceneitem_remove(obs_sceneitem_t *item): Removes the scene item from the scene.

obs_scene_t *obs_sceneitem_get_scene(const obs_sceneitem_t *item)

Returns:: The scene associated with the scene item. Does not increment the reference

obs_source_t *obs_sceneitem_get_source(const obs_sceneitem_t *item)

Returns:: The source associated with the scene item. Does not increment the reference

obs_sceneitem_t *obs_scene_sceneitem_from_source(obs_scene_t *scene, obs_source_t *source)

This will add a reference to the sceneitem.

Returns:: The sceneitem associated with a source in a scene. Returns NULL if not found.

Deprecated since version 31.0: This function is problematic because there can be multiple items of the same source in a scene. In that case, which of those this function will return is undefined. If this is the behavior you need, manually use obs_scene_enum_items() instead.

void obs_sceneitem_set_id(obs_sceneitem_t *item);: Sets the unique numeric identifier of the sceneitem. This is dangerous function and should not normally be used. It can cause errors within obs.

int64_t obs_sceneitem_get_id(const obs_sceneitem_t *item)

Gets the numeric identifier of the sceneitem.

Returns:: Gets the unique numeric identifier of the scene item.

obs_data_t *obs_scene_save_transform_states(obs_scene_t *scene, bool all_items)

void obs_scene_load_transform_states(const char *states)

Saves all the transformation states for the sceneitems in scene. When all_items is false, it will only save selected items

Returns:: Data containing transformation states for all* sceneitems in scene

void obs_sceneitem_set_pos(obs_sceneitem_t *item, const struct vec2 *pos)
void obs_sceneitem_get_pos(const obs_sceneitem_t *item, struct vec2 *pos): Sets/gets the position of a scene item.

void obs_sceneitem_set_relative_pos(obs_sceneitem_t *item, const struct vec2 *pos)
void obs_sceneitem_get_relative_pos(const obs_sceneitem_t *item, struct vec2 *pos): Sets/gets the position of a scene item in relative coordinates. In this system (0.0, 0.0) is the center of the screen, (0, -1.0) the bottom and (0, 1.0) the top. The visible range of the horizontal axis depends on aspect ratio, for example, with 16:9 (1.7777…) this is [-1.777.., -1.777..]. Positions are rounded to the nearest half-pixel when converting from relative to absolute pixel values to maintain backwards compaibility.

Added in version 31.0.

void obs_sceneitem_set_rot(obs_sceneitem_t *item, float rot_deg)
float obs_sceneitem_get_rot(const obs_sceneitem_t *item): Sets/gets the rotation of a scene item.

void obs_sceneitem_set_scale(obs_sceneitem_t *item, const struct vec2 *scale)
void obs_sceneitem_get_scale(const obs_sceneitem_t *item, struct vec2 *scale): Sets/gets the scaling of the scene item.

void obs_sceneitem_set_alignment(obs_sceneitem_t *item, uint32_t alignment)

uint32_t obs_sceneitem_get_alignment(const obs_sceneitem_t *item)

Sets/gets the alignment of the scene item relative to its position.

Parameters:

alignment –

Can be any bitwise OR combination of:

OBS_ALIGN_CENTER

OBS_ALIGN_LEFT

OBS_ALIGN_RIGHT

OBS_ALIGN_TOP

OBS_ALIGN_BOTTOM

void obs_sceneitem_set_order(obs_sceneitem_t *item, enum obs_order_movement movement)

Changes the scene item’s order relative to the other scene items within the scene.

Parameters:

movement –

Can be one of the following:

OBS_ORDER_MOVE_UP

OBS_ORDER_MOVE_DOWN

OBS_ORDER_MOVE_TOP

OBS_ORDER_MOVE_BOTTOM

void obs_sceneitem_set_order_position(obs_sceneitem_t *item, int position): Changes the sceneitem’s order index.

int obs_sceneitem_get_order_position(obs_sceneitem_t *item)

Returns:: Gets position of sceneitem in its scene.

void obs_sceneitem_set_bounds_type(obs_sceneitem_t *item, enum obs_bounds_type type)

enum obs_bounds_type obs_sceneitem_get_bounds_type(const obs_sceneitem_t *item)

Sets/gets the bounding box type of a scene item. Bounding boxes are used to stretch/position the source relative to a specific bounding box of a specific size.

Parameters:

type –

Can be one of the following values:

OBS_BOUNDS_NONE - No bounding box

OBS_BOUNDS_STRETCH - Stretch to the bounding box without preserving aspect ratio

OBS_BOUNDS_SCALE_INNER - Scales with aspect ratio to inner bounding box rectangle

OBS_BOUNDS_SCALE_OUTER - Scales with aspect ratio to outer bounding box rectangle

OBS_BOUNDS_SCALE_TO_WIDTH - Scales with aspect ratio to the bounding box width

OBS_BOUNDS_SCALE_TO_HEIGHT - Scales with aspect ratio to the bounding box height

OBS_BOUNDS_MAX_ONLY - Scales with aspect ratio, but only to the size of the source maximum

void obs_sceneitem_set_bounds_alignment(obs_sceneitem_t *item, uint32_t alignment)

uint32_t obs_sceneitem_get_bounds_alignment(const obs_sceneitem_t *item)

Sets/gets the alignment of the source within the bounding box.

Parameters:

alignment –

Can be any bitwise OR combination of:

OBS_ALIGN_CENTER

OBS_ALIGN_LEFT

OBS_ALIGN_RIGHT

OBS_ALIGN_TOP

OBS_ALIGN_BOTTOM

void obs_sceneitem_set_bounds(obs_sceneitem_t *item, const struct vec2 *bounds)
void obs_sceneitem_get_bounds(const obs_sceneitem_t *item, struct vec2 *bounds): Sets/gets the bounding box width/height of the scene item.

void obs_sceneitem_set_relative_bounds(obs_sceneitem_t *item, const struct vec2 *bounds)
void obs_sceneitem_get_relative_bounds(const obs_sceneitem_t *item, struct vec2 *bounds): Sets/gets the bounding box width/height of the scene item in relative sizes. See obs_sceneitem_get_relative_pos()/obs_sceneitem_set_relative_pos() for details on the relative coordinate system.

Added in version 31.0.

void obs_sceneitem_set_info(obs_sceneitem_t *item, const struct obs_transform_info *info)
void obs_sceneitem_get_info(const obs_sceneitem_t *item, struct obs_transform_info *info): Sets/gets the transform information of the scene item.

void obs_sceneitem_set_info2(obs_sceneitem_t *item, const struct obs_transform_info *info)
void obs_sceneitem_get_info2(const obs_sceneitem_t *item, struct obs_transform_info *info): Sets/gets the transform information of the scene item. This version of the function also sets the crop_to_bounds member of obs_transform_info.

Added in version 30.1.

void obs_sceneitem_set_info3(obs_sceneitem_t *item, const struct obs_transform_info *info)
void obs_sceneitem_get_info3(const obs_sceneitem_t *item, struct obs_transform_info *info): Sets/gets the transform information of the scene item. This version uses relative coordinates, see obs_sceneitem_get_relative_pos()/obs_sceneitem_set_relative_pos() for details.

Added in version 31.0.

void obs_sceneitem_get_draw_transform(const obs_sceneitem_t *item, struct matrix4 *transform): Gets the transform matrix of the scene item used for drawing the source.

void obs_sceneitem_get_box_transform(const obs_sceneitem_t *item, struct matrix4 *transform): Gets the transform matrix of the scene item used for the bounding box or edges of the scene item.

void obs_sceneitem_select(obs_sceneitem_t *item, bool select)
bool obs_sceneitem_selected(const obs_sceneitem_t *item): Sets/gets the selection state of the scene item. Note that toggling the selected state will not affect the selected state of other scene items, as multiple scene items can be selected.

bool obs_sceneitem_set_visible(obs_sceneitem_t *item, bool visible)
bool obs_sceneitem_visible(const obs_sceneitem_t *item): Sets/gets the visibility state of the scene item.

bool obs_sceneitem_set_locked(obs_sceneitem_t *item, bool locked)
bool obs_sceneitem_locked(const obs_sceneitem_t *item): Sets/gets the locked/unlocked state of the scene item.

void obs_sceneitem_set_crop(obs_sceneitem_t *item, const struct obs_sceneitem_crop *crop)
void obs_sceneitem_get_crop(const obs_sceneitem_t *item, struct obs_sceneitem_crop *crop): Sets/gets the cropping of the scene item.

void obs_sceneitem_set_scale_filter(obs_sceneitem_t *item, enum obs_scale_type filter)

enum obs_scale_type obs_sceneitem_get_scale_filter(obs_sceneitem_t *item)

Sets/gets the scale filter used for the scene item.

Parameters:

filter –

Can be one of the following values:

OBS_SCALE_DISABLE

OBS_SCALE_POINT

OBS_SCALE_BICUBIC

OBS_SCALE_BILINEAR

OBS_SCALE_LANCZOS

void obs_sceneitem_set_blending_method(obs_sceneitem_t *item, enum obs_blending_method method)

enum obs_blending_method obs_sceneitem_get_blending_method(obs_sceneitem_t *item)

Sets/gets the blending method used for the scene item.

Parameters:

method –

Can be one of the following values:

OBS_BLEND_METHOD_DEFAULT

OBS_BLEND_METHOD_SRGB_OFF

void obs_sceneitem_set_blending_mode(obs_sceneitem_t *item, enum obs_blending_type type)

enum obs_blending_type obs_sceneitem_get_blending_mode(obs_sceneitem_t *item)

Sets/gets the blending mode used for the scene item.

Parameters:

type –

Can be one of the following values:

OBS_BLEND_NORMAL

OBS_BLEND_ADDITIVE

OBS_BLEND_SUBTRACT

OBS_BLEND_SCREEN

OBS_BLEND_MULTIPLY

OBS_BLEND_LIGHTEN

OBS_BLEND_DARKEN

void obs_sceneitem_defer_update_begin(obs_sceneitem_t *item)
void obs_sceneitem_defer_update_end(obs_sceneitem_t *item): Allows the ability to call any one of the transform functions without updating the internal matrices until obs_sceneitem_defer_update_end has been called.

obs_data_t *obs_sceneitem_get_private_settings(obs_sceneitem_t *item)

Returns:: An incremented reference to the private settings of the scene item. Allows the front-end to set custom information which is saved with the scene item. Release with obs_data_release().

void obs_sceneitem_set_transition(obs_sceneitem_t *item, bool show, obs_source_t *transition)

Sets a transition for showing or hiding a scene item.

Parameters:

item – The target scene item
show – If true, this will set the show transition. If false, this will set the hide transition.
transition – The transition to set. Pass NULL to remove the transition.

obs_source_t *obs_sceneitem_get_transition(obs_sceneitem_t *item, bool show)

Parameters:

item – The target scene item
show – If true, this will return the show transition. If false, this will return the hide transition.

Returns:

The transition for showing or hiding a scene item. NULL if no transition is set.

void obs_sceneitem_set_transition_duration(obs_sceneitem_t *item, bool show, uint32_t duration_ms)

Sets the transition duration for showing or hiding a scene item.

Parameters:

item – The target scene item
show – If true, this will set the duration of the show transition. If false, this will set the duration of the hide transition.
duration_ms – The transition duration in milliseconds

uint32_t obs_sceneitem_get_transition_duration(obs_sceneitem_t *item, bool show)

Gets the transition duration for showing or hiding a scene item.

Parameters:

item – The target scene item
show – If true, this will return the duration of the show transition. If false, this will return the duration of the hide transition.

Returns:

The transition duration in milliseconds

void obs_sceneitem_do_transition(obs_sceneitem_t *item, bool visible): Start the transition for showing or hiding a scene item.

Scene Item Group Functions

obs_sceneitem_t *obs_scene_add_group(obs_scene_t *scene, const char *name)

Adds a group with the specified name. Does not signal the scene with the refresh signal.

Parameters:

scene – Scene to add the group to
name – Name of the group

Returns:

The new group’s scene item

obs_sceneitem_t *obs_scene_add_group2(obs_scene_t *scene, const char *name, bool signal)

Adds a group with the specified name.

Parameters:

scene – Scene to add the group to
name – Name of the group
signal – If true, signals the scene with the refresh signal

Returns:

The new group’s scene item

obs_sceneitem_t *obs_scene_insert_group(obs_scene_t *scene, const char *name, obs_sceneitem_t **items, size_t count)

Creates a group out of the specified scene items. The group will be inserted at the top scene item. Does not signal the scene with the refresh signal.

Parameters:

scene – Scene to add the group to
name – Name of the group
items – Array of scene items to put in a group
count – Number of scene items in the array

Returns:

The new group’s scene item

obs_sceneitem_t *obs_scene_insert_group2(obs_scene_t *scene, const char *name, obs_sceneitem_t **items, size_t count, bool signal)

Creates a group out of the specified scene items. The group will be inserted at the top scene item. Does not signal a refresh.

Parameters:

scene – Scene to add the group to
name – Name of the group
items – Array of scene items to put in a group
count – Number of scene items in the array
signal – If true, signals the scene with the refresh signal

Returns:

The new group’s scene item

obs_sceneitem_t *obs_scene_get_group(obs_scene_t *scene, const char *name)

Finds a group within a scene by its name.

Parameters:

scene – Scene to find the group within
name – The name of the group to find

Returns:

The group scene item, or NULL if not found

obs_scene_t *obs_group_from_source(const obs_source_t *source)

Returns:: The group context, or NULL if not a group. Does not increase the reference

obs_scene_t *obs_group_or_scene_from_source(const obs_source_t *source)

Returns:: The context for the source, regardless of if it is a group or a scene. NULL if neither. Does not increase the reference

bool obs_sceneitem_is_group(obs_sceneitem_t *item)

Parameters:

item – Scene item

Returns:

true if scene item is a group, false otherwise

obs_scene_t *obs_sceneitem_group_get_scene(const obs_sceneitem_t *group)

Parameters:

group – Group scene item

Returns:

Scene of the group, or NULL if not a group

void obs_sceneitem_group_ungroup(obs_sceneitem_t *group): Ungroups the specified group. Scene items within the group will be placed where the group was. Does not signal the scene with the refresh signal.

void obs_sceneitem_group_ungroup2(obs_sceneitem_t *group, bool signal)

Ungroups the specified group. Scene items within the group will be placed where the group was.

Parameters:

group – Group scene item
signal – If true, signals the scene with the refresh signal

void obs_sceneitem_group_add_item(obs_sceneitem_t *group, obs_sceneitem_t *item): Adds a scene item to a group.

void obs_sceneitem_group_remove_item(obs_sceneitem_t *item): Removes a scene item from a group. The item will be placed before the group in the main scene.

obs_sceneitem_t *obs_sceneitem_get_group(obs_scene_t *scene, obs_sceneitem_t *item)

Returns the parent group of a scene item.

Parameters:

scene – Scene to find the group within
item – Scene item to get the group of

Returns:

The parent group of the scene item, or NULL if not in a group

void obs_sceneitem_group_enum_items(obs_sceneitem_t *group, bool (*callback)(obs_scene_t*, obs_sceneitem_t*, void*), void *param)

Enumerates scene items within a group.

Callback function returns true to continue enumeration, or false to end enumeration.

Use obs_sceneitem_addref() if you want to retain a reference after obs_sceneitem_group_enum_items finishes.

void obs_sceneitem_defer_group_resize_begin(obs_sceneitem_t *item)

void obs_sceneitem_defer_group_resize_end(obs_sceneitem_t *item)

Allows the ability to call any one of the transform functions on scene items within a group without updating the internal matrices of the group until obs_sceneitem_defer_group_resize_end has been called.

This is necessary if the user is resizing items while they are within a group, as the group’s transform will automatically update its transform every frame otherwise.