1 /****************************************************************************** 2 Copyright (C) 2014 by Hugh Bailey <obs.jim@gmail.com> 3 4 This program is free software: you can redistribute it and/or modify 5 it under the terms of the GNU General Public License as published by 6 the Free Software Foundation, either version 2 of the License, or 7 (at your option) any later version. 8 9 This program is distributed in the hope that it will be useful, 10 but WITHOUT ANY WARRANTY; without even the implied warranty of 11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 12 GNU General Public License for more details. 13 14 You should have received a copy of the GNU General Public License 15 along with this program. If not, see <http://www.gnu.org/licenses/>. 16 ******************************************************************************/ 17 18 #pragma once 19 20 #include "obs.h" 21 22 #ifdef __cplusplus 23 #define MODULE_EXPORT extern "C" EXPORT 24 #define MODULE_EXTERN extern "C" 25 #else 26 #define MODULE_EXPORT EXPORT 27 #define MODULE_EXTERN extern 28 #endif 29 30 /** 31 * @file 32 * @brief This file is used by modules for module declaration and module 33 * exports. 34 * 35 * @page modules_page Modules 36 * @brief Modules or plugins are libraries that can be loaded by libobs and 37 * subsequently interact with it. 38 * 39 * @section modules_overview_sec Overview 40 * 41 * Modules can provide a wide range of functionality to libobs, they for example 42 * can feed captured audio or video to libobs, or interface with an encoder to 43 * provide some codec to libobs. 44 * 45 * @section modules_basic_sec Creating a basic module 46 * 47 * In order to create a module for libobs you will need to build a shared 48 * library that implements a basic interface for libobs to interact with. 49 * The following code would create a simple source plugin without localization: 50 * 51 @code 52 #include <obs-module.h> 53 54 OBS_DECLARE_MODULE() 55 56 extern struct obs_source_info my_source; 57 58 bool obs_module_load(void) 59 { 60 obs_register_source(&my_source); 61 return true; 62 } 63 @endcode 64 * 65 * If you want to enable localization, you will need to also use the 66 * @ref OBS_MODULE_USE_DEFAULT_LOCALE() macro. 67 * 68 * Other module types: 69 * - @ref obs_register_encoder() 70 * - @ref obs_register_service() 71 * - @ref obs_register_output() 72 * 73 */ 74 75 /** Required: Declares a libobs module. */ 76 #define OBS_DECLARE_MODULE() \ 77 static obs_module_t *obs_module_pointer; \ 78 MODULE_EXPORT void obs_module_set_pointer(obs_module_t *module); \ 79 void obs_module_set_pointer(obs_module_t *module) \ 80 { \ 81 obs_module_pointer = module; \ 82 } \ 83 obs_module_t *obs_current_module(void) { return obs_module_pointer; } \ 84 MODULE_EXPORT uint32_t obs_module_ver(void); \ 85 uint32_t obs_module_ver(void) { return LIBOBS_API_VER; } 86 87 /** 88 * Required: Called when the module is loaded. Use this function to load all 89 * the sources/encoders/outputs/services for your module, or anything else that 90 * may need loading. 91 * 92 * @return Return true to continue loading the module, otherwise 93 * false to indicate failure and unload the module 94 */ 95 MODULE_EXPORT bool obs_module_load(void); 96 97 /** Optional: Called when the module is unloaded. */ 98 MODULE_EXPORT void obs_module_unload(void); 99 100 /** Optional: Called when all modules have finished loading */ 101 MODULE_EXPORT void obs_module_post_load(void); 102 103 /** Called to set the current locale data for the module. */ 104 MODULE_EXPORT void obs_module_set_locale(const char *locale); 105 106 /** Called to free the current locale data for the module. */ 107 MODULE_EXPORT void obs_module_free_locale(void); 108 109 /** Optional: Use this macro in a module to use default locale handling. */ 110 #define OBS_MODULE_USE_DEFAULT_LOCALE(module_name, default_locale) \ 111 lookup_t *obs_module_lookup = NULL; \ 112 const char *obs_module_text(const char *val) \ 113 { \ 114 const char *out = val; \ 115 text_lookup_getstr(obs_module_lookup, val, &out); \ 116 return out; \ 117 } \ 118 bool obs_module_get_string(const char *val, const char **out) \ 119 { \ 120 return text_lookup_getstr(obs_module_lookup, val, out); \ 121 } \ 122 void obs_module_set_locale(const char *locale) \ 123 { \ 124 if (obs_module_lookup) \ 125 text_lookup_destroy(obs_module_lookup); \ 126 obs_module_lookup = obs_module_load_locale( \ 127 obs_current_module(), default_locale, locale); \ 128 } \ 129 void obs_module_free_locale(void) \ 130 { \ 131 text_lookup_destroy(obs_module_lookup); \ 132 obs_module_lookup = NULL; \ 133 } 134 135 /** Helper function for looking up locale if default locale handler was used */ 136 MODULE_EXTERN const char *obs_module_text(const char *lookup_string); 137 138 /** Helper function for looking up locale if default locale handler was used, 139 * returns true if text found, otherwise false */ 140 MODULE_EXPORT bool obs_module_get_string(const char *lookup_string, 141 const char **translated_string); 142 143 /** Helper function that returns the current module */ 144 MODULE_EXTERN obs_module_t *obs_current_module(void); 145 146 /** 147 * Returns the location to a module data file associated with the current 148 * module. Free with bfree when complete. Equivalent to: 149 * obs_find_module_file(obs_current_module(), file); 150 */ 151 #define obs_module_file(file) obs_find_module_file(obs_current_module(), file) 152 153 /** 154 * Returns the location to a module config file associated with the current 155 * module. Free with bfree when complete. Will return NULL if configuration 156 * directory is not set. Equivalent to: 157 * obs_module_get_config_path(obs_current_module(), file); 158 */ 159 #define obs_module_config_path(file) \ 160 obs_module_get_config_path(obs_current_module(), file) 161 162 /** 163 * Optional: Declares the author(s) of the module 164 * 165 * @param name Author name(s) 166 */ 167 #define OBS_MODULE_AUTHOR(name) \ 168 MODULE_EXPORT const char *obs_module_author(void); \ 169 const char *obs_module_author(void) { return name; } 170 171 /** Optional: Returns the full name of the module */ 172 MODULE_EXPORT const char *obs_module_name(void); 173 174 /** Optional: Returns a description of the module */ 175 MODULE_EXPORT const char *obs_module_description(void); 176