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.

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

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

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


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.


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)

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