1 /****************************************************************************** 2 Copyright (C) 2013-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 /** 23 * @file 24 * @brief header for modules implementing sources. 25 * 26 * Sources are modules that either feed data to libobs or modify it. 27 */ 28 29 #ifdef __cplusplus 30 extern "C" { 31 #endif 32 33 enum obs_source_type { 34 OBS_SOURCE_TYPE_INPUT, 35 OBS_SOURCE_TYPE_FILTER, 36 OBS_SOURCE_TYPE_TRANSITION, 37 OBS_SOURCE_TYPE_SCENE, 38 }; 39 40 enum obs_balance_type { 41 OBS_BALANCE_TYPE_SINE_LAW, 42 OBS_BALANCE_TYPE_SQUARE_LAW, 43 OBS_BALANCE_TYPE_LINEAR, 44 }; 45 46 enum obs_icon_type { 47 OBS_ICON_TYPE_UNKNOWN, 48 OBS_ICON_TYPE_IMAGE, 49 OBS_ICON_TYPE_COLOR, 50 OBS_ICON_TYPE_SLIDESHOW, 51 OBS_ICON_TYPE_AUDIO_INPUT, 52 OBS_ICON_TYPE_AUDIO_OUTPUT, 53 OBS_ICON_TYPE_DESKTOP_CAPTURE, 54 OBS_ICON_TYPE_WINDOW_CAPTURE, 55 OBS_ICON_TYPE_GAME_CAPTURE, 56 OBS_ICON_TYPE_CAMERA, 57 OBS_ICON_TYPE_TEXT, 58 OBS_ICON_TYPE_MEDIA, 59 OBS_ICON_TYPE_BROWSER, 60 OBS_ICON_TYPE_CUSTOM, 61 }; 62 63 enum obs_media_state { 64 OBS_MEDIA_STATE_NONE, 65 OBS_MEDIA_STATE_PLAYING, 66 OBS_MEDIA_STATE_OPENING, 67 OBS_MEDIA_STATE_BUFFERING, 68 OBS_MEDIA_STATE_PAUSED, 69 OBS_MEDIA_STATE_STOPPED, 70 OBS_MEDIA_STATE_ENDED, 71 OBS_MEDIA_STATE_ERROR, 72 }; 73 74 /** 75 * @name Source output flags 76 * 77 * These flags determine what type of data the source outputs and expects. 78 * @{ 79 */ 80 81 /** 82 * Source has video. 83 * 84 * Unless SOURCE_ASYNC_VIDEO is specified, the source must include the 85 * video_render callback in the source definition structure. 86 */ 87 #define OBS_SOURCE_VIDEO (1 << 0) 88 89 /** 90 * Source has audio. 91 * 92 * Use the obs_source_output_audio function to pass raw audio data, which will 93 * be automatically converted and uploaded. If used with SOURCE_ASYNC_VIDEO, 94 * audio will automatically be synced up to the video output. 95 */ 96 #define OBS_SOURCE_AUDIO (1 << 1) 97 98 /** Async video flag (use OBS_SOURCE_ASYNC_VIDEO) */ 99 #define OBS_SOURCE_ASYNC (1 << 2) 100 101 /** 102 * Source passes raw video data via RAM. 103 * 104 * Use the obs_source_output_video function to pass raw video data, which will 105 * be automatically uploaded at the specified timestamp. 106 * 107 * If this flag is specified, it is not necessary to include the video_render 108 * callback. However, if you wish to use that function as well, you must call 109 * obs_source_getframe to get the current frame data, and 110 * obs_source_releaseframe to release the data when complete. 111 */ 112 #define OBS_SOURCE_ASYNC_VIDEO (OBS_SOURCE_ASYNC | OBS_SOURCE_VIDEO) 113 114 /** 115 * Source uses custom drawing, rather than a default effect. 116 * 117 * If this flag is specified, the video_render callback will pass a NULL 118 * effect, and effect-based filters will not use direct rendering. 119 */ 120 #define OBS_SOURCE_CUSTOM_DRAW (1 << 3) 121 122 /** 123 * Source supports interaction. 124 * 125 * When this is used, the source will receive interaction events 126 * if they provide the necessary callbacks in the source definition structure. 127 */ 128 #define OBS_SOURCE_INTERACTION (1 << 5) 129 130 /** 131 * Source composites sub-sources 132 * 133 * When used specifies that the source composites one or more sub-sources. 134 * Sources that render sub-sources must implement the audio_render callback 135 * in order to perform custom mixing of sub-sources. 136 * 137 * This capability flag is always set for transitions. 138 */ 139 #define OBS_SOURCE_COMPOSITE (1 << 6) 140 141 /** 142 * Source should not be fully duplicated 143 * 144 * When this is used, specifies that the source should not be fully duplicated, 145 * and should prefer to duplicate via holding references rather than full 146 * duplication. 147 */ 148 #define OBS_SOURCE_DO_NOT_DUPLICATE (1 << 7) 149 150 /** 151 * Source is deprecated and should not be used 152 */ 153 #define OBS_SOURCE_DEPRECATED (1 << 8) 154 155 /** 156 * Source cannot have its audio monitored 157 * 158 * Specifies that this source may cause a feedback loop if audio is monitored 159 * with a device selected as desktop audio. 160 * 161 * This is used primarily with desktop audio capture sources. 162 */ 163 #define OBS_SOURCE_DO_NOT_SELF_MONITOR (1 << 9) 164 165 /** 166 * Source type is currently disabled and should not be shown to the user 167 */ 168 #define OBS_SOURCE_CAP_DISABLED (1 << 10) 169 170 /** 171 * Source type is obsolete (has been updated with new defaults/properties/etc) 172 */ 173 #define OBS_SOURCE_CAP_OBSOLETE OBS_SOURCE_CAP_DISABLED 174 175 /** 176 * Source should enable monitoring by default. Monitoring should be set by the 177 * frontend if this flag is set. 178 */ 179 #define OBS_SOURCE_MONITOR_BY_DEFAULT (1 << 11) 180 181 /** Used internally for audio submixing */ 182 #define OBS_SOURCE_SUBMIX (1 << 12) 183 184 /** 185 * Source type can be controlled by media controls 186 */ 187 #define OBS_SOURCE_CONTROLLABLE_MEDIA (1 << 13) 188 189 /** 190 * Source type provides cea708 data 191 */ 192 #define OBS_SOURCE_CEA_708 (1 << 14) 193 194 /** 195 * Source understands SRGB rendering 196 */ 197 #define OBS_SOURCE_SRGB (1 << 15) 198 199 /** @} */ 200 201 typedef void (*obs_source_enum_proc_t)(obs_source_t *parent, 202 obs_source_t *child, void *param); 203 204 struct obs_source_audio_mix { 205 struct audio_output_data output[MAX_AUDIO_MIXES]; 206 }; 207 208 /** 209 * Source definition structure 210 */ 211 struct obs_source_info { 212 /* ----------------------------------------------------------------- */ 213 /* Required implementation*/ 214 215 /** Unique string identifier for the source */ 216 const char *id; 217 218 /** 219 * Type of source. 220 * 221 * OBS_SOURCE_TYPE_INPUT for input sources, 222 * OBS_SOURCE_TYPE_FILTER for filter sources, and 223 * OBS_SOURCE_TYPE_TRANSITION for transition sources. 224 */ 225 enum obs_source_type type; 226 227 /** Source output flags */ 228 uint32_t output_flags; 229 230 /** 231 * Get the translated name of the source type 232 * 233 * @param type_data The type_data variable of this structure 234 * @return The translated name of the source type 235 */ 236 const char *(*get_name)(void *type_data); 237 238 /** 239 * Creates the source data for the source 240 * 241 * @param settings Settings to initialize the source with 242 * @param source Source that this data is associated with 243 * @return The data associated with this source 244 */ 245 void *(*create)(obs_data_t *settings, obs_source_t *source); 246 247 /** 248 * Destroys the private data for the source 249 * 250 * Async sources must not call obs_source_output_video after returning 251 * from destroy 252 */ 253 void (*destroy)(void *data); 254 255 /** Returns the width of the source. Required if this is an input 256 * source and has non-async video */ 257 uint32_t (*get_width)(void *data); 258 259 /** Returns the height of the source. Required if this is an input 260 * source and has non-async video */ 261 uint32_t (*get_height)(void *data); 262 263 /* ----------------------------------------------------------------- */ 264 /* Optional implementation */ 265 266 /** 267 * Gets the default settings for this source 268 * 269 * @param[out] settings Data to assign default settings to 270 * @deprecated Use get_defaults2 if type_data is needed 271 */ 272 void (*get_defaults)(obs_data_t *settings); 273 274 /** 275 * Gets the property information of this source 276 * 277 * @return The properties data 278 * @deprecated Use get_properties2 if type_data is needed 279 */ 280 obs_properties_t *(*get_properties)(void *data); 281 282 /** 283 * Updates the settings for this source 284 * 285 * @param data Source data 286 * @param settings New settings for this source 287 */ 288 void (*update)(void *data, obs_data_t *settings); 289 290 /** Called when the source has been activated in the main view */ 291 void (*activate)(void *data); 292 293 /** 294 * Called when the source has been deactivated from the main view 295 * (no longer being played/displayed) 296 */ 297 void (*deactivate)(void *data); 298 299 /** Called when the source is visible */ 300 void (*show)(void *data); 301 302 /** Called when the source is no longer visible */ 303 void (*hide)(void *data); 304 305 /** 306 * Called each video frame with the time elapsed 307 * 308 * @param data Source data 309 * @param seconds Seconds elapsed since the last frame 310 */ 311 void (*video_tick)(void *data, float seconds); 312 313 /** 314 * Called when rendering the source with the graphics subsystem. 315 * 316 * If this is an input/transition source, this is called to draw the 317 * source texture with the graphics subsystem using the specified 318 * effect. 319 * 320 * If this is a filter source, it wraps source draw calls (for 321 * example applying a custom effect with custom parameters to a 322 * source). In this case, it's highly recommended to use the 323 * obs_source_process_filter function to automatically handle 324 * effect-based filter processing. However, you can implement custom 325 * draw handling as desired as well. 326 * 327 * If the source output flags do not include SOURCE_CUSTOM_DRAW, all 328 * a source needs to do is set the "image" parameter of the effect to 329 * the desired texture, and then draw. If the output flags include 330 * SOURCE_COLOR_MATRIX, you may optionally set the "color_matrix" 331 * parameter of the effect to a custom 4x4 conversion matrix (by 332 * default it will be set to an YUV->RGB conversion matrix) 333 * 334 * @param data Source data 335 * @param effect Effect to be used with this source. If the source 336 * output flags include SOURCE_CUSTOM_DRAW, this will 337 * be NULL, and the source is expected to process with 338 * an effect manually. 339 */ 340 void (*video_render)(void *data, gs_effect_t *effect); 341 342 /** 343 * Called to filter raw async video data. 344 * 345 * @note This function is only used with filter sources. 346 * 347 * @param data Filter data 348 * @param frame Video frame to filter 349 * @return New video frame data. This can defer video data to 350 * be drawn later if time is needed for processing 351 */ 352 struct obs_source_frame *(*filter_video)( 353 void *data, struct obs_source_frame *frame); 354 355 /** 356 * Called to filter raw audio data. 357 * 358 * @note This function is only used with filter sources. 359 * 360 * @param data Filter data 361 * @param audio Audio data to filter. 362 * @return Modified or new audio data. You can directly modify 363 * the data passed and return it, or you can defer audio 364 * data for later if time is needed for processing. If 365 * you are returning new data, that data must exist 366 * until the next call to the filter_audio callback or 367 * until the filter is removed/destroyed. 368 */ 369 struct obs_audio_data *(*filter_audio)(void *data, 370 struct obs_audio_data *audio); 371 372 /** 373 * Called to enumerate all active sources being used within this 374 * source. If the source has children that render audio/video it must 375 * implement this callback. 376 * 377 * @param data Filter data 378 * @param enum_callback Enumeration callback 379 * @param param User data to pass to callback 380 */ 381 void (*enum_active_sources)(void *data, 382 obs_source_enum_proc_t enum_callback, 383 void *param); 384 385 /** 386 * Called when saving a source. This is a separate function because 387 * sometimes a source needs to know when it is being saved so it 388 * doesn't always have to update the current settings until a certain 389 * point. 390 * 391 * @param data Source data 392 * @param settings Settings 393 */ 394 void (*save)(void *data, obs_data_t *settings); 395 396 /** 397 * Called when loading a source from saved data. This should be called 398 * after all the loading sources have actually been created because 399 * sometimes there are sources that depend on each other. 400 * 401 * @param data Source data 402 * @param settings Settings 403 */ 404 void (*load)(void *data, obs_data_t *settings); 405 406 /** 407 * Called when interacting with a source and a mouse-down or mouse-up 408 * occurs. 409 * 410 * @param data Source data 411 * @param event Mouse event properties 412 * @param type Mouse button pushed 413 * @param mouse_up Mouse event type (true if mouse-up) 414 * @param click_count Mouse click count (1 for single click, etc.) 415 */ 416 void (*mouse_click)(void *data, const struct obs_mouse_event *event, 417 int32_t type, bool mouse_up, uint32_t click_count); 418 /** 419 * Called when interacting with a source and a mouse-move occurs. 420 * 421 * @param data Source data 422 * @param event Mouse event properties 423 * @param mouse_leave Mouse leave state (true if mouse left source) 424 */ 425 void (*mouse_move)(void *data, const struct obs_mouse_event *event, 426 bool mouse_leave); 427 428 /** 429 * Called when interacting with a source and a mouse-wheel occurs. 430 * 431 * @param data Source data 432 * @param event Mouse event properties 433 * @param x_delta Movement delta in the horizontal direction 434 * @param y_delta Movement delta in the vertical direction 435 */ 436 void (*mouse_wheel)(void *data, const struct obs_mouse_event *event, 437 int x_delta, int y_delta); 438 /** 439 * Called when interacting with a source and gain focus/lost focus event 440 * occurs. 441 * 442 * @param data Source data 443 * @param focus Focus state (true if focus gained) 444 */ 445 void (*focus)(void *data, bool focus); 446 447 /** 448 * Called when interacting with a source and a key-up or key-down 449 * occurs. 450 * 451 * @param data Source data 452 * @param event Key event properties 453 * @param focus Key event type (true if mouse-up) 454 */ 455 void (*key_click)(void *data, const struct obs_key_event *event, 456 bool key_up); 457 458 /** 459 * Called when the filter is removed from a source 460 * 461 * @param data Filter data 462 * @param source Source that the filter being removed from 463 */ 464 void (*filter_remove)(void *data, obs_source_t *source); 465 466 /** 467 * Private data associated with this entry 468 */ 469 void *type_data; 470 471 /** 472 * If defined, called to free private data on shutdown 473 */ 474 void (*free_type_data)(void *type_data); 475 476 bool (*audio_render)(void *data, uint64_t *ts_out, 477 struct obs_source_audio_mix *audio_output, 478 uint32_t mixers, size_t channels, 479 size_t sample_rate); 480 481 /** 482 * Called to enumerate all active and inactive sources being used 483 * within this source. If this callback isn't implemented, 484 * enum_active_sources will be called instead. 485 * 486 * This is typically used if a source can have inactive child sources. 487 * 488 * @param data Filter data 489 * @param enum_callback Enumeration callback 490 * @param param User data to pass to callback 491 */ 492 void (*enum_all_sources)(void *data, 493 obs_source_enum_proc_t enum_callback, 494 void *param); 495 496 void (*transition_start)(void *data); 497 void (*transition_stop)(void *data); 498 499 /** 500 * Gets the default settings for this source 501 * 502 * If get_defaults is also defined both will be called, and the first 503 * call will be to get_defaults, then to get_defaults2. 504 * 505 * @param type_data The type_data variable of this structure 506 * @param[out] settings Data to assign default settings to 507 */ 508 void (*get_defaults2)(void *type_data, obs_data_t *settings); 509 510 /** 511 * Gets the property information of this source 512 * 513 * @param data Source data 514 * @param type_data The type_data variable of this structure 515 * @return The properties data 516 */ 517 obs_properties_t *(*get_properties2)(void *data, void *type_data); 518 519 bool (*audio_mix)(void *data, uint64_t *ts_out, 520 struct audio_output_data *audio_output, 521 size_t channels, size_t sample_rate); 522 523 /** Icon type for the source */ 524 enum obs_icon_type icon_type; 525 526 /** Media controls */ 527 void (*media_play_pause)(void *data, bool pause); 528 void (*media_restart)(void *data); 529 void (*media_stop)(void *data); 530 void (*media_next)(void *data); 531 void (*media_previous)(void *data); 532 int64_t (*media_get_duration)(void *data); 533 int64_t (*media_get_time)(void *data); 534 void (*media_set_time)(void *data, int64_t miliseconds); 535 enum obs_media_state (*media_get_state)(void *data); 536 537 /* version-related stuff */ 538 uint32_t version; /* increment if needed to specify a new version */ 539 const char *unversioned_id; /* set internally, don't set manually */ 540 541 /** Missing files **/ 542 obs_missing_files_t *(*missing_files)(void *data); 543 }; 544 545 EXPORT void obs_register_source_s(const struct obs_source_info *info, 546 size_t size); 547 548 /** 549 * Registers a source definition to the current obs context. This should be 550 * used in obs_module_load. 551 * 552 * @param info Pointer to the source definition structure 553 */ 554 #define obs_register_source(info) \ 555 obs_register_source_s(info, sizeof(struct obs_source_info)) 556 557 #ifdef __cplusplus 558 } 559 #endif 560