Scene API Reference (obs_scene_t)

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

obs_scene_t

A reference-counted scene object.

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

reorder (ptr scene)

Called when scene items have been reoredered 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)
void obs_scene_release(obs_scene_t *scene)

Adds/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.


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.


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


int64_t obs_sceneitem_get_id(const obs_sceneitem_t *item)
Returns

The unique numeric identifier of the scene item.


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 scene item’s order index.


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.


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


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


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_sceneitem_t *item)

Returns the parent group of a scene item.

Parameters
  • item – Scene item to get the group of

Returns

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


obs_sceneitem_t *obs_sceneitem_group_from_scene(obs_scene_t *scene)
Returns

The group associated with the scene, or NULL if the specified scene is not a group.


obs_sceneitem_t *obs_sceneitem_group_from_source(obs_source_t *source)
Returns

The group associated with the scene’s source, or NULL if the specified source is not 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.


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.