docs/sphinx: Add sphinx documentation

.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

docs/sphinx/Makefile

+# 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

docs/sphinx/backend-design.rst

+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

docs/sphinx/conf.py

+#!/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'),
+]
+
+
+

docs/sphinx/frontends.rst

+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

docs/sphinx/graphics.rst

+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);
+   }
+

docs/sphinx/index.rst

+.. 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

docs/sphinx/make.bat

+@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

docs/sphinx/reference-core-objects.rst

+Core API Object Reference
+=========================
+
+.. toctree::
+   :maxdepth: 3
+
+   reference-sources
+   reference-scenes
+   reference-outputs
+   reference-encoders
+   reference-services
+   reference-settings
+   reference-properties

docs/sphinx/reference-core.rst

+OBS Core API Reference
+======================
+
+.. code:: cpp
+
+   #include <obs.h>
+
+
+.. _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.

docs/sphinx/reference-encoders.rst

+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 <obs.h>
+
+
+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

docs/sphinx/reference-libobs-callback.rst

+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 <callback/signal.h>
+
+.. 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 <callback/proc.h>
+
+.. 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

docs/sphinx/reference-libobs-graphics-axisang.rst

+Axis Angle
+==========
+
+Provides a helper structure for conversion to quaternions.
+
+.. code:: cpp
+
+   #include <graphics/axisang.h>
+
+.. 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

docs/sphinx/reference-libobs-graphics-effects.rst

+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 <graphics/graphics.h>
+
+.. 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

docs/sphinx/reference-libobs-graphics-image-file.rst

+.. _image_file_helper:
+
+Image File Helper
+=================
+
+Helper functions/type for easily loading/managing image files, including
+animated gif files.
+
+.. code:: cpp
+
+   #include <graphics/image-file.h>
+
+.. 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