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

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = OBSStudio
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/sphinx/backend-design.rst

@@ -0,0 +1,194 @@
+OBS Studio Backend Design
+=========================
+The OBS Studio backend is powered by the library libobs.  Libobs
+provides the main pipeline, the video/audio subsystems, and the general
+framework for all plugins.
+
+
+Libobs Plugin Objects
+---------------------
+Libobs is designed to be modular, where adding modules will add custom
+functionality.  There are four libobs objects that you can make plugins
+for:
+
+- :ref:`plugins_sources` -- Sources are used to render video and/or
+  audio on stream.  Things such as capturing displays/games/audio,
+  playing a video, showing an image, or playing audio.  Sources can also
+  be used to implement audio and video filters.
+
+- :ref:`plugins_outputs` -- Outputs allow the ability to output the
+  currently rendering audio/video.  Streaming and recording are two
+  common examples of outputs, but not the only types of outputs.
+  Outputs can receive the raw data or receive encoded data.
+
+- :ref:`plugins_encoders` -- Encoders are OBS-specific implementations
+  of video/audio encoders, which are used with outputs that use
+  encoders.  x264, NVENC, Quicksync are examples of encoder
+  implementations.
+
+- :ref:`plugins_services` -- Services are custom implementations of
+  streaming services, which are used with outputs that stream.  For
+  example, you could have a custom implementation for streaming to
+  Twitch, and another for YouTube to allow the ability to log in and use
+  their APIs to do things such as get the RTMP servers or control the
+  channel.
+  
+*(Author's note: the service API is incomplete as of this writing)*
+
+
+Libobs Threads
+--------------
+There are three primary threads spawned by libobs on initialization:
+
+- The obs_graphics_thread_ function used exclusively for rendering in
+  `libobs/obs-video.c`_
+
+- The video_thread_ function used exclusively for video encoding/output
+  in `libobs/media-io/video-io.c`_
+
+- The audio_thread_ function used for all audio
+  processing/encoding/output in `libobs/media-io/audio-io.c`_
+
+*(Author's note: obs_graphics_thread was originally named
+obs_video_thread; it was renamed as of this writing to prevent confusion
+with video_thread)*
+
+
+.. _output_channels:
+
+Output Channels
+---------------
+Rendering video or audio starts from output channels.  You assign a
+source to an output channel via the :c:func:`obs_set_output_source()`
+function.  The *channel* parameter can be any number from
+0..(MAX_CHANNELS_-1).  You may initially think that this is how you
+display multiple sources at once; however, sources are hierarchical.
+Sources such as scenes or transitions can have multiple sub-sources, and
+those sub-sources in turn can have sub-sources and so on (see
+:ref:`displaying_sources` for more information).  Typically, you would
+use scenes to draw multiple sources as a group with specific transforms
+for each source, as a scene is just another type of source.  The
+"channel" design allows for highly complex video presentation setups.
+The OBS Studio front-end has yet to even fully utilize this back-end
+design for its rendering, and currently only uses one output channel to
+render one scene at a time.  It does however utilize additional channels
+for things such as global audio sources which are set in audio settings.
+
+*(Author's note: "Output channels" are not to be confused with output
+objects or audio channels.  Output channels are used to set the sources
+you want to output, and output objects are used for actually
+streaming/recording/etc.)*
+
+
+General Video Pipeline Overview
+-------------------------------
+The video graphics pipeline is run from two threads: a dedicated
+graphics thread that renders preview displays as well as the final mix
+(the obs_graphics_thread_ function in `libobs/obs-video.c`_), and a
+dedicated thread specific to video encoding/output (the video_thread_
+function in `libobs/media-io/video-io.c`_).
+
+Sources assigned to output channels will be drawn from channels
+0..(MAX_CHANNELS_-1).  They are drawn on to the final texture which will
+be used for output `[1]`_.  Once all sources are drawn, the final
+texture is converted to whatever format that libobs is set to (typically
+a YUV format).  After being converted to the back-end video format, it's
+then sent along with its timestamp to the current video handler,
+`obs_core_video::video`_.
+
+It then puts that raw frame in a queue of MAX_CACHE_SIZE_ in the `video
+output handler`_.  A semaphore is posted, then the video-io thread will
+process frames as it's able.  If the video frame queue is full, it will
+duplicate the last frame in the queue in an attempt to reduce video
+encoding complexity (and thus CPU usage) `[2]`_.  This is why you may
+see frame skipping when the encoder can't keep up.  Frames are sent to
+any raw outputs or video encoders that are currently active `[3]`_.
+
+If it's sent to a video encoder object (`libobs/obs-encoder.c`_), it
+encodes the frame and sends the encoded packet off to the outputs that
+encoder is connected to (which can be multiple).  If the output takes
+both encoded video/audio, it puts the packets in an interleave queue to
+ensure encoded packets are sent in monotonic timestamp order `[4]`_.
+
+The encoded packet or raw frame is then sent to the output.
+
+
+General Audio Pipeline Overview
+-------------------------------
+The audio pipeline is run from a dedicated audio thread in the audio
+handler (the `audio_thread`_ function in `libobs/media-io/audio-io.c`_);
+assuming that AUDIO_OUTPUT_FRAMES_ is set to 1024, the audio thread
+"ticks" (processes audio data) once every 1024 audio samples (around
+every 21 millisecond intervals at 48khz), and calls the audio_callback_
+function in `libobs/obs-audio.c`_ where most of the audio processing is
+accomplished.
+
+A source with audio will output its audio via the
+obs_source_output_audio_ function, and that audio data will be appended
+or inserted in to the circular buffer `obs_source::audio_input_buf`_.
+If the sample rate or channel count does not match what the back-end is
+set to, the audio is automatically remixed/resampled via swresample
+`[5]`_.  Before insertion, audio data is also run through any audio
+filters attached to the source `[6]`_.
+
+Each audio tick, the audio thread takes a reference snapshot of the
+audio source tree (stores references of all sources that output/process
+audio) `[7]`_.  On each audio leaf (audio source), it takes the closest
+audio (relative to the current audio thread timestamp) stored in the
+circular buffer `obs_source::audio_input_buf`_, and puts it in
+`obs_source::audio_output_buf`_.
+
+Then, the audio samples stored in `obs_source::audio_output_buf`_ of the
+leaves get sent through their parents in the source tree snapshot for
+mixing or processing at each source node in the hierarchy `[8]`_.
+Sources with multiple children such as scenes or transitions will
+mix/process their children's audio themselves via the
+`obs_source_info::audio_render`_ callback.  This allows, for example,
+transitions to fade in the audio of one source and fade in the audio of
+a new source when they're transitioning between two sources.  The mix or
+processed audio data is then stored in `obs_source::audio_output_buf`_
+of that node similarly, and the process is repeated until the audio
+reaches the root nodes of the tree.
+
+Finally, when the audio has reached the base of the snapshot tree, the
+audio of all the sources in each output channel are mixed together for a
+final mix `[9]`_.  That final mix is then sent to any raw outputs or
+audio encoders that are currently active `[10]`_.
+
+If it's sent to an audio encoder object (`libobs/obs-encoder.c`_), it
+encodes the audio data and sends the encoded packet off to the outputs
+that encoder is connected to (which can be multiple).  If the output
+takes both encoded video/audio, it puts the packets in an interleave
+queue to ensure encoded packets are sent in monotonic timestamp order
+`[4]`_.
+
+The encoded packet or raw audio data is then sent to the output.
+
+.. _obs_graphics_thread: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-video.c#L588-L651
+.. _libobs/obs-audio.c: https://github.com/jp9000/obs-studio/blob/master/libobs/obs-audio.c
+.. _libobs/obs-video.c: https://github.com/jp9000/obs-studio/blob/master/libobs/obs-video.c
+.. _video_thread: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/media-io/video-io.c#L169-L195
+.. _libobs/media-io/video-io.c: https://github.com/jp9000/obs-studio/blob/master/libobs/media-io/video-io.c
+.. _video output handler: https://github.com/jp9000/obs-studio/blob/master/libobs/media-io/video-io.c
+.. _audio_thread: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/media-io/audio-io.c#L241-L282
+.. _libobs/media-io/audio-io.c: https://github.com/jp9000/obs-studio/blob/master/libobs/media-io/audio-io.c
+.. _MAX_CHANNELS: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-defs.h#L20-L21
+.. _[1]: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-video.c#L99-L129
+.. _obs_core_video::video: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-internal.h#L250
+.. _MAX_CACHE_SIZE: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/media-io/video-io.c#L34
+.. _[2]: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/media-io/video-io.c#L431-L434
+.. _[3]: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/media-io/video-io.c#L115-L167
+.. _libobs/obs-encoder.c: https://github.com/jp9000/obs-studio/blob/master/libobs/obs-encoder.c
+.. _[4]: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-output.c#L1382-L1439
+.. _AUDIO_OUTPUT_FRAMES: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/media-io/audio-io.h#L30
+.. _audio_callback: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-audio.c#L367-L485
+.. _obs_source_output_audio: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-source.c#L2578-L2608
+.. _obs_source::audio_input_buf: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-source.c#L1280-L1283
+.. _[5]: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-source.c#L2561-L2563
+.. _[6]: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-source.c#L2591
+.. _[7]: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-audio.c#L393-L415
+.. _obs_source::audio_output_buf: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-internal.h#L580
+.. _[8]: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-audio.c#L417-L423
+.. _obs_source_info::audio_render: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-source.h#L410-L412
+.. _[9]: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-audio.c#L436-L453
+.. _[10]: https://github.com/jp9000/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/media-io/audio-io.c#L144-L165

docs/sphinx/conf.py

@@ -0,0 +1,171 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+#
+# OBS Studio documentation build configuration file, created by
+# sphinx-quickstart on Wed Oct 25 00:03:21 2017.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+primary_domain = 'c'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = 'OBS Studio'
+copyright = '2017, Hugh Bailey'
+author = 'Hugh Bailey'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '20.1.0'
+# The full version, including alpha/beta/rc tags.
+release = '20.1.0'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'bizstyle'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# This is required for the alabaster theme
+# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
+html_sidebars = {
+    '**': [
+        'relations.html',  # needs 'show_related': True theme option to display
+        'searchbox.html',
+    ]
+}
+
+
+# -- Options for HTMLHelp output ------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'OBSStudiodoc'
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'OBSStudio.tex', 'OBS Studio Documentation',
+     'Hugh Bailey', 'manual'),
+]
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'obsstudio', 'OBS Studio Documentation',
+     [author], 1)
+]
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'OBSStudio', 'OBS Studio Documentation',
+     author, 'OBSStudio', 'One line description of project.',
+     'Miscellaneous'),
+]
+
+
+

docs/sphinx/frontends.rst

@@ -0,0 +1,252 @@
+Frontends
+=========
+
+Initialization and Shutdown
+---------------------------
+
+To initialize libobs, you must call :c:func:`obs_startup()`,
+:c:func:`obs_reset_video()`, and then :c:func:`obs_reset_audio()`.
+After that, modules typically should be loaded.
+
+You can load individual modules manually by calling
+:c:func:`obs_open_module()`.  After loading, the
+:c:func:`obs_open_module()` function, you must then call
+:c:func:`obs_init_module()` to initialize the module.
+
+You can load modules automatically via two functions:
+:c:func:`obs_add_module_path()` and :c:func:`obs_load_all_modules()`.
+
+After all plugin modules have been loaded, call
+:c:func:`obs_post_load_modules()`.
+
+Certain modules may optionally use a configuration storage directory,
+which is set as a parameter to :c:func:`obs_startup()`.
+
+When it's time to shut down the frontend, make sure to release all
+references to any objects, free any data, and then call
+:c:func:`obs_shutdown()`.  If for some reason any libobs objects have
+not been released, they will be destroyed automatically and a warning
+will be logged.
+
+To detect if any general memory allocations have not been freed, call
+the :c:func:`bnum_allocs()` to get the number of allocations remaining.
+If the number remaining is above 0, there are memory leaks.
+
+See :ref:`obs_init_shutdown_reference` for more information.
+
+
+Reconfiguring Video
+-------------------
+
+Any time after initialization, video settings can be reconfigured by
+calling :c:func:`obs_reset_video()` as long as no outputs are active.
+Audio was originally intended to have this capability as well, but
+currently is not able to be reset once initialized; libobs must be fully
+shutdown in order to reconfigure audio settings.
+
+
+Displays
+--------
+
+Displays as the name implies are used for display/preview panes.  To use
+displays, you must have a native window handle or identifier to draw on.
+
+First you must call :c:func:`obs_display_create()` to initialize the
+display, then you must assign a draw callback with
+:c:func:`obs_display_add_draw_callback()`.  If you need to remove a draw
+callback, call :c:func:`obs_display_remove_draw_callback()` similarly.
+
+When drawing, to draw the main preview window (if any), call
+:c:func:`obs_render_main_view()`.  If you need to render a specific
+source on a secondary display, you can increment its "showing" state
+with :c:func:`obs_source_inc_showing()` while it's showing in the
+secondary display, draw it with :c:func:`obs_source_video_render()` in
+the draw callback, then when it's no longer showing in the secondary
+display, call :c:func:`obs_source_dec_showing()`.
+
+If the display needs to be resized, call :c:func:`obs_display_resize()`.
+
+If the display needs a custom background color other than black, call
+:c:func:`obs_display_set_background_color()`.
+
+If the display needs to be temporarily disabled, call
+:c:func:`obs_display_set_enabled()` to disable, and
+:c:func:`obs_display_enabled()` to get its enabled/disabled state.
+
+Then call :c:func:`obs_display_destroy()` to destroy the display when
+it's no longer needed.
+
+*(Important note: do not use more than one display widget within the
+hierarchy of the same base window; this will cause presentation stalls
+on Macs.)*
+
+For an example of how displays are used with Qt, see
+`UI/qt-display.hpp`_ and `UI/qt-display.cpp`_.
+
+See :ref:`display_reference` for more information.
+
+
+Saving/Loading Objects and Object Management
+--------------------------------------------
+
+The frontend is generally expected to manage its own objects, however
+for sources, there are some helper functions to allow easier
+saving/loading all sources: :c:func:`obs_save_sources()` and
+:c:func:`obs_load_sources()`.  With those functions, all sources that
+aren't private will automatically be saved and loaded.  You can also
+save/load individual sources manually by using
+:c:func:`obs_save_source()` and :c:func:`obs_load_source()`.
+
+*(Author's note: I should not have written those helper functions; the
+downside is I had to add "private" sources that aren't savable via the*
+:c:func:`obs_source_create_private()` *function.  Just one of the many
+minor design flaws that can occur during long-term development.)*
+
+For outputs, encoders, and services, there are no helper functions, so
+usually you'd get their settings individually and save them as json.
+(See :c:func:`obs_output_get_settings()`).  You don't have to save each
+object to different files individually; you'd save multiple objects
+together in a bigger :c:type:`obs_data_t` object, then save that via
+:c:func:`obs_data_save_json_safe()`, then load everything again via
+:c:func:`obs_data_create_from_json_file_safe()`.
+
+
+Signals
+-------
+
+The core, as well as scenes and sources, have a set of standard signals
+that are used to determine when something happens or changes.
+
+Typically the most important signals are the
+:ref:`output_signal_handler_reference`:  the **start**, **stop**,
+**starting**, **stopping**, **reconnect**, **reconnect_success**
+signals in particular.
+
+Most other signals for scenes/sources are optional if you are the only
+thing controlling their state.  However, it's generally recommended to
+watch most signals when possible for consistency.  See
+:ref:`source_signal_handler_reference` and :ref:`scene_signal_reference`
+for more information.
+
+For example, let's say you wanted to connect a callback to the **stop**
+signal of an output.  The **stop** signal has two parameters:  *output*
+and *code*.  A callback for this signal would typically look something
+like this:
+
+.. code:: cpp
+
+   static void output_stopped(void *my_data, calldata_t *cd)
+   {
+           obs_output_t *output = calldata_ptr(cd, "output");
+           int code = calldata_int(cd, "code");
+
+           [...]
+   }
+
+*(Note that callbacks are not thread-safe.)*
+
+Then to connect it to the **stop** signal, you use the
+:c:func:`signal_handler_connect()` with the callback.  In this case for
+example:
+
+.. code:: cpp
+
+   signal_handler_t *handler = obs_output_get_signal_handler(output);
+   signal_handler_connect(handler, "stop", output_stopped);
+
+
+.. _displaying_sources:
+
+Displaying Sources
+------------------
+
+Sources are displayed on stream/recording via :ref:`output_channels`
+with the :c:func:`obs_set_output_source()` function.  There are 64
+channels that you can assign sources to, which will draw on top of each
+other in ascending index order.  Typically, a normal source shouldn't be
+directly assigned with this function; you would use a scene or a
+transition containing scenes.
+
+To draw one or more sources together with a specific transform applied
+to them, scenes are used.  To create a scene, you call
+:c:func:`obs_scene_create()`.  Child sources are referenced using scene
+items, and then specific transforms are applied to those scene items.
+Scene items are not sources but containers for sources; the same source
+can be referenced by multiple scene items within the same scene, or can
+be referenced in multiple scenes.  To create a scene item that
+references a source, you call :c:func:`obs_scene_add()`, which returns a
+new reference to a scene item.
+
+To change the transform of a scene item, you typically would call a
+function like :c:func:`obs_sceneitem_set_pos()` to change its position,
+:c:func:`obs_sceneitem_set_rot()` to change its rotation, or
+:c:func:`obs_sceneitem_set_scale()` to change its scaling.  Scene items
+can also force scaling in to a custom size constraint referred to as a
+"bounding box"; a bounding box will force the source to be drawn at a
+specific size and with specific scaling constraint within that size.  To
+use a bounding box, you call the
+:c:func:`obs_sceneitem_set_bounds_type()`,
+:c:func:`obs_sceneitem_set_bounds()`, and
+:c:func:`obs_sceneitem_set_bounds_alignment()`.  Though the easiest way
+to handle everything related to transforms is to use the
+:c:func:`obs_sceneitem_set_info()` and
+:c:func:`obs_sceneitem_get_info()` functions.  See
+:ref:`scene_item_reference` for all the functions related to scene
+items.
+
+Usually, a smooth transition between multiple scenes is required.  To do
+this, transitions are used.  To create a transition, you use
+:c:func:`obs_source_create()` or :c:func:`obs_source_create_private()`
+like any other source.  Then, to activate a transition, you call
+:c:func:`obs_transition_start()`.  When the transition is not active and
+is only displaying one source, it performs a pass-through to the current
+displaying source.  See :ref:`transitions` for more functions related to
+using transitions.
+
+The recommended way to set up your structure is to have a transition as
+the source that is used as the main output source, then your scene as a
+child of the transition, then your sources as children in the scene.
+When you need to switch to a new scene, simply call
+:c:func:`obs_transition_start()`.
+
+
+Outputs, Encoders, and Services
+-------------------------------
+
+Outputs, encoders, and services are all used together, and managed a bit
+differently than sources.  There currently is no global function to
+save/load them, that must be accomplished manually for now via their
+settings if needed.
+
+Encoders are used with outputs that expect encoded data (which is almost
+all typical outputs), such as standard file recording or streaming.
+
+Services are used with outputs to a stream; the `RTMP output`_ is the
+quintessential example of this.
+
+Here's an example of how an output would be used with encoders and
+services:
+
+.. code:: cpp
+
+   obs_encoder_set_video(my_h264_encoder, obs_get_video());
+   obs_encoder_set_audio(my_aac_encoder, obs_get_audio());
+   obs_output_set_video_encoder(my_output, my_h264_encoder);
+   obs_output_set_audio_encoder(my_output, my_aac_encoder);
+   obs_output_set_service(my_output, my_service); /* if a stream */
+   obs_output_start(my_output);
+
+Once the output has started successfully, it automatically starts
+capturing the video and/or audio from the current video/audio output
+(i.e. any sources that are assigned to the :ref:`output_channels`).
+
+If the output fails to start up, it will send the **stop** signal with
+an error code in the *code* parameter, possibly accompanied by a
+translated error message stored that can be obtained via the
+:c:func:`obs_output_get_last_error()` function.
+
+.. --------------------------------------------------------------------
+
+.. _RTMP Output: https://github.com/jp9000/obs-studio/blob/master/plugins/obs-outputs/rtmp-stream.c
+.. _UI/qt-display.hpp: https://github.com/jp9000/obs-studio/blob/master/UI/qt-display.hpp
+.. _UI/qt-display.cpp: https://github.com/jp9000/obs-studio/blob/master/UI/qt-display.cpp

docs/sphinx/graphics.rst

@@ -0,0 +1,364 @@
+Rendering Graphics
+==================
+
+Libobs has a custom-made programmable graphics subsystem that wraps both
+Direct3D 11 and OpenGL.  The reason why it was designed with a custom
+graphics subsystem was to accommodate custom capture features only
+available on specific operating systems.
+
+*(Author's note: In retrospect, I probably should have used something
+like ANGLE, but I would have to modify it to accommodate my specific
+use-cases.)*
+
+Most rendering is dependent upon effects.  Effects are used by all video
+objects in libobs; they're used to easily bundle related vertex/pixel
+shaders in to one file.
+
+An effect file has a nearly identical syntax to Direct3D 11 HLSL effect
+files.  The only differences are as follows:
+
+- Sampler states are named "sampler_state"
+- Position semantic is called "POSITION" rather than "SV_Position"
+- Target semantic is called "TARGET" rather than "SV_Target"
+
+*(Author's note: I'm probably missing a few exceptions here, if I am
+please let me know)*
+
+
+The Graphics Context
+--------------------
+
+Using graphics functions isn't possible unless the current thread has
+entered a graphics context, and the graphics context can only be used by
+one thread at a time.  To enter the graphics context, use
+:c:func:`obs_enter_graphics()`, and to leave the graphics context, use
+:c:func:`obs_leave_graphics()`.
+
+Certain callback will automatically be within the graphics context:
+:c:member:`obs_source_info.video_render`, and the draw callback
+parameter of :c:func:`obs_display_add_draw_callback()`, and
+:c:func:`obs_add_main_render_callback()`.
+
+
+Creating Effects
+----------------
+
+Effect Parameters
+^^^^^^^^^^^^^^^^^
+
+To create an effect, it's recommended to start with the uniforms
+(parameters) of the effect.
+
+There are a number of different types of uniforms:
+
++------------------+---------------+------------------+------------+------------+
+| Floating points: | **float**     | **float2**       | **float3** | **float4** |
++------------------+---------------+------------------+------------+------------+
+| Matrices:        | **float3x3**  | **float4x4**     |            |            |
++------------------+---------------+------------------+------------+------------+
+| Integers:        | **int**       | **int2**         | **int3**   | **int4**   |
++------------------+---------------+------------------+------------+------------+
+| Booleans:        | **bool**      |                  |            |            |
++------------------+---------------+------------------+------------+------------+
+| Textures:        | **texture2d** | **texture_cube** |            |            |
++------------------+---------------+------------------+------------+------------+
+
+To get the effect uniform parameters, you use
+:c:func:`gs_effect_get_param_by_name()` or
+:c:func:`gs_effect_get_param_by_idx()`.
+
+Then the uniforms are set through the following functions:
+
+- :c:func:`gs_effect_set_bool()`
+- :c:func:`gs_effect_set_float()`
+- :c:func:`gs_effect_set_int()`
+- :c:func:`gs_effect_set_matrix4()`
+- :c:func:`gs_effect_set_vec2()`
+- :c:func:`gs_effect_set_vec3()`
+- :c:func:`gs_effect_set_vec4()`
+- :c:func:`gs_effect_set_texture()`
+
+There are two "universal" effect parameters that may be expected of
+effects:  **ViewProj**, and **image**.  The **ViewProj** parameter
+(which is a float4x4) is used for the primary view/projection matrix
+combination.  The **image** parameter (which is a texture2d) is a
+commonly used parameter for the main texture; this parameter will be
+used with the functions :c:func:`obs_source_draw()`,
+:c:func:`gs_draw_sprite()`, and
+:c:func:`obs_source_process_filter_end()`.
+
+Here is an example of effect parameters:
+
+.. code:: cpp
+
+   uniform float4x4 ViewProj;
+   uniform texture2d image;
+
+   uniform float4 my_color_param;
+   uniform float my_float_param;
+
+Effect parameters can also have default values.  Default parameters of
+elements that have multiple elements should be treated as an array.
+
+Here are some examples of default parameters:
+
+.. code:: cpp
+
+   uniform float4x4 my_matrix = {1.0, 0.0, 0.0, 0.0,
+                                 0.0, 1.0, 0.0, 0.0,
+                                 0.0, 0.0, 1.0, 0.0,
+                                 0.0, 0.0, 0.0, 1.0};
+
+   uniform float4 my_float4 = {1.0, 0.5, 0.25, 0.0};
+   uniform float my_float = 4.0;
+   uniform int my_int = 5;
+
+Effect Sampler States
+^^^^^^^^^^^^^^^^^^^^^
+
+Then, if textures are used, sampler states should be defined.  Sampler
+states have certain sub-parameters:
+
+- **Filter** - The type of filtering to use.  Can be one of the
+  following values:
+
+  - **Anisotropy**
+  - **Point**
+  - **Linear**
+  - **MIN_MAG_POINT_MIP_LINEAR**
+  - **MIN_POINT_MAG_LINEAR_MIP_POINT**
+  - **MIN_POINT_MAG_MIP_LINEAR**
+  - **MIN_LINEAR_MAG_MIP_POINT**
+  - **MIN_LINEAR_MAG_POINT_MIP_LINEAR**
+  - **MIN_MAG_LINEAR_MIP_POINT**
+
+- **AddressU**, **AddressV** -  Specifies how to handle the sampling
+  when the coordinate goes beyond 0.0..1.0.  Can be one of the following
+  values:
+
+  - **Wrap** or **Repeat**
+  - **Clamp** or **None**
+  - **Mirror**
+  - **Border** (uses *BorderColor* to fill the color)
+  - **MirrorOnce**
+
+- **BorderColor** - Specifies the border color if using the "Border"
+  address mode.  This value should be a hexadecimal value representing
+  the color, in the format of: AARRGGBB.  For example, 7FFF0000 would
+  have its alpha value at 127, its red value at 255, and blue and green
+  at 0.  If *Border* is not used as an addressing type, this value is
+  ignored.
+
+Here is an example of writing a sampler state in an effect file:
+
+.. code:: cpp
+
+   sampler_state defaultSampler {
+           Filter      = Linear;
+           AddressU    = Border;
+           AddressV    = Border;
+           BorderColor = 7FFF0000;
+   };
+
+This sampler state would use linear filtering, would use border
+addressing for texture coordinate values beyond 0.0..1.0, and the border
+color would be the color specified above.
+
+When a sampler state is used, it's used identically to the HLSL form:
+
+.. code:: cpp
+
+   [...]
+
+   uniform texture2d image;
+
+   sampler_state defaultSampler {
+           Filter      = Linear;
+           AddressU    = Clamp;
+           AddressV    = Clamp;
+   };
+
+   [...]
+
+   float4 MyPixelShaderFunc(VertInOut vert_in) : TARGET
+   {
+           return image.Sample(def_sampler, vert_in.uv);
+   }
+
+Effect Vertex/Pixel Semantics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Then structures should be defined for inputs and outputs vertex
+semantics.
+
+Vertex components can have the following semantics:
+
+- **COLOR**          - Color value (*float4*).
+- **POSITION**       - Position value (*float4*).
+- **NORMAL**         - Normal value (*float4*).
+- **TANGENT**        - Tangent value (*float4*).
+- **TEXCOORD[0..7]** - Texture cooordinate value (*float2*, *float3*, or
+  *float4*).
+
+Here is an example of a vertex semantic structure:
+
+.. code:: cpp
+
+   struct VertexIn {
+           float4 my_position : POSITION;
+           float2 my_texcoord : TEXCOORD0;
+   };
+
+These semantic structures are then passed in as a parameter to the
+primary shader entry point, and used as a return value for the vertex
+shader.  Note that the vertex shader is allowed to return different
+semantics than it takes in; but the return type of the vertex shader and
+the parameter of the pixel shader must match.
+
+The semantic structure used for the parameter to the vertex shader
+function will require that the vertex buffer have those values, so if
+you have POSITION and TEXCOORD0, the vertex buffer will have to have at
+least a position buffer and a texture coordinate buffer in it.
+
+For pixel shaders, they need to return with a TARGET semantic (which is
+a float4 RGBA value).  Here is an example of how it's usually used with
+a pixel shader function:
+
+.. code:: cpp
+
+   float4 MyPixelShaderFunc(VertInOut vert_in) : TARGET
+   {
+           return image.Sample(def_sampler, vert_in.uv);
+   }
+
+
+Effect Techniques
+^^^^^^^^^^^^^^^^^
+
+Techniques are used to define the primary vertex/pixel shader entry
+functions per pass.  One technique can have multiple passes or custom
+pass setup.
+
+*(Author's note: These days, multiple passes aren't really needed; GPUs
+are powerful enough to where you can perform all actions in the same
+shader.  Named passes can be useful for custom draw setups, but even
+then you can just make it a separate technique.  For that reason, it's
+best to just ignore the extra pass functionality.)*
+
+If you're making an effect filter for video sources, typically you'd
+name the pass **Draw**, and then
+:c:func:`obs_source_process_filter_end()` will automatically call that
+specific effect name.  However, you can also use
+:c:func:`obs_source_process_filter_tech_end()` to make the filter use a
+specific technique by its name.
+
+The first parameter of the vertex/pixel shader functions in passes
+should always be the name of its vertex semantic structure parameter.
+
+For techniques, it's better to show some examples of how techniques
+would be used:
+
+.. code:: cpp
+
+   uniform float4x4 ViewProj;
+   uniform texture2d image;
+
+   struct VertInOut {
+           float4 my_position : POSITION;
+           float2 my_texcoord : TEXCOORD0;
+   };
+
+   VertInOut MyVertexShaderFunc(VertInOut vert_in)
+   {
+           VertInOut vert_out;
+           vert_out.pos = mul(float4(vert_in.pos.xyz, 1.0), ViewProj);
+           vert_out.uv  = vert_in.uv;
+           return vert_out;
+   }
+
+   float4 MyPixelShaderFunc(VertInOut vert_in) : TARGET
+   {
+           return image.Sample(def_sampler, vert_in.uv);
+   }
+
+   technique Draw
+   {
+           pass
+           {
+                   vertex_shader = MyVertexShaderFunc(vert_in);
+                   pixel_shader  = MyPixelShaderFunc(vert_in);
+           }
+   };
+
+Using Effects
+-------------
+
+The recommended way to use effects is like so:
+
+.. code:: cpp
+
+   for (gs_effect_loop(effect, "technique")) {
+           [draw calls go here]
+   }
+
+This will automatically handle loading/unloading of the effect and its
+shaders for a given technique name.
+
+
+Rendering Video Sources
+-----------------------
+
+A synchronous video source renders in its
+:c:member:`obs_source_info.video_render` callback.
+
+Sources can render with custom drawing (via the OBS_SOURCE_CUSTOM_DRAW
+output capability flag), or without.  When sources render without custom
+rendering, it's recommended to render a single texture with
+:c:func:`obs_source_draw()`.  Otherwise the source is expected to
+perform rendering on its own and manage its own effects.
+
+Libobs comes with a set of default/standard effects that can be accessed
+via the :c:func:`obs_get_base_effect()` function.  You can use these
+effects to render, or you can create custom effects with
+:c:func:`gs_effect_create_from_file()` and render with a custom effect.
+
+
+Rendering Video Effect Filters
+------------------------------
+
+For most video effect filters, it comprises of adding a layer of
+processing shaders to an existing image in its
+:c:member:`obs_source_info.video_render` callback.  When this is the
+case, it's expected that the filter has its own effect created, and to
+draw the effect, one would simply use the
+:c:func:`obs_source_process_filter_begin()` function, set the parameters
+on your custom effect, then call either
+:c:func:`obs_source_process_filter_end()` or
+:c:func:`obs_source_process_filter_tech_end()` to finish rendering the
+filter.
+
+Here's an example of rendering a filter from the color key filter:
+
+.. code:: cpp
+
+   static void color_key_render(void *data, gs_effect_t *effect)
+   {
+           struct color_key_filter_data *filter = data;
+   
+           if (!obs_source_process_filter_begin(filter->context, GS_RGBA,
+                                   OBS_ALLOW_DIRECT_RENDERING))
+                   return;
+   
+           gs_effect_set_vec4(filter->color_param, &filter->color);
+           gs_effect_set_float(filter->contrast_param, filter->contrast);
+           gs_effect_set_float(filter->brightness_param, filter->brightness);
+           gs_effect_set_float(filter->gamma_param, filter->gamma);
+           gs_effect_set_vec4(filter->key_color_param, &filter->key_color);
+           gs_effect_set_float(filter->similarity_param, filter->similarity);
+           gs_effect_set_float(filter->smoothness_param, filter->smoothness);
+   
+           obs_source_process_filter_end(filter->context, filter->effect, 0, 0);
+   
+           UNUSED_PARAMETER(effect);
+   }
+

docs/sphinx/index.rst

@@ -0,0 +1,24 @@
+.. OBS Studio documentation master file, created by
+   sphinx-quickstart on Wed Oct 25 00:03:21 2017.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+.. _contents:
+
+Welcome to OBS Studio's documentation!
+======================================
+
+.. toctree::
+   :maxdepth: 3
+
+   backend-design
+   plugins
+   frontends
+   graphics
+   reference-core
+   reference-modules
+   reference-core-objects
+   reference-libobs-util
+   reference-libobs-callback
+   reference-libobs-graphics
+   reference-libobs-media-io

docs/sphinx/make.bat

@@ -0,0 +1,36 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+set SPHINXPROJ=OBSStudio
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+
+:end
+popd

docs/sphinx/plugins.rst

@@ -0,0 +1,569 @@
+Plugins
+=======
+Almost all custom functionality is added through plugin modules, which
+are typically dynamic libraries or scripts.  The ability to capture
+and/or output audio/video, make a recording, output to an RTMP stream,
+encode in x264 are all examples of things that are accomplished via
+plugin modules.
+
+Plugins can implement sources, outputs, encoders, and services.
+
+
+Plugin Module Headers
+---------------------
+These are some notable headers commonly used by plugins:
+
+- `libobs/obs-module.h`_ -- The primary header used for creating plugin
+  modules.  This file automatically includes the following files: 
+
+  - `libobs/obs.h`_ -- The main libobs header.  This file automatically
+    includes the following files:
+
+    - `libobs/obs-source.h`_ -- Used for implementing sources in plugin
+      modules
+
+    - `libobs/obs-output.h`_ -- Used for implementing outputs in plugin
+      modules
+
+    - `libobs/obs-encoder.h`_ -- Used for implementing encoders in
+      plugin modules
+
+    - `libobs/obs-service.h`_ -- Used for implementing services in
+      plugin modules
+
+    - `libobs/obs-data.h`_ -- Used for managing settings for libobs
+      objects
+
+    - `libobs/obs-properties.h`_ -- Used for generating properties for
+      libobs objects
+
+    - `libobs/graphics/graphics.h`_ -- Used for graphics rendering
+
+
+Common Directory Structure and CMakeLists.txt
+---------------------------------------------
+The common way source files are organized is to have one file for plugin
+initialization, and then specific files for each individual object
+you're implementing.  For example, if you were to create a plugin called
+'my-plugin', you'd have something like my-plugin.c where plugin
+initialization is done, my-source.c for the definition of a custom
+source, my-output.c for the definition of a custom output, etc.  (This
+is not a rule of course)
+
+This is an example of a common directory structure for a native plugin
+module::
+
+  my-plugin/data/locale/en-US.ini
+  my-plugin/CMakeLists.txt
+  my-plugin/my-plugin.c
+  my-plugin/my-source.c
+  my-plugin/my-output.c
+  my-plugin/my-encoder.c
+  my-plugin/my-service.c
+
+This would be an example of a common CMakeLists.txt file associated with
+these files::
+
+  # my-plugin/CMakeLists.txt
+
+  project(my-plugin)
+
+  set(my-plugin_SOURCES
+        my-plugin.c
+        my-source.c
+        my-output.c
+        my-encoder.c
+        my-service.c)
+
+  add_library(my-plugin MODULE
+        ${my-plugin_SOURCES})
+  target_link_libraries(my-plugin
+        libobs)
+
+  install_obs_plugin_with_data(my-plugin data)
+
+
+Native Plugin Initialization
+----------------------------
+To create a native plugin module, you will need to include the
+`libobs/obs-module.h`_ header, use :c:func:`OBS_DECLARE_MODULE()` macro,
+then create a definition of the function :c:func:`obs_module_load()`.
+In your :c:func:`obs_module_load()` function, you then register any of
+your custom sources, outputs, encoders, or services.  See the
+:doc:`reference-modules` for more information.
+
+The following is an example of my-plugin.c, which would register one
+object of each type:
+
+.. code:: cpp
+
+  /* my-plugin.c */
+  #include <obs-module.h>
+
+  /* Defines common functions (required) */
+  OBS_DECLARE_MODULE()
+
+  /* Implements common ini-based locale (optional) */
+  OBS_MODULE_USE_DEFAULT_LOCALE("my-plugin", "en-US")
+
+  extern struct obs_source_info  my_source;  /* Defined in my-source.c  */
+  extern struct obs_output_info  my_output;  /* Defined in my-output.c  */
+  extern struct obs_encoder_info my_encoder; /* Defined in my-encoder.c */
+  extern struct obs_service_info my_service; /* Defined in my-service.c */
+
+  bool obs_module_load(void)
+  {
+          obs_register_source(&my_source);
+          obs_register_output(&my_output);
+          obs_register_encoder(&my_encoder);
+          obs_register_service(&my_service);
+          return true;
+  }
+
+
+.. _plugins_sources:
+
+Sources
+-------
+Sources are used to render video and/or audio on stream.  Things such as
+capturing displays/games/audio, playing a video, showing an image, or
+playing audio.  Sources can also be used to implement audio and video
+filters as well as transitions.  The `libobs/obs-source.h`_ file is the
+dedicated header for implementing sources.  See the
+:doc:`reference-sources` for more information.
+
+For example, to implement a source object, you need to define an
+:c:type:`obs_source_info` structure and fill it out with information and
+callbacks related to your source:
+
+.. code:: cpp
+
+  /* my-source.c */
+
+  [...]
+
+  struct obs_source_info my_source {
+          .id           = "my_source",
+          .type         = OBS_SOURCE_TYPE_INPUT,
+          .output_flags = OBS_SOURCE_VIDEO,
+          .get_name     = my_source_name,
+          .create       = my_source_create,
+          .destroy      = my_source_destroy,
+          .update       = my_source_update,
+          .video_render = my_source_render,
+          .get_width    = my_source_width,
+          .get_height   = my_source_height
+  };
+
+Then, in my-plugin.c, you would call :c:func:`obs_register_source()` in
+:c:func:`obs_module_load()` to register the source with libobs.
+
+.. code:: cpp
+
+  /* my-plugin.c */
+
+  [...]
+  
+  extern struct obs_source_info  my_source;  /* Defined in my-source.c  */
+
+  bool obs_module_load(void)
+  {
+          obs_register_source(&my_source);
+
+          [...]
+
+          return true;
+  }
+
+Some simple examples of sources:
+
+- Synchronous video source: The `image source <https://github.com/jp9000/obs-studio/blob/master/plugins/image-source/image-source.c>`_
+- Asynchronous video source: The `random texture test source <https://github.com/jp9000/obs-studio/blob/master/test/test-input/test-random.c>`_
+- Audio source: The `sine wave test source <https://github.com/jp9000/obs-studio/blob/master/test/test-input/test-sinewave.c>`_
+- Video filter: The `test video filter <https://github.com/jp9000/obs-studio/blob/master/test/test-input/test-filter.c>`_
+- Audio filter: The `gain audio filter <https://github.com/jp9000/obs-studio/blob/master/plugins/obs-filters/gain-filter.c>`_
+
+
+.. _plugins_outputs:
+
+Outputs
+-------
+Outputs allow the ability to output the currently rendering audio/video.
+Streaming and recording are two common examples of outputs, but not the
+only types of outputs.  Outputs can receive the raw data or receive
+encoded data.  The `libobs/obs-output.h`_ file is the dedicated header
+for implementing outputs.  See the :doc:`reference-outputs` for more
+information.
+
+For example, to implement an output object, you need to define an
+:c:type:`obs_output_info` structure and fill it out with information and
+callbacks related to your output:
+
+.. code:: cpp
+
+  /* my-output.c */
+
+  [...]
+
+  struct obs_output_info my_output {
+          .id                   = "my_output",
+          .flags                = OBS_OUTPUT_AV | OBS_OUTPUT_ENCODED,
+          .get_name             = my_output_name,
+          .create               = my_output_create,
+          .destroy              = my_output_destroy,
+          .start                = my_output_start,
+          .stop                 = my_output_stop,
+          .encoded_packet       = my_output_data,
+          .get_total_bytes      = my_output_total_bytes,
+          .encoded_video_codecs = "h264",
+          .encoded_audio_codecs = "aac"
+  };
+
+Then, in my-plugin.c, you would call :c:func:`obs_register_output()` in
+:c:func:`obs_module_load()` to register the output with libobs.
+
+.. code:: cpp
+
+  /* my-plugin.c */
+
+  [...]
+  
+  extern struct obs_output_info  my_output;  /* Defined in my-output.c  */
+
+  bool obs_module_load(void)
+  {
+          obs_register_output(&my_output);
+
+          [...]
+
+          return true;
+  }
+
+Some examples of outputs:
+
+- Encoded video/audio outputs:
+
+  - The `FLV output <https://github.com/jp9000/obs-studio/blob/master/plugins/obs-outputs/flv-output.c>`_
+  - The `FFmpeg muxer output <https://github.com/jp9000/obs-studio/blob/master/plugins/obs-ffmpeg/obs-ffmpeg-mux.c>`_
+  - The `RTMP stream output <https://github.com/jp9000/obs-studio/blob/master/plugins/obs-outputs/rtmp-stream.c>`_
+
+- Raw video/audio outputs:
+
+  - The `FFmpeg output <https://github.com/jp9000/obs-studio/blob/master/plugins/obs-ffmpeg/obs-ffmpeg-output.c>`_
+
+
+.. _plugins_encoders:
+
+Encoders
+--------
+Encoders are OBS-specific implementations of video/audio encoders, which
+are used with outputs that use encoders.  x264, NVENC, Quicksync are
+examples of encoder implementations.  The `libobs/obs-encoder.h`_ file
+is the dedicated header for implementing encoders.  See the
+:doc:`reference-encoders` for more information.
+
+For example, to implement an encoder object, you need to define an
+:c:type:`obs_encoder_info` structure and fill it out with information
+and callbacks related to your encoder:
+
+.. code:: cpp
+
+  /* my-encoder.c */
+
+  [...]
+
+  struct obs_encoder_info my_encoder_encoder = {
+          .id             = "my_encoder",
+          .type           = OBS_ENCODER_VIDEO,
+          .codec          = "h264",
+          .get_name       = my_encoder_name,
+          .create         = my_encoder_create,
+          .destroy        = my_encoder_destroy,
+          .encode         = my_encoder_encode,
+          .update         = my_encoder_update,
+          .get_extra_data = my_encoder_extra_data,
+          .get_sei_data   = my_encoder_sei,
+          .get_video_info = my_encoder_video_info
+  };
+
+Then, in my-plugin.c, you would call :c:func:`obs_register_encoder()`
+in :c:func:`obs_module_load()` to register the encoder with libobs.
+
+.. code:: cpp
+
+  /* my-plugin.c */
+
+  [...]
+  
+  extern struct obs_encoder_info my_encoder; /* Defined in my-encoder.c */
+
+  bool obs_module_load(void)
+  {
+          obs_register_encoder(&my_encoder);
+
+          [...]
+
+          return true;
+  }
+
+**IMPORTANT NOTE:** Encoder settings currently have a few expected
+common setting values that should have a specific naming convention:
+
+  - **"bitrate"** - This value should be used for both video and audio
+    encoders: bitrate, in kilobits.
+  - **"rate_control"** - This is a setting used for video encoders.
+    It's generally expected to have at least a "CBR" rate control.
+    Other common rate controls are "VBR", "CQP".
+  - **"keyint_sec"** - For video encoders, sets the keyframe interval
+    value, in seconds, or closest possible approximation.  *(Author's
+    note: This should have have been "keyint", in frames.)*
+
+Examples of encoders:
+
+- Video encoders:
+
+  - The `x264 encoder <https://github.com/jp9000/obs-studio/tree/master/plugins/obs-x264>`_
+  - The `FFmpeg NVENC encoder <https://github.com/jp9000/obs-studio/blob/master/plugins/obs-ffmpeg/obs-ffmpeg-nvenc.c>`_
+  - The `Quicksync encoder <https://github.com/jp9000/obs-studio/tree/master/plugins/obs-qsv11>`_
+
+- Audio encoders:
+
+  - The `FFmpeg AAC/Opus encoder <https://github.com/jp9000/obs-studio/blob/master/plugins/obs-ffmpeg/obs-ffmpeg-audio-encoders.c>`_
+
+
+.. _plugins_services:
+
+Services
+--------
+Services are custom implementations of streaming services, which are
+used with outputs that stream.  For example, you could have a custom
+implementation for streaming to Twitch, and another for YouTube to allow
+the ability to log in and use their APIs to do things such as get the
+RTMP servers or control the channel.  The `libobs/obs-service.h`_ file
+is the dedicated header for implementing services.  See the
+:doc:`reference-services` for more information.
+
+*(Author's note: the service API is incomplete as of this writing)*
+
+For example, to implement a service object, you need to define an
+:c:type:`obs_service_info` structure and fill it out with information
+and callbacks related to your service:
+
+.. code:: cpp
+
+  /* my-service.c */
+
+  [...]
+
+  struct obs_service_info my_service_service = {
+          .id       = "my_service",
+          .get_name = my_service_name,
+          .create   = my_service_create,
+          .destroy  = my_service_destroy,
+          .encode   = my_service_encode,
+          .update   = my_service_update,
+          .get_url  = my_service_url,
+          .get_key  = my_service_key
+  };
+
+Then, in my-plugin.c, you would call :c:func:`obs_register_service()` in
+:c:func:`obs_module_load()` to register the service with libobs.
+
+.. code:: cpp
+
+  /* my-plugin.c */
+
+  [...]
+  
+  extern struct obs_service_info my_service; /* Defined in my-service.c */
+
+  bool obs_module_load(void)
+  {
+          obs_register_service(&my_service);
+
+          [...]
+
+          return true;
+  }
+
+The only two existing services objects are the "common RTMP services"
+and "custom RTMP service" objects in `plugins/rtmp-services
+<https://github.com/jp9000/obs-studio/tree/master/plugins/rtmp-services>`_
+
+
+Settings
+--------
+Settings (see `libobs/obs-data.h`_) are used to get or set settings data
+typically associated with libobs objects, and can then be saved and
+loaded via Json text.  See the :doc:`reference-settings` for more
+information.
+
+The *obs_data_t* is the equivalent of a Json object, where it's a string
+table of sub-objects, and the *obs_data_array_t* is similarly used to
+store an array of *obs_data_t* objects, similar to Json arrays (though
+not quite identical).
+
+To create an *obs_data_t* or *obs_data_array_t* object, you'd call the
+:c:func:`obs_data_create()` or :c:func:`obs_data_array_create()`
+functions.  *obs_data_t* and *obs_data_array_t* objects are reference
+counted, so when you are finished with the object, call
+:c:func:`obs_data_release()` or :c:func:`obs_data_array_release()` to
+release those references.  Any time an *obs_data_t* or
+*obs_data_array_t* object is returned by a function, their references
+are incremented, so you must release those references each time.
+
+To set values for an *obs_data_t* object, you'd use one of the following
+functions:
+
+.. code:: cpp
+
+  /* Set functions */
+  EXPORT void obs_data_set_string(obs_data_t *data, const char *name, const char *val);
+  EXPORT void obs_data_set_int(obs_data_t *data, const char *name, long long val);
+  EXPORT void obs_data_set_double(obs_data_t *data, const char *name, double val);
+  EXPORT void obs_data_set_bool(obs_data_t *data, const char *name, bool val);
+  EXPORT void obs_data_set_obj(obs_data_t *data, const char *name, obs_data_t *obj);
+  EXPORT void obs_data_set_array(obs_data_t *data, const char *name, obs_data_array_t *array);
+
+Similarly, to get a value from an *obs_data_t* object, you'd use one of
+the following functions:
+
+.. code:: cpp
+
+  /* Get functions */
+  EXPORT const char *obs_data_get_string(obs_data_t *data, const char *name);
+  EXPORT long long obs_data_get_int(obs_data_t *data, const char *name);
+  EXPORT double obs_data_get_double(obs_data_t *data, const char *name);
+  EXPORT bool obs_data_get_bool(obs_data_t *data, const char *name);
+  EXPORT obs_data_t *obs_data_get_obj(obs_data_t *data, const char *name);
+  EXPORT obs_data_array_t *obs_data_get_array(obs_data_t *data, const char *name);
+
+Unlike typical Json data objects, the *obs_data_t* object can also set
+default values.  This allows the ability to control what is returned if
+there is no value assigned to a specific string in an *obs_data_t*
+object when that data is loaded from a Json string or Json file.  Each
+libobs object also has a *get_defaults* callback which allows setting
+the default settings for the object on creation.
+
+These functions control the default values are as follows:
+
+.. code:: cpp
+
+  /* Default value functions. */
+  EXPORT void obs_data_set_default_string(obs_data_t *data, const char *name, const char *val);
+  EXPORT void obs_data_set_default_int(obs_data_t *data, const char *name, long long val);
+  EXPORT void obs_data_set_default_double(obs_data_t *data, const char *name, double val);
+  EXPORT void obs_data_set_default_bool(obs_data_t *data, const char *name, bool val);
+  EXPORT void obs_data_set_default_obj(obs_data_t *data, const char *name, obs_data_t *obj);
+
+
+Properties
+----------
+Properties (see `libobs/obs-properties.h`_) are used to automatically
+generate user interface to modify settings for a libobs object (if
+desired).  Each libobs object has a *get_properties* callback which is
+used to generate properties.  The properties API defines specific
+properties that are linked to the object's settings, and the front-end
+uses those properties to generate widgets in order to allow the user to
+modify the settings.  For example, if you had a boolean setting, you
+would use :c:func:`obs_properties_add_bool()` to allow the user to be
+able to change that setting.  See the :doc:`reference-properties` for
+more information.
+
+An example of this:
+
+.. code:: cpp
+
+   static obs_properties_t *my_source_properties(void *data)
+   {
+           obs_properties_t *ppts = obs_properties_create();
+           obs_properties_add_bool(ppts, "my_bool",
+                           obs_module_text("MyBool"));
+           UNUSED_PARAMETER(data);
+           return ppts;
+   }
+
+   [...]
+
+   struct obs_source_info my_source {
+           .get_properties = my_source_properties,
+           [...]
+   };
+
+The *data* parameter is the object's data if the object is present.
+Typically this is unused and probably shouldn't be used if possible.  It
+can be null if the properties are retrieved without an object associated
+with it.
+
+Properties can also be modified depending on what settings are shown.
+For example, you can mark certain properties as disabled or invisible
+depending on what a particular setting is set to using the
+:c:func:`obs_property_set_modified_callback()` function.
+
+For example, if you wanted boolean property A to hide text property B:
+
+.. code:: cpp
+
+   static bool setting_a_modified(obs_properties_t *ppts,
+                   obs_property_t *p, obs_data_t *settings)
+   {
+           bool enabled = obs_data_get_bool(settings, "setting_a");
+           p = obs_properties_get(ppts, "setting_b");
+           obs_property_set_enabled(p, enabled);
+
+           /* return true to update property widgets, false
+              otherwise */
+           return true;
+   }
+
+   [...]
+
+   static obs_properties_t *my_source_properties(void *data)
+   {
+           obs_properties_t *ppts = obs_properties_create();
+           obs_property_t *p;
+
+           p = obs_properties_add_bool(ppts, "setting_a",
+                           obs_module_text("SettingA"));
+           obs_property_set_modified_callback(p, setting_a_modified);
+
+           obs_properties_add_text(ppts, "setting_b",
+                           obs_module_text("SettingB"),
+                           OBS_TEXT_DEFAULT);
+           return ppts;
+   }
+
+
+Localization
+------------
+Typically, most plugins bundled with OBS Studio will use a simple
+ini-file localization method, where each file is a different language.
+When using this method, the :c:func:`OBS_MODULE_USE_DEFAULT_LOCALE()`
+macro is used which will automatically load/destroy the locale data with
+no extra effort on part of the plugin.  Then the
+:c:func:`obs_module_text()` function (which is automatically declared as
+an extern by `libobs/obs-module.h`_) is used when text lookup is needed.
+
+There are two exports the module used to load/destroy locale: the
+:c:func:`obs_module_set_locale()` export, and the
+:c:func:`obs_module_free_locale()` export.  The
+:c:func:`obs_module_set_locale()` export is called by libobs to set the
+current language, and then the :c:func:`obs_module_free_locale()` export
+is called by libobs on destruction of the module.  If you wish to
+implement a custom locale implementation for your plugin, you'd want to
+define these exports along with the :c:func:`obs_module_text()` extern
+yourself instead of relying on the
+:c:func:`OBS_MODULE_USE_DEFAULT_LOCALE()` macro.
+
+
+.. ---------------------------------------------------------------------------
+
+.. _libobs/obs-module.h: https://github.com/jp9000/obs-studio/blob/master/libobs/obs-module.h
+.. _libobs/obs.h: https://github.com/jp9000/obs-studio/blob/master/libobs/obs.h
+.. _libobs/obs-source.h: https://github.com/jp9000/obs-studio/blob/master/libobs/obs-source.h
+.. _libobs/obs-output.h: https://github.com/jp9000/obs-studio/blob/master/libobs/obs-output.h
+.. _libobs/obs-encoder.h: https://github.com/jp9000/obs-studio/blob/master/libobs/obs-encoder.h
+.. _libobs/obs-service.h: https://github.com/jp9000/obs-studio/blob/master/libobs/obs-service.h
+.. _libobs/obs-data.h: https://github.com/jp9000/obs-studio/blob/master/libobs/obs-data.h
+.. _libobs/obs-properties.h: https://github.com/jp9000/obs-studio/blob/master/libobs/obs-properties.h
+.. _libobs/graphics/graphics.h: https://github.com/jp9000/obs-studio/blob/master/libobs/graphics/graphics.h

docs/sphinx/reference-core-objects.rst

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

docs/sphinx/reference-core.rst

@@ -0,0 +1,643 @@
+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

@@ -0,0 +1,493 @@
+Encoder API Reference (obs_encoder_t)
+=====================================
+
+Encoders are OBS-specific implementations of video/audio encoders, which
+are used with outputs that use encoders.  x264, NVENC, Quicksync are
+examples of encoder implementations.  The `libobs/obs-encoder.h`_ file
+is the dedicated header for implementing encoders
+
+.. type:: obs_encoder_t
+
+   A reference-counted encoder object.
+
+.. type:: obs_weak_encoder_t
+
+   A weak reference to an encoder object.
+
+.. code:: cpp
+
+   #include <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

@@ -0,0 +1,276 @@
+Callback API Reference (libobs/callback)
+========================================
+
+
+Calldata
+--------
+
+The :c:type:`calldata_t` object is used to pass parameters from signal
+handlers or to procedure handlers.
+
+.. type:: calldata_t
+
+---------------------
+
+.. function:: void calldata_init(calldata_t *data)
+
+   Initializes a calldata structure (zeroes it).
+
+   :param data: Calldata structure
+
+---------------------
+
+.. function:: void calldata_free(calldata_t *data)
+
+   Frees a calldata structure.
+
+   :param data: Calldata structure
+
+---------------------
+
+.. function:: void calldata_set_int(calldata_t *data, const char *name, long long val)
+
+   Sets an integer parameter.
+
+   :param data: Calldata structure
+   :param name: Parameter name
+   :param val:  Integer value
+
+---------------------
+
+.. function:: void calldata_set_float(calldata_t *data, const char *name, double val)
+
+   Sets a floating point parameter.
+
+   :param data: Calldata structure
+   :param name: Parameter name
+   :param val:  Floating point value
+
+---------------------
+
+.. function:: void calldata_set_bool(calldata_t *data, const char *name, bool val)
+
+   Sets a boolean parameter.
+
+   :param data: Calldata structure
+   :param name: Parameter name
+   :param val:  Boolean value
+
+---------------------
+
+.. function:: void calldata_set_ptr(calldata_t *data, const char *name, void *ptr)
+
+   Sets a pointer parameter.
+
+   :param data: Calldata structure
+   :param name: Parameter name
+   :param val:  Pointer value
+
+---------------------
+
+.. function:: void calldata_set_string(calldata_t *data, const char *name, const char *str)
+
+   Sets a string parameter.
+
+   :param data: Calldata structure
+   :param name: Parameter name
+   :param val:  String
+
+---------------------
+
+.. function:: long long calldata_int(const calldata_t *data, const char *name)
+
+   Gets an integer parameter.
+
+   :param data: Calldata structure
+   :param name: Parameter name
+   :return:     Integer value
+
+---------------------
+
+.. function:: double calldata_float(const calldata_t *data, const char *name)
+
+   Gets a floating point parameter.
+
+   :param data: Calldata structure
+   :param name: Parameter name
+   :return:     Floating point value
+
+---------------------
+
+.. function:: bool calldata_bool(const calldata_t *data, const char *name)
+
+   Gets a boolean parameter.
+
+   :param data: Calldata structure
+   :param name: Parameter name
+   :return:     Boolean value
+
+---------------------
+
+.. function:: void *calldata_ptr(const calldata_t *data, const char *name)
+
+   Gets a pointer parameter.
+
+   :param data: Calldata structure
+   :param name: Parameter name
+   :return:     Pointer value
+
+---------------------
+
+.. function:: const char *calldata_string(const calldata_t *data, const char *name)
+
+   Gets a string parameter.
+
+   :param data: Calldata structure
+   :param name: Parameter name
+   :return:     String value
+
+---------------------
+
+
+Signals
+-------
+
+Signals are used for all event-based callbacks.
+
+.. code:: cpp
+
+   #include <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

@@ -0,0 +1,65 @@
+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

@@ -0,0 +1,324 @@
+Effects (Shaders)
+=================
+
+Effects are a single collection of related shaders.  They're used for
+easily writing vertex and pixel shaders together all in the same file in
+HLSL format.
+
+.. code:: cpp
+
+   #include <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-graphics.rst

@@ -0,0 +1,1459 @@
+Core Graphics API
+=================
+
+.. code:: cpp
+
+   #include <graphics/graphics.h>
+
+
+Graphics Enumerations
+---------------------
+
+.. type:: enum gs_draw_mode
+
+   Draw mode.  Can be one of the following values:
+
+   - GS_POINTS    - Draws points
+   - GS_LINES     - Draws individual lines
+   - GS_LINESTRIP - Draws a line strip
+   - GS_TRIS      - Draws individual triangles
+   - GS_TRISTRIP  - Draws a triangle strip
+
+.. type:: enum gs_color_format
+
+   Color format.  Can be one of the following values:
+
+   - GS_UNKNOWN     - Unknown format
+   - GS_A8          - 8 bit alpha channel only
+   - GS_R8          - 8 bit red channel only
+   - GS_RGBA        - RGBA, 8 bits per channel
+   - GS_BGRX        - BGRX, 8 bits per channel
+   - GS_BGRA        - BGRA, 8 bits per channel
+   - GS_R10G10B10A2 - RGBA, 10 bits per channel except alpha, which is 2
+     bits
+   - GS_RGBA16      - RGBA, 16 bits per channel
+   - GS_R16         - 16 bit red channel only
+   - GS_RGBA16F     - RGBA, 16 bit floating point per channel
+   - GS_RGBA32F     - RGBA, 32 bit floating point per channel
+   - GS_RG16F       - 16 bit floating point red and green channels only
+   - GS_RG32F       - 32 bit floating point red and green channels only
+   - GS_R16F        - 16 bit floating point red channel only
+   - GS_R32F        - 32 bit floating point red channel only
+   - GS_DXT1        - Compressed DXT1
+   - GS_DXT3        - Compressed DXT3
+   - GS_DXT5        - Compressed DXT5
+
+.. type:: enum gs_zstencil_format
+
+   Z-Stencil buffer format.  Can be one of the following values:
+
+   - GS_ZS_NONE    - No Z-stencil buffer
+   - GS_Z16        - 16 bit Z buffer
+   - GS_Z24_S8     - 24 bit Z buffer, 8 bit stencil
+   - GS_Z32F       - 32 bit floating point Z buffer
+   - GS_Z32F_S8X24 - 32 bit floating point Z buffer, 8 bit stencil
+
+.. type:: enum gs_index_type
+
+   Index buffer type.  Can be one of the following values:
+
+   - GS_UNSIGNED_SHORT - 16 bit index
+   - GS_UNSIGNED_LONG  - 32 bit index
+
+.. type:: enum gs_cull_mode
+
+   Cull mode.  Can be one of the following values:
+
+   - GS_BACK    - Cull back faces
+   - GS_FRONT   - Cull front faces
+   - GS_NEITHER - Cull neither
+
+.. type:: enum gs_blend_type
+
+   Blend type.  Can be one of the following values:
+
+   - GS_BLEND_ZERO
+   - GS_BLEND_ONE
+   - GS_BLEND_SRCCOLOR
+   - GS_BLEND_INVSRCCOLOR
+   - GS_BLEND_SRCALPHA
+   - GS_BLEND_INVSRCALPHA
+   - GS_BLEND_DSTCOLOR
+   - GS_BLEND_INVDSTCOLOR
+   - GS_BLEND_DSTALPHA
+   - GS_BLEND_INVDSTALPHA
+   - GS_BLEND_SRCALPHASAT
+
+.. type:: enum gs_depth_test
+
+   Depth test type.  Can be one of the following values:
+
+   - GS_NEVER
+   - GS_LESS
+   - GS_LEQUAL
+   - GS_EQUAL
+   - GS_GEQUAL
+   - GS_GREATER
+   - GS_NOTEQUAL
+   - GS_ALWAYS
+
+.. type:: enum gs_stencil_side
+
+   Stencil side.  Can be one of the following values:
+
+   - GS_STENCIL_FRONT=1
+   - GS_STENCIL_BACK
+   - GS_STENCIL_BOTH
+
+.. type:: enum gs_stencil_op_type
+
+   Stencil operation type.  Can be one of the following values:
+
+   - GS_KEEP
+   - GS_ZERO
+   - GS_REPLACE
+   - GS_INCR
+   - GS_DECR
+   - GS_INVERT
+
+.. type:: enum gs_cube_sides
+
+   Cubemap side.  Can be one of the following values:
+
+   - GS_POSITIVE_X
+   - GS_NEGATIVE_X
+   - GS_POSITIVE_Y
+   - GS_NEGATIVE_Y
+   - GS_POSITIVE_Z
+   - GS_NEGATIVE_Z
+
+.. type:: enum gs_sample_filter
+
+   Sample filter type.  Can be one of the following values:
+
+   - GS_FILTER_POINT
+   - GS_FILTER_LINEAR
+   - GS_FILTER_ANISOTROPIC
+   - GS_FILTER_MIN_MAG_POINT_MIP_LINEAR
+   - GS_FILTER_MIN_POINT_MAG_LINEAR_MIP_POINT
+   - GS_FILTER_MIN_POINT_MAG_MIP_LINEAR
+   - GS_FILTER_MIN_LINEAR_MAG_MIP_POINT
+   - GS_FILTER_MIN_LINEAR_MAG_POINT_MIP_LINEAR
+   - GS_FILTER_MIN_MAG_LINEAR_MIP_POINT
+
+.. type:: enum gs_address_mode
+
+   Address mode.  Can be one of the following values:
+
+   - GS_ADDRESS_CLAMP
+   - GS_ADDRESS_WRAP
+   - GS_ADDRESS_MIRROR
+   - GS_ADDRESS_BORDER
+   - GS_ADDRESS_MIRRORONCE
+
+.. type:: enum gs_texture_type
+
+   Texture type.  Can be one of the following values:
+
+   - GS_TEXTURE_2D
+   - GS_TEXTURE_3D
+   - GS_TEXTURE_CUBE
+
+
+Graphics Structures
+-------------------
+
+.. type:: struct gs_monitor_info
+.. member:: int gs_monitor_info.rotation_degrees
+.. member:: long gs_monitor_info.x
+.. member:: long gs_monitor_info.y
+.. member:: long gs_monitor_info.cx
+.. member:: long gs_monitor_info.cy
+
+---------------------
+
+.. type:: struct gs_tvertarray
+.. member:: size_t gs_tvertarray.width
+.. member:: void *gs_tvertarray.array
+
+---------------------
+
+.. type:: struct gs_vb_data
+.. member:: size_t gs_vb_data.num
+.. member:: struct vec3 *gs_vb_data.points
+.. member:: struct vec3 *gs_vb_data.normals
+.. member:: struct vec3 *gs_vb_data.tangents
+.. member:: uint32_t *gs_vb_data.colors
+.. member:: size_t gs_vb_data.num_tex
+.. member:: struct gs_tvertarray *gs_vb_data.tvarray
+
+---------------------
+
+.. type:: struct gs_sampler_info
+.. member:: enum gs_sample_filter gs_sampler_info.filter
+.. member:: enum gs_address_mode gs_sampler_info.address_u
+.. member:: enum gs_address_mode gs_sampler_info.address_v
+.. member:: enum gs_address_mode gs_sampler_info.address_w
+.. member:: int gs_sampler_info.max_anisotropy
+.. member:: uint32_t gs_sampler_info.border_color
+
+---------------------
+
+.. type:: struct gs_display_mode
+.. member:: uint32_t gs_display_mode.width
+.. member:: uint32_t gs_display_mode.height
+.. member:: uint32_t gs_display_mode.bits
+.. member:: uint32_t gs_display_mode.freq
+
+---------------------
+
+.. type:: struct gs_rect
+.. member:: int gs_rect.x
+.. member:: int gs_rect.y
+.. member:: int gs_rect.cx
+.. member:: int gs_rect.cy
+
+---------------------
+
+.. type:: struct gs_window
+
+   A window structure.  This structure is used with a native widget.
+
+.. member:: void                    *gs_window.hwnd
+
+   (Windows only) an HWND widget.
+
+.. member:: id  gs_window.view
+
+   (Mac only) A view ID.
+
+.. member:: uint32_t gs_window.id
+            void* gs_window.display
+
+   (Linux only) Window ID and display
+
+---------------------
+
+.. type:: struct gs_init_data
+
+   Swap chain initialization data.
+
+.. member:: struct gs_window        gs_init_data.window
+.. member:: uint32_t                gs_init_data.cx
+.. member:: uint32_t                gs_init_data.cy
+.. member:: uint32_t                gs_init_data.num_backbuffers
+.. member:: enum gs_color_format    gs_init_data.format
+.. member:: enum gs_zstencil_format gs_init_data.zsformat
+.. member:: uint32_t                gs_init_data.adapter
+
+---------------------
+
+
+Initialization Functions
+------------------------
+
+.. function:: void gs_enum_adapters(bool (*callback)(void *param, const char *name, uint32_t id), void *param)
+
+   Enumerates adapters (this really only applies on windows).
+
+   :param callback: Enumeration callback
+   :param param:    Private data passed to the callback
+
+---------------------
+
+.. function:: int gs_create(graphics_t **graphics, const char *module, uint32_t adapter)
+
+   Creates a graphics context
+
+   :param graphics: Pointer to receive the graphics context
+   :param module:   Module name
+   :param adapter:  Adapter index
+   :return:         Can return one of the following values:
+
+                    - GS_SUCCESS
+                    - GS_ERROR_FAIL
+                    - GS_ERROR_MODULE_NOT_FOUND
+                    - GS_ERROR_NOT_SUPPORTED
+
+---------------------
+
+.. function:: void gs_destroy(graphics_t *graphics)
+
+   Destroys a graphics context
+
+   :param graphics: Graphics context
+
+---------------------
+
+.. function:: void gs_enter_context(graphics_t *graphics)
+
+   Enters and locks the graphics context
+
+   :param graphics: Graphics context
+
+---------------------
+
+.. function:: void gs_leave_context(void)
+
+   Leaves and unlocks the graphics context
+
+   :param graphics: Graphics context
+
+---------------------
+
+.. function:: graphics_t *gs_get_context(void)
+
+   :return: The currently locked graphics context for this thread
+
+---------------------
+
+
+Matrix Stack Functions
+----------------------
+
+.. function:: void gs_matrix_push(void)
+
+   Pushes the matrix stack and duplicates the current matrix.
+
+---------------------
+
+.. function:: void gs_matrix_pop(void)
+
+   Pops the current matrix from the matrix stack.
+
+---------------------
+
+.. function:: void gs_matrix_identity(void)
+
+   Sets the current matrix to an identity matrix.
+
+---------------------
+
+.. function:: void gs_matrix_transpose(void)
+
+   Transposes the current matrix.
+
+---------------------
+
+.. function:: void gs_matrix_set(const struct matrix4 *matrix)
+
+   Sets the current matrix.
+
+   :param matrix: The matrix to set
+
+---------------------
+
+.. function:: void gs_matrix_get(struct matrix4 *dst)
+
+   Gets the current matrix
+
+   :param dst: Destination matrix
+
+---------------------
+
+.. function:: void gs_matrix_mul(const struct matrix4 *matrix)
+
+   Multiplies the current matrix
+
+   :param matrix: Matrix to multiply the current stack matrix with
+
+---------------------
+
+.. function:: void gs_matrix_rotquat(const struct quat *rot)
+
+   Multiplies the current matrix with a quaternion
+
+   :param rot: Quaternion to multiple the current matrix stack with
+
+---------------------
+
+.. function:: void gs_matrix_rotaa(const struct axisang *rot)
+              void gs_matrix_rotaa4f(float x, float y, float z, float angle)
+
+   Multiplies the current matrix with an axis angle
+
+   :param rot: Axis angle to multiple the current matrix stack with
+
+---------------------
+
+.. function:: void gs_matrix_translate(const struct vec3 *pos)
+              void gs_matrix_translate3f(float x, float y, float z)
+
+   Translates the current matrix
+
+   :param pos: Vector to translate the current matrix stack with
+
+---------------------
+
+.. function:: void gs_matrix_scale(const struct vec3 *scale)
+              void gs_matrix_scale3f(float x, float y, float z)
+
+   Scales the current matrix
+
+   :param scale: Scale value to scale the current matrix stack with
+
+---------------------
+
+
+Draw Functions
+--------------
+
+.. function:: gs_effect_t *gs_get_effect(void)
+
+   :return: The currently active effect, or *NULL* if none active
+
+---------------------
+
+.. function:: void gs_draw_sprite(gs_texture_t *tex, uint32_t flip, uint32_t width, uint32_t height)
+
+   Draws a 2D sprite.  Sets the "image" parameter of the current effect
+   to the texture and renders a quad.
+
+   If width or height is 0, the width or height of the texture will be
+   used.  The flip value specifies whether the texture should be flipped
+   on the U or V axis with GS_FLIP_U and GS_FLIP_V.
+
+   :param tex:    Texture to draw
+   :param flip:   Can be 0 or a bitwise-OR combination of one of the
+                  following values:
+
+                  - GS_FLIP_U - Flips the texture horizontally
+                  - GS_FLIP_V - Flips the texture vertically
+
+   :param width:  Width
+   :param height: Height
+
+---------------------
+
+.. function:: void gs_draw_sprite_subregion(gs_texture_t *tex, uint32_t flip, uint32_t x, uint32_t y, uint32_t cx, uint32_t cy)
+
+   Draws a subregion of a 2D sprite.  Sets the "image" parameter of the
+   current effect to the texture and renders a quad.
+
+   :param tex:    Texture to draw
+   :param flip:   Can be 0 or a bitwise-OR combination of one of the
+                  following values:
+
+                  - GS_FLIP_U - Flips the texture horizontally
+                  - GS_FLIP_V - Flips the texture vertically
+
+   :param x:      X value within subregion
+   :param y:      Y value within subregion
+   :param cx:     CX value of subregion
+   :param cy:     CY value of subregion
+
+---------------------
+
+.. function:: void gs_reset_viewport(void)
+
+    Sets the viewport to current swap chain size
+
+---------------------
+
+.. function:: void gs_set_2d_mode(void)
+
+    Sets the projection matrix to a default screen-sized orthographic
+    mode
+
+---------------------
+
+.. function:: void gs_set_3d_mode(double fovy, double znear, double zfar)
+
+    Sets the projection matrix to a default screen-sized perspective
+    mode
+
+    :param fovy:  Field of view (in degrees)
+    :param znear: Near plane
+    :param zfar:  Far plane
+
+---------------------
+
+.. function:: void gs_viewport_push(void)
+
+   Pushes/stores the current viewport
+
+---------------------
+
+.. function:: void gs_viewport_pop(void)
+
+   Pops/recalls the last pushed viewport
+
+---------------------
+
+.. function:: void gs_perspective(float fovy, float aspect, float znear, float zfar)
+
+   Sets the projection matrix to a perspective mode
+
+   :param fovy:   Field of view (in degrees)
+   :param aspect: Aspect ratio
+   :param znear:  Near plane
+   :param zfar:   Far plane
+
+---------------------
+
+.. function:: void gs_blend_state_push(void)
+
+   Pushes/stores the current blend state
+
+---------------------
+
+.. function:: void gs_blend_state_pop(void)
+
+   Pops/restores the last blend state
+
+---------------------
+
+.. function:: void gs_reset_blend_state(void)
+
+   Sets the blend state to the default value: source alpha and invert
+   source alpha.
+
+---------------------
+
+
+Swap Chains
+-----------
+
+.. function:: gs_swapchain_t *gs_swapchain_create(const struct gs_init_data *data)
+
+   Creates a swap chain (display view on a native widget)
+
+   :param data: Swap chain initialization data
+   :return:     New swap chain object, or *NULL* if failed
+
+---------------------
+
+.. function:: void     gs_swapchain_destroy(gs_swapchain_t *swapchain)
+
+   Destroys a swap chain
+
+---------------------
+
+.. function:: void gs_resize(uint32_t cx, uint32_t cy)
+
+   Resizes the currently active swap chain
+
+   :param cx: New width
+   :param cy: New height
+
+---------------------
+
+.. function:: void gs_get_size(uint32_t *cx, uint32_t *cy)
+
+   Gets the size of the currently active swap chain
+
+   :param cx: Pointer to receive width
+   :param cy: Pointer to receive height
+
+---------------------
+
+.. function:: uint32_t gs_get_width(void)
+
+   Gets the width of the currently active swap chain
+
+---------------------
+
+.. function:: uint32_t gs_get_height(void)
+
+   Gets the height of the currently active swap chain
+
+---------------------
+
+
+Resource Loading
+----------------
+
+.. function:: void gs_load_vertexbuffer(gs_vertbuffer_t *vertbuffer)
+
+   Loads a vertex buffer
+
+   :param vertbuffer: Vertex buffer to load, or NULL to unload
+
+---------------------
+
+.. function:: void gs_load_indexbuffer(gs_indexbuffer_t *indexbuffer)
+
+   Loads a index buffer
+
+   :param indexbuffer: Index buffer to load, or NULL to unload
+
+---------------------
+
+.. function:: void gs_load_texture(gs_texture_t *tex, int unit)
+
+   Loads a texture (this is usually not called manually)
+
+   :param tex:  Texture to load, or NULL to unload
+   :param unit: Texture unit to load texture for
+
+---------------------
+
+.. function:: void gs_load_samplerstate(gs_samplerstate_t *samplerstate, int unit)
+
+   Loads a sampler state (this is usually not called manually)
+
+   :param samplerstate: Sampler state to load, or NULL to unload
+   :param unit:         Texture unit to load sampler state for
+
+---------------------
+
+.. function:: void gs_load_swapchain(gs_swapchain_t *swapchain)
+
+   Loads a swapchain
+
+   :param swapchain: Swap chain to load, or NULL to unload
+
+---------------------
+
+
+Draw Functions
+--------------
+
+.. function:: gs_texture_t  *gs_get_render_target(void)
+
+   :return: The currently active render target
+
+---------------------
+
+.. function:: gs_zstencil_t *gs_get_zstencil_target(void)
+
+   :return: The currently active Z-stencil target
+
+---------------------
+
+.. function:: void gs_set_render_target(gs_texture_t *tex, gs_zstencil_t *zstencil)
+
+   Sets the active render target
+
+   :param tex:      Texture to set as the active render target
+   :param zstencil: Z-stencil to use as the active render target
+
+---------------------
+
+.. function:: void gs_set_cube_render_target(gs_texture_t *cubetex, int side, gs_zstencil_t *zstencil)
+
+   Sets a cubemap side as the active render target
+
+   :param cubetex:  Cubemap
+   :param side:     Cubemap side
+   :param zstencil: Z-stencil buffer, or *NULL* if none
+
+---------------------
+
+.. function:: void gs_copy_texture(gs_texture_t *dst, gs_texture_t *src)
+
+   Copies a texture
+
+   :param dst: Destination texture
+   :param src: Source texture
+
+---------------------
+
+.. function:: void gs_stage_texture(gs_stagesurf_t *dst, gs_texture_t *src)
+
+   Copies a texture to a staging surface and copies it to RAM.  Ideally
+   best to give this a frame to process to prevent stalling.
+
+   :param dst: Staging surface
+   :param src: Texture to stage
+
+---------------------
+
+.. function:: void gs_begin_scene(void)
+              void gs_end_scene(void)
+
+   Begins/ends a scene (this is automatically called by libobs, there's
+   no need to call this manually).
+
+---------------------
+
+.. function:: void gs_draw(enum gs_draw_mode draw_mode, uint32_t start_vert, uint32_t num_verts)
+
+   Draws a primitive or set of primitives.
+
+   :param draw_mode:  The primitive draw mode to use
+   :param start_vert: Starting vertex index
+   :param num_verts:  Number of vertices
+
+---------------------
+
+.. function:: void gs_clear(uint32_t clear_flags, const struct vec4 *color, float depth, uint8_t stencil)
+
+   Clears color/depth/stencil buffers.
+
+   :param clear_flags: Flags to clear with.  Can be one of the following
+                       values:
+
+                       - GS_CLEAR_COLOR   - Clears color buffer
+                       - GS_CLEAR_DEPTH   - Clears depth buffer
+                       - GS_CLEAR_STENCIL - Clears stencil buffer
+
+   :param color:       Color value to clear the color buffer with
+   :param depth:       Depth value to clear the depth buffer with
+   :param stencil:     Stencil value to clear the stencil buffer with
+
+---------------------
+
+.. function:: void gs_present(void)
+
+   Displays what was rendered on to the current render target
+
+---------------------
+
+.. function:: void gs_flush(void)
+
+   Flushes GPU calls
+
+---------------------
+
+.. function:: void gs_set_cull_mode(enum gs_cull_mode mode)
+
+   Sets the current cull mode.
+
+   :param mode: Cull mode
+
+---------------------
+
+.. function:: enum gs_cull_mode gs_get_cull_mode(void)
+
+   :return: The current cull mode
+
+---------------------
+
+.. function:: void gs_enable_blending(bool enable)
+
+   Enables/disables blending
+
+   :param enable: *true* to enable, *false* to disable
+
+---------------------
+
+.. function:: void gs_enable_depth_test(bool enable)
+
+   Enables/disables depth testing
+
+   :param enable: *true* to enable, *false* to disable
+
+---------------------
+
+.. function:: void gs_enable_stencil_test(bool enable)
+
+   Enables/disables stencil testing
+
+   :param enable: *true* to enable, *false* to disable
+
+---------------------
+
+.. function:: void gs_enable_stencil_write(bool enable)
+
+   Enables/disables stencil writing
+
+   :param enable: *true* to enable, *false* to disable
+
+---------------------
+
+.. function:: void gs_enable_color(bool red, bool green, bool blue, bool alpha)
+
+   Enables/disables specific color channels
+
+   :param red:   *true* to enable red channel, *false* to disable
+   :param green: *true* to enable green channel, *false* to disable
+   :param blue:  *true* to enable blue channel, *false* to disable
+   :param alpha: *true* to enable alpha channel, *false* to disable
+
+---------------------
+
+.. function:: void gs_blend_function(enum gs_blend_type src, enum gs_blend_type dest)
+
+   Sets the blend function
+
+   :param src:  Blend type for the source
+   :param dest: Blend type for the destination
+
+---------------------
+
+.. function:: void gs_blend_function_separate(enum gs_blend_type src_c, enum gs_blend_type dest_c, enum gs_blend_type src_a, enum gs_blend_type dest_a)
+
+   Sets the blend function for RGB and alpha separately
+
+   :param src_c:  Blend type for the source RGB
+   :param dest_c: Blend type for the destination RGB
+   :param src_a:  Blend type for the source alpha
+   :param dest_a: Blend type for the destination alpha
+
+---------------------
+
+.. function:: void gs_depth_function(enum gs_depth_test test)
+
+   Sets the depth function
+
+   :param test: Sets the depth test type
+
+---------------------
+
+.. function:: void gs_stencil_function(enum gs_stencil_side side, enum gs_depth_test test)
+
+   Sets the stencil function
+
+   :param side: Stencil side
+   :param test: Depth test
+
+---------------------
+
+.. function:: void gs_stencil_op(enum gs_stencil_side side, enum gs_stencil_op_type fail, enum gs_stencil_op_type zfail, enum gs_stencil_op_type zpass)
+
+   Sets the stencil operation
+
+   :param side:  Stencil side
+   :param fail:  Operation to perform on stencil test failure
+   :param zfail: Operation to perform on depth test failure
+   :param zpass: Operation to perform on depth test success
+
+---------------------
+
+.. function:: void gs_set_viewport(int x, int y, int width, int height)
+
+   Sets the current viewport
+
+   :param x:      X position relative to upper left
+   :param y:      Y position relative to upper left
+   :param width:  Width of the viewport
+   :param height: Height of the viewport
+
+---------------------
+
+.. function:: void gs_get_viewport(struct gs_rect *rect)
+
+   Gets the current viewport
+
+   :param rect: Pointer to recieve viewport rectangle
+
+---------------------
+
+.. function:: void gs_set_scissor_rect(const struct gs_rect *rect)
+
+   Sets or clears the current scissor rectangle
+
+   :rect: Scissor rectangle, or *NULL* to clear
+
+---------------------
+
+.. function:: void gs_ortho(float left, float right, float top, float bottom, float znear, float zfar)
+
+   Sets the projection matrix to an orthographic matrix
+
+---------------------
+
+.. function:: void gs_frustum(float left, float right, float top, float bottom, float znear, float zfar)
+
+   Sets the projection matrix to a frustum matrix
+
+---------------------
+
+.. function:: void gs_projection_push(void)
+
+   Pushes/stores the current projection matrix
+
+---------------------
+
+.. function:: void gs_projection_pop(void)
+
+   Pops/restores the last projection matrix pushed
+
+---------------------
+
+
+Texture Functions
+-----------------
+
+.. function:: gs_texture_t *gs_texture_create(uint32_t width, uint32_t height, enum gs_color_format color_format, uint32_t levels, const uint8_t **data, uint32_t flags)
+
+   Creates a texture.
+
+   :param width:        Width
+   :param height:       Height
+   :param color_format: Color format
+   :param levels:       Number of total texture levels.  Set to 1 if no
+                        mip-mapping
+   :param data:         Pointer to array of texture data pointers
+   :param flags:        Can be 0 or a bitwise-OR combination of one or
+                        more of the following value:
+                        
+                        - GS_BUILD_MIPMAPS - Automatically builds
+                          mipmaps (Note: not fully tested)
+                        - GS_DYNAMIC - Dynamic
+                        - GS_RENDER_TARGET - Render target
+
+   :return:             A new texture object
+
+---------------------
+
+.. function:: gs_texture_t *gs_texture_create_from_file(const char *file)
+
+   Creates a texture from a file.  Note that this isn't recommended for
+   animated gifs -- instead use the :ref:`image_file_helper`.
+
+   :param file: Image file to open
+
+---------------------
+
+.. function:: void     gs_texture_destroy(gs_texture_t *tex)
+
+   Destroys a texture
+
+   :param tex: Texture object
+
+---------------------
+
+.. function:: uint32_t gs_texture_get_width(const gs_texture_t *tex)
+
+   Gets the texture's width
+
+   :param tex: Texture object
+   :return:    The texture's width
+
+---------------------
+
+.. function:: uint32_t gs_texture_get_height(const gs_texture_t *tex)
+
+   Gets the texture's height
+
+   :param tex: Texture object
+   :return:    The texture's height
+
+---------------------
+
+.. function:: enum gs_color_format gs_texture_get_color_format(const gs_texture_t *tex)
+
+   Gets the texture's color format
+
+   :param tex: Texture object
+   :return:    The texture's color format
+
+---------------------
+
+.. function:: bool     gs_texture_map(gs_texture_t *tex, uint8_t **ptr, uint32_t *linesize)
+
+   Maps a texture.
+
+   :param tex:      Texture object
+   :param ptr:      Pointer to receive the pointer to the texture data
+                    to write to
+   :param linesize: Pointer to receive the line size (pitch) of the
+                    texture
+
+---------------------
+
+.. function:: void     gs_texture_unmap(gs_texture_t *tex)
+
+   Unmaps a texture.
+
+   :param tex: Texture object
+
+---------------------
+
+.. function:: void gs_texture_set_image(gs_texture_t *tex, const uint8_t *data, uint32_t linesize, bool invert)
+
+   Sets the image of a dynamic texture
+
+   :param tex:      Texture object
+   :param data:     Data to set as the image
+   :param linesize: Line size (pitch) of the data
+   :param invert:   *true* to invert vertically, *false* otherwise
+
+---------------------
+
+.. function:: gs_texture_t *gs_texture_create_from_iosurface(void *iosurf)
+
+   **Mac only:** Creates a texture from an IOSurface.
+
+   :param iosurf: IOSurface object
+
+---------------------
+
+.. function:: bool     gs_texture_rebind_iosurface(gs_texture_t *texture, void *iosurf)
+
+   **Mac only:** Rebinds a texture to another IOSurface
+
+   :param texture: Texture object
+   :param iosuf:   IOSurface object
+
+---------------------
+
+.. function:: gs_texture_t *gs_texture_create_gdi(uint32_t width, uint32_t height)
+
+   **Windows only:** Creates a GDI-interop texture
+
+   :param width:  Width
+   :param height: Height
+
+---------------------
+
+.. function:: void *gs_texture_get_dc(gs_texture_t *gdi_tex)
+
+   **Windows only:** Gets the HDC of a GDI-interop texture.  Call
+   :c:func:`gs_texture_release_dc()` to release the HDC.
+
+   :param gdi_tex: GDI-interop texture object
+   :return:        HDC object
+
+---------------------
+
+.. function:: void gs_texture_release_dc(gs_texture_t *gdi_tex)
+
+   **Windows only:** Releases the HDC of the GDI-interop texture.
+
+   :param gdi_tex: GDI-interop texture object
+
+---------------------
+
+.. function:: gs_texture_t *gs_texture_open_shared(uint32_t handle)
+
+   **Windows only:** Creates a texture from a shared texture handle.
+
+   :param handle: Shared texture handle
+   :return:       A texture object
+
+---------------------
+
+.. function:: bool gs_gdi_texture_available(void)
+
+   **Windows only:** Returns whether GDI-interop textures are available.
+
+   :return: *true* if available, *false* otherwise
+
+---------------------
+
+.. function:: bool gs_shared_texture_available(void)
+
+   **Windows only:** Returns whether shared textures are available.
+
+   :return: *true* if available, *false* otherwise
+
+---------------------
+
+
+Cube Texture Functions
+----------------------
+
+.. function:: gs_texture_t *gs_cubetexture_create(uint32_t size, enum gs_color_format color_format, uint32_t levels, const uint8_t **data, uint32_t flags)
+
+   Creates a cubemap texture.
+
+   :param size:         Width/height/depth value
+   :param color_format: Color format
+   :param levels:       Number of texture levels
+   :param data:         Pointer to array of texture data pointers
+   :param flags:        Can be 0 or a bitwise-OR combination of one or
+                        more of the following value:
+                        
+                        - GS_BUILD_MIPMAPS - Automatically builds
+                          mipmaps (Note: not fully tested)
+                        - GS_DYNAMIC - Dynamic
+                        - GS_RENDER_TARGET - Render target
+
+   :return:             A new cube texture object
+
+---------------------
+
+.. function:: void     gs_cubetexture_destroy(gs_texture_t *cubetex)
+
+   Destroys a cube texture.
+
+   :param cubetex: Cube texture object
+
+---------------------
+
+.. function:: uint32_t gs_cubetexture_get_size(const gs_texture_t *cubetex)
+
+   Get the width/height/depth value of a cube texture.
+
+   :param cubetex: Cube texture object
+   :return:        The width/height/depth value of the cube texture
+
+---------------------
+
+.. function:: enum gs_color_format gs_cubetexture_get_color_format(const gs_texture_t *cubetex)
+
+   Gets the color format of a cube texture.
+
+   :param cubetex: Cube texture object
+   :return:        The color format of the cube texture
+
+---------------------
+
+.. function:: void gs_cubetexture_set_image(gs_texture_t *cubetex, uint32_t side, const void *data, uint32_t linesize, bool invert)
+
+   Sets an image of a cube texture side.
+
+   :param cubetex:  Cube texture object
+   :param side:     Side
+   :param data:     Texture data to set
+   :param linesize: Line size (pitch) of the texture data
+   :param invert:   *true* to invert texture data, *false* otherwise
+
+---------------------
+
+
+Staging Surface Functions
+-------------------------
+
+Staging surfaces are used to efficiently copy textures from VRAM to RAM.
+
+.. function:: gs_stagesurf_t *gs_stagesurface_create(uint32_t width, uint32_t height, enum gs_color_format color_format)
+
+   Creates a staging surface.
+
+   :param width:        Width
+   :param height:       Height
+   :param color_format: Color format
+   :return:             The staging surface object
+
+---------------------
+
+.. function:: void     gs_stagesurface_destroy(gs_stagesurf_t *stagesurf)
+
+   Destroys a staging surface.
+
+   :param stagesurf: Staging surface object
+
+---------------------
+
+.. function:: uint32_t gs_stagesurface_get_width(const gs_stagesurf_t *stagesurf)
+              uint32_t gs_stagesurface_get_height(const gs_stagesurf_t *stagesurf)
+
+   Gets the width/height of a staging surface object.
+
+   :param stagesurf: Staging surface object
+   :return:          Width/height of the staging surface
+
+---------------------
+
+.. function:: enum gs_color_format gs_stagesurface_get_color_format(const gs_stagesurf_t *stagesurf)
+
+   Gets the color format of a staging surface object.
+
+   :param stagesurf: Staging surface object
+   :return:          Color format of the staging surface
+
+---------------------
+
+.. function:: bool     gs_stagesurface_map(gs_stagesurf_t *stagesurf, uint8_t **data, uint32_t *linesize)
+
+   Maps the staging surface texture (for reading).  Call
+   :c:func:`gs_stagesurface_unmap()` to unmap when complete.
+
+   :param stagesurf: Staging surface object
+   :param data:      Pointer to receive texture data pointer
+   :param linesize:  Pointer to receive line size (pitch) of the texture
+                     data
+   :return:          *true* if map successful, *false* otherwise
+
+---------------------
+
+.. function:: void     gs_stagesurface_unmap(gs_stagesurf_t *stagesurf)
+
+   Unmaps a staging surface.
+
+   :param stagesurf: Staging surface object
+
+---------------------
+
+
+Z-Stencil Functions
+-------------------
+
+.. function:: gs_zstencil_t *gs_zstencil_create(uint32_t width, uint32_t height, enum gs_zstencil_format format)
+
+   Creates a Z-stencil surface object.
+
+   :param width:  Width
+   :param height: Height
+   :param format: Format
+   :return:       New Z-stencil surface object, or *NULL* if failed
+
+---------------------
+
+.. function:: void     gs_zstencil_destroy(gs_zstencil_t *zstencil)
+
+   Destroys a Z-stencil buffer.
+
+   :param zstencil: Z-stencil surface object
+
+---------------------
+
+
+Sampler State Functions
+-----------------------
+
+.. function:: gs_samplerstate_t *gs_samplerstate_create(const struct gs_sampler_info *info)
+
+   Creates a sampler state object.
+
+   :param info: Sampler state information
+   :return:     New sampler state object
+
+---------------------
+
+.. function:: void     gs_samplerstate_destroy(gs_samplerstate_t *samplerstate)
+
+   Destroys a sampler state object.
+
+   :param samplerstate: Sampler state object
+
+---------------------
+
+
+Vertex Buffer Functions
+-----------------------
+
+.. function:: gs_vertbuffer_t *gs_vertexbuffer_create(struct gs_vb_data *data, uint32_t flags)
+
+   Creates a vertex buffer.
+
+   :param data:  Vertex buffer data to create vertex buffer with.
+                 Buffers in this structure should be allocated with
+                 :c:func:`bmalloc()`, :c:func:`bzalloc()`, or
+                 :c:func:`brealloc()`.  Their ownership is passed to the
+                 function, and they should not be destroyed by the
+                 caller once passed
+
+   :param flags: Creation flags.  Can be 0 or a bitwise-OR combination
+                 of any of the following values:
+
+                 - GS_DYNAMIC - Can be dynamically updated in real time.
+                 - GS_DUP_BUFFER - Do not pass buffer ownership
+
+   :return:      A new vertex buffer object, or *NULL* if failed
+
+---------------------
+
+.. function:: void     gs_vertexbuffer_destroy(gs_vertbuffer_t *vertbuffer)
+
+   Destroys a vertex buffer object.
+
+   :param vertbuffer: Vertex buffer object
+
+---------------------
+
+.. function:: void     gs_vertexbuffer_flush(gs_vertbuffer_t *vertbuffer)
+
+   Flushes a vertex buffer to its interval vertex data object.  To
+   modify its internal vertex data, call
+   :c:func:`gs_vertexbuffer_get_data()`.
+
+   Can only be used with dynamic vertex buffer objects.
+
+   :param vertbuffer: Vertex buffer object
+
+---------------------
+
+.. function:: void     gs_vertexbuffer_flush_direct(gs_vertbuffer_t *vertbuffer, const struct gs_vb_data *data)
+
+   Directly flushes a vertex buffer to the specified vertex buffer data.
+   .
+
+   Can only be used with dynamic vertex buffer objects.
+
+   :param vertbuffer: Vertex buffer object
+   :param data:       Vertex buffer data to flush.  Components that
+                      don't need to be flushed can be left *NULL*
+
+---------------------
+
+.. function:: struct gs_vb_data *gs_vertexbuffer_get_data(const gs_vertbuffer_t *vertbuffer)
+
+   Gets the vertex buffer data associated with a vertex buffer object.
+   This data can be changed and vertex buffer can be updated with
+   :c:func:`gs_vertexbuffer_flush()`.
+
+   Can only be used with dynamic vertex buffer objects.
+
+   :param vertbuffer: Vertex buffer object
+   :return:           Vertex buffer data structure
+
+---------------------
+
+
+Index Buffer Functions
+----------------------
+
+.. function:: gs_indexbuffer_t *gs_indexbuffer_create(enum gs_index_type type, void *indices, size_t num, uint32_t flags)
+
+   Creates an index buffer.
+
+   :param type:    Index buffer type
+   :param indices: Index buffer data.  This buffer must be allocated
+                   with :c:func:`bmalloc()`, :c:func:`bzalloc()`, or
+                   :c:func:`bralloc()`, and ownership of this buffer is
+                   passed to the index buffer object.
+   :param num:     Number of indices in the buffer
+
+   :param flags:   Creation flags.  Can be 0 or a bitwise-OR combination
+                   of any of the following values:
+
+                   - GS_DYNAMIC - Can be dynamically updated in real time.
+                   - GS_DUP_BUFFER - Do not pass buffer ownership
+
+   :return:        A new index buffer object, or *NULL* if failed
+
+---------------------
+
+.. function:: void     gs_indexbuffer_destroy(gs_indexbuffer_t *indexbuffer)
+
+   Destroys an index buffer object.
+
+   :param indexbuffer: Index buffer object
+
+---------------------
+
+.. function:: void     gs_indexbuffer_flush(gs_indexbuffer_t *indexbuffer)
+
+   Flushes a index buffer to its interval index data object.  To modify
+   its internal index data, call :c:func:`gs_indexbuffer_get_data()`.
+
+   Can only be used with dynamic index buffer objects.
+
+   :param indexbuffer: Index buffer object
+
+---------------------
+
+.. function:: void     gs_indexbuffer_flush_direct(gs_indexbuffer_t *indexbuffer, const void *data)
+
+   Flushes a index buffer to the specified index buffer data.
+
+   Can only be used with dynamic index buffer objects.
+
+   :param indexbuffer: Index buffer object
+   :param data:        Index buffer data to flush
+
+---------------------
+
+.. function:: void     *gs_indexbuffer_get_data(const gs_indexbuffer_t *indexbuffer)
+
+   Gets the index buffer data associated with a index buffer object.
+   This data can be changed and index buffer can be updated with
+   :c:func:`gs_indexbuffer_flush()`.
+
+   Can only be used with dynamic index buffer objects.
+
+   :param vertbuffer: Index buffer object
+   :return:           Index buffer data pointer
+
+---------------------
+
+.. function:: size_t   gs_indexbuffer_get_num_indices(const gs_indexbuffer_t *indexbuffer)
+
+   Gets the number of indices associated with this index buffer.
+
+   :param indexbuffer: Index buffer object
+   :return:            Number of indices the vertex buffer object has
+
+---------------------
+
+.. function:: enum gs_index_type gs_indexbuffer_get_type(const gs_indexbuffer_t *indexbuffer)
+
+   Gets the type of index buffer.
+
+   :param indexbuffer: Index buffer object
+   :return:            Index buffer type
+
+---------------------
+
+
+Display Duplicator (Windows Only)
+---------------------------------
+
+.. function:: gs_duplicator_t *gs_duplicator_create(int monitor_idx)
+
+---------------------
+
+.. function:: void gs_duplicator_destroy(gs_duplicator_t *duplicator)
+
+---------------------
+
+.. function:: bool gs_duplicator_update_frame(gs_duplicator_t *duplicator)
+
+---------------------
+
+.. function:: gs_texture_t *gs_duplicator_get_texture(gs_duplicator_t *duplicator)
+
+---------------------
+
+.. function:: bool gs_get_duplicator_monitor_info(int monitor_idx, struct gs_monitor_info *monitor_info)
+
+---------------------
+
+
+Render Helper Functions
+-----------------------
+
+.. function:: void gs_render_start(bool b_new)
+
+---------------------
+
+.. function:: void gs_render_stop(enum gs_draw_mode mode)
+
+---------------------
+
+.. function:: gs_vertbuffer_t *gs_render_save(void)
+
+---------------------
+
+.. function:: void gs_vertex2f(float x, float y)
+
+---------------------
+
+.. function:: void gs_vertex3f(float x, float y, float z)
+
+---------------------
+
+.. function:: void gs_normal3f(float x, float y, float z)
+
+---------------------
+
+.. function:: void gs_color(uint32_t color)
+
+---------------------
+
+.. function:: void gs_texcoord(float x, float y, int unit)
+
+---------------------
+
+.. function:: void gs_vertex2v(const struct vec2 *v)
+
+---------------------
+
+.. function:: void gs_vertex3v(const struct vec3 *v)
+
+---------------------
+
+.. function:: void gs_normal3v(const struct vec3 *v)
+
+---------------------
+
+.. function:: void gs_color4v(const struct vec4 *v)
+
+---------------------
+
+.. function:: void gs_texcoord2v(const struct vec2 *v, int unit)
+
+---------------------
+
+
+Graphics Types
+--------------
+
+.. type:: typedef struct gs_duplicator       gs_duplicator_t
+.. type:: typedef struct gs_texture          gs_texture_t
+.. type:: typedef struct gs_stage_surface    gs_stagesurf_t
+.. type:: typedef struct gs_zstencil_buffer  gs_zstencil_t
+.. type:: typedef struct gs_vertex_buffer    gs_vertbuffer_t
+.. type:: typedef struct gs_index_buffer     gs_indexbuffer_t
+.. type:: typedef struct gs_sampler_state    gs_samplerstate_t
+.. type:: typedef struct gs_swap_chain       gs_swapchain_t
+.. type:: typedef struct gs_texture_render   gs_texrender_t
+.. type:: typedef struct gs_shader           gs_shader_t
+.. type:: typedef struct gs_shader_param     gs_sparam_t
+.. type:: typedef struct gs_device           gs_device_t
+.. type:: typedef struct graphics_subsystem  graphics_t

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

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

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

@@ -0,0 +1,39 @@
+Extra Math Functions/Macros
+===========================
+
+.. code:: 
+
+   #include <graphics/math-extra.h>
+
+Helper functions/macros for graphics math.
+
+.. function:: RAD(val)
+
+   Macro that converts a floating point degrees value to radians.
+
+.. function:: DEG(val)
+
+   Macro that converts a floating point radians value to degrees.
+
+**LARGE_EPSILON**   1e-2f
+
+   Large epsilon value.
+
+**EPSILON**         1e-4f
+
+   Epsilon value.
+
+**TINY_EPSILON**    1e-5f
+
+   Tiny Epsilon value.
+
+**M_INFINITE**      3.4e38f
+
+   Infinite value
+
+---------------------
+
+.. function:: float rand_float(int positive_only)
+
+   Generates a random floating point value (from -1.0f..1.0f, or
+   0.0f..1.0f if *positive_only* is set).

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

@@ -0,0 +1,151 @@
+Matrix
+======
+
+.. code:: cpp
+
+   #include <graphics/matrix4.h>
+
+.. type:: struct matrix4
+
+   Matrix structure
+
+.. member:: struct vec4 matrix4.x
+
+   X component vector
+
+.. member:: struct vec4 matrix4.y
+
+   Y component vector
+
+.. member:: struct vec4 matrix4.z
+
+   Z component vector
+
+.. member:: struct vec4 matrix4.w
+
+   W component vector
+
+---------------------
+
+.. function:: void matrix4_copy(struct matrix4 *dst, const struct matrix4 *m)
+
+   Copies a matrix
+
+   :param dst: Destination matrix
+   :param m:   Matrix to copy
+
+---------------------
+
+.. function:: void matrix4_identity(struct matrix4 *dst)
+
+   Sets an identity matrix
+
+   :param dst: Destination matrix
+
+---------------------
+
+.. function:: void matrix4_from_quat(struct matrix4 *dst, const struct quat *q)
+
+   Converts a quaternion to a matrix
+
+   :param dst: Destination matrix
+   :param q:   Quaternion to convert
+
+---------------------
+
+.. function:: void matrix4_from_axisang(struct matrix4 *dst, const struct axisang *aa)
+
+   Converts an axis angle to a matrix
+
+   :param dst: Destination matrix
+   :param aa:  Axis angle to convert
+
+---------------------
+
+.. function:: void matrix4_mul(struct matrix4 *dst, const struct matrix4 *m1, const struct matrix4 *m2)
+
+   Multiples two matrices
+
+   :param dst: Destination matrix
+   :param m1:  Matrix 1
+   :param m2:  Matrix 2
+
+---------------------
+
+.. function:: float matrix4_determinant(const struct matrix4 *m)
+
+   Gets the determinant value of a matrix
+
+   :param m: Matrix
+   :return:  Determinant
+
+---------------------
+
+.. function:: void matrix4_translate3v(struct matrix4 *dst, const struct matrix4 *m, const struct vec3 *v)
+              void matrix4_translate3f(struct matrix4 *dst, const struct matrix4 *m, float x, float y, float z)
+
+   Translates the matrix by a 3-component vector
+
+   :param dst: Destination matrix
+   :param m:   Matrix to translate
+   :param v:   Translation vector
+
+---------------------
+
+.. function:: void matrix4_translate4v(struct matrix4 *dst, const struct matrix4 *m, const struct vec4 *v)
+
+   Translates the matrix by a 4-component vector
+
+   :param dst: Destination matrix
+   :param m:   Matrix to translate
+   :param v:   Translation vector
+
+---------------------
+
+.. function:: void matrix4_rotate(struct matrix4 *dst, const struct matrix4 *m, const struct quat *q)
+
+   Rotates a matrix by a quaternion
+
+   :param dst: Destination matrix
+   :param m:   Matrix to rotate
+   :param q:   Rotation quaternion
+
+---------------------
+
+.. function:: void matrix4_rotate_aa(struct matrix4 *dst, const struct matrix4 *m, const struct axisang *aa)
+              void matrix4_rotate_aa4f(struct matrix4 *dst, const struct matrix4 *m, float x, float y, float z, float rot)
+
+   Rotates a matrix by an axis angle
+
+   :param dst: Destination matrix
+   :param m:   Matrix to rotate
+   :param aa:  Rotation anxis angle
+
+---------------------
+
+.. function:: void matrix4_scale(struct matrix4 *dst, const struct matrix4 *m, const struct vec3 *v)
+              void matrix4_scale3f(struct matrix4 *dst, const struct matrix4 *m, float x, float y, float z)
+
+   Scales each matrix component by the components of a 3-component vector
+
+   :param dst: Destination matrix
+   :param m:   Matrix to scale
+   :param v:   Scale vector
+
+---------------------
+
+.. function:: bool matrix4_inv(struct matrix4 *dst, const struct matrix4 *m)
+
+   Inverts a matrix
+
+   :param dst: Destination matrix
+   :param m:   Matrix to invert
+
+---------------------
+
+.. function:: void matrix4_transpose(struct matrix4 *dst, const struct matrix4 *m)
+
+   Transposes a matrix
+
+   :param dst: Destination matrix
+   :param m:   Matrix to transpose

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

@@ -0,0 +1,228 @@
+Quaternion
+==========
+
+.. code:: cpp
+
+   #include <graphics/quat.h>
+
+.. type:: struct quat
+
+   Two component quaternion structure.
+
+.. member:: float quat.x
+
+   X component
+
+.. member:: float quat.y
+
+   Y component
+
+.. member:: float quat.z
+
+   Z component
+
+.. member:: float quat.w
+
+   W component
+
+.. member:: float quat.ptr[4]
+
+   Unioned array of all components
+
+---------------------
+
+.. function:: void quat_identity(struct quat *dst)
+
+   Sets a quaternion to {0.0f, 0.0f, 0.0f, 1.0f}.
+
+   :param dst: Destination
+
+---------------------
+
+.. function:: void quat_set(struct quat *dst, float x, float y)
+
+   Sets the individual components of a quaternion.
+
+   :param dst: Destination
+   :param x:   X component
+   :param y:   Y component
+   :param y:   Z component
+   :param w:   W component
+
+---------------------
+
+.. function:: void quat_copy(struct quat *dst, const struct quat *v)
+
+   Copies a quaternion
+
+   :param dst: Destination
+   :param v:   Quaternion to copy
+
+---------------------
+
+.. function:: void quat_add(struct quat *dst, const struct quat *v1, const struct quat *v2)
+
+   Adds two quaternions
+
+   :param dst: Destination
+   :param v1:  Quaternion 1
+   :param v2:  Quaternion 2
+
+---------------------
+
+.. function:: void quat_sub(struct quat *dst, const struct quat *v1, const struct quat *v2)
+
+   Subtracts two quaternions
+
+   :param dst: Destination
+   :param v1:  Quaternion being subtracted from
+   :param v2:  Quaternion being subtracted
+
+---------------------
+
+.. function:: void quat_mul(struct quat *dst, const struct quat *v1, const struct quat *v2)
+
+   Multiplies two quaternions
+
+   :param dst: Destination
+   :param v1:  Quaternion 1
+   :param v2:  Quaternion 2
+
+---------------------
+
+.. function:: void quat_addf(struct quat *dst, const struct quat *v, float f)
+
+   Adds a floating point to all components
+
+   :param dst: Destination
+   :param dst: Quaternion
+   :param f:   Floating point
+
+---------------------
+
+.. function:: void quat_subf(struct quat *dst, const struct quat *v, float f)
+
+   Subtracts a floating point from all components
+
+   :param dst: Destination
+   :param v:   Quaternion being subtracted from
+   :param f:   Floating point being subtracted
+   
+---------------------
+
+.. function:: void quat_mulf(struct quat *dst, const struct quat *v, float f)
+
+   Multiplies a floating point with all components
+
+   :param dst: Destination
+   :param dst: Quaternion
+   :param f:   Floating point
+
+---------------------
+
+.. function:: void quat_inv(struct quat *dst, const struct quat *v)
+
+   Inverts a quaternion
+
+   :param dst: Destination
+   :param v:   Quaternion to invert
+
+---------------------
+
+.. function:: float quat_dot(const struct quat *v1, const struct quat *v2)
+
+   Performs a dot product between two quaternions
+
+   :param v1: Quaternion 1
+   :param v2: Quaternion 2
+   :return:   Result of the dot product
+
+---------------------
+
+.. function:: float quat_len(const struct quat *v)
+
+   Gets the length of a quaternion
+
+   :param v: Quaternion
+   :return:  The quaternion's length
+
+---------------------
+
+.. function:: float quat_dist(const struct quat *v1, const struct quat *v2)
+
+   Gets the distance between two quaternions
+
+   :param v1: Quaternion 1
+   :param v2: Quaternion 2
+   :return:   Distance between the two quaternions
+
+---------------------
+
+.. function:: void quat_from_axisang(struct quat *dst, const struct axisang *aa)
+
+   Converts an axis angle to a quaternion
+
+   :param dst: Destination quaternion
+   :param aa:  Axis angle
+
+---------------------
+
+.. function:: void quat_from_matrix4(struct quat *dst, const struct matrix4 *m)
+
+   Converts the rotational properties of a matrix to a quaternion
+
+   :param dst: Destination quaternion
+   :param m:   Matrix to convert
+
+---------------------
+
+.. function:: void quat_get_dir(struct vec3 *dst, const struct quat *q)
+
+   Converts a quaternion to a directional vector
+
+   :param dst: Destination 3-component vector
+   :param q:   Quaternion
+
+---------------------
+
+.. function:: void quat_set_look_dir(struct quat *dst, const struct vec3 *dir)
+
+   Creates a quaternion from a specific "look" direction
+
+   :param dst: Destination quaternion
+   :param dir: 3-component vector representing the look direction
+
+---------------------
+
+.. function:: void quat_interpolate(struct quat *dst, const struct quat *q1, const struct quat *q2, float t)
+
+   Linearly interpolates two quaternions
+
+   :param dst: Destination quaternion
+   :param q1:  Quaternion 1
+   :param q2:  Quaternion 2
+   :param t:   Time value (0.0f..1.0f)
+
+---------------------
+
+.. function:: void quat_get_tangent(struct quat *dst, const struct quat *prev, const struct quat *q, const struct quat *next)
+
+   Gets a tangent value for the center of three rotational values
+
+   :param dst:  Destination quaternion
+   :param prev: Previous rotation
+   :param q:    Rotation to get tangent for
+   :param next: Next rotation
+
+---------------------
+
+.. function:: void quat_interpolate_cubic(struct quat *dst, const struct quat *q1, const struct quat *q2, const struct quat *m1, const struct quat *m2, float t)
+
+   Performs cubic interpolation between two quaternions
+
+   :param dst: Destination quaternion
+   :param q1:  Quaternion 1
+   :param q2:  Quaternion 2
+   :param m1:  Tangent 1
+   :param m2:  Tangent 2
+   :param t:   Time value (0.0f..1.0f)

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

@@ -0,0 +1,253 @@
+2-Component Vector
+==================
+
+.. code:: cpp
+
+   #include <graphics/vec2.h>
+
+.. type:: struct vec2
+
+   Two component vector structure.
+
+.. member:: float vec2.x
+
+   X component
+
+.. member:: float vec2.y
+
+   Y component
+
+.. member:: float vec2.ptr[2]
+
+   Unioned array of both components
+
+---------------------
+
+.. function:: void vec2_zero(struct vec2 *dst)
+
+   Zeroes a vector
+
+   :param dst: Destination
+
+---------------------
+
+.. function:: void vec2_set(struct vec2 *dst, float x, float y)
+
+   Sets the individual components of a 2-component vector.
+
+   :param dst: Destination
+   :param x:   X component
+   :param y:   Y component
+
+---------------------
+
+.. function:: void vec2_copy(struct vec2 *dst, const struct vec2 *v)
+
+   Copies a vector
+
+   :param dst: Destination
+   :param v:   Vector to copy
+
+---------------------
+
+.. function:: void vec2_add(struct vec2 *dst, const struct vec2 *v1, const struct vec2 *v2)
+
+   Adds two vectors
+
+   :param dst: Destination
+   :param v1:  Vector 1
+   :param v2:  Vector 2
+
+---------------------
+
+.. function:: void vec2_sub(struct vec2 *dst, const struct vec2 *v1, const struct vec2 *v2)
+
+   Subtracts two vectors
+
+   :param dst: Destination
+   :param v1:  Vector being subtracted from
+   :param v2:  Vector being subtracted
+
+---------------------
+
+.. function:: void vec2_mul(struct vec2 *dst, const struct vec2 *v1, const struct vec2 *v2)
+
+   Multiplies two vectors
+
+   :param dst: Destination
+   :param v1:  Vector 1
+   :param v2:  Vector 2
+
+---------------------
+
+.. function:: void vec2_div(struct vec2 *dst, const struct vec2 *v1, const struct vec2 *v2)
+
+   Divides two vectors
+
+   :param dst: Destination
+   :param v1:  Dividend
+   :param v2:  Divisor
+
+---------------------
+
+.. function:: void vec2_addf(struct vec2 *dst, const struct vec2 *v, float f)
+
+   Adds a floating point to all components
+
+   :param dst: Destination
+   :param dst: Vector
+   :param f:   Floating point
+
+---------------------
+
+.. function:: void vec2_subf(struct vec2 *dst, const struct vec2 *v, float f)
+
+   Subtracts a floating point from all components
+
+   :param dst: Destination
+   :param v:   Vector being subtracted from
+   :param f:   Floating point being subtracted
+   
+---------------------
+
+.. function:: void vec2_mulf(struct vec2 *dst, const struct vec2 *v, float f)
+
+   Multiplies a floating point with all components
+
+   :param dst: Destination
+   :param dst: Vector
+   :param f:   Floating point
+
+---------------------
+
+.. function:: void vec2_divf(struct vec2 *dst, const struct vec2 *v, float f)
+
+   Divides a floating point from all components
+
+   :param dst: Destination
+   :param v:   Vector (dividend)
+   :param f:   Floating point (divisor)
+
+---------------------
+
+.. function:: void vec2_neg(struct vec2 *dst, const struct vec2 *v)
+
+   Negates a vector
+
+   :param dst: Destination
+   :param v:   Vector to negate
+
+---------------------
+
+.. function:: float vec2_dot(const struct vec2 *v1, const struct vec2 *v2)
+
+   Performs a dot product between two vectors
+
+   :param v1: Vector 1
+   :param v2: Vector 2
+   :return:   Result of the dot product
+
+---------------------
+
+.. function:: float vec2_len(const struct vec2 *v)
+
+   Gets the length of a vector
+
+   :param v: Vector
+   :return:  The vector's length
+
+---------------------
+
+.. function:: float vec2_dist(const struct vec2 *v1, const struct vec2 *v2)
+
+   Gets the distance between two vectors
+
+   :param v1: Vector 1
+   :param v2: Vector 2
+   :return:   Distance between the two vectors
+
+---------------------
+
+.. function:: void vec2_minf(struct vec2 *dst, const struct vec2 *v, float val)
+
+   Gets the minimum values between a vector's components and a floating point
+
+   :param dst: Destination
+   :param v:   Vector
+   :param val: Floating point
+
+---------------------
+
+.. function:: void vec2_min(struct vec2 *dst, const struct vec2 *v, const struct vec2 *min_v)
+
+   Gets the minimum values between two vectors
+
+   :param dst:   Destination
+   :param v:     Vector 1
+   :param min_v: Vector 2
+
+---------------------
+
+.. function:: void vec2_maxf(struct vec2 *dst, const struct vec2 *v, float val)
+
+   Gets the maximum values between a vector's components and a floating point
+
+   :param dst: Destination
+   :param v:   Vector
+   :param val: Floating point
+
+---------------------
+
+.. function:: void vec2_max(struct vec2 *dst, const struct vec2 *v, const struct vec2 *max_v)
+
+   Gets the maximum values between two vectors
+
+   :param dst:   Destination
+   :param v:     Vector 1
+   :param max_v: Vector 2
+
+---------------------
+
+.. function:: void vec2_abs(struct vec2 *dst, const struct vec2 *v)
+
+   Gets the absolute values of each component
+
+   :param dst: Destination
+   :param v:   Vector
+
+---------------------
+
+.. function:: void vec2_floor(struct vec2 *dst, const struct vec2 *v)
+
+   Gets the floor values of each component
+
+   :param dst: Destination
+   :param v:   Vector
+
+---------------------
+
+.. function:: void vec2_ceil(struct vec2 *dst, const struct vec2 *v)
+
+   Gets the ceiling values of each component
+
+   :param dst: Destination
+   :param v:   Vector
+
+---------------------
+
+.. function:: int vec2_close(const struct vec2 *v1, const struct vec2 *v2, float epsilon)
+
+   Compares two vectors
+
+   :param v1:      Vector 1
+   :param v2:      Vector 2
+   :param epsilon: Maximum precision for comparison
+
+---------------------
+
+.. function:: void vec2_norm(struct vec2 *dst, const struct vec2 *v)
+
+   Normalizes a vector
+
+   :param dst: Desination
+   :param v:   Vector to normalize

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

@@ -0,0 +1,306 @@
+3-Component Vector
+==================
+
+.. code:: cpp
+
+   #include <graphics/vec3.h>
+
+.. type:: struct vec3
+
+   Two component vector structure.
+
+.. member:: float vec3.x
+
+   X component
+
+.. member:: float vec3.y
+
+   Y component
+
+.. member:: float vec3.z
+
+   Z component
+
+.. member:: float vec3.ptr[3]
+
+   Unioned array of all components
+
+---------------------
+
+.. function:: void vec3_zero(struct vec3 *dst)
+
+   Zeroes a vector
+
+   :param dst: Destination
+
+---------------------
+
+.. function:: void vec3_set(struct vec3 *dst, float x, float y)
+
+   Sets the individual components of a 3-component vector.
+
+   :param dst: Destination
+   :param x:   X component
+   :param y:   Y component
+   :param y:   Z component
+
+---------------------
+
+.. function:: void vec3_copy(struct vec3 *dst, const struct vec3 *v)
+
+   Copies a vector
+
+   :param dst: Destination
+   :param v:   Vector to copy
+
+---------------------
+
+.. function:: void vec3_from_vec4(struct vec3 *dst, const struct vec4 *v)
+
+   Creates a 3-component vector from a 4-component vector
+
+   :param dst: 3-component vector destination
+   :param v:   4-component vector
+
+---------------------
+
+.. function:: void vec3_add(struct vec3 *dst, const struct vec3 *v1, const struct vec3 *v2)
+
+   Adds two vectors
+
+   :param dst: Destination
+   :param v1:  Vector 1
+   :param v2:  Vector 2
+
+---------------------
+
+.. function:: void vec3_sub(struct vec3 *dst, const struct vec3 *v1, const struct vec3 *v2)
+
+   Subtracts two vectors
+
+   :param dst: Destination
+   :param v1:  Vector being subtracted from
+   :param v2:  Vector being subtracted
+
+---------------------
+
+.. function:: void vec3_mul(struct vec3 *dst, const struct vec3 *v1, const struct vec3 *v2)
+
+   Multiplies two vectors
+
+   :param dst: Destination
+   :param v1:  Vector 1
+   :param v2:  Vector 2
+
+---------------------
+
+.. function:: void vec3_div(struct vec3 *dst, const struct vec3 *v1, const struct vec3 *v2)
+
+   Divides two vectors
+
+   :param dst: Destination
+   :param v1:  Dividend
+   :param v2:  Divisor
+
+---------------------
+
+.. function:: void vec3_addf(struct vec3 *dst, const struct vec3 *v, float f)
+
+   Adds a floating point to all components
+
+   :param dst: Destination
+   :param dst: Vector
+   :param f:   Floating point
+
+---------------------
+
+.. function:: void vec3_subf(struct vec3 *dst, const struct vec3 *v, float f)
+
+   Subtracts a floating point from all components
+
+   :param dst: Destination
+   :param v:   Vector being subtracted from
+   :param f:   Floating point being subtracted
+   
+---------------------
+
+.. function:: void vec3_mulf(struct vec3 *dst, const struct vec3 *v, float f)
+
+   Multiplies a floating point with all components
+
+   :param dst: Destination
+   :param dst: Vector
+   :param f:   Floating point
+
+---------------------
+
+.. function:: void vec3_divf(struct vec3 *dst, const struct vec3 *v, float f)
+
+   Divides a floating point from all components
+
+   :param dst: Destination
+   :param v:   Vector (dividend)
+   :param f:   Floating point (divisor)
+
+---------------------
+
+.. function:: void vec3_neg(struct vec3 *dst, const struct vec3 *v)
+
+   Negates a vector
+
+   :param dst: Destination
+   :param v:   Vector to negate
+
+---------------------
+
+.. function:: float vec3_dot(const struct vec3 *v1, const struct vec3 *v2)
+
+   Performs a dot product between two vectors
+
+   :param v1: Vector 1
+   :param v2: Vector 2
+   :return:   Result of the dot product
+
+---------------------
+
+.. function:: void vec3_cross(struct vec3 *dst, const struct vec3 *v1, const struct vec3 *v2)
+
+   Performs a cross product between two vectors
+
+   :param dst: Destination
+   :param v1:  Vector 1
+   :param v2:  Vector 2
+
+---------------------
+
+.. function:: float vec3_len(const struct vec3 *v)
+
+   Gets the length of a vector
+
+   :param v: Vector
+   :return:  The vector's length
+
+---------------------
+
+.. function:: float vec3_dist(const struct vec3 *v1, const struct vec3 *v2)
+
+   Gets the distance between two vectors
+
+   :param v1: Vector 1
+   :param v2: Vector 2
+   :return:   Distance between the two vectors
+
+---------------------
+
+.. function:: void vec3_minf(struct vec3 *dst, const struct vec3 *v, float val)
+
+   Gets the minimum values between a vector's components and a floating point
+
+   :param dst: Destination
+   :param v:   Vector
+   :param val: Floating point
+
+---------------------
+
+.. function:: void vec3_min(struct vec3 *dst, const struct vec3 *v, const struct vec3 *min_v)
+
+   Gets the minimum values between two vectors
+
+   :param dst:   Destination
+   :param v:     Vector 1
+   :param min_v: Vector 2
+
+---------------------
+
+.. function:: void vec3_maxf(struct vec3 *dst, const struct vec3 *v, float val)
+
+   Gets the maximum values between a vector's components and a floating point
+
+   :param dst: Destination
+   :param v:   Vector
+   :param val: Floating point
+
+---------------------
+
+.. function:: void vec3_max(struct vec3 *dst, const struct vec3 *v, const struct vec3 *max_v)
+
+   Gets the maximum values between two vectors
+
+   :param dst:   Destination
+   :param v:     Vector 1
+   :param max_v: Vector 2
+
+---------------------
+
+.. function:: void vec3_abs(struct vec3 *dst, const struct vec3 *v)
+
+   Gets the absolute values of each component
+
+   :param dst: Destination
+   :param v:   Vector
+
+---------------------
+
+.. function:: void vec3_floor(struct vec3 *dst, const struct vec3 *v)
+
+   Gets the floor values of each component
+
+   :param dst: Destination
+   :param v:   Vector
+
+---------------------
+
+.. function:: void vec3_ceil(struct vec3 *dst, const struct vec3 *v)
+
+   Gets the ceiling values of each component
+
+   :param dst: Destination
+   :param v:   Vector
+
+---------------------
+
+.. function:: int vec3_close(const struct vec3 *v1, const struct vec3 *v2, float epsilon)
+
+   Compares two vectors
+
+   :param v1:      Vector 1
+   :param v2:      Vector 2
+   :param epsilon: Maximum precision for comparison
+
+---------------------
+
+.. function:: void vec3_norm(struct vec3 *dst, const struct vec3 *v)
+
+   Normalizes a vector
+
+   :param dst: Desination
+   :param v:   Vector to normalize
+
+---------------------
+
+.. function:: void vec3_transform(struct vec3 *dst, const struct vec3 *v, const struct matrix4 *m)
+
+   Transforms a vector
+
+   :param dst: Destination
+   :param v:   Vector
+   :param m:   Matrix
+
+---------------------
+
+.. function:: void vec3_rotate(struct vec3 *dst, const struct vec3 *v, const struct matrix3 *m)
+
+   Rotates a vector
+
+   :param dst: Destination
+   :param v:   Vector
+   :param m:   Matrix
+
+---------------------
+
+.. function:: void vec3_rand(struct vec3 *dst, int positive_only)
+
+   Generates a random vector
+
+   :param dst:           Destination
+   :param positive_only: *true* if positive only, *false* otherwise

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

@@ -0,0 +1,282 @@
+4-Component Vector
+==================
+
+.. code:: cpp
+
+   #include <graphics/vec4.h>
+
+.. type:: struct vec4
+
+   Two component vector structure.
+
+.. member:: float vec4.x
+
+   X component
+
+.. member:: float vec4.y
+
+   Y component
+
+.. member:: float vec4.z
+
+   Z component
+
+.. member:: float vec4.w
+
+   W component
+
+.. member:: float vec4.ptr[4]
+
+   Unioned array of all components
+
+---------------------
+
+.. function:: void vec4_zero(struct vec4 *dst)
+
+   Zeroes a vector
+
+   :param dst: Destination
+
+---------------------
+
+.. function:: void vec4_set(struct vec4 *dst, float x, float y)
+
+   Sets the individual components of a 4-component vector.
+
+   :param dst: Destination
+   :param x:   X component
+   :param y:   Y component
+   :param y:   Z component
+   :param w:   W component
+
+---------------------
+
+.. function:: void vec4_copy(struct vec4 *dst, const struct vec4 *v)
+
+   Copies a vector
+
+   :param dst: Destination
+   :param v:   Vector to copy
+
+---------------------
+
+.. function:: void vec4_from_vec3(struct vec4 *dst, const struct vec3 *v)
+
+   Creates a 4-component vector from a 3-component vector
+
+   :param dst: 4-component vector destination
+   :param v:   3-component vector
+
+---------------------
+
+.. function:: void vec4_add(struct vec4 *dst, const struct vec4 *v1, const struct vec4 *v2)
+
+   Adds two vectors
+
+   :param dst: Destination
+   :param v1:  Vector 1
+   :param v2:  Vector 2
+
+---------------------
+
+.. function:: void vec4_sub(struct vec4 *dst, const struct vec4 *v1, const struct vec4 *v2)
+
+   Subtracts two vectors
+
+   :param dst: Destination
+   :param v1:  Vector being subtracted from
+   :param v2:  Vector being subtracted
+
+---------------------
+
+.. function:: void vec4_mul(struct vec4 *dst, const struct vec4 *v1, const struct vec4 *v2)
+
+   Multiplies two vectors
+
+   :param dst: Destination
+   :param v1:  Vector 1
+   :param v2:  Vector 2
+
+---------------------
+
+.. function:: void vec4_div(struct vec4 *dst, const struct vec4 *v1, const struct vec4 *v2)
+
+   Divides two vectors
+
+   :param dst: Destination
+   :param v1:  Dividend
+   :param v2:  Divisor
+
+---------------------
+
+.. function:: void vec4_addf(struct vec4 *dst, const struct vec4 *v, float f)
+
+   Adds a floating point to all components
+
+   :param dst: Destination
+   :param dst: Vector
+   :param f:   Floating point
+
+---------------------
+
+.. function:: void vec4_subf(struct vec4 *dst, const struct vec4 *v, float f)
+
+   Subtracts a floating point from all components
+
+   :param dst: Destination
+   :param v:   Vector being subtracted from
+   :param f:   Floating point being subtracted
+   
+---------------------
+
+.. function:: void vec4_mulf(struct vec4 *dst, const struct vec4 *v, float f)
+
+   Multiplies a floating point with all components
+
+   :param dst: Destination
+   :param dst: Vector
+   :param f:   Floating point
+
+---------------------
+
+.. function:: void vec4_divf(struct vec4 *dst, const struct vec4 *v, float f)
+
+   Divides a floating point from all components
+
+   :param dst: Destination
+   :param v:   Vector (dividend)
+   :param f:   Floating point (divisor)
+
+---------------------
+
+.. function:: void vec4_neg(struct vec4 *dst, const struct vec4 *v)
+
+   Negates a vector
+
+   :param dst: Destination
+   :param v:   Vector to negate
+
+---------------------
+
+.. function:: float vec4_dot(const struct vec4 *v1, const struct vec4 *v2)
+
+   Performs a dot product between two vectors
+
+   :param v1: Vector 1
+   :param v2: Vector 2
+   :return:   Result of the dot product
+
+---------------------
+
+.. function:: float vec4_len(const struct vec4 *v)
+
+   Gets the length of a vector
+
+   :param v: Vector
+   :return:  The vector's length
+
+---------------------
+
+.. function:: float vec4_dist(const struct vec4 *v1, const struct vec4 *v2)
+
+   Gets the distance between two vectors
+
+   :param v1: Vector 1
+   :param v2: Vector 2
+   :return:   Distance between the two vectors
+
+---------------------
+
+.. function:: void vec4_minf(struct vec4 *dst, const struct vec4 *v, float val)
+
+   Gets the minimum values between a vector's components and a floating point
+
+   :param dst: Destination
+   :param v:   Vector
+   :param val: Floating point
+
+---------------------
+
+.. function:: void vec4_min(struct vec4 *dst, const struct vec4 *v, const struct vec4 *min_v)
+
+   Gets the minimum values between two vectors
+
+   :param dst:   Destination
+   :param v:     Vector 1
+   :param min_v: Vector 2
+
+---------------------
+
+.. function:: void vec4_maxf(struct vec4 *dst, const struct vec4 *v, float val)
+
+   Gets the maximum values between a vector's components and a floating point
+
+   :param dst: Destination
+   :param v:   Vector
+   :param val: Floating point
+
+---------------------
+
+.. function:: void vec4_max(struct vec4 *dst, const struct vec4 *v, const struct vec4 *max_v)
+
+   Gets the maximum values between two vectors
+
+   :param dst:   Destination
+   :param v:     Vector 1
+   :param max_v: Vector 2
+
+---------------------
+
+.. function:: void vec4_abs(struct vec4 *dst, const struct vec4 *v)
+
+   Gets the absolute values of each component
+
+   :param dst: Destination
+   :param v:   Vector
+
+---------------------
+
+.. function:: void vec4_floor(struct vec4 *dst, const struct vec4 *v)
+
+   Gets the floor values of each component
+
+   :param dst: Destination
+   :param v:   Vector
+
+---------------------
+
+.. function:: void vec4_ceil(struct vec4 *dst, const struct vec4 *v)
+
+   Gets the ceiling values of each component
+
+   :param dst: Destination
+   :param v:   Vector
+
+---------------------
+
+.. function:: int vec4_close(const struct vec4 *v1, const struct vec4 *v2, float epsilon)
+
+   Compares two vectors
+
+   :param v1:      Vector 1
+   :param v2:      Vector 2
+   :param epsilon: Maximum precision for comparison
+
+---------------------
+
+.. function:: void vec4_norm(struct vec4 *dst, const struct vec4 *v)
+
+   Normalizes a vector
+
+   :param dst: Desination
+   :param v:   Vector to normalize
+
+---------------------
+
+.. function:: void vec4_transform(struct vec4 *dst, const struct vec4 *v, const struct matrix4 *m)
+
+   Transforms a vector
+
+   :param dst: Destination
+   :param v:   Vector
+   :param m:   Matrix

docs/sphinx/reference-libobs-graphics.rst

@@ -0,0 +1,17 @@
+Graphics API Reference (libobs/graphics)
+========================================
+
+.. toctree::
+   :maxdepth: 2
+
+   reference-libobs-graphics-effects
+   reference-libobs-graphics-vec2
+   reference-libobs-graphics-vec3
+   reference-libobs-graphics-vec4
+   reference-libobs-graphics-quat
+   reference-libobs-graphics-matrix4
+   reference-libobs-graphics-math
+   reference-libobs-graphics-image-file
+   reference-libobs-graphics-axisang
+   reference-libobs-graphics-graphics
+

docs/sphinx/reference-libobs-media-io.rst

@@ -0,0 +1,463 @@
+Media I/O API Reference (libobs/media-io)
+=========================================
+
+.. code:: cpp
+
+   #include <obs.h>
+
+
+Video Handler
+-------------
+
+.. type:: video_t
+
+   Video output handler object
+
+---------------------
+
+.. type:: enum video_format
+
+   Video format.  Can be one of the following values:
+
+   - VIDEO_FORMAT_I420
+   - VIDEO_FORMAT_NV12
+
+   - VIDEO_FORMAT_YVYU
+   - VIDEO_FORMAT_YUY2
+   - VIDEO_FORMAT_UYVY
+
+   - VIDEO_FORMAT_RGBA
+   - VIDEO_FORMAT_BGRA
+   - VIDEO_FORMAT_BGRX
+   - VIDEO_FORMAT_Y800
+
+   - VIDEO_FORMAT_I444
+
+---------------------
+
+.. type:: enum video_colorspace
+
+   YUV color space.  Can be one of the following values:
+
+   - VIDEO_CS_DEFAULT - Equivalent to VIDEO_CS_601
+   - VIDEO_CS_601     - 601 color space
+   - VIDEO_CS_709     - 709 color space
+
+---------------------
+
+.. type:: enum video_range_type
+
+   YUV color range.
+
+   - VIDEO_RANGE_DEFAULT - Equivalent to VIDEO_RANGE_PARTIAL
+   - VIDEO_RANGE_PARTIAL - Partial range
+   - VIDEO_RANGE_FULL    - Full range
+
+---------------------
+
+.. type:: struct video_data
+
+   Video frame structure.
+
+.. member:: uint8_t           *video_data.data[MAX_AV_PLANES]
+.. member:: uint32_t          video_data.linesize[MAX_AV_PLANES]
+.. member:: uint64_t          video_data.timestamp
+
+---------------------
+
+.. type:: struct video_output_info
+
+   Video output handler information
+
+.. member:: const char        *video_output_info.name
+.. member:: enum video_format video_output_info.format
+.. member:: uint32_t          video_output_info.fps_num
+.. member:: uint32_t          video_output_info.fps_den
+.. member:: uint32_t          video_output_info.width
+.. member:: uint32_t          video_output_info.height
+.. member:: size_t            video_output_info.cache_size
+.. member:: enum video_colorspace video_output_info.colorspace
+.. member:: enum video_range_type video_output_info.range
+
+---------------------
+
+.. function:: enum video_format video_format_from_fourcc(uint32_t fourcc)
+
+   Converts a fourcc value to a video format.
+
+   :param forcecc: Fourcc value
+   :return:        Video format
+
+---------------------
+
+.. function:: bool video_format_get_parameters(enum video_colorspace color_space, enum video_range_type range, float matrix[16], float min_range[3], float max_range[3])
+
+   Converts a color space/range to matrix/min/max values.
+
+   :param color_space: Color space to convert
+   :param range:       Color range to convert
+   :param matrix:      Pointer to the matrix
+   :param min_range:   Pointer to get the minimum range value
+   :param max_range:   Pointer to get the maximum range value
+
+---------------------
+
+.. function:: bool video_output_connect(video_t *video, const struct video_scale_info *conversion, void (*callback)(void *param, struct video_data *frame), void *param)
+
+   Connects a raw video callback to the video output handler.
+
+   :param video:    Video output handler object
+   :param callback: Callback to receive video data
+   :param param:    Private data to pass to the callback
+
+---------------------
+
+.. function:: void video_output_disconnect(video_t *video, void (*callback)(void *param, struct video_data *frame), void *param)
+
+   Disconnects a raw video callback from the video output handler.
+
+   :param video:    Video output handler object
+   :param callback: Callback
+   :param param:    Private data
+
+---------------------
+
+.. function:: const struct video_output_info *video_output_get_info(const video_t *video)
+
+   Gets the full video information of the video output handler.
+
+   :param video: Video output handler object
+   :return:      Video output info structure pointer
+
+---------------------
+
+.. function:: uint64_t video_output_get_frame_time(const video_t *video)
+
+   Gets the frame interval of the video output handler.
+
+   :param video: Video output handler object
+   :return:      Video frame interval in nanoseconds
+
+---------------------
+
+.. function:: enum video_format video_output_get_format(const video_t *video)
+
+   Gets the video format of the video output handler.
+
+   :param video: Video output handler object
+   :return:      Video format
+
+---------------------
+
+.. function:: uint32_t video_output_get_width(const video_t *video)
+.. function:: uint32_t video_output_get_height(const video_t *video)
+
+   Gets the width/height of the video output handler.
+
+   :param video: Video output handler object
+   :return:      Width/height
+
+---------------------
+
+.. function:: double video_output_get_frame_rate(const video_t *video)
+
+   Gets the frame rate (as a floating point) of the video output
+   handler.
+
+   :param video: Video output handler object
+   :return:      Frame rate
+
+---------------------
+
+.. function:: uint32_t video_output_get_skipped_frames(const video_t *video)
+
+   Gets the skipped frame count of the video output handler.
+
+   :param video: Video output handler object
+   :return:      Skipped frame count
+
+---------------------
+
+.. function:: uint32_t video_output_get_total_frames(const video_t *video)
+
+   Gets the total frames processed of the video output handler.
+
+   :param video: Video output handler object
+   :return:      Total frames processed
+
+---------------------
+
+
+Audio Handler
+-------------
+
+.. type:: audio_t
+
+---------------------
+
+.. type:: enum audio_format
+
+   Audio format.  Can be one of the following values:
+
+   - AUDIO_FORMAT_UNKNOWN
+   - AUDIO_FORMAT_U8BIT
+   - AUDIO_FORMAT_16BIT
+   - AUDIO_FORMAT_32BIT
+   - AUDIO_FORMAT_FLOAT
+   - AUDIO_FORMAT_U8BIT_PLANAR
+   - AUDIO_FORMAT_16BIT_PLANAR
+   - AUDIO_FORMAT_32BIT_PLANAR
+   - AUDIO_FORMAT_FLOAT_PLANAR
+
+---------------------
+
+.. type:: enum speaker_layout
+
+   Speaker layout.  Can be one of the following values:
+
+   - SPEAKERS_UNKNOWN
+   - SPEAKERS_MONO
+   - SPEAKERS_STEREO
+   - SPEAKERS_2POINT1
+   - SPEAKERS_QUAD
+   - SPEAKERS_4POINT1
+   - SPEAKERS_5POINT1
+   - SPEAKERS_5POINT1_SURROUND
+   - SPEAKERS_7POINT1
+   - SPEAKERS_7POINT1_SURROUND
+   - SPEAKERS_SURROUND
+
+---------------------
+
+.. type:: struct audio_data
+
+   Audio data structure.
+
+.. member:: uint8_t             *audio_data.data[MAX_AV_PLANES]
+.. member:: uint32_t            audio_data.frames
+.. member:: uint64_t            audio_data.timestamp
+
+---------------------
+
+.. type:: struct audio_output_data
+.. member:: float               *audio_output_data.data[MAX_AUDIO_CHANNELS]
+
+---------------------
+
+.. type:: struct audio_output_info
+.. member:: const char             *audio_output_info.name
+.. member:: uint32_t               audio_output_info.samples_per_sec
+.. member:: enum audio_format      audio_output_info.format
+.. member:: enum speaker_layout    audio_output_info.speakers
+.. member:: audio_input_callback_t audio_output_info.input_callback
+.. member:: void                   *audio_output_info.input_param
+
+---------------------
+
+.. type:: struct audio_convert_info
+.. member:: uint32_t            audio_convert_info.samples_per_sec
+.. member:: enum audio_format   audio_convert_info.format
+.. member:: enum speaker_layout audio_convert_info.speakers
+
+---------------------
+
+.. type:: typedef bool (*audio_input_callback_t)(void *param, uint64_t start_ts, uint64_t end_ts, uint64_t *new_ts, uint32_t active_mixers, struct audio_output_data *mixes)
+
+   Audio input callback (typically used internally).
+
+---------------------
+
+.. function:: uint32_t get_audio_channels(enum speaker_layout speakers)
+
+   Converts a speaker layout to its audio channel count.
+
+   :param speakers: Speaker layout enumeration
+   :return:         Channel count
+
+---------------------
+
+.. function:: size_t get_audio_bytes_per_channel(enum audio_format format)
+
+   Gets the audio bytes per channel for a specific audio format.
+
+   :param format: Audio format
+   :return:       Bytes per channel
+
+---------------------
+
+.. function:: bool is_audio_planar(enum audio_format format)
+
+   Returns whether the audio format is a planar format.
+
+   :param format: Audio format
+   :return:       *true* if audio is planar, *false* otherwise
+
+---------------------
+
+.. function:: size_t get_audio_planes(enum audio_format format, enum speaker_layout speakers)
+
+   Gets the number of audio planes for a specific audio format and
+   speaker layout.
+
+   :param format:   Audio format
+   :param speakers: Speaker layout
+   :return:         Number of audio planes
+
+---------------------
+
+.. function:: size_t get_audio_size(enum audio_format format, enum speaker_layout speakers, uint32_t frames)
+
+   Gets the audio block size for a specific frame out with the given
+   format and speaker layout.
+
+   :param format:   Audio format
+   :param speakers: Speaker layout
+   :param frames:   Audio frame count
+   :return:         Audio block size
+
+---------------------
+
+.. function:: uint64_t audio_frames_to_ns(size_t sample_rate, uint64_t frames)
+
+   Helper function to convert a specific number of audio frames to
+   nanoseconds based upon its sample rate.
+
+   :param sample_rate: Sample rate
+   :param frames:      Frame count
+   :return:            Nanoseconds
+
+---------------------
+
+.. function:: uint64_t ns_to_audio_frames(size_t sample_rate, uint64_t ns)
+
+   Helper function to convert a specific number of nanoseconds to audio
+   frame count based upon its sample rate.
+
+   :param sample_rate: Sample rate
+   :param ns:          Nanoseconds
+   :return:            Frame count
+
+---------------------
+
+.. type:: typedef void (*audio_output_callback_t)(void *param, size_t mix_idx, struct audio_data *data)
+
+   Audio output callback.  Typically used internally.
+
+---------------------
+
+.. function:: bool audio_output_connect(audio_t *audio, size_t mix_idx, const struct audio_convert_info *conversion, audio_output_callback_t callback, void *param)
+
+   Connects a raw audio callback to the audio output handler.
+   Optionally allows audio conversion if necessary.
+
+   :param audio:      Audio output handler object
+   :param mix_idx:    Mix index to get raw audio from
+   :param conversion: Audio conversion information, or *NULL* for no
+                      conversion
+   :param callback:   Raw audio callback
+   :param param:      Private data to pass to the callback
+
+---------------------
+
+.. function:: void audio_output_disconnect(audio_t *audio, size_t mix_idx, audio_output_callback_t callback, void *param)
+
+   Disconnects a raw audio callback from the audio output handler.
+
+   :param audio:      Audio output handler object
+   :param mix_idx:    Mix index to get raw audio from
+   :param callback:   Raw audio callback
+   :param param:      Private data to pass to the callback
+
+---------------------
+
+.. function:: size_t audio_output_get_block_size(const audio_t *audio)
+
+   Gets the audio block size of an audio output handler.
+
+   :param audio: Audio output handler object
+   :return:      Audio block size
+
+---------------------
+
+.. function:: size_t audio_output_get_planes(const audio_t *audio)
+
+   Gets the plane count of an audio output handler.
+
+   :param audio: Audio output handler object
+   :return:      Audio plane count
+
+---------------------
+
+.. function:: size_t audio_output_get_channels(const audio_t *audio)
+
+   Gets the channel count of an audio output handler.
+
+   :param audio: Audio output handler object
+   :return:      Audio channel count
+
+---------------------
+
+.. function:: uint32_t audio_output_get_sample_rate(const audio_t *audio)
+
+   Gets the sample rate of an audio output handler.
+
+   :param audio: Audio output handler object
+   :return:      Audio sample rate
+
+---------------------
+
+.. function:: const struct audio_output_info *audio_output_get_info(const audio_t *audio)
+
+   Gets all audio information for an audio output handler.
+
+   :param audio: Audio output handler object
+   :return:      Pointer to audio output information structure
+
+---------------------
+
+
+Resampler
+---------
+
+FFmpeg wrapper to resample audio.
+
+.. type:: typedef struct audio_resampler audio_resampler_t
+
+---------------------
+
+.. type:: struct resample_info
+.. member:: uint32_t            resample_info.samples_per_sec
+.. member:: enum audio_format   resample_info.format
+.. member:: enum speaker_layout resample_info.speakers
+
+---------------------
+
+.. function:: audio_resampler_t *audio_resampler_create(const struct resample_info *dst, const struct resample_info *src)
+
+   Creates an audio resampler.
+
+   :param dst: Destination audio information
+   :param src: Source audio information
+   :return:    Audio resampler object
+
+---------------------
+
+.. function:: void audio_resampler_destroy(audio_resampler_t *resampler)
+
+   Destroys an audio resampler.
+
+   :param resampler: Audio resampler object
+
+---------------------
+
+.. function:: bool audio_resampler_resample(audio_resampler_t *resampler, uint8_t *output[], uint32_t *out_frames, uint64_t *ts_offset, const uint8_t *const input[], uint32_t in_frames)
+
+   Resamples audio frames.
+
+   :param resampler:   Audio resampler object
+   :param output:      Pointer to receive converted audio frames
+   :param out_frames:  Pointer to receive converted audio frame count
+   :param ts_offset:   Pointer to receive timestamp offset (in
+                       nanoseconds)
+   :param const input: Input frames to convert
+   :param in_frames:   Input frame count

docs/sphinx/reference-libobs-util-base.rst

@@ -0,0 +1,75 @@
+Logging
+=======
+
+Functions for logging and getting log data.
+
+.. code:: cpp
+
+   #include <util/base.h>
+
+
+Logging Levels
+--------------
+
+**LOG_ERROR** = 100
+
+   Use if there's a problem that can potentially affect the program,
+   but isn't enough to require termination of the program.
+
+   Use in creation functions and core subsystem functions.  Places that
+   should definitely not fail.
+
+**LOG_WARNING** = 200
+
+   Use if a problem occurs that doesn't affect the program and is
+   recoverable.
+
+   Use in places where failure isn't entirely unexpected, and can
+   be handled safely.
+
+**LOG_INFO** = 300
+
+   Informative message to be displayed in the log.
+
+**LOG_DEBUG** = 400
+
+   Debug message to be used mostly by and for developers.
+
+
+Logging Functions
+-----------------
+
+.. type:: typedef void (*log_handler_t)(int lvl, const char *msg, va_list args, void *p)
+
+   Logging callback.
+
+---------------------
+
+.. function:: void base_set_log_handler(log_handler_t handler, void *param)
+              void base_get_log_handler(log_handler_t *handler, void **param)
+
+   Sets/gets the current log handler.
+
+---------------------
+
+.. function:: void base_set_crash_handler(void (*handler)(const char *, va_list, void *), void *param)
+
+   Sets the current crash handler.
+
+---------------------
+
+.. function:: void blogva(int log_level, const char *format, va_list args)
+
+   Logging function (using a va_list).
+
+---------------------
+
+.. function:: void blog(int log_level, const char *format, ...)
+
+   Logging function.
+
+---------------------
+
+.. function:: void bcrash(const char *format, ...)
+
+   Crash function.

docs/sphinx/reference-libobs-util-bmem.rst

@@ -0,0 +1,62 @@
+Memory Management
+=================
+
+Various functions and helpers used for memory management.
+
+.. code:: cpp
+
+   #include <util/bmem.h>
+
+
+Memory Functions
+----------------
+
+.. function:: void *bmalloc(size_t size)
+
+   Allocates memory and increases the memory leak counter.
+
+---------------------
+
+.. function:: void *brealloc(void *ptr, size_t size)
+
+   Reallocates memory.  Use only with memory that's been allocated by
+   :c:func:`bmalloc()`.
+
+---------------------
+
+.. function:: void bfree(void *ptr)
+
+   Frees memory allocated with :c:func:`bmalloc()` or :c:func:`bfree()`.
+
+---------------------
+
+.. function:: long bnum_allocs(void)
+
+   Returns current number of active allocations.
+
+---------------------
+
+.. function:: void *bmemdup(const void *ptr, size_t size)
+
+   Duplicates memory.
+
+---------------------
+
+.. function:: void *bzalloc(size_t size)
+
+   Inline function that allocates zeroed memory.
+
+---------------------
+
+.. function:: char *bstrdup_n(const char *str, size_t n)
+              wchar_t *bwstrdup_n(const wchar_t *str, size_t n)
+
+   Duplicates a string of *n* bytes and automatically zero-terminates
+   it.
+
+---------------------
+
+.. function:: char *bstrdup(const char *str)
+              wchar_t *bwstrdup(const wchar_t *str)
+
+   Duplicates a string.

docs/sphinx/reference-libobs-util-circlebuf.rst

@@ -0,0 +1,140 @@
+Circular Buffers
+================
+
+A circular buffer that will automatically increase in size as necessary
+as data is pushed to the front or back.
+
+.. code:: cpp
+
+   #include <util/circlebuf.h>
+
+
+Circular Buffer Structure (struct circlebuf)
+--------------------------------------------
+
+.. type:: struct circlebuf
+.. member:: void   *circlebuf.data
+.. member:: size_t circlebuf.size
+.. member:: size_t circlebuf.start_pos
+.. member:: size_t circlebuf.end_pos
+.. member:: size_t circlebuf.capacity
+
+
+Circular Buffer Inline Functions
+--------------------------------
+
+.. function:: void circlebuf_init(struct circlebuf *cb)
+
+   Initializes a circular buffer (just zeroes out the entire structure).
+
+   :param cb: The circular buffer
+
+---------------------
+
+.. function:: void circlebuf_free(struct circlebuf *cb)
+
+   Frees a circular buffer.
+
+   :param cb: The circular buffer
+
+---------------------
+
+.. function:: void circlebuf_reserve(struct circlebuf *cb, size_t capacity)
+
+   Reserves a specific amount of buffer space to ensure minimum
+   upsizing.
+
+   :param cb:       The circular buffer
+   :param capacity: The new capacity, in bytes
+
+---------------------
+
+.. function:: void circlebuf_upsize(struct circlebuf *cb, size_t size)
+
+   Sets the current active (not just reserved) size.  Any new data is
+   zeroed.
+
+   :param cb:       The circular buffer
+   :param size:     The new size, in bytes
+
+---------------------
+
+.. function:: void circlebuf_place(struct circlebuf *cb, size_t position, const void *data, size_t size)
+
+   Places data at a specific positional index (relative to the starting
+   point) within the circular buffer.
+
+   :param cb:       The circular buffer
+   :param position: Positional index relative to starting point
+   :param data:     Data to insert
+   :param size:     Size of data to insert
+
+---------------------
+
+.. function:: void circlebuf_push_back(struct circlebuf *cb, const void *data, size_t size)
+
+   Pushes data to the end of the circular buffer.
+
+   :param cb:       The circular buffer
+   :param data:     Data
+   :param size:     Size of data
+
+---------------------
+
+.. function:: void circlebuf_push_front(struct circlebuf *cb, const void *data, size_t size)
+
+   Pushes data to the front of the circular buffer.
+
+   :param cb:       The circular buffer
+   :param data:     Data
+   :param size:     Size of data
+
+---------------------
+
+.. function:: void circlebuf_peek_front(struct circlebuf *cb, void *data, size_t size)
+
+   Peeks data at the front of the circular buffer.
+
+   :param cb:       The circular buffer
+   :param data:     Buffer to store data in
+   :param size:     Size of data to retrieve
+
+---------------------
+
+.. function:: void circlebuf_peek_back(struct circlebuf *cb, void *data, size_t size)
+
+   Peeks data at the back of the circular buffer.
+
+   :param cb:       The circular buffer
+   :param data:     Buffer to store data in
+   :param size:     Size of data to retrieve
+
+---------------------
+
+.. function:: void circlebuf_pop_front(struct circlebuf *cb, void *data, size_t size)
+
+   Pops data from the front of the circular buffer.
+
+   :param cb:       The circular buffer
+   :param data:     Buffer to store data in, or *NULL*
+   :param size:     Size of data to retrieve
+
+---------------------
+
+.. function:: void circlebuf_pop_back(struct circlebuf *cb, void *data, size_t size)
+
+   Pops data from the back of the circular buffer.
+
+   :param cb:       The circular buffer
+   :param data:     Buffer to store data in, or *NULL*
+   :param size:     Size of data to retrieve
+
+---------------------
+
+.. function:: void *circlebuf_data(struct circlebuf *cb, size_t idx)
+
+   Gets a direct pointer to data at a specific positional index within
+   the circular buffer, relative to the starting point.
+
+   :param cb:       The circular buffer
+   :param idx:      Byte index relative to the starting point

docs/sphinx/reference-libobs-util-config-file.rst

@@ -0,0 +1,312 @@
+Config Files
+============
+
+The configuration file functions are a simple implementation of the INI
+file format, with the addition of default values.
+
+.. code:: cpp
+
+   #include <util/config-file.h>
+
+.. type:: config_t
+
+
+Config File Functions
+---------------------
+
+.. function:: config_t *config_create(const char *file)
+
+   Creates a new configuration object and associates it with the
+   specified file name.
+
+   :param file: Path to the new configuration file
+   :return:     A new configuration file object
+
+----------------------
+
+.. function:: int config_open(config_t **config, const char *file, enum config_open_type open_type)
+
+   Opens a configuration file.
+
+   :param config:    Pointer that receives a pointer to a new configuration
+                     file object (if successful)
+   :param file:      Path to the configuration file
+   :param open_type: Can be one of the following values:
+
+                     - CONFIG_OPEN_EXISTING - Fail if the file doesn't
+                       exist.
+                     - CONFIG_OPEN_ALWAYS - Try to open the file.  If
+                       the file doesn't exist, create it.
+
+   :return:          Can return the following values:
+
+                     - CONFIG_SUCCESS - Successful
+                     - CONFIG_FILENOTFOUND - File not found
+                     - CONFIG_ERROR - Generic error
+
+----------------------
+
+.. function:: int config_open_string(config_t **config, const char *str)
+
+   Opens configuration data via a string rather than a file.
+
+   :param config:    Pointer that receives a pointer to a new configuration
+                     file object (if successful)
+   :param str:       Configuration string
+
+   :return:          Can return the following values:
+
+                     - CONFIG_SUCCESS - Successful
+                     - CONFIG_FILENOTFOUND - File not found
+                     - CONFIG_ERROR - Generic error
+
+----------------------
+
+.. function:: int config_save(config_t *config)
+
+   Saves configuration data to a file (if associated with a file).
+
+   :param config:    Configuration object
+
+   :return:          Can return the following values:
+
+                     - CONFIG_SUCCESS - Successful
+                     - CONFIG_FILENOTFOUND - File not found
+                     - CONFIG_ERROR - Generic error
+
+----------------------
+
+.. function:: int config_save_safe(config_t *config, const char *temp_ext, const char *backup_ext)
+
+   Saves configuration data and minimizes overwrite corruption risk.
+   Saves the file with the file name
+
+   :param config:     Configuration object
+   :param temp_ext:   Temporary extension for the new file
+   :param backup_ext: Backup extension for the old file.  Can be *NULL*
+                      if no backup is desired.
+
+   :return:           Can return the following values:
+
+                      - CONFIG_SUCCESS - Successful
+                      - CONFIG_FILENOTFOUND - File not found
+                      - CONFIG_ERROR - Generic error
+
+----------------------
+
+.. function:: void config_close(config_t *config)
+
+   Closes the configuration object.
+
+   :param config:     Configuration object
+
+----------------------
+
+.. function:: size_t config_num_sections(config_t *config)
+
+   Returns the number of sections.
+
+   :param config:     Configuration object
+   :return:           Number of configuration sections
+
+----------------------
+
+.. function:: const char *config_get_section(config_t *config, size_t idx)
+
+   Returns a section name based upon its index.
+
+   :param config:     Configuration object
+   :param idx:        Index of the section
+   :return:           The section's name
+
+Set/Get Functions
+-----------------
+
+.. function:: void config_set_string(config_t *config, const char *section, const char *name, const char *value)
+
+   Sets a string value.
+
+   :param config:     Configuration object
+   :param section:    The section of the value
+   :param name:       The value name
+   :param value:      The string value
+
+----------------------
+
+.. function:: void config_set_int(config_t *config, const char *section, const char *name, int64_t value)
+
+   Sets an integer value.
+
+   :param config:     Configuration object
+   :param section:    The section of the value
+   :param name:       The value name
+   :param value:      The integer value
+
+----------------------
+
+.. function:: void config_set_uint(config_t *config, const char *section, const char *name, uint64_t value)
+
+   Sets an unsigned integer value.
+
+   :param config:     Configuration object
+   :param section:    The section of the value
+   :param name:       The value name
+   :param value:      The unsigned integer value
+
+----------------------
+
+.. function:: void config_set_bool(config_t *config, const char *section, const char *name, bool value)
+
+   Sets a boolean value.
+
+   :param config:     Configuration object
+   :param section:    The section of the value
+   :param name:       The value name
+   :param value:      The boolean value
+
+----------------------
+
+.. function:: void config_set_double(config_t *config, const char *section, const char *name, double value)
+
+   Sets a floating point value.
+
+   :param config:     Configuration object
+   :param section:    The section of the value
+   :param name:       The value name
+   :param value:      The floating point value
+
+----------------------
+
+.. function:: const char *config_get_string(config_t *config, const char *section, const char *name)
+
+   Gets a string value.  If the value is not set, it will use the
+   default value.  If there is no default value, it will return *NULL*.
+
+   :param config:     Configuration object
+   :param section:    The section of the value
+   :param name:       The value name
+   :return:           The string value
+
+----------------------
+
+.. function:: int64_t config_get_int(config_t *config, const char *section, const char *name)
+
+   Gets an integer value.  If the value is not set, it will use the
+   default value.  If there is no default value, it will return 0.
+
+   :param config:     Configuration object
+   :param section:    The section of the value
+   :param name:       The value name
+   :return:           The integer value
+
+----------------------
+
+.. function:: uint64_t config_get_uint(config_t *config, const char *section, const char *name)
+
+   Gets an unsigned integer value.  If the value is not set, it will use
+   the default value.  If there is no default value, it will return 0.
+
+   :param config:     Configuration object
+   :param section:    The section of the value
+   :param name:       The value name
+   :return:           The unsigned integer value
+
+----------------------
+
+.. function:: bool config_get_bool(config_t *config, const char *section, const char *name)
+
+   Gets a boolean value.  If the value is not set, it will use the
+   default value.  If there is no default value, it will return false.
+
+   :param config:     Configuration object
+   :param section:    The section of the value
+   :param name:       The value name
+   :return:           The boolean value
+
+----------------------
+
+.. function:: double config_get_double(config_t *config, const char *section, const char *name)
+
+   Gets a floating point value.  If the value is not set, it will use
+   the default value.  If there is no default value, it will return 0.0.
+
+   :param config:     Configuration object
+   :param section:    The section of the value
+   :param name:       The value name
+   :return:           The floating point value
+
+----------------------
+
+.. function:: bool config_remove_value(config_t *config, const char *section, const char *name)
+
+   Removes a value.  Does not remove the default value if any.
+
+   :param config:     Configuration object
+   :param section:    The section of the value
+   :param name:       The value name
+
+
+Default Value Functions
+-----------------------
+
+.. function:: int config_open_defaults(config_t *config, const char *file)
+
+   Opens a file and uses it for default values.
+
+   :param config:     Configuration object
+   :param file:       The file to open for default values
+
+----------------------
+
+.. function:: void config_set_default_string(config_t *config, const char *section, const char *name, const char *value)
+
+   Sets a default string value.
+
+   :param config:     Configuration object
+   :param section:    The section of the value
+   :param name:       The value name
+   :param value:      The string value
+
+----------------------
+
+.. function:: void config_set_default_int(config_t *config, const char *section, const char *name, int64_t value)
+
+   Sets a default integer value.
+
+   :param config:     Configuration object
+   :param section:    The section of the value
+   :param name:       The value name
+   :param value:      The integer value
+
+----------------------
+
+.. function:: void config_set_default_uint(config_t *config, const char *section, const char *name, uint64_t value)
+
+   Sets a default unsigned integer value.
+
+   :param config:     Configuration object
+   :param section:    The section of the value
+   :param name:       The value name
+   :param value:      The unsigned integer value
+
+----------------------
+
+.. function:: void config_set_default_bool(config_t *config, const char *section, const char *name, bool value)
+
+   Sets a default boolean value.
+
+   :param config:     Configuration object
+   :param section:    The section of the value
+   :param name:       The value name
+   :param value:      The boolean value
+
+----------------------
+
+.. function:: void config_set_default_double(config_t *config, const char *section, const char *name, double value)
+
+   Sets a default floating point value.
+
+   :param config:     Configuration object
+   :param section:    The section of the value
+   :param name:       The value name
+   :param value:      The floating point value

docs/sphinx/reference-libobs-util-darray.rst

@@ -0,0 +1,275 @@
+Dynamic Arrays
+==============
+
+Dynamically resizing arrays (a C equivalent to std::vector).
+
+.. code:: cpp
+
+   #include <util/darray.h>
+
+.. type:: struct darray
+
+   The base dynamic array structure.
+
+.. type:: DARRAY(type)
+
+   Macro for a dynamic array based upon an actual type.  Use this with
+   da_* macros.
+
+.. member:: void *darray.array
+
+   The array pointer.
+
+.. member:: size_t darray.num
+
+   The number of items within the array.
+
+.. member:: size_t darray.capacity
+
+   The capacity of the array.
+
+
+Dynamic Array Macros
+--------------------
+
+These macro functions are used with variables created with the
+**DARRAY** type macro.  When using these functions, do not use the
+dynamic array value with a reference (&) operator.  For example:
+
+.. code:: cpp
+
+   /* creates an array of integers: 0..9 */
+   DARRAY(int) array_of_integers;
+   da_init(array_of_integers);
+
+   for (size_t i = 0; i < 10; i++)
+           da_push_back(array_of_integers, &i);
+
+   [...]
+
+   /* free when complete */
+   da_free(array_of_integers);
+
+.. function:: void da_init(da)
+
+   Initializes a dynamic array.
+
+   :param da: The dynamic array
+
+---------------------
+
+.. function:: void da_free(da)
+
+   Frees a dynamic array.
+
+   :param da: The dynamic array
+
+---------------------
+
+.. function:: void *da_end(da)
+
+   Gets a pointer to the last value.
+
+   :param da: The dynamic array
+   :return:   The last value of a dynamic array, or *NULL* if empty.
+
+---------------------
+
+.. function:: void da_reserve(da, size_t capacity)
+
+   Reserves a specific amount of buffer space for the dynamic array.
+
+   :param da:       The dynamic array
+   :param capacity: New capacity of the dynamic array
+
+---------------------
+
+.. function:: void da_resize(da, size_t new_size)
+
+   Resizes the dynamic array with zeroed values.
+
+   :param da:   The dynamic array
+   :param size: New size of the dynamic array
+
+---------------------
+
+.. function:: void da_copy(da_dst, da_src)
+
+   Makes a copy of a dyanmic array.
+
+   :param da_dst: The dynamic array to copy to
+   :param da_src: The dynamic array to copy from
+
+---------------------
+
+.. function:: void da_copy_array(da, const void *src_array, size_t size)
+
+   Makes a copy of an array pointer.
+
+   :param da:        The dynamic array
+   :param src_array: The array pointer to make a copy from
+   :param size:      New size of the dynamic array
+
+---------------------
+
+.. function:: void da_move(da_dst, da_src)
+
+   Moves one dynamic array variable to another without allocating new
+   data.  *da_dst* is freed before moving, *da_dst* is set to *da_src*,
+   then *da_src* is then zeroed.
+
+   :param da_dst: Destination variable
+   :param da_src: Source variable
+
+---------------------
+
+.. function:: size_t da_find(da, const void *item_data, size_t starting_idx)
+
+   Finds a value based upon its data.  If the value cannot be found, the
+   return value will be DARRAY_INVALID (-1).
+
+   :param da:           The dynamic array
+   :param item_data:    The item data to find
+   :param starting_idx: The index to start from or 0 to search the
+                        entire array
+
+---------------------
+
+.. function:: void da_push_back(da, const void *data)
+
+   Pushes data to the back of the array.
+
+   :param da:   The dynamic array
+   :param data: Pointer to the new data to push
+
+---------------------
+
+.. function:: void *da_push_back_new(da)
+
+   Pushes a zeroed value to the back of the array, and returns a pointer
+   to it.
+
+   :param da: The dynamic array
+   :return:   Pointer to the new value
+
+---------------------
+
+.. function:: void da_push_back_array(da, const void *src_array, size_t item_count)
+
+   Pushes an array of values to the back of the array.
+
+   :param da:         The dynamic array
+   :param src_array:  Pointer of the array of values
+   :param item_count: Number of items to push back
+
+---------------------
+
+.. function:: void da_insert(da, size_t idx, const void *data)
+
+   Inserts a value at a given index.
+
+   :param da:   The dynamic array:
+   :param idx:  Index where the new item will be inserted
+   :param data: Pointer to the item data to insert
+
+---------------------
+
+.. function:: void *da_insert_new(da, size_t idx)
+
+   Inserts a new zeroed value at a specific index, and returns a pointer
+   to it.
+
+   :param da:  The dynamic array
+   :param idx: Index to insert at
+   :return:    Pointer to the new value
+
+---------------------
+
+.. function:: void da_insert_da(da_dst, size_t idx, da_src)
+
+   Inserts a dynamic array in to another dynamic array at a specific
+   index.
+
+   :param da_dst: Destination dynamic array being inserted in to
+   :param idx:    Index to insert the data at
+   :param da_src: The dynamic array to insert
+
+---------------------
+
+.. function:: void da_erase(da, size_t idx)
+
+   Erases an item at a specific index.
+
+   :param da:  The dynamic array
+   :param idx: The index of the value to remove
+
+---------------------
+
+.. function:: void da_erase_item(da, const void *item_data)
+
+   Erases an item that matches the value specified
+
+   :param da:        The dynamic array
+   :param item_data: Pointer to the data to remove
+
+---------------------
+
+.. function:: void da_erase_range(da, size_t start_idx, size_t end_idx)
+
+   Erases a range of values.
+
+   :param da:        The dynamic array
+   :param start_idx: The starting index
+   :param end_idx:   The ending index
+
+---------------------
+
+.. function:: void da_pop_back(da)
+
+   Removes one item from the end of a dynamic array.
+
+   :param da: The dynamic array
+
+---------------------
+
+.. function:: void da_join(da_dst, da_src)
+
+   Pushes *da_src* to the end of *da_dst* and frees *da_src*.
+
+   :param da_dst: The destination dynamic array
+   :param da_src: The source dynamic array
+
+---------------------
+
+.. function:: void da_split(da_dst1, da_dst2, da_src, size_t split_idx)
+
+   Creates two dynamic arrays by splitting another dynamic array at a
+   specific index.  If the destination arrays are not freed, they will
+   be freed before getting their new values.  The array being split will
+   not be freed.
+
+   :param da_dst1:   Dynamic array that will get the lower half
+   :param da_dst2:   Dynamic array that will get the upper half
+   :param da_src:    Dynamic array to split
+   :param split_idx: Index to split *da_src* at
+
+---------------------
+
+.. function:: void da_move_item(da, size_t src_idx, size_t dst_idx)
+
+   Moves an item from one index to another, moving data between if
+   necessary.
+
+   :param da:      The dynamic array
+   :param src_idx: The index of the item to move
+   :param dst_idx: The new index of where the item will be moved to
+
+---------------------
+
+.. function:: void da_swap(da, size_t idx1, size_t idx2)
+
+   Swaps two values at the given indices.
+
+   :param da: The dynamic array
+   :param idx1: Index of the first item to swap
+   :param idx2: Index of the second item to swap

docs/sphinx/reference-libobs-util-dstr.rst

@@ -0,0 +1,490 @@
+Dynamic Strings And String Helpers
+==================================
+
+Provides string helper structures/functions (roughly equivalent to
+std::string).
+
+.. code:: cpp
+
+   #include <util/dstr.h>
+
+
+Dynamic String Structure (struct dstr)
+--------------------------------------
+
+.. type:: struct dstr
+.. member:: char *dstr.array
+.. member:: size_t dstr.len
+.. member:: size_t dstr.capacity
+
+
+General String Helper Functions
+-------------------------------
+
+.. function:: int astrcmpi(const char *str1, const char *str2)
+
+   Case insensitive string comparison function.
+
+----------------------
+
+.. function:: int wstrcmpi(const wchar_t *str1, const wchar_t *str2)
+
+   Case insensitive wide string comparison function.
+
+----------------------
+
+.. function:: int astrcmp_n(const char *str1, const char *str2, size_t n)
+
+   String comparison function for a specific number of characters.
+
+----------------------
+
+.. function:: int wstrcmp_n(const wchar_t *str1, const wchar_t *str2, size_t n)
+
+   Wide string comparison function for a specific number of characters.
+
+----------------------
+
+.. function:: int astrcmpi_n(const char *str1, const char *str2, size_t n)
+
+   Case insensitive string comparison function for a specific number of
+   characters.
+
+----------------------
+
+.. function:: int wstrcmpi_n(const wchar_t *str1, const wchar_t *str2, size_t n)
+
+   Case insensitive wide string comparison function for a specific
+   number of characters.
+
+----------------------
+
+.. function:: char *astrstri(const char *str, const char *find)
+
+   Case insensitive version of strstr.
+
+----------------------
+
+.. function:: wchar_t *wstrstri(const wchar_t *str, const wchar_t *find)
+
+   Case insensitive version of wcsstr.
+
+----------------------
+
+.. function:: char *strdepad(char *str)
+
+   Removes padding characters (tab, space, CR, LF) from the front and
+   end of a string.
+
+----------------------
+
+.. function:: wchar_t *wcsdepad(wchar_t *str)
+
+   Removes padding characters (tab, space, CR, LF) from the front and
+   end of a wide string.
+
+----------------------
+
+.. function:: char **strlist_split(const char *str, char split_ch, bool include_empty)
+
+   Splits a string in to a list of multiple sub-strings.  Free with
+   :c:func:`strlist_free()`.
+
+----------------------
+
+.. function:: void strlist_free(char **strlist)
+
+   Frees a string list created with :c:func:`strlist_split()`.
+
+---------------------
+
+
+Dynamic String Functions
+------------------------
+
+.. function:: void dstr_init(struct dstr *dst)
+
+   Initializes a dynamic string variable (just zeroes the variable).
+
+   :param dst: Dynamic string to initialize
+
+----------------------
+
+.. function:: void dstr_init_move(struct dstr *dst, struct dstr *src)
+
+   Moves a *src* to *dst* without copying data and zeroes *src*.
+
+   :param dst: Destination
+   :param src: Source
+
+----------------------
+
+.. function:: void dstr_init_move_array(struct dstr *dst, char *str)
+
+   Sets a bmalloc-allocated string as the dynamic string without
+   copying/reallocating.
+
+   :param dst: Dynamic string to initialize
+   :param str: bmalloc-allocated string
+
+----------------------
+
+.. function:: void dstr_init_copy(struct dstr *dst, const char *src)
+
+   Initializes a dynamic string with a copy of a string
+
+   :param dst: Dynamic string to initialize
+   :param src: String to copy
+
+----------------------
+
+.. function:: void dstr_init_copy_dstr(struct dstr *dst, const struct dstr *src)
+
+   Initializes a dynamic string with a copy of another dynamic string
+
+   :param dst: Dynamic string to initialize
+   :param src: Dynamic string to copy
+
+----------------------
+
+.. function:: void dstr_free(struct dstr *dst)
+
+   Frees a dynamic string.
+
+   :param dst: Dynamic string
+
+----------------------
+
+.. function:: void dstr_copy(struct dstr *dst, const char *array)
+
+   Copies a string.
+
+   :param dst:   Dynamic string
+   :param array: String to copy
+
+----------------------
+
+.. function:: void dstr_copy_dstr(struct dstr *dst, const struct dstr *src)
+
+   Copies another dynamic string.
+
+   :param dst: Dynamic string
+   :param src: Dynamic string to copy
+
+----------------------
+
+.. function:: void dstr_ncopy(struct dstr *dst, const char *array, const size_t len)
+
+   Copies a specific number of characters from a string.
+
+   :param dst:   Dynamic string
+   :param array: String to copy
+   :param len:   Number of characters to copy
+
+----------------------
+
+.. function:: void dstr_ncopy_dstr(struct dstr *dst, const struct dstr *src, const size_t len)
+
+   Copies a specific number of characters from another dynamic string.
+
+   :param dst:   Dynamic string
+   :param src:   Dynamic tring to copy
+   :param len:   Number of characters to copy
+
+----------------------
+
+.. function:: void dstr_resize(struct dstr *dst, const size_t num)
+
+   Sets the size of the dynamic string.  If the new size is bigger than
+   current size, zeroes the new characters.
+
+   :param dst: Dynamic string
+   :param num: New size
+
+----------------------
+
+.. function:: void dstr_reserve(struct dstr *dst, const size_t num)
+
+   Reserves a specific number of characters in the buffer (but does not
+   change the size).  Does not work if the value is smaller than the
+   current reserve size.
+
+   :param dst: Dynamic string
+   :param num: New reserve size
+
+----------------------
+
+.. function:: bool dstr_is_empty(const struct dstr *str)
+
+   Returns whether the dynamic string is empty.
+
+   :param str: Dynamic string
+   :return:    *true* if empty, *false* otherwise
+
+----------------------
+
+.. function:: void dstr_cat(struct dstr *dst, const char *array)
+
+   Concatenates a dynamic string.
+
+   :param dst:   Dynamic string
+   :param array: String to concatenate with
+
+----------------------
+
+.. function:: void dstr_cat_dstr(struct dstr *dst, const struct dstr *str)
+
+   Concatenates a dyanmic string with another dynamic string.
+
+   :param dst: Dynamic string to concatenate to
+   :param str: Dynamic string to concatenate with
+
+----------------------
+
+.. function:: void dstr_cat_ch(struct dstr *dst, char ch)
+
+   Concatenates a dynamic string with a single character.
+
+   :param dst: Dynamic string to concatenate to
+   :param ch:  Character to concatenate
+
+----------------------
+
+.. function:: void dstr_ncat(struct dstr *dst, const char *array, const size_t len)
+
+   Concatenates a dynamic string with a specific number of characters
+   from a string.
+
+   :param dst:   Dynamic string to concatenate to
+   :param array: String to concatenate with
+   :param len:   Number of characters to concatenate with
+
+----------------------
+
+.. function:: void dstr_ncat_dstr(struct dstr *dst, const struct dstr *str, const size_t len)
+
+   Concatenates a dynamic string with a specific number of characters
+   from another dynamic string.
+
+   :param dst: Dynamic string to concatenate to
+   :param str: Dynamic string to concatenate with
+   :param len: Number of characters to concatenate with
+
+----------------------
+
+.. function:: void dstr_insert(struct dstr *dst, const size_t idx, const char *array)
+
+   Inserts a string in to a dynamic string at a specific index.
+
+   :param dst:   Dynamic string to insert in to
+   :param idx:   Character index to insert at
+   :param array: String to insert
+
+----------------------
+
+.. function:: void dstr_insert_dstr(struct dstr *dst, const size_t idx, const struct dstr *str)
+
+   Inserts another dynamic string in to a dynamic string at a specific
+   index.
+
+   :param dst:   Dynamic string to insert in to
+   :param idx:   Character index to insert at
+   :param str:   Dynamic string to insert
+
+----------------------
+
+.. function:: void dstr_insert_ch(struct dstr *dst, const size_t idx, const char ch)
+
+   Inserts a character in to a dynamic string at a specific index.
+
+   :param dst:   Dynamic string to insert in to
+   :param idx:   Character index to insert at
+   :param ch:    Character to insert
+
+----------------------
+
+.. function:: void dstr_remove(struct dstr *dst, const size_t idx, const size_t count)
+
+   Removes a specific number of characters starting from a specific
+   index.
+
+   :param dst:   Dyanmic string
+   :param idx:   Index to start removing characters at
+   :param count: Number of characters to remove
+
+----------------------
+
+.. function:: void dstr_printf(struct dstr *dst, const char *format, ...)
+              void dstr_vprintf(struct dstr *dst, const char *format, va_list args)
+
+   Sets a dynamic string to a formatted string.
+
+   :param dst:    Dynamic string
+   :param format: Format string
+
+----------------------
+
+.. function:: void dstr_catf(struct dstr *dst, const char *format, ...)
+              void dstr_vcatf(struct dstr *dst, const char *format, va_list args)
+
+   Concatenates a dynamic string with a formatted string.
+
+   :param dst:    Dynamic string
+   :param format: Format string
+
+----------------------
+
+.. function:: const char *dstr_find_i(const struct dstr *str, const char *find)
+
+   Finds a string within a dynamic string, case insensitive.
+
+   :param str:  Dynamic string
+   :param find: String to find
+   :return:     Pointer to the first occurrence, or *NULL* if not found
+
+----------------------
+
+.. function:: const char *dstr_find(const struct dstr *str, const char *find)
+
+   Finds a string within a dynamic string.
+
+   :param str:  Dynamic string
+   :param find: String to find
+   :return:     Pointer to the first occurrence, or *NULL* if not found
+
+----------------------
+
+.. function:: void dstr_replace(struct dstr *str, const char *find, const char *replace)
+
+   Replaces all occurrences of *find* with *replace*.
+
+   :param str:     Dynamic string
+   :param find:    String to find
+   :param replace: Replacement string
+
+----------------------
+
+.. function:: int dstr_cmp(const struct dstr *str1, const char *str2)
+
+   Compares with a string.
+
+   :param str1: Dynamic string
+   :param str2: String to compare
+   :return:     0 if equal, nonzero otherwise
+
+----------------------
+
+.. function:: int dstr_cmpi(const struct dstr *str1, const char *str2)
+
+   Compares with a string, case-insensitive.
+
+   :param str1: Dynamic string
+   :param str2: String to compare
+   :return:     0 if equal, nonzero otherwise
+
+----------------------
+
+.. function:: int dstr_ncmp(const struct dstr *str1, const char *str2, const size_t n)
+
+   Compares a specific number of characters.
+
+   :param str1: Dynamic string
+   :param str2: String to compare
+   :param n:    Number of characters to compare
+   :return:     0 if equal, nonzero otherwise
+
+----------------------
+
+.. function:: int dstr_ncmpi(const struct dstr *str1, const char *str2, const size_t n)
+
+   Compares a specific number of characters, case-insensitive.
+
+   :param str1: Dynamic string
+   :param str2: String to compare
+   :param n:    Number of characters to compare
+   :return:     0 if equal, nonzero otherwise
+
+----------------------
+
+.. function:: void dstr_depad(struct dstr *dst)
+
+   Removes all padding characters (tabs, spaces, CR, LF) from the front
+   and ends of a dynamic string.
+
+   :param dst: Dynamic string
+
+----------------------
+
+.. function:: void dstr_left(struct dstr *dst, const struct dstr *str, const size_t pos)
+
+   Copies a certain number of characters from the left side of one
+   dynamic string in to another.
+
+   :param dst:   Destination
+   :param str:   Source
+   :param pos:   Number of characters
+
+----------------------
+
+.. function:: void dstr_mid(struct dstr *dst, const struct dstr *str, const size_t start, const size_t count)
+
+   Copies a certain number of characters from the middle of one dynamic
+   string in to another.
+
+   :param dst:   Destination
+   :param str:   Source
+   :param start: Starting index within *str*
+   :param count: Number of characters to copy
+
+----------------------
+
+.. function:: void dstr_right(struct dstr *dst, const struct dstr *str, const size_t pos)
+
+   Copies a certain number of characters from the right of one dynamic
+   string in to another.
+
+   :param dst:   Destination
+   :param str:   Source
+   :param pos:   Index of *str* to copy from
+
+----------------------
+
+.. function:: char dstr_end(const struct dstr *str)
+
+   :param str: Dynamic string
+   :return:    The last character of a dynamic string
+
+----------------------
+
+.. function:: void dstr_from_wcs(struct dstr *dst, const wchar_t *wstr)
+
+   Copies a wide string in to a dynamic string and converts it to UTF-8.
+
+   :param dst:  Dynamic string
+   :param wstr: Wide string
+
+----------------------
+
+.. function:: wchar_t *dstr_to_wcs(const struct dstr *str)
+
+   Converts a dynamic array to a wide string.  Free with
+   :c:func:`bfree()`.
+
+   :param str: Dynamic string
+   :return:    Wide string allocation.  Free with :c:func:`bfree()`
+
+----------------------
+
+.. function:: void dstr_to_upper(struct dstr *str)
+
+   Converts all characters within a dynamic array to uppercase.
+
+   :param str: Dynamic string
+
+----------------------
+
+.. function:: void dstr_to_lower(struct dstr *str)
+
+   Converts all characters within a dynamic array to lowercase.
+
+   :param str: Dynamic string

docs/sphinx/reference-libobs-util-platform.rst

@@ -0,0 +1,465 @@
+Platform Helpers
+================
+
+These functions/structures/types are used to perform actions that
+typically don't have shared functions across different operating systems
+and platforms.
+
+.. code:: cpp
+
+   #include <util/platform.h>
+
+
+File Functions
+--------------
+
+.. function:: FILE *os_wfopen(const wchar_t *path, const char *mode)
+
+   Opens a file with a wide string path.
+
+----------------------
+
+.. function:: FILE *os_fopen(const char *path, const char *mode)
+
+   Opens a file with a UTF8 string path.
+
+----------------------
+
+.. function:: int64_t os_fgetsize(FILE *file)
+
+   Returns a file's size.
+
+----------------------
+
+.. function:: int os_stat(const char *file, struct stat *st)
+
+   Equivalent to the posix *stat* function.
+
+----------------------
+
+.. function:: int os_fseeki64(FILE *file, int64_t offset, int origin)
+
+   Equivalent to fseek.
+
+----------------------
+
+.. function:: int64_t os_ftelli64(FILE *file)
+
+   Gets the current file position.
+
+----------------------
+
+.. function:: size_t os_fread_utf8(FILE *file, char **pstr)
+
+   Reads a UTF8 encoded file and allocates a pointer to the UTF8 string.
+
+----------------------
+
+.. function:: char *os_quick_read_utf8_file(const char *path)
+
+   Reads a UTF8 encoded file and returns an allocated pointer to the
+   string.
+
+----------------------
+
+.. function:: bool os_quick_write_utf8_file(const char *path, const char *str, size_t len, bool marker)
+
+   Writes a UTF8 encoded file.
+
+----------------------
+
+.. function:: bool os_quick_write_utf8_file_safe(const char *path, const char *str, size_t len, bool marker, const char *temp_ext, const char *backup_ext)
+
+   Writes a UTF8 encoded file with overwrite corruption prevention.
+
+----------------------
+
+.. function:: int64_t os_get_file_size(const char *path)
+
+   Gets a file's size.
+
+----------------------
+
+.. function:: int64_t os_get_free_space(const char *path)
+
+   Gets free space of a specific file path.
+
+---------------------
+
+
+String Conversion Functions
+---------------------------
+
+.. function:: size_t os_utf8_to_wcs(const char *str, size_t len, wchar_t *dst, size_t dst_size)
+
+   Converts a UTF8 string to a wide string.
+
+----------------------
+
+.. function:: size_t os_wcs_to_utf8(const wchar_t *str, size_t len, char *dst, size_t dst_size)
+
+   Converts a wide string to a UTF8 string.
+
+----------------------
+
+.. function:: size_t os_utf8_to_wcs_ptr(const char *str, size_t len, wchar_t **pstr)
+
+   Gets an bmalloc-allocated wide string converted from a UTF8 string.
+
+----------------------
+
+.. function:: size_t os_wcs_to_utf8_ptr(const wchar_t *str, size_t len, char **pstr)
+
+   Gets an bmalloc-allocated UTF8 string converted from a wide string.
+
+---------------------
+
+
+Number/String Conversion Functions
+----------------------------------
+
+.. function:: double os_strtod(const char *str)
+
+   Converts a string to a double.
+
+----------------------
+
+.. function:: int os_dtostr(double value, char *dst, size_t size)
+
+   Converts a double to a string.
+
+---------------------
+
+
+Dynamic Link Library Functions
+------------------------------
+
+These functions are roughly equivalent to dlopen/dlsym/dlclose.
+
+.. function:: void *os_dlopen(const char *path)
+
+   Opens a dynamic library.
+
+----------------------
+
+.. function:: void *os_dlsym(void *module, const char *func)
+
+   Returns a symbol from a dynamic library.
+
+----------------------
+
+.. function:: void os_dlclose(void *module)
+
+   Closes a dynamic library.
+
+---------------------
+
+
+CPU Usage Functions
+-------------------
+
+.. function:: os_cpu_usage_info_t *os_cpu_usage_info_start(void)
+
+   Creates a CPU usage information object.
+
+----------------------
+
+.. function:: double              os_cpu_usage_info_query(os_cpu_usage_info_t *info)
+
+   Queries the current CPU usage.
+
+----------------------
+
+.. function:: void                os_cpu_usage_info_destroy(os_cpu_usage_info_t *info)
+
+   Destroys a CPU usage information object.
+
+---------------------
+
+
+Sleep/Time Functions
+--------------------
+
+.. function:: bool os_sleepto_ns(uint64_t time_target)
+
+   Sleeps to a specific time with high precision, in nanoseconds.
+
+---------------------
+
+.. function:: void os_sleep_ms(uint32_t duration)
+
+   Sleeps for a specific number of milliseconds.
+
+---------------------
+
+.. function:: uint64_t os_gettime_ns(void)
+
+   Gets the current high-precision system time, in nanoseconds.
+
+---------------------
+
+Other Path/File Functions
+-------------------------
+
+.. function:: int os_get_config_path(char *dst, size_t size, const char *name)
+              char *os_get_config_path_ptr(const char *name)
+
+   Gets the user-specific application configuration data path.
+
+---------------------
+
+.. function:: int os_get_program_data_path(char *dst, size_t size, const char *name)
+              char *os_get_program_data_path_ptr(const char *name)
+
+   Gets the application configuration data path.
+
+---------------------
+
+.. function:: bool os_file_exists(const char *path)
+
+   Returns true if a file/directory exists, false otherwise.
+
+---------------------
+
+.. function:: size_t os_get_abs_path(const char *path, char *abspath, size_t size)
+              char *os_get_abs_path_ptr(const char *path)
+
+   Converts a relative path to an absolute path.
+
+---------------------
+
+.. function:: const char *os_get_path_extension(const char *path)
+
+   Returns the extension portion of a path string.
+
+---------------------
+
+.. type:: typedef struct os_dir os_dir_t
+
+   A directory object.
+
+.. type:: struct os_dirent
+
+   A directory entry record.
+
+.. member:: char os_dirent.d_name[256]
+
+   The directory entry name.
+
+.. member:: bool os_dirent.directory
+
+   *true* if the entry is a directory.
+
+---------------------
+
+.. function:: os_dir_t *os_opendir(const char *path)
+
+   Opens a directory object to enumerate files within the directory.
+
+---------------------
+
+.. function:: struct os_dirent *os_readdir(os_dir_t *dir)
+
+   Returns the linked list of directory entries.
+
+---------------------
+
+.. function:: void os_closedir(os_dir_t *dir)
+
+   Closes a directory object.
+
+---------------------
+
+.. type:: struct os_globent
+
+   A glob entry.
+   
+.. member:: char *os_globent.path
+
+   The full path to the glob entry.
+
+.. member:: bool os_globent.directory
+
+   *true* if the glob entry is a directory, *false* otherwise.
+
+.. type:: struct os_glob_info
+
+   A glob object.
+
+.. member:: size_t             os_glob_info.gl_pathc
+
+   Number of glob entries.
+
+.. member:: struct os_globent *os_glob_info.gl_pathv
+
+   Array of glob entries.
+
+.. type:: typedef struct os_glob_info os_glob_t
+
+---------------------
+
+.. function:: int os_glob(const char *pattern, int flags, os_glob_t **pglob)
+
+   Enumerates files based upon a glob string.
+
+---------------------
+
+.. function:: void os_globfree(os_glob_t *pglob)
+
+   Frees a glob object.
+
+---------------------
+
+.. function:: int os_unlink(const char *path)
+
+   Deletes a file.
+
+---------------------
+
+.. function:: int os_rmdir(const char *path)
+
+   Deletes a directory.
+
+---------------------
+
+.. function:: char *os_getcwd(char *path, size_t size)
+
+   Returns a new bmalloc-allocated path to the current working
+   directory.
+
+---------------------
+
+.. function:: int os_chdir(const char *path)
+
+   Changes the current working directory.
+
+---------------------
+
+.. function:: int os_mkdir(const char *path)
+
+   Creates a directory.
+
+---------------------
+
+.. function:: int os_mkdirs(const char *path)
+
+   Creates a full directory path if it doesn't exist.
+
+---------------------
+
+.. function:: int os_rename(const char *old_path, const char *new_path)
+
+   Renames a file.
+
+---------------------
+
+.. function:: int os_copyfile(const char *file_in, const char *file_out)
+
+   Copys a file.
+
+---------------------
+
+.. function:: int os_safe_replace(const char *target_path, const char *from_path, const char *backup_path)
+
+   Safely replaces a file.
+
+---------------------
+
+.. function:: char *os_generate_formatted_filename(const char *extension, bool space, const char *format)
+
+   Returns a new bmalloc-allocated filename generated from specific
+   formatting.
+
+---------------------
+
+
+Sleep-Inhibition Functions
+--------------------------
+
+These functions/types are used to inhibit the computer from going to
+sleep.
+
+.. type:: struct os_inhibit_info
+.. type:: typedef struct os_inhibit_info os_inhibit_t
+
+---------------------
+
+.. function:: os_inhibit_t *os_inhibit_sleep_create(const char *reason)
+
+   Creates a sleep inhibition object.
+
+---------------------
+
+.. function:: bool os_inhibit_sleep_set_active(os_inhibit_t *info, bool active)
+
+   Activates/deactivates a sleep inhibition object.
+
+---------------------
+
+.. function:: void os_inhibit_sleep_destroy(os_inhibit_t *info)
+
+   Destroys a sleep inhibition object.  If the sleep inhibition object
+   was active, it will be deactivated.
+
+---------------------
+
+
+Other Functions
+---------------
+
+.. function:: void os_breakpoint(void)
+
+   Triggers a debugger breakpoint (or crashes the program if no debugger
+   present).
+
+---------------------
+
+.. function:: int os_get_physical_cores(void)
+
+   Returns the number of physical cores available.
+
+---------------------
+
+.. function:: int os_get_logical_cores(void)
+
+   Returns the number of logical cores available.
+
+---------------------
+
+.. function:: uint64_t os_get_sys_free_size(void)
+
+   Returns the amount of memory available.
+
+---------------------
+
+.. type:: struct os_proc_memory_usage
+
+   Memory usage structure.
+
+.. member:: uint64_t os_proc_memory_usage.resident_size
+
+   Resident size.
+
+.. member:: uint64_t os_proc_memory_usage.virtual_size
+
+   Virtual size.
+
+.. type:: typedef struct os_proc_memory_usage os_proc_memory_usage_t
+
+---------------------
+
+.. function:: bool os_get_proc_memory_usage(os_proc_memory_usage_t *usage)
+
+   Gets memory usage of the current process.
+
+---------------------
+
+.. function:: uint64_t os_get_proc_resident_size(void)
+
+   Returns the resident memory size of the current process.
+
+---------------------
+
+.. function:: uint64_t os_get_proc_virtual_size(void)
+
+   Returns the virtual memory size of the current process.

docs/sphinx/reference-libobs-util-profiler.rst

@@ -0,0 +1,327 @@
+Profiler
+========
+
+The profiler is used to get information about program performance and
+efficiency.
+
+.. type:: typedef struct profiler_snapshot profiler_snapshot_t
+.. type:: typedef struct profiler_snapshot_entry profiler_snapshot_entry_t
+.. type:: typedef struct profiler_name_store profiler_name_store_t
+.. type:: typedef struct profiler_time_entry profiler_time_entry_t
+
+.. code:: cpp
+
+   #include <util/profiler.h>
+
+
+Profiler Structures
+-------------------
+
+.. type:: struct profiler_time_entry
+.. member:: uint64_t profiler_time_entry.time_delta
+.. member:: uint64_t profiler_time_entry.count
+
+
+Profiler Control Functions
+--------------------------
+
+.. function:: void profiler_start(void)
+
+   Starts the profiler.
+
+----------------------
+
+.. function:: void profiler_stop(void)
+
+   Stops the profiler.
+
+----------------------
+
+.. function:: void profiler_print(profiler_snapshot_t *snap)
+
+   Creates a profiler snapshot and saves it within *snap*.
+
+   :param snap: A profiler snapshot object
+
+----------------------
+
+.. function:: void profiler_print_time_between_calls(profiler_snapshot_t *snap)
+
+   Creates a profiler snapshot of time between calls and saves it within
+   *snap*.
+
+   :param snap: A profiler snapshot object
+
+----------------------
+
+.. function:: void profiler_free(void)
+
+   Frees the profiler.
+
+----------------------
+
+
+Profiling Functions
+-------------------
+
+.. function:: void profile_register_root(const char *name, uint64_t expected_time_between_calls)
+
+   Registers a root profile node.
+
+   :param name:                        Name of the root profile node
+   :param expected_time_between_calls: The expected time between calls
+                                       of the profile root node, or 0 if
+                                       none.
+
+----------------------
+
+.. function:: void profile_start(const char *name)
+
+   Starts a profile node.  This profile node will be a child of the last
+   node that was started.
+
+   :param name: Name of the profile node
+
+----------------------
+
+.. function:: void profile_end(const char *name)
+
+   :param name: Name of the profile node
+
+----------------------
+
+.. function:: void profile_reenable_thread(void)
+
+   Because :c:func:`profiler_start()` can be called in a different
+   thread than the current thread, this is used to specify a point where
+   it's safe to re-enable profiling in the calling thread.  Call this
+   when you have looped root profile nodes and need to specify a safe
+   point where the root profile node isn't active and the profiler can
+   start up in the current thread again.
+
+----------------------
+
+
+Profiler Name Storage Functions
+-------------------------------
+
+.. function:: profiler_name_store_t *profiler_name_store_create(void)
+
+   Creates a profiler name storage object.
+
+   :return: Profiler name store object
+
+----------------------
+
+.. function:: void profiler_name_store_free(profiler_name_store_t *store)
+
+   Frees a profiler name storage object.
+
+   :param store: Profiler name storage object
+
+----------------------
+
+.. function:: const char *profile_store_name(profiler_name_store_t *store, const char *format, ...)
+
+   Creates a formatted string and stores it within a profiler name
+   storage object.
+
+   :param store:  Profiler name storage object
+   :param format: Formatted string
+   :return:       The string created from format specifications
+
+----------------------
+
+
+Profiler Data Access Functions
+------------------------------
+
+.. function:: profiler_snapshot_t *profile_snapshot_create(void)
+
+   Creates a profile snapshot.  Profiler snapshots are used to obtain
+   data about how the active profiles performed.
+
+   :return: A profiler snapshot object
+
+----------------------
+
+.. function:: void profile_snapshot_free(profiler_snapshot_t *snap)
+
+   Frees a profiler snapshot object.
+
+   :param snap: A profiler snapshot
+
+----------------------
+
+.. function:: bool profiler_snapshot_dump_csv(const profiler_snapshot_t *snap, const char *filename)
+
+   Creates a CSV file of the profiler snapshot.
+
+   :param snap:     A profiler snapshot
+   :param filename: The path to the CSV file to save
+   :return:         *true* if successfuly written, *false* otherwise
+
+----------------------
+
+.. function:: bool profiler_snapshot_dump_csv_gz(const profiler_snapshot_t *snap, const char *filename)
+
+   Creates a gzipped CSV file of the profiler snapshot.
+
+   :param snap:     A profiler snapshot
+   :param filename: The path to the gzipped CSV file to save
+   :return:         *true* if successfuly written, *false* otherwise
+
+----------------------
+
+.. function:: size_t profiler_snapshot_num_roots(profiler_snapshot_t *snap)
+
+   :param snap: A profiler snapshot
+   :return:     Number of root profiler nodes in the snapshot
+
+----------------------
+
+.. type:: typedef bool (*profiler_entry_enum_func)(void *context, profiler_snapshot_entry_t *entry)
+
+   Profiler snapshot entry numeration callback
+
+   :param context: Private data passed to this callback
+   :param entry:   Profiler snapshot entry
+   :return:        *true* to continue enumeration, *false* otherwise
+
+----------------------
+
+.. function:: void profiler_snapshot_enumerate_roots(profiler_snapshot_t *snap, profiler_entry_enum_func func, void *context)
+
+   Enumerates root profile nodes.
+
+   :param snap:    A profiler snapshot
+   :param func:    Enumeration callback
+   :param context: Private data to pass to the callback
+
+----------------------
+
+.. type:: typedef bool (*profiler_name_filter_func)(void *data, const char *name, bool *remove)
+
+   Callback used to determine what profile nodes are removed/filtered.
+
+   :param data:    Private data passed to this callback
+   :param name:    Profile node name to be filtered
+   :param remove:  Used to determined whether the node should be removed
+                   or not
+   :return:        *true* to continue enumeration, *false* otherwise
+
+----------------------
+
+.. function:: void profiler_snapshot_filter_roots(profiler_snapshot_t *snap, profiler_name_filter_func func, void *data)
+
+   Removes/filters profile roots based upon their names.
+
+   :param snap: A profiler snapshot
+   :param func: Enumeration callback to filter with
+   :param data: Private data to pass to the callback
+
+----------------------
+
+.. function:: size_t profiler_snapshot_num_children(profiler_snapshot_entry_t *entry)
+
+   :param entry: A profiler snapshot entry
+   :return:      Number of children for the entry
+
+----------------------
+
+.. function:: void profiler_snapshot_enumerate_children(profiler_snapshot_entry_t *entry, profiler_entry_enum_func func, void *context)
+
+   Enumerates child entries of a profiler snapshot entry.
+
+   :param entry:   A profiler snapshot entry
+   :param func:    Enumeration callback
+   :param context: Private data passed to the callback
+
+----------------------
+
+.. function:: const char *profiler_snapshot_entry_name(profiler_snapshot_entry_t *entry)
+
+   :param entry: A profiler snapshot entry
+   :return:      The name of the profiler snapshot entry
+
+----------------------
+
+.. function:: profiler_time_entries_t *profiler_snapshot_entry_times(profiler_snapshot_entry_t *entry)
+
+   Gets the time entries for a snapshot entry.
+
+   :param entry: A profiler snapshot entry
+   :return:      An array of profiler time entries
+
+----------------------
+
+.. function:: uint64_t profiler_snapshot_entry_min_time(profiler_snapshot_entry_t *entry)
+
+   Gets the minimum time for a profiler snapshot entry.
+
+   :param entry: A profiler snapshot entry
+   :return:      The minimum time value for the snapshot entry
+
+----------------------
+
+.. function:: uint64_t profiler_snapshot_entry_max_time(profiler_snapshot_entry_t *entry)
+
+   Gets the maximum time for a profiler snapshot entry.
+
+   :param entry: A profiler snapshot entry
+   :return:      The maximum time value for the snapshot entry
+
+----------------------
+
+.. function:: uint64_t profiler_snapshot_entry_overall_count(profiler_snapshot_entry_t *entry)
+
+   Gets the overall count for a profiler snapshot entry.
+
+   :param entry: A profiler snapshot entry
+   :return:      The overall count value for the snapshot entry
+
+----------------------
+
+.. function:: profiler_time_entries_t *profiler_snapshot_entry_times_between_calls(profiler_snapshot_entry_t *entry)
+
+   Gets an array of time between calls for a profiler snapshot entry.
+
+   :param entry: A profiler snapshot entry
+   :return:      An array of profiler time entries
+
+----------------------
+
+.. function:: uint64_t profiler_snapshot_entry_expected_time_between_calls(profiler_snapshot_entry_t *entry)
+
+   Gets the expected time between calls for a profiler snapshot entry.
+
+   :param entry: A profiler snapshot entry
+   :return:      The expected time between calls for the snapshot entry,
+                 or 0 if not set
+
+----------------------
+
+.. function:: uint64_t profiler_snapshot_entry_min_time_between_calls(profiler_snapshot_entry_t *entry)
+
+   Gets the minimum time seen between calls for a profiler snapshot entry.
+
+   :param entry: A profiler snapshot entry
+   :return:      The minimum time seen between calls for the snapshot entry
+
+----------------------
+
+.. function:: uint64_t profiler_snapshot_entry_max_time_between_calls(profiler_snapshot_entry_t *entry)
+
+   Gets the maximum time seen between calls for a profiler snapshot entry.
+
+   :param entry: A profiler snapshot entry
+   :return:      The maximum time seen between calls for the snapshot entry
+
+----------------------
+
+.. function:: uint64_t profiler_snapshot_entry_overall_between_calls_count(profiler_snapshot_entry_t *entry)
+
+   Gets the overall time between calls for a profiler snapshot entry.
+
+   :param entry: A profiler snapshot entry
+   :return:      The overall time between calls for the snapshot entry

docs/sphinx/reference-libobs-util-serializers.rst

@@ -0,0 +1,171 @@
+Serializer
+==========
+
+General programmable serialization functions.  (A shared interface to
+various reading/writing to/from different inputs/outputs)
+
+.. code:: cpp
+
+   #include <serializer.h>
+
+Serializer Structure (struct serializer)
+----------------------------------------
+
+.. type:: struct serializer
+.. member:: void     *serializer.data
+.. member:: size_t   (*serializer.read)(void *, void *, size_t)
+.. member:: size_t   (*serializer.write)(void *, const void *, size_t)
+.. member:: int64_t  (*serializer.seek)(void *, int64_t, enum serialize_seek_type)
+.. member:: int64_t  (*serializer.get_pos)(void *)
+
+Serializer Inline Functions
+---------------------------
+
+.. function:: size_t s_read(struct serializer *s, void *data, size_t size)
+
+---------------------
+
+.. function:: size_t s_write(struct serializer *s, const void *data, size_t size)
+
+---------------------
+
+.. function:: size_t serialize(struct serializer *s, void *data, size_t len)
+
+---------------------
+
+.. function:: int64_t serializer_seek(struct serializer *s, int64_t offset, enum serialize_seek_type seek_type)
+
+---------------------
+
+.. function:: int64_t serializer_get_pos(struct serializer *s)
+
+---------------------
+
+.. function:: void s_w8(struct serializer *s, uint8_t u8)
+
+---------------------
+
+.. function:: void s_wl16(struct serializer *s, uint16_t u16)
+
+---------------------
+
+.. function:: void s_wl32(struct serializer *s, uint32_t u32)
+
+---------------------
+
+.. function:: void s_wl64(struct serializer *s, uint64_t u64)
+
+---------------------
+
+.. function:: void s_wlf(struct serializer *s, float f)
+
+---------------------
+
+.. function:: void s_wld(struct serializer *s, double d)
+
+---------------------
+
+.. function:: void s_wb16(struct serializer *s, uint16_t u16)
+
+---------------------
+
+.. function:: void s_wb24(struct serializer *s, uint32_t u24)
+
+---------------------
+
+.. function:: void s_wb32(struct serializer *s, uint32_t u32)
+
+---------------------
+
+.. function:: void s_wb64(struct serializer *s, uint64_t u64)
+
+---------------------
+
+.. function:: void s_wbf(struct serializer *s, float f)
+
+---------------------
+
+.. function:: void s_wbd(struct serializer *s, double d)
+
+---------------------
+
+
+Array Output Serializer
+=======================
+
+Provides an output serializer used with dynamic arrays.
+
+.. code:: cpp
+
+   #include <util/array-serializer.h>
+
+Array Output Serializer Structure (struct array_output_data)
+------------------------------------------------------------
+
+.. type:: struct array_output_data
+
+.. member:: DARRAY(uint8_t) array_output_data.bytes
+
+Array Output Serializer Functions
+---------------------------------
+
+.. function:: void array_output_serializer_init(struct serializer *s, struct array_output_data *data)
+
+---------------------
+
+.. function:: void array_output_serializer_free(struct array_output_data *data)
+
+---------------------
+
+
+File Input/Output Serializers
+=============================
+
+Provides file reading/writing serializers.
+
+.. code:: cpp
+
+   #include <util/file-serializer.h>
+
+
+File Input Serializer Functions
+-------------------------------
+
+.. function:: bool file_input_serializer_init(struct serializer *s, const char *path)
+
+   Initializes a file input serializer.
+
+   :return:     *true* if file opened successfully, *false* otherwise
+
+---------------------
+
+.. function:: void file_input_serializer_free(struct serializer *s)
+
+   Frees a file input serializer.
+
+---------------------
+
+
+File Output Serializer Functions
+--------------------------------
+
+.. function:: bool file_output_serializer_init(struct serializer *s, const char *path)
+
+   Initializes a file output serializer.
+
+   :return:     *true* if file created successfully, *false* otherwise
+
+---------------------
+
+.. function:: bool file_output_serializer_init_safe(struct serializer *s, const char *path, const char *temp_ext)
+
+   Initializes and safely writes to a temporary file (determined by the
+   temporary extension) until freed.
+
+   :return:     *true* if file created successfully, *false* otherwise
+
+---------------------
+
+.. function:: void file_output_serializer_free(struct serializer *s)
+
+   Frees the file output serializer and saves the file.

docs/sphinx/reference-libobs-util-text-lookup.rst

@@ -0,0 +1,56 @@
+Text Lookup Interface
+=====================
+
+Used for storing and looking up localized strings.  Uses an ini-file
+like file format for localization lookup.
+
+.. type:: struct text_lookup lookup_t
+
+.. code:: cpp
+
+   #include <util/text-lookup.h>
+
+
+Text Lookup Functions
+---------------------
+
+.. function:: lookup_t *text_lookup_create(const char *path)
+
+   Creates a text lookup object from a text lookup file.
+
+   :param path: Path to the localization file
+   :return:     New lookup object, or *NULL* if an error occurred
+
+---------------------
+
+.. function:: bool text_lookup_add(lookup_t *lookup, const char *path)
+
+   Adds text lookup from a text lookup file and replaces any values.
+   For example, you would load a default fallback language such as
+   english with :c:func:`text_lookup_create()`, and then call this
+   function to load the actual desired language in case the desired
+   language isn't fully translated.
+
+   :param lookup: Lookup object
+   :param path:   Path to the localization file
+   :return:       *true* if successful, *false* otherwise
+
+---------------------
+
+.. function:: void text_lookup_destroy(lookup_t *lookup)
+
+   Destroys a text lookup object.
+
+   :param lookup: Lookup object
+
+---------------------
+
+.. function:: bool text_lookup_getstr(lookup_t *lookup, const char *lookup_val, const char **out)
+
+   Gets a localized text string.
+
+   :param lookup:     Lookup object
+   :param lookup_val: Value to look up
+   :param out:        Pointer that receives the translated string
+                      pointer
+   :return:           *true* if the value exists, *false* otherwise

docs/sphinx/reference-libobs-util-threading.rst

@@ -0,0 +1,193 @@
+Threading
+=========
+
+Libobs provides a number of helper functions/types specifically for
+threading.  The threading header will additionally provide access to
+pthread functions even on windows.
+
+.. code:: cpp
+
+   #include <util/threading.h>
+
+
+Threading Types
+---------------
+
+.. type:: os_event_t
+.. type:: os_sem_t
+
+
+General Thread Functions
+------------------------
+
+.. function:: void os_set_thread_name(const char *name)
+
+   Sets the name of the current thread.
+
+----------------------
+
+
+Event Functions
+---------------
+
+.. function:: int  os_event_init(os_event_t **event, enum os_event_type type)
+
+   Creates an event object.
+
+   :param event: Pointer that receives a pointer to a new event object
+   :param type:  Can be one of the following values:
+
+                 - OS_EVENT_TYPE_AUTO - Automatically resets when
+                   signaled
+                 - OS_EVENT_TYPE_MANUAL - Stays signaled until the
+                   :c:func:`os_event_reset()` function is called
+
+   :return:      0 if successful, negative otherwise
+
+----------------------
+
+.. function:: void os_event_destroy(os_event_t *event)
+
+   Destroys an event.
+
+   :param event: An event object
+
+----------------------
+
+.. function:: int  os_event_wait(os_event_t *event)
+
+   Waits for an event to signal.
+
+   :param event: An event object
+   :return:      0 if successful, negative otherwise
+
+----------------------
+
+.. function:: int  os_event_timedwait(os_event_t *event, unsigned long milliseconds)
+
+   Waits a specific duration for an event to signal.
+
+   :param event:        An event object
+   :param milliseconds: Milliseconds to wait
+   :return:             Can be one of the following values:
+   
+                        - 0 - successful
+                        - ETIMEDOUT - Timed out
+                        - EINVAL - An unexpected error occured
+
+----------------------
+
+.. function:: int  os_event_try(os_event_t *event)
+
+   Checks for a signaled state without waiting.
+
+   :param event: An event object
+   :return:             Can be one of the following values:
+   
+                        - 0 - successful
+                        - EAGAIN - The event is not signaled
+                        - EINVAL - An unexpected error occured
+
+----------------------
+
+.. function:: int  os_event_signal(os_event_t *event)
+
+   Signals the event.
+
+   :param event: An event object
+   :return:      0 if successful, negative otherwise
+
+----------------------
+
+.. function:: void os_event_reset(os_event_t *event)
+
+   Resets the signaled state of the event.
+
+   :param event: An event object
+
+----------------------
+
+
+Semaphore Functions
+-------------------
+
+.. function:: int  os_sem_init(os_sem_t **sem, int value)
+
+   Creates a semaphore object.
+
+   :param sem:   Pointer that receives a pointer to the semaphore object
+   :param value: Initial value of the semaphore
+   :return:      0 if successful, negative otherwise
+
+----------------------
+
+.. function:: void os_sem_destroy(os_sem_t *sem)
+
+   Destroys a sempahore object.
+
+   :param sem:   Semaphore object
+
+----------------------
+
+.. function:: int  os_sem_post(os_sem_t *sem)
+
+   Increments the semaphore.
+
+   :param sem:   Semaphore object
+   :return:      0 if successful, negative otherwise
+
+----------------------
+
+.. function:: int  os_sem_wait(os_sem_t *sem)
+
+   Decrements the semphore or waits until the semaphore has been
+   incremented.
+
+   :param sem:   Semaphore object
+   :return:      0 if successful, negative otherwise
+
+---------------------
+
+
+Atomic Inline Functions
+-----------------------
+
+.. function:: long os_atomic_inc_long(volatile long *val)
+
+   Increments a long variable atomically.
+
+---------------------
+
+.. function:: long os_atomic_dec_long(volatile long *val)
+
+   Decrements a long variable atomically.
+
+---------------------
+
+.. function:: long os_atomic_set_long(volatile long *ptr, long val)
+
+   Sets the value of a long variable atomically.
+
+---------------------
+
+.. function:: long os_atomic_load_long(const volatile long *ptr)
+
+   Gets the value of a long variable atomically.
+
+---------------------
+
+.. function:: bool os_atomic_compare_swap_long(volatile long *val, long old_val, long new_val)
+
+   Swaps the value of a long variable atomically if its value matches.
+
+---------------------
+
+.. function:: bool os_atomic_set_bool(volatile bool *ptr, bool val)
+
+   Sets the value of a boolean variable atomically.
+
+---------------------
+
+.. function:: bool os_atomic_load_bool(const volatile bool *ptr)
+
+   Gets the value of a boolean variable atomically.

docs/sphinx/reference-libobs-util.rst

@@ -0,0 +1,17 @@
+Platform/Utility API Reference (libobs/util)
+============================================
+
+.. toctree::
+   :maxdepth: 2
+
+   reference-libobs-util-base
+   reference-libobs-util-bmem
+   reference-libobs-util-circlebuf
+   reference-libobs-util-config-file
+   reference-libobs-util-darray
+   reference-libobs-util-dstr
+   reference-libobs-util-platform
+   reference-libobs-util-profiler
+   reference-libobs-util-serializers
+   reference-libobs-util-text-lookup
+   reference-libobs-util-threading

docs/sphinx/reference-modules.rst

@@ -0,0 +1,310 @@
+Module API Reference
+====================
+
+Modules add custom functionality to libobs: typically
+:ref:`plugins_sources`, :ref:`plugins_outputs`, :ref:`plugins_encoders`,
+and :ref:`plugins_services`.
+
+.. type:: obs_module_t
+
+   A module object (not reference counted).
+
+.. code:: cpp
+
+   #include <obs-module.h>
+
+
+Module Macros
+-------------
+
+These macros are used within custom plugin modules.
+
+.. function:: OBS_DECLARE_MODULE()
+
+   Declares a libobs module.  Exports important core module functions
+   related to the module itself, OBS version, etc.
+
+---------------------
+
+.. function:: OBS_MODULE_USE_DEFAULT_LOCALE(module_name, default_locale)
+
+   Helper macro that uses the standard ini file format for localization.
+   Automatically initializes and destroys localization data, and
+   automatically provides module externs such as
+   :c:func:`obs_module_text()` to be able to get a localized string with
+   little effort.
+
+---------------------
+
+Module Exports
+--------------
+
+These are functions that plugin modules can optionally export in order
+to communicate with libobs and front-ends.
+
+.. function:: bool obs_module_load(void)
+
+   Required: Called when the module is loaded.  Implement this function
+   to load all the sources/encoders/outputs/services for your module, or
+   anything else that may need loading.
+  
+   :return:          Return true to continue loading the module, otherwise
+                     false to indicate failure and unload the module
+
+---------------------
+
+.. function:: void obs_module_unload(void)
+
+   Optional: Called when the module is unloaded.
+
+---------------------
+
+.. function:: void obs_module_post_load(void)
+
+   Optional: Called when all modules have finished loading.
+
+---------------------
+
+.. function:: void obs_module_set_locale(const char *locale)
+
+   Called to set the locale language and load the locale data for the
+   module.
+
+---------------------
+
+.. function:: void obs_module_free_locale(void)
+
+   Called on module destruction to free locale data.
+
+---------------------
+
+.. function:: const char *obs_module_name(void)
+
+   (Optional)
+   
+   :return: The full name of the module
+
+---------------------
+
+.. function:: const char *obs_module_description(void)
+
+   (Optional)
+
+   :return: A description of the module
+
+---------------------
+
+
+Module Externs
+--------------
+
+These functions are externs that are useable throughout the module.
+
+.. function:: const char *obs_module_text(const char *lookup_string)
+
+   :return: A localized string
+
+---------------------
+
+.. function:: bool obs_module_get_string(const char *lookup_string, const char **translated_string)
+
+   Helper function for looking up locale.
+   
+   :return: *true* if text found, otherwise *false*
+
+---------------------
+
+.. function:: obs_module_t *obs_current_module(void)
+
+   :return: The current module
+
+---------------------
+
+.. function:: char *obs_module_file(const char *file)
+
+   Returns the location to a module data file associated with the
+   current module.  Free with :c:func:`bfree()` when complete.
+   
+   Equivalent to:
+
+.. code:: cpp
+
+      obs_find_module_file(obs_current_module(), file);
+
+---------------------
+
+.. function:: char *obs_module_config_path(const char *file)
+
+   Returns the location to a module config file associated with the
+   current module.  Free with :c:func:`bfree()` when complete.  Will
+   return NULL if configuration directory is not set.
+   
+   Equivalent to:
+
+.. code:: cpp
+
+      obs_module_get_config_path(obs_current_module(), file);
+
+---------------------
+
+
+Frontend Module Functions
+--------------------------
+
+These are functions used by frontends to load and get information about
+plugin modules.
+
+.. function:: int obs_open_module(obs_module_t **module, const char *path, const char *data_path)
+
+   Opens a plugin module directly from a specific path.
+  
+   If the module already exists then the function will return successful, and
+   the module parameter will be given the pointer to the existing
+   module.
+  
+   This does not initialize the module, it only loads the module image.  To
+   initialize the module, call :c:func:`obs_init_module()`.
+  
+   :param  module:    The pointer to the created module
+   :param  path:      Specifies the path to the module library file.  If the
+                      extension is not specified, it will use the extension
+                      appropriate to the operating system
+   :param  data_path: Specifies the path to the directory where the module's
+                      data files are stored (or *NULL* if none)
+   :returns:          | MODULE_SUCCESS          - Successful
+                      | MODULE_ERROR            - A generic error occurred
+                      | MODULE_FILE_NOT_FOUND   - The module was not found
+                      | MODULE_MISSING_EXPORTS  - Required exports are missing
+                      | MODULE_INCOMPATIBLE_VER - Incompatible version
+
+---------------------
+
+.. function:: bool obs_init_module(obs_module_t *module)
+
+   Initializes the module, which calls its obs_module_load export.
+   
+   :return: *true* if the module was loaded successfully
+
+---------------------
+
+.. function:: void obs_log_loaded_modules(void)
+
+   Logs loaded modules.
+
+---------------------
+
+.. function:: const char *obs_get_module_file_name(obs_module_t *module)
+
+   :return: The module file name
+
+---------------------
+
+.. function:: const char *obs_get_module_name(obs_module_t *module)
+
+   :return: The module full name (or *NULL* if none)
+
+---------------------
+
+.. function:: void obs_get_module_author(obs_module_t *module)
+
+   :return: The module author(s)
+
+---------------------
+
+.. function:: const char *obs_get_module_description(obs_module_t *module)
+
+   :return: The module description
+
+---------------------
+
+.. function:: const char *obs_get_module_binary_path(obs_module_t *module)
+
+   :return: The module binary path
+
+---------------------
+
+.. function:: const char *obs_get_module_data_path(obs_module_t *module)
+
+   :return: The module data path
+
+---------------------
+
+.. function:: void obs_add_module_path(const char *bin, const char *data)
+
+   Adds a module search path to be used with obs_find_modules.  If the search
+   path strings contain %module%, that text will be replaced with the module
+   name when used.
+  
+   :param  bin:  Specifies the module's binary directory search path
+   :param  data: Specifies the module's data directory search path
+
+---------------------
+
+.. function:: void obs_load_all_modules(void)
+
+   Automatically loads all modules from module paths (convenience function).
+
+---------------------
+
+.. function:: void obs_post_load_modules(void)
+
+   Notifies modules that all modules have been loaded.
+
+---------------------
+
+.. function:: void obs_find_modules(obs_find_module_callback_t callback, void *param)
+
+   Finds all modules within the search paths added by
+   :c:func:`obs_add_module_path()`.
+
+   Relevant data types used with this function:
+
+.. code:: cpp
+
+   struct obs_module_info {
+           const char *bin_path;
+           const char *data_path;
+   };
+
+   typedef void (*obs_find_module_callback_t)(void *param,
+                   const struct obs_module_info *info);
+
+---------------------
+
+.. function:: void obs_enum_modules(obs_enum_module_callback_t callback, void *param)
+
+   Enumerates all loaded modules.
+
+   Relevant data types used with this function:
+
+.. code:: cpp
+
+   typedef void (*obs_enum_module_callback_t)(void *param, obs_module_t *module);
+
+---------------------
+
+.. function:: char *obs_find_module_file(obs_module_t *module, const char *file)
+
+   Returns the location of a plugin module data file.
+  
+   Note:   Modules should use obs_module_file function defined in obs-module.h
+           as a more elegant means of getting their files without having to
+           specify the module parameter.
+  
+   :param  module: The module associated with the file to locate
+   :param  file:   The file to locate
+   :return:        Path string, or NULL if not found.  Use bfree to free string
+
+---------------------
+
+.. function:: char *obs_module_get_config_path(obs_module_t *module, const char *file)
+
+   Returns the path of a plugin module config file (whether it exists or not).
+  
+   Note:   Modules should use obs_module_config_path function defined in
+           obs-module.h as a more elegant means of getting their files without
+           having to specify the module parameter.
+  
+   :param  module: The module associated with the path
+   :param  file:   The file to get a path to
+   :return:        Path string, or NULL if not found.  Use bfree to free string

docs/sphinx/reference-outputs.rst

@@ -0,0 +1,778 @@
+Output API Reference (obs_output_t)
+===================================
+
+Outputs allow the ability to output the currently rendering audio/video.
+Streaming and recording are two common examples of outputs, but not the
+only types of outputs.  Outputs can receive the raw data or receive
+encoded data.  The `libobs/obs-output.h`_ file is the dedicated header
+for implementing outputs
+
+.. type:: obs_output_t
+
+   A reference-counted output object.
+
+.. type:: obs_weak_output_t
+
+   A weak reference to an output object.
+
+.. code:: cpp
+
+   #include <obs.h>
+
+
+Output Definition Structure (obs_output_info)
+---------------------------------------------
+
+.. type:: struct obs_output_info
+
+   Output definition structure.
+
+.. member:: const char *obs_output_info.id
+
+   Unique string identifier for the source (required).
+
+.. member:: uint32_t obs_output_info.flags
+
+   Output capability flags (required).
+
+   (Author's note: This should be renamed to "capability_flags")
+
+   A bitwise OR combination of one or more of the following values:
+
+   - **OBS_OUTPUT_VIDEO** - Can output video.
+
+   - **OBS_OUTPUT_AUDIO** - Can output audio.
+
+   - **OBS_OUTPUT_AV** - Combines OBS_OUTPUT_VIDEO and OBS_OUTPUT_AUDIO.
+
+   - **OBS_OUTPUT_ENCODED** - Output is encoded.
+
+     When this capability flag is used, the output must have encoders
+     assigned to it via the :c:func:`obs_output_set_video_encoder()`
+     and/or :c:func:`obs_output_set_audio_encoder()` functions in order
+     to be started.
+
+   - **OBS_OUTPUT_SERVICE** - Output requires a service object.
+
+     When this capability flag is used, the output must have a service
+     assigned to it via the :c:func:`obs_output_set_service()` function
+     in order to be started.
+
+     This is usually used with live streaming outputs that stream to
+     specific services.
+
+   - **OBS_OUTPUT_MULTI_TRACK** - Output supports multiple audio tracks.
+
+     When this capability flag is used, specifies that this output
+     supports multiple encoded audio tracks simultaneously.
+
+.. member:: const char *(*obs_output_info.get_name)(void *type_data)
+
+   Get the translated name of the output type.
+
+   :param  type_data:  The type_data variable of this structure
+   :return:            The translated name of the output type
+
+.. member:: void *(*obs_output_info.create)(obs_data_t *settings, obs_output_t *output)
+
+   Creates the implementation data for the output.
+
+   :param  settings: Settings to initialize the output with
+   :param  output:   Output that this data is associated with
+   :return:          The implementation data associated with this output
+
+.. member:: void (*obs_output_info.destroy)(void *data)
+
+   Destroys the implementation data for the output.
+
+.. member:: bool (*obs_output_info.start)(void *data)
+
+   Starts the output.  If needed, this function can spawn a thread,
+   return *true* immediately, and then signal for failure later.
+
+   :return: *true* if successful or deferring to a signal to indicate
+            failure, *false* on failure to start
+
+.. member:: void (*obs_output_info.stop)(void *data, uint64_t ts)
+
+   Requests an output to stop at a specified time.  The *ts* parameter
+   indicates when the stop should occur.  Output will actually stop when
+   either the :c:func:`obs_output_end_data_capture()` or
+   :c:func:`obs_output_signal_stop()` functions are called.  If *ts* is
+   0, an immediate stop was requested.
+
+   :param ts: The timestamp to stop.  If 0, the output should attempt to
+              stop immediately rather than wait for any more data to
+              process
+
+.. member:: void (*obs_output_info.raw_video)(void *data, struct video_data *frame)
+
+   This is called when the output receives raw video data.  Only applies
+   to outputs that are not encoded.
+
+   :param frame: The raw video frame
+
+.. member:: void (*obs_output_info.raw_audio)(void *data, struct audio_data *frames)
+
+   This is called when the output recieves raw audio data.  Only applies
+   to outputs that are not encoded.
+
+   :param frames: The raw audio frames
+
+.. member:: void (*obs_output_info.encoded_packet)(void *data, struct encoder_packet *packet)
+
+   This is called when the output receives encoded video/audio data.
+   Only applies to outputs that are encoded.  Packets will always be
+   given in monotonic timestamp order.
+
+   :param packet: The video or audio packet
+
+.. member:: void (*obs_output_info.update)(void *data, obs_data_t *settings)
+
+   Updates the settings for this output.
+
+   (Optional)
+
+   :param settings: New settings for this output
+
+.. member:: void (*obs_output_info.get_defaults)(obs_data_t *settings)
+            void (*obs_output_info.get_defaults2)(void *type_data, obs_data_t *settings)
+
+   Sets the default settings for this output.
+
+   (Optional)
+
+   :param  settings:  Default settings.  Call obs_data_set_default*
+                      functions on this object to set default setting
+                      values
+
+.. member:: obs_properties_t *(*obs_output_info.get_properties)(void *data)
+            obs_properties_t *(*obs_output_info.get_properties2)(void *data, void *type_data)
+
+   Gets the property information of this output.
+
+   (Optional)
+
+   :return: The properties of the output
+
+.. member:: void (*obs_output_info.pause)(void *data)
+
+   Pauses the output (if the output supports pausing).
+
+   (Author's note: This is currently unimplemented)
+
+   (Optional)
+
+.. member:: uint64_t (*obs_output_info.get_total_bytes)(void *data)
+
+   Returns the number of total bytes processed by this output.
+
+   (Optional)
+
+   :return: Total bytes processed by this output since it started
+
+.. member:: int (*obs_output_info.get_dropped_frames)(void *data)
+
+   Returns the number of dropped frames.
+
+   (Optional)
+
+   :return: Number of dropped frames due to network congestion by this
+            output since it started
+
+.. member:: void *obs_output_info.type_data
+            void (*obs_output_info.free_type_data)(void *type_data)
+
+   Private data associated with this entry.  Note that this is not the
+   same as the implementation data; this is used to differentiate
+   between two different types if the same callbacks are used for more
+   than one different type.
+
+   (Optional)
+
+.. member:: float (*obs_output_info.get_congestion)(void *data)
+
+   This function is used to indicate how currently congested the output
+   is.  Useful for visualizing how much data is backed up on streaming
+   outputs.
+
+   (Optional)
+
+   :return: Current congestion value (0.0f..1.0f)
+
+.. member:: int (*obs_output_info.get_connect_time_ms)(void *data)
+
+   This function is used to determine how many milliseconds it took to
+   connect to its current server.
+
+   (Optional)
+
+   :return: Milliseconds it took to connect to its current server
+
+.. member:: const char *obs_output_info.encoded_video_codecs
+            const char *obs_output_info.encoded_audio_codecs
+
+   This variable specifies which codecs are supported by an encoded
+   output, separated by semicolon.
+
+   (Optional, though recommended)
+
+.. _output_signal_handler_reference:
+
+Output Signals
+--------------
+
+**start** (ptr output)
+
+   Called when the output starts.
+
+**stop** (ptr output, int code)
+
+   Called when the output stops.
+
+   :Parameters: - **code** - Can be one of the following values:
+
+                  | OBS_OUTPUT_SUCCESS        - Successfuly stopped
+                  | OBS_OUTPUT_BAD_PATH       - The specified path was invalid
+                  | OBS_OUTPUT_CONNECT_FAILED - Failed to connect to a server
+                  | OBS_OUTPUT_INVALID_STREAM - Invalid stream path
+                  | OBS_OUTPUT_ERROR          - Generic error
+                  | OBS_OUTPUT_DISCONNECTED   - Unexpectedly disconnected
+                  | OBS_OUTPUT_UNSUPPORTED    - The settings, video/audio format, or codecs are unsupported by this output
+                  | OBS_OUTPUT_NO_SPACE       - Ran out of disk space
+
+**starting** (ptr output)
+
+   Called when the output is starting.
+
+**stopping** (ptr output)
+
+   Called when the output is stopping.
+
+**activate** (ptr output)
+
+   Called when the output activates (starts capturing data).
+
+**deactivate** (ptr output)
+
+   Called when the output deactivates (stops capturing data).
+
+**reconnect** (ptr output)
+
+   Called when the output is reconnecting.
+
+**reconnect_success** (ptr output)
+
+   Called when the output has successfully reconnected.
+
+General Output Functions
+------------------------
+
+.. function:: void obs_register_output(struct obs_output_info *info)
+
+   Registers an output type.  Typically used in
+   :c:func:`obs_module_load()` or in the program's initialization phase.
+
+---------------------
+
+.. function:: const char *obs_output_get_display_name(const char *id)
+
+   Calls the :c:member:`obs_output_info.get_name` callback to get the
+   translated display name of an output type.
+
+   :param    id:            The output type string identifier
+   :return:                 The translated display name of an output type
+
+---------------------
+
+.. function:: obs_output_t *obs_output_create(const char *id, const char *name, obs_data_t *settings, obs_data_t *hotkey_data)
+
+   Creates an output with the specified settings.
+  
+   The "output" context is used for anything related to outputting the
+   final video/audio mix (E.g. streaming or recording).  Use
+   obs_output_release to release it.
+
+   :param   id:             The output type string identifier
+   :param   name:           The desired name of the output.  If this is
+                            not unique, it will be made to be unique
+   :param   settings:       The settings for the output, or *NULL* if
+                            none
+   :param   hotkey_data:    Saved hotkey data for the output, or *NULL*
+                            if none
+   :return:                 A reference to the newly created output, or
+                            *NULL* if failed
+
+---------------------
+
+.. function:: void obs_output_addref(obs_output_t *output)
+              void obs_output_release(obs_output_t *output)
+
+   Adds/releases a reference to an output.  When the last reference is
+   released, the output is destroyed.
+
+---------------------
+
+.. function:: obs_weak_output_t *obs_output_get_weak_output(obs_output_t *output)
+              obs_output_t *obs_weak_output_get_output(obs_weak_output_t *weak)
+
+   These functions are used to get a weak reference from a strong output
+   reference, or a strong output reference from a weak reference.  If
+   the output is destroyed, *obs_weak_output_get_output* will return
+   *NULL*.
+
+---------------------
+
+.. function:: void obs_weak_output_addref(obs_weak_output_t *weak)
+              void obs_weak_output_release(obs_weak_output_t *weak)
+
+   Adds/releases a weak reference to an output.
+
+---------------------
+
+.. function:: const char *obs_output_get_name(const obs_output_t *output)
+
+   :return: The name of the output
+
+---------------------
+
+.. function:: bool obs_output_start(obs_output_t *output)
+
+   Starts the output.
+
+   :return: *true* if output successfuly started, *false* otherwise.  If
+            the output failed to start,
+            :c:func:`obs_output_get_last_error()` may contain a specific
+            error string related to the reason
+
+---------------------
+
+.. function:: void obs_output_stop(obs_output_t *output)
+
+   Requests the output to stop.  The output will wait until all data is
+   sent up until the time the call was made, then when the output has
+   successfully stopped, it will send the "stop" signal.  See
+   :ref:`output_signal_handler_reference` for more information on output
+   signals.
+
+---------------------
+
+.. function:: void obs_output_set_delay(obs_output_t *output, uint32_t delay_sec, uint32_t flags)
+
+   Sets the current output delay, in seconds (if the output supports delay)
+  
+   If delay is currently active, it will set the delay value, but will not
+   affect the current delay, it will only affect the next time the output is
+   activated.
+
+   :param delay_sec: Amount to delay the output, in seconds
+   :param flags:      | Can be 0 or a combination of one of the following values:
+                      | OBS_OUTPUT_DELAY_PRESERVE - On reconnection, start where it left of on reconnection.  Note however that this option will consume extra memory to continually increase delay while waiting to reconnect
+
+---------------------
+
+.. function:: uint32_t obs_output_get_delay(const obs_output_t *output)
+
+   Gets the currently set delay value, in seconds.
+
+---------------------
+
+.. function:: uint32_t obs_output_get_active_delay(const obs_output_t *output)
+
+   If delay is active, gets the currently active delay value, in
+   seconds.  The active delay can increase if the
+   OBS_OUTPUT_DELAY_PRESERVE flag was set when setting a delay.
+
+---------------------
+
+.. function:: void obs_output_force_stop(obs_output_t *output)
+
+   Attempts to get the output to stop immediately without waiting for
+   data to send.
+
+---------------------
+
+.. function:: bool obs_output_active(const obs_output_t *output)
+
+   :return: *true* if the output is currently active, *false* otherwise
+
+---------------------
+
+.. function:: obs_data_t *obs_output_defaults(const char *id)
+
+   :return: An incremented reference to the output's default settings
+
+---------------------
+
+.. function:: obs_properties_t *obs_output_properties(const obs_output_t *output)
+              obs_properties_t *obs_get_output_properties(const char *id)
+
+   Use these functions to get the properties of an output or output
+   type.  Properties are optionally used (if desired) to automatically
+   generate user interface widgets to allow users to update settings.
+
+   :return: The properties list for a specific existing output.  Free
+            with :c:func:`obs_properties_destroy()`
+
+---------------------
+
+.. function:: void obs_output_update(obs_output_t *output, obs_data_t *settings)
+
+   Updates the settings for this output context.
+
+---------------------
+
+.. function:: bool obs_output_can_pause(const obs_output_t *output)
+
+   :return: *true* if the output can be paused, *false* otherwise
+
+---------------------
+
+.. function:: void obs_output_pause(obs_output_t *output)
+
+   Pause an output (if supported by the output).
+
+   (Author's Note: Not yet implemented)
+
+---------------------
+
+.. function:: obs_data_t *obs_output_get_settings(const obs_output_t *output)
+
+   :return: An incremented reference to the output's settings
+
+---------------------
+
+.. function:: signal_handler_t *obs_output_get_signal_handler(const obs_output_t *output)
+
+   :return: The signal handler of the output
+
+---------------------
+
+.. function:: proc_handler_t *obs_output_get_proc_handler(const obs_output_t *output)
+
+   :return: The procedure handler of the output
+
+---------------------
+
+.. function:: void obs_output_set_media(obs_output_t *output, video_t *video, audio_t *audio)
+
+   Sets the current video/audio handlers for the output (typically
+   :c:func:`obs_get_video()` and :c:func:`obs_get_audio()`).  Only used
+   with raw outputs so they can catch the raw video/audio frames.
+
+---------------------
+
+.. function:: video_t *obs_output_video(const obs_output_t *output)
+              audio_t *obs_output_audio(const obs_output_t *output)
+
+   Gets the current video/audio handlers for the output.
+
+---------------------
+
+.. function:: void obs_output_set_mixer(obs_output_t *output, size_t mixer_idx)
+              size_t obs_output_get_mixer(const obs_output_t *output)
+
+   Sets/gets the current audio mixer for non-encoded outputs.
+
+---------------------
+
+.. function:: void obs_output_set_video_encoder(obs_output_t *output, obs_encoder_t *encoder)
+              void obs_output_set_audio_encoder(obs_output_t *output, obs_encoder_t *encoder, size_t idx)
+
+   Sets the video/audio encoders for an encoded output.
+
+   :param encoder: The video/audio encoder
+   :param idx:     The audio encoder index if the output supports
+                   multiple audio streams at once
+
+---------------------
+
+.. function:: obs_encoder_t *obs_output_get_video_encoder(const obs_output_t *output)
+              obs_encoder_t *obs_output_get_audio_encoder(const obs_output_t *output, size_t idx)
+
+   Gets the video/audio encoders for an encoded output.
+
+   :param idx:     The audio encoder index if the output supports
+                   multiple audio streams at once
+   :return:        The video/audio encoder.  The reference is not
+                   incremented
+
+---------------------
+
+.. function:: void obs_output_set_service(obs_output_t *output, obs_service_t *service)
+              obs_service_t *obs_output_get_service(const obs_output_t *output)
+
+   Sets/gets the service for outputs that require services (such as RTMP
+   outputs).  *obs_output_get_service* does not return an incremented
+   reference.
+
+---------------------
+
+.. function:: void obs_output_set_reconnect_settings(obs_output_t *output, int retry_count, int retry_sec);
+
+   Sets the auto-reconnect settings for outputs that support it.  The
+   retry time will double on each retry to prevent overloading services.
+
+   :param retry_count: Maximum retry count.  Set to 0 to disable
+                       reconnecting
+   :param retry_sec:   Starting retry wait duration, in seconds
+
+---------------------
+
+.. function:: uint64_t obs_output_get_total_bytes(const obs_output_t *output)
+
+   :return: Total bytes sent/processed
+
+---------------------
+
+.. function:: int obs_output_get_frames_dropped(const obs_output_t *output)
+
+   :return: Number of frames that were dropped due to network congestion
+
+---------------------
+
+.. function:: int obs_output_get_total_frames(const obs_output_t *output)
+
+   :return: Total frames sent/processed
+
+---------------------
+
+.. function:: void obs_output_set_preferred_size(obs_output_t *output, uint32_t width, uint32_t height)
+
+   Sets the preferred scaled resolution for this output.  Set width and height
+   to 0 to disable scaling.
+  
+   If this output uses an encoder, it will call obs_encoder_set_scaled_size on
+   the encoder before the stream is started.  If the encoder is already active,
+   then this function will trigger a warning and do nothing.
+
+---------------------
+
+.. function:: uint32_t obs_output_get_width(const obs_output_t *output)
+              uint32_t obs_output_get_height(const obs_output_t *output)
+
+   :return: The width/height of the output
+
+---------------------
+
+.. function:: float obs_output_get_congestion(obs_output_t *output)
+
+   :return: The congestion value.  This value is used to visualize the
+            current congestion of a network output.  For example, if
+            there is no congestion, the value will be 0.0f, if it's
+            fully congested, the value will be 1.0f
+
+---------------------
+
+.. function:: int obs_output_get_connect_time_ms(obs_output_t *output)
+
+   :return: How long the output took to connect to a server, in
+            milliseconds
+
+---------------------
+
+.. function:: bool obs_output_reconnecting(const obs_output_t *output)
+
+   :return: *true* if the output is currently reconnecting to a server,
+            *false* otherwise
+
+---------------------
+
+.. function:: const char *obs_output_get_supported_video_codecs(const obs_output_t *output)
+              const char *obs_output_get_supported_audio_codecs(const obs_output_t *output)
+
+   :return: Supported video/audio codecs of an encoded output, separated
+            by semicolen
+
+---------------------
+
+Functions used by outputs
+-------------------------
+
+.. function:: void obs_output_set_last_error(obs_output_t *output, const char *message)
+              const char *obs_output_get_last_error(obs_output_t *output)
+
+   Sets/gets the translated error message that is presented to a user in
+   case of disconnection, inability to connect, etc.
+
+---------------------
+
+.. function:: void obs_output_set_video_conversion(obs_output_t *output, const struct video_scale_info *conversion)
+
+   Optionally sets the video conversion information.  Only used by raw
+   outputs.
+
+   Relevant data types used with this function:
+
+.. code:: cpp
+
+   enum video_format {
+           VIDEO_FORMAT_NONE,
+   
+           /* planar 420 format */
+           VIDEO_FORMAT_I420, /* three-plane */
+           VIDEO_FORMAT_NV12, /* two-plane, luma and packed chroma */
+   
+           /* packed 422 formats */
+           VIDEO_FORMAT_YVYU,
+           VIDEO_FORMAT_YUY2, /* YUYV */
+           VIDEO_FORMAT_UYVY,
+   
+           /* packed uncompressed formats */
+           VIDEO_FORMAT_RGBA,
+           VIDEO_FORMAT_BGRA,
+           VIDEO_FORMAT_BGRX,
+           VIDEO_FORMAT_Y800, /* grayscale */
+   
+           /* planar 4:4:4 */
+           VIDEO_FORMAT_I444,
+   };
+   
+   enum video_colorspace {
+           VIDEO_CS_DEFAULT,
+           VIDEO_CS_601,
+           VIDEO_CS_709,
+   };
+   
+   enum video_range_type {
+           VIDEO_RANGE_DEFAULT,
+           VIDEO_RANGE_PARTIAL,
+           VIDEO_RANGE_FULL
+   };
+   
+   struct video_scale_info {
+           enum video_format     format;
+           uint32_t              width;
+           uint32_t              height;
+           enum video_range_type range;
+           enum video_colorspace colorspace;
+   };
+
+---------------------
+
+.. function:: void obs_output_set_audio_conversion(obs_output_t *output, const struct audio_convert_info *conversion)
+
+   Optionally sets the audio conversion information.  Only used by raw
+   outputs.
+
+   Relevant data types used with this function:
+
+.. code:: cpp
+
+   enum audio_format {
+           AUDIO_FORMAT_UNKNOWN,
+   
+           AUDIO_FORMAT_U8BIT,
+           AUDIO_FORMAT_16BIT,
+           AUDIO_FORMAT_32BIT,
+           AUDIO_FORMAT_FLOAT,
+   
+           AUDIO_FORMAT_U8BIT_PLANAR,
+           AUDIO_FORMAT_16BIT_PLANAR,
+           AUDIO_FORMAT_32BIT_PLANAR,
+           AUDIO_FORMAT_FLOAT_PLANAR,
+   };
+   
+   enum speaker_layout {
+           SPEAKERS_UNKNOWN,
+           SPEAKERS_MONO,
+           SPEAKERS_STEREO,
+           SPEAKERS_2POINT1,
+           SPEAKERS_QUAD,
+           SPEAKERS_4POINT1,
+           SPEAKERS_5POINT1,
+           SPEAKERS_5POINT1_SURROUND,
+           SPEAKERS_7POINT1,
+           SPEAKERS_7POINT1_SURROUND,
+           SPEAKERS_SURROUND,
+   };
+   
+   struct audio_convert_info {
+           uint32_t            samples_per_sec;
+           enum audio_format   format;
+           enum speaker_layout speakers;
+   };
+
+---------------------
+
+.. function:: bool obs_output_can_begin_data_capture(const obs_output_t *output, uint32_t flags)
+
+   Determines whether video/audio capture (encoded or raw) is able to
+   start.  Call this before initializing any output data to ensure that
+   the output can start.
+
+   :param flags: Set to 0 to initialize both audio/video, otherwise a
+                 bitwise OR combination of OBS_OUTPUT_VIDEO and/or
+                 OBS_OUTPUT_AUDIO
+   :return:      *true* if data capture can begin
+
+---------------------
+
+.. function:: bool obs_output_initialize_encoders(obs_output_t *output, uint32_t flags)
+
+   Initializes any encoders/services associated with the output.  This
+   must be called for encoded outputs before calling
+   :c:func:`obs_output_begin_data_capture()`.
+
+   :param flags: Set to 0 to initialize both audio/video, otherwise a
+                 bitwise OR combination of OBS_OUTPUT_VIDEO and/or
+                 OBS_OUTPUT_AUDIO
+   :return:      *true* if successful, *false* otherwise
+
+---------------------
+
+.. function:: bool obs_output_begin_data_capture(obs_output_t *output, uint32_t flags)
+
+   Begins data capture from raw media or encoders.  This is typically
+   when the output actually activates (starts) internally.  Video/audio
+   data will start being sent to the callbacks of the output.
+
+   :param flags: Set to 0 to initialize both audio/video, otherwise a
+                 bitwise OR combination of OBS_OUTPUT_VIDEO and/or
+                 OBS_OUTPUT_AUDIO
+   :return:      *true* if successful, *false* otherwise.  Typically the
+                 return value does not need to be checked if
+                 :c:func:`obs_output_can_begin_data_capture()` was
+                 called
+
+---------------------
+
+.. function:: void obs_output_end_data_capture(obs_output_t *output)
+
+   Ends data capture of an output.  This is typically when the output
+   actually intentionally deactivates (stops).  Video/audio data will
+   stop being sent to the callbacks of the output.  The output will
+   trigger the "stop" signal with the OBS_OUTPUT_SUCCESS code to
+   indicate that the output has stopped successfully.  See
+   :ref:`output_signal_handler_reference` for more information on output
+   signals.
+
+---------------------
+
+.. function:: void obs_output_signal_stop(obs_output_t *output, int code)
+
+   Ends data capture of an output with an output code, indicating that
+   the output stopped unexpectedly.  This is typically used if for
+   example the server was disconnected for some reason, or if there was
+   an error saving to file.  The output will trigger the "stop" signal
+   with the the desired code to indicate that the output has stopped
+   successfully.  See :ref:`output_signal_handler_reference` for more
+   information on output signals.
+
+   :c:func:`obs_output_set_last_error()` may be used in conjunction with
+   these error codes to optionally relay more detailed error information
+   to the user
+
+   :param code: | Can be one of the following values:
+                | OBS_OUTPUT_SUCCESS        - Successfuly stopped
+                | OBS_OUTPUT_BAD_PATH       - The specified path was invalid
+                | OBS_OUTPUT_CONNECT_FAILED - Failed to connect to a server
+                | OBS_OUTPUT_INVALID_STREAM - Invalid stream path
+                | OBS_OUTPUT_ERROR          - Generic error
+                | OBS_OUTPUT_DISCONNECTED   - Unexpectedly disconnected
+                | OBS_OUTPUT_UNSUPPORTED    - The settings, video/audio format, or codecs are unsupported by this output
+                | OBS_OUTPUT_NO_SPACE       - Ran out of disk space
+
+.. ---------------------------------------------------------------------------
+
+.. _libobs/obs-output.h: https://github.com/jp9000/obs-studio/blob/master/libobs/obs-output.h

docs/sphinx/reference-properties.rst

@@ -0,0 +1,597 @@
+Properties API Reference (obs_properties_t)
+===========================================
+
+Properties are used to enumerate available settings for a libobs object.
+Typically this is used to automatically generate user interface widgets,
+though can be used to enumerate available and/or valid values for
+specific settings as well.
+
+.. type:: obs_properties_t
+
+   Properties object (not reference counted).
+
+.. type:: obs_property_t
+
+   A property object (not reference counted).
+
+.. code:: cpp
+
+   #include <obs.h>
+
+
+General Functions
+-----------------
+
+.. function:: obs_properties_t *obs_properties_create(void)
+
+   :return: A new properties object.
+
+---------------------
+
+.. function:: obs_properties_t *obs_properties_create_param(void *param, void (*destroy)(void *param))
+
+   Creates a new properties object with specific private data *param*
+   associated with the object, and is automatically freed with the
+   object when the properties are destroyed via the *destroy* function.
+
+   :return: A new properties object.
+
+---------------------
+
+.. function:: void obs_properties_destroy(obs_properties_t *props)
+
+---------------------
+
+.. function:: void obs_properties_set_flags(obs_properties_t *props, uint32_t flags)
+              uint32_t obs_properties_get_flags(obs_properties_t *props)
+
+   :param flags: 0 or a bitwise OR combination of one of the following
+                 values:
+                 
+                 - OBS_PROPERTIES_DEFER_UPDATE - A hint that tells the
+                   front-end to defers updating the settings until the
+                   user has finished editing all properties rather than
+                   immediately updating any settings
+
+---------------------
+
+.. function:: void obs_properties_set_param(obs_properties_t *props, void *param, void (*destroy)(void *param))
+              void *obs_properties_get_param(obs_properties_t *props)
+
+   Sets custom data associated with this properties object.  If private
+   data is already associated with the object, that private data will be
+   destroyed before assigning new private data to it.
+
+---------------------
+
+.. function:: void obs_properties_apply_settings(obs_properties_t *props, obs_data_t *settings)
+
+   Applies settings to the properties by calling all the necessary
+   modification callbacks
+
+---------------------
+
+
+Property Object Functions
+-------------------------
+
+.. function:: obs_property_t *obs_properties_add_bool(obs_properties_t *props, const char *name, const char *description)
+
+   Adds a boolean property.
+
+   :param    name:        Setting identifier string
+   :param    description: Localized name shown to user
+   :return:               The property
+
+---------------------
+
+.. function:: obs_property_t *obs_properties_add_int(obs_properties_t *props, const char *name, const char *description, int min, int max, int step)
+
+   Adds an integer property.
+
+   :param    name:        Setting identifier string
+   :param    description: Localized name shown to user
+   :param    min:         Minimum value
+   :param    max:         Maximum value
+   :param    step:        Step value
+   :return:               The property
+
+---------------------
+
+.. function:: obs_property_t *obs_properties_add_float(obs_properties_t *props, const char *name, const char *description, double min, double max, double step)
+
+   :param    name:        Setting identifier string
+   :param    description: Localized name shown to user
+   :param    min:         Minimum value
+   :param    max:         Maximum value
+   :param    step:        Step value
+   :return:               The property
+
+---------------------
+
+.. function:: obs_property_t *obs_properties_add_int_slider(obs_properties_t *props, const char *name, const char *description, int min, int max, int step)
+
+   :param    name:        Setting identifier string
+   :param    description: Localized name shown to user
+   :param    min:         Minimum value
+   :param    max:         Maximum value
+   :param    step:        Step value
+   :return:               The property
+
+---------------------
+
+.. function:: obs_property_t *obs_properties_add_float_slider(obs_properties_t *props, const char *name, const char *description, double min, double max, double step)
+
+   :param    name:        Setting identifier string
+   :param    description: Localized name shown to user
+   :param    min:         Minimum value
+   :param    max:         Maximum value
+   :param    step:        Step value
+   :return:               The property
+
+---------------------
+
+.. function:: obs_property_t *obs_properties_add_text(obs_properties_t *props, const char *name, const char *description, enum obs_text_type type)
+
+   :param    name:        Setting identifier string
+   :param    description: Localized name shown to user
+   :param    type:        Can be one of the following values:
+
+                          - **OBS_TEXT_DEFAULT** - Single line of text
+                          - **OBS_TEXT_PASSWORD** - Single line of text (passworded)
+                          - **OBS_TEXT_MULTILINE** - Multi-line text
+
+   :return:               The property
+
+---------------------
+
+.. function:: obs_property_t *obs_properties_add_path(obs_properties_t *props, const char *name, const char *description, enum obs_path_type type, const char *filter, const char *default_path)
+
+   Adds a 'path' property.  Can be a directory or a file.
+
+   If target is a file path, the filters should be this format, separated by
+   double semi-colens, and extensions separated by space::
+
+     "Example types 1 and 2 (*.ex1 *.ex2);;Example type 3 (*.ex3)"
+
+   :param    name:         Setting identifier string
+   :param    description:  Localized name shown to user
+   :param    type:         Can be one of the following values:
+
+                           - **OBS_PATH_FILE** - File (for reading)
+                           - **OBS_PATH_FILE_SAVE** - File (for writing)
+                           - **OBS_PATH_DIRECTORY** - Directory
+
+   :param    filter:       If type is a file path, then describes the file filter
+                           that the user can browse.  Items are separated via
+                           double semi-colens.  If multiple file types in a
+                           filter, separate with space.
+   :param    default_path: The default path to start in, or *NULL*
+   :return:                The property
+
+---------------------
+
+.. function:: obs_property_t *obs_properties_add_list(obs_properties_t *props, const char *name, const char *description, enum obs_combo_type type, enum obs_combo_format format)
+
+   Adds an integer/string/floating point item list.  This would be
+   implemented as a combo box in user interface.
+
+   :param    name:        Setting identifier string
+   :param    description: Localized name shown to user
+   :param    type:        Can be one of the following values:
+
+                          - **OBS_COMBO_TYPE_EDITABLE** - Can be edited.
+                            Only used with string lists.
+                          - **OBS_COMBO_TYPE_LIST** - Not ediable.
+
+   :param    format:      Can be one of the following values:
+
+                          - **OBS_COMBO_FORMAT_INT** - Integer list
+                          - **OBS_COMBO_FORMAT_FLOAT** - Floating point
+                            list
+                          - **OBS_COMBO_FORMAT_STRING** - String list
+
+   :return:               The property
+
+   Important Related Functions:
+
+   - :c:func:`obs_property_list_add_string`
+   - :c:func:`obs_property_list_add_int`
+   - :c:func:`obs_property_list_add_float`
+   - :c:func:`obs_property_list_insert_string`
+   - :c:func:`obs_property_list_insert_int`
+   - :c:func:`obs_property_list_insert_float`
+   - :c:func:`obs_property_list_item_remove`
+   - :c:func:`obs_property_list_clear`
+
+---------------------
+
+.. function:: obs_property_t *obs_properties_add_color(obs_properties_t *props, const char *name, const char *description)
+
+   Adds a color property.
+
+   :param    name:        Setting identifier string
+   :param    description: Localized name shown to user
+   :return:               The property
+
+---------------------
+
+.. function:: obs_property_t *obs_properties_add_button(obs_properties_t *props, const char *name, const char *text, obs_property_clicked_t callback)
+
+   Adds a button property.  This property does not actually store any
+   settings; it's used to implement a button in user interface if the
+   properties are used to generate user interface.
+
+   :param    name:        Setting identifier string
+   :param    description: Localized name shown to user
+   :return:               The property
+
+---------------------
+
+.. function:: obs_property_t *obs_properties_add_font(obs_properties_t *props, const char *name, const char *description)
+
+   Adds a font property.
+
+   :param    name:        Setting identifier string
+   :param    description: Localized name shown to user
+   :return:               The property
+
+---------------------
+
+.. function:: obs_property_t *obs_properties_add_editable_list(obs_properties_t *props, const char *name, const char *description, enum obs_editable_list_type type, const char *filter, const char *default_path)
+
+   Adds a list in which the user can add/insert/remove items.
+
+   :param    name:         Setting identifier string
+   :param    description:  Localized name shown to user
+   :param    type:         Can be one of the following values:
+                          
+                           - **OBS_EDITABLE_LIST_TYPE_STRINGS** - An
+                             editable list of strings.
+                           - **OBS_EDITABLE_LIST_TYPE_FILES** - An
+                             editable list of files.
+                           - **OBS_EDITABLE_LIST_TYPE_FILES_AND_URLS** -
+                             An editable list of files and URLs.
+
+   :param    filter:       File filter to use if a file list
+   :param    default_path: Default path if a file list
+   :return:                The property
+
+---------------------
+
+.. function:: obs_property_t *obs_properties_add_frame_rate(obs_properties_t *props, const char *name, const char *description)
+
+   Adds a frame rate property.
+
+   :param    name:        Setting identifier string
+   :param    description: Localized name shown to user
+   :return:               The property
+
+   Important Related Functions:
+
+   - :c:func:`obs_property_frame_rate_option_add`
+   - :c:func:`obs_property_frame_rate_fps_range_add`
+   - :c:func:`obs_property_frame_rate_option_insert`
+   - :c:func:`obs_property_frame_rate_fps_range_insert`
+
+---------------------
+
+
+Property Enumeration Functions
+------------------------------
+
+.. function:: obs_property_t *obs_properties_first(obs_properties_t *props)
+
+   :return: The first property in the properties object.
+
+---------------------
+
+.. function:: obs_property_t *obs_properties_get(obs_properties_t *props, const char *property)
+
+   :param property: The name of the property to get
+   :return:         A specific property or *NULL* if not found
+
+---------------------
+
+.. function:: bool                   obs_property_next(obs_property_t **p)
+
+   :param p: Pointer to the pointer of the next property
+   :return: *true* if successful, *false* if no more properties
+
+---------------------
+
+.. function:: const char *           obs_property_name(obs_property_t *p)
+
+   :return: The setting identifier string of the property
+
+   *(Author's Note: "name" was a bad name to use here.  Should have been
+   "setting")*
+
+---------------------
+
+.. function:: const char *           obs_property_description(obs_property_t *p)
+
+   :return: The actual localized display name of the property
+
+   *(Author's note: This one should have been the "name")*
+
+---------------------
+
+.. function:: const char *           obs_property_long_description(obs_property_t *p)
+
+   :return: A detailed description of what the setting is used for.
+            Usually used with things like tooltips.
+
+---------------------
+
+.. function:: enum obs_property_type obs_property_get_type(obs_property_t *p)
+
+   :return: One of the following values:
+
+            - OBS_PROPERTY_INVALID
+            - OBS_PROPERTY_BOOL
+            - OBS_PROPERTY_INT
+            - OBS_PROPERTY_FLOAT
+            - OBS_PROPERTY_TEXT
+            - OBS_PROPERTY_PATH
+            - OBS_PROPERTY_LIST
+            - OBS_PROPERTY_COLOR
+            - OBS_PROPERTY_BUTTON
+            - OBS_PROPERTY_FONT
+            - OBS_PROPERTY_EDITABLE_LIST
+            - OBS_PROPERTY_FRAME_RATE
+
+---------------------
+
+.. function:: bool                   obs_property_enabled(obs_property_t *p)
+
+---------------------
+
+.. function:: bool                   obs_property_visible(obs_property_t *p)
+
+---------------------
+
+.. function:: int                    obs_property_int_min(obs_property_t *p)
+
+---------------------
+
+.. function:: int                    obs_property_int_max(obs_property_t *p)
+
+---------------------
+
+.. function:: int                    obs_property_int_step(obs_property_t *p)
+
+---------------------
+
+.. function:: enum obs_number_type   obs_property_int_type(obs_property_t *p)
+
+---------------------
+
+.. function:: double                 obs_property_float_min(obs_property_t *p)
+
+---------------------
+
+.. function:: double                 obs_property_float_max(obs_property_t *p)
+
+---------------------
+
+.. function:: double                 obs_property_float_step(obs_property_t *p)
+
+---------------------
+
+.. function:: enum obs_number_type   obs_property_float_type(obs_property_t *p)
+
+---------------------
+
+.. function:: enum obs_text_type     obs_proprety_text_type(obs_property_t *p)
+
+---------------------
+
+.. function:: enum obs_path_type     obs_property_path_type(obs_property_t *p)
+
+---------------------
+
+.. function:: const char *           obs_property_path_filter(obs_property_t *p)
+
+---------------------
+
+.. function:: const char *           obs_property_path_default_path(obs_property_t *p)
+
+---------------------
+
+.. function:: enum obs_combo_type    obs_property_list_type(obs_property_t *p)
+
+---------------------
+
+.. function:: enum obs_combo_format  obs_property_list_format(obs_property_t *p)
+
+---------------------
+
+.. function:: bool obs_property_list_item_disabled(obs_property_t *p, size_t idx)
+
+---------------------
+
+.. function:: size_t      obs_property_list_item_count(obs_property_t *p)
+
+---------------------
+
+.. function:: const char *obs_property_list_item_name(obs_property_t *p, size_t idx)
+
+---------------------
+
+.. function:: const char *obs_property_list_item_string(obs_property_t *p, size_t idx)
+
+---------------------
+
+.. function:: long long   obs_property_list_item_int(obs_property_t *p, size_t idx)
+
+---------------------
+
+.. function:: double      obs_property_list_item_float(obs_property_t *p, size_t idx)
+
+---------------------
+
+.. function:: enum obs_editable_list_type obs_property_editable_list_type(obs_property_t *p)
+
+---------------------
+
+.. function:: const char *obs_property_editable_list_filter(obs_property_t *p)
+
+---------------------
+
+.. function:: const char *obs_property_editable_list_default_path(obs_property_t *p)
+
+---------------------
+
+.. function:: size_t      obs_property_frame_rate_options_count(obs_property_t *p)
+
+---------------------
+
+.. function:: const char *obs_property_frame_rate_option_name(obs_property_t *p, size_t idx)
+
+---------------------
+
+.. function:: const char *obs_property_frame_rate_option_description( obs_property_t *p, size_t idx)
+
+---------------------
+
+.. function:: size_t      obs_property_frame_rate_fps_ranges_count(obs_property_t *p)
+
+---------------------
+
+.. function:: struct media_frames_per_second obs_property_frame_rate_fps_range_min( obs_property_t *p, size_t idx)
+
+---------------------
+
+.. function:: struct media_frames_per_second obs_property_frame_rate_fps_range_max( obs_property_t *p, size_t idx)
+
+---------------------
+
+
+Property Modification Functions
+-------------------------------
+
+.. function:: void obs_property_set_modified_callback(obs_property_t *p, obs_property_modified_t modified)
+
+   Allows the ability to change the properties depending on what
+   settings are used by the user.
+
+   Relevant data types used with this function:
+
+.. code:: cpp
+
+   typedef bool (*obs_property_clicked_t)(obs_properties_t *props,
+                   obs_property_t *property, void *data);
+
+---------------------
+
+.. function:: bool obs_property_modified(obs_property_t *p, obs_data_t *settings)
+
+---------------------
+
+.. function:: bool obs_property_button_clicked(obs_property_t *p, void *obj)
+
+---------------------
+
+.. function:: void obs_property_set_visible(obs_property_t *p, bool visible)
+
+---------------------
+
+.. function:: void obs_property_set_enabled(obs_property_t *p, bool enabled)
+
+---------------------
+
+.. function:: void obs_property_set_description(obs_property_t *p, const char *description)
+
+   Sets the displayed localized name of the property, shown to the user.
+
+---------------------
+
+.. function:: void obs_property_set_long_description(obs_property_t *p, const char *long_description)
+
+   Sets the localized long description of the property, usually shown to
+   a user via tooltip.
+
+---------------------
+
+.. function:: void obs_property_int_set_limits(obs_property_t *p, int min, int max, int step)
+
+---------------------
+
+.. function:: void obs_property_float_set_limits(obs_property_t *p, double min, double max, double step)
+
+---------------------
+
+.. function:: void obs_property_list_clear(obs_property_t *p)
+
+---------------------
+
+.. function:: size_t obs_property_list_add_string(obs_property_t *p, const char *name, const char *val)
+
+   Adds a string to a string list.
+
+---------------------
+
+.. function:: size_t obs_property_list_add_int(obs_property_t *p, const char *name, long long val)
+
+   Adds an integer to a integer list.
+
+---------------------
+
+.. function:: size_t obs_property_list_add_float(obs_property_t *p, const char *name, double val)
+
+   Adds a floating point to a floating point list.
+
+---------------------
+
+.. function:: void obs_property_list_insert_string(obs_property_t *p, size_t idx, const char *name, const char *val)
+
+   Inserts a string in to a string list.
+
+---------------------
+
+.. function:: void obs_property_list_insert_int(obs_property_t *p, size_t idx, const char *name, long long val)
+
+   Inserts an integer in to an integer list.
+
+---------------------
+
+.. function:: void obs_property_list_insert_float(obs_property_t *p, size_t idx, const char *name, double val)
+
+   Inserts a floating point in to a floating point list.
+
+---------------------
+
+.. function:: void obs_property_list_item_disable(obs_property_t *p, size_t idx,
+
+---------------------
+
+.. function:: void obs_property_list_item_remove(obs_property_t *p, size_t idx)
+
+---------------------
+
+.. function:: size_t obs_property_frame_rate_option_add(obs_property_t *p, const char *name, const char *description)
+
+---------------------
+
+.. function:: size_t obs_property_frame_rate_fps_range_add(obs_property_t *p, struct media_frames_per_second min, struct media_frames_per_second max)
+
+---------------------
+
+.. function:: void obs_property_frame_rate_clear(obs_property_t *p)
+
+---------------------
+
+.. function:: void obs_property_frame_rate_options_clear(obs_property_t *p)
+
+---------------------
+
+.. function:: void obs_property_frame_rate_fps_ranges_clear(obs_property_t *p)
+
+---------------------
+
+.. function:: void obs_property_frame_rate_option_insert(obs_property_t *p, size_t idx, const char *name, const char *description)
+
+---------------------
+
+.. function:: void obs_property_frame_rate_fps_range_insert(obs_property_t *p, size_t idx, struct media_frames_per_second min, struct media_frames_per_second max)

docs/sphinx/reference-scenes.rst

@@ -0,0 +1,414 @@
+Scene API Reference (obs_scene_t)
+=================================
+
+A scene is a source which contains and renders other sources using
+specific transforms and/or filtering
+
+.. type:: obs_scene_t
+
+   A reference-counted scene object.
+
+.. type:: obs_sceneitem_t
+
+   A reference-counted scene item object.
+
+.. code:: cpp
+
+   #include <obs.h>
+
+
+Scene Item Transform Structure (obs_transform_info)
+---------------------------------------------------
+
+.. type:: struct obs_transform_info
+
+   Scene item transform structure.
+
+.. member:: struct vec2          obs_transform_info.pos
+
+   Position.
+
+.. member:: float                obs_transform_info.rot
+
+   Rotation (degrees).
+
+.. member:: struct vec2          obs_transform_info.scale
+
+   Scale.
+
+.. member:: uint32_t             obs_transform_info.alignment
+
+   The alignment of the scene item relative to its position.
+
+   Can be 0 or a bitwise OR combination of one of the following values:
+
+   - **OBS_ALIGN_CENTER**
+   - **OBS_ALIGN_LEFT**
+   - **OBS_ALIGN_RIGHT**
+   - **OBS_ALIGN_TOP**
+   - **OBS_ALIGN_BOTTOM**
+
+.. member:: enum obs_bounds_type obs_transform_info.bounds_type
+
+   Can be one of the following values:
+
+   - **OBS_BOUNDS_NONE**            - No bounding box
+   - **OBS_BOUNDS_STRETCH**         - Stretch to the bounding box without preserving aspect ratio
+   - **OBS_BOUNDS_SCALE_INNER**     - Scales with aspect ratio to inner bounding box rectangle
+   - **OBS_BOUNDS_SCALE_OUTER**     - Scales with aspect ratio to outer bounding box rectangle
+   - **OBS_BOUNDS_SCALE_TO_WIDTH**  - Scales with aspect ratio to the bounding box width
+   - **OBS_BOUNDS_SCALE_TO_HEIGHT** - Scales with aspect ratio to the bounding box height
+   - **OBS_BOUNDS_MAX_ONLY**        - Scales with aspect ratio, but only to the size of the source maximum
+
+.. member:: uint32_t             obs_transform_info.bounds_alignment
+
+   The alignment of the source within the bounding box.
+
+   Can be 0 or a bitwise OR combination of one of the following values:
+
+   - **OBS_ALIGN_CENTER**
+   - **OBS_ALIGN_LEFT**
+   - **OBS_ALIGN_RIGHT**
+   - **OBS_ALIGN_TOP**
+   - **OBS_ALIGN_BOTTOM**
+
+.. member:: struct vec2          obs_transform_info.bounds
+
+   The bounding box (if a bounding box is enabled).
+
+
+Scene Item Crop Structure (obs_sceneitem_crop)
+----------------------------------------------
+
+.. type:: struct obs_sceneitem_crop
+
+   Scene item crop structure.
+
+.. member:: int obs_sceneitem_crop.left
+
+   Left crop value.
+
+.. member:: int obs_sceneitem_crop.top
+
+   Top crop value.
+
+.. member:: int obs_sceneitem_crop.right
+
+   Right crop value.
+
+.. member:: int obs_sceneitem_crop.bottom
+
+   Bottom crop value.
+
+
+.. _scene_signal_reference:
+
+Scene Signals
+-------------
+
+**item_add** (ptr scene, ptr item)
+
+   Called when a scene item has been added to the scene.
+
+**item_remove** (ptr scene, ptr item)
+
+   Called when a scene item has been removed from the scen.
+
+**reorder** (ptr scene)
+
+   Called when scene items have been reoredered in the scene.
+
+**item_visible** (ptr scene, ptr item, bool visible)
+
+   Called when a scene item's visibility state changes.
+
+**item_select** (ptr scene, ptr item)
+**item_deselect** (ptr scene, ptr item)
+
+   Called when a scene item has been selected/deselected.
+
+   (Author's note: These should be replaced)
+
+**item_transform** (ptr scene, ptr item)
+
+   Called when a scene item's transform has changed.
+
+
+General Scene Functions
+-----------------------
+
+.. function:: obs_scene_t *obs_scene_create(const char *name)
+
+   :param name: Name of the scene source.  If it's not unique, it will
+                be made unique
+   :return:     A reference to a scene
+
+---------------------
+
+.. function:: obs_scene_t *obs_scene_create_private(const char *name)
+
+   :param name: Name of the scene source.  Does not have to be unique,
+                or can be *NULL*
+   :return:     A reference to a private scene
+
+---------------------
+
+.. function:: obs_scene_t *obs_scene_duplicate(obs_scene_t *scene, const char *name, enum obs_scene_duplicate_type type)
+
+   Duplicates a scene.  When a scene is duplicated, its sources can be
+   just referenced, or fully duplicated.
+
+   :param name: Name of the new scene source
+
+   :param type:  | Type of duplication:
+                 | OBS_SCENE_DUP_REFS         - Duplicates the scene, but scene items are only duplicated with references
+                 | OBS_SCENE_DUP_COPY         - Duplicates the scene, and scene items are also fully duplicated when possible
+                 | OBS_SCENE_DUP_PRIVATE_REFS - Duplicates with references, but the scene is a private source
+                 | OBS_SCENE_DUP_PRIVATE_COPY - Fully duplicates scene items when possible, but the scene and duplicates sources are private sources
+
+   :return:     A reference to a new scene
+
+---------------------
+
+.. function:: void obs_scene_addref(obs_scene_t *scene)
+              void obs_scene_release(obs_scene_t *scene)
+
+   Adds/releases a reference to a scene.
+
+---------------------
+
+.. function:: obs_sceneitem_t *obs_scene_add(obs_scene_t *scene, obs_source_t *source)
+
+   :return: A new scene item for a source within a scene.  Does not
+            increment the reference
+
+---------------------
+
+.. function:: obs_source_t *obs_scene_get_source(const obs_scene_t *scene)
+
+   :return: The scene's source.  Does not increment the reference
+
+---------------------
+
+.. function:: obs_scene_t *obs_scene_from_source(const obs_source_t *source)
+
+   :return: The scene context, or *NULL* if not a scene.  Does not
+            increase the reference
+
+---------------------
+
+.. function:: obs_sceneitem_t *obs_scene_find_source(obs_scene_t *scene, const char *name)
+
+   :param name: The name of the source to find
+   :return:     The scene item if found, otherwise *NULL* if not found
+
+---------------------
+
+.. function:: obs_sceneitem_t *obs_scene_find_sceneitem_by_id(obs_scene_t *scene, int64_t id)
+
+   :param id: The unique numeric identifier of the scene item
+   :return:   The scene item if found, otherwise *NULL* if not found
+
+---------------------
+
+.. function:: void obs_scene_enum_items(obs_scene_t *scene, bool (*callback)(obs_scene_t*, obs_sceneitem_t*, void*), void *param)
+
+   Enumerates scene items within a scene.
+
+---------------------
+
+.. function:: bool obs_scene_reorder_items(obs_scene_t *scene, obs_sceneitem_t * const *item_order, size_t item_order_size)
+
+   Reorders items within a scene.
+
+---------------------
+
+
+.. _scene_item_reference:
+
+Scene Item Functions
+--------------------
+
+.. function:: void obs_sceneitem_addref(obs_sceneitem_t *item)
+              void obs_sceneitem_release(obs_sceneitem_t *item)
+
+   Adds/releases a reference to a scene item.
+
+---------------------
+
+.. function:: void obs_sceneitem_remove(obs_sceneitem_t *item)
+
+   Removes the scene item from the scene.
+
+---------------------
+
+.. function:: obs_scene_t *obs_sceneitem_get_scene(const obs_sceneitem_t *item)
+
+   :return: The scene associated with the scene item.  Does not
+            increment the reference
+
+---------------------
+
+.. function:: obs_source_t *obs_sceneitem_get_source(const obs_sceneitem_t *item)
+
+   :return: The source associated with the scene item.  Does not
+            increment the reference
+
+---------------------
+
+.. function:: void obs_sceneitem_set_pos(obs_sceneitem_t *item, const struct vec2 *pos)
+              void obs_sceneitem_get_pos(const obs_sceneitem_t *item, struct vec2 *pos)
+
+   Sets/gets the position of a scene item.
+
+---------------------
+
+.. function:: void obs_sceneitem_set_rot(obs_sceneitem_t *item, float rot_deg)
+              float obs_sceneitem_get_rot(const obs_sceneitem_t *item)
+
+   Sets/gets the rotation of a scene item.
+
+---------------------
+
+.. function:: void obs_sceneitem_set_scale(obs_sceneitem_t *item, const struct vec2 *scale)
+              void obs_sceneitem_get_scale(const obs_sceneitem_t *item, struct vec2 *scale)
+
+   Sets/gets the scaling of the scene item.
+
+---------------------
+
+.. function:: void obs_sceneitem_set_alignment(obs_sceneitem_t *item, uint32_t alignment)
+              uint32_t obs_sceneitem_get_alignment(const obs_sceneitem_t *item)
+
+   Sets/gets the alignment of the scene item relative to its position.
+
+   :param alignment: | Can be any bitwise OR combination of:
+                     | OBS_ALIGN_CENTER
+                     | OBS_ALIGN_LEFT
+                     | OBS_ALIGN_RIGHT
+                     | OBS_ALIGN_TOP
+                     | OBS_ALIGN_BOTTOM
+
+---------------------
+
+.. function:: void obs_sceneitem_set_order(obs_sceneitem_t *item, enum obs_order_movement movement)
+
+   Changes the scene item's order relative to the other scene items
+   within the scene.
+
+   :param movement: | Can be one of the following:
+                    | OBS_ORDER_MOVE_UP
+                    | OBS_ORDER_MOVE_DOWN
+                    | OBS_ORDER_MOVE_TOP
+                    | OBS_ORDER_MOVE_BOTTOM
+
+---------------------
+
+.. function:: void obs_sceneitem_set_order_position(obs_sceneitem_t *item, int position)
+
+   Changes the scene item's order index.
+
+---------------------
+
+.. function:: void obs_sceneitem_set_bounds_type(obs_sceneitem_t *item, enum obs_bounds_type type)
+              enum obs_bounds_type obs_sceneitem_get_bounds_type(const obs_sceneitem_t *item)
+
+   Sets/gets the bounding box type of a scene item.  Bounding boxes are
+   used to stretch/position the source relative to a specific bounding
+   box of a specific size.
+
+   :param type: | Can be one of the following values:
+                | OBS_BOUNDS_NONE            - No bounding box
+                | OBS_BOUNDS_STRETCH         - Stretch to the bounding box without preserving aspect ratio
+                | OBS_BOUNDS_SCALE_INNER     - Scales with aspect ratio to inner bounding box rectangle
+                | OBS_BOUNDS_SCALE_OUTER     - Scales with aspect ratio to outer bounding box rectangle
+                | OBS_BOUNDS_SCALE_TO_WIDTH  - Scales with aspect ratio to the bounding box width
+                | OBS_BOUNDS_SCALE_TO_HEIGHT - Scales with aspect ratio to the bounding box height
+                | OBS_BOUNDS_MAX_ONLY        - Scales with aspect ratio, but only to the size of the source maximum
+
+---------------------
+
+.. function:: void obs_sceneitem_set_bounds_alignment(obs_sceneitem_t *item, uint32_t alignment)
+              uint32_t obs_sceneitem_get_bounds_alignment(const obs_sceneitem_t *item)
+
+   Sets/gets the alignment of the source within the bounding box.
+
+   :param alignment: | Can be any bitwise OR combination of:
+                     | OBS_ALIGN_CENTER
+                     | OBS_ALIGN_LEFT
+                     | OBS_ALIGN_RIGHT
+                     | OBS_ALIGN_TOP
+                     | OBS_ALIGN_BOTTOM
+
+---------------------
+
+.. function:: void obs_sceneitem_set_bounds(obs_sceneitem_t *item, const struct vec2 *bounds)
+              void obs_sceneitem_get_bounds(const obs_sceneitem_t *item, struct vec2 *bounds)
+
+   Sets/gets the bounding box width/height of the scene item.
+
+---------------------
+
+.. function:: void obs_sceneitem_set_info(obs_sceneitem_t *item, const struct obs_transform_info *info)
+              void obs_sceneitem_get_info(const obs_sceneitem_t *item, struct obs_transform_info *info)
+
+   Sets/gets the transform information of the scene item.
+
+---------------------
+
+.. function:: void obs_sceneitem_get_draw_transform(const obs_sceneitem_t *item, struct matrix4 *transform)
+
+   Gets the transform matrix of the scene item used for drawing the
+   source.
+
+---------------------
+
+.. function:: void obs_sceneitem_get_box_transform(const obs_sceneitem_t *item, struct matrix4 *transform)
+
+   Gets the transform matrix of the scene item used for the bouding box
+   or edges of the scene item.
+
+---------------------
+
+.. function:: bool obs_sceneitem_set_visible(obs_sceneitem_t *item, bool visible)
+              bool obs_sceneitem_visible(const obs_sceneitem_t *item)
+
+   Sets/gets the visibility state of the scene item.
+
+---------------------
+
+.. function:: void obs_sceneitem_set_crop(obs_sceneitem_t *item, const struct obs_sceneitem_crop *crop)
+              void obs_sceneitem_get_crop(const obs_sceneitem_t *item, struct obs_sceneitem_crop *crop)
+
+   Sets/gets the cropping of the scene item.
+
+---------------------
+
+.. function:: void obs_sceneitem_set_scale_filter(obs_sceneitem_t *item, enum obs_scale_type filter)
+              enum obs_scale_type obs_sceneitem_get_scale_filter( obs_sceneitem_t *item)
+
+   Sets/gets the scale filter used for the scene item.
+
+   :param filter: | Can be one of the following values:
+                  | OBS_SCALE_DISABLE
+                  | OBS_SCALE_POINT
+                  | OBS_SCALE_BICUBIC
+                  | OBS_SCALE_BILINEAR
+                  | OBS_SCALE_LANCZOS
+
+---------------------
+
+.. function:: void obs_sceneitem_defer_update_begin(obs_sceneitem_t *item)
+              void obs_sceneitem_defer_update_end(obs_sceneitem_t *item)
+
+   Allows the ability to call any one of the transform functions without
+   updating the internal matrices until obs_sceneitem_defer_update_end
+   has been called.
+
+---------------------
+
+.. function:: obs_data_t *obs_sceneitem_get_private_settings(obs_sceneitem_t *item)
+
+   :return: An incremented reference to the private settings of the
+            scene item.  Allows the front-end to set custom information
+            which is saved with the scene item

docs/sphinx/reference-services.rst

@@ -0,0 +1,276 @@
+Service API Reference (obs_service_t)
+=====================================
+
+Services are custom implementations of streaming services, which are
+used with outputs that stream.  For example, you could have a custom
+implementation for streaming to Twitch, and another for YouTube to allow
+the ability to log in and use their APIs to do things such as get the
+RTMP servers or control the channel.  The `libobs/obs-service.h`_ file
+is the dedicated header for implementing services.
+
+*(Author's note: the service API is incomplete as of this writing)*
+
+.. type:: obs_service_t
+
+   A reference-counted service object.
+
+.. type:: obs_weak_service_t
+
+   A weak reference to a service object.
+
+.. code:: cpp
+
+   #include <obs.h>
+
+
+Service Definition Structure
+----------------------------
+
+.. type:: struct obs_service_info
+
+   Service definition structure.
+
+.. member:: const char *obs_service_info.id
+
+   Unique string identifier for the service (required).
+
+.. member:: const char *(*obs_service_info.get_name)(void *type_data)
+
+   Get the translated name of the service type.
+
+   :param  type_data:  The type_data variable of this structure
+   :return:            The translated name of the service type
+
+.. member:: void *(*obs_service_info.create)(obs_data_t *settings, obs_service_t *service)
+
+   Creates the implementation data for the service.
+
+   :param  settings: Settings to initialize the service with
+   :param  service:   Source that this data is associated with
+   :return:          The implementation data associated with this service
+
+.. member:: void (*obs_service_info.destroy)(void *data)
+
+   Destroys the implementation data for the service.
+
+.. member:: void (*obs_service_info.get_defaults)(obs_data_t *settings)
+            void (*obs_service_info.get_defaults2)(void *type_data, obs_data_t *settings)
+
+   Sets the default settings for this service.
+
+   :param  settings:  Default settings.  Call obs_data_set_default*
+                      functions on this object to set default setting
+                      values
+
+.. member:: obs_properties_t *(*obs_service_info.get_properties)(void *data)
+            obs_properties_t *(*obs_service_info.get_properties2)(void *data, void *type_data)
+
+   Gets the property information of this service.
+
+   (Optional)
+
+   :return: The properties of the service
+
+.. member:: void (*obs_service_info.update)(void *data, obs_data_t *settings)
+
+   Updates the settings for this service.
+
+   (Optional)
+
+   :param settings: New settings for this service
+
+.. member:: bool (*obs_service_info.initialize)(void *data, obs_output_t *output)
+
+   Called when getting ready to start up an output, before the encoders
+   and output are initialized.
+
+   (Optional)
+
+   :param  output: Output context to use this service with
+   :return:        *true* to allow the output to start up,
+                   *false* to prevent output from starting up
+
+.. member:: const char *(*obs_service_info.get_url)(void *data)
+
+   :return: The stream URL
+
+.. member:: const char *(*obs_service_info.get_key)(void *data)
+
+   :return: The stream key
+
+.. member:: const char *(*obs_service_info.get_username)(void *data)
+
+   (Optional)
+
+   :return: The username
+
+.. member:: const char *(*obs_service_info.get_password)(void *data)
+
+   (Optional)
+
+   :return: The password
+
+.. member:: void (*obs_service_info.apply_encoder_settings)(void *data, obs_data_t *video_encoder_settings, obs_data_t *audio_encoder_settings)
+
+   This function is called to apply custom encoder settings specific to
+   this service.  For example, if a service requires a specific keyframe
+   interval, or has a bitrate limit, the settings for the video and
+   audio encoders can be optionally modified if the front-end optionally
+   calls :c:func:`obs_service_apply_encoder_settings()`.
+
+   (Optional)
+
+   :param video_encoder_settings: The audio encoder settings to change
+   :param audio_encoder_settings: The video encoder settings to change
+
+.. member:: void *obs_service_info.type_data
+            void (*obs_service_info.free_type_data)(void *type_data)
+
+   Private data associated with this entry.  Note that this is not the
+   same as the implementation data; this is used to differentiate
+   between two different types if the same callbacks are used for more
+   than one different type.
+
+   (Optional)
+
+.. member:: const char *(*obs_service_info.get_output_type)(void *data)
+
+   (Optional)
+
+   :return: The output type that should be used with this service
+
+
+General Service Functions
+-------------------------
+
+.. function:: void obs_register_service(struct obs_service_info *info)
+
+   Registers a service type.  Typically used in
+   :c:func:`obs_module_load()` or in the program's initialization phase.
+
+---------------------
+
+.. function:: const char *obs_service_get_display_name(const char *id)
+
+   Calls the :c:member:`obs_service_info.get_name` callback to get the
+   translated display name of a service type.
+
+   :param    id:            The service type string identifier
+   :return:                 The translated display name of a service type
+
+---------------------
+
+.. function:: obs_service_t *obs_service_create(const char *id, const char *name, obs_data_t *settings, obs_data_t *hotkey_data)
+
+   Creates a service with the specified settings.
+  
+   The "service" context is used for encoding video/audio data.  Use
+   obs_service_release to release it.
+
+   :param   id:             The service type string identifier
+   :param   name:           The desired name of the service.  If this is
+                            not unique, it will be made to be unique
+   :param   settings:       The settings for the service, or *NULL* if
+                            none
+   :param   hotkey_data:    Saved hotkey data for the service, or *NULL*
+                            if none
+   :return:                 A reference to the newly created service, or
+                            *NULL* if failed
+
+---------------------
+
+.. function:: void obs_service_addref(obs_service_t *service)
+              void obs_service_release(obs_service_t *service)
+
+   Adds/releases a reference to a service.  When the last reference is
+   released, the service is destroyed.
+
+---------------------
+
+.. function:: obs_weak_service_t *obs_service_get_weak_service(obs_service_t *service)
+              obs_service_t *obs_weak_service_get_service(obs_weak_service_t *weak)
+
+   These functions are used to get a weak reference from a strong service
+   reference, or a strong service reference from a weak reference.  If
+   the service is destroyed, *obs_weak_service_get_service* will return
+   *NULL*.
+
+---------------------
+
+.. function:: void obs_weak_service_addref(obs_weak_service_t *weak)
+              void obs_weak_service_release(obs_weak_service_t *weak)
+
+   Adds/releases a weak reference to a service.
+
+---------------------
+
+.. function:: const char *obs_service_get_name(const obs_service_t *service)
+
+   :return: The name of the service
+
+---------------------
+
+.. function:: obs_data_t *obs_service_defaults(const char *id)
+
+   :return: An incremented reference to the service's default settings
+
+---------------------
+
+.. function:: obs_properties_t *obs_service_properties(const obs_service_t *service)
+              obs_properties_t *obs_get_service_properties(const char *id)
+
+   Use these functions to get the properties of a service or service
+   type.  Properties are optionally used (if desired) to automatically
+   generate user interface widgets to allow users to update settings.
+
+   :return: The properties list for a specific existing service.  Free
+            with :c:func:`obs_properties_destroy()`
+
+---------------------
+
+.. function:: obs_data_t *obs_service_get_settings(const obs_service_t *service)
+
+   :return: An incremented reference to the service's settings
+
+---------------------
+
+.. function:: void obs_service_update(obs_service_t *service, obs_data_t *settings)
+
+   Updates the settings for this service context.
+
+---------------------
+
+.. function:: const char *obs_service_get_url(const obs_service_t *service)
+
+  :return: The URL currently used for this service
+
+---------------------
+
+.. function:: const char *obs_service_get_key(const obs_service_t *service)
+
+  :return: Stream key (if any) currently used for this service
+
+---------------------
+
+.. function:: const char *obs_service_get_username(const obs_service_t *service)
+
+   :return: User name (if any) currently used for this service
+
+---------------------
+
+.. function:: const char *obs_service_get_password(const obs_service_t *service)
+
+   :return: Password (if any) currently used for this service
+
+---------------------
+
+.. function:: void obs_service_apply_encoder_settings(obs_service_t *service, obs_data_t *video_encoder_settings, obs_data_t *audio_encoder_settings)
+
+   Applies service-specific video encoder settings.
+  
+   :param  video_encoder_settings: Video encoder settings.  Can be *NULL*
+   :param  audio_encoder_settings: Audio encoder settings.  Can be *NULL*
+
+.. ---------------------------------------------------------------------------
+
+.. _libobs/obs-service.h: https://github.com/jp9000/obs-studio/blob/master/libobs/obs-service.h

docs/sphinx/reference-settings.rst

@@ -0,0 +1,279 @@
+Data Settings API Reference (obs_data_t)
+========================================
+
+Data settings objects are reference-counted objects that store values in
+a string-table or array.  They're similar to Json objects, but
+additionally allow additional functionality such as default or
+auto-selection values.  Data is saved/loaded to/from Json text and Json
+text files.
+
+.. type:: obs_data_t
+
+   A reference-counted data object.
+
+.. type:: obs_data_array_t
+
+   A reference-counted data array object.
+
+.. code:: cpp
+
+   #include <obs.h>
+
+
+General Functions
+-----------------
+
+.. function:: obs_data_t *obs_data_create()
+
+   :return: A new reference to a data object.
+
+---------------------
+
+.. function:: obs_data_t *obs_data_create_from_json(const char *json_string)
+
+   Creates a data object from a Json string.
+
+   :param json_string: Json string
+   :return:            A new reference to a data object
+
+---------------------
+
+.. function:: obs_data_t *obs_data_create_from_json_file(const char *json_file)
+
+   Creates a data object from a Json file.
+
+   :param json_file: Json file path
+   :return:          A new reference to a data object
+
+---------------------
+
+.. function:: obs_data_t *obs_data_create_from_json_file_safe(const char *json_file, const char *backup_ext)
+
+   Creates a data object from a Json file, with a backup file in case
+   the original is corrupted or fails to load.
+
+   :param json_file:  Json file path
+   :param backup_ext: Backup file extension
+   :return:           A new reference to a data object
+
+---------------------
+
+.. function:: void obs_data_addref(obs_data_t *data)
+              void obs_data_release(obs_data_t *data)
+
+   Adds/releases a reference to a data object.
+
+---------------------
+
+.. function:: const char *obs_data_get_json(obs_data_t *data)
+
+   :return: Json string for this object
+
+---------------------
+
+.. function:: bool obs_data_save_json(obs_data_t *data, const char *file)
+
+   Saves the data to a file as Json text.
+
+   :param file: The file to save to
+   :return:     *true* if successful, *false* otherwise
+
+---------------------
+
+.. function:: bool obs_data_save_json_safe(obs_data_t *data, const char *file, const char *temp_ext, const char *backup_ext)
+
+   Saves the data to a file as Json text, and if overwriting an old
+   file, backs up that old file to help prevent potential file
+   corruption.
+
+   :param file:       The file to save to
+   :param backup_ext: The backup extension to use for the overwritten
+                      file if it exists
+   :return:           *true* if successful, *false* otherwise
+
+---------------------
+
+.. function:: void obs_data_apply(obs_data_t *target, obs_data_t *apply_data)
+
+   Merges the data of *apply_data* in to *target*.
+
+---------------------
+
+.. function:: void obs_data_erase(obs_data_t *data, const char *name)
+
+   Erases the user data for item *name* within the data object.
+
+---------------------
+
+.. function:: void obs_data_clear(obs_data_t *data)
+
+   Clears all user data in the data object.
+
+---------------------
+
+
+Set Functions
+-------------
+
+.. function:: void obs_data_set_string(obs_data_t *data, const char *name, const char *val)
+
+---------------------
+
+.. function:: void obs_data_set_int(obs_data_t *data, const char *name, long long val)
+
+---------------------
+
+.. function:: void obs_data_set_double(obs_data_t *data, const char *name, double val)
+
+---------------------
+
+.. function:: void obs_data_set_bool(obs_data_t *data, const char *name, bool val)
+
+---------------------
+
+.. function:: void obs_data_set_obj(obs_data_t *data, const char *name, obs_data_t *obj)
+
+---------------------
+
+.. function:: void obs_data_set_array(obs_data_t *data, const char *name, obs_data_array_t *array)
+
+---------------------
+
+
+Get Functions
+-------------
+
+.. function:: const char *obs_data_get_string(obs_data_t *data, const char *name)
+
+---------------------
+
+.. function:: long long obs_data_get_int(obs_data_t *data, const char *name)
+
+---------------------
+
+.. function:: double obs_data_get_double(obs_data_t *data, const char *name)
+
+---------------------
+
+.. function:: bool obs_data_get_bool(obs_data_t *data, const char *name)
+
+---------------------
+
+.. function:: obs_data_t *obs_data_get_obj(obs_data_t *data, const char *name)
+
+   :return: An incremented reference to a data object.
+
+---------------------
+
+.. function:: obs_data_array_t *obs_data_get_array(obs_data_t *data, const char *name)
+
+   :return: An incremented reference to a data array object.
+
+---------------------
+
+Default Value Functions
+-----------------------
+
+Default values are used to determine what value will be given if a value
+is not set.
+
+.. function:: void obs_data_set_default_string(obs_data_t *data, const char *name, const char *val)
+              const char *obs_data_get_default_string(obs_data_t *data, const char *name)
+
+---------------------
+
+.. function:: void obs_data_set_default_int(obs_data_t *data, const char *name, long long val)
+              long long obs_data_get_default_int(obs_data_t *data, const char *name)
+
+---------------------
+
+.. function:: void obs_data_set_default_double(obs_data_t *data, const char *name, double val)
+              double obs_data_get_default_double(obs_data_t *data, const char *name)
+
+---------------------
+
+.. function:: void obs_data_set_default_bool(obs_data_t *data, const char *name, bool val)
+              bool obs_data_get_default_bool(obs_data_t *data, const char *name)
+
+---------------------
+
+.. function:: void obs_data_set_default_obj(obs_data_t *data, const char *name, obs_data_t *obj)
+              obs_data_t *obs_data_get_default_obj(obs_data_t *data, const char *name)
+
+   :return: An incremented reference to a data object.
+
+---------------------
+
+
+Autoselect Functions
+--------------------
+
+Autoselect values are optionally used to determine what values should be
+used to ensure functionality if the currently set values are
+inappropriate or invalid.
+
+.. function:: void obs_data_set_autoselect_string(obs_data_t *data, const char *name, const char *val)
+              const char *obs_data_get_autoselect_string(obs_data_t *data, const char *name)
+
+---------------------
+
+.. function:: void obs_data_set_autoselect_int(obs_data_t *data, const char *name, long long val)
+              long long obs_data_get_autoselect_int(obs_data_t *data, const char *name)
+
+---------------------
+
+.. function:: void obs_data_set_autoselect_double(obs_data_t *data, const char *name, double val)
+              double obs_data_get_autoselect_double(obs_data_t *data, const char *name)
+
+---------------------
+
+.. function:: void obs_data_set_autoselect_bool(obs_data_t *data, const char *name, bool val)
+              bool obs_data_get_autoselect_bool(obs_data_t *data, const char *name)
+
+---------------------
+
+.. function:: void obs_data_set_autoselect_obj(obs_data_t *data, const char *name, obs_data_t *obj)
+              obs_data_t *obs_data_get_autoselect_obj(obs_data_t *data, const char *name)
+
+   :return: An incremented reference to a data object.
+
+---------------------
+
+
+Array Functions
+---------------
+
+.. function:: obs_data_array_t *obs_data_array_create()
+
+   :return: A new reference to a data array object.
+
+---------------------
+
+.. function:: void obs_data_array_addref(obs_data_array_t *array)
+
+---------------------
+
+.. function:: void obs_data_array_release(obs_data_array_t *array)
+
+---------------------
+
+.. function:: size_t obs_data_array_count(obs_data_array_t *array)
+
+---------------------
+
+.. function:: obs_data_t *obs_data_array_item(obs_data_array_t *array, size_t idx)
+
+   :return: An incremented reference to the data object associated with
+            this array entry.
+
+---------------------
+
+.. function:: size_t obs_data_array_push_back(obs_data_array_t *array, obs_data_t *obj)
+
+---------------------
+
+.. function:: void obs_data_array_insert(obs_data_array_t *array, size_t idx, obs_data_t *obj)
+
+---------------------
+
+.. function:: void obs_data_array_erase(obs_data_array_t *array, size_t idx)

docs/sphinx/reference-sources.rst

@@ -0,0 +1,1363 @@
+Source API Reference (obs_source_t)
+===================================
+
+Sources are used to render video and/or audio on stream.  Things such as
+capturing displays/games/audio, playing a video, showing an image, or
+playing audio.  Sources can also be used to implement audio and video
+filters as well as transitions.  The `libobs/obs-source.h`_ file is the
+dedicated header for implementing sources.
+
+.. type:: obs_source_t
+
+   A reference-counted video/audio input source.
+
+.. type:: obs_weak_source_t
+
+   A weak reference to an video/audio input source.
+
+.. code:: cpp
+
+   #include <obs.h>
+
+
+Source Definition Structure (obs_source_info)
+---------------------------------------------
+
+.. type:: struct obs_source_info
+
+   Source definition structure.
+
+.. member:: const char *obs_source_info.id
+
+   Unique string identifier for the source (required).
+
+.. member:: enum obs_source_type obs_source_info.type
+
+   Type of source.
+
+   - **OBS_SOURCE_TYPE_INPUT**      - Video/Audio Input
+   - **OBS_SOURCE_TYPE_FILTER**     - Filter
+   - **OBS_SOURCE_TYPE_TRANSITION** - Transition
+
+.. member:: uint32_t obs_source_info.output_flags
+
+   Source output capability flags (required).
+
+   (Author's note: This should be renamed to "capability_flags")
+
+   A bitwise OR combination of one or more of the following values:
+
+   - **OBS_SOURCE_VIDEO** - Source has video
+  
+     Unless SOURCE_ASYNC_VIDEO is specified, the source must include the
+     :c:member:`obs_source_info.video_render` callback in the source
+     definition structure.
+
+   - **OBS_SOURCE_AUDIO** - Source has audio
+  
+     Use the :c:func:`obs_source_output_audio()` function to pass raw
+     audio data, which will be automatically converted and uploaded.  If
+     used with OBS_SOURCE_ASYNC_VIDEO, audio will automatically be
+     synced up to the video output based upon their mutual timestamps.
+
+   - **OBS_SOURCE_ASYNC** - Video is asynchronous (use
+     OBS_SOURCE_ASYNC_VIDEO instead to automatically combine this flag
+     with the OBS_SOURCE_VIDEO flag).
+
+   - **OBS_SOURCE_ASYNC_VIDEO** - Source passes raw video data via RAM
+
+     Use the :c:func:`obs_source_output_video()` function to pass raw
+     video data, which will be automatically drawn at a timing relative
+     to the provided timestamp.
+     
+     If audio is also present on the source, the audio will
+     automatically be synced to the video based upon their mutual
+     timestamps.
+
+   - **OBS_SOURCE_CUSTOM_DRAW** - Source uses custom graphics calls,
+     rather than just rendering a single texture.
+
+     This capability flag must be used if the source does not use
+     :c:func:`obs_source_draw()` to render a single texture.
+
+     This capability flag is an important hint to turn off a specific
+     optimization that allows the first effect filter in the filter
+     chain to render the source directly with that effect filter.  The
+     optimization does not work if there are custom graphics calls, and
+     the source must be rendered to a texture first before being sent to
+     the first filter in the filter chain.
+
+     (Author's note: Ironically, not many sources render with that
+     optimization.  I should have made it so that the optimization isn't
+     used by default, and a flag should have been used to turn on the
+     optimization -- not turn it off).
+
+   - **OBS_SOURCE_INTERACTION** - Source can be interacted with by the
+     user.
+
+     When this is used, the source will receive interaction events if
+     theese callbacks are provided:
+     :c:member:`obs_source_info.mouse_click`,
+     :c:member:`obs_source_info.mouse_move`,
+     :c:member:`obs_source_info.mouse_wheel`,
+     :c:member:`obs_source_info.focus`, and
+     :c:member:`obs_source_info.key_click`.
+
+   - **OBS_SOURCE_COMPOSITE** - Source composites child sources
+
+     When used, specifies that the source composites one or more child
+     sources.  Scenes and transitions are examples of sources that
+     contain and render child sources.
+     
+     Sources that render sub-sources must implement the audio_render
+     callback in order to perform custom audio mixing of child sources.
+
+     This capability flag is always set for transitions.
+
+   - **OBS_SOURCE_DO_NOT_DUPLICATE** - Source should not be fully
+     duplicated.
+
+     When this is used, specifies that the source should not be fully
+     duplicated, and should prefer to duplicate via holding references
+     rather than full duplication.
+
+     When functions such as :c:func:`obs_source_duplicate()` or
+     :c:func:`obs_scene_duplicate()` are called, sources or child
+     sources with this flag will never be fully duplicated, and will
+     instead only be referenced.
+
+     An example of the type of sources that should not be fully
+     duplicated are video devices, browsers, and video/audio captures,
+     as they will either not function correctly or will cause
+     performance or resource issues when duplicated.
+
+   - **OBS_SOURCE_DEPRECATED** - Source is deprecated and should not be
+     used.
+
+   - **OBS_SOURCE_DO_NOT_SELF_MONITOR** - Audio of this source should
+     not allow monitoring if the current monitoring device is the same
+     device being captured by the source.
+
+     This flag is used as a hint to the back-end to prevent the source
+     from creating an audio feedback loop.  This is primarily only used
+     with desktop audio capture sources.
+
+.. member:: const char *(*obs_source_info.get_name)(void *type_data)
+
+   Get the translated name of the source type.
+
+   :param  type_data:  The type_data variable of this structure
+   :return:            The translated name of the source type
+
+.. member:: void *(*obs_source_info.create)(obs_data_t *settings, obs_source_t *source)
+
+   Creates the implementation data for the source.
+
+   :param  settings: Settings to initialize the source with
+   :param  source:   Source that this data is associated with
+   :return:          The implementation data associated with this source
+
+.. member:: void (*obs_source_info.destroy)(void *data)
+
+   Destroys the implementation data for the source.
+
+   Async sources must not call obs_source_output_video after returning
+   from destroy.
+
+.. member:: uint32_t (*obs_source_info.get_width)(void *data)
+	    uint32_t (*obs_source_info.get_height)(void *data);
+
+   Returns the width/height of the source.  These callbacks are required
+   if this is a video source and is synchronous.
+
+   (Author's note: These should really be consolidated in to one
+   function, not two)
+
+   :return: The width/height of the video
+
+.. member:: void (*obs_source_info.get_defaults)(obs_data_t *settings)
+            void (*obs_source_info.get_defaults2)(void *type_data, obs_data_t *settings)
+
+   Sets the default settings for this source.
+
+   :param  settings:  Default settings.  Call obs_data_set_default*
+                      functions on this object to set default setting
+                      values
+
+.. member:: obs_properties_t *(*obs_source_info.get_properties)(void *data)
+            obs_properties_t *(*obs_source_info.get_properties2)(void *data, void *type_data)
+
+   Gets the property information of this source.
+
+   (Optional)
+
+   :return: The properties of the source
+
+.. member:: void (*obs_source_info.update)(void *data, obs_data_t *settings)
+
+   Updates the settings for this source.
+
+   (Optional)
+
+   :param settings: New settings for this source
+
+.. member:: void (*obs_source_info.activate)(void *data)
+
+   Called when the source has been activated in the main view (visible
+   on stream/recording).
+
+   (Optional)
+
+.. member:: void (*obs_source_info.deactivate)(void *data)
+
+   Called when the source has been deactivated from the main view (no
+   longer visible on stream/recording).
+
+   (Optional)
+
+.. member:: void (*obs_source_info.show)(void *data)
+
+   Called when the source is visible on any display and/or on the main
+   view.
+
+   (Optional)
+
+.. member:: void (*obs_source_info.hide)(void *data)
+
+   Called when the source is no longer visible on any display and/or on
+   the main view.
+
+   (Optional)
+
+.. member:: void (*obs_source_info.video_tick)(void *data, float seconds)
+
+   Called each video frame with the time elapsed.
+
+   (Optional)
+
+   :param  seconds: Seconds elapsed since the last frame
+
+.. member:: void (*obs_source_info.video_render)(void *data, gs_effect_t *effect)
+
+   Called when rendering the source with the graphics subsystem.
+
+   If this is an input/transition source, this is called to draw the
+   source texture with the graphics subsystem.
+
+   If this is a filter source, it wraps source draw calls (for example
+   applying a custom effect with custom parameters to a source).  In
+   this case, it's highly recommended to use the
+   :c:func:`obs_source_process_filter_begin()` and
+   :c:func:`obs_source_process_filter_end()` functions to automatically
+   handle effect-based filter processing.  However, you can implement
+   custom draw handling as desired as well.
+
+   If the source output capability flags do not include
+   OBS_SOURCE_CUSTOM_DRAW, the source must use
+   :c:func:`obs_source_draw()` to render the source's texture.
+
+   :param effect: This parameter is no longer used.  Instead, call
+                  :c:func:`obs_source_draw()`
+
+.. member:: struct obs_source_frame *(*obs_source_info.filter_video)(void *data, struct obs_source_frame *frame)
+
+   Called to filter raw async video data.  This function is only used
+   with asynchronous video filters.
+
+   :param  frame: Video frame to filter
+   :return:       New video frame data.  This can defer video data to
+                  be drawn later if time is needed for processing
+
+.. member:: struct obs_audio_data *(*obs_source_info.filter_audio)(void *data, struct obs_audio_data *audio)
+
+   Called to filter raw audio data.  This function is only used with
+   audio filters.
+
+   :param  audio: Audio data to filter
+   :return:       Modified or new audio data.  You can directly modify
+                  the data passed and return it, or you can defer audio
+                  data for later if time is needed for processing.  If
+                  you are returning new data, that data must exist until
+                  the next call to the
+                  :c:member:`obs_source_info.filter_audio` callback or
+                  until the filter is removed/destroyed
+
+.. member:: void (*obs_source_info.enum_active_sources)(void *data, obs_source_enum_proc_t enum_callback, void *param)
+
+   Called to enumerate all active sources being used within this
+   source.  If the source has children that render audio/video it must
+   implement this callback.  Only used with sources that have tha
+   OBS_SOURCE_COMPOSITE output capability flag.
+
+   :param  enum_callback: Enumeration callback
+   :param  param:         User data to pass to callback
+
+.. member:: void (*obs_source_info.save)(void *data, obs_data_t *settings)
+
+   Called when saving custom data for a source.  This is a separate
+   function because sometimes a source needs to know when it is being
+   saved so it doesn't always have to update the current settings until
+   a certain point.
+
+   (Optional)
+
+   :param  settings: Settings object to save data to
+
+.. member:: void (*obs_source_info.load)(void *data, obs_data_t *settings)
+
+   Called when loading custom data from saved source data.  This is
+   called after all the loading sources have actually been created,
+   allowing the ability to reference other sources if desired.
+
+   (Optional)
+
+   :param  settings: Settings object to load data from
+
+.. member:: void (*obs_source_info.mouse_click)(void *data, const struct obs_mouse_event *event, int32_t type, bool mouse_up, uint32_t click_count)
+
+   Called when interacting with a source and a mouse-down or mouse-up
+   occurs.  Only used with sources that have the OBS_SOURCE_INTERACTION
+   output capability flag.
+
+   (Optional)
+
+   :param event:       Mouse event properties
+   :param type:        Mouse button pushed
+   :param mouse_up:    Mouse event type (true if mouse-up)
+   :param click_count: Mouse click count (1 for single click, etc.)
+
+.. member:: void (*obs_source_info.mouse_move)(void *data, const struct obs_mouse_event *event, bool mouse_leave)
+
+   Called when interacting with a source and a mouse-move occurs.  Only
+   used with sources that have the OBS_SOURCE_INTERACTION output
+   capability flag.
+
+   (Optional)
+
+   :param event:       Mouse event properties
+   :param mouse_leave: Mouse leave state (true if mouse left source)
+
+.. member:: void (*obs_source_info.mouse_wheel)(void *data, const struct obs_mouse_event *event, int x_delta, int y_delta)
+
+   Called when interacting with a source and a mouse-wheel occurs.  Only
+   used with sources that have the OBS_SOURCE_INTERACTION output
+   capability flag.
+
+   (Optional)
+
+   :param event:       Mouse event properties
+   :param x_delta:     Movement delta in the horizontal direction
+   :param y_delta:     Movement delta in the vertical direction
+
+
+.. member:: void (*obs_source_info.focus)(void *data, bool focus)
+
+   Called when interacting with a source and gain focus/lost focus event
+   occurs.  Only used with sources that have the OBS_SOURCE_INTERACTION
+   output capability flag.
+
+   (Optional)
+
+   :param focus:       Focus state (true if focus gained)
+
+.. member:: void (*obs_source_info.key_click)(void *data, const struct obs_key_event *event, bool key_up)
+
+   Called when interacting with a source and a key-up or key-down
+   occurs.  Only used with sources that have the OBS_SOURCE_INTERACTION
+   output capability flag.
+
+   (Optional)
+
+   :param event:       Key event properties
+   :param focus:       Key event type (true if mouse-up)
+
+.. member:: void (*obs_source_info.filter_remove)(void *data, obs_source_t *source)
+
+   Called when the filter is removed from a source.
+
+   (Optional)
+
+   :param  data:   Filter data
+   :param  source: Source that the filter being removed from
+
+.. member:: void *obs_source_info.type_data
+            void (*obs_source_info.free_type_data)(void *type_data)
+
+   Private data associated with this entry.  Note that this is not the
+   same as the implementation data; this is used to differentiate
+   between two different types if the same callbacks are used for more
+   than one different type.
+
+.. member:: bool (*obs_source_info.audio_render)(void *data, uint64_t *ts_out, struct obs_source_audio_mix *audio_output, uint32_t mixers, size_t channels, size_t sample_rate)
+
+   Called to render audio of composite sources.  Only used with sources
+   that have tha OBS_SOURCE_COMPOSITE output capability flag.
+
+.. member:: void (*obs_source_info.enum_all_sources)(void *data, obs_source_enum_proc_t enum_callback, void *param)
+
+   Called to enumerate all active and inactive sources being used
+   within this source.  If this callback isn't implemented,
+   enum_active_sources will be called instead.  Only used with sources
+   that have tha OBS_SOURCE_COMPOSITE output capability flag.
+
+   This is typically used if a source can have inactive child sources.
+
+   :param  enum_callback: Enumeration callback
+   :param  param:         User data to pass to callback
+
+.. member:: void (*obs_source_info.transition_start)(void *data)
+            void (*obs_source_info.transition_stop)(void *data)
+
+   Called on transition sources when the transition starts/stops.
+
+   (Optional)
+
+
+.. _source_signal_handler_reference:
+
+Source Signals
+--------------
+
+**destroy** (ptr *source*)
+
+   This signal is called when the source is about to be destroyed.  Do
+   not increment any references when using this signal.
+
+**remove** (ptr source)
+
+   Called when the :c:func:`obs_source_remove()` function is called on
+   the source.
+
+**save** (ptr source)
+
+   Called when the source is being saved.
+
+**load** (ptr source)
+
+   Called when the source is being loaded.
+
+**activate** (ptr source)
+
+   Called when the source has been activated in the main view (visible
+   on stream/recording).
+
+**deactivate** (ptr source)
+
+   Called when the source has been deactivated from the main view (no
+   longer visible on stream/recording).
+
+**show** (ptr source)
+
+   Called when the source is visible on any display and/or on the main
+   view.
+
+**hide** (ptr source)
+
+   Called when the source is no longer visible on any display and/or on
+   the main view.
+
+**mute** (ptr source, bool muted)
+
+   Called when the source is muted/unmuted.
+
+**push_to_mute_changed** (ptr source, bool enabled)
+
+   Called when push-to-mute has been enabled/disabled.
+
+**push_to_mute_delay** (ptr source, int delay)
+
+   Called when the push-to-mute delay value has changed.
+
+**push_to_talk_changed** (ptr source, bool enabled)
+
+   Called when push-to-talk has been enabled/disabled.
+
+**push_to_talk_delay** (ptr source, int delay)
+
+   Called when the push-to-talk delay value has changed.
+
+**enable** (ptr source, bool enabled)
+
+   Called when the source has been disabled/enabled.
+
+**rename** (ptr source, string new_name, string prev_name)
+
+   Called when the source has been renamed.
+
+**volume** (ptr source, in out float volume)
+
+   Called when the volume of the source has changed.
+
+**update_properties** (ptr source)
+
+   Called when the properties of the source have been updated.
+
+**update_flags** (ptr source, int flags)
+
+   Called when the flags of the source have been changed.
+
+**audio_sync** (ptr source, int out int offset)
+
+   Called when the audio sync offset has changed.
+
+**audio_mixers** (ptr source, in out int mixers)
+
+   Called when the audio mixers have changed.
+
+**filter_add** (ptr source, ptr filter)
+
+   Called when a filter has been added to the source.
+
+**filter_remove** (ptr source, ptr filter)
+
+   Called when a filter has been removed from the source.
+
+**reorder_filters** (ptr source)
+
+   Called when filters have been reordered.
+
+**transition_start** (ptr source)
+
+   Called when a transition is starting.
+
+**transition_video_stop** (ptr source)
+
+   Called when a transition's video transitioning has stopped.
+
+**transition_stop** (ptr source)
+
+   Called when a transition has stopped.
+
+
+General Source Functions
+------------------------
+
+.. function:: void obs_register_source(struct obs_source_info *info)
+
+   Registers a source type.  Typically used in
+   :c:func:`obs_module_load()` or in the program's initialization phase.
+
+---------------------
+
+.. function:: const char *obs_source_get_display_name(const char *id)
+
+   Calls the :c:member:`obs_source_info.get_name` callback to get the
+   translated display name of a source type.
+
+   :param    id:            The source type string identifier
+   :return:                 The translated display name of a source type
+
+---------------------
+
+.. function:: obs_source_t *obs_source_create(const char *id, const char *name, obs_data_t *settings, obs_data_t *hotkey_data)
+
+   Creates a source of the specified type with the specified settings.
+  
+   The "source" context is used for anything related to presenting
+   or modifying video/audio.  Use obs_source_release to release it.
+
+   :param   id:             The source type string identifier
+   :param   name:           The desired name of the source.  If this is
+                            not unique, it will be made to be unique
+   :param   settings:       The settings for the source, or *NULL* if
+                            none
+   :param   hotkey_data:    Saved hotkey data for the source, or *NULL*
+                            if none
+   :return:                 A reference to the newly created source, or
+                            *NULL* if failed
+
+---------------------
+
+.. function:: obs_source_t *obs_source_create_private(const char *id, const char *name, obs_data_t *settings)
+
+   Creates a 'private' source which is not enumerated by
+   :c:func:`obs_enum_sources()`, and is not saved by
+   :c:func:`obs_save_sources()`.
+
+   Author's Note: The existence of this function is a result of design
+   flaw: the front-end should control saving/loading of sources, and
+   functions like :c:func:`obs_enum_sources()` and
+   :c:func:`obs_save_sources()` should not exist in the back-end.
+
+   :param   id:             The source type string identifier
+   :param   name:           The desired name of the source.  For private
+                            sources, this does not have to be unique,
+                            and can additionally be *NULL* if desired
+   :param   settings:       The settings for the source, or *NULL* if
+                            none
+   :return:                 A reference to the newly created source, or
+                            *NULL* if failed
+
+---------------------
+
+.. function:: obs_source_t *obs_source_duplicate(obs_source_t *source, const char *desired_name, bool create_private)
+
+   Duplicates a source.  If the source has the
+   OBS_SOURCE_DO_NOT_DUPLICATE output flag set, this only returns a
+   new reference to the same source.
+
+   :param source:         The source to duplicate
+   :param desired_name:   The desired name of the new source.  If this is
+                          not a private source and the name is not unique,
+                          it will be made to be unique
+   :param create_private: If *true*, the new source will be a private
+                          source if fully duplicated
+   :return:               A new source reference
+
+---------------------
+
+.. function:: void obs_source_addref(obs_source_t *source)
+              void obs_source_release(obs_source_t *source)
+
+   Adds/releases a reference to a source.  When the last reference is
+   released, the source is destroyed.
+
+---------------------
+
+.. function:: obs_weak_source_t *obs_source_get_weak_source(obs_source_t *source)
+              obs_source_t *obs_weak_source_get_source(obs_weak_source_t *weak)
+
+   These functions are used to get a weak reference from a strong source
+   reference, or a strong source reference from a weak reference.  If
+   the source is destroyed, *obs_weak_source_get_source* will return
+   *NULL*.
+
+---------------------
+
+.. function:: void obs_weak_source_addref(obs_weak_source_t *weak)
+              void obs_weak_source_release(obs_weak_source_t *weak)
+
+   Adds/releases a weak reference to a source.
+
+---------------------
+
+.. function:: void obs_source_remove(obs_source_t *source)
+
+   Notifies all reference holders of the source (via
+   :c:func:`obs_source_removed()`) that the source should be released.
+
+---------------------
+
+.. function:: bool obs_source_removed(const obs_source_t *source)
+
+   :return: *true* if the source should be released
+
+---------------------
+
+.. function:: uint32_t obs_source_get_output_flags(const obs_source_t *source)
+              uint32_t obs_get_source_output_flags(const char *id)
+
+   :return: Capability flags of a source
+
+   Author's Note: "Output flags" is poor wording in retrospect; this
+   should have been named "Capability flags", and the OBS_SOURCE_*
+   macros should really be OBS_SOURCE_CAP_* macros instead.
+
+   See :c:member:`obs_source_info.output_flags` for more information.
+
+---------------------
+
+.. function:: obs_data_t *obs_get_source_defaults(const char *id)
+
+   Calls :c:member:`obs_source_info.get_defaults` to get the defaults
+   settings of the source type.
+
+   :return: The default settings for a source type
+
+---------------------
+
+.. function:: obs_properties_t *obs_source_properties(const obs_source_t *source)
+              obs_properties_t *obs_get_source_properties(const char *id)
+
+   Use these functions to get the properties of a source or source type.
+   Properties are optionally used (if desired) to automatically generate
+   user interface widgets to allow users to update settings.
+
+   :return: The properties list for a specific existing source.  Free with
+            :c:func:`obs_properties_destroy()`
+
+---------------------
+
+.. function:: bool obs_source_configurable(const obs_source_t *source)
+              bool obs_is_source_configurable(const char *id)
+
+   :return: *true* if the the source has custom properties, *false*
+            otherwise
+
+---------------------
+
+.. function:: void obs_source_update(obs_source_t *source, obs_data_t *settings)
+
+   Updates the settings for a source and calls the
+   :c:member:`obs_source_info.update` callback of the source.  If the
+   source is a video source, the :c:member:`obs_source_info.update` will
+   be not be called immediately; instead, it will be deferred to the
+   video thread to prevent threading issues.
+
+---------------------
+
+.. function:: void obs_source_video_render(obs_source_t *source)
+
+   Renders a video source.  This will call the
+   :c:member:`obs_source_info.video_render` callback of the source.
+
+---------------------
+
+.. function:: uint32_t obs_source_get_width(obs_source_t *source)
+              uint32_t obs_source_get_height(obs_source_t *source)
+
+   Calls the :c:member:`obs_source_info.get_width` or
+   :c:member:`obs_source_info.get_height` of the source to get its width
+   and/or height.
+
+   Author's Note: These functions should be consolidated in to a single
+   function/callback rather than having a function for both width and
+   height.
+
+   :return: The width or height of the source
+
+---------------------
+
+.. function:: obs_data_t *obs_source_get_settings(const obs_source_t *source)
+
+   :return: The settings string for a source.  The reference counter of the
+            returned settings data is incremented, so
+            :c:func:`obs_data_release()` must be called when the
+            settings are no longer used
+
+---------------------
+
+.. function:: const char *obs_source_get_name(const obs_source_t *source)
+
+   :return: The name of the source
+
+---------------------
+
+.. function:: void obs_source_set_name(obs_source_t *source, const char *name)
+
+   Sets the name of a source.  If the source is not private and the name
+   is not unique, it will automatically be given a unique name.
+
+---------------------
+
+.. function:: enum obs_source_type obs_source_get_type(const obs_source_t *source)
+
+   :return: | OBS_SOURCE_TYPE_INPUT for inputs
+            | OBS_SOURCE_TYPE_FILTER for filters
+            | OBS_SOURCE_TYPE_TRANSITION for transitions
+            | OBS_SOURCE_TYPE_SCENE for scenes
+
+---------------------
+
+.. function:: const char *obs_source_get_id(const obs_source_t *source)
+
+   :return: The source's type identifier string
+
+---------------------
+
+.. function:: signal_handler_t *obs_source_get_signal_handler(const obs_source_t *source)
+
+   :return: The source's signal handler
+
+   See the :ref:`source_signal_handler_reference` for more information
+   on signals that are available for sources.
+
+---------------------
+
+.. function:: proc_handler_t *obs_source_get_proc_handler(const obs_source_t *source)
+
+   :return: The procedure handler for a source
+
+---------------------
+
+.. function:: void obs_source_set_volume(obs_source_t *source, float volume)
+              float obs_source_get_volume(const obs_source_t *source)
+
+   Sets/gets the user volume for a source that has audio output.
+
+---------------------
+
+.. function:: bool obs_source_muted(const obs_source_t *source)
+              void obs_source_set_muted(obs_source_t *source, bool muted)
+
+   Sets/gets whether the source's audio is muted.
+
+---------------------
+
+.. function:: bool obs_source_push_to_mute_enabled(const obs_source_t *source)
+              void obs_source_enable_push_to_mute(obs_source_t *source, bool enabled)
+
+   Sets/gets whether push-to-mute is enabled.
+
+---------------------
+
+.. function:: uint64_t obs_source_get_push_to_mute_delay(const obs_source_t *source)
+              void obs_source_set_push_to_mute_delay(obs_source_t *source, uint64_t delay)
+
+   Sets/gets the push-to-mute delay.
+
+---------------------
+
+.. function:: bool obs_source_push_to_talk_enabled(const obs_source_t *source)
+              void obs_source_enable_push_to_talk(obs_source_t *source, bool enabled)
+
+   Sets/gets whether push-to-talk is enabled.
+
+---------------------
+
+.. function:: uint64_t obs_source_get_push_to_talk_delay(const obs_source_t *source)
+              void obs_source_set_push_to_talk_delay(obs_source_t *source, uint64_t delay)
+
+   Sets/gets the push-to-talk delay.
+
+---------------------
+
+.. function:: void obs_source_set_sync_offset(obs_source_t *source, int64_t offset)
+              int64_t obs_source_get_sync_offset(const obs_source_t *source)
+
+   Sets/gets the audio sync offset (in nanoseconds) for a source.
+
+---------------------
+
+.. function:: void obs_source_enum_active_sources(obs_source_t *source, obs_source_enum_proc_t enum_callback, void *param)
+              void obs_source_enum_active_tree(obs_source_t *source, obs_source_enum_proc_t enum_callback, void *param)
+
+   Enumerates active child sources or source tree used by this source.
+
+   Relevant data types used with this function:
+
+.. code:: cpp
+
+   typedef void (*obs_source_enum_proc_t)(obs_source_t *parent,
+                   obs_source_t *child, void *param);
+
+---------------------
+
+.. function:: bool obs_source_active(const obs_source_t *source)
+
+   :return: *true* if active, *false* if not.  A source is only
+            consdiered active if it's being shown on the final mix
+
+---------------------
+
+.. function:: bool obs_source_showing(const obs_source_t *source)
+
+   :return: *true* if showing, *false* if not.  A source is considered
+            showing if it's being displayed anywhere at all, whether on
+            a display context or on the final output
+
+---------------------
+
+.. function:: void obs_source_inc_showing(obs_source_t *source)
+              void obs_source_dec_showing(obs_source_t *source)
+
+   Increments/decrements a source's "showing" state.  Typically used
+   when drawing a source on a display manually.
+
+---------------------
+
+.. function:: void obs_source_set_flags(obs_source_t *source, uint32_t flags)
+              uint32_t obs_source_get_flags(const obs_source_t *source)
+
+   :param flags: OBS_SOURCE_FLAG_FORCE_MONO Forces audio to mono
+
+---------------------
+
+.. function:: void obs_source_set_audio_mixers(obs_source_t *source, uint32_t mixers)
+              uint32_t obs_source_get_audio_mixers(const obs_source_t *source)
+
+   Sets/gets the audio mixer channels that a source outputs to
+   (depending on what bits are set).  Audio mixers allow filtering
+   specific using multiple audio encoders to mix different sources
+   together depending on what mixer channel they're set to.
+
+   For example, to output to mixer 1 and 3, you would perform a bitwise
+   OR on bits 0 and 2:  (1<<0) | (1<<2), or 0x5.
+
+---------------------
+
+.. function:: void obs_source_enum_filters(obs_source_t *source, obs_source_enum_proc_t callback, void *param)
+
+   Enumerates active filters on a source.
+
+   Relevant data types used with this function:
+
+.. code:: cpp
+
+   typedef void (*obs_source_enum_proc_t)(obs_source_t *parent,
+                   obs_source_t *child, void *param);
+
+---------------------
+
+.. function:: obs_source_t *obs_source_get_filter_by_name(obs_source_t *source, const char *name)
+
+   :return: The desired filter, or *NULL* if not found.  The reference
+            of the filter is incremented
+
+---------------------
+
+.. function:: void obs_source_copy_filters(obs_source_t *dst, obs_source_t *src)
+
+   Copies filters from the source to the destination.  If filters by the
+   same name already exist in the destination source, the newer filters
+   will be given unique names.
+
+---------------------
+
+.. function:: bool obs_source_enabled(const obs_source_t *source)
+              void obs_source_set_enabled(obs_source_t *source, bool enabled)
+
+   Enables/disables a source, or returns the enabled state.
+
+---------------------
+
+.. function:: void obs_source_add_audio_capture_callback(obs_source_t *source, obs_source_audio_capture_t callback, void *param)
+              void obs_source_remove_audio_capture_callback(obs_source_t *source, obs_source_audio_capture_t callback, void *param)
+
+   Adds/removes an audio capture callback for a source.  This allows the
+   ability to get the raw audio data of a source as it comes in.
+
+   Relevant data types used with this function:
+
+.. code:: cpp
+
+   typedef void (*obs_source_audio_capture_t)(void *param, obs_source_t *source,
+                   const struct audio_data *audio_data, bool muted);
+
+---------------------
+
+.. function:: void obs_source_set_deinterlace_mode(obs_source_t *source, enum obs_deinterlace_mode mode)
+              enum obs_deinterlace_mode obs_source_get_deinterlace_mode(const obs_source_t *source)
+
+   Sets/gets the deinterlace mode.
+
+   :param mode:   | OBS_DEINTERLACE_MODE_DISABLE    - Disables deinterlacing
+                  | OBS_DEINTERLACE_MODE_DISCARD    - Discard
+                  | OBS_DEINTERLACE_MODE_RETRO      - Retro
+                  | OBS_DEINTERLACE_MODE_BLEND      - Blend
+                  | OBS_DEINTERLACE_MODE_BLEND_2X   - Blend 2x
+                  | OBS_DEINTERLACE_MODE_LINEAR     - Linear
+                  | OBS_DEINTERLACE_MODE_LINEAR_2X  - Linear 2x
+                  | OBS_DEINTERLACE_MODE_YADIF      - Yadif
+                  | OBS_DEINTERLACE_MODE_YADIF_2X   - Yadif 2x
+
+
+---------------------
+
+.. function:: void obs_source_set_deinterlace_field_order(obs_source_t *source, enum obs_deinterlace_field_order order)
+              enum obs_deinterlace_field_order obs_source_get_deinterlace_field_order(const obs_source_t *source)
+
+   Sets/gets the deinterlace field order.
+
+   :param order: | OBS_DEINTERLACE_FIELD_ORDER_TOP - Start from top
+                 | OBS_DEINTERLACE_FIELD_ORDER_BOTTOM - Start from bottom
+
+---------------------
+
+.. function:: obs_data_t *obs_source_get_private_settings(obs_source_t *item)
+
+   Gets private front-end settings data.  This data is saved/loaded
+   automatically.  Returns an incremented reference.
+
+---------------------
+
+.. function:: void obs_source_send_mouse_click(obs_source_t *source, const struct obs_mouse_event *event, int32_t type, bool mouse_up, uint32_t click_count)
+
+   Used for interacting with sources: sends a mouse down/up event to a
+   source.
+
+---------------------
+
+.. function:: void obs_source_send_mouse_move(obs_source_t *source, const struct obs_mouse_event *event, bool mouse_leave)
+
+   Used for interacting with sources: sends a mouse move event to a
+   source.
+
+---------------------
+
+.. function:: void obs_source_send_mouse_wheel(obs_source_t *source, const struct obs_mouse_event *event, int x_delta, int y_delta)
+
+   Used for interacting with sources:  sends a mouse wheel event to a
+   source.
+
+---------------------
+
+.. function:: void obs_source_send_focus(obs_source_t *source, bool focus)
+
+   Used for interacting with sources:  sends a got-focus or lost-focus
+   event to a source.
+
+---------------------
+
+.. function:: void obs_source_send_key_click(obs_source_t *source, const struct obs_key_event *event, bool key_up)
+
+   Used for interacting with sources:  sends a key up/down event to a
+   source.
+
+---------------------
+
+
+Functions used by sources
+-------------------------
+
+.. function:: void obs_source_draw_set_color_matrix(const struct matrix4 *color_matrix, const struct vec3 *color_range_min, const struct vec3 *color_range_max)
+
+   Helper function to set the color matrix information when drawing the
+   source.
+  
+   :param  color_matrix:    The color matrix.  Assigns to the 'color_matrix'
+                            effect variable.
+   :param  color_range_min: The minimum color range.  Assigns to the
+                            'color_range_min' effect variable.  If NULL,
+                            {0.0f, 0.0f, 0.0f} is used.
+   :param  color_range_max: The maximum color range.  Assigns to the
+                            'color_range_max' effect variable.  If NULL,
+                            {1.0f, 1.0f, 1.0f} is used.
+
+---------------------
+
+.. function:: void obs_source_draw(gs_texture_t *image, int x, int y, uint32_t cx, uint32_t cy, bool flip)
+
+   Helper function to draw sprites for a source (synchronous video).
+  
+   :param  image:  The sprite texture to draw.  Assigns to the 'image' variable
+                   of the current effect.
+   :param  x:      X position of the sprite.
+   :param  y:      Y position of the sprite.
+   :param  cx:     Width of the sprite.  If 0, uses the texture width.
+   :param  cy:     Height of the sprite.  If 0, uses the texture height.
+   :param  flip:   Specifies whether to flip the image vertically.
+
+---------------------
+
+.. function:: void obs_source_output_video(obs_source_t *source, const struct obs_source_frame *frame)
+
+   Outputs asynchronous video data.  Set to NULL to deactivate the texture.
+
+   Relevant data types used with this function:
+
+.. code:: cpp
+
+   enum video_format {
+           VIDEO_FORMAT_NONE,
+   
+           /* planar 420 format */
+           VIDEO_FORMAT_I420, /* three-plane */
+           VIDEO_FORMAT_NV12, /* two-plane, luma and packed chroma */
+   
+           /* packed 422 formats */
+           VIDEO_FORMAT_YVYU,
+           VIDEO_FORMAT_YUY2, /* YUYV */
+           VIDEO_FORMAT_UYVY,
+   
+           /* packed uncompressed formats */
+           VIDEO_FORMAT_RGBA,
+           VIDEO_FORMAT_BGRA,
+           VIDEO_FORMAT_BGRX,
+           VIDEO_FORMAT_Y800, /* grayscale */
+   
+           /* planar 4:4:4 */
+           VIDEO_FORMAT_I444,
+   };
+
+   struct obs_source_frame {
+           uint8_t             *data[MAX_AV_PLANES];
+           uint32_t            linesize[MAX_AV_PLANES];
+           uint32_t            width;
+           uint32_t            height;
+           uint64_t            timestamp;
+   
+           enum video_format   format;
+           float               color_matrix[16];
+           bool                full_range;
+           float               color_range_min[3];
+           float               color_range_max[3];
+           bool                flip;
+   };
+
+---------------------
+
+.. function:: void obs_source_preload_video(obs_source_t *source, const struct obs_source_frame *frame)
+
+   Preloads a video frame to ensure a frame is ready for playback as
+   soon as video playback starts.
+
+---------------------
+
+.. function:: void obs_source_show_preloaded_video(obs_source_t *source)
+
+   Shows any preloaded video frame.
+   
+---------------------
+
+.. function:: void obs_source_output_audio(obs_source_t *source, const struct obs_source_audio *audio)
+
+   Outputs audio data.
+
+---------------------
+
+.. function:: void obs_source_update_properties(obs_source_t *source)
+
+   Signal an update to any currently used properties.
+
+---------------------
+
+.. function:: bool obs_source_add_active_child(obs_source_t *parent, obs_source_t *child)
+
+   Adds an active child source.  Must be called by parent sources on child
+   sources when the child is added and active.  This ensures that the source is
+   properly activated if the parent is active.
+  
+   :return: *true* if source can be added, *false* if it causes recursion
+
+---------------------
+
+.. function:: void obs_source_remove_active_child(obs_source_t *parent, obs_source_t *child)
+
+   Removes an active child source.  Must be called by parent sources on child
+   sources when the child is removed or inactive.  This ensures that the source
+   is properly deactivated if the parent is no longer active.
+
+---------------------
+
+
+Filters
+-------
+
+.. function:: obs_source_t *obs_filter_get_parent(const obs_source_t *filter)
+
+   If the source is a filter, returns the parent source of the filter.
+   The parent source is the source being filtered.
+   
+   Only guaranteed to be valid inside of the video_render, filter_audio,
+   filter_video, and filter_remove callbacks.
+
+---------------------
+
+.. function:: obs_source_t *obs_filter_get_target(const obs_source_t *filter)
+
+   If the source is a filter, returns the target source of the filter.
+   The target source is the next source in the filter chain.
+   
+   Only guaranteed to be valid inside of the video_render, filter_audio,
+   filter_video, and filter_remove callbacks.
+
+---------------------
+
+.. function:: void obs_source_default_render(obs_source_t *source)
+
+   Can be used by filters to directly render a non-async parent source
+   without any filter processing.
+
+---------------------
+
+.. function:: void obs_source_filter_add(obs_source_t *source, obs_source_t *filter)
+              void obs_source_filter_remove(obs_source_t *source, obs_source_t *filter)
+
+   Adds/removes a filter to/from a source.
+
+---------------------
+
+.. function:: void obs_source_filter_set_order(obs_source_t *source, obs_source_t *filter, enum obs_order_movement movement)
+
+   Modifies the order of a specific filter.
+
+   :param movement: | Can be one of the following:
+                    | OBS_ORDER_MOVE_UP
+                    | OBS_ORDER_MOVE_DOWN
+                    | OBS_ORDER_MOVE_TOP
+                    | OBS_ORDER_MOVE_BOTTOM
+
+---------------------
+
+
+Functions used by filters
+-------------------------
+
+.. function:: bool obs_source_process_filter_begin(obs_source_t *filter, enum gs_color_format format, enum obs_allow_direct_render allow_direct)
+
+   Default RGB filter handler for generic effect filters.  Processes the
+   filter chain and renders them to texture if needed, then the filter is
+   drawn with.
+  
+   After calling this, set your parameters for the effect, then call
+   obs_source_process_filter_end to draw the filter.
+  
+   :return: *true* if filtering should continue, *false* if the filter
+            is bypassed for whatever reason
+
+---------------------
+
+.. function:: void obs_source_process_filter_end(obs_source_t *filter, gs_effect_t *effect, uint32_t width, uint32_t height)
+
+   Draws the filter using the effect's "Draw" technique.
+  
+   Before calling this function, first call obs_source_process_filter_begin and
+   then set the effect parameters, and then call this function to finalize the
+   filter.
+
+---------------------
+
+.. function:: void obs_source_process_filter_tech_end(obs_source_t *filter, gs_effect_t *effect, uint32_t width, uint32_t height, const char *tech_name)
+
+   Draws the filter with a specific technique in the effect.
+  
+   Before calling this function, first call obs_source_process_filter_begin and
+   then set the effect parameters, and then call this function to finalize the
+   filter.
+
+---------------------
+
+.. function:: void obs_source_skip_video_filter(obs_source_t *filter)
+
+   Skips the filter if the filter is invalid and cannot be rendered.
+
+---------------------
+
+
+.. _transitions:
+
+Transitions
+-----------
+
+.. function:: obs_source_t *obs_transition_get_source(obs_source_t *transition, enum obs_transition_target target)
+
+   :param target: | OBS_TRANSITION_SOURCE_A - Source being transitioned from, or the current source if not transitioning
+                  | OBS_TRANSITION_SOURCE_B - Source being transitioned to
+   :return:       An incremented reference to the source or destination
+                  sources of the transition
+
+---------------------
+
+.. function:: void obs_transition_clear(obs_source_t *transition)
+
+   Clears the transition.
+
+---------------------
+
+.. function:: obs_source_t *obs_transition_get_active_source(obs_source_t *transition)
+
+   :return: An incremented reference to the currently active source of
+            the transition
+
+---------------------
+
+.. function:: bool obs_transition_start(obs_source_t *transition, enum obs_transition_mode mode, uint32_t duration_ms, obs_source_t *dest)
+
+   Starts the transition with the desired destination source.
+
+   :param mode:        Currently only OBS_TRANSITION_MODE_AUTO
+   :param duration_ms: Duration in milliseconds.  If the transition has
+                       a fixed duration set by
+                       :c:func:`obs_transition_enable_fixed`, this
+                       parameter will have no effect
+   :param dest:        The destination source to transition to
+
+---------------------
+
+.. function:: void obs_transition_set_size(obs_source_t *transition, uint32_t cx, uint32_t cy)
+              void obs_transition_get_size(const obs_source_t *transition, uint32_t *cx, uint32_t *cy)
+
+   Sets/gets the dimensions of the transition.
+
+---------------------
+
+.. function:: void obs_transition_set_scale_type(obs_source_t *transition, enum obs_transition_scale_type type)
+              enum obs_transition_scale_type obs_transition_get_scale_type( const obs_source_t *transition)
+
+   Sets/gets the scale type for sources within the transition.
+
+   :param type: | OBS_TRANSITION_SCALE_MAX_ONLY - Scale to aspect ratio, but only to the maximum size of each source
+                | OBS_TRANSITION_SCALE_ASPECT   - Alwasy scale the sources, but keep aspect ratio
+                | OBS_TRANSITION_SCALE_STRETCH  - Scale and stretch the sources to the size of the transision
+
+---------------------
+
+.. function:: void obs_transition_set_alignment(obs_source_t *transition, uint32_t alignment)
+              uint32_t obs_transition_get_alignment(const obs_source_t *transition)
+
+   Sets/gets the alignment used to draw the two sources within
+   transition the transition.
+
+   :param alignment: | Can be any bitwise OR combination of:
+                     | OBS_ALIGN_CENTER
+                     | OBS_ALIGN_LEFT
+                     | OBS_ALIGN_RIGHT
+                     | OBS_ALIGN_TOP
+                     | OBS_ALIGN_BOTTOM
+
+---------------------
+
+
+Functions used by transitions
+-----------------------------
+
+.. function:: void obs_transition_enable_fixed(obs_source_t *transition, bool enable, uint32_t duration_ms)
+              bool obs_transition_fixed(obs_source_t *transition)
+
+   Sets/gets whether the transition uses a fixed duration.  Useful for
+   certain types of transitions such as stingers.  If this is set, the 
+   *duration_ms* parameter of :c:func:`obs_transition_start()` has no
+   effect.
+
+---------------------
+
+.. function:: float obs_transition_get_time(obs_source_t *transition)
+
+   :return: The current transition time value (0.0f..1.0f)
+
+---------------------
+
+.. function:: void obs_transition_video_render(obs_source_t *transition, obs_transition_video_render_callback_t callback)
+
+   Helper function used for rendering transitions.  This function will
+   render two distinct textures for source A and source B of the
+   transition, allowing the ability to blend them together with a pixel
+   shader in a desired manner.
+
+   The *a* and *b* parameters of *callback* are automatically rendered
+   textures of source A and source B, *t* is the time value
+   (0.0f..1.0f), *cx* and *cy* are the current dimensions of the
+   transition, and *data* is the implementation's private data.
+
+   Relevant data types used with this function:
+
+.. code:: cpp
+
+   typedef void (*obs_transition_video_render_callback_t)(void *data,
+                   gs_texture_t *a, gs_texture_t *b, float t,
+                   uint32_t cx, uint32_t cy);
+
+---------------------
+
+.. function::  bool obs_transition_audio_render(obs_source_t *transition, uint64_t *ts_out, struct obs_source_audio_mix *audio, uint32_t mixers, size_t channels, size_t sample_rate, obs_transition_audio_mix_callback_t mix_a_callback, obs_transition_audio_mix_callback_t mix_b_callback)
+
+   Helper function used for transitioning audio.  Typically you'd call
+   this in the obs_source_info.audio_render callback with its
+   parameters, and use the mix_a_callback and mix_b_callback to
+   determine the the audio fading of source A and source B.
+
+   Relevant data types used with this function:
+
+.. code:: cpp
+
+   typedef float (*obs_transition_audio_mix_callback_t)(void *data, float t);
+
+---------------------
+
+.. function:: void obs_transition_swap_begin(obs_source_t *tr_dest, obs_source_t *tr_source)
+              void obs_transition_swap_end(obs_source_t *tr_dest, obs_source_t *tr_source)
+
+   Swaps two transitions.  Call obs_transition_swap_begin, swap the
+   source, then call obs_transition_swap_end when complete.  This allows
+   the ability to seamlessly swap two different transitions without it
+   affecting the output.
+   
+   For example, if a transition is assigned to output channel 0, you'd
+   call obs_transition_swap_begin, then you'd call obs_set_output_source
+   with the new transition, then call
+   :c:func:`obs_transition_swap_begin()`.
+
+.. ---------------------------------------------------------------------------
+
+.. _libobs/obs-source.h: https://github.com/jp9000/obs-studio/blob/master/libobs/obs-source.h