jp9000
/
obs-studio
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs/sphinx: Add sphinx documentation

master
jp9000 2017-10-25 10:52:58 -07:00
parent c111fa68b8
commit d51e2a019b
47 changed files with 13318 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
.gitignore vendored
View File

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

20
docs/sphinx/Makefile Normal file
View File

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

0
docs/sphinx/_build/.gitignore vendored Normal file
View File

0
docs/sphinx/_static/.gitignore vendored Normal file
View File

0
docs/sphinx/_templates/.gitignore vendored Normal file
View File

194
docs/sphinx/backend-design.rst Normal file
View File

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

171
docs/sphinx/conf.py Normal file
View File

@ -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'),
]

252
docs/sphinx/frontends.rst Normal file
View File

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

364
docs/sphinx/graphics.rst Normal file
View File

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

24
docs/sphinx/index.rst Normal file
View File

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

36
docs/sphinx/make.bat Normal file
View File

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

569
docs/sphinx/plugins.rst Normal file
View File

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

13
docs/sphinx/reference-core-objects.rst Normal file
View File

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

643
docs/sphinx/reference-core.rst Normal file
View File

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

493
docs/sphinx/reference-encoders.rst Normal file
View File

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

276
docs/sphinx/reference-libobs-callback.rst Normal file
View File

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

65
docs/sphinx/reference-libobs-graphics-axisang.rst Normal file
View File

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

324
docs/sphinx/reference-libobs-graphics-effects.rst Normal file
View File

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

1459
docs/sphinx/reference-libobs-graphics-graphics.rst Normal file
View File

File diff suppressed because it is too large Load Diff

71
docs/sphinx/reference-libobs-graphics-image-file.rst Normal file
View File

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

39
docs/sphinx/reference-libobs-graphics-math.rst Normal file
View File

@ -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).

151
docs/sphinx/reference-libobs-graphics-matrix4.rst Normal file
View File

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

228
docs/sphinx/reference-libobs-graphics-quat.rst Normal file
View File

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

253
docs/sphinx/reference-libobs-graphics-vec2.rst Normal file
View File

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

306
docs/sphinx/reference-libobs-graphics-vec3.rst Normal file
View File

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

282
docs/sphinx/reference-libobs-graphics-vec4.rst Normal file
View File

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

17
docs/sphinx/reference-libobs-graphics.rst Normal file
View File

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

463
docs/sphinx/reference-libobs-media-io.rst Normal file
View File

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

75
docs/sphinx/reference-libobs-util-base.rst Normal file
View File

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

62
docs/sphinx/reference-libobs-util-bmem.rst Normal file
View File

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

140
docs/sphinx/reference-libobs-util-circlebuf.rst Normal file
View File

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

312
docs/sphinx/reference-libobs-util-config-file.rst Normal file
View File

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

275
docs/sphinx/reference-libobs-util-darray.rst Normal file
View File

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

490
docs/sphinx/reference-libobs-util-dstr.rst Normal file
View File

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

465
docs/sphinx/reference-libobs-util-platform.rst Normal file
View File

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

327
docs/sphinx/reference-libobs-util-profiler.rst Normal file
View File

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

171
docs/sphinx/reference-libobs-util-serializers.rst Normal file
View File

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

56
docs/sphinx/reference-libobs-util-text-lookup.rst Normal file
View File

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

193
docs/sphinx/reference-libobs-util-threading.rst Normal file
View File

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

17
docs/sphinx/reference-libobs-util.rst Normal file
View File

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

310
docs/sphinx/reference-modules.rst Normal file
View File

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

778
docs/sphinx/reference-outputs.rst Normal file
View File

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

597
docs/sphinx/reference-properties.rst Normal file
View File

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

414
docs/sphinx/reference-scenes.rst Normal file
View File

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

276
docs/sphinx/reference-services.rst Normal file
View File

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

279
docs/sphinx/reference-settings.rst Normal file
View File

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

1363
docs/sphinx/reference-sources.rst Normal file
View File

File diff suppressed because it is too large Load Diff