633 lines
20 KiB
ReStructuredText
633 lines
20 KiB
ReStructuredText
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.
|
|
|
|
.. code:: cpp
|
|
|
|
#include <obs.h>
|
|
|
|
|
|
Scene Item Transform Structure (obs_transform_info)
|
|
---------------------------------------------------
|
|
|
|
.. type:: 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).
|
|
|
|
|
|
Scene Item Crop Structure (obs_sceneitem_crop)
|
|
----------------------------------------------
|
|
|
|
.. type:: 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.
|
|
|
|
|
|
Scene Item Order Info Structure (\*obs_sceneitem_order_info)
|
|
------------------------------------------------------------
|
|
|
|
.. type:: 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.
|
|
|
|
|
|
|
|
.. _scene_signal_reference:
|
|
|
|
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
|
|
-----------------------
|
|
|
|
.. 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)
|
|
void obs_scene_release(obs_scene_t *scene)
|
|
|
|
Adds/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.
|
|
|
|
---------------------
|
|
|
|
.. 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.
|
|
|
|
---------------------
|
|
|
|
|
|
.. _scene_item_reference:
|
|
|
|
Scene Item Functions
|
|
--------------------
|
|
|
|
.. 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:: int64_t obs_sceneitem_get_id(const obs_sceneitem_t *item)
|
|
|
|
:return: The unique numeric identifier of the scene item.
|
|
|
|
---------------------
|
|
|
|
.. 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 scene item's order index.
|
|
|
|
---------------------
|
|
|
|
.. 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_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
|
|
|
|
---------------------
|
|
|
|
|
|
.. _scene_item_group_reference:
|
|
|
|
Scene Item Group Functions
|
|
--------------------------
|
|
|
|
.. 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:: 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.
|