diff --git a/.gitignore b/.gitignore index 3606bf56f..2267e3e92 100644 --- a/.gitignore +++ b/.gitignore @@ -42,6 +42,11 @@ install-sh Makefile.in Makefile +#sphinx +/docs/sphinx/_build/* +!/docs/sphinx/_build/.gitignore +!/docs/sphinx/Makefile + #random useless file stuff *.dmg *.app diff --git a/docs/sphinx/Makefile b/docs/sphinx/Makefile new file mode 100644 index 000000000..6a2b50199 --- /dev/null +++ b/docs/sphinx/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SPHINXPROJ = OBSStudio +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/docs/sphinx/_build/.gitignore b/docs/sphinx/_build/.gitignore new file mode 100644 index 000000000..e69de29bb diff --git a/docs/sphinx/_static/.gitignore b/docs/sphinx/_static/.gitignore new file mode 100644 index 000000000..e69de29bb diff --git a/docs/sphinx/_templates/.gitignore b/docs/sphinx/_templates/.gitignore new file mode 100644 index 000000000..e69de29bb diff --git a/docs/sphinx/backend-design.rst b/docs/sphinx/backend-design.rst new file mode 100644 index 000000000..8602bede1 --- /dev/null +++ b/docs/sphinx/backend-design.rst @@ -0,0 +1,194 @@ +OBS Studio Backend Design +========================= +The OBS Studio backend is powered by the library libobs. Libobs +provides the main pipeline, the video/audio subsystems, and the general +framework for all plugins. + + +Libobs Plugin Objects +--------------------- +Libobs is designed to be modular, where adding modules will add custom +functionality. There are four libobs objects that you can make plugins +for: + +- :ref:`plugins_sources` -- Sources are used to render video and/or + audio on stream. Things such as capturing displays/games/audio, + playing a video, showing an image, or playing audio. Sources can also + be used to implement audio and video filters. + +- :ref:`plugins_outputs` -- Outputs allow the ability to output the + currently rendering audio/video. Streaming and recording are two + common examples of outputs, but not the only types of outputs. + Outputs can receive the raw data or receive encoded data. + +- :ref:`plugins_encoders` -- Encoders are OBS-specific implementations + of video/audio encoders, which are used with outputs that use + encoders. x264, NVENC, Quicksync are examples of encoder + implementations. + +- :ref:`plugins_services` -- Services are custom implementations of + streaming services, which are used with outputs that stream. For + example, you could have a custom implementation for streaming to + Twitch, and another for YouTube to allow the ability to log in and use + their APIs to do things such as get the RTMP servers or control the + channel. + +*(Author's note: the service API is incomplete as of this writing)* + + +Libobs Threads +-------------- +There are three primary threads spawned by libobs on initialization: + +- The obs_graphics_thread_ function used exclusively for rendering in + `libobs/obs-video.c`_ + +- The video_thread_ function used exclusively for video encoding/output + in `libobs/media-io/video-io.c`_ + +- The audio_thread_ function used for all audio + processing/encoding/output in `libobs/media-io/audio-io.c`_ + +*(Author's note: obs_graphics_thread was originally named +obs_video_thread; it was renamed as of this writing to prevent confusion +with video_thread)* + + +.. _output_channels: + +Output Channels +--------------- +Rendering video or audio starts from output channels. You assign a +source to an output channel via the :c:func:`obs_set_output_source()` +function. The *channel* parameter can be any number from +0..(MAX_CHANNELS_-1). You may initially think that this is how you +display multiple sources at once; however, sources are hierarchical. +Sources such as scenes or transitions can have multiple sub-sources, and +those sub-sources in turn can have sub-sources and so on (see +:ref:`displaying_sources` for more information). Typically, you would +use scenes to draw multiple sources as a group with specific transforms +for each source, as a scene is just another type of source. The +"channel" design allows for highly complex video presentation setups. +The OBS Studio front-end has yet to even fully utilize this back-end +design for its rendering, and currently only uses one output channel to +render one scene at a time. It does however utilize additional channels +for things such as global audio sources which are set in audio settings. + +*(Author's note: "Output channels" are not to be confused with output +objects or audio channels. Output channels are used to set the sources +you want to output, and output objects are used for actually +streaming/recording/etc.)* + + +General Video Pipeline Overview +------------------------------- +The video graphics pipeline is run from two threads: a dedicated +graphics thread that renders preview displays as well as the final mix +(the obs_graphics_thread_ function in `libobs/obs-video.c`_), and a +dedicated thread specific to video encoding/output (the video_thread_ +function in `libobs/media-io/video-io.c`_). + +Sources assigned to output channels will be drawn from channels +0..(MAX_CHANNELS_-1). They are drawn on to the final texture which will +be used for output `[1]`_. Once all sources are drawn, the final +texture is converted to whatever format that libobs is set to (typically +a YUV format). After being converted to the back-end video format, it's +then sent along with its timestamp to the current video handler, +`obs_core_video::video`_. + +It then puts that raw frame in a queue of MAX_CACHE_SIZE_ in the `video +output handler`_. A semaphore is posted, then the video-io thread will +process frames as it's able. If the video frame queue is full, it will +duplicate the last frame in the queue in an attempt to reduce video +encoding complexity (and thus CPU usage) `[2]`_. This is why you may +see frame skipping when the encoder can't keep up. Frames are sent to +any raw outputs or video encoders that are currently active `[3]`_. + +If it's sent to a video encoder object (`libobs/obs-encoder.c`_), it +encodes the frame and sends the encoded packet off to the outputs that +encoder is connected to (which can be multiple). If the output takes +both encoded video/audio, it puts the packets in an interleave queue to +ensure encoded packets are sent in monotonic timestamp order `[4]`_. + +The encoded packet or raw frame is then sent to the output. + + +General Audio Pipeline Overview +------------------------------- +The audio pipeline is run from a dedicated audio thread in the audio +handler (the `audio_thread`_ function in `libobs/media-io/audio-io.c`_); +assuming that AUDIO_OUTPUT_FRAMES_ is set to 1024, the audio thread +"ticks" (processes audio data) once every 1024 audio samples (around +every 21 millisecond intervals at 48khz), and calls the audio_callback_ +function in `libobs/obs-audio.c`_ where most of the audio processing is +accomplished. + +A source with audio will output its audio via the +obs_source_output_audio_ function, and that audio data will be appended +or inserted in to the circular buffer `obs_source::audio_input_buf`_. +If the sample rate or channel count does not match what the back-end is +set to, the audio is automatically remixed/resampled via swresample +`[5]`_. Before insertion, audio data is also run through any audio +filters attached to the source `[6]`_. + +Each audio tick, the audio thread takes a reference snapshot of the +audio source tree (stores references of all sources that output/process +audio) `[7]`_. On each audio leaf (audio source), it takes the closest +audio (relative to the current audio thread timestamp) stored in the +circular buffer `obs_source::audio_input_buf`_, and puts it in +`obs_source::audio_output_buf`_. + +Then, the audio samples stored in `obs_source::audio_output_buf`_ of the +leaves get sent through their parents in the source tree snapshot for +mixing or processing at each source node in the hierarchy `[8]`_. +Sources with multiple children such as scenes or transitions will +mix/process their children's audio themselves via the +`obs_source_info::audio_render`_ callback. This allows, for example, +transitions to fade in the audio of one source and fade in the audio of +a new source when they're transitioning between two sources. The mix or +processed audio data is then stored in `obs_source::audio_output_buf`_ +of that node similarly, and the process is repeated until the audio +reaches the root nodes of the tree. + +Finally, when the audio has reached the base of the snapshot tree, the +audio of all the sources in each output channel are mixed together for a +final mix `[9]`_. That final mix is then sent to any raw outputs or +audio encoders that are currently active `[10]`_. + +If it's sent to an audio encoder object (`libobs/obs-encoder.c`_), it +encodes the audio data and sends the encoded packet off to the outputs +that encoder is connected to (which can be multiple). If the output +takes both encoded video/audio, it puts the packets in an interleave +queue to ensure encoded packets are sent in monotonic timestamp order +`[4]`_. + +The encoded packet or raw audio data is then sent to the output. + +.. _obs_graphics_thread: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-video.c#L588-L651 +.. _libobs/obs-audio.c: https://github.com/jp9000/obs-studio/blob/master/libobs/obs-audio.c +.. _libobs/obs-video.c: https://github.com/jp9000/obs-studio/blob/master/libobs/obs-video.c +.. _video_thread: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/media-io/video-io.c#L169-L195 +.. _libobs/media-io/video-io.c: https://github.com/jp9000/obs-studio/blob/master/libobs/media-io/video-io.c +.. _video output handler: https://github.com/jp9000/obs-studio/blob/master/libobs/media-io/video-io.c +.. _audio_thread: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/media-io/audio-io.c#L241-L282 +.. _libobs/media-io/audio-io.c: https://github.com/jp9000/obs-studio/blob/master/libobs/media-io/audio-io.c +.. _MAX_CHANNELS: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-defs.h#L20-L21 +.. _[1]: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-video.c#L99-L129 +.. _obs_core_video::video: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-internal.h#L250 +.. _MAX_CACHE_SIZE: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/media-io/video-io.c#L34 +.. _[2]: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/media-io/video-io.c#L431-L434 +.. _[3]: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/media-io/video-io.c#L115-L167 +.. _libobs/obs-encoder.c: https://github.com/jp9000/obs-studio/blob/master/libobs/obs-encoder.c +.. _[4]: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-output.c#L1382-L1439 +.. _AUDIO_OUTPUT_FRAMES: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/media-io/audio-io.h#L30 +.. _audio_callback: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-audio.c#L367-L485 +.. _obs_source_output_audio: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-source.c#L2578-L2608 +.. _obs_source::audio_input_buf: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-source.c#L1280-L1283 +.. _[5]: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-source.c#L2561-L2563 +.. _[6]: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-source.c#L2591 +.. _[7]: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-audio.c#L393-L415 +.. _obs_source::audio_output_buf: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-internal.h#L580 +.. _[8]: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-audio.c#L417-L423 +.. _obs_source_info::audio_render: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-source.h#L410-L412 +.. _[9]: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-audio.c#L436-L453 +.. _[10]: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/media-io/audio-io.c#L144-L165 diff --git a/docs/sphinx/conf.py b/docs/sphinx/conf.py new file mode 100644 index 000000000..47ee2ec37 --- /dev/null +++ b/docs/sphinx/conf.py @@ -0,0 +1,171 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +# +# OBS Studio documentation build configuration file, created by +# sphinx-quickstart on Wed Oct 25 00:03:21 2017. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +primary_domain = 'c' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = 'OBS Studio' +copyright = '2017, Hugh Bailey' +author = 'Hugh Bailey' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '20.1.0' +# The full version, including alpha/beta/rc tags. +release = '20.1.0' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'bizstyle' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# This is required for the alabaster theme +# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars +html_sidebars = { + '**': [ + 'relations.html', # needs 'show_related': True theme option to display + 'searchbox.html', + ] +} + + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = 'OBSStudiodoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'OBSStudio.tex', 'OBS Studio Documentation', + 'Hugh Bailey', 'manual'), +] + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'obsstudio', 'OBS Studio Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'OBSStudio', 'OBS Studio Documentation', + author, 'OBSStudio', 'One line description of project.', + 'Miscellaneous'), +] + + + diff --git a/docs/sphinx/frontends.rst b/docs/sphinx/frontends.rst new file mode 100644 index 000000000..9ddd0599b --- /dev/null +++ b/docs/sphinx/frontends.rst @@ -0,0 +1,252 @@ +Frontends +========= + +Initialization and Shutdown +--------------------------- + +To initialize libobs, you must call :c:func:`obs_startup()`, +:c:func:`obs_reset_video()`, and then :c:func:`obs_reset_audio()`. +After that, modules typically should be loaded. + +You can load individual modules manually by calling +:c:func:`obs_open_module()`. After loading, the +:c:func:`obs_open_module()` function, you must then call +:c:func:`obs_init_module()` to initialize the module. + +You can load modules automatically via two functions: +:c:func:`obs_add_module_path()` and :c:func:`obs_load_all_modules()`. + +After all plugin modules have been loaded, call +:c:func:`obs_post_load_modules()`. + +Certain modules may optionally use a configuration storage directory, +which is set as a parameter to :c:func:`obs_startup()`. + +When it's time to shut down the frontend, make sure to release all +references to any objects, free any data, and then call +:c:func:`obs_shutdown()`. If for some reason any libobs objects have +not been released, they will be destroyed automatically and a warning +will be logged. + +To detect if any general memory allocations have not been freed, call +the :c:func:`bnum_allocs()` to get the number of allocations remaining. +If the number remaining is above 0, there are memory leaks. + +See :ref:`obs_init_shutdown_reference` for more information. + + +Reconfiguring Video +------------------- + +Any time after initialization, video settings can be reconfigured by +calling :c:func:`obs_reset_video()` as long as no outputs are active. +Audio was originally intended to have this capability as well, but +currently is not able to be reset once initialized; libobs must be fully +shutdown in order to reconfigure audio settings. + + +Displays +-------- + +Displays as the name implies are used for display/preview panes. To use +displays, you must have a native window handle or identifier to draw on. + +First you must call :c:func:`obs_display_create()` to initialize the +display, then you must assign a draw callback with +:c:func:`obs_display_add_draw_callback()`. If you need to remove a draw +callback, call :c:func:`obs_display_remove_draw_callback()` similarly. + +When drawing, to draw the main preview window (if any), call +:c:func:`obs_render_main_view()`. If you need to render a specific +source on a secondary display, you can increment its "showing" state +with :c:func:`obs_source_inc_showing()` while it's showing in the +secondary display, draw it with :c:func:`obs_source_video_render()` in +the draw callback, then when it's no longer showing in the secondary +display, call :c:func:`obs_source_dec_showing()`. + +If the display needs to be resized, call :c:func:`obs_display_resize()`. + +If the display needs a custom background color other than black, call +:c:func:`obs_display_set_background_color()`. + +If the display needs to be temporarily disabled, call +:c:func:`obs_display_set_enabled()` to disable, and +:c:func:`obs_display_enabled()` to get its enabled/disabled state. + +Then call :c:func:`obs_display_destroy()` to destroy the display when +it's no longer needed. + +*(Important note: do not use more than one display widget within the +hierarchy of the same base window; this will cause presentation stalls +on Macs.)* + +For an example of how displays are used with Qt, see +`UI/qt-display.hpp`_ and `UI/qt-display.cpp`_. + +See :ref:`display_reference` for more information. + + +Saving/Loading Objects and Object Management +-------------------------------------------- + +The frontend is generally expected to manage its own objects, however +for sources, there are some helper functions to allow easier +saving/loading all sources: :c:func:`obs_save_sources()` and +:c:func:`obs_load_sources()`. With those functions, all sources that +aren't private will automatically be saved and loaded. You can also +save/load individual sources manually by using +:c:func:`obs_save_source()` and :c:func:`obs_load_source()`. + +*(Author's note: I should not have written those helper functions; the +downside is I had to add "private" sources that aren't savable via the* +:c:func:`obs_source_create_private()` *function. Just one of the many +minor design flaws that can occur during long-term development.)* + +For outputs, encoders, and services, there are no helper functions, so +usually you'd get their settings individually and save them as json. +(See :c:func:`obs_output_get_settings()`). You don't have to save each +object to different files individually; you'd save multiple objects +together in a bigger :c:type:`obs_data_t` object, then save that via +:c:func:`obs_data_save_json_safe()`, then load everything again via +:c:func:`obs_data_create_from_json_file_safe()`. + + +Signals +------- + +The core, as well as scenes and sources, have a set of standard signals +that are used to determine when something happens or changes. + +Typically the most important signals are the +:ref:`output_signal_handler_reference`: the **start**, **stop**, +**starting**, **stopping**, **reconnect**, **reconnect_success** +signals in particular. + +Most other signals for scenes/sources are optional if you are the only +thing controlling their state. However, it's generally recommended to +watch most signals when possible for consistency. See +:ref:`source_signal_handler_reference` and :ref:`scene_signal_reference` +for more information. + +For example, let's say you wanted to connect a callback to the **stop** +signal of an output. The **stop** signal has two parameters: *output* +and *code*. A callback for this signal would typically look something +like this: + +.. code:: cpp + + static void output_stopped(void *my_data, calldata_t *cd) + { + obs_output_t *output = calldata_ptr(cd, "output"); + int code = calldata_int(cd, "code"); + + [...] + } + +*(Note that callbacks are not thread-safe.)* + +Then to connect it to the **stop** signal, you use the +:c:func:`signal_handler_connect()` with the callback. In this case for +example: + +.. code:: cpp + + signal_handler_t *handler = obs_output_get_signal_handler(output); + signal_handler_connect(handler, "stop", output_stopped); + + +.. _displaying_sources: + +Displaying Sources +------------------ + +Sources are displayed on stream/recording via :ref:`output_channels` +with the :c:func:`obs_set_output_source()` function. There are 64 +channels that you can assign sources to, which will draw on top of each +other in ascending index order. Typically, a normal source shouldn't be +directly assigned with this function; you would use a scene or a +transition containing scenes. + +To draw one or more sources together with a specific transform applied +to them, scenes are used. To create a scene, you call +:c:func:`obs_scene_create()`. Child sources are referenced using scene +items, and then specific transforms are applied to those scene items. +Scene items are not sources but containers for sources; the same source +can be referenced by multiple scene items within the same scene, or can +be referenced in multiple scenes. To create a scene item that +references a source, you call :c:func:`obs_scene_add()`, which returns a +new reference to a scene item. + +To change the transform of a scene item, you typically would call a +function like :c:func:`obs_sceneitem_set_pos()` to change its position, +:c:func:`obs_sceneitem_set_rot()` to change its rotation, or +:c:func:`obs_sceneitem_set_scale()` to change its scaling. Scene items +can also force scaling in to a custom size constraint referred to as a +"bounding box"; a bounding box will force the source to be drawn at a +specific size and with specific scaling constraint within that size. To +use a bounding box, you call the +:c:func:`obs_sceneitem_set_bounds_type()`, +:c:func:`obs_sceneitem_set_bounds()`, and +:c:func:`obs_sceneitem_set_bounds_alignment()`. Though the easiest way +to handle everything related to transforms is to use the +:c:func:`obs_sceneitem_set_info()` and +:c:func:`obs_sceneitem_get_info()` functions. See +:ref:`scene_item_reference` for all the functions related to scene +items. + +Usually, a smooth transition between multiple scenes is required. To do +this, transitions are used. To create a transition, you use +:c:func:`obs_source_create()` or :c:func:`obs_source_create_private()` +like any other source. Then, to activate a transition, you call +:c:func:`obs_transition_start()`. When the transition is not active and +is only displaying one source, it performs a pass-through to the current +displaying source. See :ref:`transitions` for more functions related to +using transitions. + +The recommended way to set up your structure is to have a transition as +the source that is used as the main output source, then your scene as a +child of the transition, then your sources as children in the scene. +When you need to switch to a new scene, simply call +:c:func:`obs_transition_start()`. + + +Outputs, Encoders, and Services +------------------------------- + +Outputs, encoders, and services are all used together, and managed a bit +differently than sources. There currently is no global function to +save/load them, that must be accomplished manually for now via their +settings if needed. + +Encoders are used with outputs that expect encoded data (which is almost +all typical outputs), such as standard file recording or streaming. + +Services are used with outputs to a stream; the `RTMP output`_ is the +quintessential example of this. + +Here's an example of how an output would be used with encoders and +services: + +.. code:: cpp + + obs_encoder_set_video(my_h264_encoder, obs_get_video()); + obs_encoder_set_audio(my_aac_encoder, obs_get_audio()); + obs_output_set_video_encoder(my_output, my_h264_encoder); + obs_output_set_audio_encoder(my_output, my_aac_encoder); + obs_output_set_service(my_output, my_service); /* if a stream */ + obs_output_start(my_output); + +Once the output has started successfully, it automatically starts +capturing the video and/or audio from the current video/audio output +(i.e. any sources that are assigned to the :ref:`output_channels`). + +If the output fails to start up, it will send the **stop** signal with +an error code in the *code* parameter, possibly accompanied by a +translated error message stored that can be obtained via the +:c:func:`obs_output_get_last_error()` function. + +.. -------------------------------------------------------------------- + +.. _RTMP Output: https://github.com/jp9000/obs-studio/blob/master/plugins/obs-outputs/rtmp-stream.c +.. _UI/qt-display.hpp: https://github.com/jp9000/obs-studio/blob/master/UI/qt-display.hpp +.. _UI/qt-display.cpp: https://github.com/jp9000/obs-studio/blob/master/UI/qt-display.cpp diff --git a/docs/sphinx/graphics.rst b/docs/sphinx/graphics.rst new file mode 100644 index 000000000..c2c91849a --- /dev/null +++ b/docs/sphinx/graphics.rst @@ -0,0 +1,364 @@ +Rendering Graphics +================== + +Libobs has a custom-made programmable graphics subsystem that wraps both +Direct3D 11 and OpenGL. The reason why it was designed with a custom +graphics subsystem was to accommodate custom capture features only +available on specific operating systems. + +*(Author's note: In retrospect, I probably should have used something +like ANGLE, but I would have to modify it to accommodate my specific +use-cases.)* + +Most rendering is dependent upon effects. Effects are used by all video +objects in libobs; they're used to easily bundle related vertex/pixel +shaders in to one file. + +An effect file has a nearly identical syntax to Direct3D 11 HLSL effect +files. The only differences are as follows: + +- Sampler states are named "sampler_state" +- Position semantic is called "POSITION" rather than "SV_Position" +- Target semantic is called "TARGET" rather than "SV_Target" + +*(Author's note: I'm probably missing a few exceptions here, if I am +please let me know)* + + +The Graphics Context +-------------------- + +Using graphics functions isn't possible unless the current thread has +entered a graphics context, and the graphics context can only be used by +one thread at a time. To enter the graphics context, use +:c:func:`obs_enter_graphics()`, and to leave the graphics context, use +:c:func:`obs_leave_graphics()`. + +Certain callback will automatically be within the graphics context: +:c:member:`obs_source_info.video_render`, and the draw callback +parameter of :c:func:`obs_display_add_draw_callback()`, and +:c:func:`obs_add_main_render_callback()`. + + +Creating Effects +---------------- + +Effect Parameters +^^^^^^^^^^^^^^^^^ + +To create an effect, it's recommended to start with the uniforms +(parameters) of the effect. + +There are a number of different types of uniforms: + ++------------------+---------------+------------------+------------+------------+ +| Floating points: | **float** | **float2** | **float3** | **float4** | ++------------------+---------------+------------------+------------+------------+ +| Matrices: | **float3x3** | **float4x4** | | | ++------------------+---------------+------------------+------------+------------+ +| Integers: | **int** | **int2** | **int3** | **int4** | ++------------------+---------------+------------------+------------+------------+ +| Booleans: | **bool** | | | | ++------------------+---------------+------------------+------------+------------+ +| Textures: | **texture2d** | **texture_cube** | | | ++------------------+---------------+------------------+------------+------------+ + +To get the effect uniform parameters, you use +:c:func:`gs_effect_get_param_by_name()` or +:c:func:`gs_effect_get_param_by_idx()`. + +Then the uniforms are set through the following functions: + +- :c:func:`gs_effect_set_bool()` +- :c:func:`gs_effect_set_float()` +- :c:func:`gs_effect_set_int()` +- :c:func:`gs_effect_set_matrix4()` +- :c:func:`gs_effect_set_vec2()` +- :c:func:`gs_effect_set_vec3()` +- :c:func:`gs_effect_set_vec4()` +- :c:func:`gs_effect_set_texture()` + +There are two "universal" effect parameters that may be expected of +effects: **ViewProj**, and **image**. The **ViewProj** parameter +(which is a float4x4) is used for the primary view/projection matrix +combination. The **image** parameter (which is a texture2d) is a +commonly used parameter for the main texture; this parameter will be +used with the functions :c:func:`obs_source_draw()`, +:c:func:`gs_draw_sprite()`, and +:c:func:`obs_source_process_filter_end()`. + +Here is an example of effect parameters: + +.. code:: cpp + + uniform float4x4 ViewProj; + uniform texture2d image; + + uniform float4 my_color_param; + uniform float my_float_param; + +Effect parameters can also have default values. Default parameters of +elements that have multiple elements should be treated as an array. + +Here are some examples of default parameters: + +.. code:: cpp + + uniform float4x4 my_matrix = {1.0, 0.0, 0.0, 0.0, + 0.0, 1.0, 0.0, 0.0, + 0.0, 0.0, 1.0, 0.0, + 0.0, 0.0, 0.0, 1.0}; + + uniform float4 my_float4 = {1.0, 0.5, 0.25, 0.0}; + uniform float my_float = 4.0; + uniform int my_int = 5; + +Effect Sampler States +^^^^^^^^^^^^^^^^^^^^^ + +Then, if textures are used, sampler states should be defined. Sampler +states have certain sub-parameters: + +- **Filter** - The type of filtering to use. Can be one of the + following values: + + - **Anisotropy** + - **Point** + - **Linear** + - **MIN_MAG_POINT_MIP_LINEAR** + - **MIN_POINT_MAG_LINEAR_MIP_POINT** + - **MIN_POINT_MAG_MIP_LINEAR** + - **MIN_LINEAR_MAG_MIP_POINT** + - **MIN_LINEAR_MAG_POINT_MIP_LINEAR** + - **MIN_MAG_LINEAR_MIP_POINT** + +- **AddressU**, **AddressV** - Specifies how to handle the sampling + when the coordinate goes beyond 0.0..1.0. Can be one of the following + values: + + - **Wrap** or **Repeat** + - **Clamp** or **None** + - **Mirror** + - **Border** (uses *BorderColor* to fill the color) + - **MirrorOnce** + +- **BorderColor** - Specifies the border color if using the "Border" + address mode. This value should be a hexadecimal value representing + the color, in the format of: AARRGGBB. For example, 7FFF0000 would + have its alpha value at 127, its red value at 255, and blue and green + at 0. If *Border* is not used as an addressing type, this value is + ignored. + +Here is an example of writing a sampler state in an effect file: + +.. code:: cpp + + sampler_state defaultSampler { + Filter = Linear; + AddressU = Border; + AddressV = Border; + BorderColor = 7FFF0000; + }; + +This sampler state would use linear filtering, would use border +addressing for texture coordinate values beyond 0.0..1.0, and the border +color would be the color specified above. + +When a sampler state is used, it's used identically to the HLSL form: + +.. code:: cpp + + [...] + + uniform texture2d image; + + sampler_state defaultSampler { + Filter = Linear; + AddressU = Clamp; + AddressV = Clamp; + }; + + [...] + + float4 MyPixelShaderFunc(VertInOut vert_in) : TARGET + { + return image.Sample(def_sampler, vert_in.uv); + } + +Effect Vertex/Pixel Semantics +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Then structures should be defined for inputs and outputs vertex +semantics. + +Vertex components can have the following semantics: + +- **COLOR** - Color value (*float4*). +- **POSITION** - Position value (*float4*). +- **NORMAL** - Normal value (*float4*). +- **TANGENT** - Tangent value (*float4*). +- **TEXCOORD[0..7]** - Texture cooordinate value (*float2*, *float3*, or + *float4*). + +Here is an example of a vertex semantic structure: + +.. code:: cpp + + struct VertexIn { + float4 my_position : POSITION; + float2 my_texcoord : TEXCOORD0; + }; + +These semantic structures are then passed in as a parameter to the +primary shader entry point, and used as a return value for the vertex +shader. Note that the vertex shader is allowed to return different +semantics than it takes in; but the return type of the vertex shader and +the parameter of the pixel shader must match. + +The semantic structure used for the parameter to the vertex shader +function will require that the vertex buffer have those values, so if +you have POSITION and TEXCOORD0, the vertex buffer will have to have at +least a position buffer and a texture coordinate buffer in it. + +For pixel shaders, they need to return with a TARGET semantic (which is +a float4 RGBA value). Here is an example of how it's usually used with +a pixel shader function: + +.. code:: cpp + + float4 MyPixelShaderFunc(VertInOut vert_in) : TARGET + { + return image.Sample(def_sampler, vert_in.uv); + } + + +Effect Techniques +^^^^^^^^^^^^^^^^^ + +Techniques are used to define the primary vertex/pixel shader entry +functions per pass. One technique can have multiple passes or custom +pass setup. + +*(Author's note: These days, multiple passes aren't really needed; GPUs +are powerful enough to where you can perform all actions in the same +shader. Named passes can be useful for custom draw setups, but even +then you can just make it a separate technique. For that reason, it's +best to just ignore the extra pass functionality.)* + +If you're making an effect filter for video sources, typically you'd +name the pass **Draw**, and then +:c:func:`obs_source_process_filter_end()` will automatically call that +specific effect name. However, you can also use +:c:func:`obs_source_process_filter_tech_end()` to make the filter use a +specific technique by its name. + +The first parameter of the vertex/pixel shader functions in passes +should always be the name of its vertex semantic structure parameter. + +For techniques, it's better to show some examples of how techniques +would be used: + +.. code:: cpp + + uniform float4x4 ViewProj; + uniform texture2d image; + + struct VertInOut { + float4 my_position : POSITION; + float2 my_texcoord : TEXCOORD0; + }; + + VertInOut MyVertexShaderFunc(VertInOut vert_in) + { + VertInOut vert_out; + vert_out.pos = mul(float4(vert_in.pos.xyz, 1.0), ViewProj); + vert_out.uv = vert_in.uv; + return vert_out; + } + + float4 MyPixelShaderFunc(VertInOut vert_in) : TARGET + { + return image.Sample(def_sampler, vert_in.uv); + } + + technique Draw + { + pass + { + vertex_shader = MyVertexShaderFunc(vert_in); + pixel_shader = MyPixelShaderFunc(vert_in); + } + }; + +Using Effects +------------- + +The recommended way to use effects is like so: + +.. code:: cpp + + for (gs_effect_loop(effect, "technique")) { + [draw calls go here] + } + +This will automatically handle loading/unloading of the effect and its +shaders for a given technique name. + + +Rendering Video Sources +----------------------- + +A synchronous video source renders in its +:c:member:`obs_source_info.video_render` callback. + +Sources can render with custom drawing (via the OBS_SOURCE_CUSTOM_DRAW +output capability flag), or without. When sources render without custom +rendering, it's recommended to render a single texture with +:c:func:`obs_source_draw()`. Otherwise the source is expected to +perform rendering on its own and manage its own effects. + +Libobs comes with a set of default/standard effects that can be accessed +via the :c:func:`obs_get_base_effect()` function. You can use these +effects to render, or you can create custom effects with +:c:func:`gs_effect_create_from_file()` and render with a custom effect. + + +Rendering Video Effect Filters +------------------------------ + +For most video effect filters, it comprises of adding a layer of +processing shaders to an existing image in its +:c:member:`obs_source_info.video_render` callback. When this is the +case, it's expected that the filter has its own effect created, and to +draw the effect, one would simply use the +:c:func:`obs_source_process_filter_begin()` function, set the parameters +on your custom effect, then call either +:c:func:`obs_source_process_filter_end()` or +:c:func:`obs_source_process_filter_tech_end()` to finish rendering the +filter. + +Here's an example of rendering a filter from the color key filter: + +.. code:: cpp + + static void color_key_render(void *data, gs_effect_t *effect) + { + struct color_key_filter_data *filter = data; + + if (!obs_source_process_filter_begin(filter->context, GS_RGBA, + OBS_ALLOW_DIRECT_RENDERING)) + return; + + gs_effect_set_vec4(filter->color_param, &filter->color); + gs_effect_set_float(filter->contrast_param, filter->contrast); + gs_effect_set_float(filter->brightness_param, filter->brightness); + gs_effect_set_float(filter->gamma_param, filter->gamma); + gs_effect_set_vec4(filter->key_color_param, &filter->key_color); + gs_effect_set_float(filter->similarity_param, filter->similarity); + gs_effect_set_float(filter->smoothness_param, filter->smoothness); + + obs_source_process_filter_end(filter->context, filter->effect, 0, 0); + + UNUSED_PARAMETER(effect); + } + diff --git a/docs/sphinx/index.rst b/docs/sphinx/index.rst new file mode 100644 index 000000000..24c885eef --- /dev/null +++ b/docs/sphinx/index.rst @@ -0,0 +1,24 @@ +.. OBS Studio documentation master file, created by + sphinx-quickstart on Wed Oct 25 00:03:21 2017. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +.. _contents: + +Welcome to OBS Studio's documentation! +====================================== + +.. toctree:: + :maxdepth: 3 + + backend-design + plugins + frontends + graphics + reference-core + reference-modules + reference-core-objects + reference-libobs-util + reference-libobs-callback + reference-libobs-graphics + reference-libobs-media-io diff --git a/docs/sphinx/make.bat b/docs/sphinx/make.bat new file mode 100644 index 000000000..9635336df --- /dev/null +++ b/docs/sphinx/make.bat @@ -0,0 +1,36 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build +set SPHINXPROJ=OBSStudio + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% + +:end +popd diff --git a/docs/sphinx/plugins.rst b/docs/sphinx/plugins.rst new file mode 100644 index 000000000..2a6dd718b --- /dev/null +++ b/docs/sphinx/plugins.rst @@ -0,0 +1,569 @@ +Plugins +======= +Almost all custom functionality is added through plugin modules, which +are typically dynamic libraries or scripts. The ability to capture +and/or output audio/video, make a recording, output to an RTMP stream, +encode in x264 are all examples of things that are accomplished via +plugin modules. + +Plugins can implement sources, outputs, encoders, and services. + + +Plugin Module Headers +--------------------- +These are some notable headers commonly used by plugins: + +- `libobs/obs-module.h`_ -- The primary header used for creating plugin + modules. This file automatically includes the following files: + + - `libobs/obs.h`_ -- The main libobs header. This file automatically + includes the following files: + + - `libobs/obs-source.h`_ -- Used for implementing sources in plugin + modules + + - `libobs/obs-output.h`_ -- Used for implementing outputs in plugin + modules + + - `libobs/obs-encoder.h`_ -- Used for implementing encoders in + plugin modules + + - `libobs/obs-service.h`_ -- Used for implementing services in + plugin modules + + - `libobs/obs-data.h`_ -- Used for managing settings for libobs + objects + + - `libobs/obs-properties.h`_ -- Used for generating properties for + libobs objects + + - `libobs/graphics/graphics.h`_ -- Used for graphics rendering + + +Common Directory Structure and CMakeLists.txt +--------------------------------------------- +The common way source files are organized is to have one file for plugin +initialization, and then specific files for each individual object +you're implementing. For example, if you were to create a plugin called +'my-plugin', you'd have something like my-plugin.c where plugin +initialization is done, my-source.c for the definition of a custom +source, my-output.c for the definition of a custom output, etc. (This +is not a rule of course) + +This is an example of a common directory structure for a native plugin +module:: + + my-plugin/data/locale/en-US.ini + my-plugin/CMakeLists.txt + my-plugin/my-plugin.c + my-plugin/my-source.c + my-plugin/my-output.c + my-plugin/my-encoder.c + my-plugin/my-service.c + +This would be an example of a common CMakeLists.txt file associated with +these files:: + + # my-plugin/CMakeLists.txt + + project(my-plugin) + + set(my-plugin_SOURCES + my-plugin.c + my-source.c + my-output.c + my-encoder.c + my-service.c) + + add_library(my-plugin MODULE + ${my-plugin_SOURCES}) + target_link_libraries(my-plugin + libobs) + + install_obs_plugin_with_data(my-plugin data) + + +Native Plugin Initialization +---------------------------- +To create a native plugin module, you will need to include the +`libobs/obs-module.h`_ header, use :c:func:`OBS_DECLARE_MODULE()` macro, +then create a definition of the function :c:func:`obs_module_load()`. +In your :c:func:`obs_module_load()` function, you then register any of +your custom sources, outputs, encoders, or services. See the +:doc:`reference-modules` for more information. + +The following is an example of my-plugin.c, which would register one +object of each type: + +.. code:: cpp + + /* my-plugin.c */ + #include + + /* Defines common functions (required) */ + OBS_DECLARE_MODULE() + + /* Implements common ini-based locale (optional) */ + OBS_MODULE_USE_DEFAULT_LOCALE("my-plugin", "en-US") + + extern struct obs_source_info my_source; /* Defined in my-source.c */ + extern struct obs_output_info my_output; /* Defined in my-output.c */ + extern struct obs_encoder_info my_encoder; /* Defined in my-encoder.c */ + extern struct obs_service_info my_service; /* Defined in my-service.c */ + + bool obs_module_load(void) + { + obs_register_source(&my_source); + obs_register_output(&my_output); + obs_register_encoder(&my_encoder); + obs_register_service(&my_service); + return true; + } + + +.. _plugins_sources: + +Sources +------- +Sources are used to render video and/or audio on stream. Things such as +capturing displays/games/audio, playing a video, showing an image, or +playing audio. Sources can also be used to implement audio and video +filters as well as transitions. The `libobs/obs-source.h`_ file is the +dedicated header for implementing sources. See the +:doc:`reference-sources` for more information. + +For example, to implement a source object, you need to define an +:c:type:`obs_source_info` structure and fill it out with information and +callbacks related to your source: + +.. code:: cpp + + /* my-source.c */ + + [...] + + struct obs_source_info my_source { + .id = "my_source", + .type = OBS_SOURCE_TYPE_INPUT, + .output_flags = OBS_SOURCE_VIDEO, + .get_name = my_source_name, + .create = my_source_create, + .destroy = my_source_destroy, + .update = my_source_update, + .video_render = my_source_render, + .get_width = my_source_width, + .get_height = my_source_height + }; + +Then, in my-plugin.c, you would call :c:func:`obs_register_source()` in +:c:func:`obs_module_load()` to register the source with libobs. + +.. code:: cpp + + /* my-plugin.c */ + + [...] + + extern struct obs_source_info my_source; /* Defined in my-source.c */ + + bool obs_module_load(void) + { + obs_register_source(&my_source); + + [...] + + return true; + } + +Some simple examples of sources: + +- Synchronous video source: The `image source `_ +- Asynchronous video source: The `random texture test source `_ +- Audio source: The `sine wave test source `_ +- Video filter: The `test video filter `_ +- Audio filter: The `gain audio filter `_ + + +.. _plugins_outputs: + +Outputs +------- +Outputs allow the ability to output the currently rendering audio/video. +Streaming and recording are two common examples of outputs, but not the +only types of outputs. Outputs can receive the raw data or receive +encoded data. The `libobs/obs-output.h`_ file is the dedicated header +for implementing outputs. See the :doc:`reference-outputs` for more +information. + +For example, to implement an output object, you need to define an +:c:type:`obs_output_info` structure and fill it out with information and +callbacks related to your output: + +.. code:: cpp + + /* my-output.c */ + + [...] + + struct obs_output_info my_output { + .id = "my_output", + .flags = OBS_OUTPUT_AV | OBS_OUTPUT_ENCODED, + .get_name = my_output_name, + .create = my_output_create, + .destroy = my_output_destroy, + .start = my_output_start, + .stop = my_output_stop, + .encoded_packet = my_output_data, + .get_total_bytes = my_output_total_bytes, + .encoded_video_codecs = "h264", + .encoded_audio_codecs = "aac" + }; + +Then, in my-plugin.c, you would call :c:func:`obs_register_output()` in +:c:func:`obs_module_load()` to register the output with libobs. + +.. code:: cpp + + /* my-plugin.c */ + + [...] + + extern struct obs_output_info my_output; /* Defined in my-output.c */ + + bool obs_module_load(void) + { + obs_register_output(&my_output); + + [...] + + return true; + } + +Some examples of outputs: + +- Encoded video/audio outputs: + + - The `FLV output `_ + - The `FFmpeg muxer output `_ + - The `RTMP stream output `_ + +- Raw video/audio outputs: + + - The `FFmpeg output `_ + + +.. _plugins_encoders: + +Encoders +-------- +Encoders are OBS-specific implementations of video/audio encoders, which +are used with outputs that use encoders. x264, NVENC, Quicksync are +examples of encoder implementations. The `libobs/obs-encoder.h`_ file +is the dedicated header for implementing encoders. See the +:doc:`reference-encoders` for more information. + +For example, to implement an encoder object, you need to define an +:c:type:`obs_encoder_info` structure and fill it out with information +and callbacks related to your encoder: + +.. code:: cpp + + /* my-encoder.c */ + + [...] + + struct obs_encoder_info my_encoder_encoder = { + .id = "my_encoder", + .type = OBS_ENCODER_VIDEO, + .codec = "h264", + .get_name = my_encoder_name, + .create = my_encoder_create, + .destroy = my_encoder_destroy, + .encode = my_encoder_encode, + .update = my_encoder_update, + .get_extra_data = my_encoder_extra_data, + .get_sei_data = my_encoder_sei, + .get_video_info = my_encoder_video_info + }; + +Then, in my-plugin.c, you would call :c:func:`obs_register_encoder()` +in :c:func:`obs_module_load()` to register the encoder with libobs. + +.. code:: cpp + + /* my-plugin.c */ + + [...] + + extern struct obs_encoder_info my_encoder; /* Defined in my-encoder.c */ + + bool obs_module_load(void) + { + obs_register_encoder(&my_encoder); + + [...] + + return true; + } + +**IMPORTANT NOTE:** Encoder settings currently have a few expected +common setting values that should have a specific naming convention: + + - **"bitrate"** - This value should be used for both video and audio + encoders: bitrate, in kilobits. + - **"rate_control"** - This is a setting used for video encoders. + It's generally expected to have at least a "CBR" rate control. + Other common rate controls are "VBR", "CQP". + - **"keyint_sec"** - For video encoders, sets the keyframe interval + value, in seconds, or closest possible approximation. *(Author's + note: This should have have been "keyint", in frames.)* + +Examples of encoders: + +- Video encoders: + + - The `x264 encoder `_ + - The `FFmpeg NVENC encoder `_ + - The `Quicksync encoder `_ + +- Audio encoders: + + - The `FFmpeg AAC/Opus encoder `_ + + +.. _plugins_services: + +Services +-------- +Services are custom implementations of streaming services, which are +used with outputs that stream. For example, you could have a custom +implementation for streaming to Twitch, and another for YouTube to allow +the ability to log in and use their APIs to do things such as get the +RTMP servers or control the channel. The `libobs/obs-service.h`_ file +is the dedicated header for implementing services. See the +:doc:`reference-services` for more information. + +*(Author's note: the service API is incomplete as of this writing)* + +For example, to implement a service object, you need to define an +:c:type:`obs_service_info` structure and fill it out with information +and callbacks related to your service: + +.. code:: cpp + + /* my-service.c */ + + [...] + + struct obs_service_info my_service_service = { + .id = "my_service", + .get_name = my_service_name, + .create = my_service_create, + .destroy = my_service_destroy, + .encode = my_service_encode, + .update = my_service_update, + .get_url = my_service_url, + .get_key = my_service_key + }; + +Then, in my-plugin.c, you would call :c:func:`obs_register_service()` in +:c:func:`obs_module_load()` to register the service with libobs. + +.. code:: cpp + + /* my-plugin.c */ + + [...] + + extern struct obs_service_info my_service; /* Defined in my-service.c */ + + bool obs_module_load(void) + { + obs_register_service(&my_service); + + [...] + + return true; + } + +The only two existing services objects are the "common RTMP services" +and "custom RTMP service" objects in `plugins/rtmp-services +`_ + + +Settings +-------- +Settings (see `libobs/obs-data.h`_) are used to get or set settings data +typically associated with libobs objects, and can then be saved and +loaded via Json text. See the :doc:`reference-settings` for more +information. + +The *obs_data_t* is the equivalent of a Json object, where it's a string +table of sub-objects, and the *obs_data_array_t* is similarly used to +store an array of *obs_data_t* objects, similar to Json arrays (though +not quite identical). + +To create an *obs_data_t* or *obs_data_array_t* object, you'd call the +:c:func:`obs_data_create()` or :c:func:`obs_data_array_create()` +functions. *obs_data_t* and *obs_data_array_t* objects are reference +counted, so when you are finished with the object, call +:c:func:`obs_data_release()` or :c:func:`obs_data_array_release()` to +release those references. Any time an *obs_data_t* or +*obs_data_array_t* object is returned by a function, their references +are incremented, so you must release those references each time. + +To set values for an *obs_data_t* object, you'd use one of the following +functions: + +.. code:: cpp + + /* Set functions */ + EXPORT void obs_data_set_string(obs_data_t *data, const char *name, const char *val); + EXPORT void obs_data_set_int(obs_data_t *data, const char *name, long long val); + EXPORT void obs_data_set_double(obs_data_t *data, const char *name, double val); + EXPORT void obs_data_set_bool(obs_data_t *data, const char *name, bool val); + EXPORT void obs_data_set_obj(obs_data_t *data, const char *name, obs_data_t *obj); + EXPORT void obs_data_set_array(obs_data_t *data, const char *name, obs_data_array_t *array); + +Similarly, to get a value from an *obs_data_t* object, you'd use one of +the following functions: + +.. code:: cpp + + /* Get functions */ + EXPORT const char *obs_data_get_string(obs_data_t *data, const char *name); + EXPORT long long obs_data_get_int(obs_data_t *data, const char *name); + EXPORT double obs_data_get_double(obs_data_t *data, const char *name); + EXPORT bool obs_data_get_bool(obs_data_t *data, const char *name); + EXPORT obs_data_t *obs_data_get_obj(obs_data_t *data, const char *name); + EXPORT obs_data_array_t *obs_data_get_array(obs_data_t *data, const char *name); + +Unlike typical Json data objects, the *obs_data_t* object can also set +default values. This allows the ability to control what is returned if +there is no value assigned to a specific string in an *obs_data_t* +object when that data is loaded from a Json string or Json file. Each +libobs object also has a *get_defaults* callback which allows setting +the default settings for the object on creation. + +These functions control the default values are as follows: + +.. code:: cpp + + /* Default value functions. */ + EXPORT void obs_data_set_default_string(obs_data_t *data, const char *name, const char *val); + EXPORT void obs_data_set_default_int(obs_data_t *data, const char *name, long long val); + EXPORT void obs_data_set_default_double(obs_data_t *data, const char *name, double val); + EXPORT void obs_data_set_default_bool(obs_data_t *data, const char *name, bool val); + EXPORT void obs_data_set_default_obj(obs_data_t *data, const char *name, obs_data_t *obj); + + +Properties +---------- +Properties (see `libobs/obs-properties.h`_) are used to automatically +generate user interface to modify settings for a libobs object (if +desired). Each libobs object has a *get_properties* callback which is +used to generate properties. The properties API defines specific +properties that are linked to the object's settings, and the front-end +uses those properties to generate widgets in order to allow the user to +modify the settings. For example, if you had a boolean setting, you +would use :c:func:`obs_properties_add_bool()` to allow the user to be +able to change that setting. See the :doc:`reference-properties` for +more information. + +An example of this: + +.. code:: cpp + + static obs_properties_t *my_source_properties(void *data) + { + obs_properties_t *ppts = obs_properties_create(); + obs_properties_add_bool(ppts, "my_bool", + obs_module_text("MyBool")); + UNUSED_PARAMETER(data); + return ppts; + } + + [...] + + struct obs_source_info my_source { + .get_properties = my_source_properties, + [...] + }; + +The *data* parameter is the object's data if the object is present. +Typically this is unused and probably shouldn't be used if possible. It +can be null if the properties are retrieved without an object associated +with it. + +Properties can also be modified depending on what settings are shown. +For example, you can mark certain properties as disabled or invisible +depending on what a particular setting is set to using the +:c:func:`obs_property_set_modified_callback()` function. + +For example, if you wanted boolean property A to hide text property B: + +.. code:: cpp + + static bool setting_a_modified(obs_properties_t *ppts, + obs_property_t *p, obs_data_t *settings) + { + bool enabled = obs_data_get_bool(settings, "setting_a"); + p = obs_properties_get(ppts, "setting_b"); + obs_property_set_enabled(p, enabled); + + /* return true to update property widgets, false + otherwise */ + return true; + } + + [...] + + static obs_properties_t *my_source_properties(void *data) + { + obs_properties_t *ppts = obs_properties_create(); + obs_property_t *p; + + p = obs_properties_add_bool(ppts, "setting_a", + obs_module_text("SettingA")); + obs_property_set_modified_callback(p, setting_a_modified); + + obs_properties_add_text(ppts, "setting_b", + obs_module_text("SettingB"), + OBS_TEXT_DEFAULT); + return ppts; + } + + +Localization +------------ +Typically, most plugins bundled with OBS Studio will use a simple +ini-file localization method, where each file is a different language. +When using this method, the :c:func:`OBS_MODULE_USE_DEFAULT_LOCALE()` +macro is used which will automatically load/destroy the locale data with +no extra effort on part of the plugin. Then the +:c:func:`obs_module_text()` function (which is automatically declared as +an extern by `libobs/obs-module.h`_) is used when text lookup is needed. + +There are two exports the module used to load/destroy locale: the +:c:func:`obs_module_set_locale()` export, and the +:c:func:`obs_module_free_locale()` export. The +:c:func:`obs_module_set_locale()` export is called by libobs to set the +current language, and then the :c:func:`obs_module_free_locale()` export +is called by libobs on destruction of the module. If you wish to +implement a custom locale implementation for your plugin, you'd want to +define these exports along with the :c:func:`obs_module_text()` extern +yourself instead of relying on the +:c:func:`OBS_MODULE_USE_DEFAULT_LOCALE()` macro. + + +.. --------------------------------------------------------------------------- + +.. _libobs/obs-module.h: https://github.com/jp9000/obs-studio/blob/master/libobs/obs-module.h +.. _libobs/obs.h: https://github.com/jp9000/obs-studio/blob/master/libobs/obs.h +.. _libobs/obs-source.h: https://github.com/jp9000/obs-studio/blob/master/libobs/obs-source.h +.. _libobs/obs-output.h: https://github.com/jp9000/obs-studio/blob/master/libobs/obs-output.h +.. _libobs/obs-encoder.h: https://github.com/jp9000/obs-studio/blob/master/libobs/obs-encoder.h +.. _libobs/obs-service.h: https://github.com/jp9000/obs-studio/blob/master/libobs/obs-service.h +.. _libobs/obs-data.h: https://github.com/jp9000/obs-studio/blob/master/libobs/obs-data.h +.. _libobs/obs-properties.h: https://github.com/jp9000/obs-studio/blob/master/libobs/obs-properties.h +.. _libobs/graphics/graphics.h: https://github.com/jp9000/obs-studio/blob/master/libobs/graphics/graphics.h diff --git a/docs/sphinx/reference-core-objects.rst b/docs/sphinx/reference-core-objects.rst new file mode 100644 index 000000000..8949b586c --- /dev/null +++ b/docs/sphinx/reference-core-objects.rst @@ -0,0 +1,13 @@ +Core API Object Reference +========================= + +.. toctree:: + :maxdepth: 3 + + reference-sources + reference-scenes + reference-outputs + reference-encoders + reference-services + reference-settings + reference-properties diff --git a/docs/sphinx/reference-core.rst b/docs/sphinx/reference-core.rst new file mode 100644 index 000000000..9fcf3543b --- /dev/null +++ b/docs/sphinx/reference-core.rst @@ -0,0 +1,643 @@ +OBS Core API Reference +====================== + +.. code:: cpp + + #include + + +.. _obs_init_shutdown_reference: + +Initialization, Shutdown, and Information +----------------------------------------- + +.. function:: bool obs_startup(const char *locale, const char *module_config_path, profiler_name_store_t *store) + + Initializes the OBS core context. + + :param locale: The locale to use for modules + (E.G. "en-US") + :param module_config_path: Path to module config storage directory + (or *NULL* if none) + :param store: The profiler name store for OBS to use or NULL + :return: *false* if already initialized or failed + to initialize + +--------------------- + +.. function:: void obs_shutdown(void) + + Releases all data associated with OBS and terminates the OBS context. + +--------------------- + +.. function:: bool obs_initialized(void) + + :return: true if the main OBS context has been initialized + +--------------------- + +.. function:: uint32_t obs_get_version(void) + + :return: The current core version + +--------------------- + +.. function:: const char *obs_get_version_string(void) + + :return: The current core version string + +--------------------- + +.. function:: void obs_set_locale(const char *locale) + + Sets a new locale to use for modules. This will call + obs_module_set_locale for each module with the new locale. + + :param locale: The locale to use for modules + +--------------------- + +.. function:: const char *obs_get_locale(void) + + :return: The current locale + +--------------------- + +.. function:: profiler_name_store_t *obs_get_profiler_name_store(void) + + :return: The profiler name store (see util/profiler.h) used by OBS, + which is either a name store passed to obs_startup, an + internal name store, or NULL in case obs_initialized() + returns false. + +--------------------- + +.. function:: int obs_reset_video(struct obs_video_info *ovi) + + Sets base video output base resolution/fps/format. + + Note: This data cannot be changed if an output is currently active. + + Note: The graphics module cannot be changed without fully destroying + the OBS context. + + :param ovi: Pointer to an obs_video_info structure containing the + specification of the graphics subsystem, + :return: | OBS_VIDEO_SUCCESS - Success + | OBS_VIDEO_NOT_SUPPORTED - The adapter lacks capabilities + | OBS_VIDEO_INVALID_PARAM - A parameter is invalid + | OBS_VIDEO_CURRENTLY_ACTIVE - Video is currently active + | OBS_VIDEO_MODULE_NOT_FOUND - The graphics module is not found + | OBS_VIDEO_FAIL - Generic failure + + Relevant data types used with this function: + +.. code:: cpp + + struct obs_video_info { + /** + * Graphics module to use (usually "libobs-opengl" or "libobs-d3d11") + */ + const char *graphics_module; + + uint32_t fps_num; /**< Output FPS numerator */ + uint32_t fps_den; /**< Output FPS denominator */ + + uint32_t base_width; /**< Base compositing width */ + uint32_t base_height; /**< Base compositing height */ + + uint32_t output_width; /**< Output width */ + uint32_t output_height; /**< Output height */ + enum video_format output_format; /**< Output format */ + + /** Video adapter index to use (NOTE: avoid for optimus laptops) */ + uint32_t adapter; + + /** Use shaders to convert to different color formats */ + bool gpu_conversion; + + enum video_colorspace colorspace; /**< YUV type (if YUV) */ + enum video_range_type range; /**< YUV range (if YUV) */ + + enum obs_scale_type scale_type; /**< How to scale if scaling */ + }; + +--------------------- + +.. function:: bool obs_reset_audio(const struct obs_audio_info *oai) + + Sets base audio output format/channels/samples/etc. + + Note: Cannot reset base audio if an output is currently active. + + :return: *true* if successful, *false* otherwise + + Relevant data types used with this function: + +.. code:: cpp + + struct obs_audio_info { + uint32_t samples_per_sec; + enum speaker_layout speakers; + }; + +--------------------- + +.. function:: bool obs_get_video_info(struct obs_video_info *ovi) + + Gets the current video settings. + + :return: *false* if no video + +--------------------- + +.. function:: bool obs_get_audio_info(struct obs_audio_info *oai) + + Gets the current audio settings. + + :return: *false* if no audio + +--------------------- + + +Libobs Objects +-------------- + +.. function:: bool obs_enum_source_types(size_t idx, const char **id) + + Enumerates all source types (inputs, filters, transitions, etc). + +--------------------- + +.. function:: bool obs_enum_input_types(size_t idx, const char **id) + + Enumerates all available inputs source types. + + Inputs are general source inputs (such as capture sources, device sources, + etc). + +--------------------- + +.. function:: bool obs_enum_filter_types(size_t idx, const char **id) + + Enumerates all available filter source types. + + Filters are sources that are used to modify the video/audio output of + other sources. + +--------------------- + +.. function:: bool obs_enum_transition_types(size_t idx, const char **id) + + Enumerates all available transition source types. + + Transitions are sources used to transition between two or more other + sources. + +--------------------- + +.. function:: bool obs_enum_output_types(size_t idx, const char **id) + + Enumerates all available output types. + +--------------------- + +.. function:: bool obs_enum_encoder_types(size_t idx, const char **id) + + Enumerates all available encoder types. + +--------------------- + +.. function:: bool obs_enum_service_types(size_t idx, const char **id) + + Enumerates all available service types. + +--------------------- + +.. function:: void obs_enum_sources(bool (*enum_proc)(void*, obs_source_t*), void *param) + + Enumerates all input sources. + + Callback function returns true to continue enumeration, or false to end + enumeration. + + Use :c:func:`obs_source_get_ref()` or + :c:func:`obs_source_get_weak_source()` if you want to retain a + reference after obs_enum_sources finishes. + +--------------------- + +.. function:: void obs_enum_outputs(bool (*enum_proc)(void*, obs_output_t*), void *param) + + Enumerates outputs. + +--------------------- + +.. function:: void obs_enum_encoders(bool (*enum_proc)(void*, obs_encoder_t*), void *param) + + Enumerates encoders. + +--------------------- + +.. function:: obs_source_t *obs_get_source_by_name(const char *name) + + Gets a source by its name. + + Increments the source reference counter, use + :c:func:`obs_source_release()` to release it when complete. + +--------------------- + +.. function:: obs_output_t *obs_get_output_by_name(const char *name) + + Gets an output by its name. + + Increments the output reference counter, use + :c:func:`obs_output_release()` to release it when complete. + +--------------------- + +.. function:: obs_encoder_t *obs_get_encoder_by_name(const char *name) + + Gets an encoder by its name. + + Increments the encoder reference counter, use + :c:func:`obs_encoder_release()` to release it when complete. + +--------------------- + +.. function:: obs_service_t *obs_get_service_by_name(const char *name) + + Gets an service by its name. + + Increments the service reference counter, use + :c:func:`obs_service_release()` to release it when complete. + +--------------------- + +.. function:: obs_data_t *obs_save_source(obs_source_t *source) + + :return: A new reference to a source's saved data + +--------------------- + +.. function:: obs_source_t *obs_load_source(obs_data_t *data) + + :return: A source created from saved data + +--------------------- + +.. function:: void obs_load_sources(obs_data_array_t *array, obs_load_source_cb cb, void *private_data) + + Helper function to load active sources from a data array. + + Relevant data types used with this function: + +.. code:: cpp + + typedef void (*obs_load_source_cb)(void *private_data, obs_source_t *source); + +--------------------- + +.. function:: obs_data_array_t *obs_save_sources(void) + + :return: A data array with the saved data of all active sources + +--------------------- + +.. function:: obs_data_array_t *obs_save_sources_filtered(obs_save_source_filter_cb cb, void *data) + + :return: A data array with the saved data of all active sources, + filtered by the *cb* function + + Relevant data types used with this function: + +.. code:: cpp + + typedef bool (*obs_save_source_filter_cb)(void *data, obs_source_t *source); + +--------------------- + + +Video, Audio, and Graphics +-------------------------- + +.. function:: void obs_enter_graphics(void) + + Helper function for entering the OBS graphics context. + +--------------------- + +.. function:: void obs_leave_graphics(void) + + Helper function for leaving the OBS graphics context. + +--------------------- + +.. function:: audio_t *obs_get_audio(void) + + :return: The main audio output handler for this OBS context + +--------------------- + +.. function:: video_t *obs_get_video(void) + + :return: The main video output handler for this OBS context + +--------------------- + +.. function:: void obs_set_output_source(uint32_t channel, obs_source_t *source) + + Sets the primary output source for a channel. + +--------------------- + +.. function:: obs_source_t *obs_get_output_source(uint32_t channel) + + Gets the primary output source for a channel and increments the reference + counter for that source. Use :c:func:`obs_source_release()` to release. + +--------------------- + +.. function:: gs_effect_t *obs_get_base_effect(enum obs_base_effect effect) + + Returns a commoinly used base effect. + + :param effect: | Can be one of the following values: + | OBS_EFFECT_DEFAULT - RGB/YUV + | OBS_EFFECT_DEFAULT_RECT - RGB/YUV (using texture_rect) + | OBS_EFFECT_OPAQUE - RGB/YUV (alpha set to 1.0) + | OBS_EFFECT_SOLID - RGB/YUV (solid color only) + | OBS_EFFECT_BICUBIC - Bicubic downscale + | OBS_EFFECT_LANCZOS - Lanczos downscale + | OBS_EFFECT_BILINEAR_LOWRES - Bilinear low resolution downscale + | OBS_EFFECT_PREMULTIPLIED_ALPHA - Premultiplied alpha + +--------------------- + +.. function:: void obs_render_main_view(void) + + Renders the main view. + +--------------------- + +.. function:: void obs_set_master_volume(float volume) + + Sets the master user volume. + +--------------------- + +.. function:: float obs_get_master_volume(void) + + :return: The master user volume + +--------------------- + +.. function:: void obs_enum_audio_monitoring_devices(obs_enum_audio_device_cb cb, void *data) + + Enumerates audio devices which can be used for audio monitoring. + + Relevant data types used with this function: + +.. code:: cpp + + typedef bool (*obs_enum_audio_device_cb)(void *data, const char *name, const char *id); + +--------------------- + +.. function:: bool obs_set_audio_monitoring_device(const char *name, const char *id) + + Sets the current audio device for audio monitoring. + +--------------------- + +.. function:: void obs_get_audio_monitoring_device(const char **name, const char **id) + + Gets the current audio device for audio monitoring. + +--------------------- + +.. function:: void obs_add_main_render_callback(void (*draw)(void *param, uint32_t cx, uint32_t cy), void *param) + void obs_remove_main_render_callback(void (*draw)(void *param, uint32_t cx, uint32_t cy), void *param) + + Adds/removes a main rendering callback. Allows custom rendering to + the main stream/recording output. + + +Primary signal/procedure handlers +--------------------------------- + +.. function:: signal_handler_t *obs_get_signal_handler(void) + + :return: The primary obs signal handler + + See :ref:`core_signal_handler_reference` for more information on + core signals. + +--------------------- + +.. function:: proc_handler_t *obs_get_proc_handler(void) + + :return: The primary obs procedure handler + + +.. _core_signal_handler_reference: + +Core OBS Signals +---------------- + +**source_create** (ptr source) + + Called when a source has been created. + +**source_destroy** (ptr source) + + Called when a source has been destroyed. + +**source_remove** (ptr source) + + Called when a source has been removed (:c:func:`obs_source_remove()` + has been called on the source). + +**source_save** (ptr source) + + Called when a source is being saved. + +**source_load** (ptr source) + + Called when a source is being loaded. + +**source_activate** (ptr source) + + Called when a source has been activated in the main view (visible on + stream/recording). + +**source_deactivate** (ptr source) + + Called when a source has been deactivated from the main view (no + longer visible on stream/recording). + +**source_show** (ptr source) + + Called when a source is visible on any display and/or on the main + view. + +**source_hide** (ptr source) + + Called when a source is no longer visible on any display and/or on + the main view. + +**source_rename** (ptr source, string new_name, string prev_name) + + Called when a source has been renamed. + +**source_volume** (ptr source, in out float volume) + + Called when a source's volume has changed. + +**source_transition_start** (ptr source) + + Called when a transition has started its transition. + +**source_transition_video_stop** (ptr source) + + Called when a transition has stopped its video transitioning. + +**source_transition_stop** (ptr source) + + Called when a transition has stopped its transition. + +**channel_change** (int channel, in out ptr source, ptr prev_source) + + Called when :c:func:`obs_set_output_source()` has been called. + +**master_volume** (in out float volume) + + Called when the master volume has changed. + +**hotkey_layout_change** () + + Called when the hotkey layout has changed. + +**hotkey_register** (ptr hotkey) + + Called when a hotkey has been registered. + +**hotkey_unregister** (ptr hotkey) + + Called when a hotkey has been unregistered. + +**hotkey_bindings_changed** (ptr hotkey) + + Called when a hotkey's bindings has changed. + +--------------------- + + +.. _display_reference: + +Displays +-------- + +.. function:: obs_display_t *obs_display_create(const struct gs_init_data *graphics_data) + + Adds a new window display linked to the main render pipeline. This creates + a new swap chain which updates every frame. + + *(Important note: do not use more than one display widget within the + hierarchy of the same base window; this will cause presentation + stalls on Macs.)* + + :param graphics_data: The swap chain initialization data + :return: The new display context, or NULL if failed + + Relevant data types used with this function: + +.. code:: cpp + + enum gs_color_format { + [...] + GS_RGBA, + GS_BGRX, + GS_BGRA, + GS_RGBA16F, + GS_RGBA32F, + [...] + }; + + enum gs_zstencil_format { + GS_ZS_NONE, + GS_Z16, + GS_Z24_S8, + GS_Z32F, + GS_Z32F_S8X24 + }; + + struct gs_window { + #if defined(_WIN32) + void *hwnd; + #elif defined(__APPLE__) + __unsafe_unretained id view; + #elif defined(__linux__) || defined(__FreeBSD__) + uint32_t id; + void *display; + #endif + }; + + struct gs_init_data { + struct gs_window window; + uint32_t cx, cy; + uint32_t num_backbuffers; + enum gs_color_format format; + enum gs_zstencil_format zsformat; + uint32_t adapter; + }; + +--------------------- + +.. function:: void obs_display_destroy(obs_display_t *display) + + Destroys a display context. + +--------------------- + +.. function:: void obs_display_resize(obs_display_t *display, uint32_t cx, uint32_t cy) + + Changes the size of a display context. + +--------------------- + +.. function:: void obs_display_add_draw_callback(obs_display_t *display, void (*draw)(void *param, uint32_t cx, uint32_t cy), void *param) + + Adds a draw callback for a display context, which will be called + whenever the display is rendered. + + :param display: The display context + :param draw: The draw callback which is called each time a frame + updates + :param param: The user data to be associated with this draw callback + +--------------------- + +.. function:: void obs_display_remove_draw_callback(obs_display_t *display, void (*draw)(void *param, uint32_t cx, uint32_t cy), void *param) + + Removes a draw callback for a display context. + +--------------------- + +.. function:: void obs_display_set_enabled(obs_display_t *display, bool enable) + + Enables/disables a display context. + +--------------------- + +.. function:: bool obs_display_enabled(obs_display_t *display) + + :return: *true* if the display is enabled, *false* otherwise + +--------------------- + +.. function:: void obs_display_set_background_color(obs_display_t *display, uint32_t color) + + Sets the background (clear) color for the display context. diff --git a/docs/sphinx/reference-encoders.rst b/docs/sphinx/reference-encoders.rst new file mode 100644 index 000000000..37cde8312 --- /dev/null +++ b/docs/sphinx/reference-encoders.rst @@ -0,0 +1,493 @@ +Encoder API Reference (obs_encoder_t) +===================================== + +Encoders are OBS-specific implementations of video/audio encoders, which +are used with outputs that use encoders. x264, NVENC, Quicksync are +examples of encoder implementations. The `libobs/obs-encoder.h`_ file +is the dedicated header for implementing encoders + +.. type:: obs_encoder_t + + A reference-counted encoder object. + +.. type:: obs_weak_encoder_t + + A weak reference to an encoder object. + +.. code:: cpp + + #include + + +Encoder Definition Structure (obs_encoder_info) +----------------------------------------------- + +.. type:: struct obs_encoder_info + + Encoder definition structure. + +.. member:: const char *obs_encoder_info.id + + Unique string identifier for the encoder (required). + +.. member:: enum obs_encoder_type obs_encoder_info.type + + Type of encoder. + + - **OBS_ENCODER_VIDEO** - Video encoder + - **OBS_ENCODER_AUDIO** - Audio encoder + +.. member:: const char *obs_encoder_info.codec + + The codec, in string form. For example, "h264" for an H.264 encoder. + +.. member:: const char *(*obs_encoder_info.get_name)(void *type_data) + + Get the translated name of the encoder type. + + :param type_data: The type_data variable of this structure + :return: The translated name of the encoder type + +.. member:: void *(*obs_encoder_info.create)(obs_data_t *settings, obs_encoder_t *encoder) + + Creates the implementation data for the encoder. + + :param settings: Settings to initialize the encoder with + :param encoder: Encoder that this data is associated with + :return: The implementation data associated with this encoder + +.. member:: void (*obs_encoder_info.destroy)(void *data) + + Destroys the implementation data for the encoder. + +.. member:: bool (*encode)(void *data, struct encoder_frame *frame, struct encoder_packet *packet, bool *received_packet) + + Called to encode video or audio and outputs packets as they become + available. + + :param frame: Raw audio/video data to encode + :param packet: Encoder packet output, if any + :param received_packet: Set to *true* if a packet was received, + *false* otherwise + :return: true if successful, false on critical failure + +.. member:: size_t (*get_frame_size)(void *data) + + :return: An audio encoder's frame size. For example, for AAC this + number would be 1024 + +.. member:: void (*obs_encoder_info.get_defaults)(obs_data_t *settings) + void (*obs_encoder_info.get_defaults2)(void *type_data, obs_data_t *settings) + + Sets the default settings for this encoder. + + :param settings: Default settings. Call obs_data_set_default* + functions on this object to set default setting + values + +.. member:: obs_properties_t *(*obs_encoder_info.get_properties)(void *data) + obs_properties_t *(*obs_encoder_info.get_properties2)(void *data, void *type_data) + + Gets the property information of this encoder. + + (Optional) + + :return: The properties of the encoder + +.. member:: void (*obs_encoder_info.update)(void *data, obs_data_t *settings) + + Updates the settings for this encoder. + + (Optional) + + :param settings: New settings for this encoder + +.. member:: bool (*obs_encoder_info.get_extra_data)(void *data, uint8_t **extra_data, size_t *size) + + Returns extra data associated with this encoder (usually header). + + (Optional) + + :param extra_data: Pointer to receive the extra data + :param size: Pointer to receive the size of the extra + data + :return: true if extra data available, false + otherwise + +.. member:: bool (*obs_encoder_info.get_sei_data)(void *data, uint8_t **sei_data, size_t *size) + + Gets the SEI data of a video encoder that has SEI data. + + (Optional) + + :param sei_data: Pointer to receive the SEI data + :param size: Pointer to receive the SEI data size + :return: true if SEI data available, false otherwise + +.. member:: void (*obs_encoder_info.get_audio_info)(void *data, struct audio_convert_info *info) + + Returns desired audio format and sample information. This callback + can be used to tell the back-end that the audio data needs to be + automatically converted to a different sample rate or audio format + before being sent to the encoder. + + (Optional) + + :param info: Audio format information + +.. member:: void (*obs_encoder_info.get_video_info)(void *data, struct video_scale_info *info) + + Returns desired video format information. This callback can be used + to tell the back-end that the video data needs to be automatically + converted to a different video format or specific size before being + sent to the encoder. + + :param info: Video format information + +.. member:: void *obs_encoder_info.type_data + void (*obs_encoder_info.free_type_data)(void *type_data) + + Private data associated with this entry. Note that this is not the + same as the implementation data; this is used to differentiate + between two different types if the same callbacks are used for more + than one different type. + +.. member:: uint32_t obs_encoder_info.caps + + Can be 0 or a bitwise OR combination of one or more of the following + values: + + - **OBS_ENCODER_CAP_DEPRECATED** - Encoder is deprecated + + +Encoder Packet Structure (encoder_packet) +----------------------------------------- + +.. type:: struct encoder_packet + + Encoder packet structure. + +.. member:: uint8_t *encoder_packet.data + + Packet data. + +.. member:: size_t encoder_packet.size + + Packet size. + +.. member:: int64_t encoder_packet.pts + int64_t encoder_packet.dts + + Packet presentation and decode timestamps. + +.. member:: int32_t encoder_packet.timebase_num + int32_t encoder_packet.timebase_den + + Packet time base. + +.. member:: enum obs_encoder_type encoder_packet.type + + Can be one of the following values: + + - **OBS_ENCODER_VIDEO** - Video data + - **OBS_ENCODER_AUDIO** - Audio data + +.. member:: bool encoder_packet.keyframe + + Packet is a keyframe. + +.. member:: int64_t encoder_packet.dts_usec + + The DTS in microseconds. + + (This should not be set by the encoder implementation) + +.. member:: int64_t encoder_packet.sys_dts_usec + + The system time of this packet in microseconds. + + (This should not be set by the encoder implementation) + +.. member:: int encoder_packet.priority + + Packet priority. This is no longer used. + + (This should not be set by the encoder implementation) + +.. member:: int encoder_packet.drop_priority + + Packet drop priority. + + If this packet needs to be dropped, the next packet must be of this + priority or higher to continue transmission. + + (This should not be set by the encoder implementation) + +.. member:: size_t encoder_packet.track_idx + + Audio track index. + + (This should not be set by the encoder implementation) + +.. member:: obs_encoder_t *encoder_packet.encoder + + Encoder object associated with this packet. + + (This should not be set by the encoder implementation) + + +Raw Frame Data Structure (encoder_frame) +---------------------------------------- + +.. type:: struct encoder_frame + + Raw frame data structure. + +.. member:: uint8_t *encoder_frame.data[MAX_AV_PLANES] + + Raw video/audio data. + +.. member:: uint32_t encoder_frame.linesize[MAX_AV_PLANES] + + Line size of each plane. + +.. member:: uint32_t encoder_frame.frames + + Number of audio frames (if audio). + +.. member:: int64_t encoder_frame.pts + + Presentation timestamp. + + +General Encoder Functions +------------------------- + +.. function:: void obs_register_encoder(struct obs_encoder_info *info) + + Registers an encoder type. Typically used in + :c:func:`obs_module_load()` or in the program's initialization phase. + +--------------------- + +.. function:: const char *obs_encoder_get_display_name(const char *id) + + Calls the :c:member:`obs_encoder_info.get_name` callback to get the + translated display name of an encoder type. + + :param id: The encoder type string identifier + :return: The translated display name of an encoder type + +--------------------- + +.. function:: obs_encoder_t *obs_video_encoder_create(const char *id, const char *name, obs_data_t *settings, obs_data_t *hotkey_data) + + Creates a video encoder with the specified settings. + + The "encoder" context is used for encoding video/audio data. Use + obs_encoder_release to release it. + + :param id: The encoder type string identifier + :param name: The desired name of the encoder. If this is + not unique, it will be made to be unique + :param settings: The settings for the encoder, or *NULL* if + none + :param hotkey_data: Saved hotkey data for the encoder, or *NULL* + if none + :return: A reference to the newly created encoder, or + *NULL* if failed + +--------------------- + +.. function:: obs_encoder_t *obs_audio_encoder_create(const char *id, const char *name, obs_data_t *settings, size_t mixer_idx, obs_data_t *hotkey_data) + + Creates an audio encoder with the specified settings. + + The "encoder" context is used for encoding video/audio data. Use + :c:func:`obs_encoder_release()` to release it. + + :param id: The encoder type string identifier + :param name: The desired name of the encoder. If this is + not unique, it will be made to be unique + :param settings: The settings for the encoder, or *NULL* if + none + :param mixer_idx: The audio mixer index this audio encoder + will capture audio from + :param hotkey_data: Saved hotkey data for the encoder, or *NULL* + if none + :return: A reference to the newly created encoder, or + *NULL* if failed + +--------------------- + +.. function:: void obs_encoder_addref(obs_encoder_t *encoder) + void obs_encoder_release(obs_encoder_t *encoder) + + Adds/releases a reference to an encoder. When the last reference is + released, the encoder is destroyed. + +--------------------- + +.. function:: obs_weak_encoder_t *obs_encoder_get_weak_encoder(obs_encoder_t *encoder) + obs_encoder_t *obs_weak_encoder_get_encoder(obs_weak_encoder_t *weak) + + These functions are used to get a weak reference from a strong encoder + reference, or a strong encoder reference from a weak reference. If + the encoder is destroyed, *obs_weak_encoder_get_encoder* will return + *NULL*. + +--------------------- + +.. function:: void obs_weak_encoder_addref(obs_weak_encoder_t *weak) + void obs_weak_encoder_release(obs_weak_encoder_t *weak) + + Adds/releases a weak reference to an encoder. + +--------------------- + +.. function:: void obs_encoder_set_name(obs_encoder_t *encoder, const char *name) + + Sets the name of an encoder. If the encoder is not private and the + name is not unique, it will automatically be given a unique name. + +--------------------- + +.. function:: const char *obs_encoder_get_name(const obs_encoder_t *encoder) + + :return: The name of the encoder + +--------------------- + +.. function:: const char *obs_encoder_get_codec(const obs_encoder_t *encoder) + const char *obs_get_encoder_codec(const char *id) + + :return: The codec identifier of the encoder + +--------------------- + +.. function:: enum obs_encoder_type obs_encoder_get_type(const obs_encoder_t *encoder) + enum obs_encoder_type obs_get_encoder_type(const char *id) + + :return: The encoder type: OBS_ENCODER_VIDEO or OBS_ENCODER_AUDIO + +--------------------- + +.. function:: void obs_encoder_set_scaled_size(obs_encoder_t *encoder, uint32_t width, uint32_t height) + + Sets the scaled resolution for a video encoder. Set width and height to 0 + to disable scaling. If the encoder is active, this function will trigger + a warning, and do nothing. + +--------------------- + +.. function:: uint32_t obs_encoder_get_width(const obs_encoder_t *encoder) + uint32_t obs_encoder_get_height(const obs_encoder_t *encoder) + + :return: The width/height of a video encoder's encoded image + +--------------------- + +.. function:: uint32_t obs_encoder_get_sample_rate(const obs_encoder_t *encoder) + + :return: The sample rate of an audio encoder's audio data + +--------------------- + +.. function:: void obs_encoder_set_preferred_video_format(obs_encoder_t *encoder, enum video_format format) + enum video_format obs_encoder_get_preferred_video_format(const obs_encoder_t *encoder) + + + Sets the preferred video format for a video encoder. If the encoder can use + the format specified, it will force a conversion to that format if the + obs output format does not match the preferred format. + + If the format is set to VIDEO_FORMAT_NONE, will revert to the default + functionality of converting only when absolutely necessary. + +--------------------- + +.. function:: obs_data_t *obs_encoder_defaults(const char *id) + + :return: An incremented reference to the encoder's default settings + +--------------------- + +.. function:: obs_properties_t *obs_encoder_properties(const obs_encoder_t *encoder) + obs_properties_t *obs_get_encoder_properties(const char *id) + + Use these functions to get the properties of an encoder or encoder + type. Properties are optionally used (if desired) to automatically + generate user interface widgets to allow users to update settings. + + :return: The properties list for a specific existing encoder. Free + with :c:func:`obs_properties_destroy()` + +--------------------- + +.. function:: void obs_encoder_update(obs_encoder_t *encoder, obs_data_t *settings) + + Updates the settings for this encoder context. + +--------------------- + +.. function:: obs_data_t *obs_encoder_get_settings(const obs_encoder_t *encoder) + + :return: An incremented reference to the encoder's settings + +--------------------- + +.. function:: signal_handler_t *obs_encoder_get_signal_handler(const obs_encoder_t *encoder) + + :return: The signal handler of the encoder + +--------------------- + +.. function:: proc_handler_t *obs_encoder_get_proc_handler(const obs_encoder_t *encoder) + + :return: The procedure handler of the encoder + +--------------------- + +.. function:: bool obs_encoder_get_extra_data(const obs_encoder_t *encoder, uint8_t **extra_data, size_t *size) + + Gets extra data (headers) associated with this encoder. + + :return: *true* if successful, *false* if no extra data associated + with this encoder + +--------------------- + +.. function:: void obs_encoder_set_video(obs_encoder_t *encoder, video_t *video) + void obs_encoder_set_audio(obs_encoder_t *encoder, audio_t *audio) + + Sets the video/audio handler to use with this video/audio encoder. + This is used to capture the raw video/audio data. + +--------------------- + +.. function:: video_t *obs_encoder_video(const obs_encoder_t *encoder) + audio_t *obs_encoder_audio(const obs_encoder_t *encoder) + + :return: The video/audio handler associated with this encoder, or + *NULL* if none or not a matching encoder type + +--------------------- + +.. function:: bool obs_encoder_active(const obs_encoder_t *encoder) + + :return: *true* if the encoder is active, *false* otherwise + +--------------------- + + +Functions used by encoders +-------------------------- + +.. function:: void obs_encoder_packet_ref(struct encoder_packet *dst, struct encoder_packet *src) + void obs_encoder_packet_release(struct encoder_packet *packet) + + Adds or releases a reference to an encoder packet. + +.. --------------------------------------------------------------------------- + +.. _libobs/obs-encoder.h: https://github.com/jp9000/obs-studio/blob/master/libobs/obs-encoder.h diff --git a/docs/sphinx/reference-libobs-callback.rst b/docs/sphinx/reference-libobs-callback.rst new file mode 100644 index 000000000..6a954ddd1 --- /dev/null +++ b/docs/sphinx/reference-libobs-callback.rst @@ -0,0 +1,276 @@ +Callback API Reference (libobs/callback) +======================================== + + +Calldata +-------- + +The :c:type:`calldata_t` object is used to pass parameters from signal +handlers or to procedure handlers. + +.. type:: calldata_t + +--------------------- + +.. function:: void calldata_init(calldata_t *data) + + Initializes a calldata structure (zeroes it). + + :param data: Calldata structure + +--------------------- + +.. function:: void calldata_free(calldata_t *data) + + Frees a calldata structure. + + :param data: Calldata structure + +--------------------- + +.. function:: void calldata_set_int(calldata_t *data, const char *name, long long val) + + Sets an integer parameter. + + :param data: Calldata structure + :param name: Parameter name + :param val: Integer value + +--------------------- + +.. function:: void calldata_set_float(calldata_t *data, const char *name, double val) + + Sets a floating point parameter. + + :param data: Calldata structure + :param name: Parameter name + :param val: Floating point value + +--------------------- + +.. function:: void calldata_set_bool(calldata_t *data, const char *name, bool val) + + Sets a boolean parameter. + + :param data: Calldata structure + :param name: Parameter name + :param val: Boolean value + +--------------------- + +.. function:: void calldata_set_ptr(calldata_t *data, const char *name, void *ptr) + + Sets a pointer parameter. + + :param data: Calldata structure + :param name: Parameter name + :param val: Pointer value + +--------------------- + +.. function:: void calldata_set_string(calldata_t *data, const char *name, const char *str) + + Sets a string parameter. + + :param data: Calldata structure + :param name: Parameter name + :param val: String + +--------------------- + +.. function:: long long calldata_int(const calldata_t *data, const char *name) + + Gets an integer parameter. + + :param data: Calldata structure + :param name: Parameter name + :return: Integer value + +--------------------- + +.. function:: double calldata_float(const calldata_t *data, const char *name) + + Gets a floating point parameter. + + :param data: Calldata structure + :param name: Parameter name + :return: Floating point value + +--------------------- + +.. function:: bool calldata_bool(const calldata_t *data, const char *name) + + Gets a boolean parameter. + + :param data: Calldata structure + :param name: Parameter name + :return: Boolean value + +--------------------- + +.. function:: void *calldata_ptr(const calldata_t *data, const char *name) + + Gets a pointer parameter. + + :param data: Calldata structure + :param name: Parameter name + :return: Pointer value + +--------------------- + +.. function:: const char *calldata_string(const calldata_t *data, const char *name) + + Gets a string parameter. + + :param data: Calldata structure + :param name: Parameter name + :return: String value + +--------------------- + + +Signals +------- + +Signals are used for all event-based callbacks. + +.. code:: cpp + + #include + +.. type:: signal_handler_t + +--------------------- + +.. type:: typedef void (*signal_callback_t)(void *data, calldata_t *cd) + + Signal callback. + + :param data: Private data passed to this callback + :param cd: Calldata object + +--------------------- + +.. function:: signal_handler_t *signal_handler_create(void) + + Creates a new signal handler object. + + :return: A new signal handler object + +--------------------- + +.. function:: void signal_handler_destroy(signal_handler_t *handler) + + Destroys a signal handler. + + :param handler: Signal handler object + +--------------------- + +.. function:: bool signal_handler_add(signal_handler_t *handler, const char *signal_decl) + + Adds a signal to a signal handler. + + :param handler: Signal handler object + :param signal_decl: Signal declaration string + +--------------------- + +.. function:: bool signal_handler_add_array(signal_handler_t *handler, const char **signal_decls) + + Adds multiple signals to a signal handler. + + :param handler: Signal handler object + :param signal_decls: An array of signal declaration strings, + terminated by *NULL* + +--------------------- + +.. function:: void signal_handler_connect(signal_handler_t *handler, const char *signal, signal_callback_t callback, void *data) + + Connect a callback to a signal on a signal handler. + + :param handler: Signal handler object + :param callback: Signal callback + :param data: Private data passed the callback + +--------------------- + +.. function:: void signal_handler_disconnect(signal_handler_t *handler, const char *signal, signal_callback_t callback, void *data) + + Disconnects a callback from a signal on a signal handler. + + :param handler: Signal handler object + :param callback: Signal callback + :param data: Private data passed the callback + +--------------------- + +.. function:: void signal_handler_signal(signal_handler_t *handler, const char *signal, calldata_t *params) + + Triggers a signal, calling all connected callbacks. + + :param handler: Signal handler object + :param signal: Name of signal to trigger + :param params: Parameters to pass to the signal + +--------------------- + + +Procedure Handlers +------------------ + +Procedure handlers are used to call functions without having to have +direct access to declarations or callback pointers. + +.. code:: cpp + + #include + +.. type:: proc_handler_t + +--------------------- + +.. type:: typedef void (*proc_handler_proc_t)(void *data, calldata_t *cd) + + Procedure handler callback. + + :param data: Private data passed to this callback + :param cd: Calldata object + +--------------------- + +.. function:: proc_handler_t *proc_handler_create(void) + + Creates a new procedure handler. + + :return: A new procedure handler object + +--------------------- + +.. function:: void proc_handler_destroy(proc_handler_t *handler) + + Destroys a procedure handler object. + + :param handler: Procedure handler object + +--------------------- + +.. function:: void proc_handler_add(proc_handler_t *handler, const char *decl_string, proc_handler_proc_t proc, void *data) + + Adds a procedure to a procedure handler. + + :param handler: Procedure handler object + :param decl_string: Procedure declaration string + :param proc: Procedure callback + :param data: Private data to pass to the callback + +--------------------- + +.. function:: bool proc_handler_call(proc_handler_t *handler, const char *name, calldata_t *params) + + Calls a procedure within the procedure handler. + + :param handler: Procedure handler object + :param name: Name of procedure to call + :param params: Calldata structure to pass to the procedure diff --git a/docs/sphinx/reference-libobs-graphics-axisang.rst b/docs/sphinx/reference-libobs-graphics-axisang.rst new file mode 100644 index 000000000..5414cbadd --- /dev/null +++ b/docs/sphinx/reference-libobs-graphics-axisang.rst @@ -0,0 +1,65 @@ +Axis Angle +========== + +Provides a helper structure for conversion to quaternions. + +.. code:: cpp + + #include + +.. type:: struct axisang +.. member:: float axisang.x + + X axis + +.. member:: float axisang.y + + Y axis + +.. member:: float axisang.z + + Z axis + +.. member:: float axisang.w + + Angle + +.. member:: float axisang.ptr[4] + +--------------------- + +.. function:: void axisang_zero(struct axisang *dst) + + Zeroes the axis angle. + + :param dst: Axis angle + +--------------------- + +.. function:: void axisang_copy(struct axisang *dst, struct axisang *aa) + + Copies an axis angle. + + :param dst: Axis angle to copy to + :param aa: Axis angle to copy from + +--------------------- + +.. function:: void axisang_set(struct axisang *dst, float x, float y, float z, float w) + + Sets an axis angle. + + :param dst: Axis angle to set + :param x: X axis + :param y: Y axis + :param z: Z axis + :param w: Angle + +--------------------- + +.. function:: void axisang_from_quat(struct axisang *dst, const struct quat *q) + + Creates an axis angle from a quaternion. + + :param dst: Axis angle destination + :param q: Quaternion to convert diff --git a/docs/sphinx/reference-libobs-graphics-effects.rst b/docs/sphinx/reference-libobs-graphics-effects.rst new file mode 100644 index 000000000..89217d8ba --- /dev/null +++ b/docs/sphinx/reference-libobs-graphics-effects.rst @@ -0,0 +1,324 @@ +Effects (Shaders) +================= + +Effects are a single collection of related shaders. They're used for +easily writing vertex and pixel shaders together all in the same file in +HLSL format. + +.. code:: cpp + + #include + +.. type:: typedef struct gs_effect gs_effect_t + + Effect object. + +.. type:: typedef struct gs_effect_technique gs_technique_t + + Technique object. + +.. type:: typedef struct gs_effect_param gs_eparam_t + + Effect parameter object. + + +--------------------- + +.. function:: gs_effect_t *gs_effect_create_from_file(const char *file, char **error_string) + + Creates an effect from file. + + :param file: Path to the effect file + :param error_string: Receives a pointer to the error string, which + must be freed with :c:func:`bfree()`. If + *NULL*, this parameter is ignored. + :return: The effect object, or *NULL* on error + +--------------------- + +.. function:: gs_effect_t *gs_effect_create(const char *effect_string, const char *filename, char **error_string) + + Creates an effect from a string. + + :param effect_String: Effect string + :param error_string: Receives a pointer to the error string, which + must be freed with :c:func:`bfree()`. If + *NULL*, this parameter is ignored. + :return: The effect object, or *NULL* on error + +--------------------- + +.. function:: void gs_effect_destroy(gs_effect_t *effect) + + Destroys the effect + + :param effect: Effect object + +--------------------- + +.. function:: gs_technique_t *gs_effect_get_technique(const gs_effect_t *effect, const char *name) + + Gets a technique of the effect. + + :param effect: Effect object + :param name: Name of the technique + :return: Technique object, or *NULL* if not found + +--------------------- + +.. function:: gs_technique_t *gs_effect_get_current_technique(const gs_effect_t *effect) + + Gets the current active technique of the effect. + + :param effect: Effect object + :return: Technique object, or *NULL* if none currently active + +--------------------- + +.. function:: size_t gs_technique_begin(gs_technique_t *technique) + + Begins a technique. + + :param technique: Technique object + :return: Number of passes this technique uses + +--------------------- + +.. function:: void gs_technique_end(gs_technique_t *technique) + + Ends a technique. Make sure all active passes have been ended before + calling. + + :param technique: Technique object + +--------------------- + +.. function:: bool gs_technique_begin_pass(gs_technique_t *technique, size_t pass) + + Begins a pass. Automatically loads the vertex/pixel shaders + associated with this pass. Draw after calling this function. + + :param technique: Technique object + :param pass: Pass index + :return: *true* if the pass is valid, *false* otherwise + +--------------------- + +.. function:: bool gs_technique_begin_pass_by_name(gs_technique_t *technique, const char *name) + + Begins a pass by its name if the pass has a name. Automatically + loads the vertex/pixel shaders associated with this pass. Draw after + calling this function. + + :param technique: Technique object + :param name: Name of the pass + :return: *true* if the pass is valid, *false* otherwise + +--------------------- + +.. function:: void gs_technique_end_pass(gs_technique_t *technique) + + Ends a pass. + + :param technique: Technique object + +--------------------- + +.. function:: size_t gs_effect_get_num_params(const gs_effect_t *effect) + + Gets the number of parameters associated with the effect. + + :param effect: Effect object + :return: Number of parameters the effect has + +--------------------- + +.. function:: gs_eparam_t *gs_effect_get_param_by_idx(const gs_effect_t *effect, size_t param) + + Gets a parameter of an effect by its index. + + :param effect: Effect object + :param param: Parameter index + :return: The effect parameter object, or *NULL* if index + invalid + +--------------------- + +.. function:: gs_eparam_t *gs_effect_get_param_by_name(const gs_effect_t *effect, const char *name) + + Gets parameter of an effect by its name. + + :param effect: Effect object + :param name: Name of the parameter + :return: The effect parameter object, or *NULL* if not found + +--------------------- + +.. function:: bool gs_effect_loop(gs_effect_t *effect, const char *name) + + Helper function that automatically begins techniques/passes. + + :param effect: Effect object + :param name: Name of the technique to execute + :return: *true* to draw, *false* when complete + + Here is an example of how this function is typically used: + +.. code:: cpp + + for (gs_effect_loop(effect, "my_technique")) { + /* perform drawing here */ + [...] + } + +--------------------- + +.. function:: gs_eparam_t *gs_effect_get_viewproj_matrix(const gs_effect_t *effect) + + Gets the view/projection matrix parameter ("viewproj") of the effect. + + :param effect: Effect object + :return: The view/projection matrix parameter of the effect + +--------------------- + +.. function:: gs_eparam_t *gs_effect_get_world_matrix(const gs_effect_t *effect) + + Gets the world matrix parameter ("world") of the effect. + + :param effect: Effect object + :return: The world matrix parameter of the effect + +--------------------- + +.. function:: void gs_effect_get_param_info(const gs_eparam_t *param, struct gs_effect_param_info *info) + + Gets information about an effect parameter. + + :param param: Effect parameter + :param info: Pointer to receive the data + + Relevant data types used with this function: + +.. code:: cpp + + enum gs_shader_param_type { + GS_SHADER_PARAM_UNKNOWN, + GS_SHADER_PARAM_BOOL, + GS_SHADER_PARAM_FLOAT, + GS_SHADER_PARAM_INT, + GS_SHADER_PARAM_STRING, + GS_SHADER_PARAM_VEC2, + GS_SHADER_PARAM_VEC3, + GS_SHADER_PARAM_VEC4, + GS_SHADER_PARAM_INT2, + GS_SHADER_PARAM_INT3, + GS_SHADER_PARAM_INT4, + GS_SHADER_PARAM_MATRIX4X4, + GS_SHADER_PARAM_TEXTURE, + }; + + struct gs_effect_param_info { + const char *name; + enum gs_shader_param_type type; + } + +--------------------- + +.. function:: void gs_effect_set_bool(gs_eparam_t *param, bool val) + + Sets a boolean parameter. + + :param param: Effect parameter + :param val: Boolean value + +--------------------- + +.. function:: void gs_effect_set_float(gs_eparam_t *param, float val) + + Sets a floating point parameter. + + :param param: Effect parameter + :param val: Floating point value + +--------------------- + +.. function:: void gs_effect_set_int(gs_eparam_t *param, int val) + + Sets a integer parameter. + + :param param: Effect parameter + :param val: Integer value + +--------------------- + +.. function:: void gs_effect_set_matrix4(gs_eparam_t *param, const struct matrix4 *val) + + Sets a matrix parameter. + + :param param: Effect parameter + :param val: Matrix + +--------------------- + +.. function:: void gs_effect_set_vec2(gs_eparam_t *param, const struct vec2 *val) + + Sets a 2-component vector parameter. + + :param param: Effect parameter + :param val: Vector + +--------------------- + +.. function:: void gs_effect_set_vec3(gs_eparam_t *param, const struct vec3 *val) + + Sets a 3-component vector parameter. + + :param param: Effect parameter + :param val: Vector + +--------------------- + +.. function:: void gs_effect_set_vec4(gs_eparam_t *param, const struct vec4 *val) + + Sets a 4-component vector parameter. + + :param param: Effect parameter + :param val: Vector + +--------------------- + +.. function:: void gs_effect_set_texture(gs_eparam_t *param, gs_texture_t *val) + + Sets a texture parameter. + + :param param: Effect parameter + :param val: Texture + +--------------------- + +.. function:: void gs_effect_set_val(gs_eparam_t *param, const void *val, size_t size) + + Sets a parameter with data manually. + + :param param: Effect parameter + :param val: Pointer to data + :param size: Size of data + +--------------------- + +.. function:: void gs_effect_set_default(gs_eparam_t *param) + + Sets the parameter to its default value + + :param: Effect parameter + +--------------------- + +.. function:: void gs_effect_set_next_sampler(gs_eparam_t *param, gs_samplerstate_t *sampler) + + Manually changes the sampler for an effect parameter the next time + it's used. + + :param param: Effect parameter + :param sampler: Sampler state object diff --git a/docs/sphinx/reference-libobs-graphics-graphics.rst b/docs/sphinx/reference-libobs-graphics-graphics.rst new file mode 100644 index 000000000..d35874461 --- /dev/null +++ b/docs/sphinx/reference-libobs-graphics-graphics.rst @@ -0,0 +1,1459 @@ +Core Graphics API +================= + +.. code:: cpp + + #include + + +Graphics Enumerations +--------------------- + +.. type:: enum gs_draw_mode + + Draw mode. Can be one of the following values: + + - GS_POINTS - Draws points + - GS_LINES - Draws individual lines + - GS_LINESTRIP - Draws a line strip + - GS_TRIS - Draws individual triangles + - GS_TRISTRIP - Draws a triangle strip + +.. type:: enum gs_color_format + + Color format. Can be one of the following values: + + - GS_UNKNOWN - Unknown format + - GS_A8 - 8 bit alpha channel only + - GS_R8 - 8 bit red channel only + - GS_RGBA - RGBA, 8 bits per channel + - GS_BGRX - BGRX, 8 bits per channel + - GS_BGRA - BGRA, 8 bits per channel + - GS_R10G10B10A2 - RGBA, 10 bits per channel except alpha, which is 2 + bits + - GS_RGBA16 - RGBA, 16 bits per channel + - GS_R16 - 16 bit red channel only + - GS_RGBA16F - RGBA, 16 bit floating point per channel + - GS_RGBA32F - RGBA, 32 bit floating point per channel + - GS_RG16F - 16 bit floating point red and green channels only + - GS_RG32F - 32 bit floating point red and green channels only + - GS_R16F - 16 bit floating point red channel only + - GS_R32F - 32 bit floating point red channel only + - GS_DXT1 - Compressed DXT1 + - GS_DXT3 - Compressed DXT3 + - GS_DXT5 - Compressed DXT5 + +.. type:: enum gs_zstencil_format + + Z-Stencil buffer format. Can be one of the following values: + + - GS_ZS_NONE - No Z-stencil buffer + - GS_Z16 - 16 bit Z buffer + - GS_Z24_S8 - 24 bit Z buffer, 8 bit stencil + - GS_Z32F - 32 bit floating point Z buffer + - GS_Z32F_S8X24 - 32 bit floating point Z buffer, 8 bit stencil + +.. type:: enum gs_index_type + + Index buffer type. Can be one of the following values: + + - GS_UNSIGNED_SHORT - 16 bit index + - GS_UNSIGNED_LONG - 32 bit index + +.. type:: enum gs_cull_mode + + Cull mode. Can be one of the following values: + + - GS_BACK - Cull back faces + - GS_FRONT - Cull front faces + - GS_NEITHER - Cull neither + +.. type:: enum gs_blend_type + + Blend type. Can be one of the following values: + + - GS_BLEND_ZERO + - GS_BLEND_ONE + - GS_BLEND_SRCCOLOR + - GS_BLEND_INVSRCCOLOR + - GS_BLEND_SRCALPHA + - GS_BLEND_INVSRCALPHA + - GS_BLEND_DSTCOLOR + - GS_BLEND_INVDSTCOLOR + - GS_BLEND_DSTALPHA + - GS_BLEND_INVDSTALPHA + - GS_BLEND_SRCALPHASAT + +.. type:: enum gs_depth_test + + Depth test type. Can be one of the following values: + + - GS_NEVER + - GS_LESS + - GS_LEQUAL + - GS_EQUAL + - GS_GEQUAL + - GS_GREATER + - GS_NOTEQUAL + - GS_ALWAYS + +.. type:: enum gs_stencil_side + + Stencil side. Can be one of the following values: + + - GS_STENCIL_FRONT=1 + - GS_STENCIL_BACK + - GS_STENCIL_BOTH + +.. type:: enum gs_stencil_op_type + + Stencil operation type. Can be one of the following values: + + - GS_KEEP + - GS_ZERO + - GS_REPLACE + - GS_INCR + - GS_DECR + - GS_INVERT + +.. type:: enum gs_cube_sides + + Cubemap side. Can be one of the following values: + + - GS_POSITIVE_X + - GS_NEGATIVE_X + - GS_POSITIVE_Y + - GS_NEGATIVE_Y + - GS_POSITIVE_Z + - GS_NEGATIVE_Z + +.. type:: enum gs_sample_filter + + Sample filter type. Can be one of the following values: + + - GS_FILTER_POINT + - GS_FILTER_LINEAR + - GS_FILTER_ANISOTROPIC + - GS_FILTER_MIN_MAG_POINT_MIP_LINEAR + - GS_FILTER_MIN_POINT_MAG_LINEAR_MIP_POINT + - GS_FILTER_MIN_POINT_MAG_MIP_LINEAR + - GS_FILTER_MIN_LINEAR_MAG_MIP_POINT + - GS_FILTER_MIN_LINEAR_MAG_POINT_MIP_LINEAR + - GS_FILTER_MIN_MAG_LINEAR_MIP_POINT + +.. type:: enum gs_address_mode + + Address mode. Can be one of the following values: + + - GS_ADDRESS_CLAMP + - GS_ADDRESS_WRAP + - GS_ADDRESS_MIRROR + - GS_ADDRESS_BORDER + - GS_ADDRESS_MIRRORONCE + +.. type:: enum gs_texture_type + + Texture type. Can be one of the following values: + + - GS_TEXTURE_2D + - GS_TEXTURE_3D + - GS_TEXTURE_CUBE + + +Graphics Structures +------------------- + +.. type:: struct gs_monitor_info +.. member:: int gs_monitor_info.rotation_degrees +.. member:: long gs_monitor_info.x +.. member:: long gs_monitor_info.y +.. member:: long gs_monitor_info.cx +.. member:: long gs_monitor_info.cy + +--------------------- + +.. type:: struct gs_tvertarray +.. member:: size_t gs_tvertarray.width +.. member:: void *gs_tvertarray.array + +--------------------- + +.. type:: struct gs_vb_data +.. member:: size_t gs_vb_data.num +.. member:: struct vec3 *gs_vb_data.points +.. member:: struct vec3 *gs_vb_data.normals +.. member:: struct vec3 *gs_vb_data.tangents +.. member:: uint32_t *gs_vb_data.colors +.. member:: size_t gs_vb_data.num_tex +.. member:: struct gs_tvertarray *gs_vb_data.tvarray + +--------------------- + +.. type:: struct gs_sampler_info +.. member:: enum gs_sample_filter gs_sampler_info.filter +.. member:: enum gs_address_mode gs_sampler_info.address_u +.. member:: enum gs_address_mode gs_sampler_info.address_v +.. member:: enum gs_address_mode gs_sampler_info.address_w +.. member:: int gs_sampler_info.max_anisotropy +.. member:: uint32_t gs_sampler_info.border_color + +--------------------- + +.. type:: struct gs_display_mode +.. member:: uint32_t gs_display_mode.width +.. member:: uint32_t gs_display_mode.height +.. member:: uint32_t gs_display_mode.bits +.. member:: uint32_t gs_display_mode.freq + +--------------------- + +.. type:: struct gs_rect +.. member:: int gs_rect.x +.. member:: int gs_rect.y +.. member:: int gs_rect.cx +.. member:: int gs_rect.cy + +--------------------- + +.. type:: struct gs_window + + A window structure. This structure is used with a native widget. + +.. member:: void *gs_window.hwnd + + (Windows only) an HWND widget. + +.. member:: id gs_window.view + + (Mac only) A view ID. + +.. member:: uint32_t gs_window.id + void* gs_window.display + + (Linux only) Window ID and display + +--------------------- + +.. type:: struct gs_init_data + + Swap chain initialization data. + +.. member:: struct gs_window gs_init_data.window +.. member:: uint32_t gs_init_data.cx +.. member:: uint32_t gs_init_data.cy +.. member:: uint32_t gs_init_data.num_backbuffers +.. member:: enum gs_color_format gs_init_data.format +.. member:: enum gs_zstencil_format gs_init_data.zsformat +.. member:: uint32_t gs_init_data.adapter + +--------------------- + + +Initialization Functions +------------------------ + +.. function:: void gs_enum_adapters(bool (*callback)(void *param, const char *name, uint32_t id), void *param) + + Enumerates adapters (this really only applies on windows). + + :param callback: Enumeration callback + :param param: Private data passed to the callback + +--------------------- + +.. function:: int gs_create(graphics_t **graphics, const char *module, uint32_t adapter) + + Creates a graphics context + + :param graphics: Pointer to receive the graphics context + :param module: Module name + :param adapter: Adapter index + :return: Can return one of the following values: + + - GS_SUCCESS + - GS_ERROR_FAIL + - GS_ERROR_MODULE_NOT_FOUND + - GS_ERROR_NOT_SUPPORTED + +--------------------- + +.. function:: void gs_destroy(graphics_t *graphics) + + Destroys a graphics context + + :param graphics: Graphics context + +--------------------- + +.. function:: void gs_enter_context(graphics_t *graphics) + + Enters and locks the graphics context + + :param graphics: Graphics context + +--------------------- + +.. function:: void gs_leave_context(void) + + Leaves and unlocks the graphics context + + :param graphics: Graphics context + +--------------------- + +.. function:: graphics_t *gs_get_context(void) + + :return: The currently locked graphics context for this thread + +--------------------- + + +Matrix Stack Functions +---------------------- + +.. function:: void gs_matrix_push(void) + + Pushes the matrix stack and duplicates the current matrix. + +--------------------- + +.. function:: void gs_matrix_pop(void) + + Pops the current matrix from the matrix stack. + +--------------------- + +.. function:: void gs_matrix_identity(void) + + Sets the current matrix to an identity matrix. + +--------------------- + +.. function:: void gs_matrix_transpose(void) + + Transposes the current matrix. + +--------------------- + +.. function:: void gs_matrix_set(const struct matrix4 *matrix) + + Sets the current matrix. + + :param matrix: The matrix to set + +--------------------- + +.. function:: void gs_matrix_get(struct matrix4 *dst) + + Gets the current matrix + + :param dst: Destination matrix + +--------------------- + +.. function:: void gs_matrix_mul(const struct matrix4 *matrix) + + Multiplies the current matrix + + :param matrix: Matrix to multiply the current stack matrix with + +--------------------- + +.. function:: void gs_matrix_rotquat(const struct quat *rot) + + Multiplies the current matrix with a quaternion + + :param rot: Quaternion to multiple the current matrix stack with + +--------------------- + +.. function:: void gs_matrix_rotaa(const struct axisang *rot) + void gs_matrix_rotaa4f(float x, float y, float z, float angle) + + Multiplies the current matrix with an axis angle + + :param rot: Axis angle to multiple the current matrix stack with + +--------------------- + +.. function:: void gs_matrix_translate(const struct vec3 *pos) + void gs_matrix_translate3f(float x, float y, float z) + + Translates the current matrix + + :param pos: Vector to translate the current matrix stack with + +--------------------- + +.. function:: void gs_matrix_scale(const struct vec3 *scale) + void gs_matrix_scale3f(float x, float y, float z) + + Scales the current matrix + + :param scale: Scale value to scale the current matrix stack with + +--------------------- + + +Draw Functions +-------------- + +.. function:: gs_effect_t *gs_get_effect(void) + + :return: The currently active effect, or *NULL* if none active + +--------------------- + +.. function:: void gs_draw_sprite(gs_texture_t *tex, uint32_t flip, uint32_t width, uint32_t height) + + Draws a 2D sprite. Sets the "image" parameter of the current effect + to the texture and renders a quad. + + If width or height is 0, the width or height of the texture will be + used. The flip value specifies whether the texture should be flipped + on the U or V axis with GS_FLIP_U and GS_FLIP_V. + + :param tex: Texture to draw + :param flip: Can be 0 or a bitwise-OR combination of one of the + following values: + + - GS_FLIP_U - Flips the texture horizontally + - GS_FLIP_V - Flips the texture vertically + + :param width: Width + :param height: Height + +--------------------- + +.. function:: void gs_draw_sprite_subregion(gs_texture_t *tex, uint32_t flip, uint32_t x, uint32_t y, uint32_t cx, uint32_t cy) + + Draws a subregion of a 2D sprite. Sets the "image" parameter of the + current effect to the texture and renders a quad. + + :param tex: Texture to draw + :param flip: Can be 0 or a bitwise-OR combination of one of the + following values: + + - GS_FLIP_U - Flips the texture horizontally + - GS_FLIP_V - Flips the texture vertically + + :param x: X value within subregion + :param y: Y value within subregion + :param cx: CX value of subregion + :param cy: CY value of subregion + +--------------------- + +.. function:: void gs_reset_viewport(void) + + Sets the viewport to current swap chain size + +--------------------- + +.. function:: void gs_set_2d_mode(void) + + Sets the projection matrix to a default screen-sized orthographic + mode + +--------------------- + +.. function:: void gs_set_3d_mode(double fovy, double znear, double zfar) + + Sets the projection matrix to a default screen-sized perspective + mode + + :param fovy: Field of view (in degrees) + :param znear: Near plane + :param zfar: Far plane + +--------------------- + +.. function:: void gs_viewport_push(void) + + Pushes/stores the current viewport + +--------------------- + +.. function:: void gs_viewport_pop(void) + + Pops/recalls the last pushed viewport + +--------------------- + +.. function:: void gs_perspective(float fovy, float aspect, float znear, float zfar) + + Sets the projection matrix to a perspective mode + + :param fovy: Field of view (in degrees) + :param aspect: Aspect ratio + :param znear: Near plane + :param zfar: Far plane + +--------------------- + +.. function:: void gs_blend_state_push(void) + + Pushes/stores the current blend state + +--------------------- + +.. function:: void gs_blend_state_pop(void) + + Pops/restores the last blend state + +--------------------- + +.. function:: void gs_reset_blend_state(void) + + Sets the blend state to the default value: source alpha and invert + source alpha. + +--------------------- + + +Swap Chains +----------- + +.. function:: gs_swapchain_t *gs_swapchain_create(const struct gs_init_data *data) + + Creates a swap chain (display view on a native widget) + + :param data: Swap chain initialization data + :return: New swap chain object, or *NULL* if failed + +--------------------- + +.. function:: void gs_swapchain_destroy(gs_swapchain_t *swapchain) + + Destroys a swap chain + +--------------------- + +.. function:: void gs_resize(uint32_t cx, uint32_t cy) + + Resizes the currently active swap chain + + :param cx: New width + :param cy: New height + +--------------------- + +.. function:: void gs_get_size(uint32_t *cx, uint32_t *cy) + + Gets the size of the currently active swap chain + + :param cx: Pointer to receive width + :param cy: Pointer to receive height + +--------------------- + +.. function:: uint32_t gs_get_width(void) + + Gets the width of the currently active swap chain + +--------------------- + +.. function:: uint32_t gs_get_height(void) + + Gets the height of the currently active swap chain + +--------------------- + + +Resource Loading +---------------- + +.. function:: void gs_load_vertexbuffer(gs_vertbuffer_t *vertbuffer) + + Loads a vertex buffer + + :param vertbuffer: Vertex buffer to load, or NULL to unload + +--------------------- + +.. function:: void gs_load_indexbuffer(gs_indexbuffer_t *indexbuffer) + + Loads a index buffer + + :param indexbuffer: Index buffer to load, or NULL to unload + +--------------------- + +.. function:: void gs_load_texture(gs_texture_t *tex, int unit) + + Loads a texture (this is usually not called manually) + + :param tex: Texture to load, or NULL to unload + :param unit: Texture unit to load texture for + +--------------------- + +.. function:: void gs_load_samplerstate(gs_samplerstate_t *samplerstate, int unit) + + Loads a sampler state (this is usually not called manually) + + :param samplerstate: Sampler state to load, or NULL to unload + :param unit: Texture unit to load sampler state for + +--------------------- + +.. function:: void gs_load_swapchain(gs_swapchain_t *swapchain) + + Loads a swapchain + + :param swapchain: Swap chain to load, or NULL to unload + +--------------------- + + +Draw Functions +-------------- + +.. function:: gs_texture_t *gs_get_render_target(void) + + :return: The currently active render target + +--------------------- + +.. function:: gs_zstencil_t *gs_get_zstencil_target(void) + + :return: The currently active Z-stencil target + +--------------------- + +.. function:: void gs_set_render_target(gs_texture_t *tex, gs_zstencil_t *zstencil) + + Sets the active render target + + :param tex: Texture to set as the active render target + :param zstencil: Z-stencil to use as the active render target + +--------------------- + +.. function:: void gs_set_cube_render_target(gs_texture_t *cubetex, int side, gs_zstencil_t *zstencil) + + Sets a cubemap side as the active render target + + :param cubetex: Cubemap + :param side: Cubemap side + :param zstencil: Z-stencil buffer, or *NULL* if none + +--------------------- + +.. function:: void gs_copy_texture(gs_texture_t *dst, gs_texture_t *src) + + Copies a texture + + :param dst: Destination texture + :param src: Source texture + +--------------------- + +.. function:: void gs_stage_texture(gs_stagesurf_t *dst, gs_texture_t *src) + + Copies a texture to a staging surface and copies it to RAM. Ideally + best to give this a frame to process to prevent stalling. + + :param dst: Staging surface + :param src: Texture to stage + +--------------------- + +.. function:: void gs_begin_scene(void) + void gs_end_scene(void) + + Begins/ends a scene (this is automatically called by libobs, there's + no need to call this manually). + +--------------------- + +.. function:: void gs_draw(enum gs_draw_mode draw_mode, uint32_t start_vert, uint32_t num_verts) + + Draws a primitive or set of primitives. + + :param draw_mode: The primitive draw mode to use + :param start_vert: Starting vertex index + :param num_verts: Number of vertices + +--------------------- + +.. function:: void gs_clear(uint32_t clear_flags, const struct vec4 *color, float depth, uint8_t stencil) + + Clears color/depth/stencil buffers. + + :param clear_flags: Flags to clear with. Can be one of the following + values: + + - GS_CLEAR_COLOR - Clears color buffer + - GS_CLEAR_DEPTH - Clears depth buffer + - GS_CLEAR_STENCIL - Clears stencil buffer + + :param color: Color value to clear the color buffer with + :param depth: Depth value to clear the depth buffer with + :param stencil: Stencil value to clear the stencil buffer with + +--------------------- + +.. function:: void gs_present(void) + + Displays what was rendered on to the current render target + +--------------------- + +.. function:: void gs_flush(void) + + Flushes GPU calls + +--------------------- + +.. function:: void gs_set_cull_mode(enum gs_cull_mode mode) + + Sets the current cull mode. + + :param mode: Cull mode + +--------------------- + +.. function:: enum gs_cull_mode gs_get_cull_mode(void) + + :return: The current cull mode + +--------------------- + +.. function:: void gs_enable_blending(bool enable) + + Enables/disables blending + + :param enable: *true* to enable, *false* to disable + +--------------------- + +.. function:: void gs_enable_depth_test(bool enable) + + Enables/disables depth testing + + :param enable: *true* to enable, *false* to disable + +--------------------- + +.. function:: void gs_enable_stencil_test(bool enable) + + Enables/disables stencil testing + + :param enable: *true* to enable, *false* to disable + +--------------------- + +.. function:: void gs_enable_stencil_write(bool enable) + + Enables/disables stencil writing + + :param enable: *true* to enable, *false* to disable + +--------------------- + +.. function:: void gs_enable_color(bool red, bool green, bool blue, bool alpha) + + Enables/disables specific color channels + + :param red: *true* to enable red channel, *false* to disable + :param green: *true* to enable green channel, *false* to disable + :param blue: *true* to enable blue channel, *false* to disable + :param alpha: *true* to enable alpha channel, *false* to disable + +--------------------- + +.. function:: void gs_blend_function(enum gs_blend_type src, enum gs_blend_type dest) + + Sets the blend function + + :param src: Blend type for the source + :param dest: Blend type for the destination + +--------------------- + +.. function:: void gs_blend_function_separate(enum gs_blend_type src_c, enum gs_blend_type dest_c, enum gs_blend_type src_a, enum gs_blend_type dest_a) + + Sets the blend function for RGB and alpha separately + + :param src_c: Blend type for the source RGB + :param dest_c: Blend type for the destination RGB + :param src_a: Blend type for the source alpha + :param dest_a: Blend type for the destination alpha + +--------------------- + +.. function:: void gs_depth_function(enum gs_depth_test test) + + Sets the depth function + + :param test: Sets the depth test type + +--------------------- + +.. function:: void gs_stencil_function(enum gs_stencil_side side, enum gs_depth_test test) + + Sets the stencil function + + :param side: Stencil side + :param test: Depth test + +--------------------- + +.. function:: void gs_stencil_op(enum gs_stencil_side side, enum gs_stencil_op_type fail, enum gs_stencil_op_type zfail, enum gs_stencil_op_type zpass) + + Sets the stencil operation + + :param side: Stencil side + :param fail: Operation to perform on stencil test failure + :param zfail: Operation to perform on depth test failure + :param zpass: Operation to perform on depth test success + +--------------------- + +.. function:: void gs_set_viewport(int x, int y, int width, int height) + + Sets the current viewport + + :param x: X position relative to upper left + :param y: Y position relative to upper left + :param width: Width of the viewport + :param height: Height of the viewport + +--------------------- + +.. function:: void gs_get_viewport(struct gs_rect *rect) + + Gets the current viewport + + :param rect: Pointer to recieve viewport rectangle + +--------------------- + +.. function:: void gs_set_scissor_rect(const struct gs_rect *rect) + + Sets or clears the current scissor rectangle + + :rect: Scissor rectangle, or *NULL* to clear + +--------------------- + +.. function:: void gs_ortho(float left, float right, float top, float bottom, float znear, float zfar) + + Sets the projection matrix to an orthographic matrix + +--------------------- + +.. function:: void gs_frustum(float left, float right, float top, float bottom, float znear, float zfar) + + Sets the projection matrix to a frustum matrix + +--------------------- + +.. function:: void gs_projection_push(void) + + Pushes/stores the current projection matrix + +--------------------- + +.. function:: void gs_projection_pop(void) + + Pops/restores the last projection matrix pushed + +--------------------- + + +Texture Functions +----------------- + +.. function:: gs_texture_t *gs_texture_create(uint32_t width, uint32_t height, enum gs_color_format color_format, uint32_t levels, const uint8_t **data, uint32_t flags) + + Creates a texture. + + :param width: Width + :param height: Height + :param color_format: Color format + :param levels: Number of total texture levels. Set to 1 if no + mip-mapping + :param data: Pointer to array of texture data pointers + :param flags: Can be 0 or a bitwise-OR combination of one or + more of the following value: + + - GS_BUILD_MIPMAPS - Automatically builds + mipmaps (Note: not fully tested) + - GS_DYNAMIC - Dynamic + - GS_RENDER_TARGET - Render target + + :return: A new texture object + +--------------------- + +.. function:: gs_texture_t *gs_texture_create_from_file(const char *file) + + Creates a texture from a file. Note that this isn't recommended for + animated gifs -- instead use the :ref:`image_file_helper`. + + :param file: Image file to open + +--------------------- + +.. function:: void gs_texture_destroy(gs_texture_t *tex) + + Destroys a texture + + :param tex: Texture object + +--------------------- + +.. function:: uint32_t gs_texture_get_width(const gs_texture_t *tex) + + Gets the texture's width + + :param tex: Texture object + :return: The texture's width + +--------------------- + +.. function:: uint32_t gs_texture_get_height(const gs_texture_t *tex) + + Gets the texture's height + + :param tex: Texture object + :return: The texture's height + +--------------------- + +.. function:: enum gs_color_format gs_texture_get_color_format(const gs_texture_t *tex) + + Gets the texture's color format + + :param tex: Texture object + :return: The texture's color format + +--------------------- + +.. function:: bool gs_texture_map(gs_texture_t *tex, uint8_t **ptr, uint32_t *linesize) + + Maps a texture. + + :param tex: Texture object + :param ptr: Pointer to receive the pointer to the texture data + to write to + :param linesize: Pointer to receive the line size (pitch) of the + texture + +--------------------- + +.. function:: void gs_texture_unmap(gs_texture_t *tex) + + Unmaps a texture. + + :param tex: Texture object + +--------------------- + +.. function:: void gs_texture_set_image(gs_texture_t *tex, const uint8_t *data, uint32_t linesize, bool invert) + + Sets the image of a dynamic texture + + :param tex: Texture object + :param data: Data to set as the image + :param linesize: Line size (pitch) of the data + :param invert: *true* to invert vertically, *false* otherwise + +--------------------- + +.. function:: gs_texture_t *gs_texture_create_from_iosurface(void *iosurf) + + **Mac only:** Creates a texture from an IOSurface. + + :param iosurf: IOSurface object + +--------------------- + +.. function:: bool gs_texture_rebind_iosurface(gs_texture_t *texture, void *iosurf) + + **Mac only:** Rebinds a texture to another IOSurface + + :param texture: Texture object + :param iosuf: IOSurface object + +--------------------- + +.. function:: gs_texture_t *gs_texture_create_gdi(uint32_t width, uint32_t height) + + **Windows only:** Creates a GDI-interop texture + + :param width: Width + :param height: Height + +--------------------- + +.. function:: void *gs_texture_get_dc(gs_texture_t *gdi_tex) + + **Windows only:** Gets the HDC of a GDI-interop texture. Call + :c:func:`gs_texture_release_dc()` to release the HDC. + + :param gdi_tex: GDI-interop texture object + :return: HDC object + +--------------------- + +.. function:: void gs_texture_release_dc(gs_texture_t *gdi_tex) + + **Windows only:** Releases the HDC of the GDI-interop texture. + + :param gdi_tex: GDI-interop texture object + +--------------------- + +.. function:: gs_texture_t *gs_texture_open_shared(uint32_t handle) + + **Windows only:** Creates a texture from a shared texture handle. + + :param handle: Shared texture handle + :return: A texture object + +--------------------- + +.. function:: bool gs_gdi_texture_available(void) + + **Windows only:** Returns whether GDI-interop textures are available. + + :return: *true* if available, *false* otherwise + +--------------------- + +.. function:: bool gs_shared_texture_available(void) + + **Windows only:** Returns whether shared textures are available. + + :return: *true* if available, *false* otherwise + +--------------------- + + +Cube Texture Functions +---------------------- + +.. function:: gs_texture_t *gs_cubetexture_create(uint32_t size, enum gs_color_format color_format, uint32_t levels, const uint8_t **data, uint32_t flags) + + Creates a cubemap texture. + + :param size: Width/height/depth value + :param color_format: Color format + :param levels: Number of texture levels + :param data: Pointer to array of texture data pointers + :param flags: Can be 0 or a bitwise-OR combination of one or + more of the following value: + + - GS_BUILD_MIPMAPS - Automatically builds + mipmaps (Note: not fully tested) + - GS_DYNAMIC - Dynamic + - GS_RENDER_TARGET - Render target + + :return: A new cube texture object + +--------------------- + +.. function:: void gs_cubetexture_destroy(gs_texture_t *cubetex) + + Destroys a cube texture. + + :param cubetex: Cube texture object + +--------------------- + +.. function:: uint32_t gs_cubetexture_get_size(const gs_texture_t *cubetex) + + Get the width/height/depth value of a cube texture. + + :param cubetex: Cube texture object + :return: The width/height/depth value of the cube texture + +--------------------- + +.. function:: enum gs_color_format gs_cubetexture_get_color_format(const gs_texture_t *cubetex) + + Gets the color format of a cube texture. + + :param cubetex: Cube texture object + :return: The color format of the cube texture + +--------------------- + +.. function:: void gs_cubetexture_set_image(gs_texture_t *cubetex, uint32_t side, const void *data, uint32_t linesize, bool invert) + + Sets an image of a cube texture side. + + :param cubetex: Cube texture object + :param side: Side + :param data: Texture data to set + :param linesize: Line size (pitch) of the texture data + :param invert: *true* to invert texture data, *false* otherwise + +--------------------- + + +Staging Surface Functions +------------------------- + +Staging surfaces are used to efficiently copy textures from VRAM to RAM. + +.. function:: gs_stagesurf_t *gs_stagesurface_create(uint32_t width, uint32_t height, enum gs_color_format color_format) + + Creates a staging surface. + + :param width: Width + :param height: Height + :param color_format: Color format + :return: The staging surface object + +--------------------- + +.. function:: void gs_stagesurface_destroy(gs_stagesurf_t *stagesurf) + + Destroys a staging surface. + + :param stagesurf: Staging surface object + +--------------------- + +.. function:: uint32_t gs_stagesurface_get_width(const gs_stagesurf_t *stagesurf) + uint32_t gs_stagesurface_get_height(const gs_stagesurf_t *stagesurf) + + Gets the width/height of a staging surface object. + + :param stagesurf: Staging surface object + :return: Width/height of the staging surface + +--------------------- + +.. function:: enum gs_color_format gs_stagesurface_get_color_format(const gs_stagesurf_t *stagesurf) + + Gets the color format of a staging surface object. + + :param stagesurf: Staging surface object + :return: Color format of the staging surface + +--------------------- + +.. function:: bool gs_stagesurface_map(gs_stagesurf_t *stagesurf, uint8_t **data, uint32_t *linesize) + + Maps the staging surface texture (for reading). Call + :c:func:`gs_stagesurface_unmap()` to unmap when complete. + + :param stagesurf: Staging surface object + :param data: Pointer to receive texture data pointer + :param linesize: Pointer to receive line size (pitch) of the texture + data + :return: *true* if map successful, *false* otherwise + +--------------------- + +.. function:: void gs_stagesurface_unmap(gs_stagesurf_t *stagesurf) + + Unmaps a staging surface. + + :param stagesurf: Staging surface object + +--------------------- + + +Z-Stencil Functions +------------------- + +.. function:: gs_zstencil_t *gs_zstencil_create(uint32_t width, uint32_t height, enum gs_zstencil_format format) + + Creates a Z-stencil surface object. + + :param width: Width + :param height: Height + :param format: Format + :return: New Z-stencil surface object, or *NULL* if failed + +--------------------- + +.. function:: void gs_zstencil_destroy(gs_zstencil_t *zstencil) + + Destroys a Z-stencil buffer. + + :param zstencil: Z-stencil surface object + +--------------------- + + +Sampler State Functions +----------------------- + +.. function:: gs_samplerstate_t *gs_samplerstate_create(const struct gs_sampler_info *info) + + Creates a sampler state object. + + :param info: Sampler state information + :return: New sampler state object + +--------------------- + +.. function:: void gs_samplerstate_destroy(gs_samplerstate_t *samplerstate) + + Destroys a sampler state object. + + :param samplerstate: Sampler state object + +--------------------- + + +Vertex Buffer Functions +----------------------- + +.. function:: gs_vertbuffer_t *gs_vertexbuffer_create(struct gs_vb_data *data, uint32_t flags) + + Creates a vertex buffer. + + :param data: Vertex buffer data to create vertex buffer with. + Buffers in this structure should be allocated with + :c:func:`bmalloc()`, :c:func:`bzalloc()`, or + :c:func:`brealloc()`. Their ownership is passed to the + function, and they should not be destroyed by the + caller once passed + + :param flags: Creation flags. Can be 0 or a bitwise-OR combination + of any of the following values: + + - GS_DYNAMIC - Can be dynamically updated in real time. + - GS_DUP_BUFFER - Do not pass buffer ownership + + :return: A new vertex buffer object, or *NULL* if failed + +--------------------- + +.. function:: void gs_vertexbuffer_destroy(gs_vertbuffer_t *vertbuffer) + + Destroys a vertex buffer object. + + :param vertbuffer: Vertex buffer object + +--------------------- + +.. function:: void gs_vertexbuffer_flush(gs_vertbuffer_t *vertbuffer) + + Flushes a vertex buffer to its interval vertex data object. To + modify its internal vertex data, call + :c:func:`gs_vertexbuffer_get_data()`. + + Can only be used with dynamic vertex buffer objects. + + :param vertbuffer: Vertex buffer object + +--------------------- + +.. function:: void gs_vertexbuffer_flush_direct(gs_vertbuffer_t *vertbuffer, const struct gs_vb_data *data) + + Directly flushes a vertex buffer to the specified vertex buffer data. + . + + Can only be used with dynamic vertex buffer objects. + + :param vertbuffer: Vertex buffer object + :param data: Vertex buffer data to flush. Components that + don't need to be flushed can be left *NULL* + +--------------------- + +.. function:: struct gs_vb_data *gs_vertexbuffer_get_data(const gs_vertbuffer_t *vertbuffer) + + Gets the vertex buffer data associated with a vertex buffer object. + This data can be changed and vertex buffer can be updated with + :c:func:`gs_vertexbuffer_flush()`. + + Can only be used with dynamic vertex buffer objects. + + :param vertbuffer: Vertex buffer object + :return: Vertex buffer data structure + +--------------------- + + +Index Buffer Functions +---------------------- + +.. function:: gs_indexbuffer_t *gs_indexbuffer_create(enum gs_index_type type, void *indices, size_t num, uint32_t flags) + + Creates an index buffer. + + :param type: Index buffer type + :param indices: Index buffer data. This buffer must be allocated + with :c:func:`bmalloc()`, :c:func:`bzalloc()`, or + :c:func:`bralloc()`, and ownership of this buffer is + passed to the index buffer object. + :param num: Number of indices in the buffer + + :param flags: Creation flags. Can be 0 or a bitwise-OR combination + of any of the following values: + + - GS_DYNAMIC - Can be dynamically updated in real time. + - GS_DUP_BUFFER - Do not pass buffer ownership + + :return: A new index buffer object, or *NULL* if failed + +--------------------- + +.. function:: void gs_indexbuffer_destroy(gs_indexbuffer_t *indexbuffer) + + Destroys an index buffer object. + + :param indexbuffer: Index buffer object + +--------------------- + +.. function:: void gs_indexbuffer_flush(gs_indexbuffer_t *indexbuffer) + + Flushes a index buffer to its interval index data object. To modify + its internal index data, call :c:func:`gs_indexbuffer_get_data()`. + + Can only be used with dynamic index buffer objects. + + :param indexbuffer: Index buffer object + +--------------------- + +.. function:: void gs_indexbuffer_flush_direct(gs_indexbuffer_t *indexbuffer, const void *data) + + Flushes a index buffer to the specified index buffer data. + + Can only be used with dynamic index buffer objects. + + :param indexbuffer: Index buffer object + :param data: Index buffer data to flush + +--------------------- + +.. function:: void *gs_indexbuffer_get_data(const gs_indexbuffer_t *indexbuffer) + + Gets the index buffer data associated with a index buffer object. + This data can be changed and index buffer can be updated with + :c:func:`gs_indexbuffer_flush()`. + + Can only be used with dynamic index buffer objects. + + :param vertbuffer: Index buffer object + :return: Index buffer data pointer + +--------------------- + +.. function:: size_t gs_indexbuffer_get_num_indices(const gs_indexbuffer_t *indexbuffer) + + Gets the number of indices associated with this index buffer. + + :param indexbuffer: Index buffer object + :return: Number of indices the vertex buffer object has + +--------------------- + +.. function:: enum gs_index_type gs_indexbuffer_get_type(const gs_indexbuffer_t *indexbuffer) + + Gets the type of index buffer. + + :param indexbuffer: Index buffer object + :return: Index buffer type + +--------------------- + + +Display Duplicator (Windows Only) +--------------------------------- + +.. function:: gs_duplicator_t *gs_duplicator_create(int monitor_idx) + +--------------------- + +.. function:: void gs_duplicator_destroy(gs_duplicator_t *duplicator) + +--------------------- + +.. function:: bool gs_duplicator_update_frame(gs_duplicator_t *duplicator) + +--------------------- + +.. function:: gs_texture_t *gs_duplicator_get_texture(gs_duplicator_t *duplicator) + +--------------------- + +.. function:: bool gs_get_duplicator_monitor_info(int monitor_idx, struct gs_monitor_info *monitor_info) + +--------------------- + + +Render Helper Functions +----------------------- + +.. function:: void gs_render_start(bool b_new) + +--------------------- + +.. function:: void gs_render_stop(enum gs_draw_mode mode) + +--------------------- + +.. function:: gs_vertbuffer_t *gs_render_save(void) + +--------------------- + +.. function:: void gs_vertex2f(float x, float y) + +--------------------- + +.. function:: void gs_vertex3f(float x, float y, float z) + +--------------------- + +.. function:: void gs_normal3f(float x, float y, float z) + +--------------------- + +.. function:: void gs_color(uint32_t color) + +--------------------- + +.. function:: void gs_texcoord(float x, float y, int unit) + +--------------------- + +.. function:: void gs_vertex2v(const struct vec2 *v) + +--------------------- + +.. function:: void gs_vertex3v(const struct vec3 *v) + +--------------------- + +.. function:: void gs_normal3v(const struct vec3 *v) + +--------------------- + +.. function:: void gs_color4v(const struct vec4 *v) + +--------------------- + +.. function:: void gs_texcoord2v(const struct vec2 *v, int unit) + +--------------------- + + +Graphics Types +-------------- + +.. type:: typedef struct gs_duplicator gs_duplicator_t +.. type:: typedef struct gs_texture gs_texture_t +.. type:: typedef struct gs_stage_surface gs_stagesurf_t +.. type:: typedef struct gs_zstencil_buffer gs_zstencil_t +.. type:: typedef struct gs_vertex_buffer gs_vertbuffer_t +.. type:: typedef struct gs_index_buffer gs_indexbuffer_t +.. type:: typedef struct gs_sampler_state gs_samplerstate_t +.. type:: typedef struct gs_swap_chain gs_swapchain_t +.. type:: typedef struct gs_texture_render gs_texrender_t +.. type:: typedef struct gs_shader gs_shader_t +.. type:: typedef struct gs_shader_param gs_sparam_t +.. type:: typedef struct gs_device gs_device_t +.. type:: typedef struct graphics_subsystem graphics_t diff --git a/docs/sphinx/reference-libobs-graphics-image-file.rst b/docs/sphinx/reference-libobs-graphics-image-file.rst new file mode 100644 index 000000000..dd52db73f --- /dev/null +++ b/docs/sphinx/reference-libobs-graphics-image-file.rst @@ -0,0 +1,71 @@ +.. _image_file_helper: + +Image File Helper +================= + +Helper functions/type for easily loading/managing image files, including +animated gif files. + +.. code:: cpp + + #include + +.. type:: struct gs_image_file + + Image file structure + +.. type:: gs_texture_t *gs_image_file.texture + + Texture + +.. type:: typedef struct gs_image_file gs_image_file_t + + Image file type + +--------------------- + +.. function:: void gs_image_file_init(gs_image_file_t *image, const char *file) + + Loads an initializes an image file helper. Does not initialize the + texture; call :c:func:`gs_image_file_init_texture()` to initialize + the texture. + + :param image: Image file helper to initialize + :param file: Path to the image file to load + +--------------------- + +.. function:: void gs_image_file_free(gs_image_file_t *image) + + Frees an image file helper + + :param image: Image file helper + +--------------------- + +.. function:: void gs_image_file_init_texture(gs_image_file_t *image) + + Initializes the texture of an image file helper. This is separate + from :c:func:`gs_image_file_init()` because it allows deferring the + graphics initialization if needed. + + :param image: Image file helper + +--------------------- + +.. function:: bool gs_image_file_tick(gs_image_file_t *image, uint64_t elapsed_time_ns) + + Performs a tick operation on the image file helper (used primarily + for animated file). Does not update the texture until + :c:func:`gs_image_file_update_texture()` is called. + + :param image: Image file helper + :param elapsed_time_ns: Elapsed time in nanoseconds + +--------------------- + +.. function:: void gs_image_file_update_texture(gs_image_file_t *image) + + Updates the texture (used primarily for animated files) + + :param image: Image file helper diff --git a/docs/sphinx/reference-libobs-graphics-math.rst b/docs/sphinx/reference-libobs-graphics-math.rst new file mode 100644 index 000000000..c5cffe416 --- /dev/null +++ b/docs/sphinx/reference-libobs-graphics-math.rst @@ -0,0 +1,39 @@ +Extra Math Functions/Macros +=========================== + +.. code:: + + #include + +Helper functions/macros for graphics math. + +.. function:: RAD(val) + + Macro that converts a floating point degrees value to radians. + +.. function:: DEG(val) + + Macro that converts a floating point radians value to degrees. + +**LARGE_EPSILON** 1e-2f + + Large epsilon value. + +**EPSILON** 1e-4f + + Epsilon value. + +**TINY_EPSILON** 1e-5f + + Tiny Epsilon value. + +**M_INFINITE** 3.4e38f + + Infinite value + +--------------------- + +.. function:: float rand_float(int positive_only) + + Generates a random floating point value (from -1.0f..1.0f, or + 0.0f..1.0f if *positive_only* is set). diff --git a/docs/sphinx/reference-libobs-graphics-matrix4.rst b/docs/sphinx/reference-libobs-graphics-matrix4.rst new file mode 100644 index 000000000..6924cbc76 --- /dev/null +++ b/docs/sphinx/reference-libobs-graphics-matrix4.rst @@ -0,0 +1,151 @@ +Matrix +====== + +.. code:: cpp + + #include + +.. type:: struct matrix4 + + Matrix structure + +.. member:: struct vec4 matrix4.x + + X component vector + +.. member:: struct vec4 matrix4.y + + Y component vector + +.. member:: struct vec4 matrix4.z + + Z component vector + +.. member:: struct vec4 matrix4.w + + W component vector + +--------------------- + +.. function:: void matrix4_copy(struct matrix4 *dst, const struct matrix4 *m) + + Copies a matrix + + :param dst: Destination matrix + :param m: Matrix to copy + +--------------------- + +.. function:: void matrix4_identity(struct matrix4 *dst) + + Sets an identity matrix + + :param dst: Destination matrix + +--------------------- + +.. function:: void matrix4_from_quat(struct matrix4 *dst, const struct quat *q) + + Converts a quaternion to a matrix + + :param dst: Destination matrix + :param q: Quaternion to convert + +--------------------- + +.. function:: void matrix4_from_axisang(struct matrix4 *dst, const struct axisang *aa) + + Converts an axis angle to a matrix + + :param dst: Destination matrix + :param aa: Axis angle to convert + +--------------------- + +.. function:: void matrix4_mul(struct matrix4 *dst, const struct matrix4 *m1, const struct matrix4 *m2) + + Multiples two matrices + + :param dst: Destination matrix + :param m1: Matrix 1 + :param m2: Matrix 2 + +--------------------- + +.. function:: float matrix4_determinant(const struct matrix4 *m) + + Gets the determinant value of a matrix + + :param m: Matrix + :return: Determinant + +--------------------- + +.. function:: void matrix4_translate3v(struct matrix4 *dst, const struct matrix4 *m, const struct vec3 *v) + void matrix4_translate3f(struct matrix4 *dst, const struct matrix4 *m, float x, float y, float z) + + Translates the matrix by a 3-component vector + + :param dst: Destination matrix + :param m: Matrix to translate + :param v: Translation vector + +--------------------- + +.. function:: void matrix4_translate4v(struct matrix4 *dst, const struct matrix4 *m, const struct vec4 *v) + + Translates the matrix by a 4-component vector + + :param dst: Destination matrix + :param m: Matrix to translate + :param v: Translation vector + +--------------------- + +.. function:: void matrix4_rotate(struct matrix4 *dst, const struct matrix4 *m, const struct quat *q) + + Rotates a matrix by a quaternion + + :param dst: Destination matrix + :param m: Matrix to rotate + :param q: Rotation quaternion + +--------------------- + +.. function:: void matrix4_rotate_aa(struct matrix4 *dst, const struct matrix4 *m, const struct axisang *aa) + void matrix4_rotate_aa4f(struct matrix4 *dst, const struct matrix4 *m, float x, float y, float z, float rot) + + Rotates a matrix by an axis angle + + :param dst: Destination matrix + :param m: Matrix to rotate + :param aa: Rotation anxis angle + +--------------------- + +.. function:: void matrix4_scale(struct matrix4 *dst, const struct matrix4 *m, const struct vec3 *v) + void matrix4_scale3f(struct matrix4 *dst, const struct matrix4 *m, float x, float y, float z) + + Scales each matrix component by the components of a 3-component vector + + :param dst: Destination matrix + :param m: Matrix to scale + :param v: Scale vector + +--------------------- + +.. function:: bool matrix4_inv(struct matrix4 *dst, const struct matrix4 *m) + + Inverts a matrix + + :param dst: Destination matrix + :param m: Matrix to invert + +--------------------- + +.. function:: void matrix4_transpose(struct matrix4 *dst, const struct matrix4 *m) + + Transposes a matrix + + :param dst: Destination matrix + :param m: Matrix to transpose diff --git a/docs/sphinx/reference-libobs-graphics-quat.rst b/docs/sphinx/reference-libobs-graphics-quat.rst new file mode 100644 index 000000000..fbaa4f41a --- /dev/null +++ b/docs/sphinx/reference-libobs-graphics-quat.rst @@ -0,0 +1,228 @@ +Quaternion +========== + +.. code:: cpp + + #include + +.. type:: struct quat + + Two component quaternion structure. + +.. member:: float quat.x + + X component + +.. member:: float quat.y + + Y component + +.. member:: float quat.z + + Z component + +.. member:: float quat.w + + W component + +.. member:: float quat.ptr[4] + + Unioned array of all components + +--------------------- + +.. function:: void quat_identity(struct quat *dst) + + Sets a quaternion to {0.0f, 0.0f, 0.0f, 1.0f}. + + :param dst: Destination + +--------------------- + +.. function:: void quat_set(struct quat *dst, float x, float y) + + Sets the individual components of a quaternion. + + :param dst: Destination + :param x: X component + :param y: Y component + :param y: Z component + :param w: W component + +--------------------- + +.. function:: void quat_copy(struct quat *dst, const struct quat *v) + + Copies a quaternion + + :param dst: Destination + :param v: Quaternion to copy + +--------------------- + +.. function:: void quat_add(struct quat *dst, const struct quat *v1, const struct quat *v2) + + Adds two quaternions + + :param dst: Destination + :param v1: Quaternion 1 + :param v2: Quaternion 2 + +--------------------- + +.. function:: void quat_sub(struct quat *dst, const struct quat *v1, const struct quat *v2) + + Subtracts two quaternions + + :param dst: Destination + :param v1: Quaternion being subtracted from + :param v2: Quaternion being subtracted + +--------------------- + +.. function:: void quat_mul(struct quat *dst, const struct quat *v1, const struct quat *v2) + + Multiplies two quaternions + + :param dst: Destination + :param v1: Quaternion 1 + :param v2: Quaternion 2 + +--------------------- + +.. function:: void quat_addf(struct quat *dst, const struct quat *v, float f) + + Adds a floating point to all components + + :param dst: Destination + :param dst: Quaternion + :param f: Floating point + +--------------------- + +.. function:: void quat_subf(struct quat *dst, const struct quat *v, float f) + + Subtracts a floating point from all components + + :param dst: Destination + :param v: Quaternion being subtracted from + :param f: Floating point being subtracted + +--------------------- + +.. function:: void quat_mulf(struct quat *dst, const struct quat *v, float f) + + Multiplies a floating point with all components + + :param dst: Destination + :param dst: Quaternion + :param f: Floating point + +--------------------- + +.. function:: void quat_inv(struct quat *dst, const struct quat *v) + + Inverts a quaternion + + :param dst: Destination + :param v: Quaternion to invert + +--------------------- + +.. function:: float quat_dot(const struct quat *v1, const struct quat *v2) + + Performs a dot product between two quaternions + + :param v1: Quaternion 1 + :param v2: Quaternion 2 + :return: Result of the dot product + +--------------------- + +.. function:: float quat_len(const struct quat *v) + + Gets the length of a quaternion + + :param v: Quaternion + :return: The quaternion's length + +--------------------- + +.. function:: float quat_dist(const struct quat *v1, const struct quat *v2) + + Gets the distance between two quaternions + + :param v1: Quaternion 1 + :param v2: Quaternion 2 + :return: Distance between the two quaternions + +--------------------- + +.. function:: void quat_from_axisang(struct quat *dst, const struct axisang *aa) + + Converts an axis angle to a quaternion + + :param dst: Destination quaternion + :param aa: Axis angle + +--------------------- + +.. function:: void quat_from_matrix4(struct quat *dst, const struct matrix4 *m) + + Converts the rotational properties of a matrix to a quaternion + + :param dst: Destination quaternion + :param m: Matrix to convert + +--------------------- + +.. function:: void quat_get_dir(struct vec3 *dst, const struct quat *q) + + Converts a quaternion to a directional vector + + :param dst: Destination 3-component vector + :param q: Quaternion + +--------------------- + +.. function:: void quat_set_look_dir(struct quat *dst, const struct vec3 *dir) + + Creates a quaternion from a specific "look" direction + + :param dst: Destination quaternion + :param dir: 3-component vector representing the look direction + +--------------------- + +.. function:: void quat_interpolate(struct quat *dst, const struct quat *q1, const struct quat *q2, float t) + + Linearly interpolates two quaternions + + :param dst: Destination quaternion + :param q1: Quaternion 1 + :param q2: Quaternion 2 + :param t: Time value (0.0f..1.0f) + +--------------------- + +.. function:: void quat_get_tangent(struct quat *dst, const struct quat *prev, const struct quat *q, const struct quat *next) + + Gets a tangent value for the center of three rotational values + + :param dst: Destination quaternion + :param prev: Previous rotation + :param q: Rotation to get tangent for + :param next: Next rotation + +--------------------- + +.. function:: void quat_interpolate_cubic(struct quat *dst, const struct quat *q1, const struct quat *q2, const struct quat *m1, const struct quat *m2, float t) + + Performs cubic interpolation between two quaternions + + :param dst: Destination quaternion + :param q1: Quaternion 1 + :param q2: Quaternion 2 + :param m1: Tangent 1 + :param m2: Tangent 2 + :param t: Time value (0.0f..1.0f) diff --git a/docs/sphinx/reference-libobs-graphics-vec2.rst b/docs/sphinx/reference-libobs-graphics-vec2.rst new file mode 100644 index 000000000..41c7c8222 --- /dev/null +++ b/docs/sphinx/reference-libobs-graphics-vec2.rst @@ -0,0 +1,253 @@ +2-Component Vector +================== + +.. code:: cpp + + #include + +.. type:: struct vec2 + + Two component vector structure. + +.. member:: float vec2.x + + X component + +.. member:: float vec2.y + + Y component + +.. member:: float vec2.ptr[2] + + Unioned array of both components + +--------------------- + +.. function:: void vec2_zero(struct vec2 *dst) + + Zeroes a vector + + :param dst: Destination + +--------------------- + +.. function:: void vec2_set(struct vec2 *dst, float x, float y) + + Sets the individual components of a 2-component vector. + + :param dst: Destination + :param x: X component + :param y: Y component + +--------------------- + +.. function:: void vec2_copy(struct vec2 *dst, const struct vec2 *v) + + Copies a vector + + :param dst: Destination + :param v: Vector to copy + +--------------------- + +.. function:: void vec2_add(struct vec2 *dst, const struct vec2 *v1, const struct vec2 *v2) + + Adds two vectors + + :param dst: Destination + :param v1: Vector 1 + :param v2: Vector 2 + +--------------------- + +.. function:: void vec2_sub(struct vec2 *dst, const struct vec2 *v1, const struct vec2 *v2) + + Subtracts two vectors + + :param dst: Destination + :param v1: Vector being subtracted from + :param v2: Vector being subtracted + +--------------------- + +.. function:: void vec2_mul(struct vec2 *dst, const struct vec2 *v1, const struct vec2 *v2) + + Multiplies two vectors + + :param dst: Destination + :param v1: Vector 1 + :param v2: Vector 2 + +--------------------- + +.. function:: void vec2_div(struct vec2 *dst, const struct vec2 *v1, const struct vec2 *v2) + + Divides two vectors + + :param dst: Destination + :param v1: Dividend + :param v2: Divisor + +--------------------- + +.. function:: void vec2_addf(struct vec2 *dst, const struct vec2 *v, float f) + + Adds a floating point to all components + + :param dst: Destination + :param dst: Vector + :param f: Floating point + +--------------------- + +.. function:: void vec2_subf(struct vec2 *dst, const struct vec2 *v, float f) + + Subtracts a floating point from all components + + :param dst: Destination + :param v: Vector being subtracted from + :param f: Floating point being subtracted + +--------------------- + +.. function:: void vec2_mulf(struct vec2 *dst, const struct vec2 *v, float f) + + Multiplies a floating point with all components + + :param dst: Destination + :param dst: Vector + :param f: Floating point + +--------------------- + +.. function:: void vec2_divf(struct vec2 *dst, const struct vec2 *v, float f) + + Divides a floating point from all components + + :param dst: Destination + :param v: Vector (dividend) + :param f: Floating point (divisor) + +--------------------- + +.. function:: void vec2_neg(struct vec2 *dst, const struct vec2 *v) + + Negates a vector + + :param dst: Destination + :param v: Vector to negate + +--------------------- + +.. function:: float vec2_dot(const struct vec2 *v1, const struct vec2 *v2) + + Performs a dot product between two vectors + + :param v1: Vector 1 + :param v2: Vector 2 + :return: Result of the dot product + +--------------------- + +.. function:: float vec2_len(const struct vec2 *v) + + Gets the length of a vector + + :param v: Vector + :return: The vector's length + +--------------------- + +.. function:: float vec2_dist(const struct vec2 *v1, const struct vec2 *v2) + + Gets the distance between two vectors + + :param v1: Vector 1 + :param v2: Vector 2 + :return: Distance between the two vectors + +--------------------- + +.. function:: void vec2_minf(struct vec2 *dst, const struct vec2 *v, float val) + + Gets the minimum values between a vector's components and a floating point + + :param dst: Destination + :param v: Vector + :param val: Floating point + +--------------------- + +.. function:: void vec2_min(struct vec2 *dst, const struct vec2 *v, const struct vec2 *min_v) + + Gets the minimum values between two vectors + + :param dst: Destination + :param v: Vector 1 + :param min_v: Vector 2 + +--------------------- + +.. function:: void vec2_maxf(struct vec2 *dst, const struct vec2 *v, float val) + + Gets the maximum values between a vector's components and a floating point + + :param dst: Destination + :param v: Vector + :param val: Floating point + +--------------------- + +.. function:: void vec2_max(struct vec2 *dst, const struct vec2 *v, const struct vec2 *max_v) + + Gets the maximum values between two vectors + + :param dst: Destination + :param v: Vector 1 + :param max_v: Vector 2 + +--------------------- + +.. function:: void vec2_abs(struct vec2 *dst, const struct vec2 *v) + + Gets the absolute values of each component + + :param dst: Destination + :param v: Vector + +--------------------- + +.. function:: void vec2_floor(struct vec2 *dst, const struct vec2 *v) + + Gets the floor values of each component + + :param dst: Destination + :param v: Vector + +--------------------- + +.. function:: void vec2_ceil(struct vec2 *dst, const struct vec2 *v) + + Gets the ceiling values of each component + + :param dst: Destination + :param v: Vector + +--------------------- + +.. function:: int vec2_close(const struct vec2 *v1, const struct vec2 *v2, float epsilon) + + Compares two vectors + + :param v1: Vector 1 + :param v2: Vector 2 + :param epsilon: Maximum precision for comparison + +--------------------- + +.. function:: void vec2_norm(struct vec2 *dst, const struct vec2 *v) + + Normalizes a vector + + :param dst: Desination + :param v: Vector to normalize diff --git a/docs/sphinx/reference-libobs-graphics-vec3.rst b/docs/sphinx/reference-libobs-graphics-vec3.rst new file mode 100644 index 000000000..7a2e9387d --- /dev/null +++ b/docs/sphinx/reference-libobs-graphics-vec3.rst @@ -0,0 +1,306 @@ +3-Component Vector +================== + +.. code:: cpp + + #include + +.. type:: struct vec3 + + Two component vector structure. + +.. member:: float vec3.x + + X component + +.. member:: float vec3.y + + Y component + +.. member:: float vec3.z + + Z component + +.. member:: float vec3.ptr[3] + + Unioned array of all components + +--------------------- + +.. function:: void vec3_zero(struct vec3 *dst) + + Zeroes a vector + + :param dst: Destination + +--------------------- + +.. function:: void vec3_set(struct vec3 *dst, float x, float y) + + Sets the individual components of a 3-component vector. + + :param dst: Destination + :param x: X component + :param y: Y component + :param y: Z component + +--------------------- + +.. function:: void vec3_copy(struct vec3 *dst, const struct vec3 *v) + + Copies a vector + + :param dst: Destination + :param v: Vector to copy + +--------------------- + +.. function:: void vec3_from_vec4(struct vec3 *dst, const struct vec4 *v) + + Creates a 3-component vector from a 4-component vector + + :param dst: 3-component vector destination + :param v: 4-component vector + +--------------------- + +.. function:: void vec3_add(struct vec3 *dst, const struct vec3 *v1, const struct vec3 *v2) + + Adds two vectors + + :param dst: Destination + :param v1: Vector 1 + :param v2: Vector 2 + +--------------------- + +.. function:: void vec3_sub(struct vec3 *dst, const struct vec3 *v1, const struct vec3 *v2) + + Subtracts two vectors + + :param dst: Destination + :param v1: Vector being subtracted from + :param v2: Vector being subtracted + +--------------------- + +.. function:: void vec3_mul(struct vec3 *dst, const struct vec3 *v1, const struct vec3 *v2) + + Multiplies two vectors + + :param dst: Destination + :param v1: Vector 1 + :param v2: Vector 2 + +--------------------- + +.. function:: void vec3_div(struct vec3 *dst, const struct vec3 *v1, const struct vec3 *v2) + + Divides two vectors + + :param dst: Destination + :param v1: Dividend + :param v2: Divisor + +--------------------- + +.. function:: void vec3_addf(struct vec3 *dst, const struct vec3 *v, float f) + + Adds a floating point to all components + + :param dst: Destination + :param dst: Vector + :param f: Floating point + +--------------------- + +.. function:: void vec3_subf(struct vec3 *dst, const struct vec3 *v, float f) + + Subtracts a floating point from all components + + :param dst: Destination + :param v: Vector being subtracted from + :param f: Floating point being subtracted + +--------------------- + +.. function:: void vec3_mulf(struct vec3 *dst, const struct vec3 *v, float f) + + Multiplies a floating point with all components + + :param dst: Destination + :param dst: Vector + :param f: Floating point + +--------------------- + +.. function:: void vec3_divf(struct vec3 *dst, const struct vec3 *v, float f) + + Divides a floating point from all components + + :param dst: Destination + :param v: Vector (dividend) + :param f: Floating point (divisor) + +--------------------- + +.. function:: void vec3_neg(struct vec3 *dst, const struct vec3 *v) + + Negates a vector + + :param dst: Destination + :param v: Vector to negate + +--------------------- + +.. function:: float vec3_dot(const struct vec3 *v1, const struct vec3 *v2) + + Performs a dot product between two vectors + + :param v1: Vector 1 + :param v2: Vector 2 + :return: Result of the dot product + +--------------------- + +.. function:: void vec3_cross(struct vec3 *dst, const struct vec3 *v1, const struct vec3 *v2) + + Performs a cross product between two vectors + + :param dst: Destination + :param v1: Vector 1 + :param v2: Vector 2 + +--------------------- + +.. function:: float vec3_len(const struct vec3 *v) + + Gets the length of a vector + + :param v: Vector + :return: The vector's length + +--------------------- + +.. function:: float vec3_dist(const struct vec3 *v1, const struct vec3 *v2) + + Gets the distance between two vectors + + :param v1: Vector 1 + :param v2: Vector 2 + :return: Distance between the two vectors + +--------------------- + +.. function:: void vec3_minf(struct vec3 *dst, const struct vec3 *v, float val) + + Gets the minimum values between a vector's components and a floating point + + :param dst: Destination + :param v: Vector + :param val: Floating point + +--------------------- + +.. function:: void vec3_min(struct vec3 *dst, const struct vec3 *v, const struct vec3 *min_v) + + Gets the minimum values between two vectors + + :param dst: Destination + :param v: Vector 1 + :param min_v: Vector 2 + +--------------------- + +.. function:: void vec3_maxf(struct vec3 *dst, const struct vec3 *v, float val) + + Gets the maximum values between a vector's components and a floating point + + :param dst: Destination + :param v: Vector + :param val: Floating point + +--------------------- + +.. function:: void vec3_max(struct vec3 *dst, const struct vec3 *v, const struct vec3 *max_v) + + Gets the maximum values between two vectors + + :param dst: Destination + :param v: Vector 1 + :param max_v: Vector 2 + +--------------------- + +.. function:: void vec3_abs(struct vec3 *dst, const struct vec3 *v) + + Gets the absolute values of each component + + :param dst: Destination + :param v: Vector + +--------------------- + +.. function:: void vec3_floor(struct vec3 *dst, const struct vec3 *v) + + Gets the floor values of each component + + :param dst: Destination + :param v: Vector + +--------------------- + +.. function:: void vec3_ceil(struct vec3 *dst, const struct vec3 *v) + + Gets the ceiling values of each component + + :param dst: Destination + :param v: Vector + +--------------------- + +.. function:: int vec3_close(const struct vec3 *v1, const struct vec3 *v2, float epsilon) + + Compares two vectors + + :param v1: Vector 1 + :param v2: Vector 2 + :param epsilon: Maximum precision for comparison + +--------------------- + +.. function:: void vec3_norm(struct vec3 *dst, const struct vec3 *v) + + Normalizes a vector + + :param dst: Desination + :param v: Vector to normalize + +--------------------- + +.. function:: void vec3_transform(struct vec3 *dst, const struct vec3 *v, const struct matrix4 *m) + + Transforms a vector + + :param dst: Destination + :param v: Vector + :param m: Matrix + +--------------------- + +.. function:: void vec3_rotate(struct vec3 *dst, const struct vec3 *v, const struct matrix3 *m) + + Rotates a vector + + :param dst: Destination + :param v: Vector + :param m: Matrix + +--------------------- + +.. function:: void vec3_rand(struct vec3 *dst, int positive_only) + + Generates a random vector + + :param dst: Destination + :param positive_only: *true* if positive only, *false* otherwise diff --git a/docs/sphinx/reference-libobs-graphics-vec4.rst b/docs/sphinx/reference-libobs-graphics-vec4.rst new file mode 100644 index 000000000..7d6c51f0a --- /dev/null +++ b/docs/sphinx/reference-libobs-graphics-vec4.rst @@ -0,0 +1,282 @@ +4-Component Vector +================== + +.. code:: cpp + + #include + +.. type:: struct vec4 + + Two component vector structure. + +.. member:: float vec4.x + + X component + +.. member:: float vec4.y + + Y component + +.. member:: float vec4.z + + Z component + +.. member:: float vec4.w + + W component + +.. member:: float vec4.ptr[4] + + Unioned array of all components + +--------------------- + +.. function:: void vec4_zero(struct vec4 *dst) + + Zeroes a vector + + :param dst: Destination + +--------------------- + +.. function:: void vec4_set(struct vec4 *dst, float x, float y) + + Sets the individual components of a 4-component vector. + + :param dst: Destination + :param x: X component + :param y: Y component + :param y: Z component + :param w: W component + +--------------------- + +.. function:: void vec4_copy(struct vec4 *dst, const struct vec4 *v) + + Copies a vector + + :param dst: Destination + :param v: Vector to copy + +--------------------- + +.. function:: void vec4_from_vec3(struct vec4 *dst, const struct vec3 *v) + + Creates a 4-component vector from a 3-component vector + + :param dst: 4-component vector destination + :param v: 3-component vector + +--------------------- + +.. function:: void vec4_add(struct vec4 *dst, const struct vec4 *v1, const struct vec4 *v2) + + Adds two vectors + + :param dst: Destination + :param v1: Vector 1 + :param v2: Vector 2 + +--------------------- + +.. function:: void vec4_sub(struct vec4 *dst, const struct vec4 *v1, const struct vec4 *v2) + + Subtracts two vectors + + :param dst: Destination + :param v1: Vector being subtracted from + :param v2: Vector being subtracted + +--------------------- + +.. function:: void vec4_mul(struct vec4 *dst, const struct vec4 *v1, const struct vec4 *v2) + + Multiplies two vectors + + :param dst: Destination + :param v1: Vector 1 + :param v2: Vector 2 + +--------------------- + +.. function:: void vec4_div(struct vec4 *dst, const struct vec4 *v1, const struct vec4 *v2) + + Divides two vectors + + :param dst: Destination + :param v1: Dividend + :param v2: Divisor + +--------------------- + +.. function:: void vec4_addf(struct vec4 *dst, const struct vec4 *v, float f) + + Adds a floating point to all components + + :param dst: Destination + :param dst: Vector + :param f: Floating point + +--------------------- + +.. function:: void vec4_subf(struct vec4 *dst, const struct vec4 *v, float f) + + Subtracts a floating point from all components + + :param dst: Destination + :param v: Vector being subtracted from + :param f: Floating point being subtracted + +--------------------- + +.. function:: void vec4_mulf(struct vec4 *dst, const struct vec4 *v, float f) + + Multiplies a floating point with all components + + :param dst: Destination + :param dst: Vector + :param f: Floating point + +--------------------- + +.. function:: void vec4_divf(struct vec4 *dst, const struct vec4 *v, float f) + + Divides a floating point from all components + + :param dst: Destination + :param v: Vector (dividend) + :param f: Floating point (divisor) + +--------------------- + +.. function:: void vec4_neg(struct vec4 *dst, const struct vec4 *v) + + Negates a vector + + :param dst: Destination + :param v: Vector to negate + +--------------------- + +.. function:: float vec4_dot(const struct vec4 *v1, const struct vec4 *v2) + + Performs a dot product between two vectors + + :param v1: Vector 1 + :param v2: Vector 2 + :return: Result of the dot product + +--------------------- + +.. function:: float vec4_len(const struct vec4 *v) + + Gets the length of a vector + + :param v: Vector + :return: The vector's length + +--------------------- + +.. function:: float vec4_dist(const struct vec4 *v1, const struct vec4 *v2) + + Gets the distance between two vectors + + :param v1: Vector 1 + :param v2: Vector 2 + :return: Distance between the two vectors + +--------------------- + +.. function:: void vec4_minf(struct vec4 *dst, const struct vec4 *v, float val) + + Gets the minimum values between a vector's components and a floating point + + :param dst: Destination + :param v: Vector + :param val: Floating point + +--------------------- + +.. function:: void vec4_min(struct vec4 *dst, const struct vec4 *v, const struct vec4 *min_v) + + Gets the minimum values between two vectors + + :param dst: Destination + :param v: Vector 1 + :param min_v: Vector 2 + +--------------------- + +.. function:: void vec4_maxf(struct vec4 *dst, const struct vec4 *v, float val) + + Gets the maximum values between a vector's components and a floating point + + :param dst: Destination + :param v: Vector + :param val: Floating point + +--------------------- + +.. function:: void vec4_max(struct vec4 *dst, const struct vec4 *v, const struct vec4 *max_v) + + Gets the maximum values between two vectors + + :param dst: Destination + :param v: Vector 1 + :param max_v: Vector 2 + +--------------------- + +.. function:: void vec4_abs(struct vec4 *dst, const struct vec4 *v) + + Gets the absolute values of each component + + :param dst: Destination + :param v: Vector + +--------------------- + +.. function:: void vec4_floor(struct vec4 *dst, const struct vec4 *v) + + Gets the floor values of each component + + :param dst: Destination + :param v: Vector + +--------------------- + +.. function:: void vec4_ceil(struct vec4 *dst, const struct vec4 *v) + + Gets the ceiling values of each component + + :param dst: Destination + :param v: Vector + +--------------------- + +.. function:: int vec4_close(const struct vec4 *v1, const struct vec4 *v2, float epsilon) + + Compares two vectors + + :param v1: Vector 1 + :param v2: Vector 2 + :param epsilon: Maximum precision for comparison + +--------------------- + +.. function:: void vec4_norm(struct vec4 *dst, const struct vec4 *v) + + Normalizes a vector + + :param dst: Desination + :param v: Vector to normalize + +--------------------- + +.. function:: void vec4_transform(struct vec4 *dst, const struct vec4 *v, const struct matrix4 *m) + + Transforms a vector + + :param dst: Destination + :param v: Vector + :param m: Matrix diff --git a/docs/sphinx/reference-libobs-graphics.rst b/docs/sphinx/reference-libobs-graphics.rst new file mode 100644 index 000000000..d3553b26b --- /dev/null +++ b/docs/sphinx/reference-libobs-graphics.rst @@ -0,0 +1,17 @@ +Graphics API Reference (libobs/graphics) +======================================== + +.. toctree:: + :maxdepth: 2 + + reference-libobs-graphics-effects + reference-libobs-graphics-vec2 + reference-libobs-graphics-vec3 + reference-libobs-graphics-vec4 + reference-libobs-graphics-quat + reference-libobs-graphics-matrix4 + reference-libobs-graphics-math + reference-libobs-graphics-image-file + reference-libobs-graphics-axisang + reference-libobs-graphics-graphics + diff --git a/docs/sphinx/reference-libobs-media-io.rst b/docs/sphinx/reference-libobs-media-io.rst new file mode 100644 index 000000000..6e978cede --- /dev/null +++ b/docs/sphinx/reference-libobs-media-io.rst @@ -0,0 +1,463 @@ +Media I/O API Reference (libobs/media-io) +========================================= + +.. code:: cpp + + #include + + +Video Handler +------------- + +.. type:: video_t + + Video output handler object + +--------------------- + +.. type:: enum video_format + + Video format. Can be one of the following values: + + - VIDEO_FORMAT_I420 + - VIDEO_FORMAT_NV12 + + - VIDEO_FORMAT_YVYU + - VIDEO_FORMAT_YUY2 + - VIDEO_FORMAT_UYVY + + - VIDEO_FORMAT_RGBA + - VIDEO_FORMAT_BGRA + - VIDEO_FORMAT_BGRX + - VIDEO_FORMAT_Y800 + + - VIDEO_FORMAT_I444 + +--------------------- + +.. type:: enum video_colorspace + + YUV color space. Can be one of the following values: + + - VIDEO_CS_DEFAULT - Equivalent to VIDEO_CS_601 + - VIDEO_CS_601 - 601 color space + - VIDEO_CS_709 - 709 color space + +--------------------- + +.. type:: enum video_range_type + + YUV color range. + + - VIDEO_RANGE_DEFAULT - Equivalent to VIDEO_RANGE_PARTIAL + - VIDEO_RANGE_PARTIAL - Partial range + - VIDEO_RANGE_FULL - Full range + +--------------------- + +.. type:: struct video_data + + Video frame structure. + +.. member:: uint8_t *video_data.data[MAX_AV_PLANES] +.. member:: uint32_t video_data.linesize[MAX_AV_PLANES] +.. member:: uint64_t video_data.timestamp + +--------------------- + +.. type:: struct video_output_info + + Video output handler information + +.. member:: const char *video_output_info.name +.. member:: enum video_format video_output_info.format +.. member:: uint32_t video_output_info.fps_num +.. member:: uint32_t video_output_info.fps_den +.. member:: uint32_t video_output_info.width +.. member:: uint32_t video_output_info.height +.. member:: size_t video_output_info.cache_size +.. member:: enum video_colorspace video_output_info.colorspace +.. member:: enum video_range_type video_output_info.range + +--------------------- + +.. function:: enum video_format video_format_from_fourcc(uint32_t fourcc) + + Converts a fourcc value to a video format. + + :param forcecc: Fourcc value + :return: Video format + +--------------------- + +.. function:: bool video_format_get_parameters(enum video_colorspace color_space, enum video_range_type range, float matrix[16], float min_range[3], float max_range[3]) + + Converts a color space/range to matrix/min/max values. + + :param color_space: Color space to convert + :param range: Color range to convert + :param matrix: Pointer to the matrix + :param min_range: Pointer to get the minimum range value + :param max_range: Pointer to get the maximum range value + +--------------------- + +.. function:: bool video_output_connect(video_t *video, const struct video_scale_info *conversion, void (*callback)(void *param, struct video_data *frame), void *param) + + Connects a raw video callback to the video output handler. + + :param video: Video output handler object + :param callback: Callback to receive video data + :param param: Private data to pass to the callback + +--------------------- + +.. function:: void video_output_disconnect(video_t *video, void (*callback)(void *param, struct video_data *frame), void *param) + + Disconnects a raw video callback from the video output handler. + + :param video: Video output handler object + :param callback: Callback + :param param: Private data + +--------------------- + +.. function:: const struct video_output_info *video_output_get_info(const video_t *video) + + Gets the full video information of the video output handler. + + :param video: Video output handler object + :return: Video output info structure pointer + +--------------------- + +.. function:: uint64_t video_output_get_frame_time(const video_t *video) + + Gets the frame interval of the video output handler. + + :param video: Video output handler object + :return: Video frame interval in nanoseconds + +--------------------- + +.. function:: enum video_format video_output_get_format(const video_t *video) + + Gets the video format of the video output handler. + + :param video: Video output handler object + :return: Video format + +--------------------- + +.. function:: uint32_t video_output_get_width(const video_t *video) +.. function:: uint32_t video_output_get_height(const video_t *video) + + Gets the width/height of the video output handler. + + :param video: Video output handler object + :return: Width/height + +--------------------- + +.. function:: double video_output_get_frame_rate(const video_t *video) + + Gets the frame rate (as a floating point) of the video output + handler. + + :param video: Video output handler object + :return: Frame rate + +--------------------- + +.. function:: uint32_t video_output_get_skipped_frames(const video_t *video) + + Gets the skipped frame count of the video output handler. + + :param video: Video output handler object + :return: Skipped frame count + +--------------------- + +.. function:: uint32_t video_output_get_total_frames(const video_t *video) + + Gets the total frames processed of the video output handler. + + :param video: Video output handler object + :return: Total frames processed + +--------------------- + + +Audio Handler +------------- + +.. type:: audio_t + +--------------------- + +.. type:: enum audio_format + + Audio format. Can be one of the following values: + + - AUDIO_FORMAT_UNKNOWN + - AUDIO_FORMAT_U8BIT + - AUDIO_FORMAT_16BIT + - AUDIO_FORMAT_32BIT + - AUDIO_FORMAT_FLOAT + - AUDIO_FORMAT_U8BIT_PLANAR + - AUDIO_FORMAT_16BIT_PLANAR + - AUDIO_FORMAT_32BIT_PLANAR + - AUDIO_FORMAT_FLOAT_PLANAR + +--------------------- + +.. type:: enum speaker_layout + + Speaker layout. Can be one of the following values: + + - SPEAKERS_UNKNOWN + - SPEAKERS_MONO + - SPEAKERS_STEREO + - SPEAKERS_2POINT1 + - SPEAKERS_QUAD + - SPEAKERS_4POINT1 + - SPEAKERS_5POINT1 + - SPEAKERS_5POINT1_SURROUND + - SPEAKERS_7POINT1 + - SPEAKERS_7POINT1_SURROUND + - SPEAKERS_SURROUND + +--------------------- + +.. type:: struct audio_data + + Audio data structure. + +.. member:: uint8_t *audio_data.data[MAX_AV_PLANES] +.. member:: uint32_t audio_data.frames +.. member:: uint64_t audio_data.timestamp + +--------------------- + +.. type:: struct audio_output_data +.. member:: float *audio_output_data.data[MAX_AUDIO_CHANNELS] + +--------------------- + +.. type:: struct audio_output_info +.. member:: const char *audio_output_info.name +.. member:: uint32_t audio_output_info.samples_per_sec +.. member:: enum audio_format audio_output_info.format +.. member:: enum speaker_layout audio_output_info.speakers +.. member:: audio_input_callback_t audio_output_info.input_callback +.. member:: void *audio_output_info.input_param + +--------------------- + +.. type:: struct audio_convert_info +.. member:: uint32_t audio_convert_info.samples_per_sec +.. member:: enum audio_format audio_convert_info.format +.. member:: enum speaker_layout audio_convert_info.speakers + +--------------------- + +.. type:: typedef bool (*audio_input_callback_t)(void *param, uint64_t start_ts, uint64_t end_ts, uint64_t *new_ts, uint32_t active_mixers, struct audio_output_data *mixes) + + Audio input callback (typically used internally). + +--------------------- + +.. function:: uint32_t get_audio_channels(enum speaker_layout speakers) + + Converts a speaker layout to its audio channel count. + + :param speakers: Speaker layout enumeration + :return: Channel count + +--------------------- + +.. function:: size_t get_audio_bytes_per_channel(enum audio_format format) + + Gets the audio bytes per channel for a specific audio format. + + :param format: Audio format + :return: Bytes per channel + +--------------------- + +.. function:: bool is_audio_planar(enum audio_format format) + + Returns whether the audio format is a planar format. + + :param format: Audio format + :return: *true* if audio is planar, *false* otherwise + +--------------------- + +.. function:: size_t get_audio_planes(enum audio_format format, enum speaker_layout speakers) + + Gets the number of audio planes for a specific audio format and + speaker layout. + + :param format: Audio format + :param speakers: Speaker layout + :return: Number of audio planes + +--------------------- + +.. function:: size_t get_audio_size(enum audio_format format, enum speaker_layout speakers, uint32_t frames) + + Gets the audio block size for a specific frame out with the given + format and speaker layout. + + :param format: Audio format + :param speakers: Speaker layout + :param frames: Audio frame count + :return: Audio block size + +--------------------- + +.. function:: uint64_t audio_frames_to_ns(size_t sample_rate, uint64_t frames) + + Helper function to convert a specific number of audio frames to + nanoseconds based upon its sample rate. + + :param sample_rate: Sample rate + :param frames: Frame count + :return: Nanoseconds + +--------------------- + +.. function:: uint64_t ns_to_audio_frames(size_t sample_rate, uint64_t ns) + + Helper function to convert a specific number of nanoseconds to audio + frame count based upon its sample rate. + + :param sample_rate: Sample rate + :param ns: Nanoseconds + :return: Frame count + +--------------------- + +.. type:: typedef void (*audio_output_callback_t)(void *param, size_t mix_idx, struct audio_data *data) + + Audio output callback. Typically used internally. + +--------------------- + +.. function:: bool audio_output_connect(audio_t *audio, size_t mix_idx, const struct audio_convert_info *conversion, audio_output_callback_t callback, void *param) + + Connects a raw audio callback to the audio output handler. + Optionally allows audio conversion if necessary. + + :param audio: Audio output handler object + :param mix_idx: Mix index to get raw audio from + :param conversion: Audio conversion information, or *NULL* for no + conversion + :param callback: Raw audio callback + :param param: Private data to pass to the callback + +--------------------- + +.. function:: void audio_output_disconnect(audio_t *audio, size_t mix_idx, audio_output_callback_t callback, void *param) + + Disconnects a raw audio callback from the audio output handler. + + :param audio: Audio output handler object + :param mix_idx: Mix index to get raw audio from + :param callback: Raw audio callback + :param param: Private data to pass to the callback + +--------------------- + +.. function:: size_t audio_output_get_block_size(const audio_t *audio) + + Gets the audio block size of an audio output handler. + + :param audio: Audio output handler object + :return: Audio block size + +--------------------- + +.. function:: size_t audio_output_get_planes(const audio_t *audio) + + Gets the plane count of an audio output handler. + + :param audio: Audio output handler object + :return: Audio plane count + +--------------------- + +.. function:: size_t audio_output_get_channels(const audio_t *audio) + + Gets the channel count of an audio output handler. + + :param audio: Audio output handler object + :return: Audio channel count + +--------------------- + +.. function:: uint32_t audio_output_get_sample_rate(const audio_t *audio) + + Gets the sample rate of an audio output handler. + + :param audio: Audio output handler object + :return: Audio sample rate + +--------------------- + +.. function:: const struct audio_output_info *audio_output_get_info(const audio_t *audio) + + Gets all audio information for an audio output handler. + + :param audio: Audio output handler object + :return: Pointer to audio output information structure + +--------------------- + + +Resampler +--------- + +FFmpeg wrapper to resample audio. + +.. type:: typedef struct audio_resampler audio_resampler_t + +--------------------- + +.. type:: struct resample_info +.. member:: uint32_t resample_info.samples_per_sec +.. member:: enum audio_format resample_info.format +.. member:: enum speaker_layout resample_info.speakers + +--------------------- + +.. function:: audio_resampler_t *audio_resampler_create(const struct resample_info *dst, const struct resample_info *src) + + Creates an audio resampler. + + :param dst: Destination audio information + :param src: Source audio information + :return: Audio resampler object + +--------------------- + +.. function:: void audio_resampler_destroy(audio_resampler_t *resampler) + + Destroys an audio resampler. + + :param resampler: Audio resampler object + +--------------------- + +.. function:: bool audio_resampler_resample(audio_resampler_t *resampler, uint8_t *output[], uint32_t *out_frames, uint64_t *ts_offset, const uint8_t *const input[], uint32_t in_frames) + + Resamples audio frames. + + :param resampler: Audio resampler object + :param output: Pointer to receive converted audio frames + :param out_frames: Pointer to receive converted audio frame count + :param ts_offset: Pointer to receive timestamp offset (in + nanoseconds) + :param const input: Input frames to convert + :param in_frames: Input frame count diff --git a/docs/sphinx/reference-libobs-util-base.rst b/docs/sphinx/reference-libobs-util-base.rst new file mode 100644 index 000000000..a3d4744f8 --- /dev/null +++ b/docs/sphinx/reference-libobs-util-base.rst @@ -0,0 +1,75 @@ +Logging +======= + +Functions for logging and getting log data. + +.. code:: cpp + + #include + + +Logging Levels +-------------- + +**LOG_ERROR** = 100 + + Use if there's a problem that can potentially affect the program, + but isn't enough to require termination of the program. + + Use in creation functions and core subsystem functions. Places that + should definitely not fail. + +**LOG_WARNING** = 200 + + Use if a problem occurs that doesn't affect the program and is + recoverable. + + Use in places where failure isn't entirely unexpected, and can + be handled safely. + +**LOG_INFO** = 300 + + Informative message to be displayed in the log. + +**LOG_DEBUG** = 400 + + Debug message to be used mostly by and for developers. + + +Logging Functions +----------------- + +.. type:: typedef void (*log_handler_t)(int lvl, const char *msg, va_list args, void *p) + + Logging callback. + +--------------------- + +.. function:: void base_set_log_handler(log_handler_t handler, void *param) + void base_get_log_handler(log_handler_t *handler, void **param) + + Sets/gets the current log handler. + +--------------------- + +.. function:: void base_set_crash_handler(void (*handler)(const char *, va_list, void *), void *param) + + Sets the current crash handler. + +--------------------- + +.. function:: void blogva(int log_level, const char *format, va_list args) + + Logging function (using a va_list). + +--------------------- + +.. function:: void blog(int log_level, const char *format, ...) + + Logging function. + +--------------------- + +.. function:: void bcrash(const char *format, ...) + + Crash function. diff --git a/docs/sphinx/reference-libobs-util-bmem.rst b/docs/sphinx/reference-libobs-util-bmem.rst new file mode 100644 index 000000000..36bc93cbe --- /dev/null +++ b/docs/sphinx/reference-libobs-util-bmem.rst @@ -0,0 +1,62 @@ +Memory Management +================= + +Various functions and helpers used for memory management. + +.. code:: cpp + + #include + + +Memory Functions +---------------- + +.. function:: void *bmalloc(size_t size) + + Allocates memory and increases the memory leak counter. + +--------------------- + +.. function:: void *brealloc(void *ptr, size_t size) + + Reallocates memory. Use only with memory that's been allocated by + :c:func:`bmalloc()`. + +--------------------- + +.. function:: void bfree(void *ptr) + + Frees memory allocated with :c:func:`bmalloc()` or :c:func:`bfree()`. + +--------------------- + +.. function:: long bnum_allocs(void) + + Returns current number of active allocations. + +--------------------- + +.. function:: void *bmemdup(const void *ptr, size_t size) + + Duplicates memory. + +--------------------- + +.. function:: void *bzalloc(size_t size) + + Inline function that allocates zeroed memory. + +--------------------- + +.. function:: char *bstrdup_n(const char *str, size_t n) + wchar_t *bwstrdup_n(const wchar_t *str, size_t n) + + Duplicates a string of *n* bytes and automatically zero-terminates + it. + +--------------------- + +.. function:: char *bstrdup(const char *str) + wchar_t *bwstrdup(const wchar_t *str) + + Duplicates a string. diff --git a/docs/sphinx/reference-libobs-util-circlebuf.rst b/docs/sphinx/reference-libobs-util-circlebuf.rst new file mode 100644 index 000000000..0fdf98bb8 --- /dev/null +++ b/docs/sphinx/reference-libobs-util-circlebuf.rst @@ -0,0 +1,140 @@ +Circular Buffers +================ + +A circular buffer that will automatically increase in size as necessary +as data is pushed to the front or back. + +.. code:: cpp + + #include + + +Circular Buffer Structure (struct circlebuf) +-------------------------------------------- + +.. type:: struct circlebuf +.. member:: void *circlebuf.data +.. member:: size_t circlebuf.size +.. member:: size_t circlebuf.start_pos +.. member:: size_t circlebuf.end_pos +.. member:: size_t circlebuf.capacity + + +Circular Buffer Inline Functions +-------------------------------- + +.. function:: void circlebuf_init(struct circlebuf *cb) + + Initializes a circular buffer (just zeroes out the entire structure). + + :param cb: The circular buffer + +--------------------- + +.. function:: void circlebuf_free(struct circlebuf *cb) + + Frees a circular buffer. + + :param cb: The circular buffer + +--------------------- + +.. function:: void circlebuf_reserve(struct circlebuf *cb, size_t capacity) + + Reserves a specific amount of buffer space to ensure minimum + upsizing. + + :param cb: The circular buffer + :param capacity: The new capacity, in bytes + +--------------------- + +.. function:: void circlebuf_upsize(struct circlebuf *cb, size_t size) + + Sets the current active (not just reserved) size. Any new data is + zeroed. + + :param cb: The circular buffer + :param size: The new size, in bytes + +--------------------- + +.. function:: void circlebuf_place(struct circlebuf *cb, size_t position, const void *data, size_t size) + + Places data at a specific positional index (relative to the starting + point) within the circular buffer. + + :param cb: The circular buffer + :param position: Positional index relative to starting point + :param data: Data to insert + :param size: Size of data to insert + +--------------------- + +.. function:: void circlebuf_push_back(struct circlebuf *cb, const void *data, size_t size) + + Pushes data to the end of the circular buffer. + + :param cb: The circular buffer + :param data: Data + :param size: Size of data + +--------------------- + +.. function:: void circlebuf_push_front(struct circlebuf *cb, const void *data, size_t size) + + Pushes data to the front of the circular buffer. + + :param cb: The circular buffer + :param data: Data + :param size: Size of data + +--------------------- + +.. function:: void circlebuf_peek_front(struct circlebuf *cb, void *data, size_t size) + + Peeks data at the front of the circular buffer. + + :param cb: The circular buffer + :param data: Buffer to store data in + :param size: Size of data to retrieve + +--------------------- + +.. function:: void circlebuf_peek_back(struct circlebuf *cb, void *data, size_t size) + + Peeks data at the back of the circular buffer. + + :param cb: The circular buffer + :param data: Buffer to store data in + :param size: Size of data to retrieve + +--------------------- + +.. function:: void circlebuf_pop_front(struct circlebuf *cb, void *data, size_t size) + + Pops data from the front of the circular buffer. + + :param cb: The circular buffer + :param data: Buffer to store data in, or *NULL* + :param size: Size of data to retrieve + +--------------------- + +.. function:: void circlebuf_pop_back(struct circlebuf *cb, void *data, size_t size) + + Pops data from the back of the circular buffer. + + :param cb: The circular buffer + :param data: Buffer to store data in, or *NULL* + :param size: Size of data to retrieve + +--------------------- + +.. function:: void *circlebuf_data(struct circlebuf *cb, size_t idx) + + Gets a direct pointer to data at a specific positional index within + the circular buffer, relative to the starting point. + + :param cb: The circular buffer + :param idx: Byte index relative to the starting point diff --git a/docs/sphinx/reference-libobs-util-config-file.rst b/docs/sphinx/reference-libobs-util-config-file.rst new file mode 100644 index 000000000..d2f8b9086 --- /dev/null +++ b/docs/sphinx/reference-libobs-util-config-file.rst @@ -0,0 +1,312 @@ +Config Files +============ + +The configuration file functions are a simple implementation of the INI +file format, with the addition of default values. + +.. code:: cpp + + #include + +.. type:: config_t + + +Config File Functions +--------------------- + +.. function:: config_t *config_create(const char *file) + + Creates a new configuration object and associates it with the + specified file name. + + :param file: Path to the new configuration file + :return: A new configuration file object + +---------------------- + +.. function:: int config_open(config_t **config, const char *file, enum config_open_type open_type) + + Opens a configuration file. + + :param config: Pointer that receives a pointer to a new configuration + file object (if successful) + :param file: Path to the configuration file + :param open_type: Can be one of the following values: + + - CONFIG_OPEN_EXISTING - Fail if the file doesn't + exist. + - CONFIG_OPEN_ALWAYS - Try to open the file. If + the file doesn't exist, create it. + + :return: Can return the following values: + + - CONFIG_SUCCESS - Successful + - CONFIG_FILENOTFOUND - File not found + - CONFIG_ERROR - Generic error + +---------------------- + +.. function:: int config_open_string(config_t **config, const char *str) + + Opens configuration data via a string rather than a file. + + :param config: Pointer that receives a pointer to a new configuration + file object (if successful) + :param str: Configuration string + + :return: Can return the following values: + + - CONFIG_SUCCESS - Successful + - CONFIG_FILENOTFOUND - File not found + - CONFIG_ERROR - Generic error + +---------------------- + +.. function:: int config_save(config_t *config) + + Saves configuration data to a file (if associated with a file). + + :param config: Configuration object + + :return: Can return the following values: + + - CONFIG_SUCCESS - Successful + - CONFIG_FILENOTFOUND - File not found + - CONFIG_ERROR - Generic error + +---------------------- + +.. function:: int config_save_safe(config_t *config, const char *temp_ext, const char *backup_ext) + + Saves configuration data and minimizes overwrite corruption risk. + Saves the file with the file name + + :param config: Configuration object + :param temp_ext: Temporary extension for the new file + :param backup_ext: Backup extension for the old file. Can be *NULL* + if no backup is desired. + + :return: Can return the following values: + + - CONFIG_SUCCESS - Successful + - CONFIG_FILENOTFOUND - File not found + - CONFIG_ERROR - Generic error + +---------------------- + +.. function:: void config_close(config_t *config) + + Closes the configuration object. + + :param config: Configuration object + +---------------------- + +.. function:: size_t config_num_sections(config_t *config) + + Returns the number of sections. + + :param config: Configuration object + :return: Number of configuration sections + +---------------------- + +.. function:: const char *config_get_section(config_t *config, size_t idx) + + Returns a section name based upon its index. + + :param config: Configuration object + :param idx: Index of the section + :return: The section's name + +Set/Get Functions +----------------- + +.. function:: void config_set_string(config_t *config, const char *section, const char *name, const char *value) + + Sets a string value. + + :param config: Configuration object + :param section: The section of the value + :param name: The value name + :param value: The string value + +---------------------- + +.. function:: void config_set_int(config_t *config, const char *section, const char *name, int64_t value) + + Sets an integer value. + + :param config: Configuration object + :param section: The section of the value + :param name: The value name + :param value: The integer value + +---------------------- + +.. function:: void config_set_uint(config_t *config, const char *section, const char *name, uint64_t value) + + Sets an unsigned integer value. + + :param config: Configuration object + :param section: The section of the value + :param name: The value name + :param value: The unsigned integer value + +---------------------- + +.. function:: void config_set_bool(config_t *config, const char *section, const char *name, bool value) + + Sets a boolean value. + + :param config: Configuration object + :param section: The section of the value + :param name: The value name + :param value: The boolean value + +---------------------- + +.. function:: void config_set_double(config_t *config, const char *section, const char *name, double value) + + Sets a floating point value. + + :param config: Configuration object + :param section: The section of the value + :param name: The value name + :param value: The floating point value + +---------------------- + +.. function:: const char *config_get_string(config_t *config, const char *section, const char *name) + + Gets a string value. If the value is not set, it will use the + default value. If there is no default value, it will return *NULL*. + + :param config: Configuration object + :param section: The section of the value + :param name: The value name + :return: The string value + +---------------------- + +.. function:: int64_t config_get_int(config_t *config, const char *section, const char *name) + + Gets an integer value. If the value is not set, it will use the + default value. If there is no default value, it will return 0. + + :param config: Configuration object + :param section: The section of the value + :param name: The value name + :return: The integer value + +---------------------- + +.. function:: uint64_t config_get_uint(config_t *config, const char *section, const char *name) + + Gets an unsigned integer value. If the value is not set, it will use + the default value. If there is no default value, it will return 0. + + :param config: Configuration object + :param section: The section of the value + :param name: The value name + :return: The unsigned integer value + +---------------------- + +.. function:: bool config_get_bool(config_t *config, const char *section, const char *name) + + Gets a boolean value. If the value is not set, it will use the + default value. If there is no default value, it will return false. + + :param config: Configuration object + :param section: The section of the value + :param name: The value name + :return: The boolean value + +---------------------- + +.. function:: double config_get_double(config_t *config, const char *section, const char *name) + + Gets a floating point value. If the value is not set, it will use + the default value. If there is no default value, it will return 0.0. + + :param config: Configuration object + :param section: The section of the value + :param name: The value name + :return: The floating point value + +---------------------- + +.. function:: bool config_remove_value(config_t *config, const char *section, const char *name) + + Removes a value. Does not remove the default value if any. + + :param config: Configuration object + :param section: The section of the value + :param name: The value name + + +Default Value Functions +----------------------- + +.. function:: int config_open_defaults(config_t *config, const char *file) + + Opens a file and uses it for default values. + + :param config: Configuration object + :param file: The file to open for default values + +---------------------- + +.. function:: void config_set_default_string(config_t *config, const char *section, const char *name, const char *value) + + Sets a default string value. + + :param config: Configuration object + :param section: The section of the value + :param name: The value name + :param value: The string value + +---------------------- + +.. function:: void config_set_default_int(config_t *config, const char *section, const char *name, int64_t value) + + Sets a default integer value. + + :param config: Configuration object + :param section: The section of the value + :param name: The value name + :param value: The integer value + +---------------------- + +.. function:: void config_set_default_uint(config_t *config, const char *section, const char *name, uint64_t value) + + Sets a default unsigned integer value. + + :param config: Configuration object + :param section: The section of the value + :param name: The value name + :param value: The unsigned integer value + +---------------------- + +.. function:: void config_set_default_bool(config_t *config, const char *section, const char *name, bool value) + + Sets a default boolean value. + + :param config: Configuration object + :param section: The section of the value + :param name: The value name + :param value: The boolean value + +---------------------- + +.. function:: void config_set_default_double(config_t *config, const char *section, const char *name, double value) + + Sets a default floating point value. + + :param config: Configuration object + :param section: The section of the value + :param name: The value name + :param value: The floating point value diff --git a/docs/sphinx/reference-libobs-util-darray.rst b/docs/sphinx/reference-libobs-util-darray.rst new file mode 100644 index 000000000..13ca27334 --- /dev/null +++ b/docs/sphinx/reference-libobs-util-darray.rst @@ -0,0 +1,275 @@ +Dynamic Arrays +============== + +Dynamically resizing arrays (a C equivalent to std::vector). + +.. code:: cpp + + #include + +.. type:: struct darray + + The base dynamic array structure. + +.. type:: DARRAY(type) + + Macro for a dynamic array based upon an actual type. Use this with + da_* macros. + +.. member:: void *darray.array + + The array pointer. + +.. member:: size_t darray.num + + The number of items within the array. + +.. member:: size_t darray.capacity + + The capacity of the array. + + +Dynamic Array Macros +-------------------- + +These macro functions are used with variables created with the +**DARRAY** type macro. When using these functions, do not use the +dynamic array value with a reference (&) operator. For example: + +.. code:: cpp + + /* creates an array of integers: 0..9 */ + DARRAY(int) array_of_integers; + da_init(array_of_integers); + + for (size_t i = 0; i < 10; i++) + da_push_back(array_of_integers, &i); + + [...] + + /* free when complete */ + da_free(array_of_integers); + +.. function:: void da_init(da) + + Initializes a dynamic array. + + :param da: The dynamic array + +--------------------- + +.. function:: void da_free(da) + + Frees a dynamic array. + + :param da: The dynamic array + +--------------------- + +.. function:: void *da_end(da) + + Gets a pointer to the last value. + + :param da: The dynamic array + :return: The last value of a dynamic array, or *NULL* if empty. + +--------------------- + +.. function:: void da_reserve(da, size_t capacity) + + Reserves a specific amount of buffer space for the dynamic array. + + :param da: The dynamic array + :param capacity: New capacity of the dynamic array + +--------------------- + +.. function:: void da_resize(da, size_t new_size) + + Resizes the dynamic array with zeroed values. + + :param da: The dynamic array + :param size: New size of the dynamic array + +--------------------- + +.. function:: void da_copy(da_dst, da_src) + + Makes a copy of a dyanmic array. + + :param da_dst: The dynamic array to copy to + :param da_src: The dynamic array to copy from + +--------------------- + +.. function:: void da_copy_array(da, const void *src_array, size_t size) + + Makes a copy of an array pointer. + + :param da: The dynamic array + :param src_array: The array pointer to make a copy from + :param size: New size of the dynamic array + +--------------------- + +.. function:: void da_move(da_dst, da_src) + + Moves one dynamic array variable to another without allocating new + data. *da_dst* is freed before moving, *da_dst* is set to *da_src*, + then *da_src* is then zeroed. + + :param da_dst: Destination variable + :param da_src: Source variable + +--------------------- + +.. function:: size_t da_find(da, const void *item_data, size_t starting_idx) + + Finds a value based upon its data. If the value cannot be found, the + return value will be DARRAY_INVALID (-1). + + :param da: The dynamic array + :param item_data: The item data to find + :param starting_idx: The index to start from or 0 to search the + entire array + +--------------------- + +.. function:: void da_push_back(da, const void *data) + + Pushes data to the back of the array. + + :param da: The dynamic array + :param data: Pointer to the new data to push + +--------------------- + +.. function:: void *da_push_back_new(da) + + Pushes a zeroed value to the back of the array, and returns a pointer + to it. + + :param da: The dynamic array + :return: Pointer to the new value + +--------------------- + +.. function:: void da_push_back_array(da, const void *src_array, size_t item_count) + + Pushes an array of values to the back of the array. + + :param da: The dynamic array + :param src_array: Pointer of the array of values + :param item_count: Number of items to push back + +--------------------- + +.. function:: void da_insert(da, size_t idx, const void *data) + + Inserts a value at a given index. + + :param da: The dynamic array: + :param idx: Index where the new item will be inserted + :param data: Pointer to the item data to insert + +--------------------- + +.. function:: void *da_insert_new(da, size_t idx) + + Inserts a new zeroed value at a specific index, and returns a pointer + to it. + + :param da: The dynamic array + :param idx: Index to insert at + :return: Pointer to the new value + +--------------------- + +.. function:: void da_insert_da(da_dst, size_t idx, da_src) + + Inserts a dynamic array in to another dynamic array at a specific + index. + + :param da_dst: Destination dynamic array being inserted in to + :param idx: Index to insert the data at + :param da_src: The dynamic array to insert + +--------------------- + +.. function:: void da_erase(da, size_t idx) + + Erases an item at a specific index. + + :param da: The dynamic array + :param idx: The index of the value to remove + +--------------------- + +.. function:: void da_erase_item(da, const void *item_data) + + Erases an item that matches the value specified + + :param da: The dynamic array + :param item_data: Pointer to the data to remove + +--------------------- + +.. function:: void da_erase_range(da, size_t start_idx, size_t end_idx) + + Erases a range of values. + + :param da: The dynamic array + :param start_idx: The starting index + :param end_idx: The ending index + +--------------------- + +.. function:: void da_pop_back(da) + + Removes one item from the end of a dynamic array. + + :param da: The dynamic array + +--------------------- + +.. function:: void da_join(da_dst, da_src) + + Pushes *da_src* to the end of *da_dst* and frees *da_src*. + + :param da_dst: The destination dynamic array + :param da_src: The source dynamic array + +--------------------- + +.. function:: void da_split(da_dst1, da_dst2, da_src, size_t split_idx) + + Creates two dynamic arrays by splitting another dynamic array at a + specific index. If the destination arrays are not freed, they will + be freed before getting their new values. The array being split will + not be freed. + + :param da_dst1: Dynamic array that will get the lower half + :param da_dst2: Dynamic array that will get the upper half + :param da_src: Dynamic array to split + :param split_idx: Index to split *da_src* at + +--------------------- + +.. function:: void da_move_item(da, size_t src_idx, size_t dst_idx) + + Moves an item from one index to another, moving data between if + necessary. + + :param da: The dynamic array + :param src_idx: The index of the item to move + :param dst_idx: The new index of where the item will be moved to + +--------------------- + +.. function:: void da_swap(da, size_t idx1, size_t idx2) + + Swaps two values at the given indices. + + :param da: The dynamic array + :param idx1: Index of the first item to swap + :param idx2: Index of the second item to swap diff --git a/docs/sphinx/reference-libobs-util-dstr.rst b/docs/sphinx/reference-libobs-util-dstr.rst new file mode 100644 index 000000000..20fb9115f --- /dev/null +++ b/docs/sphinx/reference-libobs-util-dstr.rst @@ -0,0 +1,490 @@ +Dynamic Strings And String Helpers +================================== + +Provides string helper structures/functions (roughly equivalent to +std::string). + +.. code:: cpp + + #include + + +Dynamic String Structure (struct dstr) +-------------------------------------- + +.. type:: struct dstr +.. member:: char *dstr.array +.. member:: size_t dstr.len +.. member:: size_t dstr.capacity + + +General String Helper Functions +------------------------------- + +.. function:: int astrcmpi(const char *str1, const char *str2) + + Case insensitive string comparison function. + +---------------------- + +.. function:: int wstrcmpi(const wchar_t *str1, const wchar_t *str2) + + Case insensitive wide string comparison function. + +---------------------- + +.. function:: int astrcmp_n(const char *str1, const char *str2, size_t n) + + String comparison function for a specific number of characters. + +---------------------- + +.. function:: int wstrcmp_n(const wchar_t *str1, const wchar_t *str2, size_t n) + + Wide string comparison function for a specific number of characters. + +---------------------- + +.. function:: int astrcmpi_n(const char *str1, const char *str2, size_t n) + + Case insensitive string comparison function for a specific number of + characters. + +---------------------- + +.. function:: int wstrcmpi_n(const wchar_t *str1, const wchar_t *str2, size_t n) + + Case insensitive wide string comparison function for a specific + number of characters. + +---------------------- + +.. function:: char *astrstri(const char *str, const char *find) + + Case insensitive version of strstr. + +---------------------- + +.. function:: wchar_t *wstrstri(const wchar_t *str, const wchar_t *find) + + Case insensitive version of wcsstr. + +---------------------- + +.. function:: char *strdepad(char *str) + + Removes padding characters (tab, space, CR, LF) from the front and + end of a string. + +---------------------- + +.. function:: wchar_t *wcsdepad(wchar_t *str) + + Removes padding characters (tab, space, CR, LF) from the front and + end of a wide string. + +---------------------- + +.. function:: char **strlist_split(const char *str, char split_ch, bool include_empty) + + Splits a string in to a list of multiple sub-strings. Free with + :c:func:`strlist_free()`. + +---------------------- + +.. function:: void strlist_free(char **strlist) + + Frees a string list created with :c:func:`strlist_split()`. + +--------------------- + + +Dynamic String Functions +------------------------ + +.. function:: void dstr_init(struct dstr *dst) + + Initializes a dynamic string variable (just zeroes the variable). + + :param dst: Dynamic string to initialize + +---------------------- + +.. function:: void dstr_init_move(struct dstr *dst, struct dstr *src) + + Moves a *src* to *dst* without copying data and zeroes *src*. + + :param dst: Destination + :param src: Source + +---------------------- + +.. function:: void dstr_init_move_array(struct dstr *dst, char *str) + + Sets a bmalloc-allocated string as the dynamic string without + copying/reallocating. + + :param dst: Dynamic string to initialize + :param str: bmalloc-allocated string + +---------------------- + +.. function:: void dstr_init_copy(struct dstr *dst, const char *src) + + Initializes a dynamic string with a copy of a string + + :param dst: Dynamic string to initialize + :param src: String to copy + +---------------------- + +.. function:: void dstr_init_copy_dstr(struct dstr *dst, const struct dstr *src) + + Initializes a dynamic string with a copy of another dynamic string + + :param dst: Dynamic string to initialize + :param src: Dynamic string to copy + +---------------------- + +.. function:: void dstr_free(struct dstr *dst) + + Frees a dynamic string. + + :param dst: Dynamic string + +---------------------- + +.. function:: void dstr_copy(struct dstr *dst, const char *array) + + Copies a string. + + :param dst: Dynamic string + :param array: String to copy + +---------------------- + +.. function:: void dstr_copy_dstr(struct dstr *dst, const struct dstr *src) + + Copies another dynamic string. + + :param dst: Dynamic string + :param src: Dynamic string to copy + +---------------------- + +.. function:: void dstr_ncopy(struct dstr *dst, const char *array, const size_t len) + + Copies a specific number of characters from a string. + + :param dst: Dynamic string + :param array: String to copy + :param len: Number of characters to copy + +---------------------- + +.. function:: void dstr_ncopy_dstr(struct dstr *dst, const struct dstr *src, const size_t len) + + Copies a specific number of characters from another dynamic string. + + :param dst: Dynamic string + :param src: Dynamic tring to copy + :param len: Number of characters to copy + +---------------------- + +.. function:: void dstr_resize(struct dstr *dst, const size_t num) + + Sets the size of the dynamic string. If the new size is bigger than + current size, zeroes the new characters. + + :param dst: Dynamic string + :param num: New size + +---------------------- + +.. function:: void dstr_reserve(struct dstr *dst, const size_t num) + + Reserves a specific number of characters in the buffer (but does not + change the size). Does not work if the value is smaller than the + current reserve size. + + :param dst: Dynamic string + :param num: New reserve size + +---------------------- + +.. function:: bool dstr_is_empty(const struct dstr *str) + + Returns whether the dynamic string is empty. + + :param str: Dynamic string + :return: *true* if empty, *false* otherwise + +---------------------- + +.. function:: void dstr_cat(struct dstr *dst, const char *array) + + Concatenates a dynamic string. + + :param dst: Dynamic string + :param array: String to concatenate with + +---------------------- + +.. function:: void dstr_cat_dstr(struct dstr *dst, const struct dstr *str) + + Concatenates a dyanmic string with another dynamic string. + + :param dst: Dynamic string to concatenate to + :param str: Dynamic string to concatenate with + +---------------------- + +.. function:: void dstr_cat_ch(struct dstr *dst, char ch) + + Concatenates a dynamic string with a single character. + + :param dst: Dynamic string to concatenate to + :param ch: Character to concatenate + +---------------------- + +.. function:: void dstr_ncat(struct dstr *dst, const char *array, const size_t len) + + Concatenates a dynamic string with a specific number of characters + from a string. + + :param dst: Dynamic string to concatenate to + :param array: String to concatenate with + :param len: Number of characters to concatenate with + +---------------------- + +.. function:: void dstr_ncat_dstr(struct dstr *dst, const struct dstr *str, const size_t len) + + Concatenates a dynamic string with a specific number of characters + from another dynamic string. + + :param dst: Dynamic string to concatenate to + :param str: Dynamic string to concatenate with + :param len: Number of characters to concatenate with + +---------------------- + +.. function:: void dstr_insert(struct dstr *dst, const size_t idx, const char *array) + + Inserts a string in to a dynamic string at a specific index. + + :param dst: Dynamic string to insert in to + :param idx: Character index to insert at + :param array: String to insert + +---------------------- + +.. function:: void dstr_insert_dstr(struct dstr *dst, const size_t idx, const struct dstr *str) + + Inserts another dynamic string in to a dynamic string at a specific + index. + + :param dst: Dynamic string to insert in to + :param idx: Character index to insert at + :param str: Dynamic string to insert + +---------------------- + +.. function:: void dstr_insert_ch(struct dstr *dst, const size_t idx, const char ch) + + Inserts a character in to a dynamic string at a specific index. + + :param dst: Dynamic string to insert in to + :param idx: Character index to insert at + :param ch: Character to insert + +---------------------- + +.. function:: void dstr_remove(struct dstr *dst, const size_t idx, const size_t count) + + Removes a specific number of characters starting from a specific + index. + + :param dst: Dyanmic string + :param idx: Index to start removing characters at + :param count: Number of characters to remove + +---------------------- + +.. function:: void dstr_printf(struct dstr *dst, const char *format, ...) + void dstr_vprintf(struct dstr *dst, const char *format, va_list args) + + Sets a dynamic string to a formatted string. + + :param dst: Dynamic string + :param format: Format string + +---------------------- + +.. function:: void dstr_catf(struct dstr *dst, const char *format, ...) + void dstr_vcatf(struct dstr *dst, const char *format, va_list args) + + Concatenates a dynamic string with a formatted string. + + :param dst: Dynamic string + :param format: Format string + +---------------------- + +.. function:: const char *dstr_find_i(const struct dstr *str, const char *find) + + Finds a string within a dynamic string, case insensitive. + + :param str: Dynamic string + :param find: String to find + :return: Pointer to the first occurrence, or *NULL* if not found + +---------------------- + +.. function:: const char *dstr_find(const struct dstr *str, const char *find) + + Finds a string within a dynamic string. + + :param str: Dynamic string + :param find: String to find + :return: Pointer to the first occurrence, or *NULL* if not found + +---------------------- + +.. function:: void dstr_replace(struct dstr *str, const char *find, const char *replace) + + Replaces all occurrences of *find* with *replace*. + + :param str: Dynamic string + :param find: String to find + :param replace: Replacement string + +---------------------- + +.. function:: int dstr_cmp(const struct dstr *str1, const char *str2) + + Compares with a string. + + :param str1: Dynamic string + :param str2: String to compare + :return: 0 if equal, nonzero otherwise + +---------------------- + +.. function:: int dstr_cmpi(const struct dstr *str1, const char *str2) + + Compares with a string, case-insensitive. + + :param str1: Dynamic string + :param str2: String to compare + :return: 0 if equal, nonzero otherwise + +---------------------- + +.. function:: int dstr_ncmp(const struct dstr *str1, const char *str2, const size_t n) + + Compares a specific number of characters. + + :param str1: Dynamic string + :param str2: String to compare + :param n: Number of characters to compare + :return: 0 if equal, nonzero otherwise + +---------------------- + +.. function:: int dstr_ncmpi(const struct dstr *str1, const char *str2, const size_t n) + + Compares a specific number of characters, case-insensitive. + + :param str1: Dynamic string + :param str2: String to compare + :param n: Number of characters to compare + :return: 0 if equal, nonzero otherwise + +---------------------- + +.. function:: void dstr_depad(struct dstr *dst) + + Removes all padding characters (tabs, spaces, CR, LF) from the front + and ends of a dynamic string. + + :param dst: Dynamic string + +---------------------- + +.. function:: void dstr_left(struct dstr *dst, const struct dstr *str, const size_t pos) + + Copies a certain number of characters from the left side of one + dynamic string in to another. + + :param dst: Destination + :param str: Source + :param pos: Number of characters + +---------------------- + +.. function:: void dstr_mid(struct dstr *dst, const struct dstr *str, const size_t start, const size_t count) + + Copies a certain number of characters from the middle of one dynamic + string in to another. + + :param dst: Destination + :param str: Source + :param start: Starting index within *str* + :param count: Number of characters to copy + +---------------------- + +.. function:: void dstr_right(struct dstr *dst, const struct dstr *str, const size_t pos) + + Copies a certain number of characters from the right of one dynamic + string in to another. + + :param dst: Destination + :param str: Source + :param pos: Index of *str* to copy from + +---------------------- + +.. function:: char dstr_end(const struct dstr *str) + + :param str: Dynamic string + :return: The last character of a dynamic string + +---------------------- + +.. function:: void dstr_from_wcs(struct dstr *dst, const wchar_t *wstr) + + Copies a wide string in to a dynamic string and converts it to UTF-8. + + :param dst: Dynamic string + :param wstr: Wide string + +---------------------- + +.. function:: wchar_t *dstr_to_wcs(const struct dstr *str) + + Converts a dynamic array to a wide string. Free with + :c:func:`bfree()`. + + :param str: Dynamic string + :return: Wide string allocation. Free with :c:func:`bfree()` + +---------------------- + +.. function:: void dstr_to_upper(struct dstr *str) + + Converts all characters within a dynamic array to uppercase. + + :param str: Dynamic string + +---------------------- + +.. function:: void dstr_to_lower(struct dstr *str) + + Converts all characters within a dynamic array to lowercase. + + :param str: Dynamic string diff --git a/docs/sphinx/reference-libobs-util-platform.rst b/docs/sphinx/reference-libobs-util-platform.rst new file mode 100644 index 000000000..6c059d250 --- /dev/null +++ b/docs/sphinx/reference-libobs-util-platform.rst @@ -0,0 +1,465 @@ +Platform Helpers +================ + +These functions/structures/types are used to perform actions that +typically don't have shared functions across different operating systems +and platforms. + +.. code:: cpp + + #include + + +File Functions +-------------- + +.. function:: FILE *os_wfopen(const wchar_t *path, const char *mode) + + Opens a file with a wide string path. + +---------------------- + +.. function:: FILE *os_fopen(const char *path, const char *mode) + + Opens a file with a UTF8 string path. + +---------------------- + +.. function:: int64_t os_fgetsize(FILE *file) + + Returns a file's size. + +---------------------- + +.. function:: int os_stat(const char *file, struct stat *st) + + Equivalent to the posix *stat* function. + +---------------------- + +.. function:: int os_fseeki64(FILE *file, int64_t offset, int origin) + + Equivalent to fseek. + +---------------------- + +.. function:: int64_t os_ftelli64(FILE *file) + + Gets the current file position. + +---------------------- + +.. function:: size_t os_fread_utf8(FILE *file, char **pstr) + + Reads a UTF8 encoded file and allocates a pointer to the UTF8 string. + +---------------------- + +.. function:: char *os_quick_read_utf8_file(const char *path) + + Reads a UTF8 encoded file and returns an allocated pointer to the + string. + +---------------------- + +.. function:: bool os_quick_write_utf8_file(const char *path, const char *str, size_t len, bool marker) + + Writes a UTF8 encoded file. + +---------------------- + +.. function:: bool os_quick_write_utf8_file_safe(const char *path, const char *str, size_t len, bool marker, const char *temp_ext, const char *backup_ext) + + Writes a UTF8 encoded file with overwrite corruption prevention. + +---------------------- + +.. function:: int64_t os_get_file_size(const char *path) + + Gets a file's size. + +---------------------- + +.. function:: int64_t os_get_free_space(const char *path) + + Gets free space of a specific file path. + +--------------------- + + +String Conversion Functions +--------------------------- + +.. function:: size_t os_utf8_to_wcs(const char *str, size_t len, wchar_t *dst, size_t dst_size) + + Converts a UTF8 string to a wide string. + +---------------------- + +.. function:: size_t os_wcs_to_utf8(const wchar_t *str, size_t len, char *dst, size_t dst_size) + + Converts a wide string to a UTF8 string. + +---------------------- + +.. function:: size_t os_utf8_to_wcs_ptr(const char *str, size_t len, wchar_t **pstr) + + Gets an bmalloc-allocated wide string converted from a UTF8 string. + +---------------------- + +.. function:: size_t os_wcs_to_utf8_ptr(const wchar_t *str, size_t len, char **pstr) + + Gets an bmalloc-allocated UTF8 string converted from a wide string. + +--------------------- + + +Number/String Conversion Functions +---------------------------------- + +.. function:: double os_strtod(const char *str) + + Converts a string to a double. + +---------------------- + +.. function:: int os_dtostr(double value, char *dst, size_t size) + + Converts a double to a string. + +--------------------- + + +Dynamic Link Library Functions +------------------------------ + +These functions are roughly equivalent to dlopen/dlsym/dlclose. + +.. function:: void *os_dlopen(const char *path) + + Opens a dynamic library. + +---------------------- + +.. function:: void *os_dlsym(void *module, const char *func) + + Returns a symbol from a dynamic library. + +---------------------- + +.. function:: void os_dlclose(void *module) + + Closes a dynamic library. + +--------------------- + + +CPU Usage Functions +------------------- + +.. function:: os_cpu_usage_info_t *os_cpu_usage_info_start(void) + + Creates a CPU usage information object. + +---------------------- + +.. function:: double os_cpu_usage_info_query(os_cpu_usage_info_t *info) + + Queries the current CPU usage. + +---------------------- + +.. function:: void os_cpu_usage_info_destroy(os_cpu_usage_info_t *info) + + Destroys a CPU usage information object. + +--------------------- + + +Sleep/Time Functions +-------------------- + +.. function:: bool os_sleepto_ns(uint64_t time_target) + + Sleeps to a specific time with high precision, in nanoseconds. + +--------------------- + +.. function:: void os_sleep_ms(uint32_t duration) + + Sleeps for a specific number of milliseconds. + +--------------------- + +.. function:: uint64_t os_gettime_ns(void) + + Gets the current high-precision system time, in nanoseconds. + +--------------------- + +Other Path/File Functions +------------------------- + +.. function:: int os_get_config_path(char *dst, size_t size, const char *name) + char *os_get_config_path_ptr(const char *name) + + Gets the user-specific application configuration data path. + +--------------------- + +.. function:: int os_get_program_data_path(char *dst, size_t size, const char *name) + char *os_get_program_data_path_ptr(const char *name) + + Gets the application configuration data path. + +--------------------- + +.. function:: bool os_file_exists(const char *path) + + Returns true if a file/directory exists, false otherwise. + +--------------------- + +.. function:: size_t os_get_abs_path(const char *path, char *abspath, size_t size) + char *os_get_abs_path_ptr(const char *path) + + Converts a relative path to an absolute path. + +--------------------- + +.. function:: const char *os_get_path_extension(const char *path) + + Returns the extension portion of a path string. + +--------------------- + +.. type:: typedef struct os_dir os_dir_t + + A directory object. + +.. type:: struct os_dirent + + A directory entry record. + +.. member:: char os_dirent.d_name[256] + + The directory entry name. + +.. member:: bool os_dirent.directory + + *true* if the entry is a directory. + +--------------------- + +.. function:: os_dir_t *os_opendir(const char *path) + + Opens a directory object to enumerate files within the directory. + +--------------------- + +.. function:: struct os_dirent *os_readdir(os_dir_t *dir) + + Returns the linked list of directory entries. + +--------------------- + +.. function:: void os_closedir(os_dir_t *dir) + + Closes a directory object. + +--------------------- + +.. type:: struct os_globent + + A glob entry. + +.. member:: char *os_globent.path + + The full path to the glob entry. + +.. member:: bool os_globent.directory + + *true* if the glob entry is a directory, *false* otherwise. + +.. type:: struct os_glob_info + + A glob object. + +.. member:: size_t os_glob_info.gl_pathc + + Number of glob entries. + +.. member:: struct os_globent *os_glob_info.gl_pathv + + Array of glob entries. + +.. type:: typedef struct os_glob_info os_glob_t + +--------------------- + +.. function:: int os_glob(const char *pattern, int flags, os_glob_t **pglob) + + Enumerates files based upon a glob string. + +--------------------- + +.. function:: void os_globfree(os_glob_t *pglob) + + Frees a glob object. + +--------------------- + +.. function:: int os_unlink(const char *path) + + Deletes a file. + +--------------------- + +.. function:: int os_rmdir(const char *path) + + Deletes a directory. + +--------------------- + +.. function:: char *os_getcwd(char *path, size_t size) + + Returns a new bmalloc-allocated path to the current working + directory. + +--------------------- + +.. function:: int os_chdir(const char *path) + + Changes the current working directory. + +--------------------- + +.. function:: int os_mkdir(const char *path) + + Creates a directory. + +--------------------- + +.. function:: int os_mkdirs(const char *path) + + Creates a full directory path if it doesn't exist. + +--------------------- + +.. function:: int os_rename(const char *old_path, const char *new_path) + + Renames a file. + +--------------------- + +.. function:: int os_copyfile(const char *file_in, const char *file_out) + + Copys a file. + +--------------------- + +.. function:: int os_safe_replace(const char *target_path, const char *from_path, const char *backup_path) + + Safely replaces a file. + +--------------------- + +.. function:: char *os_generate_formatted_filename(const char *extension, bool space, const char *format) + + Returns a new bmalloc-allocated filename generated from specific + formatting. + +--------------------- + + +Sleep-Inhibition Functions +-------------------------- + +These functions/types are used to inhibit the computer from going to +sleep. + +.. type:: struct os_inhibit_info +.. type:: typedef struct os_inhibit_info os_inhibit_t + +--------------------- + +.. function:: os_inhibit_t *os_inhibit_sleep_create(const char *reason) + + Creates a sleep inhibition object. + +--------------------- + +.. function:: bool os_inhibit_sleep_set_active(os_inhibit_t *info, bool active) + + Activates/deactivates a sleep inhibition object. + +--------------------- + +.. function:: void os_inhibit_sleep_destroy(os_inhibit_t *info) + + Destroys a sleep inhibition object. If the sleep inhibition object + was active, it will be deactivated. + +--------------------- + + +Other Functions +--------------- + +.. function:: void os_breakpoint(void) + + Triggers a debugger breakpoint (or crashes the program if no debugger + present). + +--------------------- + +.. function:: int os_get_physical_cores(void) + + Returns the number of physical cores available. + +--------------------- + +.. function:: int os_get_logical_cores(void) + + Returns the number of logical cores available. + +--------------------- + +.. function:: uint64_t os_get_sys_free_size(void) + + Returns the amount of memory available. + +--------------------- + +.. type:: struct os_proc_memory_usage + + Memory usage structure. + +.. member:: uint64_t os_proc_memory_usage.resident_size + + Resident size. + +.. member:: uint64_t os_proc_memory_usage.virtual_size + + Virtual size. + +.. type:: typedef struct os_proc_memory_usage os_proc_memory_usage_t + +--------------------- + +.. function:: bool os_get_proc_memory_usage(os_proc_memory_usage_t *usage) + + Gets memory usage of the current process. + +--------------------- + +.. function:: uint64_t os_get_proc_resident_size(void) + + Returns the resident memory size of the current process. + +--------------------- + +.. function:: uint64_t os_get_proc_virtual_size(void) + + Returns the virtual memory size of the current process. diff --git a/docs/sphinx/reference-libobs-util-profiler.rst b/docs/sphinx/reference-libobs-util-profiler.rst new file mode 100644 index 000000000..b749bf5f2 --- /dev/null +++ b/docs/sphinx/reference-libobs-util-profiler.rst @@ -0,0 +1,327 @@ +Profiler +======== + +The profiler is used to get information about program performance and +efficiency. + +.. type:: typedef struct profiler_snapshot profiler_snapshot_t +.. type:: typedef struct profiler_snapshot_entry profiler_snapshot_entry_t +.. type:: typedef struct profiler_name_store profiler_name_store_t +.. type:: typedef struct profiler_time_entry profiler_time_entry_t + +.. code:: cpp + + #include + + +Profiler Structures +------------------- + +.. type:: struct profiler_time_entry +.. member:: uint64_t profiler_time_entry.time_delta +.. member:: uint64_t profiler_time_entry.count + + +Profiler Control Functions +-------------------------- + +.. function:: void profiler_start(void) + + Starts the profiler. + +---------------------- + +.. function:: void profiler_stop(void) + + Stops the profiler. + +---------------------- + +.. function:: void profiler_print(profiler_snapshot_t *snap) + + Creates a profiler snapshot and saves it within *snap*. + + :param snap: A profiler snapshot object + +---------------------- + +.. function:: void profiler_print_time_between_calls(profiler_snapshot_t *snap) + + Creates a profiler snapshot of time between calls and saves it within + *snap*. + + :param snap: A profiler snapshot object + +---------------------- + +.. function:: void profiler_free(void) + + Frees the profiler. + +---------------------- + + +Profiling Functions +------------------- + +.. function:: void profile_register_root(const char *name, uint64_t expected_time_between_calls) + + Registers a root profile node. + + :param name: Name of the root profile node + :param expected_time_between_calls: The expected time between calls + of the profile root node, or 0 if + none. + +---------------------- + +.. function:: void profile_start(const char *name) + + Starts a profile node. This profile node will be a child of the last + node that was started. + + :param name: Name of the profile node + +---------------------- + +.. function:: void profile_end(const char *name) + + :param name: Name of the profile node + +---------------------- + +.. function:: void profile_reenable_thread(void) + + Because :c:func:`profiler_start()` can be called in a different + thread than the current thread, this is used to specify a point where + it's safe to re-enable profiling in the calling thread. Call this + when you have looped root profile nodes and need to specify a safe + point where the root profile node isn't active and the profiler can + start up in the current thread again. + +---------------------- + + +Profiler Name Storage Functions +------------------------------- + +.. function:: profiler_name_store_t *profiler_name_store_create(void) + + Creates a profiler name storage object. + + :return: Profiler name store object + +---------------------- + +.. function:: void profiler_name_store_free(profiler_name_store_t *store) + + Frees a profiler name storage object. + + :param store: Profiler name storage object + +---------------------- + +.. function:: const char *profile_store_name(profiler_name_store_t *store, const char *format, ...) + + Creates a formatted string and stores it within a profiler name + storage object. + + :param store: Profiler name storage object + :param format: Formatted string + :return: The string created from format specifications + +---------------------- + + +Profiler Data Access Functions +------------------------------ + +.. function:: profiler_snapshot_t *profile_snapshot_create(void) + + Creates a profile snapshot. Profiler snapshots are used to obtain + data about how the active profiles performed. + + :return: A profiler snapshot object + +---------------------- + +.. function:: void profile_snapshot_free(profiler_snapshot_t *snap) + + Frees a profiler snapshot object. + + :param snap: A profiler snapshot + +---------------------- + +.. function:: bool profiler_snapshot_dump_csv(const profiler_snapshot_t *snap, const char *filename) + + Creates a CSV file of the profiler snapshot. + + :param snap: A profiler snapshot + :param filename: The path to the CSV file to save + :return: *true* if successfuly written, *false* otherwise + +---------------------- + +.. function:: bool profiler_snapshot_dump_csv_gz(const profiler_snapshot_t *snap, const char *filename) + + Creates a gzipped CSV file of the profiler snapshot. + + :param snap: A profiler snapshot + :param filename: The path to the gzipped CSV file to save + :return: *true* if successfuly written, *false* otherwise + +---------------------- + +.. function:: size_t profiler_snapshot_num_roots(profiler_snapshot_t *snap) + + :param snap: A profiler snapshot + :return: Number of root profiler nodes in the snapshot + +---------------------- + +.. type:: typedef bool (*profiler_entry_enum_func)(void *context, profiler_snapshot_entry_t *entry) + + Profiler snapshot entry numeration callback + + :param context: Private data passed to this callback + :param entry: Profiler snapshot entry + :return: *true* to continue enumeration, *false* otherwise + +---------------------- + +.. function:: void profiler_snapshot_enumerate_roots(profiler_snapshot_t *snap, profiler_entry_enum_func func, void *context) + + Enumerates root profile nodes. + + :param snap: A profiler snapshot + :param func: Enumeration callback + :param context: Private data to pass to the callback + +---------------------- + +.. type:: typedef bool (*profiler_name_filter_func)(void *data, const char *name, bool *remove) + + Callback used to determine what profile nodes are removed/filtered. + + :param data: Private data passed to this callback + :param name: Profile node name to be filtered + :param remove: Used to determined whether the node should be removed + or not + :return: *true* to continue enumeration, *false* otherwise + +---------------------- + +.. function:: void profiler_snapshot_filter_roots(profiler_snapshot_t *snap, profiler_name_filter_func func, void *data) + + Removes/filters profile roots based upon their names. + + :param snap: A profiler snapshot + :param func: Enumeration callback to filter with + :param data: Private data to pass to the callback + +---------------------- + +.. function:: size_t profiler_snapshot_num_children(profiler_snapshot_entry_t *entry) + + :param entry: A profiler snapshot entry + :return: Number of children for the entry + +---------------------- + +.. function:: void profiler_snapshot_enumerate_children(profiler_snapshot_entry_t *entry, profiler_entry_enum_func func, void *context) + + Enumerates child entries of a profiler snapshot entry. + + :param entry: A profiler snapshot entry + :param func: Enumeration callback + :param context: Private data passed to the callback + +---------------------- + +.. function:: const char *profiler_snapshot_entry_name(profiler_snapshot_entry_t *entry) + + :param entry: A profiler snapshot entry + :return: The name of the profiler snapshot entry + +---------------------- + +.. function:: profiler_time_entries_t *profiler_snapshot_entry_times(profiler_snapshot_entry_t *entry) + + Gets the time entries for a snapshot entry. + + :param entry: A profiler snapshot entry + :return: An array of profiler time entries + +---------------------- + +.. function:: uint64_t profiler_snapshot_entry_min_time(profiler_snapshot_entry_t *entry) + + Gets the minimum time for a profiler snapshot entry. + + :param entry: A profiler snapshot entry + :return: The minimum time value for the snapshot entry + +---------------------- + +.. function:: uint64_t profiler_snapshot_entry_max_time(profiler_snapshot_entry_t *entry) + + Gets the maximum time for a profiler snapshot entry. + + :param entry: A profiler snapshot entry + :return: The maximum time value for the snapshot entry + +---------------------- + +.. function:: uint64_t profiler_snapshot_entry_overall_count(profiler_snapshot_entry_t *entry) + + Gets the overall count for a profiler snapshot entry. + + :param entry: A profiler snapshot entry + :return: The overall count value for the snapshot entry + +---------------------- + +.. function:: profiler_time_entries_t *profiler_snapshot_entry_times_between_calls(profiler_snapshot_entry_t *entry) + + Gets an array of time between calls for a profiler snapshot entry. + + :param entry: A profiler snapshot entry + :return: An array of profiler time entries + +---------------------- + +.. function:: uint64_t profiler_snapshot_entry_expected_time_between_calls(profiler_snapshot_entry_t *entry) + + Gets the expected time between calls for a profiler snapshot entry. + + :param entry: A profiler snapshot entry + :return: The expected time between calls for the snapshot entry, + or 0 if not set + +---------------------- + +.. function:: uint64_t profiler_snapshot_entry_min_time_between_calls(profiler_snapshot_entry_t *entry) + + Gets the minimum time seen between calls for a profiler snapshot entry. + + :param entry: A profiler snapshot entry + :return: The minimum time seen between calls for the snapshot entry + +---------------------- + +.. function:: uint64_t profiler_snapshot_entry_max_time_between_calls(profiler_snapshot_entry_t *entry) + + Gets the maximum time seen between calls for a profiler snapshot entry. + + :param entry: A profiler snapshot entry + :return: The maximum time seen between calls for the snapshot entry + +---------------------- + +.. function:: uint64_t profiler_snapshot_entry_overall_between_calls_count(profiler_snapshot_entry_t *entry) + + Gets the overall time between calls for a profiler snapshot entry. + + :param entry: A profiler snapshot entry + :return: The overall time between calls for the snapshot entry diff --git a/docs/sphinx/reference-libobs-util-serializers.rst b/docs/sphinx/reference-libobs-util-serializers.rst new file mode 100644 index 000000000..51c6a5f0c --- /dev/null +++ b/docs/sphinx/reference-libobs-util-serializers.rst @@ -0,0 +1,171 @@ +Serializer +========== + +General programmable serialization functions. (A shared interface to +various reading/writing to/from different inputs/outputs) + +.. code:: cpp + + #include + +Serializer Structure (struct serializer) +---------------------------------------- + +.. type:: struct serializer +.. member:: void *serializer.data +.. member:: size_t (*serializer.read)(void *, void *, size_t) +.. member:: size_t (*serializer.write)(void *, const void *, size_t) +.. member:: int64_t (*serializer.seek)(void *, int64_t, enum serialize_seek_type) +.. member:: int64_t (*serializer.get_pos)(void *) + +Serializer Inline Functions +--------------------------- + +.. function:: size_t s_read(struct serializer *s, void *data, size_t size) + +--------------------- + +.. function:: size_t s_write(struct serializer *s, const void *data, size_t size) + +--------------------- + +.. function:: size_t serialize(struct serializer *s, void *data, size_t len) + +--------------------- + +.. function:: int64_t serializer_seek(struct serializer *s, int64_t offset, enum serialize_seek_type seek_type) + +--------------------- + +.. function:: int64_t serializer_get_pos(struct serializer *s) + +--------------------- + +.. function:: void s_w8(struct serializer *s, uint8_t u8) + +--------------------- + +.. function:: void s_wl16(struct serializer *s, uint16_t u16) + +--------------------- + +.. function:: void s_wl32(struct serializer *s, uint32_t u32) + +--------------------- + +.. function:: void s_wl64(struct serializer *s, uint64_t u64) + +--------------------- + +.. function:: void s_wlf(struct serializer *s, float f) + +--------------------- + +.. function:: void s_wld(struct serializer *s, double d) + +--------------------- + +.. function:: void s_wb16(struct serializer *s, uint16_t u16) + +--------------------- + +.. function:: void s_wb24(struct serializer *s, uint32_t u24) + +--------------------- + +.. function:: void s_wb32(struct serializer *s, uint32_t u32) + +--------------------- + +.. function:: void s_wb64(struct serializer *s, uint64_t u64) + +--------------------- + +.. function:: void s_wbf(struct serializer *s, float f) + +--------------------- + +.. function:: void s_wbd(struct serializer *s, double d) + +--------------------- + + +Array Output Serializer +======================= + +Provides an output serializer used with dynamic arrays. + +.. code:: cpp + + #include + +Array Output Serializer Structure (struct array_output_data) +------------------------------------------------------------ + +.. type:: struct array_output_data + +.. member:: DARRAY(uint8_t) array_output_data.bytes + +Array Output Serializer Functions +--------------------------------- + +.. function:: void array_output_serializer_init(struct serializer *s, struct array_output_data *data) + +--------------------- + +.. function:: void array_output_serializer_free(struct array_output_data *data) + +--------------------- + + +File Input/Output Serializers +============================= + +Provides file reading/writing serializers. + +.. code:: cpp + + #include + + +File Input Serializer Functions +------------------------------- + +.. function:: bool file_input_serializer_init(struct serializer *s, const char *path) + + Initializes a file input serializer. + + :return: *true* if file opened successfully, *false* otherwise + +--------------------- + +.. function:: void file_input_serializer_free(struct serializer *s) + + Frees a file input serializer. + +--------------------- + + +File Output Serializer Functions +-------------------------------- + +.. function:: bool file_output_serializer_init(struct serializer *s, const char *path) + + Initializes a file output serializer. + + :return: *true* if file created successfully, *false* otherwise + +--------------------- + +.. function:: bool file_output_serializer_init_safe(struct serializer *s, const char *path, const char *temp_ext) + + Initializes and safely writes to a temporary file (determined by the + temporary extension) until freed. + + :return: *true* if file created successfully, *false* otherwise + +--------------------- + +.. function:: void file_output_serializer_free(struct serializer *s) + + Frees the file output serializer and saves the file. diff --git a/docs/sphinx/reference-libobs-util-text-lookup.rst b/docs/sphinx/reference-libobs-util-text-lookup.rst new file mode 100644 index 000000000..5b5f1530d --- /dev/null +++ b/docs/sphinx/reference-libobs-util-text-lookup.rst @@ -0,0 +1,56 @@ +Text Lookup Interface +===================== + +Used for storing and looking up localized strings. Uses an ini-file +like file format for localization lookup. + +.. type:: struct text_lookup lookup_t + +.. code:: cpp + + #include + + +Text Lookup Functions +--------------------- + +.. function:: lookup_t *text_lookup_create(const char *path) + + Creates a text lookup object from a text lookup file. + + :param path: Path to the localization file + :return: New lookup object, or *NULL* if an error occurred + +--------------------- + +.. function:: bool text_lookup_add(lookup_t *lookup, const char *path) + + Adds text lookup from a text lookup file and replaces any values. + For example, you would load a default fallback language such as + english with :c:func:`text_lookup_create()`, and then call this + function to load the actual desired language in case the desired + language isn't fully translated. + + :param lookup: Lookup object + :param path: Path to the localization file + :return: *true* if successful, *false* otherwise + +--------------------- + +.. function:: void text_lookup_destroy(lookup_t *lookup) + + Destroys a text lookup object. + + :param lookup: Lookup object + +--------------------- + +.. function:: bool text_lookup_getstr(lookup_t *lookup, const char *lookup_val, const char **out) + + Gets a localized text string. + + :param lookup: Lookup object + :param lookup_val: Value to look up + :param out: Pointer that receives the translated string + pointer + :return: *true* if the value exists, *false* otherwise diff --git a/docs/sphinx/reference-libobs-util-threading.rst b/docs/sphinx/reference-libobs-util-threading.rst new file mode 100644 index 000000000..badd029f8 --- /dev/null +++ b/docs/sphinx/reference-libobs-util-threading.rst @@ -0,0 +1,193 @@ +Threading +========= + +Libobs provides a number of helper functions/types specifically for +threading. The threading header will additionally provide access to +pthread functions even on windows. + +.. code:: cpp + + #include + + +Threading Types +--------------- + +.. type:: os_event_t +.. type:: os_sem_t + + +General Thread Functions +------------------------ + +.. function:: void os_set_thread_name(const char *name) + + Sets the name of the current thread. + +---------------------- + + +Event Functions +--------------- + +.. function:: int os_event_init(os_event_t **event, enum os_event_type type) + + Creates an event object. + + :param event: Pointer that receives a pointer to a new event object + :param type: Can be one of the following values: + + - OS_EVENT_TYPE_AUTO - Automatically resets when + signaled + - OS_EVENT_TYPE_MANUAL - Stays signaled until the + :c:func:`os_event_reset()` function is called + + :return: 0 if successful, negative otherwise + +---------------------- + +.. function:: void os_event_destroy(os_event_t *event) + + Destroys an event. + + :param event: An event object + +---------------------- + +.. function:: int os_event_wait(os_event_t *event) + + Waits for an event to signal. + + :param event: An event object + :return: 0 if successful, negative otherwise + +---------------------- + +.. function:: int os_event_timedwait(os_event_t *event, unsigned long milliseconds) + + Waits a specific duration for an event to signal. + + :param event: An event object + :param milliseconds: Milliseconds to wait + :return: Can be one of the following values: + + - 0 - successful + - ETIMEDOUT - Timed out + - EINVAL - An unexpected error occured + +---------------------- + +.. function:: int os_event_try(os_event_t *event) + + Checks for a signaled state without waiting. + + :param event: An event object + :return: Can be one of the following values: + + - 0 - successful + - EAGAIN - The event is not signaled + - EINVAL - An unexpected error occured + +---------------------- + +.. function:: int os_event_signal(os_event_t *event) + + Signals the event. + + :param event: An event object + :return: 0 if successful, negative otherwise + +---------------------- + +.. function:: void os_event_reset(os_event_t *event) + + Resets the signaled state of the event. + + :param event: An event object + +---------------------- + + +Semaphore Functions +------------------- + +.. function:: int os_sem_init(os_sem_t **sem, int value) + + Creates a semaphore object. + + :param sem: Pointer that receives a pointer to the semaphore object + :param value: Initial value of the semaphore + :return: 0 if successful, negative otherwise + +---------------------- + +.. function:: void os_sem_destroy(os_sem_t *sem) + + Destroys a sempahore object. + + :param sem: Semaphore object + +---------------------- + +.. function:: int os_sem_post(os_sem_t *sem) + + Increments the semaphore. + + :param sem: Semaphore object + :return: 0 if successful, negative otherwise + +---------------------- + +.. function:: int os_sem_wait(os_sem_t *sem) + + Decrements the semphore or waits until the semaphore has been + incremented. + + :param sem: Semaphore object + :return: 0 if successful, negative otherwise + +--------------------- + + +Atomic Inline Functions +----------------------- + +.. function:: long os_atomic_inc_long(volatile long *val) + + Increments a long variable atomically. + +--------------------- + +.. function:: long os_atomic_dec_long(volatile long *val) + + Decrements a long variable atomically. + +--------------------- + +.. function:: long os_atomic_set_long(volatile long *ptr, long val) + + Sets the value of a long variable atomically. + +--------------------- + +.. function:: long os_atomic_load_long(const volatile long *ptr) + + Gets the value of a long variable atomically. + +--------------------- + +.. function:: bool os_atomic_compare_swap_long(volatile long *val, long old_val, long new_val) + + Swaps the value of a long variable atomically if its value matches. + +--------------------- + +.. function:: bool os_atomic_set_bool(volatile bool *ptr, bool val) + + Sets the value of a boolean variable atomically. + +--------------------- + +.. function:: bool os_atomic_load_bool(const volatile bool *ptr) + + Gets the value of a boolean variable atomically. diff --git a/docs/sphinx/reference-libobs-util.rst b/docs/sphinx/reference-libobs-util.rst new file mode 100644 index 000000000..1490bc205 --- /dev/null +++ b/docs/sphinx/reference-libobs-util.rst @@ -0,0 +1,17 @@ +Platform/Utility API Reference (libobs/util) +============================================ + +.. toctree:: + :maxdepth: 2 + + reference-libobs-util-base + reference-libobs-util-bmem + reference-libobs-util-circlebuf + reference-libobs-util-config-file + reference-libobs-util-darray + reference-libobs-util-dstr + reference-libobs-util-platform + reference-libobs-util-profiler + reference-libobs-util-serializers + reference-libobs-util-text-lookup + reference-libobs-util-threading diff --git a/docs/sphinx/reference-modules.rst b/docs/sphinx/reference-modules.rst new file mode 100644 index 000000000..da569a39d --- /dev/null +++ b/docs/sphinx/reference-modules.rst @@ -0,0 +1,310 @@ +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 + + +Module Macros +------------- + +These macros are used within custom plugin modules. + +.. function:: OBS_DECLARE_MODULE() + + Declares a libobs module. Exports important core module functions + related to the module itself, OBS version, etc. + +--------------------- + +.. function:: 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 the module is unloaded. + +--------------------- + +.. 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 useable 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 + +--------------------- + +.. 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_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_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 diff --git a/docs/sphinx/reference-outputs.rst b/docs/sphinx/reference-outputs.rst new file mode 100644 index 000000000..6d671fbcc --- /dev/null +++ b/docs/sphinx/reference-outputs.rst @@ -0,0 +1,778 @@ +Output API Reference (obs_output_t) +=================================== + +Outputs allow the ability to output the currently rendering audio/video. +Streaming and recording are two common examples of outputs, but not the +only types of outputs. Outputs can receive the raw data or receive +encoded data. The `libobs/obs-output.h`_ file is the dedicated header +for implementing outputs + +.. type:: obs_output_t + + A reference-counted output object. + +.. type:: obs_weak_output_t + + A weak reference to an output object. + +.. code:: cpp + + #include + + +Output Definition Structure (obs_output_info) +--------------------------------------------- + +.. type:: struct obs_output_info + + Output definition structure. + +.. member:: const char *obs_output_info.id + + Unique string identifier for the source (required). + +.. member:: uint32_t obs_output_info.flags + + Output capability flags (required). + + (Author's note: This should be renamed to "capability_flags") + + A bitwise OR combination of one or more of the following values: + + - **OBS_OUTPUT_VIDEO** - Can output video. + + - **OBS_OUTPUT_AUDIO** - Can output audio. + + - **OBS_OUTPUT_AV** - Combines OBS_OUTPUT_VIDEO and OBS_OUTPUT_AUDIO. + + - **OBS_OUTPUT_ENCODED** - Output is encoded. + + When this capability flag is used, the output must have encoders + assigned to it via the :c:func:`obs_output_set_video_encoder()` + and/or :c:func:`obs_output_set_audio_encoder()` functions in order + to be started. + + - **OBS_OUTPUT_SERVICE** - Output requires a service object. + + When this capability flag is used, the output must have a service + assigned to it via the :c:func:`obs_output_set_service()` function + in order to be started. + + This is usually used with live streaming outputs that stream to + specific services. + + - **OBS_OUTPUT_MULTI_TRACK** - Output supports multiple audio tracks. + + When this capability flag is used, specifies that this output + supports multiple encoded audio tracks simultaneously. + +.. member:: const char *(*obs_output_info.get_name)(void *type_data) + + Get the translated name of the output type. + + :param type_data: The type_data variable of this structure + :return: The translated name of the output type + +.. member:: void *(*obs_output_info.create)(obs_data_t *settings, obs_output_t *output) + + Creates the implementation data for the output. + + :param settings: Settings to initialize the output with + :param output: Output that this data is associated with + :return: The implementation data associated with this output + +.. member:: void (*obs_output_info.destroy)(void *data) + + Destroys the implementation data for the output. + +.. member:: bool (*obs_output_info.start)(void *data) + + Starts the output. If needed, this function can spawn a thread, + return *true* immediately, and then signal for failure later. + + :return: *true* if successful or deferring to a signal to indicate + failure, *false* on failure to start + +.. member:: void (*obs_output_info.stop)(void *data, uint64_t ts) + + Requests an output to stop at a specified time. The *ts* parameter + indicates when the stop should occur. Output will actually stop when + either the :c:func:`obs_output_end_data_capture()` or + :c:func:`obs_output_signal_stop()` functions are called. If *ts* is + 0, an immediate stop was requested. + + :param ts: The timestamp to stop. If 0, the output should attempt to + stop immediately rather than wait for any more data to + process + +.. member:: void (*obs_output_info.raw_video)(void *data, struct video_data *frame) + + This is called when the output receives raw video data. Only applies + to outputs that are not encoded. + + :param frame: The raw video frame + +.. member:: void (*obs_output_info.raw_audio)(void *data, struct audio_data *frames) + + This is called when the output recieves raw audio data. Only applies + to outputs that are not encoded. + + :param frames: The raw audio frames + +.. member:: void (*obs_output_info.encoded_packet)(void *data, struct encoder_packet *packet) + + This is called when the output receives encoded video/audio data. + Only applies to outputs that are encoded. Packets will always be + given in monotonic timestamp order. + + :param packet: The video or audio packet + +.. member:: void (*obs_output_info.update)(void *data, obs_data_t *settings) + + Updates the settings for this output. + + (Optional) + + :param settings: New settings for this output + +.. member:: void (*obs_output_info.get_defaults)(obs_data_t *settings) + void (*obs_output_info.get_defaults2)(void *type_data, obs_data_t *settings) + + Sets the default settings for this output. + + (Optional) + + :param settings: Default settings. Call obs_data_set_default* + functions on this object to set default setting + values + +.. member:: obs_properties_t *(*obs_output_info.get_properties)(void *data) + obs_properties_t *(*obs_output_info.get_properties2)(void *data, void *type_data) + + Gets the property information of this output. + + (Optional) + + :return: The properties of the output + +.. member:: void (*obs_output_info.pause)(void *data) + + Pauses the output (if the output supports pausing). + + (Author's note: This is currently unimplemented) + + (Optional) + +.. member:: uint64_t (*obs_output_info.get_total_bytes)(void *data) + + Returns the number of total bytes processed by this output. + + (Optional) + + :return: Total bytes processed by this output since it started + +.. member:: int (*obs_output_info.get_dropped_frames)(void *data) + + Returns the number of dropped frames. + + (Optional) + + :return: Number of dropped frames due to network congestion by this + output since it started + +.. member:: void *obs_output_info.type_data + void (*obs_output_info.free_type_data)(void *type_data) + + Private data associated with this entry. Note that this is not the + same as the implementation data; this is used to differentiate + between two different types if the same callbacks are used for more + than one different type. + + (Optional) + +.. member:: float (*obs_output_info.get_congestion)(void *data) + + This function is used to indicate how currently congested the output + is. Useful for visualizing how much data is backed up on streaming + outputs. + + (Optional) + + :return: Current congestion value (0.0f..1.0f) + +.. member:: int (*obs_output_info.get_connect_time_ms)(void *data) + + This function is used to determine how many milliseconds it took to + connect to its current server. + + (Optional) + + :return: Milliseconds it took to connect to its current server + +.. member:: const char *obs_output_info.encoded_video_codecs + const char *obs_output_info.encoded_audio_codecs + + This variable specifies which codecs are supported by an encoded + output, separated by semicolon. + + (Optional, though recommended) + +.. _output_signal_handler_reference: + +Output Signals +-------------- + +**start** (ptr output) + + Called when the output starts. + +**stop** (ptr output, int code) + + Called when the output stops. + + :Parameters: - **code** - Can be one of the following values: + + | OBS_OUTPUT_SUCCESS - Successfuly stopped + | OBS_OUTPUT_BAD_PATH - The specified path was invalid + | OBS_OUTPUT_CONNECT_FAILED - Failed to connect to a server + | OBS_OUTPUT_INVALID_STREAM - Invalid stream path + | OBS_OUTPUT_ERROR - Generic error + | OBS_OUTPUT_DISCONNECTED - Unexpectedly disconnected + | OBS_OUTPUT_UNSUPPORTED - The settings, video/audio format, or codecs are unsupported by this output + | OBS_OUTPUT_NO_SPACE - Ran out of disk space + +**starting** (ptr output) + + Called when the output is starting. + +**stopping** (ptr output) + + Called when the output is stopping. + +**activate** (ptr output) + + Called when the output activates (starts capturing data). + +**deactivate** (ptr output) + + Called when the output deactivates (stops capturing data). + +**reconnect** (ptr output) + + Called when the output is reconnecting. + +**reconnect_success** (ptr output) + + Called when the output has successfully reconnected. + +General Output Functions +------------------------ + +.. function:: void obs_register_output(struct obs_output_info *info) + + Registers an output type. Typically used in + :c:func:`obs_module_load()` or in the program's initialization phase. + +--------------------- + +.. function:: const char *obs_output_get_display_name(const char *id) + + Calls the :c:member:`obs_output_info.get_name` callback to get the + translated display name of an output type. + + :param id: The output type string identifier + :return: The translated display name of an output type + +--------------------- + +.. function:: obs_output_t *obs_output_create(const char *id, const char *name, obs_data_t *settings, obs_data_t *hotkey_data) + + Creates an output with the specified settings. + + The "output" context is used for anything related to outputting the + final video/audio mix (E.g. streaming or recording). Use + obs_output_release to release it. + + :param id: The output type string identifier + :param name: The desired name of the output. If this is + not unique, it will be made to be unique + :param settings: The settings for the output, or *NULL* if + none + :param hotkey_data: Saved hotkey data for the output, or *NULL* + if none + :return: A reference to the newly created output, or + *NULL* if failed + +--------------------- + +.. function:: void obs_output_addref(obs_output_t *output) + void obs_output_release(obs_output_t *output) + + Adds/releases a reference to an output. When the last reference is + released, the output is destroyed. + +--------------------- + +.. function:: obs_weak_output_t *obs_output_get_weak_output(obs_output_t *output) + obs_output_t *obs_weak_output_get_output(obs_weak_output_t *weak) + + These functions are used to get a weak reference from a strong output + reference, or a strong output reference from a weak reference. If + the output is destroyed, *obs_weak_output_get_output* will return + *NULL*. + +--------------------- + +.. function:: void obs_weak_output_addref(obs_weak_output_t *weak) + void obs_weak_output_release(obs_weak_output_t *weak) + + Adds/releases a weak reference to an output. + +--------------------- + +.. function:: const char *obs_output_get_name(const obs_output_t *output) + + :return: The name of the output + +--------------------- + +.. function:: bool obs_output_start(obs_output_t *output) + + Starts the output. + + :return: *true* if output successfuly started, *false* otherwise. If + the output failed to start, + :c:func:`obs_output_get_last_error()` may contain a specific + error string related to the reason + +--------------------- + +.. function:: void obs_output_stop(obs_output_t *output) + + Requests the output to stop. The output will wait until all data is + sent up until the time the call was made, then when the output has + successfully stopped, it will send the "stop" signal. See + :ref:`output_signal_handler_reference` for more information on output + signals. + +--------------------- + +.. function:: void obs_output_set_delay(obs_output_t *output, uint32_t delay_sec, uint32_t flags) + + Sets the current output delay, in seconds (if the output supports delay) + + If delay is currently active, it will set the delay value, but will not + affect the current delay, it will only affect the next time the output is + activated. + + :param delay_sec: Amount to delay the output, in seconds + :param flags: | Can be 0 or a combination of one of the following values: + | OBS_OUTPUT_DELAY_PRESERVE - On reconnection, start where it left of on reconnection. Note however that this option will consume extra memory to continually increase delay while waiting to reconnect + +--------------------- + +.. function:: uint32_t obs_output_get_delay(const obs_output_t *output) + + Gets the currently set delay value, in seconds. + +--------------------- + +.. function:: uint32_t obs_output_get_active_delay(const obs_output_t *output) + + If delay is active, gets the currently active delay value, in + seconds. The active delay can increase if the + OBS_OUTPUT_DELAY_PRESERVE flag was set when setting a delay. + +--------------------- + +.. function:: void obs_output_force_stop(obs_output_t *output) + + Attempts to get the output to stop immediately without waiting for + data to send. + +--------------------- + +.. function:: bool obs_output_active(const obs_output_t *output) + + :return: *true* if the output is currently active, *false* otherwise + +--------------------- + +.. function:: obs_data_t *obs_output_defaults(const char *id) + + :return: An incremented reference to the output's default settings + +--------------------- + +.. function:: obs_properties_t *obs_output_properties(const obs_output_t *output) + obs_properties_t *obs_get_output_properties(const char *id) + + Use these functions to get the properties of an output or output + type. Properties are optionally used (if desired) to automatically + generate user interface widgets to allow users to update settings. + + :return: The properties list for a specific existing output. Free + with :c:func:`obs_properties_destroy()` + +--------------------- + +.. function:: void obs_output_update(obs_output_t *output, obs_data_t *settings) + + Updates the settings for this output context. + +--------------------- + +.. function:: bool obs_output_can_pause(const obs_output_t *output) + + :return: *true* if the output can be paused, *false* otherwise + +--------------------- + +.. function:: void obs_output_pause(obs_output_t *output) + + Pause an output (if supported by the output). + + (Author's Note: Not yet implemented) + +--------------------- + +.. function:: obs_data_t *obs_output_get_settings(const obs_output_t *output) + + :return: An incremented reference to the output's settings + +--------------------- + +.. function:: signal_handler_t *obs_output_get_signal_handler(const obs_output_t *output) + + :return: The signal handler of the output + +--------------------- + +.. function:: proc_handler_t *obs_output_get_proc_handler(const obs_output_t *output) + + :return: The procedure handler of the output + +--------------------- + +.. function:: void obs_output_set_media(obs_output_t *output, video_t *video, audio_t *audio) + + Sets the current video/audio handlers for the output (typically + :c:func:`obs_get_video()` and :c:func:`obs_get_audio()`). Only used + with raw outputs so they can catch the raw video/audio frames. + +--------------------- + +.. function:: video_t *obs_output_video(const obs_output_t *output) + audio_t *obs_output_audio(const obs_output_t *output) + + Gets the current video/audio handlers for the output. + +--------------------- + +.. function:: void obs_output_set_mixer(obs_output_t *output, size_t mixer_idx) + size_t obs_output_get_mixer(const obs_output_t *output) + + Sets/gets the current audio mixer for non-encoded outputs. + +--------------------- + +.. function:: void obs_output_set_video_encoder(obs_output_t *output, obs_encoder_t *encoder) + void obs_output_set_audio_encoder(obs_output_t *output, obs_encoder_t *encoder, size_t idx) + + Sets the video/audio encoders for an encoded output. + + :param encoder: The video/audio encoder + :param idx: The audio encoder index if the output supports + multiple audio streams at once + +--------------------- + +.. function:: obs_encoder_t *obs_output_get_video_encoder(const obs_output_t *output) + obs_encoder_t *obs_output_get_audio_encoder(const obs_output_t *output, size_t idx) + + Gets the video/audio encoders for an encoded output. + + :param idx: The audio encoder index if the output supports + multiple audio streams at once + :return: The video/audio encoder. The reference is not + incremented + +--------------------- + +.. function:: void obs_output_set_service(obs_output_t *output, obs_service_t *service) + obs_service_t *obs_output_get_service(const obs_output_t *output) + + Sets/gets the service for outputs that require services (such as RTMP + outputs). *obs_output_get_service* does not return an incremented + reference. + +--------------------- + +.. function:: void obs_output_set_reconnect_settings(obs_output_t *output, int retry_count, int retry_sec); + + Sets the auto-reconnect settings for outputs that support it. The + retry time will double on each retry to prevent overloading services. + + :param retry_count: Maximum retry count. Set to 0 to disable + reconnecting + :param retry_sec: Starting retry wait duration, in seconds + +--------------------- + +.. function:: uint64_t obs_output_get_total_bytes(const obs_output_t *output) + + :return: Total bytes sent/processed + +--------------------- + +.. function:: int obs_output_get_frames_dropped(const obs_output_t *output) + + :return: Number of frames that were dropped due to network congestion + +--------------------- + +.. function:: int obs_output_get_total_frames(const obs_output_t *output) + + :return: Total frames sent/processed + +--------------------- + +.. function:: void obs_output_set_preferred_size(obs_output_t *output, uint32_t width, uint32_t height) + + Sets the preferred scaled resolution for this output. Set width and height + to 0 to disable scaling. + + If this output uses an encoder, it will call obs_encoder_set_scaled_size on + the encoder before the stream is started. If the encoder is already active, + then this function will trigger a warning and do nothing. + +--------------------- + +.. function:: uint32_t obs_output_get_width(const obs_output_t *output) + uint32_t obs_output_get_height(const obs_output_t *output) + + :return: The width/height of the output + +--------------------- + +.. function:: float obs_output_get_congestion(obs_output_t *output) + + :return: The congestion value. This value is used to visualize the + current congestion of a network output. For example, if + there is no congestion, the value will be 0.0f, if it's + fully congested, the value will be 1.0f + +--------------------- + +.. function:: int obs_output_get_connect_time_ms(obs_output_t *output) + + :return: How long the output took to connect to a server, in + milliseconds + +--------------------- + +.. function:: bool obs_output_reconnecting(const obs_output_t *output) + + :return: *true* if the output is currently reconnecting to a server, + *false* otherwise + +--------------------- + +.. function:: const char *obs_output_get_supported_video_codecs(const obs_output_t *output) + const char *obs_output_get_supported_audio_codecs(const obs_output_t *output) + + :return: Supported video/audio codecs of an encoded output, separated + by semicolen + +--------------------- + +Functions used by outputs +------------------------- + +.. function:: void obs_output_set_last_error(obs_output_t *output, const char *message) + const char *obs_output_get_last_error(obs_output_t *output) + + Sets/gets the translated error message that is presented to a user in + case of disconnection, inability to connect, etc. + +--------------------- + +.. function:: void obs_output_set_video_conversion(obs_output_t *output, const struct video_scale_info *conversion) + + Optionally sets the video conversion information. Only used by raw + outputs. + + Relevant data types used with this function: + +.. code:: cpp + + enum video_format { + VIDEO_FORMAT_NONE, + + /* planar 420 format */ + VIDEO_FORMAT_I420, /* three-plane */ + VIDEO_FORMAT_NV12, /* two-plane, luma and packed chroma */ + + /* packed 422 formats */ + VIDEO_FORMAT_YVYU, + VIDEO_FORMAT_YUY2, /* YUYV */ + VIDEO_FORMAT_UYVY, + + /* packed uncompressed formats */ + VIDEO_FORMAT_RGBA, + VIDEO_FORMAT_BGRA, + VIDEO_FORMAT_BGRX, + VIDEO_FORMAT_Y800, /* grayscale */ + + /* planar 4:4:4 */ + VIDEO_FORMAT_I444, + }; + + enum video_colorspace { + VIDEO_CS_DEFAULT, + VIDEO_CS_601, + VIDEO_CS_709, + }; + + enum video_range_type { + VIDEO_RANGE_DEFAULT, + VIDEO_RANGE_PARTIAL, + VIDEO_RANGE_FULL + }; + + struct video_scale_info { + enum video_format format; + uint32_t width; + uint32_t height; + enum video_range_type range; + enum video_colorspace colorspace; + }; + +--------------------- + +.. function:: void obs_output_set_audio_conversion(obs_output_t *output, const struct audio_convert_info *conversion) + + Optionally sets the audio conversion information. Only used by raw + outputs. + + Relevant data types used with this function: + +.. code:: cpp + + enum audio_format { + AUDIO_FORMAT_UNKNOWN, + + AUDIO_FORMAT_U8BIT, + AUDIO_FORMAT_16BIT, + AUDIO_FORMAT_32BIT, + AUDIO_FORMAT_FLOAT, + + AUDIO_FORMAT_U8BIT_PLANAR, + AUDIO_FORMAT_16BIT_PLANAR, + AUDIO_FORMAT_32BIT_PLANAR, + AUDIO_FORMAT_FLOAT_PLANAR, + }; + + enum speaker_layout { + SPEAKERS_UNKNOWN, + SPEAKERS_MONO, + SPEAKERS_STEREO, + SPEAKERS_2POINT1, + SPEAKERS_QUAD, + SPEAKERS_4POINT1, + SPEAKERS_5POINT1, + SPEAKERS_5POINT1_SURROUND, + SPEAKERS_7POINT1, + SPEAKERS_7POINT1_SURROUND, + SPEAKERS_SURROUND, + }; + + struct audio_convert_info { + uint32_t samples_per_sec; + enum audio_format format; + enum speaker_layout speakers; + }; + +--------------------- + +.. function:: bool obs_output_can_begin_data_capture(const obs_output_t *output, uint32_t flags) + + Determines whether video/audio capture (encoded or raw) is able to + start. Call this before initializing any output data to ensure that + the output can start. + + :param flags: Set to 0 to initialize both audio/video, otherwise a + bitwise OR combination of OBS_OUTPUT_VIDEO and/or + OBS_OUTPUT_AUDIO + :return: *true* if data capture can begin + +--------------------- + +.. function:: bool obs_output_initialize_encoders(obs_output_t *output, uint32_t flags) + + Initializes any encoders/services associated with the output. This + must be called for encoded outputs before calling + :c:func:`obs_output_begin_data_capture()`. + + :param flags: Set to 0 to initialize both audio/video, otherwise a + bitwise OR combination of OBS_OUTPUT_VIDEO and/or + OBS_OUTPUT_AUDIO + :return: *true* if successful, *false* otherwise + +--------------------- + +.. function:: bool obs_output_begin_data_capture(obs_output_t *output, uint32_t flags) + + Begins data capture from raw media or encoders. This is typically + when the output actually activates (starts) internally. Video/audio + data will start being sent to the callbacks of the output. + + :param flags: Set to 0 to initialize both audio/video, otherwise a + bitwise OR combination of OBS_OUTPUT_VIDEO and/or + OBS_OUTPUT_AUDIO + :return: *true* if successful, *false* otherwise. Typically the + return value does not need to be checked if + :c:func:`obs_output_can_begin_data_capture()` was + called + +--------------------- + +.. function:: void obs_output_end_data_capture(obs_output_t *output) + + Ends data capture of an output. This is typically when the output + actually intentionally deactivates (stops). Video/audio data will + stop being sent to the callbacks of the output. The output will + trigger the "stop" signal with the OBS_OUTPUT_SUCCESS code to + indicate that the output has stopped successfully. See + :ref:`output_signal_handler_reference` for more information on output + signals. + +--------------------- + +.. function:: void obs_output_signal_stop(obs_output_t *output, int code) + + Ends data capture of an output with an output code, indicating that + the output stopped unexpectedly. This is typically used if for + example the server was disconnected for some reason, or if there was + an error saving to file. The output will trigger the "stop" signal + with the the desired code to indicate that the output has stopped + successfully. See :ref:`output_signal_handler_reference` for more + information on output signals. + + :c:func:`obs_output_set_last_error()` may be used in conjunction with + these error codes to optionally relay more detailed error information + to the user + + :param code: | Can be one of the following values: + | OBS_OUTPUT_SUCCESS - Successfuly stopped + | OBS_OUTPUT_BAD_PATH - The specified path was invalid + | OBS_OUTPUT_CONNECT_FAILED - Failed to connect to a server + | OBS_OUTPUT_INVALID_STREAM - Invalid stream path + | OBS_OUTPUT_ERROR - Generic error + | OBS_OUTPUT_DISCONNECTED - Unexpectedly disconnected + | OBS_OUTPUT_UNSUPPORTED - The settings, video/audio format, or codecs are unsupported by this output + | OBS_OUTPUT_NO_SPACE - Ran out of disk space + +.. --------------------------------------------------------------------------- + +.. _libobs/obs-output.h: https://github.com/jp9000/obs-studio/blob/master/libobs/obs-output.h diff --git a/docs/sphinx/reference-properties.rst b/docs/sphinx/reference-properties.rst new file mode 100644 index 000000000..d998789c5 --- /dev/null +++ b/docs/sphinx/reference-properties.rst @@ -0,0 +1,597 @@ +Properties API Reference (obs_properties_t) +=========================================== + +Properties are used to enumerate available settings for a libobs object. +Typically this is used to automatically generate user interface widgets, +though can be used to enumerate available and/or valid values for +specific settings as well. + +.. type:: obs_properties_t + + Properties object (not reference counted). + +.. type:: obs_property_t + + A property object (not reference counted). + +.. code:: cpp + + #include + + +General Functions +----------------- + +.. function:: obs_properties_t *obs_properties_create(void) + + :return: A new properties object. + +--------------------- + +.. function:: obs_properties_t *obs_properties_create_param(void *param, void (*destroy)(void *param)) + + Creates a new properties object with specific private data *param* + associated with the object, and is automatically freed with the + object when the properties are destroyed via the *destroy* function. + + :return: A new properties object. + +--------------------- + +.. function:: void obs_properties_destroy(obs_properties_t *props) + +--------------------- + +.. function:: void obs_properties_set_flags(obs_properties_t *props, uint32_t flags) + uint32_t obs_properties_get_flags(obs_properties_t *props) + + :param flags: 0 or a bitwise OR combination of one of the following + values: + + - OBS_PROPERTIES_DEFER_UPDATE - A hint that tells the + front-end to defers updating the settings until the + user has finished editing all properties rather than + immediately updating any settings + +--------------------- + +.. function:: void obs_properties_set_param(obs_properties_t *props, void *param, void (*destroy)(void *param)) + void *obs_properties_get_param(obs_properties_t *props) + + Sets custom data associated with this properties object. If private + data is already associated with the object, that private data will be + destroyed before assigning new private data to it. + +--------------------- + +.. function:: void obs_properties_apply_settings(obs_properties_t *props, obs_data_t *settings) + + Applies settings to the properties by calling all the necessary + modification callbacks + +--------------------- + + +Property Object Functions +------------------------- + +.. function:: obs_property_t *obs_properties_add_bool(obs_properties_t *props, const char *name, const char *description) + + Adds a boolean property. + + :param name: Setting identifier string + :param description: Localized name shown to user + :return: The property + +--------------------- + +.. function:: obs_property_t *obs_properties_add_int(obs_properties_t *props, const char *name, const char *description, int min, int max, int step) + + Adds an integer property. + + :param name: Setting identifier string + :param description: Localized name shown to user + :param min: Minimum value + :param max: Maximum value + :param step: Step value + :return: The property + +--------------------- + +.. function:: obs_property_t *obs_properties_add_float(obs_properties_t *props, const char *name, const char *description, double min, double max, double step) + + :param name: Setting identifier string + :param description: Localized name shown to user + :param min: Minimum value + :param max: Maximum value + :param step: Step value + :return: The property + +--------------------- + +.. function:: obs_property_t *obs_properties_add_int_slider(obs_properties_t *props, const char *name, const char *description, int min, int max, int step) + + :param name: Setting identifier string + :param description: Localized name shown to user + :param min: Minimum value + :param max: Maximum value + :param step: Step value + :return: The property + +--------------------- + +.. function:: obs_property_t *obs_properties_add_float_slider(obs_properties_t *props, const char *name, const char *description, double min, double max, double step) + + :param name: Setting identifier string + :param description: Localized name shown to user + :param min: Minimum value + :param max: Maximum value + :param step: Step value + :return: The property + +--------------------- + +.. function:: obs_property_t *obs_properties_add_text(obs_properties_t *props, const char *name, const char *description, enum obs_text_type type) + + :param name: Setting identifier string + :param description: Localized name shown to user + :param type: Can be one of the following values: + + - **OBS_TEXT_DEFAULT** - Single line of text + - **OBS_TEXT_PASSWORD** - Single line of text (passworded) + - **OBS_TEXT_MULTILINE** - Multi-line text + + :return: The property + +--------------------- + +.. function:: obs_property_t *obs_properties_add_path(obs_properties_t *props, const char *name, const char *description, enum obs_path_type type, const char *filter, const char *default_path) + + Adds a 'path' property. Can be a directory or a file. + + If target is a file path, the filters should be this format, separated by + double semi-colens, and extensions separated by space:: + + "Example types 1 and 2 (*.ex1 *.ex2);;Example type 3 (*.ex3)" + + :param name: Setting identifier string + :param description: Localized name shown to user + :param type: Can be one of the following values: + + - **OBS_PATH_FILE** - File (for reading) + - **OBS_PATH_FILE_SAVE** - File (for writing) + - **OBS_PATH_DIRECTORY** - Directory + + :param filter: If type is a file path, then describes the file filter + that the user can browse. Items are separated via + double semi-colens. If multiple file types in a + filter, separate with space. + :param default_path: The default path to start in, or *NULL* + :return: The property + +--------------------- + +.. function:: obs_property_t *obs_properties_add_list(obs_properties_t *props, const char *name, const char *description, enum obs_combo_type type, enum obs_combo_format format) + + Adds an integer/string/floating point item list. This would be + implemented as a combo box in user interface. + + :param name: Setting identifier string + :param description: Localized name shown to user + :param type: Can be one of the following values: + + - **OBS_COMBO_TYPE_EDITABLE** - Can be edited. + Only used with string lists. + - **OBS_COMBO_TYPE_LIST** - Not ediable. + + :param format: Can be one of the following values: + + - **OBS_COMBO_FORMAT_INT** - Integer list + - **OBS_COMBO_FORMAT_FLOAT** - Floating point + list + - **OBS_COMBO_FORMAT_STRING** - String list + + :return: The property + + Important Related Functions: + + - :c:func:`obs_property_list_add_string` + - :c:func:`obs_property_list_add_int` + - :c:func:`obs_property_list_add_float` + - :c:func:`obs_property_list_insert_string` + - :c:func:`obs_property_list_insert_int` + - :c:func:`obs_property_list_insert_float` + - :c:func:`obs_property_list_item_remove` + - :c:func:`obs_property_list_clear` + +--------------------- + +.. function:: obs_property_t *obs_properties_add_color(obs_properties_t *props, const char *name, const char *description) + + Adds a color property. + + :param name: Setting identifier string + :param description: Localized name shown to user + :return: The property + +--------------------- + +.. function:: obs_property_t *obs_properties_add_button(obs_properties_t *props, const char *name, const char *text, obs_property_clicked_t callback) + + Adds a button property. This property does not actually store any + settings; it's used to implement a button in user interface if the + properties are used to generate user interface. + + :param name: Setting identifier string + :param description: Localized name shown to user + :return: The property + +--------------------- + +.. function:: obs_property_t *obs_properties_add_font(obs_properties_t *props, const char *name, const char *description) + + Adds a font property. + + :param name: Setting identifier string + :param description: Localized name shown to user + :return: The property + +--------------------- + +.. function:: obs_property_t *obs_properties_add_editable_list(obs_properties_t *props, const char *name, const char *description, enum obs_editable_list_type type, const char *filter, const char *default_path) + + Adds a list in which the user can add/insert/remove items. + + :param name: Setting identifier string + :param description: Localized name shown to user + :param type: Can be one of the following values: + + - **OBS_EDITABLE_LIST_TYPE_STRINGS** - An + editable list of strings. + - **OBS_EDITABLE_LIST_TYPE_FILES** - An + editable list of files. + - **OBS_EDITABLE_LIST_TYPE_FILES_AND_URLS** - + An editable list of files and URLs. + + :param filter: File filter to use if a file list + :param default_path: Default path if a file list + :return: The property + +--------------------- + +.. function:: obs_property_t *obs_properties_add_frame_rate(obs_properties_t *props, const char *name, const char *description) + + Adds a frame rate property. + + :param name: Setting identifier string + :param description: Localized name shown to user + :return: The property + + Important Related Functions: + + - :c:func:`obs_property_frame_rate_option_add` + - :c:func:`obs_property_frame_rate_fps_range_add` + - :c:func:`obs_property_frame_rate_option_insert` + - :c:func:`obs_property_frame_rate_fps_range_insert` + +--------------------- + + +Property Enumeration Functions +------------------------------ + +.. function:: obs_property_t *obs_properties_first(obs_properties_t *props) + + :return: The first property in the properties object. + +--------------------- + +.. function:: obs_property_t *obs_properties_get(obs_properties_t *props, const char *property) + + :param property: The name of the property to get + :return: A specific property or *NULL* if not found + +--------------------- + +.. function:: bool obs_property_next(obs_property_t **p) + + :param p: Pointer to the pointer of the next property + :return: *true* if successful, *false* if no more properties + +--------------------- + +.. function:: const char * obs_property_name(obs_property_t *p) + + :return: The setting identifier string of the property + + *(Author's Note: "name" was a bad name to use here. Should have been + "setting")* + +--------------------- + +.. function:: const char * obs_property_description(obs_property_t *p) + + :return: The actual localized display name of the property + + *(Author's note: This one should have been the "name")* + +--------------------- + +.. function:: const char * obs_property_long_description(obs_property_t *p) + + :return: A detailed description of what the setting is used for. + Usually used with things like tooltips. + +--------------------- + +.. function:: enum obs_property_type obs_property_get_type(obs_property_t *p) + + :return: One of the following values: + + - OBS_PROPERTY_INVALID + - OBS_PROPERTY_BOOL + - OBS_PROPERTY_INT + - OBS_PROPERTY_FLOAT + - OBS_PROPERTY_TEXT + - OBS_PROPERTY_PATH + - OBS_PROPERTY_LIST + - OBS_PROPERTY_COLOR + - OBS_PROPERTY_BUTTON + - OBS_PROPERTY_FONT + - OBS_PROPERTY_EDITABLE_LIST + - OBS_PROPERTY_FRAME_RATE + +--------------------- + +.. function:: bool obs_property_enabled(obs_property_t *p) + +--------------------- + +.. function:: bool obs_property_visible(obs_property_t *p) + +--------------------- + +.. function:: int obs_property_int_min(obs_property_t *p) + +--------------------- + +.. function:: int obs_property_int_max(obs_property_t *p) + +--------------------- + +.. function:: int obs_property_int_step(obs_property_t *p) + +--------------------- + +.. function:: enum obs_number_type obs_property_int_type(obs_property_t *p) + +--------------------- + +.. function:: double obs_property_float_min(obs_property_t *p) + +--------------------- + +.. function:: double obs_property_float_max(obs_property_t *p) + +--------------------- + +.. function:: double obs_property_float_step(obs_property_t *p) + +--------------------- + +.. function:: enum obs_number_type obs_property_float_type(obs_property_t *p) + +--------------------- + +.. function:: enum obs_text_type obs_proprety_text_type(obs_property_t *p) + +--------------------- + +.. function:: enum obs_path_type obs_property_path_type(obs_property_t *p) + +--------------------- + +.. function:: const char * obs_property_path_filter(obs_property_t *p) + +--------------------- + +.. function:: const char * obs_property_path_default_path(obs_property_t *p) + +--------------------- + +.. function:: enum obs_combo_type obs_property_list_type(obs_property_t *p) + +--------------------- + +.. function:: enum obs_combo_format obs_property_list_format(obs_property_t *p) + +--------------------- + +.. function:: bool obs_property_list_item_disabled(obs_property_t *p, size_t idx) + +--------------------- + +.. function:: size_t obs_property_list_item_count(obs_property_t *p) + +--------------------- + +.. function:: const char *obs_property_list_item_name(obs_property_t *p, size_t idx) + +--------------------- + +.. function:: const char *obs_property_list_item_string(obs_property_t *p, size_t idx) + +--------------------- + +.. function:: long long obs_property_list_item_int(obs_property_t *p, size_t idx) + +--------------------- + +.. function:: double obs_property_list_item_float(obs_property_t *p, size_t idx) + +--------------------- + +.. function:: enum obs_editable_list_type obs_property_editable_list_type(obs_property_t *p) + +--------------------- + +.. function:: const char *obs_property_editable_list_filter(obs_property_t *p) + +--------------------- + +.. function:: const char *obs_property_editable_list_default_path(obs_property_t *p) + +--------------------- + +.. function:: size_t obs_property_frame_rate_options_count(obs_property_t *p) + +--------------------- + +.. function:: const char *obs_property_frame_rate_option_name(obs_property_t *p, size_t idx) + +--------------------- + +.. function:: const char *obs_property_frame_rate_option_description( obs_property_t *p, size_t idx) + +--------------------- + +.. function:: size_t obs_property_frame_rate_fps_ranges_count(obs_property_t *p) + +--------------------- + +.. function:: struct media_frames_per_second obs_property_frame_rate_fps_range_min( obs_property_t *p, size_t idx) + +--------------------- + +.. function:: struct media_frames_per_second obs_property_frame_rate_fps_range_max( obs_property_t *p, size_t idx) + +--------------------- + + +Property Modification Functions +------------------------------- + +.. function:: void obs_property_set_modified_callback(obs_property_t *p, obs_property_modified_t modified) + + Allows the ability to change the properties depending on what + settings are used by the user. + + Relevant data types used with this function: + +.. code:: cpp + + typedef bool (*obs_property_clicked_t)(obs_properties_t *props, + obs_property_t *property, void *data); + +--------------------- + +.. function:: bool obs_property_modified(obs_property_t *p, obs_data_t *settings) + +--------------------- + +.. function:: bool obs_property_button_clicked(obs_property_t *p, void *obj) + +--------------------- + +.. function:: void obs_property_set_visible(obs_property_t *p, bool visible) + +--------------------- + +.. function:: void obs_property_set_enabled(obs_property_t *p, bool enabled) + +--------------------- + +.. function:: void obs_property_set_description(obs_property_t *p, const char *description) + + Sets the displayed localized name of the property, shown to the user. + +--------------------- + +.. function:: void obs_property_set_long_description(obs_property_t *p, const char *long_description) + + Sets the localized long description of the property, usually shown to + a user via tooltip. + +--------------------- + +.. function:: void obs_property_int_set_limits(obs_property_t *p, int min, int max, int step) + +--------------------- + +.. function:: void obs_property_float_set_limits(obs_property_t *p, double min, double max, double step) + +--------------------- + +.. function:: void obs_property_list_clear(obs_property_t *p) + +--------------------- + +.. function:: size_t obs_property_list_add_string(obs_property_t *p, const char *name, const char *val) + + Adds a string to a string list. + +--------------------- + +.. 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. + +--------------------- + +.. 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. + +--------------------- + +.. 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. + +--------------------- + +.. 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. + +--------------------- + +.. 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. + +--------------------- + +.. function:: void obs_property_list_item_disable(obs_property_t *p, size_t idx, + +--------------------- + +.. function:: void obs_property_list_item_remove(obs_property_t *p, size_t idx) + +--------------------- + +.. function:: size_t obs_property_frame_rate_option_add(obs_property_t *p, const char *name, const char *description) + +--------------------- + +.. function:: size_t obs_property_frame_rate_fps_range_add(obs_property_t *p, struct media_frames_per_second min, struct media_frames_per_second max) + +--------------------- + +.. function:: void obs_property_frame_rate_clear(obs_property_t *p) + +--------------------- + +.. function:: void obs_property_frame_rate_options_clear(obs_property_t *p) + +--------------------- + +.. function:: void obs_property_frame_rate_fps_ranges_clear(obs_property_t *p) + +--------------------- + +.. function:: void obs_property_frame_rate_option_insert(obs_property_t *p, size_t idx, const char *name, const char *description) + +--------------------- + +.. function:: void obs_property_frame_rate_fps_range_insert(obs_property_t *p, size_t idx, struct media_frames_per_second min, struct media_frames_per_second max) diff --git a/docs/sphinx/reference-scenes.rst b/docs/sphinx/reference-scenes.rst new file mode 100644 index 000000000..e01d8a066 --- /dev/null +++ b/docs/sphinx/reference-scenes.rst @@ -0,0 +1,414 @@ +Scene API Reference (obs_scene_t) +================================= + +A scene is a source which contains and renders other sources using +specific transforms and/or filtering + +.. type:: obs_scene_t + + A reference-counted scene object. + +.. type:: obs_sceneitem_t + + A reference-counted scene item object. + +.. code:: cpp + + #include + + +Scene Item Transform Structure (obs_transform_info) +--------------------------------------------------- + +.. type:: struct obs_transform_info + + Scene item transform structure. + +.. member:: struct vec2 obs_transform_info.pos + + Position. + +.. member:: float obs_transform_info.rot + + Rotation (degrees). + +.. member:: struct vec2 obs_transform_info.scale + + Scale. + +.. member:: uint32_t obs_transform_info.alignment + + The alignment of the scene item relative to its position. + + Can be 0 or a bitwise OR combination of one of the following values: + + - **OBS_ALIGN_CENTER** + - **OBS_ALIGN_LEFT** + - **OBS_ALIGN_RIGHT** + - **OBS_ALIGN_TOP** + - **OBS_ALIGN_BOTTOM** + +.. member:: enum obs_bounds_type obs_transform_info.bounds_type + + Can be one of the following values: + + - **OBS_BOUNDS_NONE** - No bounding box + - **OBS_BOUNDS_STRETCH** - Stretch to the bounding box without preserving aspect ratio + - **OBS_BOUNDS_SCALE_INNER** - Scales with aspect ratio to inner bounding box rectangle + - **OBS_BOUNDS_SCALE_OUTER** - Scales with aspect ratio to outer bounding box rectangle + - **OBS_BOUNDS_SCALE_TO_WIDTH** - Scales with aspect ratio to the bounding box width + - **OBS_BOUNDS_SCALE_TO_HEIGHT** - Scales with aspect ratio to the bounding box height + - **OBS_BOUNDS_MAX_ONLY** - Scales with aspect ratio, but only to the size of the source maximum + +.. member:: uint32_t obs_transform_info.bounds_alignment + + The alignment of the source within the bounding box. + + Can be 0 or a bitwise OR combination of one of the following values: + + - **OBS_ALIGN_CENTER** + - **OBS_ALIGN_LEFT** + - **OBS_ALIGN_RIGHT** + - **OBS_ALIGN_TOP** + - **OBS_ALIGN_BOTTOM** + +.. member:: struct vec2 obs_transform_info.bounds + + The bounding box (if a bounding box is enabled). + + +Scene Item Crop Structure (obs_sceneitem_crop) +---------------------------------------------- + +.. type:: struct obs_sceneitem_crop + + Scene item crop structure. + +.. member:: int obs_sceneitem_crop.left + + Left crop value. + +.. member:: int obs_sceneitem_crop.top + + Top crop value. + +.. member:: int obs_sceneitem_crop.right + + Right crop value. + +.. member:: int obs_sceneitem_crop.bottom + + Bottom crop value. + + +.. _scene_signal_reference: + +Scene Signals +------------- + +**item_add** (ptr scene, ptr item) + + Called when a scene item has been added to the scene. + +**item_remove** (ptr scene, ptr item) + + Called when a scene item has been removed from the scen. + +**reorder** (ptr scene) + + Called when scene items have been reoredered in the scene. + +**item_visible** (ptr scene, ptr item, bool visible) + + Called when a scene item's visibility state changes. + +**item_select** (ptr scene, ptr item) +**item_deselect** (ptr scene, ptr item) + + Called when a scene item has been selected/deselected. + + (Author's note: These should be replaced) + +**item_transform** (ptr scene, ptr item) + + Called when a scene item's transform has changed. + + +General Scene Functions +----------------------- + +.. function:: obs_scene_t *obs_scene_create(const char *name) + + :param name: Name of the scene source. If it's not unique, it will + be made unique + :return: A reference to a scene + +--------------------- + +.. function:: obs_scene_t *obs_scene_create_private(const char *name) + + :param name: Name of the scene source. Does not have to be unique, + or can be *NULL* + :return: A reference to a private scene + +--------------------- + +.. function:: obs_scene_t *obs_scene_duplicate(obs_scene_t *scene, const char *name, enum obs_scene_duplicate_type type) + + Duplicates a scene. When a scene is duplicated, its sources can be + just referenced, or fully duplicated. + + :param name: Name of the new scene source + + :param type: | Type of duplication: + | OBS_SCENE_DUP_REFS - Duplicates the scene, but scene items are only duplicated with references + | OBS_SCENE_DUP_COPY - Duplicates the scene, and scene items are also fully duplicated when possible + | OBS_SCENE_DUP_PRIVATE_REFS - Duplicates with references, but the scene is a private source + | OBS_SCENE_DUP_PRIVATE_COPY - Fully duplicates scene items when possible, but the scene and duplicates sources are private sources + + :return: A reference to a new scene + +--------------------- + +.. function:: void obs_scene_addref(obs_scene_t *scene) + void obs_scene_release(obs_scene_t *scene) + + Adds/releases a reference to a scene. + +--------------------- + +.. function:: obs_sceneitem_t *obs_scene_add(obs_scene_t *scene, obs_source_t *source) + + :return: A new scene item for a source within a scene. Does not + increment the reference + +--------------------- + +.. function:: obs_source_t *obs_scene_get_source(const obs_scene_t *scene) + + :return: The scene's source. Does not increment the reference + +--------------------- + +.. function:: obs_scene_t *obs_scene_from_source(const obs_source_t *source) + + :return: The scene context, or *NULL* if not a scene. Does not + increase the reference + +--------------------- + +.. function:: obs_sceneitem_t *obs_scene_find_source(obs_scene_t *scene, const char *name) + + :param name: The name of the source to find + :return: The scene item if found, otherwise *NULL* if not found + +--------------------- + +.. function:: obs_sceneitem_t *obs_scene_find_sceneitem_by_id(obs_scene_t *scene, int64_t id) + + :param id: The unique numeric identifier of the scene item + :return: The scene item if found, otherwise *NULL* if not found + +--------------------- + +.. function:: void obs_scene_enum_items(obs_scene_t *scene, bool (*callback)(obs_scene_t*, obs_sceneitem_t*, void*), void *param) + + Enumerates scene items within a scene. + +--------------------- + +.. function:: bool obs_scene_reorder_items(obs_scene_t *scene, obs_sceneitem_t * const *item_order, size_t item_order_size) + + Reorders items within a scene. + +--------------------- + + +.. _scene_item_reference: + +Scene Item Functions +-------------------- + +.. function:: void obs_sceneitem_addref(obs_sceneitem_t *item) + void obs_sceneitem_release(obs_sceneitem_t *item) + + Adds/releases a reference to a scene item. + +--------------------- + +.. function:: void obs_sceneitem_remove(obs_sceneitem_t *item) + + Removes the scene item from the scene. + +--------------------- + +.. function:: obs_scene_t *obs_sceneitem_get_scene(const obs_sceneitem_t *item) + + :return: The scene associated with the scene item. Does not + increment the reference + +--------------------- + +.. function:: obs_source_t *obs_sceneitem_get_source(const obs_sceneitem_t *item) + + :return: The source associated with the scene item. Does not + increment the reference + +--------------------- + +.. function:: void obs_sceneitem_set_pos(obs_sceneitem_t *item, const struct vec2 *pos) + void obs_sceneitem_get_pos(const obs_sceneitem_t *item, struct vec2 *pos) + + Sets/gets the position of a scene item. + +--------------------- + +.. function:: void obs_sceneitem_set_rot(obs_sceneitem_t *item, float rot_deg) + float obs_sceneitem_get_rot(const obs_sceneitem_t *item) + + Sets/gets the rotation of a scene item. + +--------------------- + +.. function:: void obs_sceneitem_set_scale(obs_sceneitem_t *item, const struct vec2 *scale) + void obs_sceneitem_get_scale(const obs_sceneitem_t *item, struct vec2 *scale) + + Sets/gets the scaling of the scene item. + +--------------------- + +.. function:: void obs_sceneitem_set_alignment(obs_sceneitem_t *item, uint32_t alignment) + uint32_t obs_sceneitem_get_alignment(const obs_sceneitem_t *item) + + Sets/gets the alignment of the scene item relative to its position. + + :param alignment: | Can be any bitwise OR combination of: + | OBS_ALIGN_CENTER + | OBS_ALIGN_LEFT + | OBS_ALIGN_RIGHT + | OBS_ALIGN_TOP + | OBS_ALIGN_BOTTOM + +--------------------- + +.. function:: void obs_sceneitem_set_order(obs_sceneitem_t *item, enum obs_order_movement movement) + + Changes the scene item's order relative to the other scene items + within the scene. + + :param movement: | Can be one of the following: + | OBS_ORDER_MOVE_UP + | OBS_ORDER_MOVE_DOWN + | OBS_ORDER_MOVE_TOP + | OBS_ORDER_MOVE_BOTTOM + +--------------------- + +.. function:: void obs_sceneitem_set_order_position(obs_sceneitem_t *item, int position) + + Changes the scene item's order index. + +--------------------- + +.. function:: void obs_sceneitem_set_bounds_type(obs_sceneitem_t *item, enum obs_bounds_type type) + enum obs_bounds_type obs_sceneitem_get_bounds_type(const obs_sceneitem_t *item) + + Sets/gets the bounding box type of a scene item. Bounding boxes are + used to stretch/position the source relative to a specific bounding + box of a specific size. + + :param type: | Can be one of the following values: + | OBS_BOUNDS_NONE - No bounding box + | OBS_BOUNDS_STRETCH - Stretch to the bounding box without preserving aspect ratio + | OBS_BOUNDS_SCALE_INNER - Scales with aspect ratio to inner bounding box rectangle + | OBS_BOUNDS_SCALE_OUTER - Scales with aspect ratio to outer bounding box rectangle + | OBS_BOUNDS_SCALE_TO_WIDTH - Scales with aspect ratio to the bounding box width + | OBS_BOUNDS_SCALE_TO_HEIGHT - Scales with aspect ratio to the bounding box height + | OBS_BOUNDS_MAX_ONLY - Scales with aspect ratio, but only to the size of the source maximum + +--------------------- + +.. function:: void obs_sceneitem_set_bounds_alignment(obs_sceneitem_t *item, uint32_t alignment) + uint32_t obs_sceneitem_get_bounds_alignment(const obs_sceneitem_t *item) + + Sets/gets the alignment of the source within the bounding box. + + :param alignment: | Can be any bitwise OR combination of: + | OBS_ALIGN_CENTER + | OBS_ALIGN_LEFT + | OBS_ALIGN_RIGHT + | OBS_ALIGN_TOP + | OBS_ALIGN_BOTTOM + +--------------------- + +.. function:: void obs_sceneitem_set_bounds(obs_sceneitem_t *item, const struct vec2 *bounds) + void obs_sceneitem_get_bounds(const obs_sceneitem_t *item, struct vec2 *bounds) + + Sets/gets the bounding box width/height of the scene item. + +--------------------- + +.. function:: void obs_sceneitem_set_info(obs_sceneitem_t *item, const struct obs_transform_info *info) + void obs_sceneitem_get_info(const obs_sceneitem_t *item, struct obs_transform_info *info) + + Sets/gets the transform information of the scene item. + +--------------------- + +.. function:: void obs_sceneitem_get_draw_transform(const obs_sceneitem_t *item, struct matrix4 *transform) + + Gets the transform matrix of the scene item used for drawing the + source. + +--------------------- + +.. function:: void obs_sceneitem_get_box_transform(const obs_sceneitem_t *item, struct matrix4 *transform) + + Gets the transform matrix of the scene item used for the bouding box + or edges of the scene item. + +--------------------- + +.. function:: bool obs_sceneitem_set_visible(obs_sceneitem_t *item, bool visible) + bool obs_sceneitem_visible(const obs_sceneitem_t *item) + + Sets/gets the visibility state of the scene item. + +--------------------- + +.. function:: void obs_sceneitem_set_crop(obs_sceneitem_t *item, const struct obs_sceneitem_crop *crop) + void obs_sceneitem_get_crop(const obs_sceneitem_t *item, struct obs_sceneitem_crop *crop) + + Sets/gets the cropping of the scene item. + +--------------------- + +.. function:: void obs_sceneitem_set_scale_filter(obs_sceneitem_t *item, enum obs_scale_type filter) + enum obs_scale_type obs_sceneitem_get_scale_filter( obs_sceneitem_t *item) + + Sets/gets the scale filter used for the scene item. + + :param filter: | Can be one of the following values: + | OBS_SCALE_DISABLE + | OBS_SCALE_POINT + | OBS_SCALE_BICUBIC + | OBS_SCALE_BILINEAR + | OBS_SCALE_LANCZOS + +--------------------- + +.. function:: void obs_sceneitem_defer_update_begin(obs_sceneitem_t *item) + void obs_sceneitem_defer_update_end(obs_sceneitem_t *item) + + Allows the ability to call any one of the transform functions without + updating the internal matrices until obs_sceneitem_defer_update_end + has been called. + +--------------------- + +.. function:: obs_data_t *obs_sceneitem_get_private_settings(obs_sceneitem_t *item) + + :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 diff --git a/docs/sphinx/reference-services.rst b/docs/sphinx/reference-services.rst new file mode 100644 index 000000000..fdfb85e41 --- /dev/null +++ b/docs/sphinx/reference-services.rst @@ -0,0 +1,276 @@ +Service API Reference (obs_service_t) +===================================== + +Services are custom implementations of streaming services, which are +used with outputs that stream. For example, you could have a custom +implementation for streaming to Twitch, and another for YouTube to allow +the ability to log in and use their APIs to do things such as get the +RTMP servers or control the channel. The `libobs/obs-service.h`_ file +is the dedicated header for implementing services. + +*(Author's note: the service API is incomplete as of this writing)* + +.. type:: obs_service_t + + A reference-counted service object. + +.. type:: obs_weak_service_t + + A weak reference to a service object. + +.. code:: cpp + + #include + + +Service Definition Structure +---------------------------- + +.. type:: struct obs_service_info + + Service definition structure. + +.. member:: const char *obs_service_info.id + + Unique string identifier for the service (required). + +.. member:: const char *(*obs_service_info.get_name)(void *type_data) + + Get the translated name of the service type. + + :param type_data: The type_data variable of this structure + :return: The translated name of the service type + +.. member:: void *(*obs_service_info.create)(obs_data_t *settings, obs_service_t *service) + + Creates the implementation data for the service. + + :param settings: Settings to initialize the service with + :param service: Source that this data is associated with + :return: The implementation data associated with this service + +.. member:: void (*obs_service_info.destroy)(void *data) + + Destroys the implementation data for the service. + +.. member:: void (*obs_service_info.get_defaults)(obs_data_t *settings) + void (*obs_service_info.get_defaults2)(void *type_data, obs_data_t *settings) + + Sets the default settings for this service. + + :param settings: Default settings. Call obs_data_set_default* + functions on this object to set default setting + values + +.. member:: obs_properties_t *(*obs_service_info.get_properties)(void *data) + obs_properties_t *(*obs_service_info.get_properties2)(void *data, void *type_data) + + Gets the property information of this service. + + (Optional) + + :return: The properties of the service + +.. member:: void (*obs_service_info.update)(void *data, obs_data_t *settings) + + Updates the settings for this service. + + (Optional) + + :param settings: New settings for this service + +.. member:: bool (*obs_service_info.initialize)(void *data, obs_output_t *output) + + Called when getting ready to start up an output, before the encoders + and output are initialized. + + (Optional) + + :param output: Output context to use this service with + :return: *true* to allow the output to start up, + *false* to prevent output from starting up + +.. member:: const char *(*obs_service_info.get_url)(void *data) + + :return: The stream URL + +.. member:: const char *(*obs_service_info.get_key)(void *data) + + :return: The stream key + +.. member:: const char *(*obs_service_info.get_username)(void *data) + + (Optional) + + :return: The username + +.. member:: const char *(*obs_service_info.get_password)(void *data) + + (Optional) + + :return: The password + +.. member:: void (*obs_service_info.apply_encoder_settings)(void *data, obs_data_t *video_encoder_settings, obs_data_t *audio_encoder_settings) + + This function is called to apply custom encoder settings specific to + this service. For example, if a service requires a specific keyframe + interval, or has a bitrate limit, the settings for the video and + audio encoders can be optionally modified if the front-end optionally + calls :c:func:`obs_service_apply_encoder_settings()`. + + (Optional) + + :param video_encoder_settings: The audio encoder settings to change + :param audio_encoder_settings: The video encoder settings to change + +.. member:: void *obs_service_info.type_data + void (*obs_service_info.free_type_data)(void *type_data) + + Private data associated with this entry. Note that this is not the + same as the implementation data; this is used to differentiate + between two different types if the same callbacks are used for more + than one different type. + + (Optional) + +.. member:: const char *(*obs_service_info.get_output_type)(void *data) + + (Optional) + + :return: The output type that should be used with this service + + +General Service Functions +------------------------- + +.. function:: void obs_register_service(struct obs_service_info *info) + + Registers a service type. Typically used in + :c:func:`obs_module_load()` or in the program's initialization phase. + +--------------------- + +.. function:: const char *obs_service_get_display_name(const char *id) + + Calls the :c:member:`obs_service_info.get_name` callback to get the + translated display name of a service type. + + :param id: The service type string identifier + :return: The translated display name of a service type + +--------------------- + +.. function:: obs_service_t *obs_service_create(const char *id, const char *name, obs_data_t *settings, obs_data_t *hotkey_data) + + Creates a service with the specified settings. + + The "service" context is used for encoding video/audio data. Use + obs_service_release to release it. + + :param id: The service type string identifier + :param name: The desired name of the service. If this is + not unique, it will be made to be unique + :param settings: The settings for the service, or *NULL* if + none + :param hotkey_data: Saved hotkey data for the service, or *NULL* + if none + :return: A reference to the newly created service, or + *NULL* if failed + +--------------------- + +.. function:: void obs_service_addref(obs_service_t *service) + void obs_service_release(obs_service_t *service) + + Adds/releases a reference to a service. When the last reference is + released, the service is destroyed. + +--------------------- + +.. function:: obs_weak_service_t *obs_service_get_weak_service(obs_service_t *service) + obs_service_t *obs_weak_service_get_service(obs_weak_service_t *weak) + + These functions are used to get a weak reference from a strong service + reference, or a strong service reference from a weak reference. If + the service is destroyed, *obs_weak_service_get_service* will return + *NULL*. + +--------------------- + +.. function:: void obs_weak_service_addref(obs_weak_service_t *weak) + void obs_weak_service_release(obs_weak_service_t *weak) + + Adds/releases a weak reference to a service. + +--------------------- + +.. function:: const char *obs_service_get_name(const obs_service_t *service) + + :return: The name of the service + +--------------------- + +.. function:: obs_data_t *obs_service_defaults(const char *id) + + :return: An incremented reference to the service's default settings + +--------------------- + +.. function:: obs_properties_t *obs_service_properties(const obs_service_t *service) + obs_properties_t *obs_get_service_properties(const char *id) + + Use these functions to get the properties of a service or service + type. Properties are optionally used (if desired) to automatically + generate user interface widgets to allow users to update settings. + + :return: The properties list for a specific existing service. Free + with :c:func:`obs_properties_destroy()` + +--------------------- + +.. function:: obs_data_t *obs_service_get_settings(const obs_service_t *service) + + :return: An incremented reference to the service's settings + +--------------------- + +.. function:: void obs_service_update(obs_service_t *service, obs_data_t *settings) + + Updates the settings for this service context. + +--------------------- + +.. function:: const char *obs_service_get_url(const obs_service_t *service) + + :return: The URL currently used for this service + +--------------------- + +.. function:: const char *obs_service_get_key(const obs_service_t *service) + + :return: Stream key (if any) currently used for this service + +--------------------- + +.. function:: const char *obs_service_get_username(const obs_service_t *service) + + :return: User name (if any) currently used for this service + +--------------------- + +.. function:: const char *obs_service_get_password(const obs_service_t *service) + + :return: Password (if any) currently used for this service + +--------------------- + +.. function:: void obs_service_apply_encoder_settings(obs_service_t *service, obs_data_t *video_encoder_settings, obs_data_t *audio_encoder_settings) + + Applies service-specific video encoder settings. + + :param video_encoder_settings: Video encoder settings. Can be *NULL* + :param audio_encoder_settings: Audio encoder settings. Can be *NULL* + +.. --------------------------------------------------------------------------- + +.. _libobs/obs-service.h: https://github.com/jp9000/obs-studio/blob/master/libobs/obs-service.h diff --git a/docs/sphinx/reference-settings.rst b/docs/sphinx/reference-settings.rst new file mode 100644 index 000000000..8a29e3ec4 --- /dev/null +++ b/docs/sphinx/reference-settings.rst @@ -0,0 +1,279 @@ +Data Settings API Reference (obs_data_t) +======================================== + +Data settings objects are reference-counted objects that store values in +a string-table or array. They're similar to Json objects, but +additionally allow additional functionality such as default or +auto-selection values. Data is saved/loaded to/from Json text and Json +text files. + +.. type:: obs_data_t + + A reference-counted data object. + +.. type:: obs_data_array_t + + A reference-counted data array object. + +.. code:: cpp + + #include + + +General Functions +----------------- + +.. function:: obs_data_t *obs_data_create() + + :return: A new reference to a data object. + +--------------------- + +.. function:: obs_data_t *obs_data_create_from_json(const char *json_string) + + Creates a data object from a Json string. + + :param json_string: Json string + :return: A new reference to a data object + +--------------------- + +.. function:: obs_data_t *obs_data_create_from_json_file(const char *json_file) + + Creates a data object from a Json file. + + :param json_file: Json file path + :return: A new reference to a data object + +--------------------- + +.. function:: obs_data_t *obs_data_create_from_json_file_safe(const char *json_file, const char *backup_ext) + + Creates a data object from a Json file, with a backup file in case + the original is corrupted or fails to load. + + :param json_file: Json file path + :param backup_ext: Backup file extension + :return: A new reference to a data object + +--------------------- + +.. function:: void obs_data_addref(obs_data_t *data) + void obs_data_release(obs_data_t *data) + + Adds/releases a reference to a data object. + +--------------------- + +.. function:: const char *obs_data_get_json(obs_data_t *data) + + :return: Json string for this object + +--------------------- + +.. function:: bool obs_data_save_json(obs_data_t *data, const char *file) + + Saves the data to a file as Json text. + + :param file: The file to save to + :return: *true* if successful, *false* otherwise + +--------------------- + +.. function:: bool obs_data_save_json_safe(obs_data_t *data, const char *file, const char *temp_ext, const char *backup_ext) + + Saves the data to a file as Json text, and if overwriting an old + file, backs up that old file to help prevent potential file + corruption. + + :param file: The file to save to + :param backup_ext: The backup extension to use for the overwritten + file if it exists + :return: *true* if successful, *false* otherwise + +--------------------- + +.. function:: void obs_data_apply(obs_data_t *target, obs_data_t *apply_data) + + Merges the data of *apply_data* in to *target*. + +--------------------- + +.. function:: void obs_data_erase(obs_data_t *data, const char *name) + + Erases the user data for item *name* within the data object. + +--------------------- + +.. function:: void obs_data_clear(obs_data_t *data) + + Clears all user data in the data object. + +--------------------- + + +Set Functions +------------- + +.. function:: void obs_data_set_string(obs_data_t *data, const char *name, const char *val) + +--------------------- + +.. function:: void obs_data_set_int(obs_data_t *data, const char *name, long long val) + +--------------------- + +.. function:: void obs_data_set_double(obs_data_t *data, const char *name, double val) + +--------------------- + +.. function:: void obs_data_set_bool(obs_data_t *data, const char *name, bool val) + +--------------------- + +.. function:: void obs_data_set_obj(obs_data_t *data, const char *name, obs_data_t *obj) + +--------------------- + +.. function:: void obs_data_set_array(obs_data_t *data, const char *name, obs_data_array_t *array) + +--------------------- + + +Get Functions +------------- + +.. function:: const char *obs_data_get_string(obs_data_t *data, const char *name) + +--------------------- + +.. function:: long long obs_data_get_int(obs_data_t *data, const char *name) + +--------------------- + +.. function:: double obs_data_get_double(obs_data_t *data, const char *name) + +--------------------- + +.. function:: bool obs_data_get_bool(obs_data_t *data, const char *name) + +--------------------- + +.. function:: obs_data_t *obs_data_get_obj(obs_data_t *data, const char *name) + + :return: An incremented reference to a data object. + +--------------------- + +.. 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. + +--------------------- + +Default Value Functions +----------------------- + +Default values are used to determine what value will be given if a value +is not set. + +.. function:: void obs_data_set_default_string(obs_data_t *data, const char *name, const char *val) + const char *obs_data_get_default_string(obs_data_t *data, const char *name) + +--------------------- + +.. function:: void obs_data_set_default_int(obs_data_t *data, const char *name, long long val) + long long obs_data_get_default_int(obs_data_t *data, const char *name) + +--------------------- + +.. function:: void obs_data_set_default_double(obs_data_t *data, const char *name, double val) + double obs_data_get_default_double(obs_data_t *data, const char *name) + +--------------------- + +.. function:: void obs_data_set_default_bool(obs_data_t *data, const char *name, bool val) + bool obs_data_get_default_bool(obs_data_t *data, const char *name) + +--------------------- + +.. 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. + +--------------------- + + +Autoselect Functions +-------------------- + +Autoselect values are optionally used to determine what values should be +used to ensure functionality if the currently set values are +inappropriate or invalid. + +.. function:: void obs_data_set_autoselect_string(obs_data_t *data, const char *name, const char *val) + const char *obs_data_get_autoselect_string(obs_data_t *data, const char *name) + +--------------------- + +.. function:: void obs_data_set_autoselect_int(obs_data_t *data, const char *name, long long val) + long long obs_data_get_autoselect_int(obs_data_t *data, const char *name) + +--------------------- + +.. function:: void obs_data_set_autoselect_double(obs_data_t *data, const char *name, double val) + double obs_data_get_autoselect_double(obs_data_t *data, const char *name) + +--------------------- + +.. function:: void obs_data_set_autoselect_bool(obs_data_t *data, const char *name, bool val) + bool obs_data_get_autoselect_bool(obs_data_t *data, const char *name) + +--------------------- + +.. 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. + +--------------------- + + +Array Functions +--------------- + +.. function:: obs_data_array_t *obs_data_array_create() + + :return: A new reference to a data array object. + +--------------------- + +.. function:: void obs_data_array_addref(obs_data_array_t *array) + +--------------------- + +.. function:: void obs_data_array_release(obs_data_array_t *array) + +--------------------- + +.. function:: size_t obs_data_array_count(obs_data_array_t *array) + +--------------------- + +.. 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. + +--------------------- + +.. function:: size_t obs_data_array_push_back(obs_data_array_t *array, obs_data_t *obj) + +--------------------- + +.. function:: void obs_data_array_insert(obs_data_array_t *array, size_t idx, obs_data_t *obj) + +--------------------- + +.. function:: void obs_data_array_erase(obs_data_array_t *array, size_t idx) diff --git a/docs/sphinx/reference-sources.rst b/docs/sphinx/reference-sources.rst new file mode 100644 index 000000000..2b7233bc0 --- /dev/null +++ b/docs/sphinx/reference-sources.rst @@ -0,0 +1,1363 @@ +Source API Reference (obs_source_t) +=================================== + +Sources are used to render video and/or audio on stream. Things such as +capturing displays/games/audio, playing a video, showing an image, or +playing audio. Sources can also be used to implement audio and video +filters as well as transitions. The `libobs/obs-source.h`_ file is the +dedicated header for implementing sources. + +.. type:: obs_source_t + + A reference-counted video/audio input source. + +.. type:: obs_weak_source_t + + A weak reference to an video/audio input source. + +.. code:: cpp + + #include + + +Source Definition Structure (obs_source_info) +--------------------------------------------- + +.. type:: struct obs_source_info + + Source definition structure. + +.. member:: const char *obs_source_info.id + + Unique string identifier for the source (required). + +.. member:: enum obs_source_type obs_source_info.type + + Type of source. + + - **OBS_SOURCE_TYPE_INPUT** - Video/Audio Input + - **OBS_SOURCE_TYPE_FILTER** - Filter + - **OBS_SOURCE_TYPE_TRANSITION** - Transition + +.. member:: uint32_t obs_source_info.output_flags + + Source output capability flags (required). + + (Author's note: This should be renamed to "capability_flags") + + A bitwise OR combination of one or more of the following values: + + - **OBS_SOURCE_VIDEO** - Source has video + + Unless SOURCE_ASYNC_VIDEO is specified, the source must include the + :c:member:`obs_source_info.video_render` callback in the source + definition structure. + + - **OBS_SOURCE_AUDIO** - Source has audio + + Use the :c:func:`obs_source_output_audio()` function to pass raw + audio data, which will be automatically converted and uploaded. If + used with OBS_SOURCE_ASYNC_VIDEO, audio will automatically be + synced up to the video output based upon their mutual timestamps. + + - **OBS_SOURCE_ASYNC** - Video is asynchronous (use + OBS_SOURCE_ASYNC_VIDEO instead to automatically combine this flag + with the OBS_SOURCE_VIDEO flag). + + - **OBS_SOURCE_ASYNC_VIDEO** - Source passes raw video data via RAM + + Use the :c:func:`obs_source_output_video()` function to pass raw + video data, which will be automatically drawn at a timing relative + to the provided timestamp. + + If audio is also present on the source, the audio will + automatically be synced to the video based upon their mutual + timestamps. + + - **OBS_SOURCE_CUSTOM_DRAW** - Source uses custom graphics calls, + rather than just rendering a single texture. + + This capability flag must be used if the source does not use + :c:func:`obs_source_draw()` to render a single texture. + + This capability flag is an important hint to turn off a specific + optimization that allows the first effect filter in the filter + chain to render the source directly with that effect filter. The + optimization does not work if there are custom graphics calls, and + the source must be rendered to a texture first before being sent to + the first filter in the filter chain. + + (Author's note: Ironically, not many sources render with that + optimization. I should have made it so that the optimization isn't + used by default, and a flag should have been used to turn on the + optimization -- not turn it off). + + - **OBS_SOURCE_INTERACTION** - Source can be interacted with by the + user. + + When this is used, the source will receive interaction events if + theese callbacks are provided: + :c:member:`obs_source_info.mouse_click`, + :c:member:`obs_source_info.mouse_move`, + :c:member:`obs_source_info.mouse_wheel`, + :c:member:`obs_source_info.focus`, and + :c:member:`obs_source_info.key_click`. + + - **OBS_SOURCE_COMPOSITE** - Source composites child sources + + When used, specifies that the source composites one or more child + sources. Scenes and transitions are examples of sources that + contain and render child sources. + + Sources that render sub-sources must implement the audio_render + callback in order to perform custom audio mixing of child sources. + + This capability flag is always set for transitions. + + - **OBS_SOURCE_DO_NOT_DUPLICATE** - Source should not be fully + duplicated. + + When this is used, specifies that the source should not be fully + duplicated, and should prefer to duplicate via holding references + rather than full duplication. + + When functions such as :c:func:`obs_source_duplicate()` or + :c:func:`obs_scene_duplicate()` are called, sources or child + sources with this flag will never be fully duplicated, and will + instead only be referenced. + + An example of the type of sources that should not be fully + duplicated are video devices, browsers, and video/audio captures, + as they will either not function correctly or will cause + performance or resource issues when duplicated. + + - **OBS_SOURCE_DEPRECATED** - Source is deprecated and should not be + used. + + - **OBS_SOURCE_DO_NOT_SELF_MONITOR** - Audio of this source should + not allow monitoring if the current monitoring device is the same + device being captured by the source. + + This flag is used as a hint to the back-end to prevent the source + from creating an audio feedback loop. This is primarily only used + with desktop audio capture sources. + +.. member:: const char *(*obs_source_info.get_name)(void *type_data) + + Get the translated name of the source type. + + :param type_data: The type_data variable of this structure + :return: The translated name of the source type + +.. member:: void *(*obs_source_info.create)(obs_data_t *settings, obs_source_t *source) + + Creates the implementation data for the source. + + :param settings: Settings to initialize the source with + :param source: Source that this data is associated with + :return: The implementation data associated with this source + +.. member:: void (*obs_source_info.destroy)(void *data) + + Destroys the implementation data for the source. + + Async sources must not call obs_source_output_video after returning + from destroy. + +.. member:: uint32_t (*obs_source_info.get_width)(void *data) + uint32_t (*obs_source_info.get_height)(void *data); + + Returns the width/height of the source. These callbacks are required + if this is a video source and is synchronous. + + (Author's note: These should really be consolidated in to one + function, not two) + + :return: The width/height of the video + +.. member:: void (*obs_source_info.get_defaults)(obs_data_t *settings) + void (*obs_source_info.get_defaults2)(void *type_data, obs_data_t *settings) + + Sets the default settings for this source. + + :param settings: Default settings. Call obs_data_set_default* + functions on this object to set default setting + values + +.. member:: obs_properties_t *(*obs_source_info.get_properties)(void *data) + obs_properties_t *(*obs_source_info.get_properties2)(void *data, void *type_data) + + Gets the property information of this source. + + (Optional) + + :return: The properties of the source + +.. member:: void (*obs_source_info.update)(void *data, obs_data_t *settings) + + Updates the settings for this source. + + (Optional) + + :param settings: New settings for this source + +.. member:: void (*obs_source_info.activate)(void *data) + + Called when the source has been activated in the main view (visible + on stream/recording). + + (Optional) + +.. member:: void (*obs_source_info.deactivate)(void *data) + + Called when the source has been deactivated from the main view (no + longer visible on stream/recording). + + (Optional) + +.. member:: void (*obs_source_info.show)(void *data) + + Called when the source is visible on any display and/or on the main + view. + + (Optional) + +.. member:: void (*obs_source_info.hide)(void *data) + + Called when the source is no longer visible on any display and/or on + the main view. + + (Optional) + +.. member:: void (*obs_source_info.video_tick)(void *data, float seconds) + + Called each video frame with the time elapsed. + + (Optional) + + :param seconds: Seconds elapsed since the last frame + +.. member:: void (*obs_source_info.video_render)(void *data, gs_effect_t *effect) + + Called when rendering the source with the graphics subsystem. + + If this is an input/transition source, this is called to draw the + source texture with the graphics subsystem. + + If this is a filter source, it wraps source draw calls (for example + applying a custom effect with custom parameters to a source). In + this case, it's highly recommended to use the + :c:func:`obs_source_process_filter_begin()` and + :c:func:`obs_source_process_filter_end()` functions to automatically + handle effect-based filter processing. However, you can implement + custom draw handling as desired as well. + + If the source output capability flags do not include + OBS_SOURCE_CUSTOM_DRAW, the source must use + :c:func:`obs_source_draw()` to render the source's texture. + + :param effect: This parameter is no longer used. Instead, call + :c:func:`obs_source_draw()` + +.. member:: struct obs_source_frame *(*obs_source_info.filter_video)(void *data, struct obs_source_frame *frame) + + Called to filter raw async video data. This function is only used + with asynchronous video filters. + + :param frame: Video frame to filter + :return: New video frame data. This can defer video data to + be drawn later if time is needed for processing + +.. member:: struct obs_audio_data *(*obs_source_info.filter_audio)(void *data, struct obs_audio_data *audio) + + Called to filter raw audio data. This function is only used with + audio filters. + + :param audio: Audio data to filter + :return: Modified or new audio data. You can directly modify + the data passed and return it, or you can defer audio + data for later if time is needed for processing. If + you are returning new data, that data must exist until + the next call to the + :c:member:`obs_source_info.filter_audio` callback or + until the filter is removed/destroyed + +.. member:: void (*obs_source_info.enum_active_sources)(void *data, obs_source_enum_proc_t enum_callback, void *param) + + Called to enumerate all active sources being used within this + source. If the source has children that render audio/video it must + implement this callback. Only used with sources that have tha + OBS_SOURCE_COMPOSITE output capability flag. + + :param enum_callback: Enumeration callback + :param param: User data to pass to callback + +.. member:: void (*obs_source_info.save)(void *data, obs_data_t *settings) + + Called when saving custom data for a source. This is a separate + function because sometimes a source needs to know when it is being + saved so it doesn't always have to update the current settings until + a certain point. + + (Optional) + + :param settings: Settings object to save data to + +.. member:: void (*obs_source_info.load)(void *data, obs_data_t *settings) + + Called when loading custom data from saved source data. This is + called after all the loading sources have actually been created, + allowing the ability to reference other sources if desired. + + (Optional) + + :param settings: Settings object to load data from + +.. member:: void (*obs_source_info.mouse_click)(void *data, const struct obs_mouse_event *event, int32_t type, bool mouse_up, uint32_t click_count) + + Called when interacting with a source and a mouse-down or mouse-up + occurs. Only used with sources that have the OBS_SOURCE_INTERACTION + output capability flag. + + (Optional) + + :param event: Mouse event properties + :param type: Mouse button pushed + :param mouse_up: Mouse event type (true if mouse-up) + :param click_count: Mouse click count (1 for single click, etc.) + +.. member:: void (*obs_source_info.mouse_move)(void *data, const struct obs_mouse_event *event, bool mouse_leave) + + Called when interacting with a source and a mouse-move occurs. Only + used with sources that have the OBS_SOURCE_INTERACTION output + capability flag. + + (Optional) + + :param event: Mouse event properties + :param mouse_leave: Mouse leave state (true if mouse left source) + +.. member:: void (*obs_source_info.mouse_wheel)(void *data, const struct obs_mouse_event *event, int x_delta, int y_delta) + + Called when interacting with a source and a mouse-wheel occurs. Only + used with sources that have the OBS_SOURCE_INTERACTION output + capability flag. + + (Optional) + + :param event: Mouse event properties + :param x_delta: Movement delta in the horizontal direction + :param y_delta: Movement delta in the vertical direction + + +.. member:: void (*obs_source_info.focus)(void *data, bool focus) + + Called when interacting with a source and gain focus/lost focus event + occurs. Only used with sources that have the OBS_SOURCE_INTERACTION + output capability flag. + + (Optional) + + :param focus: Focus state (true if focus gained) + +.. member:: void (*obs_source_info.key_click)(void *data, const struct obs_key_event *event, bool key_up) + + Called when interacting with a source and a key-up or key-down + occurs. Only used with sources that have the OBS_SOURCE_INTERACTION + output capability flag. + + (Optional) + + :param event: Key event properties + :param focus: Key event type (true if mouse-up) + +.. member:: void (*obs_source_info.filter_remove)(void *data, obs_source_t *source) + + Called when the filter is removed from a source. + + (Optional) + + :param data: Filter data + :param source: Source that the filter being removed from + +.. member:: void *obs_source_info.type_data + void (*obs_source_info.free_type_data)(void *type_data) + + Private data associated with this entry. Note that this is not the + same as the implementation data; this is used to differentiate + between two different types if the same callbacks are used for more + than one different type. + +.. member:: bool (*obs_source_info.audio_render)(void *data, uint64_t *ts_out, struct obs_source_audio_mix *audio_output, uint32_t mixers, size_t channels, size_t sample_rate) + + Called to render audio of composite sources. Only used with sources + that have tha OBS_SOURCE_COMPOSITE output capability flag. + +.. member:: void (*obs_source_info.enum_all_sources)(void *data, obs_source_enum_proc_t enum_callback, void *param) + + Called to enumerate all active and inactive sources being used + within this source. If this callback isn't implemented, + enum_active_sources will be called instead. Only used with sources + that have tha OBS_SOURCE_COMPOSITE output capability flag. + + This is typically used if a source can have inactive child sources. + + :param enum_callback: Enumeration callback + :param param: User data to pass to callback + +.. member:: void (*obs_source_info.transition_start)(void *data) + void (*obs_source_info.transition_stop)(void *data) + + Called on transition sources when the transition starts/stops. + + (Optional) + + +.. _source_signal_handler_reference: + +Source Signals +-------------- + +**destroy** (ptr *source*) + + This signal is called when the source is about to be destroyed. Do + not increment any references when using this signal. + +**remove** (ptr source) + + Called when the :c:func:`obs_source_remove()` function is called on + the source. + +**save** (ptr source) + + Called when the source is being saved. + +**load** (ptr source) + + Called when the source is being loaded. + +**activate** (ptr source) + + Called when the source has been activated in the main view (visible + on stream/recording). + +**deactivate** (ptr source) + + Called when the source has been deactivated from the main view (no + longer visible on stream/recording). + +**show** (ptr source) + + Called when the source is visible on any display and/or on the main + view. + +**hide** (ptr source) + + Called when the source is no longer visible on any display and/or on + the main view. + +**mute** (ptr source, bool muted) + + Called when the source is muted/unmuted. + +**push_to_mute_changed** (ptr source, bool enabled) + + Called when push-to-mute has been enabled/disabled. + +**push_to_mute_delay** (ptr source, int delay) + + Called when the push-to-mute delay value has changed. + +**push_to_talk_changed** (ptr source, bool enabled) + + Called when push-to-talk has been enabled/disabled. + +**push_to_talk_delay** (ptr source, int delay) + + Called when the push-to-talk delay value has changed. + +**enable** (ptr source, bool enabled) + + Called when the source has been disabled/enabled. + +**rename** (ptr source, string new_name, string prev_name) + + Called when the source has been renamed. + +**volume** (ptr source, in out float volume) + + Called when the volume of the source has changed. + +**update_properties** (ptr source) + + Called when the properties of the source have been updated. + +**update_flags** (ptr source, int flags) + + Called when the flags of the source have been changed. + +**audio_sync** (ptr source, int out int offset) + + Called when the audio sync offset has changed. + +**audio_mixers** (ptr source, in out int mixers) + + Called when the audio mixers have changed. + +**filter_add** (ptr source, ptr filter) + + Called when a filter has been added to the source. + +**filter_remove** (ptr source, ptr filter) + + Called when a filter has been removed from the source. + +**reorder_filters** (ptr source) + + Called when filters have been reordered. + +**transition_start** (ptr source) + + Called when a transition is starting. + +**transition_video_stop** (ptr source) + + Called when a transition's video transitioning has stopped. + +**transition_stop** (ptr source) + + Called when a transition has stopped. + + +General Source Functions +------------------------ + +.. function:: void obs_register_source(struct obs_source_info *info) + + Registers a source type. Typically used in + :c:func:`obs_module_load()` or in the program's initialization phase. + +--------------------- + +.. function:: const char *obs_source_get_display_name(const char *id) + + Calls the :c:member:`obs_source_info.get_name` callback to get the + translated display name of a source type. + + :param id: The source type string identifier + :return: The translated display name of a source type + +--------------------- + +.. function:: obs_source_t *obs_source_create(const char *id, const char *name, obs_data_t *settings, obs_data_t *hotkey_data) + + 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. + + :param id: The source type string identifier + :param name: The desired name of the source. If this is + not unique, it will be made to be unique + :param settings: The settings for the source, or *NULL* if + none + :param hotkey_data: Saved hotkey data for the source, or *NULL* + if none + :return: A reference to the newly created source, or + *NULL* if failed + +--------------------- + +.. function:: obs_source_t *obs_source_create_private(const char *id, const char *name, obs_data_t *settings) + + Creates a 'private' source which is not enumerated by + :c:func:`obs_enum_sources()`, and is not saved by + :c:func:`obs_save_sources()`. + + Author's Note: The existence of this function is a result of design + flaw: the front-end should control saving/loading of sources, and + functions like :c:func:`obs_enum_sources()` and + :c:func:`obs_save_sources()` should not exist in the back-end. + + :param id: The source type string identifier + :param name: The desired name of the source. For private + sources, this does not have to be unique, + and can additionally be *NULL* if desired + :param settings: The settings for the source, or *NULL* if + none + :return: A reference to the newly created source, or + *NULL* if failed + +--------------------- + +.. function:: obs_source_t *obs_source_duplicate(obs_source_t *source, const char *desired_name, bool create_private) + + 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. + + :param source: The source to duplicate + :param desired_name: The desired name of the new source. If this is + not a private source and the name is not unique, + it will be made to be unique + :param create_private: If *true*, the new source will be a private + source if fully duplicated + :return: A new source reference + +--------------------- + +.. function:: void obs_source_addref(obs_source_t *source) + void obs_source_release(obs_source_t *source) + + Adds/releases a reference to a source. When the last reference is + released, the source is destroyed. + +--------------------- + +.. function:: obs_weak_source_t *obs_source_get_weak_source(obs_source_t *source) + obs_source_t *obs_weak_source_get_source(obs_weak_source_t *weak) + + These functions are used to get a weak reference from a strong source + reference, or a strong source reference from a weak reference. If + the source is destroyed, *obs_weak_source_get_source* will return + *NULL*. + +--------------------- + +.. function:: void obs_weak_source_addref(obs_weak_source_t *weak) + void obs_weak_source_release(obs_weak_source_t *weak) + + Adds/releases a weak reference to a source. + +--------------------- + +.. function:: void obs_source_remove(obs_source_t *source) + + Notifies all reference holders of the source (via + :c:func:`obs_source_removed()`) that the source should be released. + +--------------------- + +.. function:: bool obs_source_removed(const obs_source_t *source) + + :return: *true* if the source should be released + +--------------------- + +.. function:: uint32_t obs_source_get_output_flags(const obs_source_t *source) + uint32_t obs_get_source_output_flags(const char *id) + + :return: Capability flags of a source + + Author's Note: "Output flags" is poor wording in retrospect; this + should have been named "Capability flags", and the OBS_SOURCE_* + macros should really be OBS_SOURCE_CAP_* macros instead. + + See :c:member:`obs_source_info.output_flags` for more information. + +--------------------- + +.. function:: obs_data_t *obs_get_source_defaults(const char *id) + + Calls :c:member:`obs_source_info.get_defaults` to get the defaults + settings of the source type. + + :return: The default settings for a source type + +--------------------- + +.. function:: obs_properties_t *obs_source_properties(const obs_source_t *source) + obs_properties_t *obs_get_source_properties(const char *id) + + Use these functions to get the properties of a source or source type. + Properties are optionally used (if desired) to automatically generate + user interface widgets to allow users to update settings. + + :return: The properties list for a specific existing source. Free with + :c:func:`obs_properties_destroy()` + +--------------------- + +.. function:: bool obs_source_configurable(const obs_source_t *source) + bool obs_is_source_configurable(const char *id) + + :return: *true* if the the source has custom properties, *false* + otherwise + +--------------------- + +.. function:: void obs_source_update(obs_source_t *source, obs_data_t *settings) + + Updates the settings for a source and calls the + :c:member:`obs_source_info.update` callback of the source. If the + source is a video source, the :c:member:`obs_source_info.update` will + be not be called immediately; instead, it will be deferred to the + video thread to prevent threading issues. + +--------------------- + +.. function:: void obs_source_video_render(obs_source_t *source) + + Renders a video source. This will call the + :c:member:`obs_source_info.video_render` callback of the source. + +--------------------- + +.. function:: uint32_t obs_source_get_width(obs_source_t *source) + uint32_t obs_source_get_height(obs_source_t *source) + + Calls the :c:member:`obs_source_info.get_width` or + :c:member:`obs_source_info.get_height` of the source to get its width + and/or height. + + Author's Note: These functions should be consolidated in to a single + function/callback rather than having a function for both width and + height. + + :return: The width or height of the source + +--------------------- + +.. function:: obs_data_t *obs_source_get_settings(const obs_source_t *source) + + :return: The settings string for a source. The reference counter of the + returned settings data is incremented, so + :c:func:`obs_data_release()` must be called when the + settings are no longer used + +--------------------- + +.. function:: const char *obs_source_get_name(const obs_source_t *source) + + :return: The name of the source + +--------------------- + +.. function:: void obs_source_set_name(obs_source_t *source, const char *name) + + Sets the name of a source. If the source is not private and the name + is not unique, it will automatically be given a unique name. + +--------------------- + +.. function:: enum obs_source_type obs_source_get_type(const obs_source_t *source) + + :return: | OBS_SOURCE_TYPE_INPUT for inputs + | OBS_SOURCE_TYPE_FILTER for filters + | OBS_SOURCE_TYPE_TRANSITION for transitions + | OBS_SOURCE_TYPE_SCENE for scenes + +--------------------- + +.. function:: const char *obs_source_get_id(const obs_source_t *source) + + :return: The source's type identifier string + +--------------------- + +.. function:: signal_handler_t *obs_source_get_signal_handler(const obs_source_t *source) + + :return: The source's signal handler + + See the :ref:`source_signal_handler_reference` for more information + on signals that are available for sources. + +--------------------- + +.. function:: proc_handler_t *obs_source_get_proc_handler(const obs_source_t *source) + + :return: The procedure handler for a source + +--------------------- + +.. function:: void obs_source_set_volume(obs_source_t *source, float volume) + float obs_source_get_volume(const obs_source_t *source) + + Sets/gets the user volume for a source that has audio output. + +--------------------- + +.. function:: bool obs_source_muted(const obs_source_t *source) + void obs_source_set_muted(obs_source_t *source, bool muted) + + Sets/gets whether the source's audio is muted. + +--------------------- + +.. function:: bool obs_source_push_to_mute_enabled(const obs_source_t *source) + void obs_source_enable_push_to_mute(obs_source_t *source, bool enabled) + + Sets/gets whether push-to-mute is enabled. + +--------------------- + +.. function:: uint64_t obs_source_get_push_to_mute_delay(const obs_source_t *source) + void obs_source_set_push_to_mute_delay(obs_source_t *source, uint64_t delay) + + Sets/gets the push-to-mute delay. + +--------------------- + +.. function:: bool obs_source_push_to_talk_enabled(const obs_source_t *source) + void obs_source_enable_push_to_talk(obs_source_t *source, bool enabled) + + Sets/gets whether push-to-talk is enabled. + +--------------------- + +.. function:: uint64_t obs_source_get_push_to_talk_delay(const obs_source_t *source) + void obs_source_set_push_to_talk_delay(obs_source_t *source, uint64_t delay) + + Sets/gets the push-to-talk delay. + +--------------------- + +.. function:: void obs_source_set_sync_offset(obs_source_t *source, int64_t offset) + int64_t obs_source_get_sync_offset(const obs_source_t *source) + + Sets/gets the audio sync offset (in nanoseconds) for a source. + +--------------------- + +.. function:: void obs_source_enum_active_sources(obs_source_t *source, obs_source_enum_proc_t enum_callback, void *param) + void obs_source_enum_active_tree(obs_source_t *source, obs_source_enum_proc_t enum_callback, void *param) + + Enumerates active child sources or source tree used by this source. + + Relevant data types used with this function: + +.. code:: cpp + + typedef void (*obs_source_enum_proc_t)(obs_source_t *parent, + obs_source_t *child, void *param); + +--------------------- + +.. function:: bool obs_source_active(const obs_source_t *source) + + :return: *true* if active, *false* if not. A source is only + consdiered active if it's being shown on the final mix + +--------------------- + +.. function:: bool obs_source_showing(const obs_source_t *source) + + :return: *true* if showing, *false* if not. A source is considered + showing if it's being displayed anywhere at all, whether on + a display context or on the final output + +--------------------- + +.. function:: void obs_source_inc_showing(obs_source_t *source) + void obs_source_dec_showing(obs_source_t *source) + + Increments/decrements a source's "showing" state. Typically used + when drawing a source on a display manually. + +--------------------- + +.. function:: void obs_source_set_flags(obs_source_t *source, uint32_t flags) + uint32_t obs_source_get_flags(const obs_source_t *source) + + :param flags: OBS_SOURCE_FLAG_FORCE_MONO Forces audio to mono + +--------------------- + +.. 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 + (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. + + For example, to output to mixer 1 and 3, you would perform a bitwise + OR on bits 0 and 2: (1<<0) | (1<<2), or 0x5. + +--------------------- + +.. function:: void obs_source_enum_filters(obs_source_t *source, obs_source_enum_proc_t callback, void *param) + + Enumerates active filters on a source. + + Relevant data types used with this function: + +.. code:: cpp + + typedef void (*obs_source_enum_proc_t)(obs_source_t *parent, + obs_source_t *child, void *param); + +--------------------- + +.. function:: obs_source_t *obs_source_get_filter_by_name(obs_source_t *source, const char *name) + + :return: The desired filter, or *NULL* if not found. The reference + of the filter is incremented + +--------------------- + +.. function:: void obs_source_copy_filters(obs_source_t *dst, obs_source_t *src) + + Copies filters from the source to the destination. If filters by the + same name already exist in the destination source, the newer filters + will be given unique names. + +--------------------- + +.. function:: bool obs_source_enabled(const obs_source_t *source) + void obs_source_set_enabled(obs_source_t *source, bool enabled) + + Enables/disables a source, or returns the enabled state. + +--------------------- + +.. function:: void obs_source_add_audio_capture_callback(obs_source_t *source, obs_source_audio_capture_t callback, void *param) + void obs_source_remove_audio_capture_callback(obs_source_t *source, obs_source_audio_capture_t callback, void *param) + + Adds/removes an audio capture callback for a source. This allows the + ability to get the raw audio data of a source as it comes in. + + Relevant data types used with this function: + +.. code:: cpp + + typedef void (*obs_source_audio_capture_t)(void *param, obs_source_t *source, + const struct audio_data *audio_data, bool muted); + +--------------------- + +.. function:: void obs_source_set_deinterlace_mode(obs_source_t *source, enum obs_deinterlace_mode mode) + enum obs_deinterlace_mode obs_source_get_deinterlace_mode(const obs_source_t *source) + + Sets/gets the deinterlace mode. + + :param mode: | OBS_DEINTERLACE_MODE_DISABLE - Disables deinterlacing + | OBS_DEINTERLACE_MODE_DISCARD - Discard + | OBS_DEINTERLACE_MODE_RETRO - Retro + | OBS_DEINTERLACE_MODE_BLEND - Blend + | OBS_DEINTERLACE_MODE_BLEND_2X - Blend 2x + | OBS_DEINTERLACE_MODE_LINEAR - Linear + | OBS_DEINTERLACE_MODE_LINEAR_2X - Linear 2x + | OBS_DEINTERLACE_MODE_YADIF - Yadif + | OBS_DEINTERLACE_MODE_YADIF_2X - Yadif 2x + + +--------------------- + +.. function:: void obs_source_set_deinterlace_field_order(obs_source_t *source, enum obs_deinterlace_field_order order) + enum obs_deinterlace_field_order obs_source_get_deinterlace_field_order(const obs_source_t *source) + + Sets/gets the deinterlace field order. + + :param order: | OBS_DEINTERLACE_FIELD_ORDER_TOP - Start from top + | OBS_DEINTERLACE_FIELD_ORDER_BOTTOM - Start from bottom + +--------------------- + +.. 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. + +--------------------- + +.. function:: void obs_source_send_mouse_click(obs_source_t *source, const struct obs_mouse_event *event, int32_t type, bool mouse_up, uint32_t click_count) + + Used for interacting with sources: sends a mouse down/up event to a + source. + +--------------------- + +.. function:: void obs_source_send_mouse_move(obs_source_t *source, const struct obs_mouse_event *event, bool mouse_leave) + + Used for interacting with sources: sends a mouse move event to a + source. + +--------------------- + +.. function:: void obs_source_send_mouse_wheel(obs_source_t *source, const struct obs_mouse_event *event, int x_delta, int y_delta) + + Used for interacting with sources: sends a mouse wheel event to a + source. + +--------------------- + +.. function:: void obs_source_send_focus(obs_source_t *source, bool focus) + + Used for interacting with sources: sends a got-focus or lost-focus + event to a source. + +--------------------- + +.. function:: void obs_source_send_key_click(obs_source_t *source, const struct obs_key_event *event, bool key_up) + + Used for interacting with sources: sends a key up/down event to a + source. + +--------------------- + + +Functions used by sources +------------------------- + +.. function:: void obs_source_draw_set_color_matrix(const struct matrix4 *color_matrix, const struct vec3 *color_range_min, const struct vec3 *color_range_max) + + Helper function to set the color matrix information when drawing the + source. + + :param color_matrix: The color matrix. Assigns to the 'color_matrix' + effect variable. + :param color_range_min: The minimum color range. Assigns to the + 'color_range_min' effect variable. If NULL, + {0.0f, 0.0f, 0.0f} is used. + :param color_range_max: The maximum color range. Assigns to the + 'color_range_max' effect variable. If NULL, + {1.0f, 1.0f, 1.0f} is used. + +--------------------- + +.. function:: void obs_source_draw(gs_texture_t *image, int x, int y, uint32_t cx, uint32_t cy, bool flip) + + Helper function to draw sprites for a source (synchronous video). + + :param image: The sprite texture to draw. Assigns to the 'image' variable + of the current effect. + :param x: X position of the sprite. + :param y: Y position of the sprite. + :param cx: Width of the sprite. If 0, uses the texture width. + :param cy: Height of the sprite. If 0, uses the texture height. + :param flip: Specifies whether to flip the image vertically. + +--------------------- + +.. function:: void obs_source_output_video(obs_source_t *source, const struct obs_source_frame *frame) + + Outputs asynchronous video data. Set to NULL to deactivate the texture. + + Relevant data types used with this function: + +.. code:: cpp + + enum video_format { + VIDEO_FORMAT_NONE, + + /* planar 420 format */ + VIDEO_FORMAT_I420, /* three-plane */ + VIDEO_FORMAT_NV12, /* two-plane, luma and packed chroma */ + + /* packed 422 formats */ + VIDEO_FORMAT_YVYU, + VIDEO_FORMAT_YUY2, /* YUYV */ + VIDEO_FORMAT_UYVY, + + /* packed uncompressed formats */ + VIDEO_FORMAT_RGBA, + VIDEO_FORMAT_BGRA, + VIDEO_FORMAT_BGRX, + VIDEO_FORMAT_Y800, /* grayscale */ + + /* planar 4:4:4 */ + VIDEO_FORMAT_I444, + }; + + struct obs_source_frame { + uint8_t *data[MAX_AV_PLANES]; + uint32_t linesize[MAX_AV_PLANES]; + uint32_t width; + uint32_t height; + uint64_t timestamp; + + enum video_format format; + float color_matrix[16]; + bool full_range; + float color_range_min[3]; + float color_range_max[3]; + bool flip; + }; + +--------------------- + +.. function:: void obs_source_preload_video(obs_source_t *source, const struct obs_source_frame *frame) + + Preloads a video frame to ensure a frame is ready for playback as + soon as video playback starts. + +--------------------- + +.. function:: void obs_source_show_preloaded_video(obs_source_t *source) + + Shows any preloaded video frame. + +--------------------- + +.. function:: void obs_source_output_audio(obs_source_t *source, const struct obs_source_audio *audio) + + Outputs audio data. + +--------------------- + +.. function:: void obs_source_update_properties(obs_source_t *source) + + Signal an update to any currently used properties. + +--------------------- + +.. function:: bool obs_source_add_active_child(obs_source_t *parent, obs_source_t *child) + + Adds an active child source. Must be called by parent sources on child + sources when the child is added and active. This ensures that the source is + properly activated if the parent is active. + + :return: *true* if source can be added, *false* if it causes recursion + +--------------------- + +.. function:: void obs_source_remove_active_child(obs_source_t *parent, obs_source_t *child) + + Removes an active child source. Must be called by parent sources on child + sources when the child is removed or inactive. This ensures that the source + is properly deactivated if the parent is no longer active. + +--------------------- + + +Filters +------- + +.. function:: obs_source_t *obs_filter_get_parent(const obs_source_t *filter) + + If the source is a filter, returns the parent source of the filter. + The parent source is the source being filtered. + + Only guaranteed to be valid inside of the video_render, filter_audio, + filter_video, and filter_remove callbacks. + +--------------------- + +.. function:: obs_source_t *obs_filter_get_target(const obs_source_t *filter) + + If the source is a filter, returns the target source of the filter. + The target source is the next source in the filter chain. + + Only guaranteed to be valid inside of the video_render, filter_audio, + filter_video, and filter_remove callbacks. + +--------------------- + +.. function:: void obs_source_default_render(obs_source_t *source) + + Can be used by filters to directly render a non-async parent source + without any filter processing. + +--------------------- + +.. function:: void obs_source_filter_add(obs_source_t *source, obs_source_t *filter) + void obs_source_filter_remove(obs_source_t *source, obs_source_t *filter) + + Adds/removes a filter to/from a source. + +--------------------- + +.. function:: void obs_source_filter_set_order(obs_source_t *source, obs_source_t *filter, enum obs_order_movement movement) + + Modifies the order of a specific filter. + + :param movement: | Can be one of the following: + | OBS_ORDER_MOVE_UP + | OBS_ORDER_MOVE_DOWN + | OBS_ORDER_MOVE_TOP + | OBS_ORDER_MOVE_BOTTOM + +--------------------- + + +Functions used by filters +------------------------- + +.. function:: bool obs_source_process_filter_begin(obs_source_t *filter, enum gs_color_format format, enum obs_allow_direct_render allow_direct) + + Default RGB filter handler for generic effect filters. Processes the + filter chain and renders them to texture if needed, then the filter is + drawn with. + + After calling this, set your parameters for the effect, then call + obs_source_process_filter_end to draw the filter. + + :return: *true* if filtering should continue, *false* if the filter + is bypassed for whatever reason + +--------------------- + +.. function:: void obs_source_process_filter_end(obs_source_t *filter, gs_effect_t *effect, uint32_t width, uint32_t height) + + Draws the filter using the effect's "Draw" technique. + + Before calling this function, first call obs_source_process_filter_begin and + then set the effect parameters, and then call this function to finalize the + filter. + +--------------------- + +.. function:: void obs_source_process_filter_tech_end(obs_source_t *filter, gs_effect_t *effect, uint32_t width, uint32_t height, const char *tech_name) + + Draws the filter with a specific technique in the effect. + + Before calling this function, first call obs_source_process_filter_begin and + then set the effect parameters, and then call this function to finalize the + filter. + +--------------------- + +.. function:: void obs_source_skip_video_filter(obs_source_t *filter) + + Skips the filter if the filter is invalid and cannot be rendered. + +--------------------- + + +.. _transitions: + +Transitions +----------- + +.. function:: obs_source_t *obs_transition_get_source(obs_source_t *transition, enum obs_transition_target target) + + :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 + +--------------------- + +.. function:: void obs_transition_clear(obs_source_t *transition) + + Clears the transition. + +--------------------- + +.. 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 + +--------------------- + +.. function:: bool obs_transition_start(obs_source_t *transition, enum obs_transition_mode mode, uint32_t duration_ms, obs_source_t *dest) + + Starts the transition with the desired destination source. + + :param mode: Currently only OBS_TRANSITION_MODE_AUTO + :param duration_ms: Duration in milliseconds. If the transition has + a fixed duration set by + :c:func:`obs_transition_enable_fixed`, this + parameter will have no effect + :param dest: The destination source to transition to + +--------------------- + +.. function:: void obs_transition_set_size(obs_source_t *transition, uint32_t cx, uint32_t cy) + void obs_transition_get_size(const obs_source_t *transition, uint32_t *cx, uint32_t *cy) + + Sets/gets the dimensions of the transition. + +--------------------- + +.. function:: void obs_transition_set_scale_type(obs_source_t *transition, enum obs_transition_scale_type type) + enum obs_transition_scale_type obs_transition_get_scale_type( const obs_source_t *transition) + + Sets/gets the scale type for sources within the transition. + + :param type: | OBS_TRANSITION_SCALE_MAX_ONLY - Scale to aspect ratio, but only to the maximum size of each source + | OBS_TRANSITION_SCALE_ASPECT - Alwasy scale the sources, but keep aspect ratio + | OBS_TRANSITION_SCALE_STRETCH - Scale and stretch the sources to the size of the transision + +--------------------- + +.. function:: void obs_transition_set_alignment(obs_source_t *transition, uint32_t alignment) + uint32_t obs_transition_get_alignment(const obs_source_t *transition) + + Sets/gets the alignment used to draw the two sources within + transition the transition. + + :param alignment: | Can be any bitwise OR combination of: + | OBS_ALIGN_CENTER + | OBS_ALIGN_LEFT + | OBS_ALIGN_RIGHT + | OBS_ALIGN_TOP + | OBS_ALIGN_BOTTOM + +--------------------- + + +Functions used by transitions +----------------------------- + +.. function:: void obs_transition_enable_fixed(obs_source_t *transition, bool enable, uint32_t duration_ms) + bool obs_transition_fixed(obs_source_t *transition) + + Sets/gets whether the transition uses a fixed duration. Useful for + certain types of transitions such as stingers. If this is set, the + *duration_ms* parameter of :c:func:`obs_transition_start()` has no + effect. + +--------------------- + +.. function:: float obs_transition_get_time(obs_source_t *transition) + + :return: The current transition time value (0.0f..1.0f) + +--------------------- + +.. function:: void obs_transition_video_render(obs_source_t *transition, obs_transition_video_render_callback_t callback) + + Helper function used for rendering transitions. This function will + render two distinct textures for source A and source B of the + transition, allowing the ability to blend them together with a pixel + shader in a desired manner. + + The *a* and *b* parameters of *callback* are automatically rendered + textures of source A and source B, *t* is the time value + (0.0f..1.0f), *cx* and *cy* are the current dimensions of the + transition, and *data* is the implementation's private data. + + Relevant data types used with this function: + +.. code:: cpp + + typedef void (*obs_transition_video_render_callback_t)(void *data, + gs_texture_t *a, gs_texture_t *b, float t, + uint32_t cx, uint32_t cy); + +--------------------- + +.. function:: bool obs_transition_audio_render(obs_source_t *transition, uint64_t *ts_out, struct obs_source_audio_mix *audio, uint32_t mixers, size_t channels, size_t sample_rate, obs_transition_audio_mix_callback_t mix_a_callback, obs_transition_audio_mix_callback_t mix_b_callback) + + Helper function used for transitioning audio. Typically you'd call + this in the obs_source_info.audio_render callback with its + parameters, and use the mix_a_callback and mix_b_callback to + determine the the audio fading of source A and source B. + + Relevant data types used with this function: + +.. code:: cpp + + typedef float (*obs_transition_audio_mix_callback_t)(void *data, float t); + +--------------------- + +.. function:: void obs_transition_swap_begin(obs_source_t *tr_dest, obs_source_t *tr_source) + void obs_transition_swap_end(obs_source_t *tr_dest, obs_source_t *tr_source) + + Swaps two transitions. Call obs_transition_swap_begin, swap the + source, then call obs_transition_swap_end when complete. This allows + the ability to seamlessly swap two different transitions without it + affecting the output. + + For example, if a transition is assigned to output channel 0, you'd + call obs_transition_swap_begin, then you'd call obs_set_output_source + with the new transition, then call + :c:func:`obs_transition_swap_begin()`. + +.. --------------------------------------------------------------------------- + +.. _libobs/obs-source.h: https://github.com/jp9000/obs-studio/blob/master/libobs/obs-source.h