diff --git a/docs/sphinx/reference-core.rst b/docs/sphinx/reference-core.rst index 7f186d585..e893dbd11 100644 --- a/docs/sphinx/reference-core.rst +++ b/docs/sphinx/reference-core.rst @@ -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: diff --git a/docs/sphinx/reference-encoders.rst b/docs/sphinx/reference-encoders.rst index 116711c88..7ff45a561 100644 --- a/docs/sphinx/reference-encoders.rst +++ b/docs/sphinx/reference-encoders.rst @@ -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. --------------------- diff --git a/docs/sphinx/reference-frontend-api.rst b/docs/sphinx/reference-frontend-api.rst index 418d53eca..537beb2cb 100644 --- a/docs/sphinx/reference-frontend-api.rst +++ b/docs/sphinx/reference-frontend-api.rst @@ -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()`. --------------------------------------- diff --git a/docs/sphinx/reference-libobs-callback.rst b/docs/sphinx/reference-libobs-callback.rst index 533e6f3ca..ff741a832 100644 --- a/docs/sphinx/reference-libobs-callback.rst +++ b/docs/sphinx/reference-libobs-callback.rst @@ -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 diff --git a/docs/sphinx/reference-outputs.rst b/docs/sphinx/reference-outputs.rst index ab6bebb8e..a0766ef48 100644 --- a/docs/sphinx/reference-outputs.rst +++ b/docs/sphinx/reference-outputs.rst @@ -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. --------------------- diff --git a/docs/sphinx/reference-properties.rst b/docs/sphinx/reference-properties.rst index 9fc5ebdea..9c4b97936 100644 --- a/docs/sphinx/reference-properties.rst +++ b/docs/sphinx/reference-properties.rst @@ -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) diff --git a/docs/sphinx/reference-scenes.rst b/docs/sphinx/reference-scenes.rst index dab97e862..746c4516d 100644 --- a/docs/sphinx/reference-scenes.rst +++ b/docs/sphinx/reference-scenes.rst @@ -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()`. --------------------- diff --git a/docs/sphinx/reference-services.rst b/docs/sphinx/reference-services.rst index 4d8bab5a9..85a0c8762 100644 --- a/docs/sphinx/reference-services.rst +++ b/docs/sphinx/reference-services.rst @@ -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()`. --------------------- diff --git a/docs/sphinx/reference-settings.rst b/docs/sphinx/reference-settings.rst index 821483d8e..fc881efde 100644 --- a/docs/sphinx/reference-settings.rst +++ b/docs/sphinx/reference-settings.rst @@ -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()`. --------------------- diff --git a/docs/sphinx/reference-sources.rst b/docs/sphinx/reference-sources.rst index 57d247087..40d5836ec 100644 --- a/docs/sphinx/reference-sources.rst +++ b/docs/sphinx/reference-sources.rst @@ -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. ---------------------