mirror of
https://github.com/obsproject/obs-studio.git
synced 2026-08-28 17:42:28 +08:00
Richard Stanway
6d0083dd61
obs_module_unload was never properly documented, so some plugins use it to free resources, some use it to save data, etc. While libobs tries to ensure all objects are shut down and destroyed before calling unload, if another plugin is holding a strong reference, or if a reference leak has occurred, libobs may need to call back into a plugin-provided object's destroy function even after obs_module_unload has returned. If the plugin has freed memory or other resources needed for the callback then this likely results in a crash. Going forward, we should document that obs_module_unload is now intended only for saving data and releasing references, and that calling libobs after it returns is not allowed. For cases where resource cleanup is actually needed (for example, an external out of process helper needs to be shut down or a release call to a hardware driver), a new obs_module_destroy callback is intended to be added in a future version.
395 lines
11 KiB
ReStructuredText
395 lines
11 KiB
ReStructuredText
Module API Reference
|
|
====================
|
|
|
|
Modules add custom functionality to libobs: typically
|
|
:ref:`plugins_sources`, :ref:`plugins_outputs`, :ref:`plugins_encoders`,
|
|
and :ref:`plugins_services`.
|
|
|
|
.. type:: obs_module_t
|
|
|
|
A module object (not reference counted).
|
|
|
|
.. code:: cpp
|
|
|
|
#include <obs-module.h>
|
|
|
|
|
|
Module Macros
|
|
-------------
|
|
|
|
These macros are used within custom plugin modules.
|
|
|
|
.. macro:: OBS_DECLARE_MODULE()
|
|
|
|
Declares a libobs module. Exports important core module functions
|
|
related to the module itself, OBS version, etc.
|
|
|
|
---------------------
|
|
|
|
.. macro:: OBS_MODULE_USE_DEFAULT_LOCALE(module_name, default_locale)
|
|
|
|
Helper macro that uses the standard ini file format for localization.
|
|
Automatically initializes and destroys localization data, and
|
|
automatically provides module externs such as
|
|
:c:func:`obs_module_text()` to be able to get a localized string with
|
|
little effort.
|
|
|
|
---------------------
|
|
|
|
Module Exports
|
|
--------------
|
|
|
|
These are functions that plugin modules can optionally export in order
|
|
to communicate with libobs and front-ends.
|
|
|
|
.. function:: bool obs_module_load(void)
|
|
|
|
Required: Called when the module is loaded. Implement this function
|
|
to load all the sources/encoders/outputs/services for your module, or
|
|
anything else that may need loading.
|
|
|
|
:return: Return true to continue loading the module, otherwise
|
|
false to indicate failure and unload the module
|
|
|
|
---------------------
|
|
|
|
.. function:: void obs_module_unload(void)
|
|
|
|
Optional: Called when libobs is shutting down and the module is about
|
|
to be unloaded. All libobs objects are still active and valid at this
|
|
point. Use this function to save user settings and release any strong
|
|
references that the module itself is holding to libobs objects (sources,
|
|
canvases, outputs, encoders, and services).
|
|
|
|
Do not attempt to release or destroy any still-active objects provided
|
|
by the module - ensure that they can continue functioning even after
|
|
returning from this function, as libobs may still need to call into the
|
|
module's callbacks (e.g., destroy) to clean up any remaining instances.
|
|
|
|
After this function returns, do not make any further libobs API calls
|
|
outside of libobs callbacks.
|
|
|
|
---------------------
|
|
|
|
.. function:: void obs_module_post_load(void)
|
|
|
|
Optional: Called when all modules have finished loading.
|
|
|
|
---------------------
|
|
|
|
.. function:: void obs_module_set_locale(const char *locale)
|
|
|
|
Called to set the locale language and load the locale data for the
|
|
module.
|
|
|
|
---------------------
|
|
|
|
.. function:: void obs_module_free_locale(void)
|
|
|
|
Called on module destruction to free locale data.
|
|
|
|
---------------------
|
|
|
|
.. function:: const char *obs_module_name(void)
|
|
|
|
(Optional)
|
|
|
|
:return: The full name of the module
|
|
|
|
---------------------
|
|
|
|
.. function:: const char *obs_module_description(void)
|
|
|
|
(Optional)
|
|
|
|
:return: A description of the module
|
|
|
|
---------------------
|
|
|
|
|
|
Module Externs
|
|
--------------
|
|
|
|
These functions are externs that are usable throughout the module.
|
|
|
|
.. function:: const char *obs_module_text(const char *lookup_string)
|
|
|
|
:return: A localized string
|
|
|
|
---------------------
|
|
|
|
.. function:: bool obs_module_get_string(const char *lookup_string, const char **translated_string)
|
|
|
|
Helper function for looking up locale.
|
|
|
|
:return: *true* if text found, otherwise *false*
|
|
|
|
---------------------
|
|
|
|
.. function:: obs_module_t *obs_current_module(void)
|
|
|
|
:return: The current module
|
|
|
|
---------------------
|
|
|
|
.. function:: char *obs_module_file(const char *file)
|
|
|
|
Returns the location to a module data file associated with the
|
|
current module. Free with :c:func:`bfree()` when complete.
|
|
|
|
Equivalent to:
|
|
|
|
.. code:: cpp
|
|
|
|
obs_find_module_file(obs_current_module(), file);
|
|
|
|
---------------------
|
|
|
|
.. function:: char *obs_module_config_path(const char *file)
|
|
|
|
Returns the location to a module config file associated with the
|
|
current module. Free with :c:func:`bfree()` when complete. Will
|
|
return NULL if configuration directory is not set.
|
|
|
|
Equivalent to:
|
|
|
|
.. code:: cpp
|
|
|
|
obs_module_get_config_path(obs_current_module(), file);
|
|
|
|
---------------------
|
|
|
|
|
|
Frontend Module Functions
|
|
--------------------------
|
|
|
|
These are functions used by frontends to load and get information about
|
|
plugin modules.
|
|
|
|
.. function:: int obs_open_module(obs_module_t **module, const char *path, const char *data_path)
|
|
|
|
Opens a plugin module directly from a specific path.
|
|
|
|
If the module already exists then the function will return successful, and
|
|
the module parameter will be given the pointer to the existing
|
|
module.
|
|
|
|
This does not initialize the module, it only loads the module image. To
|
|
initialize the module, call :c:func:`obs_init_module()`.
|
|
|
|
:param module: The pointer to the created module
|
|
:param path: Specifies the path to the module library file. If the
|
|
extension is not specified, it will use the extension
|
|
appropriate to the operating system
|
|
:param data_path: Specifies the path to the directory where the module's
|
|
data files are stored (or *NULL* if none)
|
|
:returns: | MODULE_SUCCESS - Successful
|
|
| MODULE_ERROR - A generic error occurred
|
|
| MODULE_FILE_NOT_FOUND - The module was not found
|
|
| MODULE_MISSING_EXPORTS - Required exports are missing
|
|
| MODULE_INCOMPATIBLE_VER - Incompatible version
|
|
| MODULE_HARDCODED_SKIP - Skipped by hardcoded rules
|
|
(e.g. obsolete obs-browser macOS plugin)
|
|
|
|
---------------------
|
|
|
|
.. function:: bool obs_init_module(obs_module_t *module)
|
|
|
|
Initializes the module, which calls its obs_module_load export.
|
|
|
|
:return: *true* if the module was loaded successfully
|
|
|
|
---------------------
|
|
|
|
.. function:: void obs_log_loaded_modules(void)
|
|
|
|
Logs loaded modules.
|
|
|
|
---------------------
|
|
|
|
.. function:: const char *obs_get_module_file_name(obs_module_t *module)
|
|
|
|
:return: The module file name
|
|
|
|
---------------------
|
|
|
|
.. function:: const char *obs_get_module_name(obs_module_t *module)
|
|
|
|
:return: The module full name (or *NULL* if none)
|
|
|
|
---------------------
|
|
|
|
.. function:: void obs_get_module_author(obs_module_t *module)
|
|
|
|
:return: The module author(s)
|
|
|
|
---------------------
|
|
|
|
.. function:: const char *obs_get_module_description(obs_module_t *module)
|
|
|
|
:return: The module description
|
|
|
|
---------------------
|
|
|
|
.. function:: const char *obs_get_module_binary_path(obs_module_t *module)
|
|
|
|
:return: The module binary path
|
|
|
|
---------------------
|
|
|
|
.. function:: const char *obs_get_module_data_path(obs_module_t *module)
|
|
|
|
:return: The module data path
|
|
|
|
---------------------
|
|
|
|
.. function:: void obs_add_module_path(const char *bin, const char *data)
|
|
|
|
Adds a module search path to be used with obs_find_modules. If the search
|
|
path strings contain %module%, that text will be replaced with the module
|
|
name when used.
|
|
|
|
:param bin: Specifies the module's binary directory search path
|
|
:param data: Specifies the module's data directory search path
|
|
|
|
---------------------
|
|
|
|
.. function:: void obs_load_all_modules(void)
|
|
|
|
Automatically loads all modules from module paths (convenience function).
|
|
|
|
---------------------
|
|
|
|
.. function:: void obs_load_all_modules2(struct obs_module_failure_info *mfi)
|
|
|
|
Automatically loads all modules from module paths (convenience function).
|
|
Additionally gives you information about modules that fail to load.
|
|
|
|
:param mfi: Provides module failure information. The *failed_modules*
|
|
member is a string list via a pointer to pointers of
|
|
strings of modules that failed to load. Can be freed
|
|
either with :c:func:`obs_module_failure_info_free()` or
|
|
by simply calling :c:func:`bfree()` on the
|
|
*failed_modules* member variable.
|
|
|
|
Relevant data types used with this function:
|
|
|
|
.. code:: cpp
|
|
|
|
struct obs_module_failure_info {
|
|
char **failed_modules;
|
|
size_t count;
|
|
};
|
|
|
|
---------------------
|
|
|
|
.. function:: void obs_add_safe_module(const char *name)
|
|
|
|
Adds a *name* to the list of modules allowed to load in Safe Mode.
|
|
If the list is empty, all modules are allowed.
|
|
|
|
:param name: The name of the module (filename sans extension).
|
|
|
|
.. versionadded:: 30.0
|
|
|
|
---------------------
|
|
|
|
.. function:: void obs_module_failure_info_free(struct obs_module_failure_info *mfi)
|
|
|
|
Frees data allocated data used in the *mfi* parameter (calls
|
|
:c:func:`bfree()` on the *failed_modules* member variable).
|
|
|
|
---------------------
|
|
|
|
.. function:: void obs_post_load_modules(void)
|
|
|
|
Notifies modules that all modules have been loaded.
|
|
|
|
---------------------
|
|
|
|
.. function:: void obs_find_modules(obs_find_module_callback_t callback, void *param)
|
|
|
|
Finds all modules within the search paths added by
|
|
:c:func:`obs_add_module_path()`.
|
|
|
|
Relevant data types used with this function:
|
|
|
|
.. code:: cpp
|
|
|
|
struct obs_module_info {
|
|
const char *bin_path;
|
|
const char *data_path;
|
|
};
|
|
|
|
typedef void (*obs_find_module_callback_t)(void *param,
|
|
const struct obs_module_info *info);
|
|
|
|
---------------------
|
|
|
|
.. function:: void obs_find_modules2(obs_find_module_callback_t callback, void *param)
|
|
|
|
Finds all modules within the search paths added by
|
|
:c:func:`obs_add_module_path()`.
|
|
|
|
Relevant data types used with this function:
|
|
|
|
.. code:: cpp
|
|
|
|
struct obs_module_info2 {
|
|
const char *bin_path;
|
|
const char *data_path;
|
|
const char *name;
|
|
};
|
|
|
|
typedef void (*obs_find_module_callback2_t)(void *param,
|
|
const struct obs_module_info2 *info);
|
|
|
|
---------------------
|
|
|
|
.. function:: void obs_enum_modules(obs_enum_module_callback_t callback, void *param)
|
|
|
|
Enumerates all loaded modules.
|
|
|
|
Relevant data types used with this function:
|
|
|
|
.. code:: cpp
|
|
|
|
typedef void (*obs_enum_module_callback_t)(void *param, obs_module_t *module);
|
|
|
|
---------------------
|
|
|
|
.. function:: char *obs_find_module_file(obs_module_t *module, const char *file)
|
|
|
|
Returns the location of a plugin module data file.
|
|
|
|
Note: Modules should use obs_module_file function defined in obs-module.h
|
|
as a more elegant means of getting their files without having to
|
|
specify the module parameter.
|
|
|
|
:param module: The module associated with the file to locate
|
|
:param file: The file to locate
|
|
:return: Path string, or NULL if not found. Use bfree to free string
|
|
|
|
---------------------
|
|
|
|
.. function:: char *obs_module_get_config_path(obs_module_t *module, const char *file)
|
|
|
|
Returns the path of a plugin module config file (whether it exists or not).
|
|
|
|
Note: Modules should use obs_module_config_path function defined in
|
|
obs-module.h as a more elegant means of getting their files without
|
|
having to specify the module parameter.
|
|
|
|
:param module: The module associated with the path
|
|
:param file: The file to get a path to
|
|
:return: Path string, or NULL if not found. Use bfree to free string
|
|
|
|
---------------------
|
|
|
|
.. function:: void *obs_get_module_lib(obs_module_t *module)
|
|
|
|
Returns library file of specified module.
|
|
|
|
:param module: The module where to find library file.
|
|
:return: Pointer to module library.
|