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

void obs_scene_addref(obs_scene_t *scene)

Adds a reference to a scene.

Deprecated since version 27.2.0: Use obs_scene_get_ref() instead.

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.

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

void obs_sceneitem_set_show_transition(obs_sceneitem_t *item, obs_source_t *transition)
void obs_sceneitem_set_hide_transition(obs_sceneitem_t *item, obs_source_t *transition)

Sets a transition for showing or hiding a scene item. Set NULL to remove the transition.

Deprecated since version 27.2.4: Use obs_sceneitem_set_transition() instead.

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.

obs_source_t *obs_sceneitem_get_show_transition(obs_sceneitem_t *item)
obs_source_t *obs_sceneitem_get_hide_transition(obs_sceneitem_t *item)
Returns:

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

Deprecated since version 27.2.4: Use obs_sceneitem_get_transition() instead.

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

void obs_sceneitem_set_show_transition_duration(obs_sceneitem_t *item, uint32_t duration_ms)
void obs_sceneitem_set_hide_transition_duration(obs_sceneitem_t *item, uint32_t duration_ms)

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

Deprecated since version 27.2.4: Use obs_sceneitem_set_transition_duration() instead.

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

uint32_t obs_sceneitem_get_show_transition_duration(obs_sceneitem_t *item)
uint32_t obs_sceneitem_get_hide_transition_duration(obs_sceneitem_t *item)
Returns:

The transition duration in ms for showing or hiding a scene item.

Deprecated since version 27.2.4: Use obs_sceneitem_get_transition_duration() instead.

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.