mirror of
https://github.com/obsproject/obs-studio.git
synced 2026-09-24 23:31:36 +08:00
docs: Add clarifications
Adds links to release functions for "new/incremented reference". Extra info on signal handler. Parameter description on `obs_property_list_add_*` functions, since their parameter `name` can be confusing and it is unclear which value is stored in obs_data_t. Adds clarifications on calldata_ptr.
This commit is contained in:
CodeYan01
@@ -363,7 +363,8 @@ Libobs Objects
|
||||
|
||||
.. function:: obs_data_t *obs_save_source(obs_source_t *source)
|
||||
|
||||
:return: A new reference to a source's saved data
|
||||
:return: A new reference to a source's saved data. Use
|
||||
:c:func:`obs_data_release()` to release it when complete.
|
||||
|
||||
---------------------
|
||||
|
||||
@@ -557,7 +558,8 @@ Primary signal/procedure handlers
|
||||
|
||||
.. function:: signal_handler_t *obs_get_signal_handler(void)
|
||||
|
||||
:return: The primary obs signal handler
|
||||
:return: The primary obs signal handler. Should not be manually freed,
|
||||
as its lifecycle is managed by libobs.
|
||||
|
||||
See :ref:`core_signal_handler_reference` for more information on
|
||||
core signals.
|
||||
@@ -566,7 +568,8 @@ Primary signal/procedure handlers
|
||||
|
||||
.. function:: proc_handler_t *obs_get_proc_handler(void)
|
||||
|
||||
:return: The primary obs procedure handler
|
||||
:return: The primary obs procedure handler. Should not be manually freed,
|
||||
as its lifecycle is managed by libobs.
|
||||
|
||||
|
||||
.. _core_signal_handler_reference:
|
||||
|
||||
@@ -332,7 +332,7 @@ General Encoder Functions
|
||||
.. function:: obs_encoder_t *obs_encoder_get_ref(obs_encoder_t *encoder)
|
||||
|
||||
Returns an incremented reference if still valid, otherwise returns
|
||||
*NULL*.
|
||||
*NULL*. Release with :c:func:`obs_encoder_release()`.
|
||||
|
||||
---------------------
|
||||
|
||||
@@ -437,7 +437,8 @@ General Encoder Functions
|
||||
.. function:: obs_data_t *obs_encoder_defaults(const char *id)
|
||||
obs_data_t *obs_encoder_get_defaults(const obs_encoder_t *encoder)
|
||||
|
||||
:return: An incremented reference to the encoder's default settings
|
||||
:return: An incremented reference to the encoder's default settings.
|
||||
Release with :c:func:`obs_data_release()`.
|
||||
|
||||
---------------------
|
||||
|
||||
@@ -461,19 +462,22 @@ General Encoder Functions
|
||||
|
||||
.. function:: obs_data_t *obs_encoder_get_settings(const obs_encoder_t *encoder)
|
||||
|
||||
:return: An incremented reference to the encoder's settings
|
||||
:return: An incremented reference to the encoder's settings. Release with
|
||||
:c:func:`obs_data_release()`.
|
||||
|
||||
---------------------
|
||||
|
||||
.. function:: signal_handler_t *obs_encoder_get_signal_handler(const obs_encoder_t *encoder)
|
||||
|
||||
:return: The signal handler of the encoder
|
||||
:return: The signal handler of the encoder. Should not be manually freed,
|
||||
as its lifecycle is managed by libobs.
|
||||
|
||||
---------------------
|
||||
|
||||
.. function:: proc_handler_t *obs_encoder_get_proc_handler(const obs_encoder_t *encoder)
|
||||
|
||||
:return: The procedure handler of the encoder
|
||||
:return: The procedure handler of the encoder. Should not be manually freed,
|
||||
as its lifecycle is managed by libobs.
|
||||
|
||||
---------------------
|
||||
|
||||
|
||||
@@ -266,7 +266,8 @@ Functions
|
||||
|
||||
.. function:: obs_source_t *obs_frontend_get_current_scene(void)
|
||||
|
||||
:return: A new reference to the currently active scene
|
||||
:return: A new reference to the currently active scene. Release with
|
||||
:c:func:`obs_source_release()`.
|
||||
|
||||
---------------------------------------
|
||||
|
||||
@@ -287,7 +288,8 @@ Functions
|
||||
|
||||
.. function:: obs_source_t *obs_frontend_get_current_transition(void)
|
||||
|
||||
:return: A new reference to the currently active transition
|
||||
:return: A new reference to the currently active transition.
|
||||
Release with :c:func:`obs_source_release()`.
|
||||
|
||||
---------------------------------------
|
||||
|
||||
@@ -612,19 +614,22 @@ Functions
|
||||
|
||||
.. function:: obs_output_t *obs_frontend_get_streaming_output(void)
|
||||
|
||||
:return: A new reference to the current streaming output
|
||||
:return: A new reference to the current streaming output.
|
||||
Release with :c:func:`obs_output_release()`.
|
||||
|
||||
---------------------------------------
|
||||
|
||||
.. function:: obs_output_t *obs_frontend_get_recording_output(void)
|
||||
|
||||
:return: A new reference to the current srecording output
|
||||
:return: A new reference to the current recording output.
|
||||
Release with :c:func:`obs_output_release()`.
|
||||
|
||||
---------------------------------------
|
||||
|
||||
.. function:: obs_output_t *obs_frontend_get_replay_buffer_output(void)
|
||||
|
||||
:return: A new reference to the current replay buffer output
|
||||
:return: A new reference to the current replay buffer output.
|
||||
Release with :c:func:`obs_output_release()`.
|
||||
|
||||
---------------------------------------
|
||||
|
||||
@@ -650,7 +655,8 @@ Functions
|
||||
|
||||
.. function:: obs_service_t *obs_frontend_get_streaming_service(void)
|
||||
|
||||
:return: A new reference to the current streaming service object
|
||||
:return: A new reference to the current streaming service object.
|
||||
Release with :c:func:`obs_service_release()`.
|
||||
|
||||
---------------------------------------
|
||||
|
||||
@@ -684,7 +690,8 @@ Functions
|
||||
.. function:: obs_source_t *obs_frontend_get_current_preview_scene(void)
|
||||
|
||||
:return: A new reference to the current preview scene if studio mode
|
||||
is active, or *NULL* if studio mode is not active.
|
||||
is active, or *NULL* if studio mode is not active. Release
|
||||
with :c:func:`obs_source_release()`.
|
||||
|
||||
---------------------------------------
|
||||
|
||||
@@ -728,7 +735,8 @@ Functions
|
||||
|
||||
.. function:: obs_output_t *obs_frontend_get_virtualcam_output(void)
|
||||
|
||||
:return: A new reference to the current virtual camera output
|
||||
:return: A new reference to the current virtual camera output.
|
||||
Release with :c:func:`obs_output_release()`.
|
||||
|
||||
---------------------------------------
|
||||
|
||||
|
||||
@@ -22,7 +22,9 @@ handlers or to procedure handlers.
|
||||
|
||||
.. function:: void calldata_free(calldata_t *data)
|
||||
|
||||
Frees a calldata structure.
|
||||
Frees a calldata structure. Should only be used if :c:func:`calldata_init()`
|
||||
was used. If the object is received as a callback parameter, this function
|
||||
should not be used.
|
||||
|
||||
:param data: Calldata structure
|
||||
|
||||
@@ -110,7 +112,9 @@ handlers or to procedure handlers.
|
||||
|
||||
.. function:: void *calldata_ptr(const calldata_t *data, const char *name)
|
||||
|
||||
Gets a pointer parameter.
|
||||
Gets a pointer parameter. For example, :ref:`core_signal_handler_reference`
|
||||
that have ``ptr source`` as a parameter requires this function to get the
|
||||
pointer, which can be casted to :c:type:`obs_source_t`. Does not have to be freed.
|
||||
|
||||
:param data: Calldata structure
|
||||
:param name: Parameter name
|
||||
|
||||
@@ -345,7 +345,7 @@ General Output Functions
|
||||
.. function:: obs_output_t *obs_output_get_ref(obs_output_t *output)
|
||||
|
||||
Returns an incremented reference if still valid, otherwise returns
|
||||
*NULL*.
|
||||
*NULL*. Release with :c:func:`obs_output_release()`.
|
||||
|
||||
---------------------
|
||||
|
||||
@@ -443,7 +443,8 @@ General Output Functions
|
||||
|
||||
.. function:: obs_data_t *obs_output_defaults(const char *id)
|
||||
|
||||
:return: An incremented reference to the output's default settings
|
||||
:return: An incremented reference to the output's default settings.
|
||||
Release with :c:func:`obs_data_release()`.
|
||||
|
||||
---------------------
|
||||
|
||||
@@ -488,19 +489,22 @@ General Output Functions
|
||||
|
||||
.. function:: obs_data_t *obs_output_get_settings(const obs_output_t *output)
|
||||
|
||||
:return: An incremented reference to the output's settings
|
||||
:return: An incremented reference to the output's settings. Release with
|
||||
:c:func:`obs_data_release()`.
|
||||
|
||||
---------------------
|
||||
|
||||
.. function:: signal_handler_t *obs_output_get_signal_handler(const obs_output_t *output)
|
||||
|
||||
:return: The signal handler of the output
|
||||
:return: The signal handler of the output. Should not be manually freed,
|
||||
as its lifecycle is managed by libobs.
|
||||
|
||||
---------------------
|
||||
|
||||
.. function:: proc_handler_t *obs_output_get_proc_handler(const obs_output_t *output)
|
||||
|
||||
:return: The procedure handler of the output
|
||||
:return: The procedure handler of the output. Should not be manually freed,
|
||||
as its lifecycle is managed by libobs.
|
||||
|
||||
---------------------
|
||||
|
||||
|
||||
@@ -649,36 +649,60 @@ Property Modification Functions
|
||||
|
||||
Adds a string to a string list.
|
||||
|
||||
:param name: Localized name shown to user
|
||||
:param val: The actual string value stored and will be returned by :c:func:`obs_data_get_string`
|
||||
:returns: The index of the list item.
|
||||
|
||||
---------------------
|
||||
|
||||
.. function:: size_t obs_property_list_add_int(obs_property_t *p, const char *name, long long val)
|
||||
|
||||
Adds an integer to a integer list.
|
||||
|
||||
:param name: Localized name shown to user
|
||||
:param val: The actual int value stored and will be returned by :c:func:`obs_data_get_int`
|
||||
:returns: The index of the list item.
|
||||
|
||||
---------------------
|
||||
|
||||
.. function:: size_t obs_property_list_add_float(obs_property_t *p, const char *name, double val)
|
||||
|
||||
Adds a floating point to a floating point list.
|
||||
|
||||
:param name: Localized name shown to user
|
||||
:param val: The actual float value stored and will be returned by :c:func:`obs_data_get_double`
|
||||
:returns: The index of the list item.
|
||||
|
||||
---------------------
|
||||
|
||||
.. function:: void obs_property_list_insert_string(obs_property_t *p, size_t idx, const char *name, const char *val)
|
||||
|
||||
Inserts a string in to a string list.
|
||||
|
||||
:param idx: The index of the list item
|
||||
:param name: Localized name shown to user
|
||||
:param val: The actual string value stored and will be returned by :c:func:`obs_data_get_string`
|
||||
|
||||
---------------------
|
||||
|
||||
.. function:: void obs_property_list_insert_int(obs_property_t *p, size_t idx, const char *name, long long val)
|
||||
|
||||
Inserts an integer in to an integer list.
|
||||
|
||||
:param idx: The index of the list item
|
||||
:param name: Localized name shown to user
|
||||
:param val: The actual int value stored and will be returned by :c:func:`obs_data_get_int`
|
||||
|
||||
---------------------
|
||||
|
||||
.. function:: void obs_property_list_insert_float(obs_property_t *p, size_t idx, const char *name, double val)
|
||||
|
||||
Inserts a floating point in to a floating point list.
|
||||
|
||||
:param idx: The index of the list item.
|
||||
:param name: Localized name shown to user
|
||||
:param val: The actual float value stored and will be returned by :c:func:`obs_data_get_double`
|
||||
|
||||
---------------------
|
||||
|
||||
.. function:: void obs_property_list_item_disable(obs_property_t *p, size_t idx, bool disabled)
|
||||
|
||||
@@ -208,7 +208,7 @@ General Scene Functions
|
||||
.. function:: obs_scene_t *obs_scene_get_ref(obs_scene_t *scene)
|
||||
|
||||
Returns an incremented reference if still valid, otherwise returns
|
||||
*NULL*.
|
||||
*NULL*. Release with :c:func:`obs_scene_release()`.
|
||||
|
||||
---------------------
|
||||
|
||||
@@ -549,7 +549,8 @@ Scene Item Functions
|
||||
|
||||
: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
|
||||
which is saved with the scene item. Release with
|
||||
:c:func:`obs_data_release()`.
|
||||
|
||||
---------------------
|
||||
|
||||
|
||||
@@ -200,7 +200,7 @@ General Service Functions
|
||||
.. function:: obs_service_t *obs_service_get_ref(obs_service_t *service)
|
||||
|
||||
Returns an incremented reference if still valid, otherwise returns
|
||||
*NULL*.
|
||||
*NULL*. Release with :c:func:`obs_service_release()`.
|
||||
|
||||
---------------------
|
||||
|
||||
@@ -236,7 +236,8 @@ General Service Functions
|
||||
|
||||
.. function:: obs_data_t *obs_service_defaults(const char *id)
|
||||
|
||||
:return: An incremented reference to the service's default settings
|
||||
:return: An incremented reference to the service's default settings.
|
||||
Release with :c:func:`obs_data_release()`.
|
||||
|
||||
---------------------
|
||||
|
||||
@@ -254,7 +255,8 @@ General Service Functions
|
||||
|
||||
.. function:: obs_data_t *obs_service_get_settings(const obs_service_t *service)
|
||||
|
||||
:return: An incremented reference to the service's settings
|
||||
:return: An incremented reference to the service's settings. Release with
|
||||
:c:func:`obs_data_release()`.
|
||||
|
||||
---------------------
|
||||
|
||||
|
||||
@@ -25,7 +25,8 @@ General Functions
|
||||
|
||||
.. function:: obs_data_t *obs_data_create()
|
||||
|
||||
:return: A new reference to a data object.
|
||||
:return: A new reference to a data object. Release with
|
||||
:c:func:`obs_data_release()`.
|
||||
|
||||
---------------------
|
||||
|
||||
@@ -34,7 +35,8 @@ General Functions
|
||||
Creates a data object from a Json string.
|
||||
|
||||
:param json_string: Json string
|
||||
:return: A new reference to a data object
|
||||
:return: A new reference to a data object. Release with
|
||||
:c:func:`obs_data_release()`.
|
||||
|
||||
---------------------
|
||||
|
||||
@@ -43,7 +45,8 @@ General Functions
|
||||
Creates a data object from a Json file.
|
||||
|
||||
:param json_file: Json file path
|
||||
:return: A new reference to a data object
|
||||
:return: A new reference to a data object. Release with
|
||||
:c:func:`obs_data_release()`.
|
||||
|
||||
---------------------
|
||||
|
||||
@@ -54,7 +57,8 @@ General Functions
|
||||
|
||||
:param json_file: Json file path
|
||||
:param backup_ext: Backup file extension
|
||||
:return: A new reference to a data object
|
||||
:return: A new reference to a data object. Release with
|
||||
:c:func:`obs_data_release()`.
|
||||
|
||||
---------------------
|
||||
|
||||
@@ -176,13 +180,15 @@ Get Functions
|
||||
|
||||
.. function:: obs_data_t *obs_data_get_obj(obs_data_t *data, const char *name)
|
||||
|
||||
:return: An incremented reference to a data object.
|
||||
:return: An incremented reference to a data object. Release with
|
||||
:c:func:`obs_data_release()`.
|
||||
|
||||
---------------------
|
||||
|
||||
.. function:: obs_data_array_t *obs_data_get_array(obs_data_t *data, const char *name)
|
||||
|
||||
:return: An incremented reference to a data array object.
|
||||
:return: An incremented reference to a data array object. Release
|
||||
with :c:func:`obs_data_array_release()`.
|
||||
|
||||
---------------------
|
||||
|
||||
@@ -224,7 +230,8 @@ is not set.
|
||||
.. function:: void obs_data_set_default_obj(obs_data_t *data, const char *name, obs_data_t *obj)
|
||||
obs_data_t *obs_data_get_default_obj(obs_data_t *data, const char *name)
|
||||
|
||||
:return: An incremented reference to a data object.
|
||||
:return: An incremented reference to a data object. Release with
|
||||
:c:func:`obs_data_release()`.
|
||||
|
||||
----------------------
|
||||
|
||||
@@ -262,7 +269,8 @@ inappropriate or invalid.
|
||||
.. function:: void obs_data_set_autoselect_obj(obs_data_t *data, const char *name, obs_data_t *obj)
|
||||
obs_data_t *obs_data_get_autoselect_obj(obs_data_t *data, const char *name)
|
||||
|
||||
:return: An incremented reference to a data object.
|
||||
:return: An incremented reference to a data object. Release with
|
||||
:c:func:`obs_data_release()`.
|
||||
|
||||
---------------------
|
||||
|
||||
@@ -272,7 +280,8 @@ Array Functions
|
||||
|
||||
.. function:: obs_data_array_t *obs_data_array_create()
|
||||
|
||||
:return: A new reference to a data array object.
|
||||
:return: A new reference to a data array object. Release
|
||||
with :c:func:`obs_data_array_release()`.
|
||||
|
||||
---------------------
|
||||
|
||||
@@ -291,7 +300,7 @@ Array Functions
|
||||
.. function:: obs_data_t *obs_data_array_item(obs_data_array_t *array, size_t idx)
|
||||
|
||||
:return: An incremented reference to the data object associated with
|
||||
this array entry.
|
||||
this array entry. Release with :c:func:`obs_data_release()`.
|
||||
|
||||
---------------------
|
||||
|
||||
|
||||
@@ -692,7 +692,7 @@ General Source Functions
|
||||
Creates a source of the specified type with the specified settings.
|
||||
|
||||
The "source" context is used for anything related to presenting
|
||||
or modifying video/audio. Use obs_source_release to release it.
|
||||
or modifying video/audio. Use :c:func:`obs_source_release` to release it.
|
||||
|
||||
:param id: The source type string identifier
|
||||
:param name: The desired name of the source. If this is
|
||||
@@ -732,7 +732,8 @@ General Source Functions
|
||||
|
||||
Duplicates a source. If the source has the
|
||||
OBS_SOURCE_DO_NOT_DUPLICATE output flag set, this only returns a
|
||||
new reference to the same source.
|
||||
new reference to the same source. Either way,
|
||||
release with :c:func:`obs_source_release`.
|
||||
|
||||
:param source: The source to duplicate
|
||||
:param desired_name: The desired name of the new source. If this is
|
||||
@@ -756,7 +757,7 @@ General Source Functions
|
||||
.. function:: obs_source_t *obs_source_get_ref(obs_source_t *source)
|
||||
|
||||
Returns an incremented reference if still valid, otherwise returns
|
||||
*NULL*.
|
||||
*NULL*. Use :c:func:`obs_source_release` to release it.
|
||||
|
||||
---------------------
|
||||
|
||||
@@ -945,7 +946,8 @@ General Source Functions
|
||||
|
||||
.. function:: signal_handler_t *obs_source_get_signal_handler(const obs_source_t *source)
|
||||
|
||||
:return: The source's signal handler
|
||||
:return: The source's signal handler. Should not be manually freed,
|
||||
as its lifecycle is managed by libobs.
|
||||
|
||||
See the :ref:`source_signal_handler_reference` for more information
|
||||
on signals that are available for sources.
|
||||
@@ -954,7 +956,8 @@ General Source Functions
|
||||
|
||||
.. function:: proc_handler_t *obs_source_get_proc_handler(const obs_source_t *source)
|
||||
|
||||
:return: The procedure handler for a source
|
||||
:return: The procedure handler for a source. Should not be manually freed,
|
||||
as its lifecycle is managed by libobs.
|
||||
|
||||
---------------------
|
||||
|
||||
@@ -995,7 +998,7 @@ General Source Functions
|
||||
.. function:: void obs_source_set_audio_mixers(obs_source_t *source, uint32_t mixers)
|
||||
uint32_t obs_source_get_audio_mixers(const obs_source_t *source)
|
||||
|
||||
Sets/gets the audio mixer channels that a source outputs to,
|
||||
Sets/gets the audio mixer channels (i.e. audio tracks) that a source outputs to,
|
||||
depending on what bits are set. Audio mixers allow filtering
|
||||
specific using multiple audio encoders to mix different sources
|
||||
together depending on what mixer channel they're set to.
|
||||
@@ -1182,7 +1185,8 @@ General Source Functions
|
||||
.. function:: obs_data_t *obs_source_get_private_settings(obs_source_t *item)
|
||||
|
||||
Gets private front-end settings data. This data is saved/loaded
|
||||
automatically. Returns an incremented reference.
|
||||
automatically. Returns an incremented reference. Use :c:func:`obs_data_release()`
|
||||
to release it.
|
||||
|
||||
---------------------
|
||||
|
||||
@@ -1493,7 +1497,8 @@ Transitions
|
||||
:param target: | OBS_TRANSITION_SOURCE_A - Source being transitioned from, or the current source if not transitioning
|
||||
| OBS_TRANSITION_SOURCE_B - Source being transitioned to
|
||||
:return: An incremented reference to the source or destination
|
||||
sources of the transition
|
||||
sources of the transition. Use :c:func:`obs_source_release`
|
||||
to release it.
|
||||
|
||||
---------------------
|
||||
|
||||
@@ -1506,7 +1511,7 @@ Transitions
|
||||
.. function:: obs_source_t *obs_transition_get_active_source(obs_source_t *transition)
|
||||
|
||||
:return: An incremented reference to the currently active source of
|
||||
the transition
|
||||
the transition. Use :c:func:`obs_source_release` to release it.
|
||||
|
||||
---------------------
|
||||
|
||||
|
||||
Reference in New Issue
Block a user