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>.. struct:: obs_transform_info Scene item transform structure.
.. member:: struct vec2 obs_transform_info.pos Position.
.. member:: float obs_transform_info.rot Rotation (degrees).
.. member:: struct vec2 obs_transform_info.scale Scale.
.. member:: 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**
.. member:: 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
.. member:: 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**
.. member:: struct vec2 obs_transform_info.bounds The bounding box (if a bounding box is enabled).
.. struct:: obs_sceneitem_crop Scene item crop structure.
.. member:: int obs_sceneitem_crop.left Left crop value.
.. member:: int obs_sceneitem_crop.top Top crop value.
.. member:: int obs_sceneitem_crop.right Right crop value.
.. member:: int obs_sceneitem_crop.bottom Bottom crop value.
.. struct:: obs_sceneitem_order_info Scene item order info structure.
.. member:: obs_sceneitem_t *obs_sceneitem_order_info.group Specifies the group this scene item belongs to, or *NULL* if none.
.. member:: obs_sceneitem_t *obs_sceneitem_order_info.item Specifies the scene item.
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.
.. function:: obs_scene_t *obs_scene_create(const char *name)
:param name: Name of the scene source. If it's not unique, it will
be made unique
:return: A reference to a scene
.. function:: obs_scene_t *obs_scene_create_private(const char *name)
:param name: Name of the scene source. Does not have to be unique,
or can be *NULL*
:return: A reference to a private scene
.. function:: 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.
:param name: Name of the new scene source
:param 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
:return: A reference to a new scene
.. function:: void obs_scene_addref(obs_scene_t *scene) Adds a reference to a scene.
.. deprecated:: 27.2.0 Use :c:func:`obs_scene_get_ref()` instead.
.. function:: obs_scene_t *obs_scene_get_ref(obs_scene_t *scene) Returns an incremented reference if still valid, otherwise returns *NULL*.
.. function:: void obs_scene_release(obs_scene_t *scene) Releases a reference to a scene.
.. function:: obs_sceneitem_t *obs_scene_add(obs_scene_t *scene, obs_source_t *source)
:return: A new scene item for a source within a scene. Does not
increment the reference
.. function:: obs_source_t *obs_scene_get_source(const obs_scene_t *scene) :return: The scene's source. Does not increment the reference
.. function:: obs_scene_t *obs_scene_from_source(const obs_source_t *source)
:return: The scene context, or *NULL* if not a scene. Does not
increase the reference
.. function:: obs_sceneitem_t *obs_scene_find_source(obs_scene_t *scene, const char *name) :param name: The name of the source to find :return: The scene item if found, otherwise *NULL* if not found
.. function:: 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. :param name: The name of the source to find :return: The scene item if found, otherwise *NULL* if not found
.. function:: obs_sceneitem_t *obs_scene_find_sceneitem_by_id(obs_scene_t *scene, int64_t id) :param id: The unique numeric identifier of the scene item :return: The scene item if found, otherwise *NULL* if not found
.. function:: 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. For scripting, use :py:func:`obs_scene_enum_items`.
.. function:: 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.
.. function:: 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.
.. function:: 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.
.. function:: void obs_sceneitem_addref(obs_sceneitem_t *item)
void obs_sceneitem_release(obs_sceneitem_t *item)
Adds/releases a reference to a scene item.
.. function:: void obs_sceneitem_remove(obs_sceneitem_t *item) Removes the scene item from the scene.
.. function:: obs_scene_t *obs_sceneitem_get_scene(const obs_sceneitem_t *item)
:return: The scene associated with the scene item. Does not
increment the reference
.. function:: obs_source_t *obs_sceneitem_get_source(const obs_sceneitem_t *item)
:return: The source associated with the scene item. Does not
increment the reference
.. function:: obs_sceneitem_t *obs_scene_sceneitem_from_source(obs_scene_t *scene, obs_source_t *source) This will add a reference to the sceneitem. :return: The sceneitem associated with a source in a scene. Returns NULL if not found.
.. function:: 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.
.. function:: int64_t obs_sceneitem_get_id(const obs_sceneitem_t *item) Gets the numeric identifier of the sceneitem. :return: Gets the unique numeric identifier of the scene item.
.. function:: obs_data_t *obs_scene_save_transform_states(obs_scene_t *scene, bool all_items)
.. function:: void obs_scene_load_transform_states(const char *states) Saves all the transformation states for the sceneitms in scene. When all_items is false, it will only save selected items :return: Data containing transformation states for all* sceneitems in scene
.. function:: 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.
.. function:: 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.
.. function:: 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.
.. function:: 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.
:param alignment: | Can be any bitwise OR combination of:
| OBS_ALIGN_CENTER
| OBS_ALIGN_LEFT
| OBS_ALIGN_RIGHT
| OBS_ALIGN_TOP
| OBS_ALIGN_BOTTOM
.. function:: 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.
:param movement: | Can be one of the following:
| OBS_ORDER_MOVE_UP
| OBS_ORDER_MOVE_DOWN
| OBS_ORDER_MOVE_TOP
| OBS_ORDER_MOVE_BOTTOM
.. function:: void obs_sceneitem_set_order_position(obs_sceneitem_t *item, int position) Changes the sceneitem's order index.
.. function:: int obs_sceneitem_get_order_position(obs_sceneitem_t *item) :return: Gets position of sceneitem in its scene.
.. function:: 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.
:param 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
.. function:: 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.
:param alignment: | Can be any bitwise OR combination of:
| OBS_ALIGN_CENTER
| OBS_ALIGN_LEFT
| OBS_ALIGN_RIGHT
| OBS_ALIGN_TOP
| OBS_ALIGN_BOTTOM
.. function:: 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.
.. function:: 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.
.. function:: 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.
.. function:: 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.
.. function:: 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.
.. function:: 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.
.. function:: 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.
.. function:: 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.
:param filter: | Can be one of the following values:
| OBS_SCALE_DISABLE
| OBS_SCALE_POINT
| OBS_SCALE_BICUBIC
| OBS_SCALE_BILINEAR
| OBS_SCALE_LANCZOS
.. function:: 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.
:param method: | Can be one of the following values:
| OBS_BLEND_METHOD_DEFAULT
| OBS_BLEND_METHOD_SRGB_OFF
.. function:: 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.
:param 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
.. function:: 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.
.. function:: obs_data_t *obs_sceneitem_get_private_settings(obs_sceneitem_t *item)
:return: 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
.. function:: 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)
Set a transition for showing or hiding a scene item. Set *NULL* to remove the transition.
.. function:: obs_source_t *obs_sceneitem_get_show_transition(obs_sceneitem_t *item)
obs_source_t *obs_sceneitem_get_hide_transition(obs_sceneitem_t *item)
:return: The transition for showing or hiding a scene item. *NULL* if no transition is set.
.. function:: 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)
Set transition duration for showing or hiding a scene item.
.. function:: uint32_t obs_sceneitem_get_show_transition_duration(obs_sceneitem_t *item)
uint32_t obs_sceneitem_get_hide_transition_duration(obs_sceneitem_t *item)
:return: The transition duration in ms for showing or hiding a scene item.
.. function:: void obs_sceneitem_do_transition(obs_sceneitem_t *item, bool visible) Start the transition for showing or hiding a scene item.
.. function:: 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. :param scene: Scene to add the group to :param name: Name of the group :return: The new group's scene item
.. function:: obs_sceneitem_t *obs_scene_add_group2(obs_scene_t *scene, const char *name, bool signal)
Adds a group with the specified name.
:param scene: Scene to add the group to
:param name: Name of the group
:param signal: If *true*, signals the scene with the *refresh*
signal
:return: The new group's scene item
.. function:: 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. :param scene: Scene to add the group to :param name: Name of the group :param items: Array of scene items to put in a group :param count: Number of scene items in the array :return: The new group's scene item
.. function:: 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.
:param scene: Scene to add the group to
:param name: Name of the group
:param items: Array of scene items to put in a group
:param count: Number of scene items in the array
:param signal: If *true*, signals the scene with the *refresh*
signal
:return: The new group's scene item
.. function:: obs_sceneitem_t *obs_scene_get_group(obs_scene_t *scene, const char *name) Finds a group within a scene by its name. :param scene: Scene to find the group within :param name: The name of the group to find :return: The group scene item, or *NULL* if not found
.. function:: obs_scene_t *obs_group_from_source(const obs_source_t *source)
:return: The group context, or *NULL* if not a group. Does not
increase the reference
.. function:: obs_scene_t *obs_group_or_scene_from_source(const obs_source_t *source)
:return: The context for the source, regardless of if it is a
group or a scene. *NULL* if neither. Does not increase
the reference
.. function:: bool obs_sceneitem_is_group(obs_sceneitem_t *item) :param item: Scene item :return: *true* if scene item is a group, *false* otherwise
.. function:: obs_scene_t *obs_sceneitem_group_get_scene(const obs_sceneitem_t *group) :param group: Group scene item :return: Scene of the group, or *NULL* if not a group
.. function:: 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.
.. function:: 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.
:param group: Group scene item
:param signal: If *true*, signals the scene with the *refresh*
signal
.. function:: void obs_sceneitem_group_add_item(obs_sceneitem_t *group, obs_sceneitem_t *item) Adds a scene item to a group.
.. function:: 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.
.. function:: obs_sceneitem_t *obs_sceneitem_get_group(obs_sceneitem_t *item)
Returns the parent group of a scene item.
:param item: Scene item to get the group of
:return: The parent group of the scene item, or *NULL* if not in
a group
.. function:: obs_sceneitem_t *obs_sceneitem_group_from_scene(obs_scene_t *scene)
:return: The group associated with the scene, or *NULL* if the
specified scene is not a group.
.. function:: obs_sceneitem_t *obs_sceneitem_group_from_source(obs_source_t *source)
:return: The group associated with the scene's source, or *NULL* if
the specified source is not a group.
.. function:: 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.
.. function:: void obs_sceneitem_defer_group_resize_begin(obs_sceneitem_t *item)
.. function:: 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.