# Table of Contents - [Welcome to OBS Studio’s documentation! — OBS Studio 31.0.2 documentation](#welcome-to-obs-studio-s-documentation-obs-studio-31-0-2-documentation) - [OBS Studio Backend Design — OBS Studio 31.0.2 documentation](#obs-studio-backend-design-obs-studio-31-0-2-documentation) - [Plugins — OBS Studio 31.0.2 documentation](#plugins-obs-studio-31-0-2-documentation) - [Core API Object Reference — OBS Studio 31.0.2 documentation](#core-api-object-reference-obs-studio-31-0-2-documentation) - [Frontends — OBS Studio 31.0.2 documentation](#frontends-obs-studio-31-0-2-documentation) - [Python/Lua Scripting — OBS Studio 31.0.2 documentation](#python-lua-scripting-obs-studio-31-0-2-documentation) - [Rendering Graphics — OBS Studio 31.0.2 documentation](#rendering-graphics-obs-studio-31-0-2-documentation) - [Module API Reference — OBS Studio 31.0.2 documentation](#module-api-reference-obs-studio-31-0-2-documentation) - [OBS Core API Reference — OBS Studio 31.0.2 documentation](#obs-core-api-reference-obs-studio-31-0-2-documentation) - [Service API Reference (obs_service_t) — OBS Studio 31.0.2 documentation](#service-api-reference-obs-service-t-obs-studio-31-0-2-documentation) - [Source API Reference (obs_source_t) — OBS Studio 31.0.2 documentation](#source-api-reference-obs-source-t-obs-studio-31-0-2-documentation) - [Data Settings API Reference (obs_data_t) — OBS Studio 31.0.2 documentation](#data-settings-api-reference-obs-data-t-obs-studio-31-0-2-documentation) - [Properties API Reference (obs_properties_t) — OBS Studio 31.0.2 documentation](#properties-api-reference-obs-properties-t-obs-studio-31-0-2-documentation) - [Platform/Utility API Reference (libobs/util) — OBS Studio 31.0.2 documentation](#platform-utility-api-reference-libobs-util-obs-studio-31-0-2-documentation) - [Encoder API Reference (obs_encoder_t) — OBS Studio 31.0.2 documentation](#encoder-api-reference-obs-encoder-t-obs-studio-31-0-2-documentation) - [Circular Buffers — OBS Studio 31.0.2 documentation](#circular-buffers-obs-studio-31-0-2-documentation) - [Dynamic Arrays — OBS Studio 31.0.2 documentation](#dynamic-arrays-obs-studio-31-0-2-documentation) - [Logging — OBS Studio 31.0.2 documentation](#logging-obs-studio-31-0-2-documentation) - [Scene API Reference (obs_scene_t) — OBS Studio 31.0.2 documentation](#scene-api-reference-obs-scene-t-obs-studio-31-0-2-documentation) - [Output API Reference (obs_output_t) — OBS Studio 31.0.2 documentation](#output-api-reference-obs-output-t-obs-studio-31-0-2-documentation) - [Memory Management — OBS Studio 31.0.2 documentation](#memory-management-obs-studio-31-0-2-documentation) - [Config Files — OBS Studio 31.0.2 documentation](#config-files-obs-studio-31-0-2-documentation) - [Double-Ended Queue — OBS Studio 31.0.2 documentation](#double-ended-queue-obs-studio-31-0-2-documentation) - [Dynamic Strings And String Helpers — OBS Studio 31.0.2 documentation](#dynamic-strings-and-string-helpers-obs-studio-31-0-2-documentation) - [Platform Helpers — OBS Studio 31.0.2 documentation](#platform-helpers-obs-studio-31-0-2-documentation) - [Serializer — OBS Studio 31.0.2 documentation](#serializer-obs-studio-31-0-2-documentation) - [Profiler — OBS Studio 31.0.2 documentation](#profiler-obs-studio-31-0-2-documentation) - [Source Profiler — OBS Studio 31.0.2 documentation](#source-profiler-obs-studio-31-0-2-documentation) - [Text Lookup Interface — OBS Studio 31.0.2 documentation](#text-lookup-interface-obs-studio-31-0-2-documentation) - [Threading — OBS Studio 31.0.2 documentation](#threading-obs-studio-31-0-2-documentation) - [Callback API Reference (libobs/callback) — OBS Studio 31.0.2 documentation](#callback-api-reference-libobs-callback-obs-studio-31-0-2-documentation) - [Graphics API Reference (libobs/graphics) — OBS Studio 31.0.2 documentation](#graphics-api-reference-libobs-graphics-obs-studio-31-0-2-documentation) - [Effects (Shaders) — OBS Studio 31.0.2 documentation](#effects-shaders-obs-studio-31-0-2-documentation) - [2-Component Vector — OBS Studio 31.0.2 documentation](#2-component-vector-obs-studio-31-0-2-documentation) - [4-Component Vector — OBS Studio 31.0.2 documentation](#4-component-vector-obs-studio-31-0-2-documentation) - [Image File Helper — OBS Studio 31.0.2 documentation](#image-file-helper-obs-studio-31-0-2-documentation) - [Matrix — OBS Studio 31.0.2 documentation](#matrix-obs-studio-31-0-2-documentation) - [3-Component Vector — OBS Studio 31.0.2 documentation](#3-component-vector-obs-studio-31-0-2-documentation) - [Extra Math Functions/Macros — OBS Studio 31.0.2 documentation](#extra-math-functions-macros-obs-studio-31-0-2-documentation) - [Quaternion — OBS Studio 31.0.2 documentation](#quaternion-obs-studio-31-0-2-documentation) - [Axis Angle — OBS Studio 31.0.2 documentation](#axis-angle-obs-studio-31-0-2-documentation) - [OBS Studio Frontend API — OBS Studio 31.0.2 documentation](#obs-studio-frontend-api-obs-studio-31-0-2-documentation) - [Core Graphics API — OBS Studio 31.0.2 documentation](#core-graphics-api-obs-studio-31-0-2-documentation) - [Media I/O API Reference (libobs/media-io) — OBS Studio 31.0.2 documentation](#media-i-o-api-reference-libobs-media-io-obs-studio-31-0-2-documentation) --- # Welcome to OBS Studio’s documentation! — OBS Studio 31.0.2 documentation * [](#) * Welcome to OBS Studio’s documentation! * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/index.rst) [Next](backend-design "OBS Studio Backend Design") * * * Welcome to OBS Studio’s documentation![](#welcome-to-obs-studio-s-documentation "Link to this heading") ========================================================================================================= * **Setting up an OBS development environment?** [Use the Wiki](https://obsproject.com/wiki/Install-Instructions) * **Developing your first OBS plugin?** [Use the obs-plugintemplate](https://github.com/obsproject/obs-plugintemplate#obs-plugin-template) Core Concepts * [OBS Studio Backend Design](backend-design) * [Plugins](plugins) * [Frontends](frontends) * [Rendering Graphics](graphics) * [Python/Lua Scripting](scripting) API Reference * [OBS Core](reference-core) * [Initialization, Shutdown, and Information](reference-core#initialization-shutdown-and-information) * [Libobs Objects](reference-core#libobs-objects) * [Video, Audio, and Graphics](reference-core#video-audio-and-graphics) * [Primary signal/procedure handlers](reference-core#primary-signal-procedure-handlers) * [Core OBS Signals](reference-core#core-obs-signals) * [Displays](reference-core#displays) * [Views](reference-core#views) * [Modules](reference-modules) * [Module Macros](reference-modules#module-macros) * [Module Exports](reference-modules#module-exports) * [Module Externs](reference-modules#module-externs) * [Frontend Module Functions](reference-modules#frontend-module-functions) * [Core API Object](reference-core-objects) * [Sources (obs\_source\_t)](reference-sources) * [Scenes (obs\_scene\_t)](reference-scenes) * [Outputs (obs\_output\_t)](reference-outputs) * [Encoders (obs\_encoder\_t)](reference-encoders) * [Services (obs\_service\_t)](reference-services) * [Data Settings (obs\_data\_t)](reference-settings) * [Properties (obs\_properties\_t)](reference-properties) * [Platform/Utility](reference-libobs-util) * [Logging](reference-libobs-util-base) * [Memory Management](reference-libobs-util-bmem) * [Circular Buffers](reference-libobs-util-circlebuf) * [Config Files](reference-libobs-util-config-file) * [Dynamic Arrays](reference-libobs-util-darray) * [Double-Ended Queue](reference-libobs-util-deque) * [Dynamic Strings And String Helpers](reference-libobs-util-dstr) * [Platform Helpers](reference-libobs-util-platform) * [Profiler](reference-libobs-util-profiler) * [Serializer](reference-libobs-util-serializers) * [Array Output Serializer](reference-libobs-util-serializers#array-output-serializer) * [File Input/Output Serializers](reference-libobs-util-serializers#file-input-output-serializers) * [Buffered File Output Serializer](reference-libobs-util-serializers#buffered-file-output-serializer) * [Source Profiler](reference-libobs-util-source-profiler) * [Text Lookup Interface](reference-libobs-util-text-lookup) * [Threading](reference-libobs-util-threading) * [Callbacks (libobs/callback)](reference-libobs-callback) * [Calldata](reference-libobs-callback#calldata) * [Signals](reference-libobs-callback#signals) * [Procedure Handlers](reference-libobs-callback#procedure-handlers) * [Graphics (libobs/graphics)](reference-libobs-graphics) * [Effects (Shaders)](reference-libobs-graphics-effects) * [2-Component Vector](reference-libobs-graphics-vec2) * [3-Component Vector](reference-libobs-graphics-vec3) * [4-Component Vector](reference-libobs-graphics-vec4) * [Quaternion](reference-libobs-graphics-quat) * [Matrix](reference-libobs-graphics-matrix4) * [Extra Math Functions/Macros](reference-libobs-graphics-math) * [Image File Helper](reference-libobs-graphics-image-file) * [Axis Angle](reference-libobs-graphics-axisang) * [Core Graphics API](reference-libobs-graphics-graphics) * [Media I/O (libobs/media-io)](reference-libobs-media-io) * [Video Handler](reference-libobs-media-io#video-handler) * [Audio Handler](reference-libobs-media-io#audio-handler) * [Resampler](reference-libobs-media-io#resampler) * [OBS Studio Frontend API](reference-frontend-api) * [Structures/Enumerations](reference-frontend-api#structures-enumerations) * [Functions](reference-frontend-api#functions) --- # OBS Studio Backend Design — OBS Studio 31.0.2 documentation * [](index) * OBS Studio Backend Design * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/backend-design.rst) [Previous](index "Welcome to OBS Studio’s documentation!") [Next](plugins "Plugins") * * * OBS Studio Backend Design[](#obs-studio-backend-design "Link to this heading") ================================================================================ 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-plugin-objects "Link to this heading") ------------------------------------------------------------------------ Libobs is designed to be modular, where adding modules will add custom functionality. There are four libobs objects that you can make plugins for: * [Sources](plugins#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. * [Outputs](plugins#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. * [Encoders](plugins#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. * [Services](plugins#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[](#libobs-threads "Link to this heading") ---------------------------------------------------------- There are three primary threads spawned by libobs on initialization: * The [obs\_graphics\_thread](https://github.com/obsproject/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-video.c#L588-L651) function used exclusively for rendering in [libobs/obs-video.c](https://github.com/obsproject/obs-studio/blob/master/libobs/obs-video.c) * The [video\_thread](https://github.com/obsproject/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/media-io/video-io.c#L169-L195) function used exclusively for video encoding/output in [libobs/media-io/video-io.c](https://github.com/obsproject/obs-studio/blob/master/libobs/media-io/video-io.c) * The [audio\_thread](https://github.com/obsproject/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/media-io/audio-io.c#L241-L282) function used for all audio processing/encoding/output in [libobs/media-io/audio-io.c](https://github.com/obsproject/obs-studio/blob/master/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 "Link to this heading") ------------------------------------------------------------ Rendering video or audio starts from output channels. You assign a source to an output channel via the [`obs_set_output_source()`](reference-core#c.obs_set_output_source "obs_set_output_source") function. The _channel_ parameter can be any number from 0..([MAX\_CHANNELS](https://github.com/obsproject/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-defs.h#L20-L21) \-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 [Displaying Sources](frontends#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[](#general-video-pipeline-overview "Link to this heading") -------------------------------------------------------------------------------------------- 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](https://github.com/obsproject/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-video.c#L588-L651) function in [libobs/obs-video.c](https://github.com/obsproject/obs-studio/blob/master/libobs/obs-video.c) ), and a dedicated thread specific to video encoding/output (the [video\_thread](https://github.com/obsproject/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/media-io/video-io.c#L169-L195) function in [libobs/media-io/video-io.c](https://github.com/obsproject/obs-studio/blob/master/libobs/media-io/video-io.c) ). Sources assigned to output channels will be drawn from channels 0..([MAX\_CHANNELS](https://github.com/obsproject/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-defs.h#L20-L21) \-1). They are drawn on to the final texture which will be used for output [\[1\]](https://github.com/obsproject/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-video.c#L99-L129) . 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](https://github.com/obsproject/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-internal.h#L250) . It then puts that raw frame in a queue of [MAX\_CACHE\_SIZE](https://github.com/obsproject/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/media-io/video-io.c#L34) in the [video output handler](https://github.com/obsproject/obs-studio/blob/master/libobs/media-io/video-io.c) . 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\]](https://github.com/obsproject/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/media-io/video-io.c#L431-L434) . 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\]](https://github.com/obsproject/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/media-io/video-io.c#L115-L167) . If it’s sent to a video encoder object ([libobs/obs-encoder.c](https://github.com/obsproject/obs-studio/blob/master/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\]](https://github.com/obsproject/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-output.c#L1382-L1439) . The encoded packet or raw frame is then sent to the output. General Audio Pipeline Overview[](#general-audio-pipeline-overview "Link to this heading") -------------------------------------------------------------------------------------------- The audio pipeline is run from a dedicated audio thread in the audio handler (the [audio\_thread](https://github.com/obsproject/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/media-io/audio-io.c#L241-L282) function in [libobs/media-io/audio-io.c](https://github.com/obsproject/obs-studio/blob/master/libobs/media-io/audio-io.c) ); assuming that [AUDIO\_OUTPUT\_FRAMES](https://github.com/obsproject/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/media-io/audio-io.h#L30) 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](https://github.com/obsproject/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-audio.c#L367-L485) function in [libobs/obs-audio.c](https://github.com/obsproject/obs-studio/blob/master/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](https://github.com/obsproject/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-source.c#L2578-L2608) function, and that audio data will be appended or inserted in to the circular buffer [obs\_source::audio\_input\_buf](https://github.com/obsproject/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-source.c#L1280-L1283) . 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\]](https://github.com/obsproject/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-source.c#L2561-L2563) . Before insertion, audio data is also run through any audio filters attached to the source [\[6\]](https://github.com/obsproject/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-source.c#L2591) . 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\]](https://github.com/obsproject/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-audio.c#L393-L415) . 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](https://github.com/obsproject/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-source.c#L1280-L1283) , and puts it in [obs\_source::audio\_output\_buf](https://github.com/obsproject/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-internal.h#L580) . Then, the audio samples stored in [obs\_source::audio\_output\_buf](https://github.com/obsproject/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-internal.h#L580) 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\]](https://github.com/obsproject/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-audio.c#L417-L423) . Sources with multiple children such as scenes or transitions will mix/process their children’s audio themselves via the [obs\_source\_info::audio\_render](https://github.com/obsproject/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-source.h#L410-L412) 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](https://github.com/obsproject/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-internal.h#L580) 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\]](https://github.com/obsproject/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-audio.c#L436-L453) . That final mix is then sent to any raw outputs or audio encoders that are currently active [\[10\]](https://github.com/obsproject/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/media-io/audio-io.c#L144-L165) . If it’s sent to an audio encoder object ([libobs/obs-encoder.c](https://github.com/obsproject/obs-studio/blob/master/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\]](https://github.com/obsproject/obs-studio/blob/2c58185af3c85f4e594a4c067c9dfe5fa4b5b0a9/libobs/obs-output.c#L1382-L1439) . The encoded packet or raw audio data is then sent to the output. --- # Plugins — OBS Studio 31.0.2 documentation * [](index) * Plugins * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/plugins.rst) [Previous](backend-design "OBS Studio Backend Design") [Next](frontends "Frontends") * * * Plugins[](#plugins "Link to this heading") ============================================ 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. Writing your first plugin? We provide [a basic template plugin](https://github.com/obsproject/obs-plugintemplate#obs-plugin-template) to get you started. Plugin Module Headers[](#plugin-module-headers "Link to this heading") ------------------------------------------------------------------------ These are some notable headers commonly used by plugins: * [libobs/obs-module.h](https://github.com/obsproject/obs-studio/blob/master/libobs/obs-module.h) – The primary header used for creating plugin modules. This file automatically includes the following files: * [libobs/obs.h](https://github.com/obsproject/obs-studio/blob/master/libobs/obs.h) – The main libobs header. This file automatically includes the following files: * [libobs/obs-source.h](https://github.com/obsproject/obs-studio/blob/master/libobs/obs-source.h) – Used for implementing sources in plugin modules * [libobs/obs-output.h](https://github.com/obsproject/obs-studio/blob/master/libobs/obs-output.h) – Used for implementing outputs in plugin modules * [libobs/obs-encoder.h](https://github.com/obsproject/obs-studio/blob/master/libobs/obs-encoder.h) – Used for implementing encoders in plugin modules * [libobs/obs-service.h](https://github.com/obsproject/obs-studio/blob/master/libobs/obs-service.h) – Used for implementing services in plugin modules * [libobs/obs-data.h](https://github.com/obsproject/obs-studio/blob/master/libobs/obs-data.h) – Used for managing settings for libobs objects * [libobs/obs-properties.h](https://github.com/obsproject/obs-studio/blob/master/libobs/obs-properties.h) – Used for generating properties for libobs objects * [libobs/graphics/graphics.h](https://github.com/obsproject/obs-studio/blob/master/libobs/graphics/graphics.h) – Used for graphics rendering Common Directory Structure and CMakeLists.txt[](#common-directory-structure-and-cmakelists-txt "Link to this heading") ------------------------------------------------------------------------------------------------------------------------ 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[](#native-plugin-initialization "Link to this heading") -------------------------------------------------------------------------------------- To create a native plugin module, you will need to include the [libobs/obs-module.h](https://github.com/obsproject/obs-studio/blob/master/libobs/obs-module.h) header, use [`OBS_DECLARE_MODULE()`](reference-modules#c.OBS_DECLARE_MODULE "OBS_DECLARE_MODULE") macro, then create a definition of the function [`obs_module_load()`](reference-modules#c.obs_module_load "obs_module_load") . In your [`obs_module_load()`](reference-modules#c.obs_module_load "obs_module_load") function, you then register any of your custom sources, outputs, encoders, or services. See the [Module API Reference](reference-modules) for more information. The following is an example of my-plugin.c, which would register one object of each type: /\* my-plugin.c \*/ #include /\* Defines common functions (required) \*/ OBS\_DECLARE\_MODULE() /\* Implements common ini-based locale (optional) \*/ OBS\_MODULE\_USE\_DEFAULT\_LOCALE("my-plugin", "en-US") extern struct obs\_source\_info my\_source; /\* Defined in my-source.c \*/ extern struct obs\_output\_info my\_output; /\* Defined in my-output.c \*/ extern struct obs\_encoder\_info my\_encoder; /\* Defined in my-encoder.c \*/ extern struct obs\_service\_info my\_service; /\* Defined in my-service.c \*/ bool obs\_module\_load(void) { obs\_register\_source(&my\_source); obs\_register\_output(&my\_output); obs\_register\_encoder(&my\_encoder); obs\_register\_service(&my\_service); return true; } Sources[](#sources "Link to this heading") -------------------------------------------- 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](https://github.com/obsproject/obs-studio/blob/master/libobs/obs-source.h) file is the dedicated header for implementing sources. See the [Source API Reference (obs\_source\_t)](reference-sources) for more information. For example, to implement a source object, you need to define an [`obs_source_info`](reference-sources#c.obs_source_info "obs_source_info") structure and fill it out with information and callbacks related to your source: /\* 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 [`obs_register_source()`](reference-sources#c.obs_register_source "obs_register_source") in [`obs_module_load()`](reference-modules#c.obs_module_load "obs_module_load") to register the source with libobs. /\* 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/obsproject/obs-studio/blob/master/plugins/image-source/image-source.c) * Asynchronous video source: The [random texture test source](https://github.com/obsproject/obs-studio/blob/master/test/test-input/test-random.c) * Audio source: The [sine wave test source](https://github.com/obsproject/obs-studio/blob/master/test/test-input/test-sinewave.c) * Video filter: The [test video filter](https://github.com/obsproject/obs-studio/blob/master/test/test-input/test-filter.c) * Audio filter: The [gain audio filter](https://github.com/obsproject/obs-studio/blob/master/plugins/obs-filters/gain-filter.c) Outputs[](#outputs "Link to this heading") -------------------------------------------- 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](https://github.com/obsproject/obs-studio/blob/master/libobs/obs-output.h) file is the dedicated header for implementing outputs. See the [Output API Reference (obs\_output\_t)](reference-outputs) for more information. For example, to implement an output object, you need to define an [`obs_output_info`](reference-outputs#c.obs_output_info "obs_output_info") structure and fill it out with information and callbacks related to your output: /\* 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 [`obs_register_output()`](reference-outputs#c.obs_register_output "obs_register_output") in [`obs_module_load()`](reference-modules#c.obs_module_load "obs_module_load") to register the output with libobs. /\* 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/obsproject/obs-studio/blob/master/plugins/obs-outputs/flv-output.c) * The [FFmpeg muxer output](https://github.com/obsproject/obs-studio/blob/master/plugins/obs-ffmpeg/obs-ffmpeg-mux.c) * The [RTMP stream output](https://github.com/obsproject/obs-studio/blob/master/plugins/obs-outputs/rtmp-stream.c) * Raw video/audio outputs: * The [FFmpeg output](https://github.com/obsproject/obs-studio/blob/master/plugins/obs-ffmpeg/obs-ffmpeg-output.c) Encoders[](#encoders "Link to this heading") ---------------------------------------------- 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](https://github.com/obsproject/obs-studio/blob/master/libobs/obs-encoder.h) file is the dedicated header for implementing encoders. See the [Encoder API Reference (obs\_encoder\_t)](reference-encoders) for more information. For example, to implement an encoder object, you need to define an [`obs_encoder_info`](reference-encoders#c.obs_encoder_info "obs_encoder_info") structure and fill it out with information and callbacks related to your encoder: /\* 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 [`obs_register_encoder()`](reference-encoders#c.obs_register_encoder "obs_register_encoder") in [`obs_module_load()`](reference-modules#c.obs_module_load "obs_module_load") to register the encoder with libobs. /\* 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/obsproject/obs-studio/tree/master/plugins/obs-x264) * The [FFmpeg NVENC encoder](https://github.com/obsproject/obs-studio/blob/master/plugins/obs-ffmpeg/obs-ffmpeg-nvenc.c) * The [Quicksync encoder](https://github.com/obsproject/obs-studio/tree/master/plugins/obs-qsv11) * Audio encoders: * The [FFmpeg AAC/Opus encoder](https://github.com/obsproject/obs-studio/blob/master/plugins/obs-ffmpeg/obs-ffmpeg-audio-encoders.c) Services[](#services "Link to this heading") ---------------------------------------------- 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](https://github.com/obsproject/obs-studio/blob/master/libobs/obs-service.h) file is the dedicated header for implementing services. See the [Service API Reference (obs\_service\_t)](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 [`obs_service_info`](reference-services#c.obs_service_info "obs_service_info") structure and fill it out with information and callbacks related to your service: /\* 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 [`obs_register_service()`](reference-services#c.obs_register_service "obs_register_service") in [`obs_module_load()`](reference-modules#c.obs_module_load "obs_module_load") to register the service with libobs. /\* 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/obsproject/obs-studio/tree/master/plugins/rtmp-services) Settings[](#settings "Link to this heading") ---------------------------------------------- Settings (see [libobs/obs-data.h](https://github.com/obsproject/obs-studio/blob/master/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 [Data Settings API Reference (obs\_data\_t)](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 [`obs_data_create()`](reference-settings#c.obs_data_create "obs_data_create") or [`obs_data_array_create()`](reference-settings#c.obs_data_array_create "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 [`obs_data_release()`](reference-settings#c.obs_data_release "obs_data_release") or [`obs_data_array_release()`](reference-settings#c.obs_data_array_release "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: /\* 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: /\* 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: /\* 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 "Link to this heading") -------------------------------------------------- Properties (see [libobs/obs-properties.h](https://github.com/obsproject/obs-studio/blob/master/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 [`obs_properties_add_bool()`](reference-properties#c.obs_properties_add_bool "obs_properties_add_bool") to allow the user to be able to change that setting. See the [Properties API Reference (obs\_properties\_t)](reference-properties) for more information. An example of this: 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 [`obs_property_set_modified_callback()`](reference-properties#c.obs_property_set_modified_callback "obs_property_set_modified_callback") function. For example, if you wanted boolean property A to hide text property B: 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[](#localization "Link to this heading") ------------------------------------------------------ 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 [`OBS_MODULE_USE_DEFAULT_LOCALE()`](reference-modules#c.OBS_MODULE_USE_DEFAULT_LOCALE "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 [`obs_module_text()`](reference-modules#c.obs_module_text "obs_module_text") function (which is automatically declared as an extern by [libobs/obs-module.h](https://github.com/obsproject/obs-studio/blob/master/libobs/obs-module.h) ) is used when text lookup is needed. There are two exports the module used to load/destroy locale: the [`obs_module_set_locale()`](reference-modules#c.obs_module_set_locale "obs_module_set_locale") export, and the [`obs_module_free_locale()`](reference-modules#c.obs_module_free_locale "obs_module_free_locale") export. The [`obs_module_set_locale()`](reference-modules#c.obs_module_set_locale "obs_module_set_locale") export is called by libobs to set the current language, and then the [`obs_module_free_locale()`](reference-modules#c.obs_module_free_locale "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 [`obs_module_text()`](reference-modules#c.obs_module_text "obs_module_text") extern yourself instead of relying on the [`OBS_MODULE_USE_DEFAULT_LOCALE()`](reference-modules#c.OBS_MODULE_USE_DEFAULT_LOCALE "OBS_MODULE_USE_DEFAULT_LOCALE") macro. --- # Core API Object Reference — OBS Studio 31.0.2 documentation * [](index) * Core API Object Reference * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/reference-core-objects.rst) [Previous](reference-modules "Module API Reference") [Next](reference-sources "Source API Reference (obs_source_t)") * * * Core API Object Reference[](#core-api-object-reference "Link to this heading") ================================================================================ * [Sources (obs\_source\_t)](reference-sources) * [Source Definition Structure (obs\_source\_info)](reference-sources#source-definition-structure-obs-source-info) * [Common Source Signals](reference-sources#common-source-signals) * [Source-specific Signals](reference-sources#source-specific-signals) * [Source-specific Procedures](reference-sources#source-specific-procedures) * [General Source Functions](reference-sources#general-source-functions) * [Functions used by sources](reference-sources#functions-used-by-sources) * [Filters](reference-sources#filters) * [Functions used by filters](reference-sources#functions-used-by-filters) * [Transitions](reference-sources#transitions) * [Functions used by transitions](reference-sources#functions-used-by-transitions) * [Scenes (obs\_scene\_t)](reference-scenes) * [Scene Item Transform Structure (obs\_transform\_info)](reference-scenes#scene-item-transform-structure-obs-transform-info) * [Scene Item Crop Structure (obs\_sceneitem\_crop)](reference-scenes#scene-item-crop-structure-obs-sceneitem-crop) * [Scene Item Order Info Structure (\*obs\_sceneitem\_order\_info)](reference-scenes#scene-item-order-info-structure-obs-sceneitem-order-info) * [Scene Signals](reference-scenes#scene-signals) * [General Scene Functions](reference-scenes#general-scene-functions) * [Scene Item Functions](reference-scenes#scene-item-functions) * [Scene Item Group Functions](reference-scenes#scene-item-group-functions) * [Outputs (obs\_output\_t)](reference-outputs) * [Output Definition Structure (obs\_output\_info)](reference-outputs#output-definition-structure-obs-output-info) * [Output Signals](reference-outputs#output-signals) * [General Output Functions](reference-outputs#general-output-functions) * [Functions used by outputs](reference-outputs#functions-used-by-outputs) * [Encoders (obs\_encoder\_t)](reference-encoders) * [Encoder Definition Structure (obs\_encoder\_info)](reference-encoders#encoder-definition-structure-obs-encoder-info) * [Encoder Packet Structure (encoder\_packet)](reference-encoders#encoder-packet-structure-encoder-packet) * [Raw Frame Data Structure (encoder\_frame)](reference-encoders#raw-frame-data-structure-encoder-frame) * [Encoder Region of Interest Structure (obs\_encoder\_roi)](reference-encoders#encoder-region-of-interest-structure-obs-encoder-roi) * [General Encoder Functions](reference-encoders#general-encoder-functions) * [Functions used by encoders](reference-encoders#functions-used-by-encoders) * [Services (obs\_service\_t)](reference-services) * [Service Definition Structure](reference-services#service-definition-structure) * [General Service Functions](reference-services#general-service-functions) * [Data Settings (obs\_data\_t)](reference-settings) * [General Functions](reference-settings#general-functions) * [Set Functions](reference-settings#set-functions) * [Get Functions](reference-settings#get-functions) * [Default Value Functions](reference-settings#default-value-functions) * [Autoselect Functions](reference-settings#autoselect-functions) * [Array Functions](reference-settings#array-functions) * [Properties (obs\_properties\_t)](reference-properties) * [General Functions](reference-properties#general-functions) * [Property Object Functions](reference-properties#property-object-functions) * [Property Enumeration Functions](reference-properties#property-enumeration-functions) * [Property Modification Functions](reference-properties#property-modification-functions) --- # Frontends — OBS Studio 31.0.2 documentation * [](index) * Frontends * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/frontends.rst) [Previous](plugins "Plugins") [Next](graphics "Rendering Graphics") * * * Frontends[](#frontends "Link to this heading") ================================================ Initialization and Shutdown[](#initialization-and-shutdown "Link to this heading") ------------------------------------------------------------------------------------ To initialize libobs, you must call [`obs_startup()`](reference-core#c.obs_startup "obs_startup") , [`obs_reset_video()`](reference-core#c.obs_reset_video "obs_reset_video") , and then [`obs_reset_audio()`](reference-core#c.obs_reset_audio "obs_reset_audio") . After that, modules typically should be loaded. You can load individual modules manually by calling [`obs_open_module()`](reference-modules#c.obs_open_module "obs_open_module") . After loading, the [`obs_open_module()`](reference-modules#c.obs_open_module "obs_open_module") function, you must then call [`obs_init_module()`](reference-modules#c.obs_init_module "obs_init_module") to initialize the module. You can load modules automatically via two functions: [`obs_add_module_path()`](reference-modules#c.obs_add_module_path "obs_add_module_path") and [`obs_load_all_modules()`](reference-modules#c.obs_load_all_modules "obs_load_all_modules") . After all plugin modules have been loaded, call [`obs_post_load_modules()`](reference-modules#c.obs_post_load_modules "obs_post_load_modules") . Certain modules may optionally use a configuration storage directory, which is set as a parameter to [`obs_startup()`](reference-core#c.obs_startup "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 [`obs_shutdown()`](reference-core#c.obs_shutdown "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 [`bnum_allocs()`](reference-libobs-util-bmem#c.bnum_allocs "bnum_allocs") to get the number of allocations remaining. If the number remaining is above 0, there are memory leaks. See [Initialization, Shutdown, and Information](reference-core#obs-init-shutdown-reference) for more information. Reconfiguring Video[](#reconfiguring-video "Link to this heading") -------------------------------------------------------------------- Any time after initialization, video settings can be reconfigured by calling [`obs_reset_video()`](reference-core#c.obs_reset_video "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 "Link to this heading") ---------------------------------------------- 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 [`obs_display_create()`](reference-core#c.obs_display_create "obs_display_create") to initialize the display, then you must assign a draw callback with [`obs_display_add_draw_callback()`](reference-core#c.obs_display_add_draw_callback "obs_display_add_draw_callback") . If you need to remove a draw callback, call [`obs_display_remove_draw_callback()`](reference-core#c.obs_display_remove_draw_callback "obs_display_remove_draw_callback") similarly. When drawing, to draw the main preview window (if any), call [`obs_render_main_texture()`](reference-core#c.obs_render_main_texture "obs_render_main_texture") . If you need to render a specific source on a secondary display, you can increment its “showing” state with [`obs_source_inc_showing()`](reference-sources#c.obs_source_inc_showing "obs_source_inc_showing") while it’s showing in the secondary display, draw it with [`obs_source_video_render()`](reference-sources#c.obs_source_video_render "obs_source_video_render") in the draw callback, then when it’s no longer showing in the secondary display, call [`obs_source_dec_showing()`](reference-sources#c.obs_source_dec_showing "obs_source_dec_showing") . If the display needs to be resized, call [`obs_display_resize()`](reference-core#c.obs_display_resize "obs_display_resize") . If the display needs a custom background color other than black, call [`obs_display_set_background_color()`](reference-core#c.obs_display_set_background_color "obs_display_set_background_color") . If the display needs to be temporarily disabled, call [`obs_display_set_enabled()`](reference-core#c.obs_display_set_enabled "obs_display_set_enabled") to disable, and [`obs_display_enabled()`](reference-core#c.obs_display_enabled "obs_display_enabled") to get its enabled/disabled state. Then call [`obs_display_destroy()`](reference-core#c.obs_display_destroy "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 macOS.)_ For an example of how displays are used with Qt, see [UI/qt-display.hpp](https://github.com/obsproject/obs-studio/blob/master/UI/qt-display.hpp) and [UI/qt-display.cpp](https://github.com/obsproject/obs-studio/blob/master/UI/qt-display.cpp) . See [Displays](reference-core#display-reference) for more information. Saving/Loading Objects and Object Management[](#saving-loading-objects-and-object-management "Link to this heading") ---------------------------------------------------------------------------------------------------------------------- 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: [`obs_save_sources()`](reference-core#c.obs_save_sources "obs_save_sources") and [`obs_load_sources()`](reference-core#c.obs_load_sources "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 [`obs_save_source()`](reference-core#c.obs_save_source "obs_save_source") and [`obs_load_source()`](reference-core#c.obs_load_source "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 saveable via the_ [`obs_source_create_private()`](reference-sources#c.obs_source_create_private "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 [`obs_output_get_settings()`](reference-outputs#c.obs_output_get_settings "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 [`obs_data_t`](reference-settings#c.obs_data_t "obs_data_t") object, then save that via [`obs_data_save_json_safe()`](reference-settings#c.obs_data_save_json_safe "obs_data_save_json_safe") , then load everything again via [`obs_data_create_from_json_file_safe()`](reference-settings#c.obs_data_create_from_json_file_safe "obs_data_create_from_json_file_safe") . Signals[](#signals "Link to this heading") -------------------------------------------- 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 [Output Signals](reference-outputs#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 [Common Source Signals](reference-sources#source-signal-handler-reference) and [Scene Signals](reference-scenes#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: 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 [`signal_handler_connect()`](reference-libobs-callback#c.signal_handler_connect "signal_handler_connect") with the callback. In this case for example: signal\_handler\_t \*handler \= obs\_output\_get\_signal\_handler(output); signal\_handler\_connect(handler, "stop", output\_stopped); Displaying Sources[](#displaying-sources "Link to this heading") ------------------------------------------------------------------ Sources are displayed on stream/recording via [Output Channels](backend-design#output-channels) with the [`obs_set_output_source()`](reference-core#c.obs_set_output_source "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 [`obs_scene_create()`](reference-scenes#c.obs_scene_create "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 [`obs_scene_add()`](reference-scenes#c.obs_scene_add "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 [`obs_sceneitem_set_pos()`](reference-scenes#c.obs_sceneitem_set_pos "obs_sceneitem_set_pos") to change its position, [`obs_sceneitem_set_rot()`](reference-scenes#c.obs_sceneitem_set_rot "obs_sceneitem_set_rot") to change its rotation, or [`obs_sceneitem_set_scale()`](reference-scenes#c.obs_sceneitem_set_scale "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 [`obs_sceneitem_set_bounds_type()`](reference-scenes#c.obs_sceneitem_set_bounds_type "obs_sceneitem_set_bounds_type") , [`obs_sceneitem_set_bounds()`](reference-scenes#c.obs_sceneitem_set_bounds "obs_sceneitem_set_bounds") , and [`obs_sceneitem_set_bounds_alignment()`](reference-scenes#c.obs_sceneitem_set_bounds_alignment "obs_sceneitem_set_bounds_alignment") . Though the easiest way to handle everything related to transforms is to use the [`obs_sceneitem_set_info()`](reference-scenes#c.obs_sceneitem_set_info "obs_sceneitem_set_info") and [`obs_sceneitem_get_info()`](reference-scenes#c.obs_sceneitem_get_info "obs_sceneitem_get_info") functions. See [Scene Item Functions](reference-scenes#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 [`obs_source_create()`](reference-sources#c.obs_source_create "obs_source_create") or [`obs_source_create_private()`](reference-sources#c.obs_source_create_private "obs_source_create_private") like any other source. Then, to activate a transition, you call [`obs_transition_start()`](reference-sources#c.obs_transition_start "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 [Transitions](reference-sources#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 [`obs_transition_start()`](reference-sources#c.obs_transition_start "obs_transition_start") . Outputs, Encoders, and Services[](#outputs-encoders-and-services "Link to this heading") ------------------------------------------------------------------------------------------ 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](https://github.com/obsproject/obs-studio/blob/master/plugins/obs-outputs/rtmp-stream.c) is the quintessential example of this. Here’s an example of how an output would be used with encoders and services: 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 [Output Channels](backend-design#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 [`obs_output_get_last_error()`](reference-outputs#c.obs_output_get_last_error "obs_output_get_last_error") function. --- # Python/Lua Scripting — OBS Studio 31.0.2 documentation * [](index) * Python/Lua Scripting * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/scripting.rst) [Previous](graphics "Rendering Graphics") [Next](reference-core "OBS Core API Reference") * * * Python/Lua Scripting[](#python-lua-scripting "Link to this heading") ====================================================================== Scripting (21.0+) adds support for Python 3 and Luajit 2 (which is roughly equivalent to Lua 5.2), allowing the ability to quickly extend, add features, or automate the program without needing to build a native plugin module. Scripting can be accessed in OBS Studio via the Tools menu -> Scripts option, which will bring up the scripting dialog. Scripts can be added, removed, and reloaded in real time while the program is running. **NOTE:** To use Python on Windows or macOS, you must download and install a Python version that matches your OBS architecture. Then, in the scripting dialog, you must set the path to the Python install in the “Python Settings” tab. All API bindings are provided through the **obspython** module in Python, and the **obslua** module in Lua. Certain functions have been changed/replaced in order to provide script callbacks, see [Other Differences From the C API](#other-script-differences) for more information. **WARNING:** Because bindings to the entire API are provided, it is possible to leak memory or crash the program with an improperly-written script. Please exercise caution when making scripts and check the memory leak counter in your log file to make sure scripts you write aren’t leaking memory. **Please treat the API bindings as though you were writing a C program: read the documentation for functions you use, and release/destroy objects you reference or create via the API.** Script Function Exports[](#script-function-exports "Link to this heading") ---------------------------------------------------------------------------- There are a number of global functions that scripts can optionally provide: script\_description()[](#script_description "Link to this definition") Called to retrieve a description string to be displayed to the user in the Scripts window. script\_load(_settings_)[](#script_load "Link to this definition") Called on script startup with specific settings associated with the script. The _settings_ parameter provided is not typically used for settings that are set by the user; instead the parameter is used for any extra internal settings data that may be used in the script. Parameters: **settings** – Settings associated with the script. script\_unload()[](#script_unload "Link to this definition") Called when the script is being unloaded. script\_save(_settings_)[](#script_save "Link to this definition") Called when the script is being saved. This is not necessary for settings that are set by the user; instead this is used for any extra internal settings data that may be used in the script. Parameters: **settings** – Settings associated with the script. script\_defaults(_settings_)[](#script_defaults "Link to this definition") Called to set default settings (if any) associated with the script. You would typically call [Default Value Functions](reference-settings#obs-data-default-funcs) for the on the settings in order to set its default values. Parameters: **settings** – Settings associated with the script. script\_update(_settings_)[](#script_update "Link to this definition") Called when the script’s settings (if any) have been changed by the user. Parameters: **settings** – Settings associated with the script. script\_properties()[](#script_properties "Link to this definition") Called to define user properties associated with the script. These properties are used to define how to show settings properties to a user. Returns: obs\_properties\_t object created via [`obs_properties_create()`](reference-properties#c.obs_properties_create "obs_properties_create") . script\_tick(_seconds_)[](#script_tick "Link to this definition") Called every frame in case per-frame processing is needed. If a timer is needed, please use [Script Timers](#scripting-timers) instead, as timers are more efficient if all that’s needed is basic timer functionality. Using this function in Python is not recommended due to the global interpreter lock of Python. Parameters: **seconds** – Seconds passed since previous frame. Getting the Current Script’s Path[](#getting-the-current-script-s-path "Link to this heading") ------------------------------------------------------------------------------------------------ There is a function you can use to get the current script’s path. This function is automatically implemented in to each script before the script is loaded, and is part of the script’s namespace, not obslua/obspython: script\_path()[](#script_path "Link to this definition") Returns: The path to the script. Script Timers[](#script-timers "Link to this heading") -------------------------------------------------------- Script timers provide an efficient means of providing timer callbacks without necessarily having to lock scripts/interpreters every frame. (These functions are part of the obspython/obslua modules/namespaces). timer\_add(_callback_, _milliseconds_)[](#timer_add "Link to this definition") Adds an timer callback which triggers every _milliseconds_. Note: Using instance methods as callbacks is not supported. Always use module methods. timer\_remove(_callback_)[](#timer_remove "Link to this definition") Removes a timer callback. (Note: You can also use [`remove_current_callback()`](#remove_current_callback "remove_current_callback") to terminate the timer from the timer callback) Script Sources (Lua Only)[](#script-sources-lua-only "Link to this heading") ------------------------------------------------------------------------------ It is possible to register sources in Lua. To do so, create a table, and define its keys the same way you would define an [`obs_source_info`](reference-sources#c.obs_source_info "obs_source_info") structure: local info \= {} info.id \= "my\_source\_id" info.type \= obslua.OBS\_SOURCE\_TYPE\_INPUT info.output\_flags \= obslua.OBS\_SOURCE\_VIDEO info.get\_name \= function() return "My Source" end info.create \= function(settings, source) \-- typically source data would be stored as a table local my\_source\_data \= {} \[...\] return my\_source\_data end info.video\_render \= function(my\_source\_data, effect) \[...\] end info.get\_width \= function(my\_source\_data) \[...\] \-- assuming the source data contains a 'width' key return my\_source\_data.width end info.get\_height \= function(my\_source\_data) \[...\] \-- assuming the source data contains a 'height' key return my\_source\_data.height end \-- register the source obs\_register\_source(info) Other Differences From the C API[](#other-differences-from-the-c-api "Link to this heading") ---------------------------------------------------------------------------------------------- Certain functions are implemented differently from the C API due to how callbacks work. (These functions are part of the obspython/obslua modules/namespaces). obs\_enum\_sources()[](#obs_enum_sources "Link to this definition") Enumerates all sources. Returns: An array of reference-incremented sources. Release with [`source_list_release()`](#source_list_release "source_list_release") . obs\_scene\_enum\_items(_scene_)[](#obs_scene_enum_items "Link to this definition") Enumerates scene items within a scene. Parameters: **scene** – obs\_scene\_t object to enumerate items from. Returns: List of scene items. Release with [`sceneitem_list_release()`](#sceneitem_list_release "sceneitem_list_release") . obs\_sceneitem\_group\_enum\_items(_group_)[](#obs_sceneitem_group_enum_items "Link to this definition") Enumerates scene items within a group. Parameters: **group** – obs\_sceneitem\_t object to enumerate items from. Returns: List of scene items. Release with [`sceneitem_list_release()`](#sceneitem_list_release "sceneitem_list_release") . obs\_add\_main\_render\_callback(_callback_)[](#obs_add_main_render_callback "Link to this definition") **Lua only:** Adds a primary output render callback. This callback has no parameters. Parameters: **callback** – Render callback. Use [`obs_remove_main_render_callback()`](#obs_remove_main_render_callback "obs_remove_main_render_callback") or [`remove_current_callback()`](#remove_current_callback "remove_current_callback") to remove the callback. obs\_remove\_main\_render\_callback(_callback_)[](#obs_remove_main_render_callback "Link to this definition") **Lua only:** Removes a primary output render callback. Parameters: **callback** – Render callback. signal\_handler\_connect(_handler_, _signal_, _callback_)[](#signal_handler_connect "Link to this definition") Adds a callback to a specific signal on a signal handler. This callback has one parameter: the calldata\_t object. Parameters: * **handler** – A signal\_handler\_t object. * **signal** – The signal on the signal handler (string) * **callback** – The callback to connect to the signal. Use [`signal_handler_disconnect()`](#signal_handler_disconnect "signal_handler_disconnect") or [`remove_current_callback()`](#remove_current_callback "remove_current_callback") to remove the callback. signal\_handler\_disconnect(_handler_, _signal_, _callback_)[](#signal_handler_disconnect "Link to this definition") Removes a callback from a specific signal of a signal handler. Parameters: * **handler** – A signal\_handler\_t object. * **signal** – The signal on the signal handler (string) * **callback** – The callback to disconnect from the signal. signal\_handler\_connect\_global(_handler_, _callback_)[](#signal_handler_connect_global "Link to this definition") Adds a global callback to a signal handler. This callback has two parameters: the first parameter is the signal string, and the second parameter is the calldata\_t object. Parameters: * **handler** – A signal\_handler\_t object. * **callback** – The callback to connect. Use [`signal_handler_disconnect_global()`](#signal_handler_disconnect_global "signal_handler_disconnect_global") or [`remove_current_callback()`](#remove_current_callback "remove_current_callback") to remove the callback. signal\_handler\_disconnect\_global(_handler_, _callback_)[](#signal_handler_disconnect_global "Link to this definition") Removes a global callback from a signal handler. Parameters: * **handler** – A signal\_handler\_t object. * **callback** – The callback to disconnect. obs\_hotkey\_register\_frontend(_name_, _description_, _callback_)[](#obs_hotkey_register_frontend "Link to this definition") Adds a frontend hotkey. The callback takes one parameter: a boolean ‘pressed’ parameter. Parameters: * **name** – Unique name identifier string of the hotkey. * **description** – Hotkey description shown to the user. * **callback** – Callback for the hotkey. Use [`obs_hotkey_unregister()`](#obs_hotkey_unregister "obs_hotkey_unregister") or [`remove_current_callback()`](#remove_current_callback "remove_current_callback") to remove the callback. obs\_hotkey\_unregister(_callback_)[](#obs_hotkey_unregister "Link to this definition") Unregisters the hotkey associated with the specified callback. Parameters: **callback** – Callback of the hotkey to unregister. obs\_properties\_add\_button(_properties_, _setting\_name_, _text_, _callback_)[](#obs_properties_add_button "Link to this definition") Adds a button property to an obs\_properties\_t object. The callback takes two parameters: the first parameter is the obs\_properties\_t object, and the second parameter is the obs\_property\_t for the button. Parameters: * **properties** – An obs\_properties\_t object. * **setting\_name** – A setting identifier string. * **text** – Button text. * **callback** – Button callback. This callback is automatically cleaned up. remove\_current\_callback()[](#remove_current_callback "Link to this definition") Removes the current callback being executed. Does nothing if not within a callback. source\_list\_release(_source\_list_)[](#source_list_release "Link to this definition") Releases the references of a source list. Parameters: **source\_list** – Array of sources to release. sceneitem\_list\_release(_item\_list_)[](#sceneitem_list_release "Link to this definition") Releases the references of a scene item list. Parameters: **item\_list** – Array of scene items to release. calldata\_source(_calldata_, _name_)[](#calldata_source "Link to this definition") Casts a pointer parameter of a calldata\_t object to an obs\_source\_t object. Parameters: * **calldata** – A calldata\_t object. * **name** – Name of the parameter. Returns: A borrowed reference to an obs\_source\_t object. calldata\_sceneitem(_calldata_, _name_)[](#calldata_sceneitem "Link to this definition") Casts a pointer parameter of a calldata\_t object to an obs\_sceneitem\_t object. Parameters: * **calldata** – A calldata\_t object. * **name** – Name of the parameter. Returns: A borrowed reference to an obs\_sceneitem\_t object. --- # Rendering Graphics — OBS Studio 31.0.2 documentation * [](index) * Rendering Graphics * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/graphics.rst) [Previous](frontends "Frontends") [Next](scripting "Python/Lua Scripting") * * * Rendering Graphics[](#rendering-graphics "Link to this heading") ================================================================== 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[](#the-graphics-context "Link to this heading") ---------------------------------------------------------------------- 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 [`obs_enter_graphics()`](reference-core#c.obs_enter_graphics "obs_enter_graphics") , and to leave the graphics context, use [`obs_leave_graphics()`](reference-core#c.obs_leave_graphics "obs_leave_graphics") . Certain callback will automatically be within the graphics context: [`obs_source_info.video_render`](reference-sources#c.obs_source_info.video_render "obs_source_info.video_render") , and the draw callback parameter of [`obs_display_add_draw_callback()`](reference-core#c.obs_display_add_draw_callback "obs_display_add_draw_callback") , and [`obs_add_main_render_callback()`](reference-core#c.obs_add_main_render_callback "obs_add_main_render_callback") . Creating Effects[](#creating-effects "Link to this heading") -------------------------------------------------------------- ### Effect Parameters[](#effect-parameters "Link to this heading") 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 [`gs_effect_get_param_by_name()`](reference-libobs-graphics-effects#c.gs_effect_get_param_by_name "gs_effect_get_param_by_name") or [`gs_effect_get_param_by_idx()`](reference-libobs-graphics-effects#c.gs_effect_get_param_by_idx "gs_effect_get_param_by_idx") . Then the uniforms are set through the following functions: * [`gs_effect_set_bool()`](reference-libobs-graphics-effects#c.gs_effect_set_bool "gs_effect_set_bool") * [`gs_effect_set_float()`](reference-libobs-graphics-effects#c.gs_effect_set_float "gs_effect_set_float") * [`gs_effect_set_int()`](reference-libobs-graphics-effects#c.gs_effect_set_int "gs_effect_set_int") * [`gs_effect_set_matrix4()`](reference-libobs-graphics-effects#c.gs_effect_set_matrix4 "gs_effect_set_matrix4") * [`gs_effect_set_vec2()`](reference-libobs-graphics-effects#c.gs_effect_set_vec2 "gs_effect_set_vec2") * [`gs_effect_set_vec3()`](reference-libobs-graphics-effects#c.gs_effect_set_vec3 "gs_effect_set_vec3") * [`gs_effect_set_vec4()`](reference-libobs-graphics-effects#c.gs_effect_set_vec4 "gs_effect_set_vec4") * [`gs_effect_set_texture()`](reference-libobs-graphics-effects#c.gs_effect_set_texture "gs_effect_set_texture") * [`gs_effect_set_texture_srgb()`](reference-libobs-graphics-effects#c.gs_effect_set_texture_srgb "gs_effect_set_texture_srgb") 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 [`obs_source_draw()`](reference-sources#c.obs_source_draw "obs_source_draw") , [`gs_draw_sprite()`](reference-libobs-graphics-graphics#c.gs_draw_sprite "gs_draw_sprite") , and [`obs_source_process_filter_end()`](reference-sources#c.obs_source_process_filter_end "obs_source_process_filter_end") . Here is an example of effect parameters: 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: 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[](#effect-sampler-states "Link to this heading") 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: 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: \[...\] 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[](#effect-vertex-pixel-semantics "Link to this heading") 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: 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: float4 MyPixelShaderFunc(VertInOut vert\_in) : TARGET { return image.Sample(def\_sampler, vert\_in.uv); } ### Effect Techniques[](#effect-techniques "Link to this heading") 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 [`obs_source_process_filter_end()`](reference-sources#c.obs_source_process_filter_end "obs_source_process_filter_end") will automatically call that specific effect name. However, you can also use [`obs_source_process_filter_tech_end()`](reference-sources#c.obs_source_process_filter_tech_end "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: 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[](#using-effects "Link to this heading") -------------------------------------------------------- The recommended way to use effects is like so: 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[](#rendering-video-sources "Link to this heading") ---------------------------------------------------------------------------- A synchronous video source renders in its [`obs_source_info.video_render`](reference-sources#c.obs_source_info.video_render "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 [`obs_source_draw()`](reference-sources#c.obs_source_draw "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 [`obs_get_base_effect()`](reference-core#c.obs_get_base_effect "obs_get_base_effect") function. You can use these effects to render, or you can create custom effects with [`gs_effect_create_from_file()`](reference-libobs-graphics-effects#c.gs_effect_create_from_file "gs_effect_create_from_file") and render with a custom effect. Rendering Video Effect Filters[](#rendering-video-effect-filters "Link to this heading") ------------------------------------------------------------------------------------------ For most video effect filters, it comprises of adding a layer of processing shaders to an existing image in its [`obs_source_info.video_render`](reference-sources#c.obs_source_info.video_render "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 [`obs_source_process_filter_begin()`](reference-sources#c.obs_source_process_filter_begin "obs_source_process_filter_begin") function, set the parameters on your custom effect, then call either [`obs_source_process_filter_end()`](reference-sources#c.obs_source_process_filter_end "obs_source_process_filter_end") or [`obs_source_process_filter_tech_end()`](reference-sources#c.obs_source_process_filter_tech_end "obs_source_process_filter_tech_end") to finish rendering the filter. Here’s an example of rendering a filter from the color key filter: 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); } --- # Module API Reference — OBS Studio 31.0.2 documentation * [](index) * Module API Reference * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/reference-modules.rst) [Previous](reference-core "OBS Core API Reference") [Next](reference-core-objects "Core API Object Reference") * * * Module API Reference[](#module-api-reference "Link to this heading") ====================================================================== Modules add custom functionality to libobs: typically [Sources](plugins#plugins-sources) , [Outputs](plugins#plugins-outputs) , [Encoders](plugins#plugins-encoders) , and [Services](plugins#plugins-services) . type obs\_module\_t[](#c.obs_module_t "Link to this definition") A module object (not reference counted). #include Module Macros[](#module-macros "Link to this heading") -------------------------------------------------------- These macros are used within custom plugin modules. OBS\_DECLARE\_MODULE()[](#c.OBS_DECLARE_MODULE "Link to this definition") Declares a libobs module. Exports important core module functions related to the module itself, OBS version, etc. * * * OBS\_MODULE\_USE\_DEFAULT\_LOCALE(module\_name, default\_locale)[](#c.OBS_MODULE_USE_DEFAULT_LOCALE "Link to this definition") Helper macro that uses the standard ini file format for localization. Automatically initializes and destroys localization data, and automatically provides module externs such as [`obs_module_text()`](#c.obs_module_text "obs_module_text") to be able to get a localized string with little effort. * * * Module Exports[](#module-exports "Link to this heading") ---------------------------------------------------------- These are functions that plugin modules can optionally export in order to communicate with libobs and front-ends. bool obs\_module\_load(void)[](#c.obs_module_load "Link to this definition") 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. Returns: Return true to continue loading the module, otherwise false to indicate failure and unload the module * * * void obs\_module\_unload(void)[](#c.obs_module_unload "Link to this definition") Optional: Called when the module is unloaded. * * * void obs\_module\_post\_load(void)[](#c.obs_module_post_load "Link to this definition") Optional: Called when all modules have finished loading. * * * void obs\_module\_set\_locale(const char \*locale)[](#c.obs_module_set_locale "Link to this definition") Called to set the locale language and load the locale data for the module. * * * void obs\_module\_free\_locale(void)[](#c.obs_module_free_locale "Link to this definition") Called on module destruction to free locale data. * * * const char \*obs\_module\_name(void)[](#c.obs_module_name "Link to this definition") (Optional) Returns: The full name of the module * * * const char \*obs\_module\_description(void)[](#c.obs_module_description "Link to this definition") (Optional) Returns: A description of the module * * * Module Externs[](#module-externs "Link to this heading") ---------------------------------------------------------- These functions are externs that are usable throughout the module. const char \*obs\_module\_text(const char \*lookup\_string)[](#c.obs_module_text "Link to this definition") Returns: A localized string * * * bool obs\_module\_get\_string(const char \*lookup\_string, const char \*\*translated\_string)[](#c.obs_module_get_string "Link to this definition") Helper function for looking up locale. Returns: _true_ if text found, otherwise _false_ * * * [obs\_module\_t](#c.obs_module_t "obs_module_t") \*obs\_current\_module(void)[](#c.obs_current_module "Link to this definition") Returns: The current module * * * char \*obs\_module\_file(const char \*file)[](#c.obs_module_file "Link to this definition") Returns the location to a module data file associated with the current module. Free with [`bfree()`](reference-libobs-util-bmem#c.bfree "bfree") when complete. Equivalent to: obs\_find\_module\_file(obs\_current\_module(), file); * * * char \*obs\_module\_config\_path(const char \*file)[](#c.obs_module_config_path "Link to this definition") Returns the location to a module config file associated with the current module. Free with [`bfree()`](reference-libobs-util-bmem#c.bfree "bfree") when complete. Will return NULL if configuration directory is not set. Equivalent to: obs\_module\_get\_config\_path(obs\_current\_module(), file); * * * Frontend Module Functions[](#frontend-module-functions "Link to this heading") -------------------------------------------------------------------------------- These are functions used by frontends to load and get information about plugin modules. int obs\_open\_module([obs\_module\_t](#c.obs_module_t "obs_module_t") \*\*module, const char \*path, const char \*data\_path)[](#c.obs_open_module "Link to this definition") 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 [`obs_init_module()`](#c.obs_init_module "obs_init_module") . Parameters: * **module** – The pointer to the created module * **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 * **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 MODULE\_HARDCODED\_SKIP - Skipped by hardcoded rules (e.g. obsolete obs-browser macOS plugin) * * * bool obs\_init\_module([obs\_module\_t](#c.obs_module_t "obs_module_t") \*module)[](#c.obs_init_module "Link to this definition") Initializes the module, which calls its obs\_module\_load export. Returns: _true_ if the module was loaded successfully * * * void obs\_log\_loaded\_modules(void)[](#c.obs_log_loaded_modules "Link to this definition") Logs loaded modules. * * * const char \*obs\_get\_module\_file\_name([obs\_module\_t](#c.obs_module_t "obs_module_t") \*module)[](#c.obs_get_module_file_name "Link to this definition") Returns: The module file name * * * const char \*obs\_get\_module\_name([obs\_module\_t](#c.obs_module_t "obs_module_t") \*module)[](#c.obs_get_module_name "Link to this definition") Returns: The module full name (or _NULL_ if none) * * * void obs\_get\_module\_author([obs\_module\_t](#c.obs_module_t "obs_module_t") \*module)[](#c.obs_get_module_author "Link to this definition") Returns: The module author(s) * * * const char \*obs\_get\_module\_description([obs\_module\_t](#c.obs_module_t "obs_module_t") \*module)[](#c.obs_get_module_description "Link to this definition") Returns: The module description * * * const char \*obs\_get\_module\_binary\_path([obs\_module\_t](#c.obs_module_t "obs_module_t") \*module)[](#c.obs_get_module_binary_path "Link to this definition") Returns: The module binary path * * * const char \*obs\_get\_module\_data\_path([obs\_module\_t](#c.obs_module_t "obs_module_t") \*module)[](#c.obs_get_module_data_path "Link to this definition") Returns: The module data path * * * void obs\_add\_module\_path(const char \*bin, const char \*data)[](#c.obs_add_module_path "Link to this definition") 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. Parameters: * **bin** – Specifies the module’s binary directory search path * **data** – Specifies the module’s data directory search path * * * void obs\_load\_all\_modules(void)[](#c.obs_load_all_modules "Link to this definition") Automatically loads all modules from module paths (convenience function). * * * void obs\_load\_all\_modules2(struct obs\_module\_failure\_info \*mfi)[](#c.obs_load_all_modules2 "Link to this definition") Automatically loads all modules from module paths (convenience function). Additionally gives you information about modules that fail to load. Parameters: * **mfi** – Provides module failure information. The _failed\_modules_ member is a string list via a pointer to pointers of strings of modules that failed to load. Can be freed either with [`obs_module_failure_info_free()`](#c.obs_module_failure_info_free "obs_module_failure_info_free") or by simply calling [`bfree()`](reference-libobs-util-bmem#c.bfree "bfree") on the _failed\_modules_ member variable. Relevant data types used with this function: struct obs\_module\_failure\_info { char \*\*failed\_modules; size\_t count; }; * * * void obs\_add\_safe\_module(const char \*name)[](#c.obs_add_safe_module "Link to this definition") Adds a _name_ to the list of modules allowed to load in Safe Mode. If the list is empty, all modules are allowed. Parameters: * **name** – The name of the module (filename sans extension). Added in version 30.0. * * * void obs\_module\_failure\_info\_free(struct obs\_module\_failure\_info \*mfi)[](#c.obs_module_failure_info_free "Link to this definition") Frees data allocated data used in the _mfi_ parameter (calls [`bfree()`](reference-libobs-util-bmem#c.bfree "bfree") on the _failed\_modules_ member variable). * * * void obs\_post\_load\_modules(void)[](#c.obs_post_load_modules "Link to this definition") Notifies modules that all modules have been loaded. * * * void obs\_find\_modules(obs\_find\_module\_callback\_t callback, void \*param)[](#c.obs_find_modules "Link to this definition") Finds all modules within the search paths added by [`obs_add_module_path()`](#c.obs_add_module_path "obs_add_module_path") . Relevant data types used with this function: 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); * * * void obs\_find\_modules2(obs\_find\_module\_callback\_t callback, void \*param)[](#c.obs_find_modules2 "Link to this definition") Finds all modules within the search paths added by [`obs_add_module_path()`](#c.obs_add_module_path "obs_add_module_path") . Relevant data types used with this function: struct obs\_module\_info2 { const char \*bin\_path; const char \*data\_path; const char \*name; }; typedef void (\*obs\_find\_module\_callback2\_t)(void \*param, const struct obs\_module\_info2 \*info); * * * void obs\_enum\_modules(obs\_enum\_module\_callback\_t callback, void \*param)[](#c.obs_enum_modules "Link to this definition") Enumerates all loaded modules. Relevant data types used with this function: typedef void (\*obs\_enum\_module\_callback\_t)(void \*param, obs\_module\_t \*module); * * * char \*obs\_find\_module\_file([obs\_module\_t](#c.obs_module_t "obs_module_t") \*module, const char \*file)[](#c.obs_find_module_file "Link to this definition") 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. Parameters: * **module** – The module associated with the file to locate * **file** – The file to locate Returns: Path string, or NULL if not found. Use bfree to free string * * * char \*obs\_module\_get\_config\_path([obs\_module\_t](#c.obs_module_t "obs_module_t") \*module, const char \*file)[](#c.obs_module_get_config_path "Link to this definition") 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. Parameters: * **module** – The module associated with the path * **file** – The file to get a path to Returns: Path string, or NULL if not found. Use bfree to free string * * * void \*obs\_get\_module\_lib([obs\_module\_t](#c.obs_module_t "obs_module_t") \*module)[](#c.obs_get_module_lib "Link to this definition") Returns library file of specified module. Parameters: * **module** – The module where to find library file. Returns: Pointer to module library. --- # OBS Core API Reference — OBS Studio 31.0.2 documentation * [](index) * OBS Core API Reference * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/reference-core.rst) [Previous](scripting "Python/Lua Scripting") [Next](reference-modules "Module API Reference") * * * OBS Core API Reference[](#obs-core-api-reference "Link to this heading") ========================================================================== #include Initialization, Shutdown, and Information[](#initialization-shutdown-and-information "Link to this heading") -------------------------------------------------------------------------------------------------------------- bool obs\_startup(const char \*locale, const char \*module\_config\_path, [profiler\_name\_store\_t](reference-libobs-util-profiler#c.profiler_name_store_t "profiler_name_store_t") \*store)[](#c.obs_startup "Link to this definition") Initializes the OBS core context. Parameters: * **locale** – The locale to use for modules (E.G. “en-US”) * **module\_config\_path** – Path to module config storage directory (or _NULL_ if none) * **store** – The profiler name store for OBS to use or NULL Returns: _false_ if already initialized or failed to initialize * * * void obs\_shutdown(void)[](#c.obs_shutdown "Link to this definition") Releases all data associated with OBS and terminates the OBS context. * * * bool obs\_initialized(void)[](#c.obs_initialized "Link to this definition") Returns: true if the main OBS context has been initialized * * * uint32\_t obs\_get\_version(void)[](#c.obs_get_version "Link to this definition") Returns: The current core version * * * const char \*obs\_get\_version\_string(void)[](#c.obs_get_version_string "Link to this definition") Returns: The current core version string * * * void obs\_set\_locale(const char \*locale)[](#c.obs_set_locale "Link to this definition") Sets a new locale to use for modules. This will call [`obs_module_set_locale()`](reference-modules#c.obs_module_set_locale "obs_module_set_locale") for each module with the new locale. Parameters: * **locale** – The locale to use for modules * * * const char \*obs\_get\_locale(void)[](#c.obs_get_locale "Link to this definition") Returns: The current locale * * * [profiler\_name\_store\_t](reference-libobs-util-profiler#c.profiler_name_store_t "profiler_name_store_t") \*obs\_get\_profiler\_name\_store(void)[](#c.obs_get_profiler_name_store "Link to this definition") Returns: The profiler name store (see util/profiler.h) used by OBS, which is either a name store passed to [`obs_startup()`](#c.obs_startup "obs_startup") , an internal name store, or NULL in case [`obs_initialized()`](#c.obs_initialized "obs_initialized") returns false. * * * int obs\_reset\_video(struct obs\_video\_info \*ovi)[](#c.obs_reset_video "Link to this definition") 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. Parameters: * **ovi** – Pointer to an obs\_video\_info structure containing the specification of the graphics subsystem, Returns: 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: 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 \*/ }; * * * bool obs\_reset\_audio(const struct obs\_audio\_info \*oai)[](#c.obs_reset_audio "Link to this definition") Sets base audio output format/channels/samples/etc. Note: Cannot reset base audio if an output is currently active. Returns: _true_ if successful, _false_ otherwise Relevant data types used with this function: struct obs\_audio\_info { uint32\_t samples\_per\_sec; enum speaker\_layout speakers; }; * * * bool obs\_reset\_audio2(const struct obs\_audio\_info2 \*oai)[](#c.obs_reset_audio2 "Link to this definition") Sets base audio output format/channels/samples/etc. Also allows the ability to set the maximum audio latency of OBS, and set whether the audio buffering is fixed or dynamically increasing. When using fixed audio buffering, OBS will automatically buffer to the maximum audio latency on startup. Maximum audio latency will clamp to the closest multiple of the audio output frames (which is typically 1024 audio frames). Note: Cannot reset base audio if an output is currently active. Returns: _true_ if successful, _false_ otherwise Relevant data types used with this function: struct obs\_audio\_info2 { uint32\_t samples\_per\_sec; enum speaker\_layout speakers; uint32\_t max\_buffering\_ms; bool fixed\_buffering; }; * * * bool obs\_get\_video\_info(struct obs\_video\_info \*ovi)[](#c.obs_get_video_info "Link to this definition") Gets the current video settings. Returns: _false_ if no video * * * float obs\_get\_video\_sdr\_white\_level(void)[](#c.obs_get_video_sdr_white_level "Link to this definition") Gets the current SDR white level. Returns: SDR white level, 300.f if no video * * * float obs\_get\_video\_hdr\_nominal\_peak\_level(void)[](#c.obs_get_video_hdr_nominal_peak_level "Link to this definition") Gets the current HDR nominal peak level. Returns: HDR nominal peak level, 1000.f if no video * * * void obs\_set\_video\_sdr\_white\_level(float sdr\_white\_level, float hdr\_nominal\_peak\_level)[](#c.obs_set_video_sdr_white_level "Link to this definition") Sets the current video levels. * * * bool obs\_get\_audio\_info(struct obs\_audio\_info \*oai)[](#c.obs_get_audio_info "Link to this definition") Gets the current audio settings. Returns: _false_ if no audio * * * Libobs Objects[](#libobs-objects "Link to this heading") ---------------------------------------------------------- bool obs\_enum\_source\_types(size\_t idx, const char \*\*id)[](#c.obs_enum_source_types "Link to this definition") Enumerates all source types (inputs, filters, transitions, etc). * * * bool obs\_enum\_input\_types(size\_t idx, const char \*\*id)[](#c.obs_enum_input_types "Link to this definition") Enumerates all available inputs source types. Inputs are general source inputs (such as capture sources, device sources, etc). * * * bool obs\_enum\_filter\_types(size\_t idx, const char \*\*id)[](#c.obs_enum_filter_types "Link to this definition") Enumerates all available filter source types. Filters are sources that are used to modify the video/audio output of other sources. * * * bool obs\_enum\_transition\_types(size\_t idx, const char \*\*id)[](#c.obs_enum_transition_types "Link to this definition") Enumerates all available transition source types. Transitions are sources used to transition between two or more other sources. * * * bool obs\_enum\_output\_types(size\_t idx, const char \*\*id)[](#c.obs_enum_output_types "Link to this definition") Enumerates all available output types. * * * bool obs\_enum\_encoder\_types(size\_t idx, const char \*\*id)[](#c.obs_enum_encoder_types "Link to this definition") Enumerates all available encoder types. * * * bool obs\_enum\_service\_types(size\_t idx, const char \*\*id)[](#c.obs_enum_service_types "Link to this definition") Enumerates all available service types. * * * void obs\_enum\_sources(bool (\*enum\_proc)(void\*, [obs\_source\_t](reference-sources#c.obs_source_t "obs_source_t") \*), void \*param)[](#c.obs_enum_sources "Link to this definition") Enumerates all input sources. Callback function returns true to continue enumeration, or false to end enumeration. Use [`obs_source_get_ref()`](reference-sources#c.obs_source_get_ref "obs_source_get_ref") or [`obs_source_get_weak_source()`](reference-sources#c.obs_source_get_weak_source "obs_source_get_weak_source") if you want to retain a reference after obs\_enum\_sources finishes. For scripting, use [`obs_enum_sources()`](scripting#obs_enum_sources "obs_enum_sources") . * * * void obs\_enum\_scenes(bool (\*enum\_proc)(void\*, [obs\_source\_t](reference-sources#c.obs_source_t "obs_source_t") \*), void \*param)[](#c.obs_enum_scenes "Link to this definition") Enumerates all scenes. Use [`obs_scene_from_source()`](reference-scenes#c.obs_scene_from_source "obs_scene_from_source") if the scene is needed as an [`obs_scene_t`](reference-scenes#c.obs_scene_t "obs_scene_t") . The order that they are enumerated should not be relied on. If one intends to enumerate the scenes in the order presented by the OBS Studio Frontend, use [`obs_frontend_get_scenes()`](reference-frontend-api#c.obs_frontend_get_scenes "obs_frontend_get_scenes") . Callback function returns true to continue enumeration, or false to end enumeration. Use [`obs_source_get_ref()`](reference-sources#c.obs_source_get_ref "obs_source_get_ref") or [`obs_source_get_weak_source()`](reference-sources#c.obs_source_get_weak_source "obs_source_get_weak_source") if you want to retain a reference after obs\_enum\_scenes finishes. * * * void obs\_enum\_outputs(bool (\*enum\_proc)(void\*, [obs\_output\_t](reference-outputs#c.obs_output_t "obs_output_t") \*), void \*param)[](#c.obs_enum_outputs "Link to this definition") Enumerates outputs. Callback function returns true to continue enumeration, or false to end enumeration. Use [`obs_output_get_ref()`](reference-outputs#c.obs_output_get_ref "obs_output_get_ref") or [`obs_output_get_weak_output()`](reference-outputs#c.obs_output_get_weak_output "obs_output_get_weak_output") if you want to retain a reference after obs\_enum\_outputs finishes. * * * void obs\_enum\_encoders(bool (\*enum\_proc)(void\*, [obs\_encoder\_t](reference-encoders#c.obs_encoder_t "obs_encoder_t") \*), void \*param)[](#c.obs_enum_encoders "Link to this definition") Enumerates encoders. Callback function returns true to continue enumeration, or false to end enumeration. Use [`obs_encoder_get_ref()`](reference-encoders#c.obs_encoder_get_ref "obs_encoder_get_ref") or [`obs_encoder_get_weak_encoder()`](reference-encoders#c.obs_encoder_get_weak_encoder "obs_encoder_get_weak_encoder") if you want to retain a reference after obs\_enum\_encoders finishes. * * * [obs\_source\_t](reference-sources#c.obs_source_t "obs_source_t") \*obs\_get\_source\_by\_name(const char \*name)[](#c.obs_get_source_by_name "Link to this definition") Gets a source by its name. Increments the source reference counter, use [`obs_source_release()`](reference-sources#c.obs_source_release "obs_source_release") to release it when complete. * * * [obs\_source\_t](reference-sources#c.obs_source_t "obs_source_t") \*obs\_get\_source\_by\_uuid(const char \*uuid)[](#c.obs_get_source_by_uuid "Link to this definition") Gets a source by its UUID. Increments the source reference counter, use [`obs_source_release()`](reference-sources#c.obs_source_release "obs_source_release") to release it when complete. Added in version 29.1. * * * [obs\_source\_t](reference-sources#c.obs_source_t "obs_source_t") \*obs\_get\_transition\_by\_name(const char \*name)[](#c.obs_get_transition_by_name "Link to this definition") Gets a transition by its name. Increments the source reference counter, use [`obs_source_release()`](reference-sources#c.obs_source_release "obs_source_release") to release it when complete. * * * [obs\_source\_t](reference-sources#c.obs_source_t "obs_source_t") \*obs\_get\_transition\_by\_uuid(const char \*uuid)[](#c.obs_get_transition_by_uuid "Link to this definition") Gets a transition by its UUID. Increments the source reference counter, use [`obs_source_release()`](reference-sources#c.obs_source_release "obs_source_release") to release it when complete. Added in version 29.1. * * * [obs\_scene\_t](reference-scenes#c.obs_scene_t "obs_scene_t") \*obs\_get\_scene\_by\_name(const char \*name)[](#c.obs_get_scene_by_name "Link to this definition") Gets a scene by its name. Increments the scene reference counter, use [`obs_scene_release()`](reference-scenes#c.obs_scene_release "obs_scene_release") to release it when complete. * * * [obs\_output\_t](reference-outputs#c.obs_output_t "obs_output_t") \*obs\_get\_output\_by\_name(const char \*name)[](#c.obs_get_output_by_name "Link to this definition") Gets an output by its name. Increments the output reference counter, use [`obs_output_release()`](reference-outputs#c.obs_output_release "obs_output_release") to release it when complete. * * * [obs\_encoder\_t](reference-encoders#c.obs_encoder_t "obs_encoder_t") \*obs\_get\_encoder\_by\_name(const char \*name)[](#c.obs_get_encoder_by_name "Link to this definition") Gets an encoder by its name. Increments the encoder reference counter, use [`obs_encoder_release()`](reference-encoders#c.obs_encoder_release "obs_encoder_release") to release it when complete. * * * [obs\_service\_t](reference-services#c.obs_service_t "obs_service_t") \*obs\_get\_service\_by\_name(const char \*name)[](#c.obs_get_service_by_name "Link to this definition") Gets an service by its name. Increments the service reference counter, use [`obs_service_release()`](reference-services#c.obs_service_release "obs_service_release") to release it when complete. * * * [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*obs\_save\_source([obs\_source\_t](reference-sources#c.obs_source_t "obs_source_t") \*source)[](#c.obs_save_source "Link to this definition") Returns: A new reference to a source’s saved data. Use [`obs_data_release()`](reference-settings#c.obs_data_release "obs_data_release") to release it when complete. * * * [obs\_source\_t](reference-sources#c.obs_source_t "obs_source_t") \*obs\_load\_source([obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*data)[](#c.obs_load_source "Link to this definition") Returns: A source created from saved data * * * void obs\_load\_sources([obs\_data\_array\_t](reference-settings#c.obs_data_array_t "obs_data_array_t") \*array, obs\_load\_source\_cb cb, void \*private\_data)[](#c.obs_load_sources "Link to this definition") Helper function to load active sources from a data array. Relevant data types used with this function: typedef void (\*obs\_load\_source\_cb)(void \*private\_data, obs\_source\_t \*source); * * * [obs\_data\_array\_t](reference-settings#c.obs_data_array_t "obs_data_array_t") \*obs\_save\_sources(void)[](#c.obs_save_sources "Link to this definition") Returns: A data array with the saved data of all active sources * * * [obs\_data\_array\_t](reference-settings#c.obs_data_array_t "obs_data_array_t") \*obs\_save\_sources\_filtered(obs\_save\_source\_filter\_cb cb, void \*data)[](#c.obs_save_sources_filtered "Link to this definition") Returns: A data array with the saved data of all active sources, filtered by the _cb_ function Relevant data types used with this function: typedef bool (\*obs\_save\_source\_filter\_cb)(void \*data, obs\_source\_t \*source); * * * Video, Audio, and Graphics[](#video-audio-and-graphics "Link to this heading") -------------------------------------------------------------------------------- void obs\_enter\_graphics(void)[](#c.obs_enter_graphics "Link to this definition") Helper function for entering the OBS graphics context. * * * void obs\_leave\_graphics(void)[](#c.obs_leave_graphics "Link to this definition") Helper function for leaving the OBS graphics context. * * * [audio\_t](reference-libobs-media-io#c.audio_t "audio_t") \*obs\_get\_audio(void)[](#c.obs_get_audio "Link to this definition") Returns: The main audio output handler for this OBS context * * * [video\_t](reference-libobs-media-io#c.video_t "video_t") \*obs\_get\_video(void)[](#c.obs_get_video "Link to this definition") Returns: The main video output handler for this OBS context * * * void obs\_set\_output\_source(uint32\_t channel, [obs\_source\_t](reference-sources#c.obs_source_t "obs_source_t") \*source)[](#c.obs_set_output_source "Link to this definition") Sets the primary output source for a channel. * * * [obs\_source\_t](reference-sources#c.obs_source_t "obs_source_t") \*obs\_get\_output\_source(uint32\_t channel)[](#c.obs_get_output_source "Link to this definition") Gets the primary output source for a channel and increments the reference counter for that source. Use [`obs_source_release()`](reference-sources#c.obs_source_release "obs_source_release") to release. * * * [gs\_effect\_t](reference-libobs-graphics-effects#c.gs_effect_t "gs_effect_t") \*obs\_get\_base\_effect(enum obs\_base\_effect effect)[](#c.obs_get_base_effect "Link to this definition") Returns a commonly used base effect. Parameters: * **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 * * * void obs\_render\_main\_texture(void)[](#c.obs_render_main_texture "Link to this definition") Renders the main output texture. Useful for rendering a preview pane of the main output. * * * bool obs\_audio\_monitoring\_available(void)[](#c.obs_audio_monitoring_available "Link to this definition") Returns: Whether audio monitoring is supported and available on the current platform * * * void obs\_reset\_audio\_monitoring(void)[](#c.obs_reset_audio_monitoring "Link to this definition") Resets all audio monitoring devices. Added in version 30.1. * * * void obs\_enum\_audio\_monitoring\_devices(obs\_enum\_audio\_device\_cb cb, void \*data)[](#c.obs_enum_audio_monitoring_devices "Link to this definition") Enumerates audio devices which can be used for audio monitoring. Callback function returns true to continue enumeration, or false to end enumeration. Relevant data types used with this function: typedef bool (\*obs\_enum\_audio\_device\_cb)(void \*data, const char \*name, const char \*id); * * * bool obs\_set\_audio\_monitoring\_device(const char \*name, const char \*id)[](#c.obs_set_audio_monitoring_device "Link to this definition") Sets the current audio device for audio monitoring. * * * void obs\_get\_audio\_monitoring\_device(const char \*\*name, const char \*\*id)[](#c.obs_get_audio_monitoring_device "Link to this definition") Gets the current audio device for audio monitoring. * * * void obs\_add\_main\_render\_callback(void (\*draw)(void \*param, uint32\_t cx, uint32\_t cy), void \*param)[](#c.obs_add_main_render_callback "Link to this definition") void obs\_remove\_main\_render\_callback(void (\*draw)(void \*param, uint32\_t cx, uint32\_t cy), void \*param)[](#c.obs_remove_main_render_callback "Link to this definition") Adds/removes a main rendering callback. Allows custom rendering to the main stream/recording output. For scripting (**Lua only**), use [`obs_add_main_render_callback()`](scripting#obs_add_main_render_callback "obs_add_main_render_callback") and [`obs_remove_main_render_callback()`](scripting#obs_remove_main_render_callback "obs_remove_main_render_callback") . * * * void obs\_add\_main\_rendered\_callback(void (\*rendered)(void \*param), void \*param)[](#c.obs_add_main_rendered_callback "Link to this definition") void obs\_remove\_main\_rendered\_callback(void (\*rendered)(void \*param), void \*param)[](#c.obs_remove_main_rendered_callback "Link to this definition") Adds/removes a main rendered callback. Allows using the result of the main stream/recording output. Added in version 29.1. * * * void obs\_add\_raw\_video\_callback(const struct video\_scale\_info \*conversion, void (\*callback)(void \*param, struct [video\_data](reference-libobs-media-io#c.video_data "video_data") \*frame), void \*param)[](#c.obs_add_raw_video_callback "Link to this definition") void obs\_remove\_raw\_video\_callback(void (\*callback)(void \*param, struct [video\_data](reference-libobs-media-io#c.video_data "video_data") \*frame), void \*param)[](#c.obs_remove_raw_video_callback "Link to this definition") Adds/removes a raw video callback. Allows the ability to obtain raw video frames without necessarily using an output. Parameters: * **conversion** – Specifies conversion requirements. Can be NULL. * **callback** – The callback that receives raw video frames. * **param** – The private data associated with the callback. * * * void obs\_add\_raw\_audio\_callback(size\_t mix\_idx, const struct [audio\_convert\_info](reference-libobs-media-io#c.audio_convert_info "audio_convert_info") \*conversion, [audio\_output\_callback\_t](reference-libobs-media-io#c.audio_output_callback_t "audio_output_callback_t") callback, void \*param)[](#c.obs_add_raw_audio_callback "Link to this definition") void obs\_remove\_raw\_raw\_callback(size\_t track, [audio\_output\_callback\_t](reference-libobs-media-io#c.audio_output_callback_t "audio_output_callback_t") callback, void \*param)[](#c.obs_remove_raw_raw_callback "Link to this definition") Adds/removes a raw audio callback. Allows the ability to obtain raw audio data without necessarily using an output. Parameters: * **mix\_idx** – Specifies audio track to get data from. * **conversion** – Specifies conversion requirements. Can be NULL. * **callback** – The callback that receives raw audio data. * **param** – The private data associated with the callback. Primary signal/procedure handlers[](#primary-signal-procedure-handlers "Link to this heading") ------------------------------------------------------------------------------------------------ [signal\_handler\_t](reference-libobs-callback#c.signal_handler_t "signal_handler_t") \*obs\_get\_signal\_handler(void)[](#c.obs_get_signal_handler "Link to this definition") Returns: The primary obs signal handler. Should not be manually freed, as its lifecycle is managed by libobs. See [Core OBS Signals](#core-signal-handler-reference) for more information on core signals. * * * [proc\_handler\_t](reference-libobs-callback#c.proc_handler_t "proc_handler_t") \*obs\_get\_proc\_handler(void)[](#c.obs_get_proc_handler "Link to this definition") Returns: The primary obs procedure handler. Should not be manually freed, as its lifecycle is managed by libobs. Core OBS Signals[](#core-obs-signals "Link to this heading") -------------------------------------------------------------- **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 ([`obs_source_remove()`](reference-sources#c.obs_source_remove "obs_source_remove") > has been called on the source). **source\_update** (ptr source) > Called when a source’s settings have been updated. **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\_audio\_activate** (ptr source) > Called when a source’s audio becomes active. **source\_audio\_deactivate** (ptr source) > Called when a source’s audio becomes inactive. **source\_filter\_add** (ptr source, ptr filter) > Called when a filter is added to a source. **source\_filter\_remove** (ptr source, ptr filter) > Called when a filter is removed from a source. **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 [`obs_set_output_source()`](#c.obs_set_output_source "obs_set_output_source") > has been called. **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. * * * Displays[](#displays "Link to this heading") ---------------------------------------------- obs\_display\_t \*obs\_display\_create(const struct [gs\_init\_data](reference-libobs-graphics-graphics#c.gs_init_data "gs_init_data") \*graphics\_data)[](#c.obs_display_create "Link to this definition") 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 macOS.)_ Parameters: * **graphics\_data** – The swap chain initialization data Returns: The new display context, or NULL if failed Relevant data types used with this function: 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; }; * * * void obs\_display\_destroy(obs\_display\_t \*display)[](#c.obs_display_destroy "Link to this definition") Destroys a display context. * * * void obs\_display\_resize(obs\_display\_t \*display, uint32\_t cx, uint32\_t cy)[](#c.obs_display_resize "Link to this definition") Changes the size of a display context. * * * void obs\_display\_add\_draw\_callback(obs\_display\_t \*display, void (\*draw)(void \*param, uint32\_t cx, uint32\_t cy), void \*param)[](#c.obs_display_add_draw_callback "Link to this definition") Adds a draw callback for a display context, which will be called whenever the display is rendered. Parameters: * **display** – The display context * **draw** – The draw callback which is called each time a frame updates * **param** – The user data to be associated with this draw callback * * * void obs\_display\_remove\_draw\_callback(obs\_display\_t \*display, void (\*draw)(void \*param, uint32\_t cx, uint32\_t cy), void \*param)[](#c.obs_display_remove_draw_callback "Link to this definition") Removes a draw callback for a display context. * * * void obs\_display\_set\_enabled(obs\_display\_t \*display, bool enable)[](#c.obs_display_set_enabled "Link to this definition") Enables/disables a display context. * * * bool obs\_display\_enabled(obs\_display\_t \*display)[](#c.obs_display_enabled "Link to this definition") Returns: _true_ if the display is enabled, _false_ otherwise * * * void obs\_display\_set\_background\_color(obs\_display\_t \*display, uint32\_t color)[](#c.obs_display_set_background_color "Link to this definition") Sets the background (clear) color for the display context. Views[](#views "Link to this heading") ---------------------------------------- obs\_view\_t \*obs\_view\_create(void)[](#c.obs_view_create "Link to this definition") Returns: A view context * * * void obs\_view\_destroy(obs\_view\_t \*view)[](#c.obs_view_destroy "Link to this definition") Destroys a view context. * * * void obs\_view\_render(obs\_view\_t \*view)[](#c.obs_view_render "Link to this definition") Renders the sources of this view context. * * * [video\_t](reference-libobs-media-io#c.video_t "video_t") \*obs\_view\_add(obs\_view\_t \*view)[](#c.obs_view_add "Link to this definition") Renders the sources of this view context. Returns: The main video output handler for the view context * * * [video\_t](reference-libobs-media-io#c.video_t "video_t") \*obs\_view\_add2(obs\_view\_t \*view, struct obs\_video\_info \*ovi)[](#c.obs_view_add2 "Link to this definition") Adds a view to the main render loop, with custom video settings. Returns: The main video output handler for the view context * * * void obs\_view\_remove(obs\_view\_t \*view)[](#c.obs_view_remove "Link to this definition") Removes a view from the main render loop. * * * void obs\_view\_set\_source(obs\_view\_t \*view, uint32\_t channel, [obs\_source\_t](reference-sources#c.obs_source_t "obs_source_t") \*source)[](#c.obs_view_set_source "Link to this definition") Sets the source to be used for this view context. * * * [obs\_source\_t](reference-sources#c.obs_source_t "obs_source_t") \*obs\_view\_get\_source(obs\_view\_t \*view, uint32\_t channel)[](#c.obs_view_get_source "Link to this definition") Returns: The source currently in use for this view context * * * bool obs\_view\_get\_video\_info(obs\_view\_t \*view, struct obs\_video\_info \*ovi)[](#c.obs_view_get_video_info "Link to this definition") Gets the video settings of the first matching mix currently in use for this view context. Returns: _false_ if no video Deprecated since version 3X.X. * * * void obs\_view\_enum\_video\_info(obs\_view\_t \*view, bool (\*enum\_proc)(void\*, struct obs\_video\_info\*), void \*param)[](#c.obs_view_enum_video_info "Link to this definition") Enumerates all the video info of all mixes that use the specified mix. Added in version 30.1. --- # Service API Reference (obs_service_t) — OBS Studio 31.0.2 documentation * [](index) * [Core API Object Reference](reference-core-objects) * Service API Reference (obs\_service\_t) * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/reference-services.rst) [Previous](reference-encoders "Encoder API Reference (obs_encoder_t)") [Next](reference-settings "Data Settings API Reference (obs_data_t)") * * * Service API Reference (obs\_service\_t)[](#service-api-reference-obs-service-t "Link to this heading") ======================================================================================================== 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](https://github.com/obsproject/obs-studio/blob/master/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[](#c.obs_service_t "Link to this definition") A reference-counted service object. type obs\_weak\_service\_t[](#c.obs_weak_service_t "Link to this definition") A weak reference to a service object. #include Service Definition Structure[](#service-definition-structure "Link to this heading") -------------------------------------------------------------------------------------- struct obs\_service\_info[](#c.obs_service_info "Link to this definition") Service definition structure. const char \*[obs\_service\_info](#c.obs_service_info "obs_service_info") .id[](#c.obs_service_info.id "Link to this definition") Unique string identifier for the service (required). const char \*(\*[obs\_service\_info](#c.obs_service_info "obs_service_info") .get\_name)(void \*type\_data)[](#c.obs_service_info.get_name "Link to this definition") 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 void \*(\*[obs\_service\_info](#c.obs_service_info "obs_service_info") .create)([obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*settings, [obs\_service\_t](#c.obs_service_t "obs_service_t") \*service)[](#c.obs_service_info.create "Link to this definition") 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 void (\*[obs\_service\_info](#c.obs_service_info "obs_service_info") .destroy)(void \*data)[](#c.obs_service_info.destroy "Link to this definition") Destroys the implementation data for the service. void (\*[obs\_service\_info](#c.obs_service_info "obs_service_info") .get\_defaults)([obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*settings)[](#c.obs_service_info.get_defaults "Link to this definition") void (\*[obs\_service\_info](#c.obs_service_info "obs_service_info") .get\_defaults2)(void \*type\_data, [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*settings)[](#c.obs_service_info.get_defaults2 "Link to this definition") 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 [obs\_properties\_t](reference-properties#c.obs_properties_t "obs_properties_t") \*(\*[obs\_service\_info](#c.obs_service_info "obs_service_info") .get\_properties)(void \*data)[](#c.obs_service_info.get_properties "Link to this definition") [obs\_properties\_t](reference-properties#c.obs_properties_t "obs_properties_t") \*(\*[obs\_service\_info](#c.obs_service_info "obs_service_info") .get\_properties2)(void \*data, void \*type\_data)[](#c.obs_service_info.get_properties2 "Link to this definition") Gets the property information of this service. (Optional) Return: The properties of the service void (\*[obs\_service\_info](#c.obs_service_info "obs_service_info") .update)(void \*data, [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*settings)[](#c.obs_service_info.update "Link to this definition") Updates the settings for this service. (Optional) Param settings: New settings for this service bool (\*[obs\_service\_info](#c.obs_service_info "obs_service_info") .initialize)(void \*data, [obs\_output\_t](reference-outputs#c.obs_output_t "obs_output_t") \*output)[](#c.obs_service_info.initialize "Link to this definition") 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 const char \*(\*[obs\_service\_info](#c.obs_service_info "obs_service_info") .get\_url)(void \*data)[](#c.obs_service_info.get_url "Link to this definition") Return: The stream URL const char \*(\*[obs\_service\_info](#c.obs_service_info "obs_service_info") .get\_key)(void \*data)[](#c.obs_service_info.get_key "Link to this definition") Return: The stream key const char \*(\*[obs\_service\_info](#c.obs_service_info "obs_service_info") .get\_username)(void \*data)[](#c.obs_service_info.get_username "Link to this definition") (Optional) Return: The username const char \*(\*[obs\_service\_info](#c.obs_service_info "obs_service_info") .get\_password)(void \*data)[](#c.obs_service_info.get_password "Link to this definition") (Optional) Return: The password void (\*[obs\_service\_info](#c.obs_service_info "obs_service_info") .apply\_encoder\_settings)(void \*data, [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*video\_encoder\_settings, [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*audio\_encoder\_settings)[](#c.obs_service_info.apply_encoder_settings "Link to this definition") 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 [`obs_service_apply_encoder_settings()`](#c.obs_service_apply_encoder_settings "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 void \*[obs\_service\_info](#c.obs_service_info "obs_service_info") .type\_data[](#c.obs_service_info.type_data "Link to this definition") void (\*[obs\_service\_info](#c.obs_service_info "obs_service_info") .free\_type\_data)(void \*type\_data)[](#c.obs_service_info.free_type_data "Link to this definition") 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) const char \*(\*[obs\_service\_info](#c.obs_service_info "obs_service_info") .get\_output\_type)(void \*data)[](#c.obs_service_info.get_output_type "Link to this definition") (Optional) Return: The output type that should be preferred with this service const char \*\*(\*get\_supported\_video\_codecs)(void \*data)[](#c.get_supported_video_codecs "Link to this definition") (Optional) Return: A string pointer array of the supported video codecs, should be stored by the plugin so the caller does not need to free the data manually (typically best to use strlist\_split to generate this) const char \*\*(\*get\_supported\_audio\_codecs)(void \*data)[](#c.get_supported_audio_codecs "Link to this definition") (Optional) Return: A string pointer array of the supported audio codecs, should be stored by the plugin so the caller does not need to free the data manually (typically best to use strlist\_split to generate this) Added in version 29.1. const char \*(\*[obs\_service\_info](#c.obs_service_info "obs_service_info") .get\_protocol)(void \*data)[](#c.obs_service_info.get_protocol "Link to this definition") Return: The protocol used by the service Added in version 29.1. const char \*(\*[obs\_service\_info](#c.obs_service_info "obs_service_info") .get\_connect\_info)(void \*data, uint32\_t type)[](#c.obs_service_info.get_connect_info "Link to this definition") Output a service connection info related to a given type value: * **OBS\_SERVICE\_CONNECT\_INFO\_SERVER\_URL** - Server URL (0) * **OBS\_SERVICE\_CONNECT\_INFO\_STREAM\_ID** - Stream ID (2) * **OBS\_SERVICE\_CONNECT\_INFO\_STREAM\_KEY** - Stream key (alias of **OBS\_SERVICE\_CONNECT\_INFO\_STREAM\_ID**) * **OBS\_SERVICE\_CONNECT\_INFO\_USERNAME** - Username (4) * **OBS\_SERVICE\_CONNECT\_INFO\_PASSWORD** - Password (6) * **OBS\_SERVICE\_CONNECT\_INFO\_ENCRYPT\_PASSPHRASE** - Encryption passphrase (8) * Odd values as types are reserved for third-party protocols Depending on the protocol, the service will have to provide information to the output to be able to connect. Irrelevant or unused types can return NULL. Added in version 29.1. bool (\*[obs\_service\_info](#c.obs_service_info "obs_service_info") .can\_try\_to\_connect)(void \*data)[](#c.obs_service_info.can_try_to_connect "Link to this definition") (Optional) Return: If the service has all the needed connection info to be able to connect. NOTE: If not set, [`obs_service_can_try_to_connect()`](#c.obs_service_can_try_to_connect "obs_service_can_try_to_connect") returns _true_ by default. Added in version 29.1. General Service Functions[](#general-service-functions "Link to this heading") -------------------------------------------------------------------------------- void obs\_register\_service(struct [obs\_service\_info](#c.obs_service_info "obs_service_info") \*info)[](#c.obs_register_service "Link to this definition") Registers a service type. Typically used in [`obs_module_load()`](reference-modules#c.obs_module_load "obs_module_load") or in the program’s initialization phase. * * * const char \*obs\_service\_get\_display\_name(const char \*id)[](#c.obs_service_get_display_name "Link to this definition") Calls the [`obs_service_info.get_name`](#c.obs_service_info.get_name "obs_service_info.get_name") callback to get the translated display name of a service type. Parameters: * **id** – The service type string identifier Returns: The translated display name of a service type * * * [obs\_service\_t](#c.obs_service_t "obs_service_t") \*obs\_service\_create(const char \*id, const char \*name, [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*settings, [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*hotkey\_data)[](#c.obs_service_create "Link to this definition") Creates a service with the specified settings. The “service” context is used for encoding video/audio data. Use obs\_service\_release to release it. Parameters: * **id** – The service type string identifier * **name** – The desired name of the service. If this is not unique, it will be made to be unique * **settings** – The settings for the service, or _NULL_ if none * **hotkey\_data** – Saved hotkey data for the service, or _NULL_ if none Returns: A reference to the newly created service, or _NULL_ if failed * * * [obs\_service\_t](#c.obs_service_t "obs_service_t") \*obs\_service\_get\_ref([obs\_service\_t](#c.obs_service_t "obs_service_t") \*service)[](#c.obs_service_get_ref "Link to this definition") Returns an incremented reference if still valid, otherwise returns _NULL_. Release with [`obs_service_release()`](#c.obs_service_release "obs_service_release") . * * * void obs\_service\_release([obs\_service\_t](#c.obs_service_t "obs_service_t") \*service)[](#c.obs_service_release "Link to this definition") Releases a reference to a service. When the last reference is released, the service is destroyed. * * * [obs\_weak\_service\_t](#c.obs_weak_service_t "obs_weak_service_t") \*obs\_service\_get\_weak\_service([obs\_service\_t](#c.obs_service_t "obs_service_t") \*service)[](#c.obs_service_get_weak_service "Link to this definition") [obs\_service\_t](#c.obs_service_t "obs_service_t") \*obs\_weak\_service\_get\_service([obs\_weak\_service\_t](#c.obs_weak_service_t "obs_weak_service_t") \*weak)[](#c.obs_weak_service_get_service "Link to this definition") 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_. * * * void obs\_weak\_service\_addref([obs\_weak\_service\_t](#c.obs_weak_service_t "obs_weak_service_t") \*weak)[](#c.obs_weak_service_addref "Link to this definition") void obs\_weak\_service\_release([obs\_weak\_service\_t](#c.obs_weak_service_t "obs_weak_service_t") \*weak)[](#c.obs_weak_service_release "Link to this definition") Adds/releases a weak reference to a service. * * * const char \*obs\_service\_get\_name(const [obs\_service\_t](#c.obs_service_t "obs_service_t") \*service)[](#c.obs_service_get_name "Link to this definition") Returns: The name of the service * * * [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*obs\_service\_defaults(const char \*id)[](#c.obs_service_defaults "Link to this definition") Returns: An incremented reference to the service’s default settings. Release with [`obs_data_release()`](reference-settings#c.obs_data_release "obs_data_release") . * * * [obs\_properties\_t](reference-properties#c.obs_properties_t "obs_properties_t") \*obs\_service\_properties(const [obs\_service\_t](#c.obs_service_t "obs_service_t") \*service)[](#c.obs_service_properties "Link to this definition") [obs\_properties\_t](reference-properties#c.obs_properties_t "obs_properties_t") \*obs\_get\_service\_properties(const char \*id)[](#c.obs_get_service_properties "Link to this definition") 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. Returns: The properties list for a specific existing service. Free with [`obs_properties_destroy()`](reference-properties#c.obs_properties_destroy "obs_properties_destroy") * * * [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*obs\_service\_get\_settings(const [obs\_service\_t](#c.obs_service_t "obs_service_t") \*service)[](#c.obs_service_get_settings "Link to this definition") Returns: An incremented reference to the service’s settings. Release with [`obs_data_release()`](reference-settings#c.obs_data_release "obs_data_release") . * * * void obs\_service\_update([obs\_service\_t](#c.obs_service_t "obs_service_t") \*service, [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*settings)[](#c.obs_service_update "Link to this definition") Updates the settings for this service context. * * * void obs\_service\_apply\_encoder\_settings([obs\_service\_t](#c.obs_service_t "obs_service_t") \*service, [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*video\_encoder\_settings, [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*audio\_encoder\_settings)[](#c.obs_service_apply_encoder_settings "Link to this definition") Applies service-specific video encoder settings. Parameters: * **video\_encoder\_settings** – Video encoder settings. Can be _NULL_ * **audio\_encoder\_settings** – Audio encoder settings. Can be _NULL_ * * * const char \*\*obs\_service\_get\_supported\_video\_codecs(const [obs\_service\_t](#c.obs_service_t "obs_service_t") \*service)[](#c.obs_service_get_supported_video_codecs "Link to this definition") Returns: An array of string pointers containing the supported video codecs for the service, terminated with a _NULL_ pointer. Does not need to be freed * * * const char \*\*obs\_service\_get\_supported\_audio\_codecs(const [obs\_service\_t](#c.obs_service_t "obs_service_t") \*service)[](#c.obs_service_get_supported_audio_codecs "Link to this definition") Returns: An array of string pointers containing the supported audio codecs for the service, terminated with a _NULL_ pointer. Does not need to be freed Added in version 29.1. * * * const char \*obs\_service\_get\_protocol(const [obs\_service\_t](#c.obs_service_t "obs_service_t") \*service)[](#c.obs_service_get_protocol "Link to this definition") Returns: Protocol currently used for this service Added in version 29.1. * * * const char \*obs\_service\_get\_preferred\_output\_type(const [obs\_service\_t](#c.obs_service_t "obs_service_t") \*service)[](#c.obs_service_get_preferred_output_type "Link to this definition") Returns: The output type that should be preferred with this service Added in version 29.1. * * * const char \*obs\_service\_get\_connect\_info(const [obs\_service\_t](#c.obs_service_t "obs_service_t") \*service, uint32\_t type)[](#c.obs_service_get_connect_info "Link to this definition") Parameters: * **type** – Check [`obs_service_info.get_connect_info`](#c.obs_service_info.get_connect_info "obs_service_info.get_connect_info") for type values. Returns: Connection info related to the type value. Added in version 29.1. * * * bool obs\_service\_can\_try\_to\_connect(const [obs\_service\_t](#c.obs_service_t "obs_service_t") \*service)[](#c.obs_service_can_try_to_connect "Link to this definition") Returns: If the service has all the needed connection info to be able to connect. Returns true if [`obs_service_info.can_try_to_connect`](#c.obs_service_info.can_try_to_connect "obs_service_info.can_try_to_connect") is not set. Added in version 29.1. --- # Source API Reference (obs_source_t) — OBS Studio 31.0.2 documentation * [](index) * [Core API Object Reference](reference-core-objects) * Source API Reference (obs\_source\_t) * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/reference-sources.rst) [Previous](reference-core-objects "Core API Object Reference") [Next](reference-scenes "Scene API Reference (obs_scene_t)") * * * Source API Reference (obs\_source\_t)[](#source-api-reference-obs-source-t "Link to this heading") ==================================================================================================== 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](https://github.com/obsproject/obs-studio/blob/master/libobs/obs-source.h) file is the dedicated header for implementing sources. type obs\_source\_t[](#c.obs_source_t "Link to this definition") A reference-counted video/audio input source. type obs\_weak\_source\_t[](#c.obs_weak_source_t "Link to this definition") A weak reference to an video/audio input source. #include Source Definition Structure (obs\_source\_info)[](#source-definition-structure-obs-source-info "Link to this heading") ------------------------------------------------------------------------------------------------------------------------ struct obs\_source\_info[](#c.obs_source_info "Link to this definition") Source definition structure. const char \*[obs\_source\_info](#c.obs_source_info "obs_source_info") .id[](#c.obs_source_info.id "Link to this definition") Unique string identifier for the source (required). uint32\_t version[](#c.version "Link to this definition") Source version (optional). This is used when a source’s implementation is significantly modified and the previous version is deprecated, but is kept to prevent old sources from breaking. enum obs\_source\_type [obs\_source\_info](#c.obs_source_info "obs_source_info") .type[](#c.obs_source_info.type "Link to this definition") Type of source. * **OBS\_SOURCE\_TYPE\_INPUT** - Video/Audio Input * **OBS\_SOURCE\_TYPE\_FILTER** - Filter * **OBS\_SOURCE\_TYPE\_TRANSITION** - Transition uint32\_t [obs\_source\_info](#c.obs_source_info "obs_source_info") .output\_flags[](#c.obs_source_info.output_flags "Link to this definition") Source output capability flags (required). (Author’s note: This should be renamed to “capability\_flags”) A bitwise OR combination of one or more of the following values: * **OBS\_SOURCE\_VIDEO** - Source has video Unless SOURCE\_ASYNC\_VIDEO is specified, the source must include the [`obs_source_info.video_render`](#c.obs_source_info.video_render "obs_source_info.video_render") callback in the source definition structure. * **OBS\_SOURCE\_AUDIO** - Source has audio Use the [`obs_source_output_audio()`](#c.obs_source_output_audio "obs_source_output_audio") function to pass raw audio data, which will be automatically converted and uploaded. If used with OBS\_SOURCE\_ASYNC\_VIDEO, audio will automatically be synced up to the video output based upon their mutual timestamps. * **OBS\_SOURCE\_ASYNC** - Video is asynchronous (use OBS\_SOURCE\_ASYNC\_VIDEO instead to automatically combine this flag with the OBS\_SOURCE\_VIDEO flag). * **OBS\_SOURCE\_ASYNC\_VIDEO** - Source passes raw video data via RAM Use the [`obs_source_output_video()`](#c.obs_source_output_video "obs_source_output_video") function to pass raw video data, which will be automatically drawn at a timing relative to the provided timestamp. If audio is also present on the source, the audio will automatically be synced to the video based upon their mutual timestamps. * **OBS\_SOURCE\_CUSTOM\_DRAW** - Source uses custom graphics calls, rather than just rendering a single texture. This capability flag must be used if the source does not use [`obs_source_draw()`](#c.obs_source_draw "obs_source_draw") to render a single texture. This capability flag is an important hint to turn off a specific optimization that allows the first effect filter in the filter chain to render the source directly with that effect filter. The optimization does not work if there are custom graphics calls, and the source must be rendered to a texture first before being sent to the first filter in the filter chain. (Author’s note: Ironically, not many sources render with that optimization. I should have made it so that the optimization isn’t used by default, and a flag should have been used to turn on the optimization – not turn it off). * **OBS\_SOURCE\_INTERACTION** - Source can be interacted with by the user. When this is used, the source will receive interaction events if these callbacks are provided: [`obs_source_info.mouse_click`](#c.obs_source_info.mouse_click "obs_source_info.mouse_click") , [`obs_source_info.mouse_move`](#c.obs_source_info.mouse_move "obs_source_info.mouse_move") , [`obs_source_info.mouse_wheel`](#c.obs_source_info.mouse_wheel "obs_source_info.mouse_wheel") , [`obs_source_info.focus`](#c.obs_source_info.focus "obs_source_info.focus") , and [`obs_source_info.key_click`](#c.obs_source_info.key_click "obs_source_info.key_click") . * **OBS\_SOURCE\_COMPOSITE** - Source composites child sources When used, specifies that the source composites one or more child sources. Scenes and transitions are examples of sources that contain and render child sources. Sources that render sub-sources must implement the audio\_render callback in order to perform custom audio mixing of child sources. This capability flag is always set for transitions. * **OBS\_SOURCE\_DO\_NOT\_DUPLICATE** - Source should not be fully duplicated. When this is used, specifies that the source should not be fully duplicated, and should prefer to duplicate via holding references rather than full duplication. When functions such as [`obs_source_duplicate()`](#c.obs_source_duplicate "obs_source_duplicate") or [`obs_scene_duplicate()`](reference-scenes#c.obs_scene_duplicate "obs_scene_duplicate") are called, sources or child sources with this flag will never be fully duplicated, and will instead only be referenced. An example of the type of sources that should not be fully duplicated are video devices, browsers, and video/audio captures, as they will either not function correctly or will cause performance or resource issues when duplicated. * **OBS\_SOURCE\_DEPRECATED** - Source is deprecated and should not be used. * **OBS\_SOURCE\_DO\_NOT\_SELF\_MONITOR** - Audio of this source should not allow monitoring if the current monitoring device is the same device being captured by the source. This flag is used as a hint to the back-end to prevent the source from creating an audio feedback loop. This is primarily only used with desktop audio capture sources. * **OBS\_SOURCE\_CAP\_DISABLED** - This source type has been disabled and should not be shown as a type of source the user can add. * **OBS\_SOURCE\_CAP\_OBSOLETE** - This source type is obsolete and should not be shown as a type of source the user can add. Identical to _OBS\_SOURCE\_CAP\_DISABLED_. Meant to be used when a source has changed in some way (mostly defaults/properties), but you want to avoid breaking older configurations. Basically solves the problem of “I want to change the defaults of a source but I don’t want to break people’s configurations” * **OBS\_SOURCE\_CONTROLLABLE\_MEDIA** - This source has media that can be controlled * **OBS\_SOURCE\_MONITOR\_BY\_DEFAULT** - Source should enable monitoring by default. Monitoring should be set by the frontend if this flag is set. * **OBS\_SOURCE\_CEA\_708** - Source type provides cea708 data * **OBS\_SOURCE\_SRGB** - Source understands SRGB rendering * **OBS\_SOURCE\_CAP\_DONT\_SHOW\_PROPERTIES** - Source type prefers not to have its properties shown on creation (prefers to rely on defaults first) const char \*(\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .get\_name)(void \*type\_data)[](#c.obs_source_info.get_name "Link to this definition") Get the translated name of the source type. Param type\_data: The type\_data variable of this structure Return: The translated name of the source type void \*(\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .create)([obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*settings, [obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_info.create "Link to this definition") Creates the implementation data for the source. Param settings: Settings to initialize the source with Param source: Source that this data is associated with Return: The implementation data associated with this source void (\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .destroy)(void \*data)[](#c.obs_source_info.destroy "Link to this definition") Destroys the implementation data for the source. Async sources must not call obs\_source\_output\_video after returning from destroy. uint32\_t (\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .get\_width)(void \*data)[](#c.obs_source_info.get_width "Link to this definition") uint32\_t (\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .get\_height)(void \*data)[](#c.obs_source_info.get_height "Link to this definition") Returns the width/height of the source. These callbacks are required if this is a video source and is synchronous. (Author’s note: These should really be consolidated in to one function, not two) Return: The width/height of the video void (\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .get\_defaults)([obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*settings)[](#c.obs_source_info.get_defaults "Link to this definition") void (\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .get\_defaults2)(void \*type\_data, [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*settings)[](#c.obs_source_info.get_defaults2 "Link to this definition") Sets the default settings for this source. Param settings: Default settings. Call obs\_data\_set\_default\* functions on this object to set default setting values [obs\_properties\_t](reference-properties#c.obs_properties_t "obs_properties_t") \*(\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .get\_properties)(void \*data)[](#c.obs_source_info.get_properties "Link to this definition") [obs\_properties\_t](reference-properties#c.obs_properties_t "obs_properties_t") \*(\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .get\_properties2)(void \*data, void \*type\_data)[](#c.obs_source_info.get_properties2 "Link to this definition") Gets the property information of this source. Param data: The implementation data associated with this source. This value can be null (e.g., when [`obs_get_source_properties()`](#c.obs_get_source_properties "obs_get_source_properties") is called on the source type), make sure to handle this gracefully. (Optional) Return: The properties of the source void (\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .update)(void \*data, [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*settings)[](#c.obs_source_info.update "Link to this definition") Updates the settings for this source. (Optional) Param settings: New settings for this source void (\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .activate)(void \*data)[](#c.obs_source_info.activate "Link to this definition") Called when the source has been activated in the main view (visible on stream/recording). (Optional) void (\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .deactivate)(void \*data)[](#c.obs_source_info.deactivate "Link to this definition") Called when the source has been deactivated from the main view (no longer visible on stream/recording). (Optional) void (\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .show)(void \*data)[](#c.obs_source_info.show "Link to this definition") Called when the source is visible on any display and/or on the main view. (Optional) void (\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .hide)(void \*data)[](#c.obs_source_info.hide "Link to this definition") Called when the source is no longer visible on any display and/or on the main view. (Optional) void (\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .video\_tick)(void \*data, float seconds)[](#c.obs_source_info.video_tick "Link to this definition") Called each video frame with the time elapsed. (Optional) Param seconds: Seconds elapsed since the last frame void (\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .video\_render)(void \*data, [gs\_effect\_t](reference-libobs-graphics-effects#c.gs_effect_t "gs_effect_t") \*effect)[](#c.obs_source_info.video_render "Link to this definition") Called when rendering the source with the graphics subsystem. If this is an input/transition source, this is called to draw the source texture with the graphics subsystem. If this is a filter source, it wraps source draw calls (for example applying a custom effect with custom parameters to a source). In this case, it’s highly recommended to use the [`obs_source_process_filter_begin()`](#c.obs_source_process_filter_begin "obs_source_process_filter_begin") and [`obs_source_process_filter_end()`](#c.obs_source_process_filter_end "obs_source_process_filter_end") functions to automatically handle effect-based filter processing. However, you can implement custom draw handling as desired as well. If the source output capability flags do not include OBS\_SOURCE\_CUSTOM\_DRAW, the source must use [`obs_source_draw()`](#c.obs_source_draw "obs_source_draw") to render the source’s texture. Param effect: This parameter is no longer used. Instead, call [`obs_source_draw()`](#c.obs_source_draw "obs_source_draw") struct obs\_source\_frame \*(\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .filter\_video)(void \*data, struct obs\_source\_frame \*frame)[](#c.obs_source_info.filter_video "Link to this definition") Called to filter raw async video data. This function is only used with asynchronous video filters. Param frame: Video frame to filter Return: New video frame data. This can defer video data to be drawn later if time is needed for processing struct obs\_audio\_data \*(\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .filter\_audio)(void \*data, struct obs\_audio\_data \*audio)[](#c.obs_source_info.filter_audio "Link to this definition") Called to filter raw audio data. This function is only used with audio filters. Param audio: Audio data to filter Return: Modified or new audio data. You can directly modify the data passed and return it, or you can defer audio data for later if time is needed for processing. If you are returning new data, that data must exist until the next call to the [`obs_source_info.filter_audio`](#c.obs_source_info.filter_audio "obs_source_info.filter_audio") callback or until the filter is removed/destroyed void (\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .enum\_active\_sources)(void \*data, obs\_source\_enum\_proc\_t enum\_callback, void \*param)[](#c.obs_source_info.enum_active_sources "Link to this definition") Called to enumerate all active sources being used within this source. If the source has children that render audio/video it must implement this callback. Only used with sources that have the OBS\_SOURCE\_COMPOSITE output capability flag. Param enum\_callback: Enumeration callback Param param: User data to pass to callback void (\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .save)(void \*data, [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*settings)[](#c.obs_source_info.save "Link to this definition") Called when saving custom data for a source. This is a separate function because sometimes a source needs to know when it is being saved so it doesn’t always have to update the current settings until a certain point. (Optional) Param settings: Settings object to save data to void (\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .load)(void \*data, [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*settings)[](#c.obs_source_info.load "Link to this definition") Called when loading custom data from saved source data. This is called after all the loading sources have actually been created, allowing the ability to reference other sources if desired. (Optional) Param settings: Settings object to load data from void (\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .mouse\_click)(void \*data, const struct obs\_mouse\_event \*event, int32\_t type, bool mouse\_up, uint32\_t click\_count)[](#c.obs_source_info.mouse_click "Link to this definition") Called when interacting with a source and a mouse-down or mouse-up occurs. Only used with sources that have the OBS\_SOURCE\_INTERACTION output capability flag. (Optional) Param event: Mouse event properties Param type: Mouse button pushed Param mouse\_up: Mouse event type (true if mouse-up) Param click\_count: Mouse click count (1 for single click, etc.) void (\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .mouse\_move)(void \*data, const struct obs\_mouse\_event \*event, bool mouse\_leave)[](#c.obs_source_info.mouse_move "Link to this definition") Called when interacting with a source and a mouse-move occurs. Only used with sources that have the OBS\_SOURCE\_INTERACTION output capability flag. (Optional) Param event: Mouse event properties Param mouse\_leave: Mouse leave state (true if mouse left source) void (\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .mouse\_wheel)(void \*data, const struct obs\_mouse\_event \*event, int x\_delta, int y\_delta)[](#c.obs_source_info.mouse_wheel "Link to this definition") Called when interacting with a source and a mouse-wheel occurs. Only used with sources that have the OBS\_SOURCE\_INTERACTION output capability flag. (Optional) Param event: Mouse event properties Param x\_delta: Movement delta in the horizontal direction Param y\_delta: Movement delta in the vertical direction void (\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .focus)(void \*data, bool focus)[](#c.obs_source_info.focus "Link to this definition") Called when interacting with a source and gain focus/lost focus event occurs. Only used with sources that have the OBS\_SOURCE\_INTERACTION output capability flag. (Optional) Param focus: Focus state (true if focus gained) void (\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .key\_click)(void \*data, const struct obs\_key\_event \*event, bool key\_up)[](#c.obs_source_info.key_click "Link to this definition") Called when interacting with a source and a key-up or key-down occurs. Only used with sources that have the OBS\_SOURCE\_INTERACTION output capability flag. (Optional) Param event: Key event properties Param focus: Key event type (true if mouse-up) void (\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .filter\_add)(void \*data, [obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_info.filter_add "Link to this definition") Called when the filter is added to a source. (Optional) Param data: Filter data Param source: Source that the filter is being added to void (\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .filter\_remove)(void \*data, [obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_info.filter_remove "Link to this definition") Called when the filter is removed from a source. (Optional) Param data: Filter data Param source: Source that the filter being removed from void \*[obs\_source\_info](#c.obs_source_info "obs_source_info") .type\_data[](#c.obs_source_info.type_data "Link to this definition") void (\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .free\_type\_data)(void \*type\_data)[](#c.obs_source_info.free_type_data "Link to this definition") 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. bool (\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .audio\_render)(void \*data, uint64\_t \*ts\_out, struct obs\_source\_audio\_mix \*audio\_output, uint32\_t mixers, size\_t channels, size\_t sample\_rate)[](#c.obs_source_info.audio_render "Link to this definition") Called to render audio of composite sources. Only used with sources that have the OBS\_SOURCE\_COMPOSITE output capability flag. void (\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .enum\_all\_sources)(void \*data, obs\_source\_enum\_proc\_t enum\_callback, void \*param)[](#c.obs_source_info.enum_all_sources "Link to this definition") Called to enumerate all active and inactive sources being used within this source. If this callback isn’t implemented, enum\_active\_sources will be called instead. Only used with sources that have the OBS\_SOURCE\_COMPOSITE output capability flag. This is typically used if a source can have inactive child sources. Param enum\_callback: Enumeration callback Param param: User data to pass to callback void (\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .transition\_start)(void \*data)[](#c.obs_source_info.transition_start "Link to this definition") void (\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .transition\_stop)(void \*data)[](#c.obs_source_info.transition_stop "Link to this definition") Called on transition sources when the transition starts/stops. (Optional) enum obs\_icon\_type [obs\_source\_info](#c.obs_source_info "obs_source_info") .icon\_type[](#c.obs_source_info.icon_type "Link to this definition") Icon used for the source. * **OBS\_ICON\_TYPE\_UNKNOWN** - Unknown * **OBS\_ICON\_TYPE\_IMAGE** - Image * **OBS\_ICON\_TYPE\_COLOR** - Color * **OBS\_ICON\_TYPE\_SLIDESHOW** - Slideshow * **OBS\_ICON\_TYPE\_AUDIO\_INPUT** - Audio Input * **OBS\_ICON\_TYPE\_AUDIO\_OUTPUT** - Audio Output * **OBS\_ICON\_TYPE\_DESKTOP\_CAPTURE** - Desktop Capture * **OBS\_ICON\_TYPE\_WINDOW\_CAPTURE** - Window Capture * **OBS\_ICON\_TYPE\_GAME\_CAPTURE** - Game Capture * **OBS\_ICON\_TYPE\_CAMERA** - Camera * **OBS\_ICON\_TYPE\_TEXT** - Text * **OBS\_ICON\_TYPE\_MEDIA** - Media * **OBS\_ICON\_TYPE\_BROWSER** - Browser * **OBS\_ICON\_TYPE\_CUSTOM** - Custom (not implemented yet) void (\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .media\_play\_pause)(void \*data, bool pause)[](#c.obs_source_info.media_play_pause "Link to this definition") Called to pause or play media. void (\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .media\_restart)(void \*data)[](#c.obs_source_info.media_restart "Link to this definition") Called to restart the media. void (\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .media\_stop)(void \*data)[](#c.obs_source_info.media_stop "Link to this definition") Called to stop the media. void (\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .media\_next)(void \*data)[](#c.obs_source_info.media_next "Link to this definition") Called to go to the next media. void (\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .media\_previous)(void \*data)[](#c.obs_source_info.media_previous "Link to this definition") Called to go to the previous media. int64\_t (\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .media\_get\_duration)(void \*data)[](#c.obs_source_info.media_get_duration "Link to this definition") Called to get the media duration. int64\_t (\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .media\_get\_time)(void \*data)[](#c.obs_source_info.media_get_time "Link to this definition") Called to get the current time of the media. void (\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .media\_set\_time)(void \*data, int64\_t milliseconds)[](#c.obs_source_info.media_set_time "Link to this definition") Called to set the media time. enum obs\_media\_state (\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .media\_get\_state)(void \*data)[](#c.obs_source_info.media_get_state "Link to this definition") Called to get the state of the media. * **OBS\_MEDIA\_STATE\_NONE** - None * **OBS\_MEDIA\_STATE\_PLAYING** - Playing * **OBS\_MEDIA\_STATE\_OPENING** - Opening * **OBS\_MEDIA\_STATE\_BUFFERING** - Buffering * **OBS\_MEDIA\_STATE\_PAUSED** - Paused * **OBS\_MEDIA\_STATE\_STOPPED** - Stopped * **OBS\_MEDIA\_STATE\_ENDED** - Ended * **OBS\_MEDIA\_STATE\_ERROR** - Error obs\_missing\_files\_t \*(\*missing\_files)(void \*data)[](#c.missing_files "Link to this definition") Called to get the missing files of the source. enum [gs\_color\_space](reference-libobs-graphics-graphics#c.gs_color_space "gs_color_space") (\*[obs\_source\_info](#c.obs_source_info "obs_source_info") .video\_get\_color\_space)(void \*data, size\_t count, const enum [gs\_color\_space](reference-libobs-graphics-graphics#c.gs_color_space "gs_color_space") \*preferred\_spaces)[](#c.obs_source_info.video_get_color_space "Link to this definition") Returns the color space of the source. Assume GS\_CS\_SRGB if not implemented. There’s an optimization an SDR source can do when rendering to HDR. Check if the active space is GS\_CS\_709\_EXTENDED, and return GS\_CS\_709\_EXTENDED instead of GS\_CS\_SRGB to avoid an redundant conversion. This optimization can only be done if the pixel shader outputs linear 709, which is why it’s not performed by default. Return: The color space of the video Common Source Signals[](#common-source-signals "Link to this heading") ------------------------------------------------------------------------ The following signals are defined for every source type: **destroy** (ptr _source_) > This signal is called when the source is about to be destroyed. Do not increment any references when using this signal. **remove** (ptr source) > Called when the [`obs_source_remove()`](#c.obs_source_remove "obs_source_remove") > function is called on the source. **update** (ptr source) > Called when the source’s settings have been updated. > > Added in version 29.0.0. **save** (ptr source) > Called when the source is being saved. **load** (ptr source) > Called when the source is being loaded. **activate** (ptr source) > Called when the source has been activated in the main view (visible on stream/recording). **deactivate** (ptr source) > Called when the source has been deactivated from the main view (no longer visible on stream/recording). **show** (ptr source) > Called when the source is visible on any display and/or on the main view. **hide** (ptr source) > Called when the source is no longer visible on any display and/or on the main view. **mute** (ptr source, bool muted) > Called when the source is muted/unmuted. **push\_to\_mute\_changed** (ptr source, bool enabled) > Called when push-to-mute has been enabled/disabled. **push\_to\_mute\_delay** (ptr source, int delay) > Called when the push-to-mute delay value has changed. **push\_to\_talk\_changed** (ptr source, bool enabled) > Called when push-to-talk has been enabled/disabled. **push\_to\_talk\_delay** (ptr source, int delay) > Called when the push-to-talk delay value has changed. **enable** (ptr source, bool enabled) > Called when the source has been disabled/enabled. **rename** (ptr source, string new\_name, string prev\_name) > Called when the source has been renamed. **volume** (ptr source, in out float volume) > Called when the volume of the source has changed. **update\_properties** (ptr source) > Called to signal to any properties view (or other users of the source’s obs\_properties\_t) that the presentable properties of the source have changed and should be re-queried via obs\_source\_properties. Does not mean that the source’s _settings_ (as configured by the user) have changed. For that, use the update signal instead. **update\_flags** (ptr source, int flags) > Called when the flags of the source have been changed. **audio\_sync** (ptr source, int out int offset) > Called when the audio sync offset has changed. **audio\_balance** (ptr source, in out float balance) > Called when the audio balance has changed. **audio\_mixers** (ptr source, in out int mixers) > Called when the audio mixers have changed. **audio\_activate** (ptr source) > Called when the source’s audio becomes active. **audio\_deactivate** (ptr source) > Called when the source’s audio becomes inactive. **filter\_add** (ptr source, ptr filter) > Called when a filter has been added to the source. > > Added in version 30.0. **filter\_remove** (ptr source, ptr filter) > Called when a filter has been removed from the source. **reorder\_filters** (ptr source) > Called when filters have been reordered. **transition\_start** (ptr source) > Called when a transition is starting. **transition\_video\_stop** (ptr source) > Called when a transition’s video transitioning has stopped. **transition\_stop** (ptr source) > Called when a transition has stopped. **media\_started** (ptr source) > Called when media has started. **media\_ended** (ptr source) > Called when media has ended. **media\_pause** (ptr source) > Called when media has been paused. **media\_play** (ptr source) > Called when media starts playing. **media\_restart** (ptr source) > Called when the playing of media has been restarted. **media\_stopped** (ptr source) > Called when the playing of media has been stopped. **media\_next** (ptr source) > Called when the media source switches to the next media. **media\_previous** (ptr source) > Called when the media source switches to the previous media. Source-specific Signals[](#source-specific-signals "Link to this heading") ---------------------------------------------------------------------------- **slide\_changed** (int index, string path) > Called when the source’s currently displayed image changes. > > Defined by: > > * Image Slide Show > * * * **hooked** (ptr source, string title, string class, string executable) > Called when the source successfully captures an existing window. > > Defined by: > > * Window Capture (Windows) > > * Game Capture (Windows) > > * Application Audio Output Capture (Windows) > * * * **hooked** (ptr source, string name, string class) > Called when the source successfully captures an existing window. > > Defined by: > > * Window Capture (Xcomposite) > * * * **unhooked** (ptr source) > Called when the source stops capturing. > > Defined by: > > * Window Capture (Windows) > > * Game Capture (Windows) > > * Application Audio Output Capture (Windows) > > * Window Capture (Xcomposite) > * * * Source-specific Procedures[](#source-specific-procedures "Link to this heading") ---------------------------------------------------------------------------------- The following procedures are defined for specific sources only: **current\_index** (out int current\_index) > Returns the index of the currently displayed image in the slideshow. > > Defined by: > > * Image Slide Show > * * * **total\_files** (out int total\_files) > Returns the total number of image files in the slideshow. > > Defined by: > > * Image Slide Show > * * * **get\_hooked** (out bool hooked, out string title, out string class, out string executable) > Returns whether the source is currently capturing a window and if yes, which. > > Defined by: > > * Window Capture (Windows) > > * Game Capture (Windows) > > * Application audio output capture (Windows) > * * * **get\_hooked** (out bool hooked, out string name, out string class) > Returns whether the source is currently capturing a window and if yes, which. > > Defined by: > > * Window Capture (Xcomposite) > * * * **get\_metadata** (in string tag\_id, out string tag\_data) > For a given metadata tag, returns the data associated with it. > > Defined by: > > * VLC Video Source > * * * **restart** () > Restarts the media. > > Defined by: > > * Media Source > * * * **get\_duration** (out int duration) > Returns the total duration of the media file, in nanoseconds. > > Defined by: > > * Media Source > * * * **get\_nb\_frames** (out int num\_frames) > Returns the total number of frames in the media file. > > Defined by: > > * Media Source > * * * **activate** (in bool active) > Activates or deactivates the device. > > Defined by: > > * Video Capture Device Source (Windows) > * * * General Source Functions[](#general-source-functions "Link to this heading") ------------------------------------------------------------------------------ void obs\_register\_source(struct [obs\_source\_info](#c.obs_source_info "obs_source_info") \*info)[](#c.obs_register_source "Link to this definition") Registers a source type. Typically used in [`obs_module_load()`](reference-modules#c.obs_module_load "obs_module_load") or in the program’s initialization phase. * * * const char \*obs\_source\_get\_display\_name(const char \*id)[](#c.obs_source_get_display_name "Link to this definition") Calls the [`obs_source_info.get_name`](#c.obs_source_info.get_name "obs_source_info.get_name") callback to get the translated display name of a source type. Parameters: * **id** – The source type string identifier Returns: The translated display name of a source type * * * [obs\_source\_t](#c.obs_source_t "obs_source_t") \*obs\_source\_create(const char \*id, const char \*name, [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*settings, [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*hotkey\_data)[](#c.obs_source_create "Link to this definition") Creates a source of the specified type with the specified settings. The “source” context is used for anything related to presenting or modifying video/audio. Use [`obs_source_release()`](#c.obs_source_release "obs_source_release") to release it. Parameters: * **id** – The source type string identifier * **name** – The desired name of the source. If this is not unique, it will be made to be unique * **settings** – The settings for the source, or _NULL_ if none * **hotkey\_data** – Saved hotkey data for the source, or _NULL_ if none Returns: A reference to the newly created source, or _NULL_ if failed * * * [obs\_source\_t](#c.obs_source_t "obs_source_t") \*obs\_source\_create\_private(const char \*id, const char \*name, [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*settings)[](#c.obs_source_create_private "Link to this definition") Creates a ‘private’ source which is not enumerated by [`obs_enum_sources()`](reference-core#c.obs_enum_sources "obs_enum_sources") , and is not saved by [`obs_save_sources()`](reference-core#c.obs_save_sources "obs_save_sources") . Author’s Note: The existence of this function is a result of design flaw: the front-end should control saving/loading of sources, and functions like [`obs_enum_sources()`](reference-core#c.obs_enum_sources "obs_enum_sources") and [`obs_save_sources()`](reference-core#c.obs_save_sources "obs_save_sources") should not exist in the back-end. Parameters: * **id** – The source type string identifier * **name** – The desired name of the source. For private sources, this does not have to be unique, and can additionally be _NULL_ if desired * **settings** – The settings for the source, or _NULL_ if none Returns: A reference to the newly created source, or _NULL_ if failed * * * [obs\_source\_t](#c.obs_source_t "obs_source_t") \*obs\_source\_duplicate([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, const char \*desired\_name, bool create\_private)[](#c.obs_source_duplicate "Link to this definition") Duplicates a source. If the source has the OBS\_SOURCE\_DO\_NOT\_DUPLICATE output flag set, this only returns a new reference to the same source. Either way, release with [`obs_source_release()`](#c.obs_source_release "obs_source_release") . Parameters: * **source** – The source to duplicate * **desired\_name** – The desired name of the new source. If this is not a private source and the name is not unique, it will be made to be unique * **create\_private** – If _true_, the new source will be a private source if fully duplicated Returns: A new source reference * * * [obs\_source\_t](#c.obs_source_t "obs_source_t") \*obs\_source\_get\_ref([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_get_ref "Link to this definition") Returns an incremented reference if still valid, otherwise returns _NULL_. Use [`obs_source_release()`](#c.obs_source_release "obs_source_release") to release it. * * * void obs\_source\_release([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_release "Link to this definition") Releases a reference to a source. When the last reference is released, the source is destroyed. * * * [obs\_weak\_source\_t](#c.obs_weak_source_t "obs_weak_source_t") \*obs\_source\_get\_weak\_source([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_get_weak_source "Link to this definition") [obs\_source\_t](#c.obs_source_t "obs_source_t") \*obs\_weak\_source\_get\_source([obs\_weak\_source\_t](#c.obs_weak_source_t "obs_weak_source_t") \*weak)[](#c.obs_weak_source_get_source "Link to this definition") These functions are used to get an incremented weak reference from a strong source reference, or an incremented strong source reference from a weak reference. If the source is destroyed, _obs\_weak\_source\_get\_source_ will return _NULL_. Release with [`obs_weak_source_release()`](#c.obs_weak_source_release "obs_weak_source_release") or [`obs_source_release()`](#c.obs_source_release "obs_source_release") , respectively. * * * void obs\_weak\_source\_addref([obs\_weak\_source\_t](#c.obs_weak_source_t "obs_weak_source_t") \*weak)[](#c.obs_weak_source_addref "Link to this definition") void obs\_weak\_source\_release([obs\_weak\_source\_t](#c.obs_weak_source_t "obs_weak_source_t") \*weak)[](#c.obs_weak_source_release "Link to this definition") Adds/releases a weak reference to a source. * * * void obs\_source\_remove([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_remove "Link to this definition") Notifies all reference holders of the source (via [`obs_source_removed()`](#c.obs_source_removed "obs_source_removed") ) that the source should be released. * * * bool obs\_source\_removed(const [obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_removed "Link to this definition") Returns: _true_ if the source should be released * * * bool obs\_source\_is\_hidden([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_is_hidden "Link to this definition") void obs\_source\_set\_hidden([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, bool hidden)[](#c.obs_source_set_hidden "Link to this definition") Gets/sets the hidden property that determines whether it should be hidden from the user. Used when the source is still alive but should not be referenced. * * * uint32\_t obs\_source\_get\_output\_flags(const [obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_get_output_flags "Link to this definition") uint32\_t obs\_get\_source\_output\_flags(const char \*id)[](#c.obs_get_source_output_flags "Link to this definition") Returns: Capability flags of a source Author’s Note: “Output flags” is poor wording in retrospect; this should have been named “Capability flags”, and the OBS\_SOURCE\_\* macros should really be OBS\_SOURCE\_CAP\_\* macros instead. See [`obs_source_info.output_flags`](#c.obs_source_info.output_flags "obs_source_info.output_flags") for more information. * * * [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*obs\_get\_source\_defaults(const char \*id)[](#c.obs_get_source_defaults "Link to this definition") Calls [`obs_source_info.get_defaults`](#c.obs_source_info.get_defaults "obs_source_info.get_defaults") to get the defaults settings of the source type. Returns: The default settings for a source type * * * [obs\_properties\_t](reference-properties#c.obs_properties_t "obs_properties_t") \*obs\_source\_properties(const [obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_properties "Link to this definition") [obs\_properties\_t](reference-properties#c.obs_properties_t "obs_properties_t") \*obs\_get\_source\_properties(const char \*id)[](#c.obs_get_source_properties "Link to this definition") Use these functions to get the properties of a source or source type. Properties are optionally used (if desired) to automatically generate user interface widgets to allow users to update settings. Returns: The properties list for a specific existing source. Free with [`obs_properties_destroy()`](reference-properties#c.obs_properties_destroy "obs_properties_destroy") * * * bool obs\_source\_configurable(const [obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_configurable "Link to this definition") bool obs\_is\_source\_configurable(const char \*id)[](#c.obs_is_source_configurable "Link to this definition") Returns: _true_ if the the source has custom properties, _false_ otherwise * * * void obs\_source\_update([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*settings)[](#c.obs_source_update "Link to this definition") Updates the settings for a source and calls the [`obs_source_info.update`](#c.obs_source_info.update "obs_source_info.update") callback of the source. If the source is a video source, the [`obs_source_info.update`](#c.obs_source_info.update "obs_source_info.update") will be not be called immediately; instead, it will be deferred to the video thread to prevent threading issues. * * * void obs\_source\_reset\_settings([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*settings)[](#c.obs_source_reset_settings "Link to this definition") Same as [`obs_source_update()`](#c.obs_source_update "obs_source_update") , but clears existing settings first. * * * void obs\_source\_video\_render([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_video_render "Link to this definition") Renders a video source. This will call the [`obs_source_info.video_render`](#c.obs_source_info.video_render "obs_source_info.video_render") callback of the source. * * * uint32\_t obs\_source\_get\_width([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_get_width "Link to this definition") uint32\_t obs\_source\_get\_height([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_get_height "Link to this definition") Calls the [`obs_source_info.get_width`](#c.obs_source_info.get_width "obs_source_info.get_width") or [`obs_source_info.get_height`](#c.obs_source_info.get_height "obs_source_info.get_height") of the source to get its width and/or height. Author’s Note: These functions should be consolidated in to a single function/callback rather than having a function for both width and height. Returns: The width or height of the source * * * enum [gs\_color\_space](reference-libobs-graphics-graphics#c.gs_color_space "gs_color_space") obs\_source\_get\_color\_space([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, size\_t count, const enum [gs\_color\_space](reference-libobs-graphics-graphics#c.gs_color_space "gs_color_space") \*preferred\_spaces)[](#c.obs_source_get_color_space "Link to this definition") Calls the [`obs_source_info.video_get_color_space`](#c.obs_source_info.video_get_color_space "obs_source_info.video_get_color_space") of the source to get its color space. Assumes GS\_CS\_SRGB if not implemented. Disabled filters are skipped, and async video sources can figure out the color space for themselves. Returns: The color space of the source * * * bool obs\_source\_get\_texcoords\_centered([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_get_texcoords_centered "Link to this definition") Hints whether or not the source will blend texels. Returns: Whether or not the source will blend texels * * * [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*obs\_source\_get\_settings(const [obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_get_settings "Link to this definition") Returns: The settings string for a source. The reference counter of the returned settings data is incremented, so [`obs_data_release()`](reference-settings#c.obs_data_release "obs_data_release") must be called when the settings are no longer used * * * const char \*obs\_source\_get\_name(const [obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_get_name "Link to this definition") Returns: The name of the source * * * const char \*obs\_source\_get\_uuid(const [obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_get_uuid "Link to this definition") Returns: The UUID of the source Added in version 29.1. * * * void obs\_source\_set\_name([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, const char \*name)[](#c.obs_source_set_name "Link to this definition") Sets the name of a source. If the source is not private and the name is not unique, it will automatically be given a unique name. * * * enum obs\_source\_type obs\_source\_get\_type(const [obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_get_type "Link to this definition") Returns: OBS\_SOURCE\_TYPE\_INPUT for inputs OBS\_SOURCE\_TYPE\_FILTER for filters OBS\_SOURCE\_TYPE\_TRANSITION for transitions OBS\_SOURCE\_TYPE\_SCENE for scenes * * * bool obs\_source\_is\_scene(const [obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_is_scene "Link to this definition") Returns: _true_ if the source is a scene * * * bool obs\_source\_is\_group(const [obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_is_group "Link to this definition") Returns: _true_ if the source is a group * * * const char \*obs\_source\_get\_id(const [obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_get_id "Link to this definition") > return: > > The source’s type identifier string. If the source is versioned, “\_vN” is appended at the end, where “N” is the source’s version. * * * const char \*obs\_source\_get\_unversioned\_id(const [obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_get_unversioned_id "Link to this definition") Returns: The source’s unversioned type identifier string. * * * [signal\_handler\_t](reference-libobs-callback#c.signal_handler_t "signal_handler_t") \*obs\_source\_get\_signal\_handler(const [obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_get_signal_handler "Link to this definition") Returns: The source’s signal handler. Should not be manually freed, as its lifecycle is managed by libobs. See the [Common Source Signals](#source-signal-handler-reference) for more information on signals that are available for sources. * * * [proc\_handler\_t](reference-libobs-callback#c.proc_handler_t "proc_handler_t") \*obs\_source\_get\_proc\_handler(const [obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_get_proc_handler "Link to this definition") Returns: The procedure handler for a source. Should not be manually freed, as its lifecycle is managed by libobs. * * * void obs\_source\_set\_volume([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, float volume)[](#c.obs_source_set_volume "Link to this definition") float obs\_source\_get\_volume(const [obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_get_volume "Link to this definition") Sets/gets the user volume for a source that has audio output. * * * bool obs\_source\_muted(const [obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_muted "Link to this definition") void obs\_source\_set\_muted([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, bool muted)[](#c.obs_source_set_muted "Link to this definition") Sets/gets whether the source’s audio is muted. * * * enum [speaker\_layout](reference-libobs-media-io#c.speaker_layout "speaker_layout") obs\_source\_get\_speaker\_layout([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_get_speaker_layout "Link to this definition") Gets the current speaker layout. * * * void obs\_source\_set\_balance\_value([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, float balance)[](#c.obs_source_set_balance_value "Link to this definition") float obs\_source\_get\_balance\_value(const [obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_get_balance_value "Link to this definition") Sets/gets the audio balance value. * * * void obs\_source\_set\_sync\_offset([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, int64\_t offset)[](#c.obs_source_set_sync_offset "Link to this definition") int64\_t obs\_source\_get\_sync\_offset(const [obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_get_sync_offset "Link to this definition") Sets/gets the audio sync offset (in nanoseconds) for a source. * * * void obs\_source\_set\_audio\_mixers([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, uint32\_t mixers)[](#c.obs_source_set_audio_mixers "Link to this definition") uint32\_t obs\_source\_get\_audio\_mixers(const [obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_get_audio_mixers "Link to this definition") Sets/gets the audio mixer channels (i.e. audio tracks) that a source outputs to, depending on what bits are set. Audio mixers allow filtering specific using multiple audio encoders to mix different sources together depending on what mixer channel they’re set to. For example, to output to mixer 1 and 3, you would perform a bitwise OR on bits 0 and 2: (1<<0) | (1<<2), or 0x5. * * * void obs\_source\_set\_monitoring\_type([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, enum obs\_monitoring\_type type)[](#c.obs_source_set_monitoring_type "Link to this definition") enum obs\_monitoring\_type obs\_source\_get\_monitoring\_type([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_get_monitoring_type "Link to this definition") Sets/gets the desktop audio monitoring type. Parameters: * **order** – OBS\_MONITORING\_TYPE\_NONE - Do not monitor OBS\_MONITORING\_TYPE\_MONITOR\_ONLY - Send to monitor device, no outputs OBS\_MONITORING\_TYPE\_MONITOR\_AND\_OUTPUT - Send to monitor device and outputs * * * void obs\_source\_set\_audio\_active([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, bool active)[](#c.obs_source_set_audio_active "Link to this definition") bool obs\_source\_audio\_active(const [obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_audio_active "Link to this definition") Sets/gets the audio active status (controls whether the source is shown in the mixer). * * * void obs\_source\_enum\_active\_sources([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, obs\_source\_enum\_proc\_t enum\_callback, void \*param)[](#c.obs_source_enum_active_sources "Link to this definition") void obs\_source\_enum\_active\_tree([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, obs\_source\_enum\_proc\_t enum\_callback, void \*param)[](#c.obs_source_enum_active_tree "Link to this definition") Enumerates active child sources or source tree used by this source. Relevant data types used with this function: typedef void (\*obs\_source\_enum\_proc\_t)(obs\_source\_t \*parent, obs\_source\_t \*child, void \*param); * * * bool obs\_source\_push\_to\_mute\_enabled(const [obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_push_to_mute_enabled "Link to this definition") void obs\_source\_enable\_push\_to\_mute([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, bool enabled)[](#c.obs_source_enable_push_to_mute "Link to this definition") Sets/gets whether push-to-mute is enabled. * * * uint64\_t obs\_source\_get\_push\_to\_mute\_delay(const [obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_get_push_to_mute_delay "Link to this definition") void obs\_source\_set\_push\_to\_mute\_delay([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, uint64\_t delay)[](#c.obs_source_set_push_to_mute_delay "Link to this definition") Sets/gets the push-to-mute delay. * * * bool obs\_source\_push\_to\_talk\_enabled(const [obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_push_to_talk_enabled "Link to this definition") void obs\_source\_enable\_push\_to\_talk([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, bool enabled)[](#c.obs_source_enable_push_to_talk "Link to this definition") Sets/gets whether push-to-talk is enabled. * * * uint64\_t obs\_source\_get\_push\_to\_talk\_delay(const [obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_get_push_to_talk_delay "Link to this definition") void obs\_source\_set\_push\_to\_talk\_delay([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, uint64\_t delay)[](#c.obs_source_set_push_to_talk_delay "Link to this definition") Sets/gets the push-to-talk delay. * * * bool obs\_source\_active(const [obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_active "Link to this definition") Returns: _true_ if active, _false_ if not. A source is only considered active if it’s being shown on the final mix * * * bool obs\_source\_showing(const [obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_showing "Link to this definition") Returns: _true_ if showing, _false_ if not. A source is considered showing if it’s being displayed anywhere at all, whether on a display context or on the final output * * * void obs\_source\_inc\_showing([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_inc_showing "Link to this definition") void obs\_source\_dec\_showing([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_dec_showing "Link to this definition") Increments/decrements a source’s “showing” state. Typically used when drawing a source on a display manually. * * * void obs\_source\_set\_flags([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, uint32\_t flags)[](#c.obs_source_set_flags "Link to this definition") uint32\_t obs\_source\_get\_flags(const [obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_get_flags "Link to this definition") Parameters: * **flags** – OBS\_SOURCE\_FLAG\_FORCE\_MONO Forces audio to mono * * * void obs\_source\_enum\_filters([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, obs\_source\_enum\_proc\_t callback, void \*param)[](#c.obs_source_enum_filters "Link to this definition") Enumerates active filters on a source. Relevant data types used with this function: typedef void (\*obs\_source\_enum\_proc\_t)(obs\_source\_t \*parent, obs\_source\_t \*child, void \*param); * * * [obs\_source\_t](#c.obs_source_t "obs_source_t") \*obs\_source\_get\_filter\_by\_name([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, const char \*name)[](#c.obs_source_get_filter_by_name "Link to this definition") Returns: The desired filter, or _NULL_ if not found. The reference of the filter is incremented * * * void obs\_source\_copy\_filters([obs\_source\_t](#c.obs_source_t "obs_source_t") \*dst, [obs\_source\_t](#c.obs_source_t "obs_source_t") \*src)[](#c.obs_source_copy_filters "Link to this definition") Copies filters from the source to the destination. If filters by the same name already exist in the destination source, the newer filters will be given unique names. * * * void obs\_source\_copy\_single\_filter([obs\_source\_t](#c.obs_source_t "obs_source_t") \*dst, [obs\_source\_t](#c.obs_source_t "obs_source_t") \*filter)[](#c.obs_source_copy_single_filter "Link to this definition") Copies the filter from the source to the destination. If a filter by the same name already exists in the destination source, the newer filter will be given a unique name. * * * size\_t obs\_source\_filter\_count(const [obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_filter_count "Link to this definition") Returns the number of filters the source has. * * * [obs\_data\_array\_t](reference-settings#c.obs_data_array_t "obs_data_array_t") \*obs\_source\_backup\_filters([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_backup_filters "Link to this definition") void obs\_source\_restore\_filters([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, [obs\_data\_array\_t](reference-settings#c.obs_data_array_t "obs_data_array_t") \*array)[](#c.obs_source_restore_filters "Link to this definition") Backs up and restores the current filter list and order. * * * bool obs\_source\_enabled(const [obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_enabled "Link to this definition") void obs\_source\_set\_enabled([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, bool enabled)[](#c.obs_source_set_enabled "Link to this definition") Enables/disables a source, or returns the enabled state. * * * void obs\_source\_add\_audio\_capture\_callback([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, obs\_source\_audio\_capture\_t callback, void \*param)[](#c.obs_source_add_audio_capture_callback "Link to this definition") void obs\_source\_remove\_audio\_capture\_callback([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, obs\_source\_audio\_capture\_t callback, void \*param)[](#c.obs_source_remove_audio_capture_callback "Link to this definition") Adds/removes an audio capture callback for a source. This allows the ability to get the raw audio data of a source as it comes in. Relevant data types used with this function: typedef void (\*obs\_source\_audio\_capture\_t)(void \*param, obs\_source\_t \*source, const struct audio\_data \*audio\_data, bool muted); * * * void obs\_source\_set\_deinterlace\_mode([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, enum obs\_deinterlace\_mode mode)[](#c.obs_source_set_deinterlace_mode "Link to this definition") enum obs\_deinterlace\_mode obs\_source\_get\_deinterlace\_mode(const [obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_get_deinterlace_mode "Link to this definition") Sets/gets the deinterlace mode. Parameters: * **mode** – OBS\_DEINTERLACE\_MODE\_DISABLE - Disables deinterlacing OBS\_DEINTERLACE\_MODE\_DISCARD - Discard OBS\_DEINTERLACE\_MODE\_RETRO - Retro OBS\_DEINTERLACE\_MODE\_BLEND - Blend OBS\_DEINTERLACE\_MODE\_BLEND\_2X - Blend 2x OBS\_DEINTERLACE\_MODE\_LINEAR - Linear OBS\_DEINTERLACE\_MODE\_LINEAR\_2X - Linear 2x OBS\_DEINTERLACE\_MODE\_YADIF - Yadif OBS\_DEINTERLACE\_MODE\_YADIF\_2X - Yadif 2x * * * void obs\_source\_set\_deinterlace\_field\_order([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, enum obs\_deinterlace\_field\_order order)[](#c.obs_source_set_deinterlace_field_order "Link to this definition") enum obs\_deinterlace\_field\_order obs\_source\_get\_deinterlace\_field\_order(const [obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_get_deinterlace_field_order "Link to this definition") Sets/gets the deinterlace field order. Parameters: * **order** – OBS\_DEINTERLACE\_FIELD\_ORDER\_TOP - Start from top OBS\_DEINTERLACE\_FIELD\_ORDER\_BOTTOM - Start from bottom * * * [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*obs\_source\_get\_private\_settings([obs\_source\_t](#c.obs_source_t "obs_source_t") \*item)[](#c.obs_source_get_private_settings "Link to this definition") Gets private front-end settings data. This data is saved/loaded automatically. Returns an incremented reference. Use [`obs_data_release()`](reference-settings#c.obs_data_release "obs_data_release") to release it. * * * void obs\_source\_send\_mouse\_click([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, const struct obs\_mouse\_event \*event, int32\_t type, bool mouse\_up, uint32\_t click\_count)[](#c.obs_source_send_mouse_click "Link to this definition") Used for interacting with sources: sends a mouse down/up event to a source. * * * void obs\_source\_send\_mouse\_move([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, const struct obs\_mouse\_event \*event, bool mouse\_leave)[](#c.obs_source_send_mouse_move "Link to this definition") Used for interacting with sources: sends a mouse move event to a source. * * * void obs\_source\_send\_mouse\_wheel([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, const struct obs\_mouse\_event \*event, int x\_delta, int y\_delta)[](#c.obs_source_send_mouse_wheel "Link to this definition") Used for interacting with sources: sends a mouse wheel event to a source. * * * void obs\_source\_send\_focus([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, bool focus)[](#c.obs_source_send_focus "Link to this definition") Used for interacting with sources: sends a got-focus or lost-focus event to a source. * * * void obs\_source\_send\_key\_click([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, const struct obs\_key\_event \*event, bool key\_up)[](#c.obs_source_send_key_click "Link to this definition") Used for interacting with sources: sends a key up/down event to a source. * * * enum obs\_icon\_type obs\_source\_get\_icon\_type(const char \*id)[](#c.obs_source_get_icon_type "Link to this definition") Calls the [`obs_source_info.icon_type`](#c.obs_source_info.icon_type "obs_source_info.icon_type") to get the icon type. * * * void obs\_source\_media\_play\_pause([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, bool pause)[](#c.obs_source_media_play_pause "Link to this definition") Calls the [`obs_source_info.media_play_pause`](#c.obs_source_info.media_play_pause "obs_source_info.media_play_pause") to pause or play media. * * * void obs\_source\_media\_restart([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_media_restart "Link to this definition") Calls the [`obs_source_info.media_restart`](#c.obs_source_info.media_restart "obs_source_info.media_restart") to restart the media. * * * void obs\_source\_media\_stop([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_media_stop "Link to this definition") Calls the [`obs_source_info.media_stop`](#c.obs_source_info.media_stop "obs_source_info.media_stop") to stop the media. * * * void obs\_source\_media\_next([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_media_next "Link to this definition") Calls the [`obs_source_info.media_next`](#c.obs_source_info.media_next "obs_source_info.media_next") to go to the next media. * * * void obs\_source\_media\_previous([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_media_previous "Link to this definition") Calls the [`obs_source_info.media_previous`](#c.obs_source_info.media_previous "obs_source_info.media_previous") to go to the previous media. * * * int64\_t obs\_source\_media\_get\_duration([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_media_get_duration "Link to this definition") Calls the [`obs_source_info.media_get_duration`](#c.obs_source_info.media_get_duration "obs_source_info.media_get_duration") to get the media duration in milliseconds. * * * int64\_t obs\_source\_media\_get\_time([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_media_get_time "Link to this definition") void obs\_source\_media\_set\_time([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, int64\_t ms)[](#c.obs_source_media_set_time "Link to this definition") Calls the [`obs_source_info.media_get_time`](#c.obs_source_info.media_get_time "obs_source_info.media_get_time") or [`obs_source_info.media_set_time`](#c.obs_source_info.media_set_time "obs_source_info.media_set_time") to get/set the current time (in milliseconds) of the media. Will return 0 for non-media sources. * * * enum obs\_media\_state obs\_source\_media\_get\_state([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_media_get_state "Link to this definition") Calls the [`obs_source_info.media_get_state`](#c.obs_source_info.media_get_state "obs_source_info.media_get_state") to get the state of the media. * * * void obs\_source\_media\_started([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_media_started "Link to this definition") Emits a **media\_started** signal. * * * void obs\_source\_media\_ended([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_media_ended "Link to this definition") Emits a **media\_ended** signal. * * * Functions used by sources[](#functions-used-by-sources "Link to this heading") -------------------------------------------------------------------------------- void obs\_source\_draw\_set\_color\_matrix(const struct [matrix4](reference-libobs-graphics-matrix4#c.matrix4 "matrix4") \*color\_matrix, const struct [vec3](reference-libobs-graphics-vec3#c.vec3 "vec3") \*color\_range\_min, const struct [vec3](reference-libobs-graphics-vec3#c.vec3 "vec3") \*color\_range\_max)[](#c.obs_source_draw_set_color_matrix "Link to this definition") Helper function to set the color matrix information when drawing the source. Parameters: * **color\_matrix** – The color matrix. Assigns to the ‘color\_matrix’ effect variable. * **color\_range\_min** – The minimum color range. Assigns to the ‘color\_range\_min’ effect variable. If NULL, {0.0f, 0.0f, 0.0f} is used. * **color\_range\_max** – The maximum color range. Assigns to the ‘color\_range\_max’ effect variable. If NULL, {1.0f, 1.0f, 1.0f} is used. * * * void obs\_source\_draw([gs\_texture\_t](reference-libobs-graphics-graphics#c.gs_texture_t "gs_texture_t") \*image, int x, int y, uint32\_t cx, uint32\_t cy, bool flip)[](#c.obs_source_draw "Link to this definition") Helper function to draw sprites for a source (synchronous video). Parameters: * **image** – The sprite texture to draw. Assigns to the ‘image’ variable of the current effect. * **x** – X position of the sprite. * **y** – Y position of the sprite. * **cx** – Width of the sprite. If 0, uses the texture width. * **cy** – Height of the sprite. If 0, uses the texture height. * **flip** – Specifies whether to flip the image vertically. * * * void obs\_source\_output\_video([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, const struct obs\_source\_frame \*frame)[](#c.obs_source_output_video "Link to this definition") Outputs asynchronous video data. Set to NULL to deactivate the texture. Relevant data types used with this function: enum video\_format { VIDEO\_FORMAT\_NONE, /\* planar 4:2:0 formats \*/ VIDEO\_FORMAT\_I420, /\* three-plane \*/ VIDEO\_FORMAT\_NV12, /\* two-plane, luma and packed chroma \*/ /\* packed 4:2:2 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, /\* more packed uncompressed formats \*/ VIDEO\_FORMAT\_BGR3, /\* planar 4:2:2 \*/ VIDEO\_FORMAT\_I422, /\* planar 4:2:0 with alpha \*/ VIDEO\_FORMAT\_I40A, /\* planar 4:2:2 with alpha \*/ VIDEO\_FORMAT\_I42A, /\* planar 4:4:4 with alpha \*/ VIDEO\_FORMAT\_YUVA, /\* packed 4:4:4 with alpha \*/ VIDEO\_FORMAT\_AYUV, /\* planar 4:2:0 format, 10 bpp \*/ VIDEO\_FORMAT\_I010, /\* three-plane \*/ VIDEO\_FORMAT\_P010, /\* two-plane, luma and packed chroma \*/ /\* planar 4:2:2 format, 10 bpp \*/ VIDEO\_FORMAT\_I210, /\* planar 4:4:4 format, 12 bpp \*/ VIDEO\_FORMAT\_I412, /\* planar 4:4:4:4 format, 12 bpp \*/ VIDEO\_FORMAT\_YA2L, /\* planar 4:2:2 format, 16 bpp \*/ VIDEO\_FORMAT\_P216, /\* two-plane, luma and packed chroma \*/ /\* planar 4:4:4 format, 16 bpp \*/ VIDEO\_FORMAT\_P416, /\* two-plane, luma and packed chroma \*/ /\* packed 4:2:2 format, 10 bpp \*/ VIDEO\_FORMAT\_V210, /\* packed uncompressed 10-bit format \*/ VIDEO\_FORMAT\_R10L, }; struct obs\_source\_frame { uint8\_t \*data\[MAX\_AV\_PLANES\]; uint32\_t linesize\[MAX\_AV\_PLANES\]; uint32\_t width; uint32\_t height; uint64\_t timestamp; enum video\_format format; float color\_matrix\[16\]; bool full\_range; uint16\_t max\_luminance; float color\_range\_min\[3\]; float color\_range\_max\[3\]; bool flip; uint8\_t flags; uint8\_t trc; /\* enum video\_trc \*/ }; * * * void obs\_source\_set\_async\_rotation([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, long rotation)[](#c.obs_source_set_async_rotation "Link to this definition") Allows the ability to set rotation (0, 90, 180, -90, 270) for an async video source. The rotation will be automatically applied to the source. * * * void obs\_source\_preload\_video([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, const struct obs\_source\_frame \*frame)[](#c.obs_source_preload_video "Link to this definition") Preloads a video frame to ensure a frame is ready for playback as soon as video playback starts. * * * void obs\_source\_show\_preloaded\_video([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_show_preloaded_video "Link to this definition") Shows any preloaded video frame. * * * void obs\_source\_output\_audio([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, const struct obs\_source\_audio \*audio)[](#c.obs_source_output_audio "Link to this definition") Outputs audio data. * * * void obs\_source\_update\_properties([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_update_properties "Link to this definition") Signals to any currently opened properties views (or other users of the source’s obs\_properties\_t) that the source’s presentable properties have changed and that the view should be updated. * * * bool obs\_source\_add\_active\_child([obs\_source\_t](#c.obs_source_t "obs_source_t") \*parent, [obs\_source\_t](#c.obs_source_t "obs_source_t") \*child)[](#c.obs_source_add_active_child "Link to this definition") Adds an active child source. Must be called by parent sources on child sources when the child is added and active. This ensures that the source is properly activated if the parent is active. Returns: _true_ if source can be added, _false_ if it causes recursion * * * void obs\_source\_remove\_active\_child([obs\_source\_t](#c.obs_source_t "obs_source_t") \*parent, [obs\_source\_t](#c.obs_source_t "obs_source_t") \*child)[](#c.obs_source_remove_active_child "Link to this definition") Removes an active child source. Must be called by parent sources on child sources when the child is removed or inactive. This ensures that the source is properly deactivated if the parent is no longer active. * * * Filters[](#filters "Link to this heading") -------------------------------------------- [obs\_source\_t](#c.obs_source_t "obs_source_t") \*obs\_filter\_get\_parent(const [obs\_source\_t](#c.obs_source_t "obs_source_t") \*filter)[](#c.obs_filter_get_parent "Link to this definition") If the source is a filter, returns the parent source of the filter. The parent source is the source being filtered. Does not increment the reference. Only guaranteed to be valid inside of the video\_render, filter\_audio, filter\_video, filter\_add, and filter\_remove callbacks. * * * [obs\_source\_t](#c.obs_source_t "obs_source_t") \*obs\_filter\_get\_target(const [obs\_source\_t](#c.obs_source_t "obs_source_t") \*filter)[](#c.obs_filter_get_target "Link to this definition") If the source is a filter, returns the target source of the filter. The target source is the next source in the filter chain. Does not increment the reference. Only guaranteed to be valid inside of the video\_render, filter\_audio, filter\_video, and filter\_remove callbacks. * * * void obs\_source\_default\_render([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source)[](#c.obs_source_default_render "Link to this definition") Can be used by filters to directly render a non-async parent source without any filter processing. * * * void obs\_source\_filter\_add([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, [obs\_source\_t](#c.obs_source_t "obs_source_t") \*filter)[](#c.obs_source_filter_add "Link to this definition") void obs\_source\_filter\_remove([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, [obs\_source\_t](#c.obs_source_t "obs_source_t") \*filter)[](#c.obs_source_filter_remove "Link to this definition") Adds/removes a filter to/from a source. * * * void obs\_source\_filter\_set\_order([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, [obs\_source\_t](#c.obs_source_t "obs_source_t") \*filter, enum obs\_order\_movement movement)[](#c.obs_source_filter_set_order "Link to this definition") Modifies the order of a specific filter. Parameters: * **movement** – Can be one of the following: OBS\_ORDER\_MOVE\_UP OBS\_ORDER\_MOVE\_DOWN OBS\_ORDER\_MOVE\_TOP OBS\_ORDER\_MOVE\_BOTTOM * * * void obs\_source\_filter\_set\_index([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, [obs\_source\_t](#c.obs_source_t "obs_source_t") \*filter, size\_t index)[](#c.obs_source_filter_set_index "Link to this definition") Moves a filter to the specified index in the filters array. Parameters: * **index** – The index to move the filter to. Added in version 30.0. * * * int obs\_source\_filter\_get\_index([obs\_source\_t](#c.obs_source_t "obs_source_t") \*source, [obs\_source\_t](#c.obs_source_t "obs_source_t") \*filter)[](#c.obs_source_filter_get_index "Link to this definition") Gets the index of the specified filter. Returns: Index of the filter or -1 if it is invalid/not found. Added in version 30.0. Functions used by filters[](#functions-used-by-filters "Link to this heading") -------------------------------------------------------------------------------- bool obs\_source\_process\_filter\_begin([obs\_source\_t](#c.obs_source_t "obs_source_t") \*filter, enum [gs\_color\_format](reference-libobs-graphics-graphics#c.gs_color_format "gs_color_format") format, enum obs\_allow\_direct\_render allow\_direct)[](#c.obs_source_process_filter_begin "Link to this definition") Default RGB filter handler for generic effect filters. Processes the filter chain and renders them to texture if needed, then the filter is drawn with. After calling this, set your parameters for the effect, then call obs\_source\_process\_filter\_end to draw the filter. Returns: _true_ if filtering should continue, _false_ if the filter is bypassed for whatever reason * * * bool obs\_source\_process\_filter\_begin\_with\_color\_space([obs\_source\_t](#c.obs_source_t "obs_source_t") \*filter, enum [gs\_color\_format](reference-libobs-graphics-graphics#c.gs_color_format "gs_color_format") format, enum [gs\_color\_space](reference-libobs-graphics-graphics#c.gs_color_space "gs_color_space") space, enum obs\_allow\_direct\_render allow\_direct)[](#c.obs_source_process_filter_begin_with_color_space "Link to this definition") Similar to obs\_source\_process\_filter\_begin, but also set the active color space. Returns: _true_ if filtering should continue, _false_ if the filter is bypassed for whatever reason * * * void obs\_source\_process\_filter\_end([obs\_source\_t](#c.obs_source_t "obs_source_t") \*filter, [gs\_effect\_t](reference-libobs-graphics-effects#c.gs_effect_t "gs_effect_t") \*effect, uint32\_t width, uint32\_t height)[](#c.obs_source_process_filter_end "Link to this definition") Draws the filter using the effect’s “Draw” technique. Before calling this function, first call obs\_source\_process\_filter\_begin and then set the effect parameters, and then call this function to finalize the filter. * * * void obs\_source\_process\_filter\_tech\_end([obs\_source\_t](#c.obs_source_t "obs_source_t") \*filter, [gs\_effect\_t](reference-libobs-graphics-effects#c.gs_effect_t "gs_effect_t") \*effect, uint32\_t width, uint32\_t height, const char \*tech\_name)[](#c.obs_source_process_filter_tech_end "Link to this definition") Draws the filter with a specific technique in the effect. Before calling this function, first call obs\_source\_process\_filter\_begin and then set the effect parameters, and then call this function to finalize the filter. * * * void obs\_source\_skip\_video\_filter([obs\_source\_t](#c.obs_source_t "obs_source_t") \*filter)[](#c.obs_source_skip_video_filter "Link to this definition") Skips the filter if the filter is invalid and cannot be rendered. * * * Transitions[](#transitions "Link to this heading") ---------------------------------------------------- [obs\_source\_t](#c.obs_source_t "obs_source_t") \*obs\_transition\_get\_source([obs\_source\_t](#c.obs_source_t "obs_source_t") \*transition, enum obs\_transition\_target target)[](#c.obs_transition_get_source "Link to this definition") Parameters: * **target** – OBS\_TRANSITION\_SOURCE\_A - Source being transitioned from, or the current source if not transitioning OBS\_TRANSITION\_SOURCE\_B - Source being transitioned to Returns: An incremented reference to the source or destination sources of the transition. Use [`obs_source_release()`](#c.obs_source_release "obs_source_release") to release it. * * * void obs\_transition\_clear([obs\_source\_t](#c.obs_source_t "obs_source_t") \*transition)[](#c.obs_transition_clear "Link to this definition") Clears the transition. * * * [obs\_source\_t](#c.obs_source_t "obs_source_t") \*obs\_transition\_get\_active\_source([obs\_source\_t](#c.obs_source_t "obs_source_t") \*transition)[](#c.obs_transition_get_active_source "Link to this definition") Returns: An incremented reference to the currently active source of the transition. Use [`obs_source_release()`](#c.obs_source_release "obs_source_release") to release it. * * * bool obs\_transition\_start([obs\_source\_t](#c.obs_source_t "obs_source_t") \*transition, enum obs\_transition\_mode mode, uint32\_t duration\_ms, [obs\_source\_t](#c.obs_source_t "obs_source_t") \*dest)[](#c.obs_transition_start "Link to this definition") Starts the transition with the desired destination source. Parameters: * **mode** – Currently only OBS\_TRANSITION\_MODE\_AUTO * **duration\_ms** – Duration in milliseconds. If the transition has a fixed duration set by [`obs_transition_enable_fixed()`](#c.obs_transition_enable_fixed "obs_transition_enable_fixed") , this parameter will have no effect * **dest** – The destination source to transition to * * * void obs\_transition\_set\_size([obs\_source\_t](#c.obs_source_t "obs_source_t") \*transition, uint32\_t cx, uint32\_t cy)[](#c.obs_transition_set_size "Link to this definition") void obs\_transition\_get\_size(const [obs\_source\_t](#c.obs_source_t "obs_source_t") \*transition, uint32\_t \*cx, uint32\_t \*cy)[](#c.obs_transition_get_size "Link to this definition") Sets/gets the dimensions of the transition. * * * void obs\_transition\_set\_scale\_type([obs\_source\_t](#c.obs_source_t "obs_source_t") \*transition, enum obs\_transition\_scale\_type type)[](#c.obs_transition_set_scale_type "Link to this definition") enum obs\_transition\_scale\_type obs\_transition\_get\_scale\_type(const [obs\_source\_t](#c.obs_source_t "obs_source_t") \*transition)[](#c.obs_transition_get_scale_type "Link to this definition") Sets/gets the scale type for sources within the transition. Parameters: * **type** – OBS\_TRANSITION\_SCALE\_MAX\_ONLY - Scale to aspect ratio, but only to the maximum size of each source OBS\_TRANSITION\_SCALE\_ASPECT - Always scale the sources, but keep aspect ratio OBS\_TRANSITION\_SCALE\_STRETCH - Scale and stretch the sources to the size of the transition * * * void obs\_transition\_set\_alignment([obs\_source\_t](#c.obs_source_t "obs_source_t") \*transition, uint32\_t alignment)[](#c.obs_transition_set_alignment "Link to this definition") uint32\_t obs\_transition\_get\_alignment(const [obs\_source\_t](#c.obs_source_t "obs_source_t") \*transition)[](#c.obs_transition_get_alignment "Link to this definition") Sets/gets the alignment used to draw the two sources within transition the transition. Parameters: * **alignment** – Can be any bitwise OR combination of: OBS\_ALIGN\_CENTER OBS\_ALIGN\_LEFT OBS\_ALIGN\_RIGHT OBS\_ALIGN\_TOP OBS\_ALIGN\_BOTTOM * * * Functions used by transitions[](#functions-used-by-transitions "Link to this heading") ---------------------------------------------------------------------------------------- void obs\_transition\_enable\_fixed([obs\_source\_t](#c.obs_source_t "obs_source_t") \*transition, bool enable, uint32\_t duration\_ms)[](#c.obs_transition_enable_fixed "Link to this definition") bool obs\_transition\_fixed([obs\_source\_t](#c.obs_source_t "obs_source_t") \*transition)[](#c.obs_transition_fixed "Link to this definition") Sets/gets whether the transition uses a fixed duration. Useful for certain types of transitions such as stingers. If this is set, the _duration\_ms_ parameter of [`obs_transition_start()`](#c.obs_transition_start "obs_transition_start") has no effect. * * * float obs\_transition\_get\_time([obs\_source\_t](#c.obs_source_t "obs_source_t") \*transition)[](#c.obs_transition_get_time "Link to this definition") Returns: The current transition time value (0.0f..1.0f) * * * void obs\_transition\_video\_render([obs\_source\_t](#c.obs_source_t "obs_source_t") \*transition, obs\_transition\_video\_render\_callback\_t callback)[](#c.obs_transition_video_render "Link to this definition") void obs\_transition\_video\_render2([obs\_source\_t](#c.obs_source_t "obs_source_t") \*transition, obs\_transition\_video\_render\_callback\_t callback, [gs\_texture\_t](reference-libobs-graphics-graphics#c.gs_texture_t "gs_texture_t") \*placeholder\_texture)[](#c.obs_transition_video_render2 "Link to this definition") Helper function used for rendering transitions. This function will render two distinct textures for source A and source B of the transition, allowing the ability to blend them together with a pixel shader in a desired manner. The _a_ and _b_ parameters of _callback_ are automatically rendered textures of source A and source B, _t_ is the time value (0.0f..1.0f), _cx_ and _cy_ are the current dimensions of the transition, and _data_ is the implementation’s private data. The _placeholder\_texture_ parameter allows a callback to receive a replacement that isn’t the default transparent texture, including NULL if the caller desires. Relevant data types used with this function: typedef void (\*obs\_transition\_video\_render\_callback\_t)(void \*data, gs\_texture\_t \*a, gs\_texture\_t \*b, float t, uint32\_t cx, uint32\_t cy); * * * enum [gs\_color\_space](reference-libobs-graphics-graphics#c.gs_color_space "gs_color_space") obs\_transition\_video\_get\_color\_space([obs\_source\_t](#c.obs_source_t "obs_source_t") \*transition)[](#c.obs_transition_video_get_color_space "Link to this definition") Figure out the color space that encompasses both child sources. The wider space wins. Returns: The color space of the transition * * * bool obs\_transition\_audio\_render([obs\_source\_t](#c.obs_source_t "obs_source_t") \*transition, uint64\_t \*ts\_out, struct obs\_source\_audio\_mix \*audio, uint32\_t mixers, size\_t channels, size\_t sample\_rate, obs\_transition\_audio\_mix\_callback\_t mix\_a\_callback, obs\_transition\_audio\_mix\_callback\_t mix\_b\_callback)[](#c.obs_transition_audio_render "Link to this definition") Helper function used for transitioning audio. Typically you’d call this in the obs\_source\_info.audio\_render callback with its parameters, and use the mix\_a\_callback and mix\_b\_callback to determine the the audio fading of source A and source B. Relevant data types used with this function: typedef float (\*obs\_transition\_audio\_mix\_callback\_t)(void \*data, float t); * * * void obs\_transition\_swap\_begin([obs\_source\_t](#c.obs_source_t "obs_source_t") \*tr\_dest, [obs\_source\_t](#c.obs_source_t "obs_source_t") \*tr\_source)[](#c.obs_transition_swap_begin "Link to this definition") void obs\_transition\_swap\_end([obs\_source\_t](#c.obs_source_t "obs_source_t") \*tr\_dest, [obs\_source\_t](#c.obs_source_t "obs_source_t") \*tr\_source)[](#c.obs_transition_swap_end "Link to this definition") Swaps two transitions. Call obs\_transition\_swap\_begin, swap the source, then call obs\_transition\_swap\_end when complete. This allows the ability to seamlessly swap two different transitions without it affecting the output. For example, if a transition is assigned to output channel 0, you’d call obs\_transition\_swap\_begin, then you’d call obs\_set\_output\_source with the new transition, then call [`obs_transition_swap_begin()`](#c.obs_transition_swap_begin "obs_transition_swap_begin") . --- # Data Settings API Reference (obs_data_t) — OBS Studio 31.0.2 documentation * [](index) * [Core API Object Reference](reference-core-objects) * Data Settings API Reference (obs\_data\_t) * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/reference-settings.rst) [Previous](reference-services "Service API Reference (obs_service_t)") [Next](reference-properties "Properties API Reference (obs_properties_t)") * * * Data Settings API Reference (obs\_data\_t)[](#data-settings-api-reference-obs-data-t "Link to this heading") ============================================================================================================== 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[](#c.obs_data_t "Link to this definition") A reference-counted data object. type obs\_data\_array\_t[](#c.obs_data_array_t "Link to this definition") A reference-counted data array object. #include General Functions[](#general-functions "Link to this heading") ---------------------------------------------------------------- [obs\_data\_t](#c.obs_data_t "obs_data_t") \*obs\_data\_create()[](#c.obs_data_create "Link to this definition") Returns: A new reference to a data object. Release with [`obs_data_release()`](#c.obs_data_release "obs_data_release") . * * * [obs\_data\_t](#c.obs_data_t "obs_data_t") \*obs\_data\_create\_from\_json(const char \*json\_string)[](#c.obs_data_create_from_json "Link to this definition") Creates a data object from a Json string. Parameters: * **json\_string** – Json string Returns: A new reference to a data object. Release with [`obs_data_release()`](#c.obs_data_release "obs_data_release") . * * * [obs\_data\_t](#c.obs_data_t "obs_data_t") \*obs\_data\_create\_from\_json\_file(const char \*json\_file)[](#c.obs_data_create_from_json_file "Link to this definition") Creates a data object from a Json file. Parameters: * **json\_file** – Json file path Returns: A new reference to a data object. Release with [`obs_data_release()`](#c.obs_data_release "obs_data_release") . * * * [obs\_data\_t](#c.obs_data_t "obs_data_t") \*obs\_data\_create\_from\_json\_file\_safe(const char \*json\_file, const char \*backup\_ext)[](#c.obs_data_create_from_json_file_safe "Link to this definition") Creates a data object from a Json file, with a backup file in case the original is corrupted or fails to load. Parameters: * **json\_file** – Json file path * **backup\_ext** – Backup file extension Returns: A new reference to a data object. Release with [`obs_data_release()`](#c.obs_data_release "obs_data_release") . * * * void obs\_data\_addref([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data)[](#c.obs_data_addref "Link to this definition") void obs\_data\_release([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data)[](#c.obs_data_release "Link to this definition") Adds/releases a reference to a data object. * * * const char \*obs\_data\_get\_json([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data)[](#c.obs_data_get_json "Link to this definition") Generates a new json string. The string allocation is stored within the data object itself, and does not need to be manually freed. Returns: Json string for this object * * * const char \*obs\_data\_get\_json\_with\_defaults([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data)[](#c.obs_data_get_json_with_defaults "Link to this definition") Same as [`obs_data_get_json()`](#c.obs_data_get_json "obs_data_get_json") but default values are also serialized. Returns: Json string for this object * * * const char \*obs\_data\_get\_json\_pretty([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data)[](#c.obs_data_get_json_pretty "Link to this definition") Same as [`obs_data_get_json()`](#c.obs_data_get_json "obs_data_get_json") but the JSON data is pretty-printed. Returns: Json string for this object * * * const char \*obs\_data\_get\_json\_pretty\_with\_defaults([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data)[](#c.obs_data_get_json_pretty_with_defaults "Link to this definition") Same as [`obs_data_get_json_pretty()`](#c.obs_data_get_json_pretty "obs_data_get_json_pretty") but default values are also serialized. Returns: Json string for this object * * * const char \*obs\_data\_get\_last\_json([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data)[](#c.obs_data_get_last_json "Link to this definition") Returns the last json string generated for this data object. Does not generate a new string. Use [`obs_data_get_json()`](#c.obs_data_get_json "obs_data_get_json") to generate a json string first. Returns: Json string for this object * * * bool obs\_data\_save\_json([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data, const char \*file)[](#c.obs_data_save_json "Link to this definition") Saves the data to a file as Json text. Parameters: * **file** – The file to save to Returns: _true_ if successful, _false_ otherwise * * * bool obs\_data\_save\_json\_safe([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data, const char \*file, const char \*temp\_ext, const char \*backup\_ext)[](#c.obs_data_save_json_safe "Link to this definition") 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. Parameters: * **file** – The file to save to * **backup\_ext** – The backup extension to use for the overwritten file if it exists Returns: _true_ if successful, _false_ otherwise * * * void obs\_data\_apply([obs\_data\_t](#c.obs_data_t "obs_data_t") \*target, [obs\_data\_t](#c.obs_data_t "obs_data_t") \*apply\_data)[](#c.obs_data_apply "Link to this definition") Merges the data of _apply\_data_ in to _target_. * * * void obs\_data\_erase([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data, const char \*name)[](#c.obs_data_erase "Link to this definition") Erases the user data for item _name_ within the data object. * * * void obs\_data\_clear([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data)[](#c.obs_data_clear "Link to this definition") Clears all user data in the data object. * * * Set Functions[](#set-functions "Link to this heading") -------------------------------------------------------- void obs\_data\_set\_string([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data, const char \*name, const char \*val)[](#c.obs_data_set_string "Link to this definition") * * * void obs\_data\_set\_int([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data, const char \*name, long long val)[](#c.obs_data_set_int "Link to this definition") * * * void obs\_data\_set\_double([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data, const char \*name, double val)[](#c.obs_data_set_double "Link to this definition") * * * void obs\_data\_set\_bool([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data, const char \*name, bool val)[](#c.obs_data_set_bool "Link to this definition") * * * void obs\_data\_set\_obj([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data, const char \*name, [obs\_data\_t](#c.obs_data_t "obs_data_t") \*obj)[](#c.obs_data_set_obj "Link to this definition") * * * void obs\_data\_set\_array([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data, const char \*name, [obs\_data\_array\_t](#c.obs_data_array_t "obs_data_array_t") \*array)[](#c.obs_data_set_array "Link to this definition") * * * Get Functions[](#get-functions "Link to this heading") -------------------------------------------------------- const char \*obs\_data\_get\_string([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data, const char \*name)[](#c.obs_data_get_string "Link to this definition") * * * long long obs\_data\_get\_int([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data, const char \*name)[](#c.obs_data_get_int "Link to this definition") * * * double obs\_data\_get\_double([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data, const char \*name)[](#c.obs_data_get_double "Link to this definition") * * * bool obs\_data\_get\_bool([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data, const char \*name)[](#c.obs_data_get_bool "Link to this definition") * * * [obs\_data\_t](#c.obs_data_t "obs_data_t") \*obs\_data\_get\_obj([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data, const char \*name)[](#c.obs_data_get_obj "Link to this definition") Returns: An incremented reference to a data object. Release with [`obs_data_release()`](#c.obs_data_release "obs_data_release") . * * * [obs\_data\_array\_t](#c.obs_data_array_t "obs_data_array_t") \*obs\_data\_get\_array([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data, const char \*name)[](#c.obs_data_get_array "Link to this definition") Returns: An incremented reference to a data array object. Release with [`obs_data_array_release()`](#c.obs_data_array_release "obs_data_array_release") . * * * Default Value Functions[](#default-value-functions "Link to this heading") ---------------------------------------------------------------------------- Default values are used to determine what value will be given if a value is not set. [obs\_data\_t](#c.obs_data_t "obs_data_t") \*obs\_data\_get\_defaults([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data);[](#c.obs_data_get_defaults "Link to this definition") Returns: obs\_data\_t \* with all default values (recursively for all objects as well). * * * void obs\_data\_set\_default\_string([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data, const char \*name, const char \*val)[](#c.obs_data_set_default_string "Link to this definition") const char \*obs\_data\_get\_default\_string([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data, const char \*name)[](#c.obs_data_get_default_string "Link to this definition") * * * void obs\_data\_set\_default\_int([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data, const char \*name, long long val)[](#c.obs_data_set_default_int "Link to this definition") long long obs\_data\_get\_default\_int([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data, const char \*name)[](#c.obs_data_get_default_int "Link to this definition") * * * void obs\_data\_set\_default\_double([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data, const char \*name, double val)[](#c.obs_data_set_default_double "Link to this definition") double obs\_data\_get\_default\_double([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data, const char \*name)[](#c.obs_data_get_default_double "Link to this definition") * * * void obs\_data\_set\_default\_bool([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data, const char \*name, bool val)[](#c.obs_data_set_default_bool "Link to this definition") bool obs\_data\_get\_default\_bool([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data, const char \*name)[](#c.obs_data_get_default_bool "Link to this definition") * * * void obs\_data\_set\_default\_obj([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data, const char \*name, [obs\_data\_t](#c.obs_data_t "obs_data_t") \*obj)[](#c.obs_data_set_default_obj "Link to this definition") [obs\_data\_t](#c.obs_data_t "obs_data_t") \*obs\_data\_get\_default\_obj([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data, const char \*name)[](#c.obs_data_get_default_obj "Link to this definition") Returns: An incremented reference to a data object. Release with [`obs_data_release()`](#c.obs_data_release "obs_data_release") . * * * void obs\_data\_set\_default\_array([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data, const char \*name, [obs\_data\_array\_t](#c.obs_data_array_t "obs_data_array_t") \*arr)[](#c.obs_data_set_default_array "Link to this definition") [obs\_data\_array\_t](#c.obs_data_array_t "obs_data_array_t") \*obs\_data\_get\_default\_array([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data, const char \*name)[](#c.obs_data_get_default_array "Link to this definition") Autoselect Functions[](#autoselect-functions "Link to this heading") ---------------------------------------------------------------------- Autoselect values are optionally used to determine what values should be used to ensure functionality if the currently set values are inappropriate or invalid. void obs\_data\_set\_autoselect\_string([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data, const char \*name, const char \*val)[](#c.obs_data_set_autoselect_string "Link to this definition") const char \*obs\_data\_get\_autoselect\_string([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data, const char \*name)[](#c.obs_data_get_autoselect_string "Link to this definition") * * * void obs\_data\_set\_autoselect\_int([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data, const char \*name, long long val)[](#c.obs_data_set_autoselect_int "Link to this definition") long long obs\_data\_get\_autoselect\_int([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data, const char \*name)[](#c.obs_data_get_autoselect_int "Link to this definition") * * * void obs\_data\_set\_autoselect\_double([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data, const char \*name, double val)[](#c.obs_data_set_autoselect_double "Link to this definition") double obs\_data\_get\_autoselect\_double([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data, const char \*name)[](#c.obs_data_get_autoselect_double "Link to this definition") * * * void obs\_data\_set\_autoselect\_bool([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data, const char \*name, bool val)[](#c.obs_data_set_autoselect_bool "Link to this definition") bool obs\_data\_get\_autoselect\_bool([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data, const char \*name)[](#c.obs_data_get_autoselect_bool "Link to this definition") * * * void obs\_data\_set\_autoselect\_obj([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data, const char \*name, [obs\_data\_t](#c.obs_data_t "obs_data_t") \*obj)[](#c.obs_data_set_autoselect_obj "Link to this definition") [obs\_data\_t](#c.obs_data_t "obs_data_t") \*obs\_data\_get\_autoselect\_obj([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data, const char \*name)[](#c.obs_data_get_autoselect_obj "Link to this definition") Returns: An incremented reference to a data object. Release with [`obs_data_release()`](#c.obs_data_release "obs_data_release") . * * * void obs\_data\_set\_autoselect\_array([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data, const char \*name, [obs\_data\_array\_t](#c.obs_data_array_t "obs_data_array_t") \*arr)[](#c.obs_data_set_autoselect_array "Link to this definition") [obs\_data\_array\_t](#c.obs_data_array_t "obs_data_array_t") \*obs\_data\_get\_autoselect\_array([obs\_data\_t](#c.obs_data_t "obs_data_t") \*data, const char \*name)[](#c.obs_data_get_autoselect_array "Link to this definition") Returns: An incremented reference to a data array object. Release with [`obs_data_array_release()`](#c.obs_data_array_release "obs_data_array_release") . Added in version 30.1. * * * Array Functions[](#array-functions "Link to this heading") ------------------------------------------------------------ [obs\_data\_array\_t](#c.obs_data_array_t "obs_data_array_t") \*obs\_data\_array\_create()[](#c.obs_data_array_create "Link to this definition") Returns: A new reference to a data array object. Release with [`obs_data_array_release()`](#c.obs_data_array_release "obs_data_array_release") . * * * void obs\_data\_array\_addref([obs\_data\_array\_t](#c.obs_data_array_t "obs_data_array_t") \*array)[](#c.obs_data_array_addref "Link to this definition") * * * void obs\_data\_array\_release([obs\_data\_array\_t](#c.obs_data_array_t "obs_data_array_t") \*array)[](#c.obs_data_array_release "Link to this definition") * * * size\_t obs\_data\_array\_count([obs\_data\_array\_t](#c.obs_data_array_t "obs_data_array_t") \*array)[](#c.obs_data_array_count "Link to this definition") * * * [obs\_data\_t](#c.obs_data_t "obs_data_t") \*obs\_data\_array\_item([obs\_data\_array\_t](#c.obs_data_array_t "obs_data_array_t") \*array, size\_t idx)[](#c.obs_data_array_item "Link to this definition") Returns: An incremented reference to the data object associated with this array entry. Release with [`obs_data_release()`](#c.obs_data_release "obs_data_release") . * * * size\_t obs\_data\_array\_push\_back([obs\_data\_array\_t](#c.obs_data_array_t "obs_data_array_t") \*array, [obs\_data\_t](#c.obs_data_t "obs_data_t") \*obj)[](#c.obs_data_array_push_back "Link to this definition") * * * void obs\_data\_array\_insert([obs\_data\_array\_t](#c.obs_data_array_t "obs_data_array_t") \*array, size\_t idx, [obs\_data\_t](#c.obs_data_t "obs_data_t") \*obj)[](#c.obs_data_array_insert "Link to this definition") * * * void obs\_data\_array\_erase([obs\_data\_array\_t](#c.obs_data_array_t "obs_data_array_t") \*array, size\_t idx)[](#c.obs_data_array_erase "Link to this definition") --- # Properties API Reference (obs_properties_t) — OBS Studio 31.0.2 documentation * [](index) * [Core API Object Reference](reference-core-objects) * Properties API Reference (obs\_properties\_t) * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/reference-properties.rst) [Previous](reference-settings "Data Settings API Reference (obs_data_t)") [Next](reference-libobs-util "Platform/Utility API Reference (libobs/util)") * * * Properties API Reference (obs\_properties\_t)[](#properties-api-reference-obs-properties-t "Link to this heading") ==================================================================================================================== 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[](#c.obs_properties_t "Link to this definition") Properties object (not reference counted). type obs\_property\_t[](#c.obs_property_t "Link to this definition") A property object (not reference counted). #include General Functions[](#general-functions "Link to this heading") ---------------------------------------------------------------- [obs\_properties\_t](#c.obs_properties_t "obs_properties_t") \*obs\_properties\_create(void)[](#c.obs_properties_create "Link to this definition") Returns: A new properties object. * * * [obs\_properties\_t](#c.obs_properties_t "obs_properties_t") \*obs\_properties\_create\_param(void \*param, void (\*destroy)(void \*param))[](#c.obs_properties_create_param "Link to this definition") 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. Returns: A new properties object. * * * void obs\_properties\_destroy([obs\_properties\_t](#c.obs_properties_t "obs_properties_t") \*props)[](#c.obs_properties_destroy "Link to this definition") * * * void obs\_properties\_set\_flags([obs\_properties\_t](#c.obs_properties_t "obs_properties_t") \*props, uint32\_t flags)[](#c.obs_properties_set_flags "Link to this definition") uint32\_t obs\_properties\_get\_flags([obs\_properties\_t](#c.obs_properties_t "obs_properties_t") \*props)[](#c.obs_properties_get_flags "Link to this definition") Parameters: * **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 * * * void obs\_properties\_set\_param([obs\_properties\_t](#c.obs_properties_t "obs_properties_t") \*props, void \*param, void (\*destroy)(void \*param))[](#c.obs_properties_set_param "Link to this definition") void \*obs\_properties\_get\_param([obs\_properties\_t](#c.obs_properties_t "obs_properties_t") \*props)[](#c.obs_properties_get_param "Link to this definition") 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. * * * void obs\_properties\_apply\_settings([obs\_properties\_t](#c.obs_properties_t "obs_properties_t") \*props, [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*settings)[](#c.obs_properties_apply_settings "Link to this definition") Applies settings to the properties by calling all the necessary modification callbacks * * * [obs\_properties\_t](#c.obs_properties_t "obs_properties_t") \*obs\_properties\_get\_parent([obs\_properties\_t](#c.obs_properties_t "obs_properties_t") \*props)[](#c.obs_properties_get_parent "Link to this definition") * * * void obs\_properties\_remove\_by\_name([obs\_properties\_t](#c.obs_properties_t "obs_properties_t") \*props, const char \*property)[](#c.obs_properties_remove_by_name "Link to this definition") Removes a property from a properties list. Only valid in `get_properties`, `script_properties` for scripts, `modified_callback`, and `modified_callback2`. `modified_callback` and `modified_callback2` _must_ return true so that all UI properties are rebuilt. Returning false is undefined behavior. Parameters: * **props** – Properties to remove from. * **property** – Name of the property to remove. * * * Property Object Functions[](#property-object-functions "Link to this heading") -------------------------------------------------------------------------------- [obs\_property\_t](#c.obs_property_t "obs_property_t") \*obs\_properties\_add\_bool([obs\_properties\_t](#c.obs_properties_t "obs_properties_t") \*props, const char \*name, const char \*description)[](#c.obs_properties_add_bool "Link to this definition") Adds a boolean property. Parameters: * **name** – Setting identifier string * **description** – Localized name shown to user Returns: The property * * * [obs\_property\_t](#c.obs_property_t "obs_property_t") \*obs\_properties\_add\_int([obs\_properties\_t](#c.obs_properties_t "obs_properties_t") \*props, const char \*name, const char \*description, int min, int max, int step)[](#c.obs_properties_add_int "Link to this definition") Adds an integer property. Parameters: * **name** – Setting identifier string * **description** – Localized name shown to user * **min** – Minimum value * **max** – Maximum value * **step** – Step value Returns: The property * * * [obs\_property\_t](#c.obs_property_t "obs_property_t") \*obs\_properties\_add\_float([obs\_properties\_t](#c.obs_properties_t "obs_properties_t") \*props, const char \*name, const char \*description, double min, double max, double step)[](#c.obs_properties_add_float "Link to this definition") Parameters: * **name** – Setting identifier string * **description** – Localized name shown to user * **min** – Minimum value * **max** – Maximum value * **step** – Step value Returns: The property * * * [obs\_property\_t](#c.obs_property_t "obs_property_t") \*obs\_properties\_add\_int\_slider([obs\_properties\_t](#c.obs_properties_t "obs_properties_t") \*props, const char \*name, const char \*description, int min, int max, int step)[](#c.obs_properties_add_int_slider "Link to this definition") Parameters: * **name** – Setting identifier string * **description** – Localized name shown to user * **min** – Minimum value * **max** – Maximum value * **step** – Step value Returns: The property * * * [obs\_property\_t](#c.obs_property_t "obs_property_t") \*obs\_properties\_add\_float\_slider([obs\_properties\_t](#c.obs_properties_t "obs_properties_t") \*props, const char \*name, const char \*description, double min, double max, double step)[](#c.obs_properties_add_float_slider "Link to this definition") Parameters: * **name** – Setting identifier string * **description** – Localized name shown to user * **min** – Minimum value * **max** – Maximum value * **step** – Step value Returns: The property * * * [obs\_property\_t](#c.obs_property_t "obs_property_t") \*obs\_properties\_add\_text([obs\_properties\_t](#c.obs_properties_t "obs_properties_t") \*props, const char \*name, const char \*description, enum obs\_text\_type type)[](#c.obs_properties_add_text "Link to this definition") Parameters: * **name** – Setting identifier string * **description** – Localized name shown to user * **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 * **OBS\_TEXT\_INFO** - Read-only informative text, behaves differently depending on wether description, string value and long description are set Returns: The property Important Related Functions: * [`obs_property_text_set_info_type()`](#c.obs_property_text_set_info_type "obs_property_text_set_info_type") * [`obs_property_text_set_info_word_wrap()`](#c.obs_property_text_set_info_word_wrap "obs_property_text_set_info_word_wrap") * * * [obs\_property\_t](#c.obs_property_t "obs_property_t") \*obs\_properties\_add\_path([obs\_properties\_t](#c.obs_properties_t "obs_properties_t") \*props, const char \*name, const char \*description, enum obs\_path\_type type, const char \*filter, const char \*default\_path)[](#c.obs_properties_add_path "Link to this definition") 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 semicolons, and extensions separated by space: "Example types 1 and 2 (\*.ex1 \*.ex2);;Example type 3 (\*.ex3)" Parameters: * **name** – Setting identifier string * **description** – Localized name shown to user * **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 * **filter** – If type is a file path, then describes the file filter that the user can browse. Items are separated via double semicolons. If multiple file types in a filter, separate with space. * **default\_path** – The default path to start in, or _NULL_ Returns: The property * * * [obs\_property\_t](#c.obs_property_t "obs_property_t") \*obs\_properties\_add\_list([obs\_properties\_t](#c.obs_properties_t "obs_properties_t") \*props, const char \*name, const char \*description, enum obs\_combo\_type type, enum obs\_combo\_format format)[](#c.obs_properties_add_list "Link to this definition") Adds an integer/string/floating point item list. This would be implemented as a combo box in user interface. Parameters: * **name** – Setting identifier string * **description** – Localized name shown to user * **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 editable. Displayed as combo box. * **OBS\_COMBO\_TYPE\_RADIO** - Not editable. Displayed as radio buttons. > Added in version 30.0. * **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 * **OBS\_COMBO\_FORMAT\_BOOL** - Boolean list > Added in version 30.0. Returns: The property Important Related Functions: * [`obs_property_list_add_string()`](#c.obs_property_list_add_string "obs_property_list_add_string") * [`obs_property_list_add_int()`](#c.obs_property_list_add_int "obs_property_list_add_int") * [`obs_property_list_add_float()`](#c.obs_property_list_add_float "obs_property_list_add_float") * [`obs_property_list_insert_string()`](#c.obs_property_list_insert_string "obs_property_list_insert_string") * [`obs_property_list_insert_int()`](#c.obs_property_list_insert_int "obs_property_list_insert_int") * [`obs_property_list_insert_float()`](#c.obs_property_list_insert_float "obs_property_list_insert_float") * [`obs_property_list_item_remove()`](#c.obs_property_list_item_remove "obs_property_list_item_remove") * [`obs_property_list_clear()`](#c.obs_property_list_clear "obs_property_list_clear") * * * [obs\_property\_t](#c.obs_property_t "obs_property_t") \*obs\_properties\_add\_color([obs\_properties\_t](#c.obs_properties_t "obs_properties_t") \*props, const char \*name, const char \*description)[](#c.obs_properties_add_color "Link to this definition") Adds a color property without alpha (stored internally with an alpha value of 255). The color can be retrieved from an [`obs_data_t`](reference-settings#c.obs_data_t "obs_data_t") object by using [`obs_data_get_int()`](reference-settings#c.obs_data_get_int "obs_data_get_int") . Parameters: * **name** – Setting identifier string * **description** – Localized name shown to user Returns: The property * * * [obs\_property\_t](#c.obs_property_t "obs_property_t") \*obs\_properties\_add\_color\_alpha([obs\_properties\_t](#c.obs_properties_t "obs_properties_t") \*props, const char \*name, const char \*description)[](#c.obs_properties_add_color_alpha "Link to this definition") Adds a color property with alpha. The color can be retrieved from an [`obs_data_t`](reference-settings#c.obs_data_t "obs_data_t") object by using [`obs_data_get_int()`](reference-settings#c.obs_data_get_int "obs_data_get_int") . Parameters: * **name** – Setting identifier string * **description** – Localized name shown to user Returns: The property * * * [obs\_property\_t](#c.obs_property_t "obs_property_t") \*obs\_properties\_add\_button([obs\_properties\_t](#c.obs_properties_t "obs_properties_t") \*props, const char \*name, const char \*text, obs\_property\_clicked\_t callback)[](#c.obs_properties_add_button "Link to this definition") [obs\_property\_t](#c.obs_property_t "obs_property_t") \*obs\_properties\_add\_button2([obs\_properties\_t](#c.obs_properties_t "obs_properties_t") \*props, const char \*name, const char \*text, obs\_property\_clicked\_t callback, void \*priv)[](#c.obs_properties_add_button2 "Link to this definition") 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. If the properties need to be refreshed due to changes to the property layout, the callback should return true, otherwise return false. Parameters: * **name** – Setting identifier string * **text** – Localized name shown to user * **callback** – Callback to be executed when the button is pressed * **priv** – Pointer passed back as the data argument of the callback Returns: The property Important Related Functions: > * [`obs_property_button_set_type()`](#c.obs_property_button_set_type "obs_property_button_set_type") > > * [`obs_property_button_set_url()`](#c.obs_property_button_set_url "obs_property_button_set_url") > For scripting, use [`obs_properties_add_button()`](scripting#obs_properties_add_button "obs_properties_add_button") . Relevant data types used with this function: typedef bool (\*obs\_property\_clicked\_t)(obs\_properties\_t \*props, obs\_property\_t \*property, void \*data); * * * [obs\_property\_t](#c.obs_property_t "obs_property_t") \*obs\_properties\_add\_font([obs\_properties\_t](#c.obs_properties_t "obs_properties_t") \*props, const char \*name, const char \*description)[](#c.obs_properties_add_font "Link to this definition") Adds a font property. The font can be retrieved from an [`obs_data_t`](reference-settings#c.obs_data_t "obs_data_t") object by using [`obs_data_get_obj()`](reference-settings#c.obs_data_get_obj "obs_data_get_obj") . Parameters: * **name** – Setting identifier string * **description** – Localized name shown to user Returns: The property * * * [obs\_property\_t](#c.obs_property_t "obs_property_t") \*obs\_properties\_add\_editable\_list([obs\_properties\_t](#c.obs_properties_t "obs_properties_t") \*props, const char \*name, const char \*description, enum obs\_editable\_list\_type type, const char \*filter, const char \*default\_path)[](#c.obs_properties_add_editable_list "Link to this definition") Adds a list in which the user can add/insert/remove items. The items can be retrieved from an [`obs_data_t`](reference-settings#c.obs_data_t "obs_data_t") object by using [`obs_data_get_array()`](reference-settings#c.obs_data_get_array "obs_data_get_array") . Parameters: * **name** – Setting identifier string * **description** – Localized name shown to user * **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. * **filter** – File filter to use if a file list * **default\_path** – Default path if a file list Returns: The property * * * [obs\_property\_t](#c.obs_property_t "obs_property_t") \*obs\_properties\_add\_frame\_rate([obs\_properties\_t](#c.obs_properties_t "obs_properties_t") \*props, const char \*name, const char \*description)[](#c.obs_properties_add_frame_rate "Link to this definition") Adds a frame rate property. Parameters: * **name** – Setting identifier string * **description** – Localized name shown to user Returns: The property Important Related Functions: * [`obs_property_frame_rate_option_add()`](#c.obs_property_frame_rate_option_add "obs_property_frame_rate_option_add") * [`obs_property_frame_rate_fps_range_add()`](#c.obs_property_frame_rate_fps_range_add "obs_property_frame_rate_fps_range_add") * [`obs_property_frame_rate_option_insert()`](#c.obs_property_frame_rate_option_insert "obs_property_frame_rate_option_insert") * [`obs_property_frame_rate_fps_range_insert()`](#c.obs_property_frame_rate_fps_range_insert "obs_property_frame_rate_fps_range_insert") * * * [obs\_property\_t](#c.obs_property_t "obs_property_t") \*obs\_properties\_add\_group([obs\_properties\_t](#c.obs_properties_t "obs_properties_t") \*props, const char \*name, const char \*description, enum obs\_group\_type type, [obs\_properties\_t](#c.obs_properties_t "obs_properties_t") \*group)[](#c.obs_properties_add_group "Link to this definition") Adds a property group. Parameters: * **name** – Setting identifier string * **description** – Localized name shown to user * **type** – Can be one of the following values: * **OBS\_GROUP\_NORMAL** - A normal group with just a name and content. * **OBS\_GROUP\_CHECKABLE** - A checkable group with a checkbox, name and content. * **group** – Group to add Returns: The property Important Related Functions: * [`obs_property_group_type()`](#c.obs_property_group_type "obs_property_group_type") * [`obs_property_group_content()`](#c.obs_property_group_content "obs_property_group_content") * [`obs_properties_get_parent()`](#c.obs_properties_get_parent "obs_properties_get_parent") * * * Property Enumeration Functions[](#property-enumeration-functions "Link to this heading") ------------------------------------------------------------------------------------------ [obs\_property\_t](#c.obs_property_t "obs_property_t") \*obs\_properties\_first([obs\_properties\_t](#c.obs_properties_t "obs_properties_t") \*props)[](#c.obs_properties_first "Link to this definition") Returns: The first property in the properties object. * * * [obs\_property\_t](#c.obs_property_t "obs_property_t") \*obs\_properties\_get([obs\_properties\_t](#c.obs_properties_t "obs_properties_t") \*props, const char \*property)[](#c.obs_properties_get "Link to this definition") Parameters: * **property** – The name of the property to get Returns: A specific property or _NULL_ if not found * * * bool obs\_property\_next([obs\_property\_t](#c.obs_property_t "obs_property_t") \*\*p)[](#c.obs_property_next "Link to this definition") Parameters: * **p** – Pointer to the pointer of the next property Returns: _true_ if successful, _false_ if no more properties * * * const char \*obs\_property\_name([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p)[](#c.obs_property_name "Link to this definition") Returns: The setting identifier string of the property _(Author’s Note: “name” was a bad name to use here. Should have been “setting”)_ * * * const char \*obs\_property\_description([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p)[](#c.obs_property_description "Link to this definition") Returns: The actual localized display name of the property _(Author’s note: This one should have been the “name”)_ * * * const char \*obs\_property\_long\_description([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p)[](#c.obs_property_long_description "Link to this definition") Returns: A detailed description of what the setting is used for. Usually used with things like tooltips. * * * enum obs\_property\_type obs\_property\_get\_type([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p)[](#c.obs_property_get_type "Link to this definition") Returns: 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 * OBS\_PROPERTY\_GROUP * * * bool obs\_property\_enabled([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p)[](#c.obs_property_enabled "Link to this definition") * * * bool obs\_property\_visible([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p)[](#c.obs_property_visible "Link to this definition") * * * int obs\_property\_int\_min([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p)[](#c.obs_property_int_min "Link to this definition") * * * int obs\_property\_int\_max([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p)[](#c.obs_property_int_max "Link to this definition") * * * int obs\_property\_int\_step([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p)[](#c.obs_property_int_step "Link to this definition") * * * enum obs\_number\_type obs\_property\_int\_type([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p)[](#c.obs_property_int_type "Link to this definition") * * * const char \*obs\_property\_int\_suffix([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p)[](#c.obs_property_int_suffix "Link to this definition") * * * double obs\_property\_float\_min([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p)[](#c.obs_property_float_min "Link to this definition") * * * double obs\_property\_float\_max([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p)[](#c.obs_property_float_max "Link to this definition") * * * double obs\_property\_float\_step([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p)[](#c.obs_property_float_step "Link to this definition") * * * enum obs\_number\_type obs\_property\_float\_type([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p)[](#c.obs_property_float_type "Link to this definition") * * * const char \*obs\_property\_float\_suffix([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p)[](#c.obs_property_float_suffix "Link to this definition") * * * enum obs\_text\_type obs\_property\_text\_type([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p)[](#c.obs_property_text_type "Link to this definition") * * * bool obs\_property\_text\_monospace([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p)[](#c.obs_property_text_monospace "Link to this definition") Returns whether the input of the text property should be rendered with a monospace font or not. Only has an effect if the text type of the property is `OBS_TEXT_MULTILINE`, even if this returns _true_. * * * enum obs\_text\_info\_type obs\_property\_text\_info\_type([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p)[](#c.obs_property_text_info_type "Link to this definition") Returns: One of the following values: * OBS\_TEXT\_INFO\_NORMAL * OBS\_TEXT\_INFO\_WARNING * OBS\_TEXT\_INFO\_ERROR * * * bool obs\_property\_text\_info\_word\_wrap([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p)[](#c.obs_property_text_info_word_wrap "Link to this definition") * * * enum obs\_path\_type obs\_property\_path\_type([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p)[](#c.obs_property_path_type "Link to this definition") * * * const char \*obs\_property\_path\_filter([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p)[](#c.obs_property_path_filter "Link to this definition") * * * const char \*obs\_property\_path\_default\_path([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p)[](#c.obs_property_path_default_path "Link to this definition") * * * enum obs\_combo\_type obs\_property\_list\_type([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p)[](#c.obs_property_list_type "Link to this definition") * * * enum obs\_combo\_format obs\_property\_list\_format([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p)[](#c.obs_property_list_format "Link to this definition") * * * bool obs\_property\_list\_item\_disabled([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p, size\_t idx)[](#c.obs_property_list_item_disabled "Link to this definition") * * * size\_t obs\_property\_list\_item\_count([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p)[](#c.obs_property_list_item_count "Link to this definition") * * * const char \*obs\_property\_list\_item\_name([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p, size\_t idx)[](#c.obs_property_list_item_name "Link to this definition") * * * const char \*obs\_property\_list\_item\_string([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p, size\_t idx)[](#c.obs_property_list_item_string "Link to this definition") * * * long long obs\_property\_list\_item\_int([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p, size\_t idx)[](#c.obs_property_list_item_int "Link to this definition") * * * double obs\_property\_list\_item\_float([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p, size\_t idx)[](#c.obs_property_list_item_float "Link to this definition") * * * enum obs\_editable\_list\_type obs\_property\_editable\_list\_type([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p)[](#c.obs_property_editable_list_type "Link to this definition") * * * const char \*obs\_property\_editable\_list\_filter([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p)[](#c.obs_property_editable_list_filter "Link to this definition") * * * const char \*obs\_property\_editable\_list\_default\_path([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p)[](#c.obs_property_editable_list_default_path "Link to this definition") * * * size\_t obs\_property\_frame\_rate\_options\_count([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p)[](#c.obs_property_frame_rate_options_count "Link to this definition") * * * const char \*obs\_property\_frame\_rate\_option\_name([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p, size\_t idx)[](#c.obs_property_frame_rate_option_name "Link to this definition") * * * const char \*obs\_property\_frame\_rate\_option\_description([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p, size\_t idx)[](#c.obs_property_frame_rate_option_description "Link to this definition") * * * size\_t obs\_property\_frame\_rate\_fps\_ranges\_count([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p)[](#c.obs_property_frame_rate_fps_ranges_count "Link to this definition") * * * struct media\_frames\_per\_second obs\_property\_frame\_rate\_fps\_range\_min([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p, size\_t idx)[](#c.obs_property_frame_rate_fps_range_min "Link to this definition") * * * struct media\_frames\_per\_second obs\_property\_frame\_rate\_fps\_range\_max([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p, size\_t idx)[](#c.obs_property_frame_rate_fps_range_max "Link to this definition") * * * enum obs\_button\_type obs\_property\_button\_type([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p)[](#c.obs_property_button_type "Link to this definition") Returns: One of the following values: * OBS\_BUTTON\_DEFAULT * OBS\_BUTTON\_URL * * * const char \*obs\_property\_button\_url([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p)[](#c.obs_property_button_url "Link to this definition") * * * enum obs\_group\_type obs\_property\_group\_type([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p)[](#c.obs_property_group_type "Link to this definition") Returns: One of the following values: * OBS\_COMBO\_INVALID * OBS\_GROUP\_NORMAL * OBS\_GROUP\_CHECKABLE * * * [obs\_properties\_t](#c.obs_properties_t "obs_properties_t") \*obs\_property\_group\_content([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p)[](#c.obs_property_group_content "Link to this definition") * * * Property Modification Functions[](#property-modification-functions "Link to this heading") -------------------------------------------------------------------------------------------- void obs\_property\_set\_modified\_callback([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p, obs\_property\_modified\_t modified)[](#c.obs_property_set_modified_callback "Link to this definition") void obs\_property\_set\_modified\_callback2([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p, obs\_property\_modified2\_t modified2, void \*priv)[](#c.obs_property_set_modified_callback2 "Link to this definition") Allows the ability to change the properties depending on what settings are used by the user. The callback should return `true` if the property widgets need to be refreshed due to changes to the property layout. Relevant data types used with these functions: typedef bool (\*obs\_property\_modified\_t)(obs\_properties\_t \*props, obs\_property\_t \*property, obs\_data\_t \*settings); typedef bool (\*obs\_property\_modified2\_t)(void \*priv, obs\_properties\_t \*props, obs\_property\_t \*property, obs\_data\_t \*settings); * * * bool obs\_property\_modified([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p, [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*settings)[](#c.obs_property_modified "Link to this definition") * * * bool obs\_property\_button\_clicked([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p, void \*obj)[](#c.obs_property_button_clicked "Link to this definition") * * * void obs\_property\_set\_visible([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p, bool visible)[](#c.obs_property_set_visible "Link to this definition") * * * void obs\_property\_set\_enabled([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p, bool enabled)[](#c.obs_property_set_enabled "Link to this definition") * * * void obs\_property\_set\_description([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p, const char \*description)[](#c.obs_property_set_description "Link to this definition") Sets the displayed localized name of the property, shown to the user. * * * void obs\_property\_set\_long\_description([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p, const char \*long\_description)[](#c.obs_property_set_long_description "Link to this definition") Sets the localized long description of the property, usually shown to a user via tooltip. * * * void obs\_property\_int\_set\_limits([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p, int min, int max, int step)[](#c.obs_property_int_set_limits "Link to this definition") * * * void obs\_property\_float\_set\_limits([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p, double min, double max, double step)[](#c.obs_property_float_set_limits "Link to this definition") * * * void obs\_property\_int\_set\_suffix([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p, const char \*suffix)[](#c.obs_property_int_set_suffix "Link to this definition") Adds a suffix to the int property, such that 100 will show up as “100ms” if the suffix is “ms”. The user will only be able to edit the number, not the suffix. * * * void obs\_property\_float\_set\_suffix([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p, const char \*suffix)[](#c.obs_property_float_set_suffix "Link to this definition") Adds a suffix to the float property, such that 1.5 will show up as “1.5s” if the suffix is “s”. The user will only be able to edit the number, not the suffix. * * * void obs\_property\_text\_set\_monospace([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p, bool monospace)[](#c.obs_property_text_set_monospace "Link to this definition") Sets whether the input of text property should be rendered with a monospace font or not. Only has an effect if the text type of the property is `OBS_TEXT_MULTILINE`. * * * void obs\_property\_text\_set\_info\_type([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p, enum obs\_text\_info\_type type)[](#c.obs_property_text_set_info_type "Link to this definition") Parameters: * **type** – Can be one of the following values: * **OBS\_TEXT\_INFO\_NORMAL** - To show a basic message * **OBS\_TEXT\_INFO\_WARNING** - To show a warning * **OBS\_TEXT\_INFO\_ERROR** - To show an error * * * void obs\_property\_text\_set\_info\_word\_wrap([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p, bool word\_wrap)[](#c.obs_property_text_set_info_word_wrap "Link to this definition") * * * void obs\_property\_list\_clear([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p)[](#c.obs_property_list_clear "Link to this definition") * * * size\_t obs\_property\_list\_add\_string([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p, const char \*name, const char \*val)[](#c.obs_property_list_add_string "Link to this definition") Adds a string to a string list. Parameters: * **name** – Localized name shown to user * **val** – The actual string value stored and will be returned by [`obs_data_get_string()`](reference-settings#c.obs_data_get_string "obs_data_get_string") Returns: The index of the list item. * * * size\_t obs\_property\_list\_add\_int([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p, const char \*name, long long val)[](#c.obs_property_list_add_int "Link to this definition") Adds an integer to a integer list. Parameters: * **name** – Localized name shown to user * **val** – The actual int value stored and will be returned by [`obs_data_get_int()`](reference-settings#c.obs_data_get_int "obs_data_get_int") Returns: The index of the list item. * * * size\_t obs\_property\_list\_add\_float([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p, const char \*name, double val)[](#c.obs_property_list_add_float "Link to this definition") Adds a floating point to a floating point list. Parameters: * **name** – Localized name shown to user * **val** – The actual float value stored and will be returned by [`obs_data_get_double()`](reference-settings#c.obs_data_get_double "obs_data_get_double") Returns: The index of the list item. * * * void obs\_property\_list\_insert\_string([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p, size\_t idx, const char \*name, const char \*val)[](#c.obs_property_list_insert_string "Link to this definition") Inserts a string in to a string list. Parameters: * **idx** – The index of the list item * **name** – Localized name shown to user * **val** – The actual string value stored and will be returned by [`obs_data_get_string()`](reference-settings#c.obs_data_get_string "obs_data_get_string") * * * void obs\_property\_list\_insert\_int([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p, size\_t idx, const char \*name, long long val)[](#c.obs_property_list_insert_int "Link to this definition") Inserts an integer in to an integer list. Parameters: * **idx** – The index of the list item * **name** – Localized name shown to user * **val** – The actual int value stored and will be returned by [`obs_data_get_int()`](reference-settings#c.obs_data_get_int "obs_data_get_int") * * * void obs\_property\_list\_insert\_float([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p, size\_t idx, const char \*name, double val)[](#c.obs_property_list_insert_float "Link to this definition") Inserts a floating point in to a floating point list. Parameters: * **idx** – The index of the list item. * **name** – Localized name shown to user * **val** – The actual float value stored and will be returned by [`obs_data_get_double()`](reference-settings#c.obs_data_get_double "obs_data_get_double") * * * void obs\_property\_list\_item\_disable([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p, size\_t idx, bool disabled)[](#c.obs_property_list_item_disable "Link to this definition") * * * void obs\_property\_list\_item\_remove([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p, size\_t idx)[](#c.obs_property_list_item_remove "Link to this definition") * * * size\_t obs\_property\_frame\_rate\_option\_add([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p, const char \*name, const char \*description)[](#c.obs_property_frame_rate_option_add "Link to this definition") * * * size\_t obs\_property\_frame\_rate\_fps\_range\_add([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p, struct media\_frames\_per\_second min, struct media\_frames\_per\_second max)[](#c.obs_property_frame_rate_fps_range_add "Link to this definition") * * * void obs\_property\_frame\_rate\_clear([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p)[](#c.obs_property_frame_rate_clear "Link to this definition") * * * void obs\_property\_frame\_rate\_options\_clear([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p)[](#c.obs_property_frame_rate_options_clear "Link to this definition") * * * void obs\_property\_frame\_rate\_fps\_ranges\_clear([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p)[](#c.obs_property_frame_rate_fps_ranges_clear "Link to this definition") * * * void obs\_property\_frame\_rate\_option\_insert([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p, size\_t idx, const char \*name, const char \*description)[](#c.obs_property_frame_rate_option_insert "Link to this definition") * * * void obs\_property\_frame\_rate\_fps\_range\_insert([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p, size\_t idx, struct media\_frames\_per\_second min, struct media\_frames\_per\_second max)[](#c.obs_property_frame_rate_fps_range_insert "Link to this definition") * * * void obs\_property\_button\_set\_type([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p, enum obs\_button\_type type)[](#c.obs_property_button_set_type "Link to this definition") Parameters: * **type** – Can be one of the following values: * **OBS\_BUTTON\_DEFAULT** - Standard button * **OBS\_BUTTON\_URL** - Button that opens a URL Returns: The property * * * void obs\_property\_button\_set\_url([obs\_property\_t](#c.obs_property_t "obs_property_t") \*p, char \*url)[](#c.obs_property_button_set_url "Link to this definition") --- # Platform/Utility API Reference (libobs/util) — OBS Studio 31.0.2 documentation * [](index) * Platform/Utility API Reference (libobs/util) * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/reference-libobs-util.rst) [Previous](reference-properties "Properties API Reference (obs_properties_t)") [Next](reference-libobs-util-base "Logging") * * * Platform/Utility API Reference (libobs/util)[](#platform-utility-api-reference-libobs-util "Link to this heading") ==================================================================================================================== * [Logging](reference-libobs-util-base) * [Logging Levels](reference-libobs-util-base#logging-levels) * [Logging Functions](reference-libobs-util-base#logging-functions) * [Memory Management](reference-libobs-util-bmem) * [Memory Functions](reference-libobs-util-bmem#memory-functions) * [Circular Buffers](reference-libobs-util-circlebuf) * [Circular Buffer Structure (struct circlebuf)](reference-libobs-util-circlebuf#circular-buffer-structure-struct-circlebuf) * [Circular Buffer Inline Functions](reference-libobs-util-circlebuf#circular-buffer-inline-functions) * [Config Files](reference-libobs-util-config-file) * [Config File Functions](reference-libobs-util-config-file#config-file-functions) * [Set/Get Functions](reference-libobs-util-config-file#set-get-functions) * [Default Value Functions](reference-libobs-util-config-file#default-value-functions) * [Dynamic Arrays](reference-libobs-util-darray) * [Dynamic Array Macros](reference-libobs-util-darray#dynamic-array-macros) * [Double-Ended Queue](reference-libobs-util-deque) * [Deque Structure (struct deque)](reference-libobs-util-deque#deque-structure-struct-deque) * [Deque Inline Functions](reference-libobs-util-deque#deque-inline-functions) * [Dynamic Strings And String Helpers](reference-libobs-util-dstr) * [Dynamic String Structure (struct dstr)](reference-libobs-util-dstr#dynamic-string-structure-struct-dstr) * [General String Helper Functions](reference-libobs-util-dstr#general-string-helper-functions) * [Dynamic String Functions](reference-libobs-util-dstr#dynamic-string-functions) * [Platform Helpers](reference-libobs-util-platform) * [File Functions](reference-libobs-util-platform#file-functions) * [String Conversion Functions](reference-libobs-util-platform#string-conversion-functions) * [Number/String Conversion Functions](reference-libobs-util-platform#number-string-conversion-functions) * [Dynamic Link Library Functions](reference-libobs-util-platform#dynamic-link-library-functions) * [CPU Usage Functions](reference-libobs-util-platform#cpu-usage-functions) * [Sleep/Time Functions](reference-libobs-util-platform#sleep-time-functions) * [Other Path/File Functions](reference-libobs-util-platform#other-path-file-functions) * [Sleep-Inhibition Functions](reference-libobs-util-platform#sleep-inhibition-functions) * [Other Functions](reference-libobs-util-platform#other-functions) * [Profiler](reference-libobs-util-profiler) * [Profiler Structures](reference-libobs-util-profiler#profiler-structures) * [Profiler Control Functions](reference-libobs-util-profiler#profiler-control-functions) * [Profiling Functions](reference-libobs-util-profiler#profiling-functions) * [Profiler Name Storage Functions](reference-libobs-util-profiler#profiler-name-storage-functions) * [Profiler Data Access Functions](reference-libobs-util-profiler#profiler-data-access-functions) * [Serializer](reference-libobs-util-serializers) * [Serializer Structure (struct serializer)](reference-libobs-util-serializers#serializer-structure-struct-serializer) * [Serializer Inline Functions](reference-libobs-util-serializers#serializer-inline-functions) * [Array Output Serializer](reference-libobs-util-serializers#array-output-serializer) * [Array Output Serializer Structure (struct array\_output\_data)](reference-libobs-util-serializers#array-output-serializer-structure-struct-array-output-data) * [Array Output Serializer Functions](reference-libobs-util-serializers#array-output-serializer-functions) * [File Input/Output Serializers](reference-libobs-util-serializers#file-input-output-serializers) * [File Input Serializer Functions](reference-libobs-util-serializers#file-input-serializer-functions) * [File Output Serializer Functions](reference-libobs-util-serializers#file-output-serializer-functions) * [Buffered File Output Serializer](reference-libobs-util-serializers#buffered-file-output-serializer) * [Buffered File Output Serializer Functions](reference-libobs-util-serializers#buffered-file-output-serializer-functions) * [Source Profiler](reference-libobs-util-source-profiler) * [Source Profiler Functions](reference-libobs-util-source-profiler#source-profiler-functions) * [Text Lookup Interface](reference-libobs-util-text-lookup) * [Text Lookup Functions](reference-libobs-util-text-lookup#text-lookup-functions) * [Threading](reference-libobs-util-threading) * [Threading Types](reference-libobs-util-threading#threading-types) * [General Thread Functions](reference-libobs-util-threading#general-thread-functions) * [Event Functions](reference-libobs-util-threading#event-functions) * [Semaphore Functions](reference-libobs-util-threading#semaphore-functions) * [Atomic Inline Functions](reference-libobs-util-threading#atomic-inline-functions) --- # Encoder API Reference (obs_encoder_t) — OBS Studio 31.0.2 documentation * [](index) * [Core API Object Reference](reference-core-objects) * Encoder API Reference (obs\_encoder\_t) * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/reference-encoders.rst) [Previous](reference-outputs "Output API Reference (obs_output_t)") [Next](reference-services "Service API Reference (obs_service_t)") * * * Encoder API Reference (obs\_encoder\_t)[](#encoder-api-reference-obs-encoder-t "Link to this heading") ======================================================================================================== 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](https://github.com/obsproject/obs-studio/blob/master/libobs/obs-encoder.h) file is the dedicated header for implementing encoders type obs\_encoder\_t[](#c.obs_encoder_t "Link to this definition") A reference-counted encoder object. type obs\_weak\_encoder\_t[](#c.obs_weak_encoder_t "Link to this definition") A weak reference to an encoder object. #include Encoder Definition Structure (obs\_encoder\_info)[](#encoder-definition-structure-obs-encoder-info "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------- struct obs\_encoder\_info[](#c.obs_encoder_info "Link to this definition") Encoder definition structure. const char \*[obs\_encoder\_info](#c.obs_encoder_info "obs_encoder_info") .id[](#c.obs_encoder_info.id "Link to this definition") Unique string identifier for the encoder (required). enum obs\_encoder\_type [obs\_encoder\_info](#c.obs_encoder_info "obs_encoder_info") .type[](#c.obs_encoder_info.type "Link to this definition") Type of encoder. * **OBS\_ENCODER\_VIDEO** - Video encoder * **OBS\_ENCODER\_AUDIO** - Audio encoder const char \*[obs\_encoder\_info](#c.obs_encoder_info "obs_encoder_info") .codec[](#c.obs_encoder_info.codec "Link to this definition") The codec, in string form. For example, “h264” for an H.264 encoder. const char \*(\*[obs\_encoder\_info](#c.obs_encoder_info "obs_encoder_info") .get\_name)(void \*type\_data)[](#c.obs_encoder_info.get_name "Link to this definition") 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 void \*(\*[obs\_encoder\_info](#c.obs_encoder_info "obs_encoder_info") .create)([obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*settings, [obs\_encoder\_t](#c.obs_encoder_t "obs_encoder_t") \*encoder)[](#c.obs_encoder_info.create "Link to this definition") 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 void (\*[obs\_encoder\_info](#c.obs_encoder_info "obs_encoder_info") .destroy)(void \*data)[](#c.obs_encoder_info.destroy "Link to this definition") Destroys the implementation data for the encoder. bool (\*encode)(void \*data, struct [encoder\_frame](#c.encoder_frame "encoder_frame") \*frame, struct [encoder\_packet](#c.encoder_packet "encoder_packet") \*packet, bool \*received\_packet)[](#c.encode "Link to this definition") 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 size\_t (\*get\_frame\_size)(void \*data)[](#c.get_frame_size "Link to this definition") Return: An audio encoder’s frame size. For example, for AAC this number would be 1024 void (\*[obs\_encoder\_info](#c.obs_encoder_info "obs_encoder_info") .get\_defaults)([obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*settings)[](#c.obs_encoder_info.get_defaults "Link to this definition") void (\*[obs\_encoder\_info](#c.obs_encoder_info "obs_encoder_info") .get\_defaults2)([obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*settings, void \*type\_data)[](#c.obs_encoder_info.get_defaults2 "Link to this definition") 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 [obs\_properties\_t](reference-properties#c.obs_properties_t "obs_properties_t") \*(\*[obs\_encoder\_info](#c.obs_encoder_info "obs_encoder_info") .get\_properties)(void \*data)[](#c.obs_encoder_info.get_properties "Link to this definition") [obs\_properties\_t](reference-properties#c.obs_properties_t "obs_properties_t") \*(\*[obs\_encoder\_info](#c.obs_encoder_info "obs_encoder_info") .get\_properties2)(void \*data, void \*type\_data)[](#c.obs_encoder_info.get_properties2 "Link to this definition") Gets the property information of this encoder. Param data: The implementation data associated with this encoder. This value can be null (e.g., when [`obs_get_encoder_properties()`](#c.obs_get_encoder_properties "obs_get_encoder_properties") is called on the encoder type), make sure to handle this gracefully. (Optional) Return: The properties of the encoder void (\*[obs\_encoder\_info](#c.obs_encoder_info "obs_encoder_info") .update)(void \*data, [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*settings)[](#c.obs_encoder_info.update "Link to this definition") Updates the settings for this encoder. (Optional) Param settings: New settings for this encoder bool (\*[obs\_encoder\_info](#c.obs_encoder_info "obs_encoder_info") .get\_extra\_data)(void \*data, uint8\_t \*\*extra\_data, size\_t \*size)[](#c.obs_encoder_info.get_extra_data "Link to this definition") 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 bool (\*[obs\_encoder\_info](#c.obs_encoder_info "obs_encoder_info") .get\_sei\_data)(void \*data, uint8\_t \*\*sei\_data, size\_t \*size)[](#c.obs_encoder_info.get_sei_data "Link to this definition") 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 void (\*[obs\_encoder\_info](#c.obs_encoder_info "obs_encoder_info") .get\_audio\_info)(void \*data, struct [audio\_convert\_info](reference-libobs-media-io#c.audio_convert_info "audio_convert_info") \*info)[](#c.obs_encoder_info.get_audio_info "Link to this definition") 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 void (\*[obs\_encoder\_info](#c.obs_encoder_info "obs_encoder_info") .get\_video\_info)(void \*data, struct video\_scale\_info \*info)[](#c.obs_encoder_info.get_video_info "Link to this definition") 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 void \*[obs\_encoder\_info](#c.obs_encoder_info "obs_encoder_info") .type\_data[](#c.obs_encoder_info.type_data "Link to this definition") void (\*[obs\_encoder\_info](#c.obs_encoder_info "obs_encoder_info") .free\_type\_data)(void \*type\_data)[](#c.obs_encoder_info.free_type_data "Link to this definition") 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. uint32\_t [obs\_encoder\_info](#c.obs_encoder_info "obs_encoder_info") .caps[](#c.obs_encoder_info.caps "Link to this definition") Can be 0 or a bitwise OR combination of one or more of the following values: * **OBS\_ENCODER\_CAP\_DEPRECATED** - Encoder is deprecated * **OBS\_ENCODER\_CAP\_ROI** - Encoder supports region of interest feature * **OBS\_ENCODER\_CAP\_SCALING** - Encoder implements its own scaling logic, desiring to receive unscaled frames Encoder Packet Structure (encoder\_packet)[](#encoder-packet-structure-encoder-packet "Link to this heading") --------------------------------------------------------------------------------------------------------------- struct encoder\_packet[](#c.encoder_packet "Link to this definition") Encoder packet structure. uint8\_t \*[encoder\_packet](#c.encoder_packet "encoder_packet") .data[](#c.encoder_packet.data "Link to this definition") Packet data. size\_t [encoder\_packet](#c.encoder_packet "encoder_packet") .size[](#c.encoder_packet.size "Link to this definition") Packet size. int64\_t [encoder\_packet](#c.encoder_packet "encoder_packet") .pts[](#c.encoder_packet.pts "Link to this definition") int64\_t [encoder\_packet](#c.encoder_packet "encoder_packet") .dts[](#c.encoder_packet.dts "Link to this definition") Packet presentation and decode timestamps. int32\_t [encoder\_packet](#c.encoder_packet "encoder_packet") .timebase\_num[](#c.encoder_packet.timebase_num "Link to this definition") int32\_t [encoder\_packet](#c.encoder_packet "encoder_packet") .timebase\_den[](#c.encoder_packet.timebase_den "Link to this definition") Packet time base. enum obs\_encoder\_type [encoder\_packet](#c.encoder_packet "encoder_packet") .type[](#c.encoder_packet.type "Link to this definition") Can be one of the following values: * **OBS\_ENCODER\_VIDEO** - Video data * **OBS\_ENCODER\_AUDIO** - Audio data bool [encoder\_packet](#c.encoder_packet "encoder_packet") .keyframe[](#c.encoder_packet.keyframe "Link to this definition") Packet is a keyframe. int64\_t [encoder\_packet](#c.encoder_packet "encoder_packet") .dts\_usec[](#c.encoder_packet.dts_usec "Link to this definition") The DTS in microseconds. (This should not be set by the encoder implementation) int64\_t [encoder\_packet](#c.encoder_packet "encoder_packet") .sys\_dts\_usec[](#c.encoder_packet.sys_dts_usec "Link to this definition") The system time of this packet in microseconds. (This should not be set by the encoder implementation) int [encoder\_packet](#c.encoder_packet "encoder_packet") .priority[](#c.encoder_packet.priority "Link to this definition") Packet priority. This is no longer used. (This should not be set by the encoder implementation) int [encoder\_packet](#c.encoder_packet "encoder_packet") .drop\_priority[](#c.encoder_packet.drop_priority "Link to this definition") 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) size\_t [encoder\_packet](#c.encoder_packet "encoder_packet") .track\_idx[](#c.encoder_packet.track_idx "Link to this definition") Audio track index. (This should not be set by the encoder implementation) [obs\_encoder\_t](#c.obs_encoder_t "obs_encoder_t") \*[encoder\_packet](#c.encoder_packet "encoder_packet") .encoder[](#c.encoder_packet.encoder "Link to this definition") Encoder object associated with this packet. (This should not be set by the encoder implementation) Raw Frame Data Structure (encoder\_frame)[](#raw-frame-data-structure-encoder-frame "Link to this heading") ------------------------------------------------------------------------------------------------------------- struct encoder\_frame[](#c.encoder_frame "Link to this definition") Raw frame data structure. uint8\_t \*[encoder\_frame](#c.encoder_frame "encoder_frame") .data\[MAX\_AV\_PLANES\][](#c.encoder_frame.data "Link to this definition") Raw video/audio data. uint32\_t [encoder\_frame](#c.encoder_frame "encoder_frame") .linesize\[MAX\_AV\_PLANES\][](#c.encoder_frame.linesize "Link to this definition") Line size of each plane. uint32\_t [encoder\_frame](#c.encoder_frame "encoder_frame") .frames[](#c.encoder_frame.frames "Link to this definition") Number of audio frames (if audio). int64\_t [encoder\_frame](#c.encoder_frame "encoder_frame") .pts[](#c.encoder_frame.pts "Link to this definition") Presentation timestamp. Encoder Region of Interest Structure (obs\_encoder\_roi)[](#encoder-region-of-interest-structure-obs-encoder-roi "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------ struct obs\_encoder\_roi[](#c.obs_encoder_roi "Link to this definition") Encoder region of interest structure. Added in version 30.1. uint32\_t top[](#c.top "Link to this definition") uint32\_t bottom[](#c.bottom "Link to this definition") uint32\_t left[](#c.left "Link to this definition") uint32\_t right[](#c.right "Link to this definition") The rectangle edges of the region are specified as number of pixels from the input video’s top and left edges (i.e. row/column 0). float priority[](#c.priority "Link to this definition") Priority is specified as a float value between _\-1.0f_ and _1_. These are converted to encoder-specific values by the encoder. Values above 0 tell the encoder to increase quality for that region, values below tell it to worsen it. Not all encoders support negative values and they may be ignored. General Encoder Functions[](#general-encoder-functions "Link to this heading") -------------------------------------------------------------------------------- void obs\_register\_encoder(struct [obs\_encoder\_info](#c.obs_encoder_info "obs_encoder_info") \*info)[](#c.obs_register_encoder "Link to this definition") Registers an encoder type. Typically used in [`obs_module_load()`](reference-modules#c.obs_module_load "obs_module_load") or in the program’s initialization phase. * * * const char \*obs\_encoder\_get\_display\_name(const char \*id)[](#c.obs_encoder_get_display_name "Link to this definition") Calls the [`obs_encoder_info.get_name`](#c.obs_encoder_info.get_name "obs_encoder_info.get_name") callback to get the translated display name of an encoder type. Parameters: * **id** – The encoder type string identifier Returns: The translated display name of an encoder type * * * [obs\_encoder\_t](#c.obs_encoder_t "obs_encoder_t") \*obs\_video\_encoder\_create(const char \*id, const char \*name, [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*settings, [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*hotkey\_data)[](#c.obs_video_encoder_create "Link to this definition") 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. Parameters: * **id** – The encoder type string identifier * **name** – The desired name of the encoder. If this is not unique, it will be made to be unique * **settings** – The settings for the encoder, or _NULL_ if none * **hotkey\_data** – Saved hotkey data for the encoder, or _NULL_ if none Returns: A reference to the newly created encoder, or _NULL_ if failed * * * [obs\_encoder\_t](#c.obs_encoder_t "obs_encoder_t") \*obs\_audio\_encoder\_create(const char \*id, const char \*name, [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*settings, size\_t mixer\_idx, [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*hotkey\_data)[](#c.obs_audio_encoder_create "Link to this definition") Creates an audio encoder with the specified settings. The “encoder” context is used for encoding video/audio data. Use [`obs_encoder_release()`](#c.obs_encoder_release "obs_encoder_release") to release it. Parameters: * **id** – The encoder type string identifier * **name** – The desired name of the encoder. If this is not unique, it will be made to be unique * **settings** – The settings for the encoder, or _NULL_ if none * **mixer\_idx** – The audio mixer index this audio encoder will capture audio from * **hotkey\_data** – Saved hotkey data for the encoder, or _NULL_ if none Returns: A reference to the newly created encoder, or _NULL_ if failed * * * [obs\_encoder\_t](#c.obs_encoder_t "obs_encoder_t") \*obs\_encoder\_get\_ref([obs\_encoder\_t](#c.obs_encoder_t "obs_encoder_t") \*encoder)[](#c.obs_encoder_get_ref "Link to this definition") Returns an incremented reference if still valid, otherwise returns _NULL_. Release with [`obs_encoder_release()`](#c.obs_encoder_release "obs_encoder_release") . * * * void obs\_encoder\_release([obs\_encoder\_t](#c.obs_encoder_t "obs_encoder_t") \*encoder)[](#c.obs_encoder_release "Link to this definition") Releases a reference to an encoder. When the last reference is released, the encoder is destroyed. * * * [obs\_weak\_encoder\_t](#c.obs_weak_encoder_t "obs_weak_encoder_t") \*obs\_encoder\_get\_weak\_encoder([obs\_encoder\_t](#c.obs_encoder_t "obs_encoder_t") \*encoder)[](#c.obs_encoder_get_weak_encoder "Link to this definition") [obs\_encoder\_t](#c.obs_encoder_t "obs_encoder_t") \*obs\_weak\_encoder\_get\_encoder([obs\_weak\_encoder\_t](#c.obs_weak_encoder_t "obs_weak_encoder_t") \*weak)[](#c.obs_weak_encoder_get_encoder "Link to this definition") 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_. * * * void obs\_weak\_encoder\_addref([obs\_weak\_encoder\_t](#c.obs_weak_encoder_t "obs_weak_encoder_t") \*weak)[](#c.obs_weak_encoder_addref "Link to this definition") void obs\_weak\_encoder\_release([obs\_weak\_encoder\_t](#c.obs_weak_encoder_t "obs_weak_encoder_t") \*weak)[](#c.obs_weak_encoder_release "Link to this definition") Adds/releases a weak reference to an encoder. * * * void obs\_encoder\_set\_name([obs\_encoder\_t](#c.obs_encoder_t "obs_encoder_t") \*encoder, const char \*name)[](#c.obs_encoder_set_name "Link to this definition") 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. * * * const char \*obs\_encoder\_get\_name(const [obs\_encoder\_t](#c.obs_encoder_t "obs_encoder_t") \*encoder)[](#c.obs_encoder_get_name "Link to this definition") Returns: The name of the encoder * * * const char \*obs\_encoder\_get\_codec(const [obs\_encoder\_t](#c.obs_encoder_t "obs_encoder_t") \*encoder)[](#c.obs_encoder_get_codec "Link to this definition") const char \*obs\_get\_encoder\_codec(const char \*id)[](#c.obs_get_encoder_codec "Link to this definition") Returns: The codec identifier of the encoder * * * enum obs\_encoder\_type obs\_encoder\_get\_type(const [obs\_encoder\_t](#c.obs_encoder_t "obs_encoder_t") \*encoder)[](#c.obs_encoder_get_type "Link to this definition") enum obs\_encoder\_type obs\_get\_encoder\_type(const char \*id)[](#c.obs_get_encoder_type "Link to this definition") Returns: The encoder type: OBS\_ENCODER\_VIDEO or OBS\_ENCODER\_AUDIO * * * void obs\_encoder\_set\_scaled\_size([obs\_encoder\_t](#c.obs_encoder_t "obs_encoder_t") \*encoder, uint32\_t width, uint32\_t height)[](#c.obs_encoder_set_scaled_size "Link to this definition") 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. * * * bool obs\_encoder\_scaling\_enabled(const [obs\_encoder\_t](#c.obs_encoder_t "obs_encoder_t") \*encoder)[](#c.obs_encoder_scaling_enabled "Link to this definition") Returns: _true_ if pre-encode (CPU) scaling enabled, _false_ otherwise. * * * uint32\_t obs\_encoder\_get\_width(const [obs\_encoder\_t](#c.obs_encoder_t "obs_encoder_t") \*encoder)[](#c.obs_encoder_get_width "Link to this definition") uint32\_t obs\_encoder\_get\_height(const [obs\_encoder\_t](#c.obs_encoder_t "obs_encoder_t") \*encoder)[](#c.obs_encoder_get_height "Link to this definition") Returns: The width/height of a video encoder’s encoded image * * * uint32\_t obs\_encoder\_get\_sample\_rate(const [obs\_encoder\_t](#c.obs_encoder_t "obs_encoder_t") \*encoder)[](#c.obs_encoder_get_sample_rate "Link to this definition") Returns: The sample rate of an audio encoder’s audio data * * * size\_t obs\_encoder\_get\_frame\_size(const [obs\_encoder\_t](#c.obs_encoder_t "obs_encoder_t") \*encoder)[](#c.obs_encoder_get_frame_size "Link to this definition") Returns: The frame size of the audio packet * * * size\_t obs\_encoder\_get\_mixer\_index(const [obs\_encoder\_t](#c.obs_encoder_t "obs_encoder_t") \*encoder)[](#c.obs_encoder_get_mixer_index "Link to this definition") Returns: The mixer index for the audio track which is encoded by the encoder * * * void obs\_encoder\_set\_preferred\_video\_format([obs\_encoder\_t](#c.obs_encoder_t "obs_encoder_t") \*encoder, enum [video\_format](reference-libobs-media-io#c.video_format "video_format") format)[](#c.obs_encoder_set_preferred_video_format "Link to this definition") enum [video\_format](reference-libobs-media-io#c.video_format "video_format") obs\_encoder\_get\_preferred\_video\_format(const [obs\_encoder\_t](#c.obs_encoder_t "obs_encoder_t") \*encoder)[](#c.obs_encoder_get_preferred_video_format "Link to this definition") 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. * * * [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*obs\_encoder\_defaults(const char \*id)[](#c.obs_encoder_defaults "Link to this definition") [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*obs\_encoder\_get\_defaults(const [obs\_encoder\_t](#c.obs_encoder_t "obs_encoder_t") \*encoder)[](#c.obs_encoder_get_defaults "Link to this definition") Returns: An incremented reference to the encoder’s default settings. Release with [`obs_data_release()`](reference-settings#c.obs_data_release "obs_data_release") . * * * [obs\_properties\_t](reference-properties#c.obs_properties_t "obs_properties_t") \*obs\_encoder\_properties(const [obs\_encoder\_t](#c.obs_encoder_t "obs_encoder_t") \*encoder)[](#c.obs_encoder_properties "Link to this definition") [obs\_properties\_t](reference-properties#c.obs_properties_t "obs_properties_t") \*obs\_get\_encoder\_properties(const char \*id)[](#c.obs_get_encoder_properties "Link to this definition") 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. Returns: The properties list for a specific existing encoder. Free with [`obs_properties_destroy()`](reference-properties#c.obs_properties_destroy "obs_properties_destroy") * * * void obs\_encoder\_update([obs\_encoder\_t](#c.obs_encoder_t "obs_encoder_t") \*encoder, [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*settings)[](#c.obs_encoder_update "Link to this definition") Updates the settings for this encoder context. * * * [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*obs\_encoder\_get\_settings(const [obs\_encoder\_t](#c.obs_encoder_t "obs_encoder_t") \*encoder)[](#c.obs_encoder_get_settings "Link to this definition") Returns: An incremented reference to the encoder’s settings. Release with [`obs_data_release()`](reference-settings#c.obs_data_release "obs_data_release") . * * * [signal\_handler\_t](reference-libobs-callback#c.signal_handler_t "signal_handler_t") \*obs\_encoder\_get\_signal\_handler(const [obs\_encoder\_t](#c.obs_encoder_t "obs_encoder_t") \*encoder)[](#c.obs_encoder_get_signal_handler "Link to this definition") Returns: The signal handler of the encoder. Should not be manually freed, as its lifecycle is managed by libobs. * * * [proc\_handler\_t](reference-libobs-callback#c.proc_handler_t "proc_handler_t") \*obs\_encoder\_get\_proc\_handler(const [obs\_encoder\_t](#c.obs_encoder_t "obs_encoder_t") \*encoder)[](#c.obs_encoder_get_proc_handler "Link to this definition") Returns: The procedure handler of the encoder. Should not be manually freed, as its lifecycle is managed by libobs. * * * bool obs\_encoder\_get\_extra\_data(const [obs\_encoder\_t](#c.obs_encoder_t "obs_encoder_t") \*encoder, uint8\_t \*\*extra\_data, size\_t \*size)[](#c.obs_encoder_get_extra_data "Link to this definition") Gets extra data (headers) associated with this encoder. Returns: _true_ if successful, _false_ if no extra data associated with this encoder * * * void obs\_encoder\_set\_video([obs\_encoder\_t](#c.obs_encoder_t "obs_encoder_t") \*encoder, [video\_t](reference-libobs-media-io#c.video_t "video_t") \*video)[](#c.obs_encoder_set_video "Link to this definition") void obs\_encoder\_set\_audio([obs\_encoder\_t](#c.obs_encoder_t "obs_encoder_t") \*encoder, [audio\_t](reference-libobs-media-io#c.audio_t "audio_t") \*audio)[](#c.obs_encoder_set_audio "Link to this definition") Sets the video/audio handler to use with this video/audio encoder. This is used to capture the raw video/audio data. * * * [video\_t](reference-libobs-media-io#c.video_t "video_t") \*obs\_encoder\_video(const [obs\_encoder\_t](#c.obs_encoder_t "obs_encoder_t") \*encoder)[](#c.obs_encoder_video "Link to this definition") [video\_t](reference-libobs-media-io#c.video_t "video_t") \*obs\_encoder\_parent\_video(const [obs\_encoder\_t](#c.obs_encoder_t "obs_encoder_t") \*encoder)[](#c.obs_encoder_parent_video "Link to this definition") [audio\_t](reference-libobs-media-io#c.audio_t "audio_t") \*obs\_encoder\_audio(const [obs\_encoder\_t](#c.obs_encoder_t "obs_encoder_t") \*encoder)[](#c.obs_encoder_audio "Link to this definition") Returns: The video/audio handler associated with this encoder, or _NULL_ if none or not a matching encoder type. _parent\_video_ returns the “original” video handler associated with this encoder, regardless of whether an FPS divisor is set. * * * bool obs\_encoder\_active(const [obs\_encoder\_t](#c.obs_encoder_t "obs_encoder_t") \*encoder)[](#c.obs_encoder_active "Link to this definition") Returns: _true_ if the encoder is active, _false_ otherwise * * * bool obs\_encoder\_add\_roi([obs\_encoder\_t](#c.obs_encoder_t "obs_encoder_t") \*encoder, const struct [obs\_encoder\_roi](#c.obs_encoder_roi "obs_encoder_roi") \*roi)[](#c.obs_encoder_add_roi "Link to this definition") > Adds a new region of interest to the encoder if ROI feature is supported. Returns: _true_ if adding succeeded, _false_ otherwise. Added in version 30.1. * * * bool obs\_encoder\_has\_roi([obs\_encoder\_t](#c.obs_encoder_t "obs_encoder_t") \*encoder)[](#c.obs_encoder_has_roi "Link to this definition") Returns: _true_ if encoder has ROI regions set, _false_ otherwise. Added in version 30.1. * * * void obs\_encoder\_clear\_roi([obs\_encoder\_t](#c.obs_encoder_t "obs_encoder_t") \*encoder)[](#c.obs_encoder_clear_roi "Link to this definition") > Clear region of interest list, if any. Added in version 30.1. * * * void obs\_encoder\_enum\_roi([obs\_encoder\_t](#c.obs_encoder_t "obs_encoder_t") \*encoder, void (\*enum\_proc)(void\*, struct [obs\_encoder\_roi](#c.obs_encoder_roi "obs_encoder_roi") \*), void \*param)[](#c.obs_encoder_enum_roi "Link to this definition") > Enumerate currently configured ROIs by invoking callback for each entry, in reverse order of addition (i.e. most recent to oldest). > > **Note:** If the encoder has scaling enabled the struct passed to the callback will be scaled accordingly. Added in version 30.1. * * * uint32\_t obs\_encoder\_get\_roi\_increment(const [obs\_encoder\_t](#c.obs_encoder_t "obs_encoder_t") \*encoder)[](#c.obs_encoder_get_roi_increment "Link to this definition") Encoders shall refresh their ROI configuration if the increment value changes. Returns: Increment/revision of ROI list Added in version 30.1. * * * Functions used by encoders[](#functions-used-by-encoders "Link to this heading") ---------------------------------------------------------------------------------- void obs\_encoder\_packet\_ref(struct [encoder\_packet](#c.encoder_packet "encoder_packet") \*dst, struct [encoder\_packet](#c.encoder_packet "encoder_packet") \*src)[](#c.obs_encoder_packet_ref "Link to this definition") void obs\_encoder\_packet\_release(struct [encoder\_packet](#c.encoder_packet "encoder_packet") \*packet)[](#c.obs_encoder_packet_release "Link to this definition") Adds or releases a reference to an encoder packet. --- # Circular Buffers — OBS Studio 31.0.2 documentation * [](index) * [Platform/Utility API Reference (libobs/util)](reference-libobs-util) * Circular Buffers * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/reference-libobs-util-circlebuf.rst) [Previous](reference-libobs-util-bmem "Memory Management") [Next](reference-libobs-util-config-file "Config Files") * * * Circular Buffers[](#circular-buffers "Link to this heading") ============================================================== A circular buffer that will automatically increase in size as necessary as data is pushed to the front or back. Deprecated since version 30.1: Replaced by [Double-Ended Queue](reference-libobs-util-deque) #include Circular Buffer Structure (struct circlebuf)[](#circular-buffer-structure-struct-circlebuf "Link to this heading") -------------------------------------------------------------------------------------------------------------------- struct circlebuf[](#c.circlebuf "Link to this definition") void \*[circlebuf](#c.circlebuf "circlebuf") .data[](#c.circlebuf.data "Link to this definition") size\_t [circlebuf](#c.circlebuf "circlebuf") .size[](#c.circlebuf.size "Link to this definition") size\_t [circlebuf](#c.circlebuf "circlebuf") .start\_pos[](#c.circlebuf.start_pos "Link to this definition") size\_t [circlebuf](#c.circlebuf "circlebuf") .end\_pos[](#c.circlebuf.end_pos "Link to this definition") size\_t [circlebuf](#c.circlebuf "circlebuf") .capacity[](#c.circlebuf.capacity "Link to this definition") Circular Buffer Inline Functions[](#circular-buffer-inline-functions "Link to this heading") ---------------------------------------------------------------------------------------------- void circlebuf\_init(struct [circlebuf](#c.circlebuf "circlebuf") \*cb)[](#c.circlebuf_init "Link to this definition") Initializes a circular buffer (just zeroes out the entire structure). Parameters: * **cb** – The circular buffer * * * void circlebuf\_free(struct [circlebuf](#c.circlebuf "circlebuf") \*cb)[](#c.circlebuf_free "Link to this definition") Frees a circular buffer. Parameters: * **cb** – The circular buffer * * * void circlebuf\_reserve(struct [circlebuf](#c.circlebuf "circlebuf") \*cb, size\_t capacity)[](#c.circlebuf_reserve "Link to this definition") Reserves a specific amount of buffer space to ensure minimum upsizing. Parameters: * **cb** – The circular buffer * **capacity** – The new capacity, in bytes * * * void circlebuf\_upsize(struct [circlebuf](#c.circlebuf "circlebuf") \*cb, size\_t size)[](#c.circlebuf_upsize "Link to this definition") Sets the current active (not just reserved) size. Any new data is zeroed. Parameters: * **cb** – The circular buffer * **size** – The new size, in bytes * * * void circlebuf\_place(struct [circlebuf](#c.circlebuf "circlebuf") \*cb, size\_t position, const void \*data, size\_t size)[](#c.circlebuf_place "Link to this definition") Places data at a specific positional index (relative to the starting point) within the circular buffer. Parameters: * **cb** – The circular buffer * **position** – Positional index relative to starting point * **data** – Data to insert * **size** – Size of data to insert * * * void circlebuf\_push\_back(struct [circlebuf](#c.circlebuf "circlebuf") \*cb, const void \*data, size\_t size)[](#c.circlebuf_push_back "Link to this definition") Pushes data to the end of the circular buffer. Parameters: * **cb** – The circular buffer * **data** – Data * **size** – Size of data * * * void circlebuf\_push\_front(struct [circlebuf](#c.circlebuf "circlebuf") \*cb, const void \*data, size\_t size)[](#c.circlebuf_push_front "Link to this definition") Pushes data to the front of the circular buffer. Parameters: * **cb** – The circular buffer * **data** – Data * **size** – Size of data * * * void circlebuf\_push\_back\_zero(struct [circlebuf](#c.circlebuf "circlebuf") \*cb, size\_t size)[](#c.circlebuf_push_back_zero "Link to this definition") Pushes zeroed data to the end of the circular buffer. Parameters: * **cb** – The circular buffer * **size** – Size * * * void circlebuf\_push\_front\_zero(struct [circlebuf](#c.circlebuf "circlebuf") \*cb, size\_t size)[](#c.circlebuf_push_front_zero "Link to this definition") Pushes zeroed data to the front of the circular buffer. Parameters: * **cb** – The circular buffer * **size** – Size * * * void circlebuf\_peek\_front(struct [circlebuf](#c.circlebuf "circlebuf") \*cb, void \*data, size\_t size)[](#c.circlebuf_peek_front "Link to this definition") Peeks data at the front of the circular buffer. Parameters: * **cb** – The circular buffer * **data** – Buffer to store data in * **size** – Size of data to retrieve * * * void circlebuf\_peek\_back(struct [circlebuf](#c.circlebuf "circlebuf") \*cb, void \*data, size\_t size)[](#c.circlebuf_peek_back "Link to this definition") Peeks data at the back of the circular buffer. Parameters: * **cb** – The circular buffer * **data** – Buffer to store data in * **size** – Size of data to retrieve * * * void circlebuf\_pop\_front(struct [circlebuf](#c.circlebuf "circlebuf") \*cb, void \*data, size\_t size)[](#c.circlebuf_pop_front "Link to this definition") Pops data from the front of the circular buffer. Parameters: * **cb** – The circular buffer * **data** – Buffer to store data in, or _NULL_ * **size** – Size of data to retrieve * * * void circlebuf\_pop\_back(struct [circlebuf](#c.circlebuf "circlebuf") \*cb, void \*data, size\_t size)[](#c.circlebuf_pop_back "Link to this definition") Pops data from the back of the circular buffer. Parameters: * **cb** – The circular buffer * **data** – Buffer to store data in, or _NULL_ * **size** – Size of data to retrieve * * * void \*circlebuf\_data(struct [circlebuf](#c.circlebuf "circlebuf") \*cb, size\_t idx)[](#c.circlebuf_data "Link to this definition") Gets a direct pointer to data at a specific positional index within the circular buffer, relative to the starting point. Parameters: * **cb** – The circular buffer * **idx** – Byte index relative to the starting point --- # Dynamic Arrays — OBS Studio 31.0.2 documentation * [](index) * [Platform/Utility API Reference (libobs/util)](reference-libobs-util) * Dynamic Arrays * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/reference-libobs-util-darray.rst) [Previous](reference-libobs-util-config-file "Config Files") [Next](reference-libobs-util-deque "Double-Ended Queue") * * * Dynamic Arrays[](#dynamic-arrays "Link to this heading") ========================================================== Dynamically resizing arrays (a C equivalent to std::vector). #include struct darray[](#c.darray "Link to this definition") The base dynamic array structure. DARRAY(type)[](#c.DARRAY "Link to this definition") Macro for a dynamic array based upon an actual type. Use this with da\_\* macros. void \*[darray](#c.darray "darray") .array[](#c.darray.array "Link to this definition") The array pointer. size\_t [darray](#c.darray "darray") .num[](#c.darray.num "Link to this definition") The number of items within the array. size\_t [darray](#c.darray "darray") .capacity[](#c.darray.capacity "Link to this definition") The capacity of the array. Dynamic Array Macros[](#dynamic-array-macros "Link to this heading") ---------------------------------------------------------------------- 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: /\* 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); To pass dynamic arrays to functions as parameters, create a typedef with the [`DARRAY`](#c.DARRAY "DARRAY") macro and type so you can pass the dynamic array with a reference (&) operator. An alternative is to define a struct that will contain the dynamic array, and that struct will be passed to the functions, instead of the dynamic array directly. An example with the typedef method: typedef DARRAY(int) int\_array\_t; void generate\_integers(int\_array\_t \*integers, int start, int end) { for (int i \= start; i < end; i++) da\_push\_back(\*integers, &i); } \[...\] int\_array\_t array\_of\_integers; da\_init(array\_of\_integers); generate\_integers(&array\_of\_integers, 0, 10); /\* free when complete \*/ da\_free(array\_of\_integers); **IMPORTANT NOTE:** While it is also possible to accept the internal [`darray`](#c.darray "darray") struct as a function parameter (via the `da` member variable of dynamic arrays) and redefine a variable with [`DARRAY`](#c.DARRAY "DARRAY") inside the function, doing so is not safe and not recommended. One potential issue with it is having a type declaration in the function that is different than the type of the actual dynamic array that will be passed to the function, which will cause memory access issues that will not be caught by the compiler. As mentioned above, the recommended way is to create a typedef or a container struct, which will be safer in usage. void da\_init(da)[](#c.da_init "Link to this definition") Initializes a dynamic array. Parameters: * **da** – The dynamic array * * * void da\_free(da)[](#c.da_free "Link to this definition") Frees a dynamic array. Parameters: * **da** – The dynamic array * * * size\_t da\_alloc\_size(v)[](#c.da_alloc_size "Link to this definition") Gets a size of allocated array in bytes. Parameters: * **da** – The dynamic array Returns: The allocated size of the dynamic array. * * * void \*da\_end(da)[](#c.da_end "Link to this definition") Gets a pointer to the last value. Parameters: * **da** – The dynamic array Returns: The last value of a dynamic array, or _NULL_ if empty. * * * void da\_reserve(da, size\_t capacity)[](#c.da_reserve "Link to this definition") Reserves a specific amount of buffer space for the dynamic array. Parameters: * **da** – The dynamic array * **capacity** – New capacity of the dynamic array * * * void da\_resize(da, size\_t new\_size)[](#c.da_resize "Link to this definition") Resizes the dynamic array with zeroed values. Parameters: * **da** – The dynamic array * **size** – New size of the dynamic array * * * void da\_copy(da\_dst, da\_src)[](#c.da_copy "Link to this definition") Makes a copy of a dynamic array. Parameters: * **da\_dst** – The dynamic array to copy to * **da\_src** – The dynamic array to copy from * * * void da\_copy\_array(da, const void \*src\_array, size\_t size)[](#c.da_copy_array "Link to this definition") Makes a copy of an array pointer. Parameters: * **da** – The dynamic array * **src\_array** – The array pointer to make a copy from * **size** – New size of the dynamic array * * * void da\_move(da\_dst, da\_src)[](#c.da_move "Link to this definition") 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. Parameters: * **da\_dst** – Destination variable * **da\_src** – Source variable * * * size\_t da\_find(da, const void \*item\_data, size\_t starting\_idx)[](#c.da_find "Link to this definition") Finds a value based upon its data. If the value cannot be found, the return value will be DARRAY\_INVALID (-1). Parameters: * **da** – The dynamic array * **item\_data** – The item data to find * **starting\_idx** – The index to start from or 0 to search the entire array * * * size\_t da\_push\_back(da, const void \*data)[](#c.da_push_back "Link to this definition") Pushes data to the back of the array. Parameters: * **da** – The dynamic array * **data** – Pointer to the new data to push Returns: Index of the new value * * * void \*da\_push\_back\_new(da)[](#c.da_push_back_new "Link to this definition") Pushes a zeroed value to the back of the array, and returns a pointer to it. Parameters: * **da** – The dynamic array Returns: Pointer to the new value * * * size\_t da\_push\_back\_array(da, const void \*src\_array, size\_t item\_count)[](#c.da_push_back_array "Link to this definition") Pushes an array of values to the back of the array. Parameters: * **da** – The dynamic array * **src\_array** – Pointer of the array of values * **item\_count** – Number of items to push back Returns: Index of the first new value * * * void da\_insert(da, size\_t idx, const void \*data)[](#c.da_insert "Link to this definition") Inserts a value at a given index. Parameters: * **da** – The dynamic array: * **idx** – Index where the new item will be inserted * **data** – Pointer to the item data to insert * * * void \*da\_insert\_new(da, size\_t idx)[](#c.da_insert_new "Link to this definition") Inserts a new zeroed value at a specific index, and returns a pointer to it. Parameters: * **da** – The dynamic array * **idx** – Index to insert at Returns: Pointer to the new value * * * void da\_insert\_array(dst, size\_t idx, src, size\_t n)[](#c.da_insert_array "Link to this definition") Inserts one or more items at a given index. Parameters: * **dst** – The dynamic array: * **idx** – Index where the new item will be inserted * **src** – Pointer to the first item to insert * **n** – Number of items to insert * * * void da\_insert\_da(da\_dst, size\_t idx, da\_src)[](#c.da_insert_da "Link to this definition") Inserts a dynamic array in to another dynamic array at a specific index. Parameters: * **da\_dst** – Destination dynamic array being inserted in to * **idx** – Index to insert the data at * **da\_src** – The dynamic array to insert * * * void da\_erase(da, size\_t idx)[](#c.da_erase "Link to this definition") Erases an item at a specific index. Parameters: * **da** – The dynamic array * **idx** – The index of the value to remove * * * void da\_erase\_item(da, const void \*item\_data)[](#c.da_erase_item "Link to this definition") Erases an item that matches the value specified Parameters: * **da** – The dynamic array * **item\_data** – Pointer to the data to remove * * * void da\_erase\_range(da, size\_t start\_idx, size\_t end\_idx)[](#c.da_erase_range "Link to this definition") Erases a range of values, including the element at `start_idx`, but not the one at `end_idx`. Parameters: * **da** – The dynamic array * **start\_idx** – The starting index * **end\_idx** – The ending index * * * void da\_pop\_back(da)[](#c.da_pop_back "Link to this definition") Removes one item from the end of a dynamic array. Parameters: * **da** – The dynamic array * * * void da\_join(da\_dst, da\_src)[](#c.da_join "Link to this definition") Pushes _da\_src_ to the end of _da\_dst_ and frees _da\_src_. Parameters: * **da\_dst** – The destination dynamic array * **da\_src** – The source dynamic array * * * void da\_split(da\_dst1, da\_dst2, da\_src, size\_t split\_idx)[](#c.da_split "Link to this definition") 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. Parameters: * **da\_dst1** – Dynamic array that will get the lower half * **da\_dst2** – Dynamic array that will get the upper half * **da\_src** – Dynamic array to split * **split\_idx** – Index to split _da\_src_ at * * * void da\_move\_item(da, size\_t src\_idx, size\_t dst\_idx)[](#c.da_move_item "Link to this definition") Moves an item from one index to another, moving data between if necessary. Parameters: * **da** – The dynamic array * **src\_idx** – The index of the item to move * **dst\_idx** – The new index of where the item will be moved to * * * void da\_swap(da, size\_t idx1, size\_t idx2)[](#c.da_swap "Link to this definition") Swaps two values at the given indices. Parameters: * **da** – The dynamic array * **idx1** – Index of the first item to swap * **idx2** – Index of the second item to swap --- # Logging — OBS Studio 31.0.2 documentation * [](index) * [Platform/Utility API Reference (libobs/util)](reference-libobs-util) * Logging * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/reference-libobs-util-base.rst) [Previous](reference-libobs-util "Platform/Utility API Reference (libobs/util)") [Next](reference-libobs-util-bmem "Memory Management") * * * Logging[](#logging "Link to this heading") ============================================ Functions for logging and getting log data. #include Logging Levels[](#logging-levels "Link to this heading") ---------------------------------------------------------- **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[](#logging-functions "Link to this heading") ---------------------------------------------------------------- typedef void (\*log\_handler\_t)(int lvl, const char \*msg, va\_list args, void \*p)[](#c.log_handler_t "Link to this definition") Logging callback. * * * void base\_set\_log\_handler([log\_handler\_t](#c.log_handler_t "log_handler_t") handler, void \*param)[](#c.base_set_log_handler "Link to this definition") void base\_get\_log\_handler([log\_handler\_t](#c.log_handler_t "log_handler_t") \*handler, void \*\*param)[](#c.base_get_log_handler "Link to this definition") Sets/gets the current log handler. * * * void base\_set\_crash\_handler(void (\*handler)(const char\*, va\_list, void\*), void \*param)[](#c.base_set_crash_handler "Link to this definition") Sets the current crash handler. * * * void blogva(int log\_level, const char \*format, va\_list args)[](#c.blogva "Link to this definition") Logging function (using a va\_list). * * * void blog(int log\_level, const char \*format, ...)[](#c.blog "Link to this definition") Logging function. * * * void bcrash(const char \*format, ...)[](#c.bcrash "Link to this definition") Crash function. --- # Scene API Reference (obs_scene_t) — OBS Studio 31.0.2 documentation * [](index) * [Core API Object Reference](reference-core-objects) * Scene API Reference (obs\_scene\_t) * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/reference-scenes.rst) [Previous](reference-sources "Source API Reference (obs_source_t)") [Next](reference-outputs "Output API Reference (obs_output_t)") * * * Scene API Reference (obs\_scene\_t)[](#scene-api-reference-obs-scene-t "Link to this heading") ================================================================================================ A scene is a source which contains and renders other sources using specific transforms and/or filtering type obs\_scene\_t[](#c.obs_scene_t "Link to this definition") A reference-counted scene object. type obs\_sceneitem\_t[](#c.obs_sceneitem_t "Link to this definition") A reference-counted scene item object. #include Scene Item Transform Structure (obs\_transform\_info)[](#scene-item-transform-structure-obs-transform-info "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------ struct obs\_transform\_info[](#c.obs_transform_info "Link to this definition") Scene item transform structure. struct [vec2](reference-libobs-graphics-vec2#c.vec2 "vec2") [obs\_transform\_info](#c.obs_transform_info "obs_transform_info") .pos[](#c.obs_transform_info.pos "Link to this definition") Position. float [obs\_transform\_info](#c.obs_transform_info "obs_transform_info") .rot[](#c.obs_transform_info.rot "Link to this definition") Rotation (degrees). struct [vec2](reference-libobs-graphics-vec2#c.vec2 "vec2") [obs\_transform\_info](#c.obs_transform_info "obs_transform_info") .scale[](#c.obs_transform_info.scale "Link to this definition") Scale. uint32\_t [obs\_transform\_info](#c.obs_transform_info "obs_transform_info") .alignment[](#c.obs_transform_info.alignment "Link to this definition") 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** enum obs\_bounds\_type [obs\_transform\_info](#c.obs_transform_info "obs_transform_info") .bounds\_type[](#c.obs_transform_info.bounds_type "Link to this definition") 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 uint32\_t [obs\_transform\_info](#c.obs_transform_info "obs_transform_info") .bounds\_alignment[](#c.obs_transform_info.bounds_alignment "Link to this definition") 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** struct [vec2](reference-libobs-graphics-vec2#c.vec2 "vec2") [obs\_transform\_info](#c.obs_transform_info "obs_transform_info") .bounds[](#c.obs_transform_info.bounds "Link to this definition") The bounding box (if a bounding box is enabled). Scene Item Crop Structure (obs\_sceneitem\_crop)[](#scene-item-crop-structure-obs-sceneitem-crop "Link to this heading") -------------------------------------------------------------------------------------------------------------------------- struct obs\_sceneitem\_crop[](#c.obs_sceneitem_crop "Link to this definition") Scene item crop structure. int [obs\_sceneitem\_crop](#c.obs_sceneitem_crop "obs_sceneitem_crop") .left[](#c.obs_sceneitem_crop.left "Link to this definition") Left crop value. int [obs\_sceneitem\_crop](#c.obs_sceneitem_crop "obs_sceneitem_crop") .top[](#c.obs_sceneitem_crop.top "Link to this definition") Top crop value. int [obs\_sceneitem\_crop](#c.obs_sceneitem_crop "obs_sceneitem_crop") .right[](#c.obs_sceneitem_crop.right "Link to this definition") Right crop value. int [obs\_sceneitem\_crop](#c.obs_sceneitem_crop "obs_sceneitem_crop") .bottom[](#c.obs_sceneitem_crop.bottom "Link to this definition") Bottom crop value. Scene Item Order Info Structure (\*obs\_sceneitem\_order\_info)[](#scene-item-order-info-structure-obs-sceneitem-order-info "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------- struct obs\_sceneitem\_order\_info[](#c.obs_sceneitem_order_info "Link to this definition") Scene item order info structure. [obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*[obs\_sceneitem\_order\_info](#c.obs_sceneitem_order_info "obs_sceneitem_order_info") .group[](#c.obs_sceneitem_order_info.group "Link to this definition") Specifies the group this scene item belongs to, or _NULL_ if none. [obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*[obs\_sceneitem\_order\_info](#c.obs_sceneitem_order_info "obs_sceneitem_order_info") .item[](#c.obs_sceneitem_order_info.item "Link to this definition") Specifies the scene item. Scene Signals[](#scene-signals "Link to this heading") -------------------------------------------------------- **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 scene. **reorder** (ptr scene) > Called when scene items have been reordered in the scene. **refresh** (ptr scene) > Called when the entire scene item list needs to be refreshed. Usually this is only used when groups have changed. **item\_visible** (ptr scene, ptr item, bool visible) > Called when a scene item’s visibility state changes. **item\_locked** (ptr scene, ptr item, bool locked) > Called when a scene item has been locked or unlocked. **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[](#general-scene-functions "Link to this heading") ---------------------------------------------------------------------------- [obs\_scene\_t](#c.obs_scene_t "obs_scene_t") \*obs\_scene\_create(const char \*name)[](#c.obs_scene_create "Link to this definition") Parameters: * **name** – Name of the scene source. If it’s not unique, it will be made unique Returns: A reference to a scene * * * [obs\_scene\_t](#c.obs_scene_t "obs_scene_t") \*obs\_scene\_create\_private(const char \*name)[](#c.obs_scene_create_private "Link to this definition") Parameters: * **name** – Name of the scene source. Does not have to be unique, or can be _NULL_ Returns: A reference to a private scene * * * [obs\_scene\_t](#c.obs_scene_t "obs_scene_t") \*obs\_scene\_duplicate([obs\_scene\_t](#c.obs_scene_t "obs_scene_t") \*scene, const char \*name, enum obs\_scene\_duplicate\_type type)[](#c.obs_scene_duplicate "Link to this definition") Duplicates a scene. When a scene is duplicated, its sources can be just referenced, or fully duplicated. Parameters: * **name** – Name of the new scene source * **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 Returns: A reference to a new scene * * * [obs\_scene\_t](#c.obs_scene_t "obs_scene_t") \*obs\_scene\_get\_ref([obs\_scene\_t](#c.obs_scene_t "obs_scene_t") \*scene)[](#c.obs_scene_get_ref "Link to this definition") Returns an incremented reference if still valid, otherwise returns _NULL_. Release with [`obs_scene_release()`](#c.obs_scene_release "obs_scene_release") . * * * void obs\_scene\_release([obs\_scene\_t](#c.obs_scene_t "obs_scene_t") \*scene)[](#c.obs_scene_release "Link to this definition") Releases a reference to a scene. * * * [obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*obs\_scene\_add([obs\_scene\_t](#c.obs_scene_t "obs_scene_t") \*scene, [obs\_source\_t](reference-sources#c.obs_source_t "obs_source_t") \*source)[](#c.obs_scene_add "Link to this definition") Returns: A new scene item for a source within a scene. Does not increment the reference * * * [obs\_source\_t](reference-sources#c.obs_source_t "obs_source_t") \*obs\_scene\_get\_source(const [obs\_scene\_t](#c.obs_scene_t "obs_scene_t") \*scene)[](#c.obs_scene_get_source "Link to this definition") Returns: The scene’s source. Does not increment the reference * * * [obs\_scene\_t](#c.obs_scene_t "obs_scene_t") \*obs\_scene\_from\_source(const [obs\_source\_t](reference-sources#c.obs_source_t "obs_source_t") \*source)[](#c.obs_scene_from_source "Link to this definition") Returns: The scene context, or _NULL_ if not a scene. Does not increase the reference * * * [obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*obs\_scene\_find\_source([obs\_scene\_t](#c.obs_scene_t "obs_scene_t") \*scene, const char \*name)[](#c.obs_scene_find_source "Link to this definition") Parameters: * **name** – The name of the source to find Returns: The scene item if found, otherwise _NULL_ if not found * * * [obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*obs\_scene\_find\_source\_recursive([obs\_scene\_t](#c.obs_scene_t "obs_scene_t") \*scene, const char \*name)[](#c.obs_scene_find_source_recursive "Link to this definition") Same as obs\_scene\_find\_source, but also searches groups within the scene. Parameters: * **name** – The name of the source to find Returns: The scene item if found, otherwise _NULL_ if not found * * * [obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*obs\_scene\_find\_sceneitem\_by\_id([obs\_scene\_t](#c.obs_scene_t "obs_scene_t") \*scene, int64\_t id)[](#c.obs_scene_find_sceneitem_by_id "Link to this definition") Parameters: * **id** – The unique numeric identifier of the scene item Returns: The scene item if found, otherwise _NULL_ if not found * * * void obs\_scene\_enum\_items([obs\_scene\_t](#c.obs_scene_t "obs_scene_t") \*scene, bool (\*callback)([obs\_scene\_t](#c.obs_scene_t "obs_scene_t") \*, [obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*, void\*), void \*param)[](#c.obs_scene_enum_items "Link to this definition") Enumerates scene items within a scene in order of the bottommost scene item to the topmost scene item. Callback function returns true to continue enumeration, or false to end enumeration. Use [`obs_sceneitem_addref()`](#c.obs_sceneitem_addref "obs_sceneitem_addref") if you want to retain a reference after obs\_scene\_enum\_items finishes. For scripting, use [`obs_scene_enum_items()`](scripting#obs_scene_enum_items "obs_scene_enum_items") . * * * bool obs\_scene\_reorder\_items([obs\_scene\_t](#c.obs_scene_t "obs_scene_t") \*scene, [obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*const \*item\_order, size\_t item\_order\_size)[](#c.obs_scene_reorder_items "Link to this definition") Reorders items within a scene. * * * bool obs\_scene\_reorder\_items2([obs\_scene\_t](#c.obs_scene_t "obs_scene_t") \*scene, struct [obs\_sceneitem\_order\_info](#c.obs_sceneitem_order_info "obs_sceneitem_order_info") \*item\_order, size\_t item\_order\_size)[](#c.obs_scene_reorder_items2 "Link to this definition") Reorders items within a scene with groups and group sub-items. * * * void obs\_scene\_prune\_sources([obs\_scene\_t](#c.obs_scene_t "obs_scene_t") \*scene)[](#c.obs_scene_prune_sources "Link to this definition") Releases all sources from a scene that have been marked as removed by obs\_source\_remove. * * * Scene Item Functions[](#scene-item-functions "Link to this heading") ---------------------------------------------------------------------- void obs\_sceneitem\_addref([obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item)[](#c.obs_sceneitem_addref "Link to this definition") void obs\_sceneitem\_release([obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item)[](#c.obs_sceneitem_release "Link to this definition") Adds/releases a reference to a scene item. * * * void obs\_sceneitem\_remove([obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item)[](#c.obs_sceneitem_remove "Link to this definition") Removes the scene item from the scene. * * * [obs\_scene\_t](#c.obs_scene_t "obs_scene_t") \*obs\_sceneitem\_get\_scene(const [obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item)[](#c.obs_sceneitem_get_scene "Link to this definition") Returns: The scene associated with the scene item. Does not increment the reference * * * [obs\_source\_t](reference-sources#c.obs_source_t "obs_source_t") \*obs\_sceneitem\_get\_source(const [obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item)[](#c.obs_sceneitem_get_source "Link to this definition") Returns: The source associated with the scene item. Does not increment the reference * * * [obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*obs\_scene\_sceneitem\_from\_source([obs\_scene\_t](#c.obs_scene_t "obs_scene_t") \*scene, [obs\_source\_t](reference-sources#c.obs_source_t "obs_source_t") \*source)[](#c.obs_scene_sceneitem_from_source "Link to this definition") This will add a reference to the sceneitem. Returns: The sceneitem associated with a source in a scene. Returns NULL if not found. Deprecated since version 31.0: This function is problematic because there can be multiple items of the same source in a scene. In that case, which of those this function will return is undefined. If this is the behavior you need, manually use [`obs_scene_enum_items()`](#c.obs_scene_enum_items "obs_scene_enum_items") instead. * * * void obs\_sceneitem\_set\_id([obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item);[](#c.obs_sceneitem_set_id "Link to this definition") Sets the unique numeric identifier of the sceneitem. This is dangerous function and should not normally be used. It can cause errors within obs. * * * int64\_t obs\_sceneitem\_get\_id(const [obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item)[](#c.obs_sceneitem_get_id "Link to this definition") Gets the numeric identifier of the sceneitem. Returns: Gets the unique numeric identifier of the scene item. * * * [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*obs\_scene\_save\_transform\_states([obs\_scene\_t](#c.obs_scene_t "obs_scene_t") \*scene, bool all\_items)[](#c.obs_scene_save_transform_states "Link to this definition") void obs\_scene\_load\_transform\_states(const char \*states)[](#c.obs_scene_load_transform_states "Link to this definition") Saves all the transformation states for the sceneitems in scene. When all\_items is false, it will only save selected items Returns: Data containing transformation states for all\* sceneitems in scene * * * void obs\_sceneitem\_set\_pos([obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item, const struct [vec2](reference-libobs-graphics-vec2#c.vec2 "vec2") \*pos)[](#c.obs_sceneitem_set_pos "Link to this definition") void obs\_sceneitem\_get\_pos(const [obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item, struct [vec2](reference-libobs-graphics-vec2#c.vec2 "vec2") \*pos)[](#c.obs_sceneitem_get_pos "Link to this definition") Sets/gets the position of a scene item. * * * void obs\_sceneitem\_set\_rot([obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item, float rot\_deg)[](#c.obs_sceneitem_set_rot "Link to this definition") float obs\_sceneitem\_get\_rot(const [obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item)[](#c.obs_sceneitem_get_rot "Link to this definition") Sets/gets the rotation of a scene item. * * * void obs\_sceneitem\_set\_scale([obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item, const struct [vec2](reference-libobs-graphics-vec2#c.vec2 "vec2") \*scale)[](#c.obs_sceneitem_set_scale "Link to this definition") void obs\_sceneitem\_get\_scale(const [obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item, struct [vec2](reference-libobs-graphics-vec2#c.vec2 "vec2") \*scale)[](#c.obs_sceneitem_get_scale "Link to this definition") Sets/gets the scaling of the scene item. * * * void obs\_sceneitem\_set\_alignment([obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item, uint32\_t alignment)[](#c.obs_sceneitem_set_alignment "Link to this definition") uint32\_t obs\_sceneitem\_get\_alignment(const [obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item)[](#c.obs_sceneitem_get_alignment "Link to this definition") Sets/gets the alignment of the scene item relative to its position. Parameters: * **alignment** – Can be any bitwise OR combination of: OBS\_ALIGN\_CENTER OBS\_ALIGN\_LEFT OBS\_ALIGN\_RIGHT OBS\_ALIGN\_TOP OBS\_ALIGN\_BOTTOM * * * void obs\_sceneitem\_set\_order([obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item, enum obs\_order\_movement movement)[](#c.obs_sceneitem_set_order "Link to this definition") Changes the scene item’s order relative to the other scene items within the scene. Parameters: * **movement** – Can be one of the following: OBS\_ORDER\_MOVE\_UP OBS\_ORDER\_MOVE\_DOWN OBS\_ORDER\_MOVE\_TOP OBS\_ORDER\_MOVE\_BOTTOM * * * void obs\_sceneitem\_set\_order\_position([obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item, int position)[](#c.obs_sceneitem_set_order_position "Link to this definition") Changes the sceneitem’s order index. * * * int obs\_sceneitem\_get\_order\_position([obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item)[](#c.obs_sceneitem_get_order_position "Link to this definition") Returns: Gets position of sceneitem in its scene. * * * void obs\_sceneitem\_set\_bounds\_type([obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item, enum obs\_bounds\_type type)[](#c.obs_sceneitem_set_bounds_type "Link to this definition") enum obs\_bounds\_type obs\_sceneitem\_get\_bounds\_type(const [obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item)[](#c.obs_sceneitem_get_bounds_type "Link to this definition") 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. Parameters: * **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 * * * void obs\_sceneitem\_set\_bounds\_alignment([obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item, uint32\_t alignment)[](#c.obs_sceneitem_set_bounds_alignment "Link to this definition") uint32\_t obs\_sceneitem\_get\_bounds\_alignment(const [obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item)[](#c.obs_sceneitem_get_bounds_alignment "Link to this definition") Sets/gets the alignment of the source within the bounding box. Parameters: * **alignment** – Can be any bitwise OR combination of: OBS\_ALIGN\_CENTER OBS\_ALIGN\_LEFT OBS\_ALIGN\_RIGHT OBS\_ALIGN\_TOP OBS\_ALIGN\_BOTTOM * * * void obs\_sceneitem\_set\_bounds([obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item, const struct [vec2](reference-libobs-graphics-vec2#c.vec2 "vec2") \*bounds)[](#c.obs_sceneitem_set_bounds "Link to this definition") void obs\_sceneitem\_get\_bounds(const [obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item, struct [vec2](reference-libobs-graphics-vec2#c.vec2 "vec2") \*bounds)[](#c.obs_sceneitem_get_bounds "Link to this definition") Sets/gets the bounding box width/height of the scene item. * * * void obs\_sceneitem\_set\_info([obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item, const struct [obs\_transform\_info](#c.obs_transform_info "obs_transform_info") \*info)[](#c.obs_sceneitem_set_info "Link to this definition") void obs\_sceneitem\_get\_info(const [obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item, struct [obs\_transform\_info](#c.obs_transform_info "obs_transform_info") \*info)[](#c.obs_sceneitem_get_info "Link to this definition") Sets/gets the transform information of the scene item. * * * void obs\_sceneitem\_set\_info2([obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item, const struct [obs\_transform\_info](#c.obs_transform_info "obs_transform_info") \*info)[](#c.obs_sceneitem_set_info2 "Link to this definition") void obs\_sceneitem\_get\_info2(const [obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item, struct [obs\_transform\_info](#c.obs_transform_info "obs_transform_info") \*info)[](#c.obs_sceneitem_get_info2 "Link to this definition") Sets/gets the transform information of the scene item. This version of the function also sets the crop\_to\_bounds member of obs\_transform\_info. Added in version 30.1. * * * void obs\_sceneitem\_get\_draw\_transform(const [obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item, struct [matrix4](reference-libobs-graphics-matrix4#c.matrix4 "matrix4") \*transform)[](#c.obs_sceneitem_get_draw_transform "Link to this definition") Gets the transform matrix of the scene item used for drawing the source. * * * void obs\_sceneitem\_get\_box\_transform(const [obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item, struct [matrix4](reference-libobs-graphics-matrix4#c.matrix4 "matrix4") \*transform)[](#c.obs_sceneitem_get_box_transform "Link to this definition") Gets the transform matrix of the scene item used for the bounding box or edges of the scene item. * * * void obs\_sceneitem\_select([obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item, bool select)[](#c.obs_sceneitem_select "Link to this definition") bool obs\_sceneitem\_selected(const [obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item)[](#c.obs_sceneitem_selected "Link to this definition") Sets/gets the selection state of the scene item. Note that toggling the selected state will not affect the selected state of other scene items, as multiple scene items can be selected. * * * bool obs\_sceneitem\_set\_visible([obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item, bool visible)[](#c.obs_sceneitem_set_visible "Link to this definition") bool obs\_sceneitem\_visible(const [obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item)[](#c.obs_sceneitem_visible "Link to this definition") Sets/gets the visibility state of the scene item. * * * bool obs\_sceneitem\_set\_locked([obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item, bool locked)[](#c.obs_sceneitem_set_locked "Link to this definition") bool obs\_sceneitem\_locked(const [obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item)[](#c.obs_sceneitem_locked "Link to this definition") Sets/gets the locked/unlocked state of the scene item. * * * void obs\_sceneitem\_set\_crop([obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item, const struct [obs\_sceneitem\_crop](#c.obs_sceneitem_crop "obs_sceneitem_crop") \*crop)[](#c.obs_sceneitem_set_crop "Link to this definition") void obs\_sceneitem\_get\_crop(const [obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item, struct [obs\_sceneitem\_crop](#c.obs_sceneitem_crop "obs_sceneitem_crop") \*crop)[](#c.obs_sceneitem_get_crop "Link to this definition") Sets/gets the cropping of the scene item. * * * void obs\_sceneitem\_set\_scale\_filter([obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item, enum obs\_scale\_type filter)[](#c.obs_sceneitem_set_scale_filter "Link to this definition") enum obs\_scale\_type obs\_sceneitem\_get\_scale\_filter([obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item)[](#c.obs_sceneitem_get_scale_filter "Link to this definition") Sets/gets the scale filter used for the scene item. Parameters: * **filter** – Can be one of the following values: OBS\_SCALE\_DISABLE OBS\_SCALE\_POINT OBS\_SCALE\_BICUBIC OBS\_SCALE\_BILINEAR OBS\_SCALE\_LANCZOS * * * void obs\_sceneitem\_set\_blending\_method([obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item, enum obs\_blending\_method method)[](#c.obs_sceneitem_set_blending_method "Link to this definition") enum obs\_blending\_method obs\_sceneitem\_get\_blending\_method([obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item)[](#c.obs_sceneitem_get_blending_method "Link to this definition") Sets/gets the blending method used for the scene item. Parameters: * **method** – Can be one of the following values: OBS\_BLEND\_METHOD\_DEFAULT OBS\_BLEND\_METHOD\_SRGB\_OFF * * * void obs\_sceneitem\_set\_blending\_mode([obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item, enum obs\_blending\_type type)[](#c.obs_sceneitem_set_blending_mode "Link to this definition") enum obs\_blending\_type obs\_sceneitem\_get\_blending\_mode([obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item)[](#c.obs_sceneitem_get_blending_mode "Link to this definition") Sets/gets the blending mode used for the scene item. Parameters: * **type** – Can be one of the following values: OBS\_BLEND\_NORMAL OBS\_BLEND\_ADDITIVE OBS\_BLEND\_SUBTRACT OBS\_BLEND\_SCREEN OBS\_BLEND\_MULTIPLY OBS\_BLEND\_LIGHTEN OBS\_BLEND\_DARKEN * * * void obs\_sceneitem\_defer\_update\_begin([obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item)[](#c.obs_sceneitem_defer_update_begin "Link to this definition") void obs\_sceneitem\_defer\_update\_end([obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item)[](#c.obs_sceneitem_defer_update_end "Link to this definition") 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. * * * [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*obs\_sceneitem\_get\_private\_settings([obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item)[](#c.obs_sceneitem_get_private_settings "Link to this definition") Returns: 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. Release with [`obs_data_release()`](reference-settings#c.obs_data_release "obs_data_release") . * * * void obs\_sceneitem\_set\_transition([obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item, bool show, [obs\_source\_t](reference-sources#c.obs_source_t "obs_source_t") \*transition)[](#c.obs_sceneitem_set_transition "Link to this definition") Sets a transition for showing or hiding a scene item. Parameters: * **item** – The target scene item * **show** – If _true_, this will set the show transition. If _false_, this will set the hide transition. * **transition** – The transition to set. Pass _NULL_ to remove the transition. * * * [obs\_source\_t](reference-sources#c.obs_source_t "obs_source_t") \*obs\_sceneitem\_get\_transition([obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item, bool show)[](#c.obs_sceneitem_get_transition "Link to this definition") Parameters: * **item** – The target scene item * **show** – If _true_, this will return the show transition. If _false_, this will return the hide transition. Returns: The transition for showing or hiding a scene item. _NULL_ if no transition is set. * * * * * * void obs\_sceneitem\_set\_transition\_duration([obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item, bool show, uint32\_t duration\_ms)[](#c.obs_sceneitem_set_transition_duration "Link to this definition") Sets the transition duration for showing or hiding a scene item. Parameters: * **item** – The target scene item * **show** – If _true_, this will set the duration of the show transition. If _false_, this will set the duration of the hide transition. * **duration\_ms** – The transition duration in milliseconds * * * uint32\_t obs\_sceneitem\_get\_transition\_duration([obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item, bool show)[](#c.obs_sceneitem_get_transition_duration "Link to this definition") Gets the transition duration for showing or hiding a scene item. Parameters: * **item** – The target scene item * **show** – If _true_, this will return the duration of the show transition. If _false_, this will return the duration of the hide transition. Returns: The transition duration in milliseconds * * * void obs\_sceneitem\_do\_transition([obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item, bool visible)[](#c.obs_sceneitem_do_transition "Link to this definition") Start the transition for showing or hiding a scene item. * * * Scene Item Group Functions[](#scene-item-group-functions "Link to this heading") ---------------------------------------------------------------------------------- [obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*obs\_scene\_add\_group([obs\_scene\_t](#c.obs_scene_t "obs_scene_t") \*scene, const char \*name)[](#c.obs_scene_add_group "Link to this definition") Adds a group with the specified name. Does not signal the scene with the _refresh_ signal. Parameters: * **scene** – Scene to add the group to * **name** – Name of the group Returns: The new group’s scene item * * * [obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*obs\_scene\_add\_group2([obs\_scene\_t](#c.obs_scene_t "obs_scene_t") \*scene, const char \*name, bool signal)[](#c.obs_scene_add_group2 "Link to this definition") Adds a group with the specified name. Parameters: * **scene** – Scene to add the group to * **name** – Name of the group * **signal** – If _true_, signals the scene with the _refresh_ signal Returns: The new group’s scene item * * * [obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*obs\_scene\_insert\_group([obs\_scene\_t](#c.obs_scene_t "obs_scene_t") \*scene, const char \*name, [obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*\*items, size\_t count)[](#c.obs_scene_insert_group "Link to this definition") Creates a group out of the specified scene items. The group will be inserted at the top scene item. Does not signal the scene with the _refresh_ signal. Parameters: * **scene** – Scene to add the group to * **name** – Name of the group * **items** – Array of scene items to put in a group * **count** – Number of scene items in the array Returns: The new group’s scene item * * * [obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*obs\_scene\_insert\_group2([obs\_scene\_t](#c.obs_scene_t "obs_scene_t") \*scene, const char \*name, [obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*\*items, size\_t count, bool signal)[](#c.obs_scene_insert_group2 "Link to this definition") Creates a group out of the specified scene items. The group will be inserted at the top scene item. Does not signal a refresh. Parameters: * **scene** – Scene to add the group to * **name** – Name of the group * **items** – Array of scene items to put in a group * **count** – Number of scene items in the array * **signal** – If _true_, signals the scene with the _refresh_ signal Returns: The new group’s scene item * * * [obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*obs\_scene\_get\_group([obs\_scene\_t](#c.obs_scene_t "obs_scene_t") \*scene, const char \*name)[](#c.obs_scene_get_group "Link to this definition") Finds a group within a scene by its name. Parameters: * **scene** – Scene to find the group within * **name** – The name of the group to find Returns: The group scene item, or _NULL_ if not found * * * [obs\_scene\_t](#c.obs_scene_t "obs_scene_t") \*obs\_group\_from\_source(const [obs\_source\_t](reference-sources#c.obs_source_t "obs_source_t") \*source)[](#c.obs_group_from_source "Link to this definition") Returns: The group context, or _NULL_ if not a group. Does not increase the reference * * * [obs\_scene\_t](#c.obs_scene_t "obs_scene_t") \*obs\_group\_or\_scene\_from\_source(const [obs\_source\_t](reference-sources#c.obs_source_t "obs_source_t") \*source)[](#c.obs_group_or_scene_from_source "Link to this definition") Returns: The context for the source, regardless of if it is a group or a scene. _NULL_ if neither. Does not increase the reference * * * bool obs\_sceneitem\_is\_group([obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item)[](#c.obs_sceneitem_is_group "Link to this definition") Parameters: * **item** – Scene item Returns: _true_ if scene item is a group, _false_ otherwise * * * [obs\_scene\_t](#c.obs_scene_t "obs_scene_t") \*obs\_sceneitem\_group\_get\_scene(const [obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*group)[](#c.obs_sceneitem_group_get_scene "Link to this definition") Parameters: * **group** – Group scene item Returns: Scene of the group, or _NULL_ if not a group * * * void obs\_sceneitem\_group\_ungroup([obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*group)[](#c.obs_sceneitem_group_ungroup "Link to this definition") Ungroups the specified group. Scene items within the group will be placed where the group was. Does not signal the scene with the _refresh_ signal. * * * void obs\_sceneitem\_group\_ungroup2([obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*group, bool signal)[](#c.obs_sceneitem_group_ungroup2 "Link to this definition") Ungroups the specified group. Scene items within the group will be placed where the group was. Parameters: * **group** – Group scene item * **signal** – If _true_, signals the scene with the _refresh_ signal * * * void obs\_sceneitem\_group\_add\_item([obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*group, [obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item)[](#c.obs_sceneitem_group_add_item "Link to this definition") Adds a scene item to a group. * * * void obs\_sceneitem\_group\_remove\_item([obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item)[](#c.obs_sceneitem_group_remove_item "Link to this definition") Removes a scene item from a group. The item will be placed before the group in the main scene. * * * [obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*obs\_sceneitem\_get\_group([obs\_scene\_t](#c.obs_scene_t "obs_scene_t") \*scene, [obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item)[](#c.obs_sceneitem_get_group "Link to this definition") Returns the parent group of a scene item. Parameters: * **scene** – Scene to find the group within * **item** – Scene item to get the group of Returns: The parent group of the scene item, or _NULL_ if not in a group * * * void obs\_sceneitem\_group\_enum\_items([obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*group, bool (\*callback)([obs\_scene\_t](#c.obs_scene_t "obs_scene_t") \*, [obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*, void\*), void \*param)[](#c.obs_sceneitem_group_enum_items "Link to this definition") Enumerates scene items within a group. Callback function returns true to continue enumeration, or false to end enumeration. Use [`obs_sceneitem_addref()`](#c.obs_sceneitem_addref "obs_sceneitem_addref") if you want to retain a reference after obs\_sceneitem\_group\_enum\_items finishes. * * * void obs\_sceneitem\_defer\_group\_resize\_begin([obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item)[](#c.obs_sceneitem_defer_group_resize_begin "Link to this definition") void obs\_sceneitem\_defer\_group\_resize\_end([obs\_sceneitem\_t](#c.obs_sceneitem_t "obs_sceneitem_t") \*item)[](#c.obs_sceneitem_defer_group_resize_end "Link to this definition") Allows the ability to call any one of the transform functions on scene items within a group without updating the internal matrices of the group until obs\_sceneitem\_defer\_group\_resize\_end has been called. This is necessary if the user is resizing items while they are within a group, as the group’s transform will automatically update its transform every frame otherwise. --- # Output API Reference (obs_output_t) — OBS Studio 31.0.2 documentation * [](index) * [Core API Object Reference](reference-core-objects) * Output API Reference (obs\_output\_t) * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/reference-outputs.rst) [Previous](reference-scenes "Scene API Reference (obs_scene_t)") [Next](reference-encoders "Encoder API Reference (obs_encoder_t)") * * * Output API Reference (obs\_output\_t)[](#output-api-reference-obs-output-t "Link to this heading") ==================================================================================================== 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](https://github.com/obsproject/obs-studio/blob/master/libobs/obs-output.h) file is the dedicated header for implementing outputs type obs\_output\_t[](#c.obs_output_t "Link to this definition") A reference-counted output object. type obs\_weak\_output\_t[](#c.obs_weak_output_t "Link to this definition") A weak reference to an output object. #include Output Definition Structure (obs\_output\_info)[](#output-definition-structure-obs-output-info "Link to this heading") ------------------------------------------------------------------------------------------------------------------------ struct obs\_output\_info[](#c.obs_output_info "Link to this definition") Output definition structure. const char \*[obs\_output\_info](#c.obs_output_info "obs_output_info") .id[](#c.obs_output_info.id "Link to this definition") Unique string identifier for the source (required). uint32\_t [obs\_output\_info](#c.obs_output_info "obs_output_info") .flags[](#c.obs_output_info.flags "Link to this definition") 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 [`obs_output_set_video_encoder()`](#c.obs_output_set_video_encoder "obs_output_set_video_encoder") and/or [`obs_output_set_audio_encoder()`](#c.obs_output_set_audio_encoder "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 [`obs_output_set_service()`](#c.obs_output_set_service "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. * **OBS\_OUTPUT\_CAN\_PAUSE** - Output supports pausing. When this capability flag is used, the output supports pausing. When an output is paused, raw or encoded audio/video data will be halted when paused down to the exact point to the closest video frame. Audio data will be correctly truncated down to the exact audio sample according to that video frame timing. const char \*(\*[obs\_output\_info](#c.obs_output_info "obs_output_info") .get\_name)(void \*type\_data)[](#c.obs_output_info.get_name "Link to this definition") 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 void \*(\*[obs\_output\_info](#c.obs_output_info "obs_output_info") .create)([obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*settings, [obs\_output\_t](#c.obs_output_t "obs_output_t") \*output)[](#c.obs_output_info.create "Link to this definition") 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 void (\*[obs\_output\_info](#c.obs_output_info "obs_output_info") .destroy)(void \*data)[](#c.obs_output_info.destroy "Link to this definition") Destroys the implementation data for the output. bool (\*[obs\_output\_info](#c.obs_output_info "obs_output_info") .start)(void \*data)[](#c.obs_output_info.start "Link to this definition") 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 void (\*[obs\_output\_info](#c.obs_output_info "obs_output_info") .stop)(void \*data, uint64\_t ts)[](#c.obs_output_info.stop "Link to this definition") 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 [`obs_output_end_data_capture()`](#c.obs_output_end_data_capture "obs_output_end_data_capture") or [`obs_output_signal_stop()`](#c.obs_output_signal_stop "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 void (\*[obs\_output\_info](#c.obs_output_info "obs_output_info") .raw\_video)(void \*data, struct [video\_data](reference-libobs-media-io#c.video_data "video_data") \*frame)[](#c.obs_output_info.raw_video "Link to this definition") This is called when the output receives raw video data. Only applies to outputs that are not encoded. Param frame: The raw video frame void (\*[obs\_output\_info](#c.obs_output_info "obs_output_info") .raw\_audio)(void \*data, struct [audio\_data](reference-libobs-media-io#c.audio_data "audio_data") \*frames)[](#c.obs_output_info.raw_audio "Link to this definition") This is called when the output receives raw audio data. Only applies to outputs that are not encoded. **This callback must be used with single-track raw outputs.** Param frames: The raw audio frames void (\*[obs\_output\_info](#c.obs_output_info "obs_output_info") .raw\_audio2)(void \*data, size\_t idx, struct [audio\_data](reference-libobs-media-io#c.audio_data "audio_data") \*frames)[](#c.obs_output_info.raw_audio2 "Link to this definition") This is called when the output receives raw audio data. Only applies to outputs that are not encoded. **This callback must be used with multi-track raw outputs.** Param idx: The audio track index Param frames: The raw audio frames void (\*[obs\_output\_info](#c.obs_output_info "obs_output_info") .encoded\_packet)(void \*data, struct [encoder\_packet](reference-encoders#c.encoder_packet "encoder_packet") \*packet)[](#c.obs_output_info.encoded_packet "Link to this definition") 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. If NULL, an encoder error occurred, and the output should call [`obs_output_signal_stop()`](#c.obs_output_signal_stop "obs_output_signal_stop") with the error code **OBS\_OUTPUT\_ENCODE\_ERROR**. void (\*[obs\_output\_info](#c.obs_output_info "obs_output_info") .update)(void \*data, [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*settings)[](#c.obs_output_info.update "Link to this definition") Updates the settings for this output. (Optional) Param settings: New settings for this output void (\*[obs\_output\_info](#c.obs_output_info "obs_output_info") .get\_defaults)([obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*settings)[](#c.obs_output_info.get_defaults "Link to this definition") void (\*[obs\_output\_info](#c.obs_output_info "obs_output_info") .get\_defaults2)(void \*type\_data, [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*settings)[](#c.obs_output_info.get_defaults2 "Link to this definition") 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 [obs\_properties\_t](reference-properties#c.obs_properties_t "obs_properties_t") \*(\*[obs\_output\_info](#c.obs_output_info "obs_output_info") .get\_properties)(void \*data)[](#c.obs_output_info.get_properties "Link to this definition") [obs\_properties\_t](reference-properties#c.obs_properties_t "obs_properties_t") \*(\*[obs\_output\_info](#c.obs_output_info "obs_output_info") .get\_properties2)(void \*data, void \*type\_data)[](#c.obs_output_info.get_properties2 "Link to this definition") Gets the property information of this output. (Optional) Return: The properties of the output void (\*[obs\_output\_info](#c.obs_output_info "obs_output_info") .unused1)(void \*data)[](#c.obs_output_info.unused1 "Link to this definition") This callback is no longer used. uint64\_t (\*[obs\_output\_info](#c.obs_output_info "obs_output_info") .get\_total\_bytes)(void \*data)[](#c.obs_output_info.get_total_bytes "Link to this definition") Returns the number of total bytes processed by this output. (Optional) Return: Total bytes processed by this output since it started int (\*[obs\_output\_info](#c.obs_output_info "obs_output_info") .get\_dropped\_frames)(void \*data)[](#c.obs_output_info.get_dropped_frames "Link to this definition") Returns the number of dropped frames. (Optional) Return: Number of dropped frames due to network congestion by this output since it started void \*[obs\_output\_info](#c.obs_output_info "obs_output_info") .type\_data[](#c.obs_output_info.type_data "Link to this definition") void (\*[obs\_output\_info](#c.obs_output_info "obs_output_info") .free\_type\_data)(void \*type\_data)[](#c.obs_output_info.free_type_data "Link to this definition") 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) float (\*[obs\_output\_info](#c.obs_output_info "obs_output_info") .get\_congestion)(void \*data)[](#c.obs_output_info.get_congestion "Link to this definition") 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) int (\*[obs\_output\_info](#c.obs_output_info "obs_output_info") .get\_connect\_time\_ms)(void \*data)[](#c.obs_output_info.get_connect_time_ms "Link to this definition") 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 const char \*[obs\_output\_info](#c.obs_output_info "obs_output_info") .encoded\_video\_codecs[](#c.obs_output_info.encoded_video_codecs "Link to this definition") const char \*[obs\_output\_info](#c.obs_output_info "obs_output_info") .encoded\_audio\_codecs[](#c.obs_output_info.encoded_audio_codecs "Link to this definition") This variable specifies which codecs are supported by an encoded output, separated by semicolon. Required if **OBS\_OUTPUT\_SERVICE** flag is set, otherwise recommended. const char \*[obs\_output\_info](#c.obs_output_info "obs_output_info") .protocols[](#c.obs_output_info.protocols "Link to this definition") This variable specifies which protocols are supported by an output, separated by semicolon. Required only if **OBS\_OUTPUT\_SERVICE** flag is set. Added in version 29.1. Output Signals[](#output-signals "Link to this heading") ---------------------------------------------------------- **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 - Successfully 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 > > OBS\_OUTPUT\_ENCODE\_ERROR - Encoder error **pause** (ptr output) > Called when the output has been paused. **unpause** (ptr output) > Called when the output has been unpaused. **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[](#general-output-functions "Link to this heading") ------------------------------------------------------------------------------ void obs\_register\_output(struct [obs\_output\_info](#c.obs_output_info "obs_output_info") \*info)[](#c.obs_register_output "Link to this definition") Registers an output type. Typically used in [`obs_module_load()`](reference-modules#c.obs_module_load "obs_module_load") or in the program’s initialization phase. * * * const char \*obs\_output\_get\_display\_name(const char \*id)[](#c.obs_output_get_display_name "Link to this definition") Calls the [`obs_output_info.get_name`](#c.obs_output_info.get_name "obs_output_info.get_name") callback to get the translated display name of an output type. Parameters: * **id** – The output type string identifier Returns: The translated display name of an output type * * * [obs\_output\_t](#c.obs_output_t "obs_output_t") \*obs\_output\_create(const char \*id, const char \*name, [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*settings, [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*hotkey\_data)[](#c.obs_output_create "Link to this definition") 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. Parameters: * **id** – The output type string identifier * **name** – The desired name of the output. If this is not unique, it will be made to be unique * **settings** – The settings for the output, or _NULL_ if none * **hotkey\_data** – Saved hotkey data for the output, or _NULL_ if none Returns: A reference to the newly created output, or _NULL_ if failed * * * [obs\_output\_t](#c.obs_output_t "obs_output_t") \*obs\_output\_get\_ref([obs\_output\_t](#c.obs_output_t "obs_output_t") \*output)[](#c.obs_output_get_ref "Link to this definition") Returns an incremented reference if still valid, otherwise returns _NULL_. Release with [`obs_output_release()`](#c.obs_output_release "obs_output_release") . * * * void obs\_output\_release([obs\_output\_t](#c.obs_output_t "obs_output_t") \*output)[](#c.obs_output_release "Link to this definition") Releases a reference to an output. When the last reference is released, the output is destroyed. * * * [obs\_weak\_output\_t](#c.obs_weak_output_t "obs_weak_output_t") \*obs\_output\_get\_weak\_output([obs\_output\_t](#c.obs_output_t "obs_output_t") \*output)[](#c.obs_output_get_weak_output "Link to this definition") [obs\_output\_t](#c.obs_output_t "obs_output_t") \*obs\_weak\_output\_get\_output([obs\_weak\_output\_t](#c.obs_weak_output_t "obs_weak_output_t") \*weak)[](#c.obs_weak_output_get_output "Link to this definition") 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_. * * * void obs\_weak\_output\_addref([obs\_weak\_output\_t](#c.obs_weak_output_t "obs_weak_output_t") \*weak)[](#c.obs_weak_output_addref "Link to this definition") void obs\_weak\_output\_release([obs\_weak\_output\_t](#c.obs_weak_output_t "obs_weak_output_t") \*weak)[](#c.obs_weak_output_release "Link to this definition") Adds/releases a weak reference to an output. * * * bool obs\_weak\_output\_references\_output([obs\_weak\_output\_t](#c.obs_weak_output_t "obs_weak_output_t") \*weak, [obs\_output\_t](#c.obs_output_t "obs_output_t") \*output)[](#c.obs_weak_output_references_output "Link to this definition") Compares a weak output reference with an output. Returns: Whether the weak output reference ties back to the specified output * * * const char \*obs\_output\_get\_name(const [obs\_output\_t](#c.obs_output_t "obs_output_t") \*output)[](#c.obs_output_get_name "Link to this definition") Returns: The name of the output * * * const char \*obs\_output\_get\_id(const [obs\_output\_t](#c.obs_output_t "obs_output_t") \*output)[](#c.obs_output_get_id "Link to this definition") Returns: The output’s type identifier string * * * bool obs\_output\_start([obs\_output\_t](#c.obs_output_t "obs_output_t") \*output)[](#c.obs_output_start "Link to this definition") Starts the output. Returns: _true_ if output successfully started, _false_ otherwise. If the output failed to start, [`obs_output_get_last_error()`](#c.obs_output_get_last_error "obs_output_get_last_error") may contain a specific error string related to the reason * * * void obs\_output\_stop([obs\_output\_t](#c.obs_output_t "obs_output_t") \*output)[](#c.obs_output_stop "Link to this definition") 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 [Output Signals](#output-signal-handler-reference) for more information on output signals. * * * void obs\_output\_set\_delay([obs\_output\_t](#c.obs_output_t "obs_output_t") \*output, uint32\_t delay\_sec, uint32\_t flags)[](#c.obs_output_set_delay "Link to this definition") 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. Parameters: * **delay\_sec** – Amount to delay the output, in seconds * **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 * * * uint32\_t obs\_output\_get\_delay(const [obs\_output\_t](#c.obs_output_t "obs_output_t") \*output)[](#c.obs_output_get_delay "Link to this definition") Gets the currently set delay value, in seconds. * * * uint32\_t obs\_output\_get\_active\_delay(const [obs\_output\_t](#c.obs_output_t "obs_output_t") \*output)[](#c.obs_output_get_active_delay "Link to this definition") 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. * * * void obs\_output\_force\_stop([obs\_output\_t](#c.obs_output_t "obs_output_t") \*output)[](#c.obs_output_force_stop "Link to this definition") Attempts to get the output to stop immediately without waiting for data to send. * * * bool obs\_output\_active(const [obs\_output\_t](#c.obs_output_t "obs_output_t") \*output)[](#c.obs_output_active "Link to this definition") Returns: _true_ if the output is currently active, _false_ otherwise * * * [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*obs\_output\_defaults(const char \*id)[](#c.obs_output_defaults "Link to this definition") Returns: An incremented reference to the output’s default settings. Release with [`obs_data_release()`](reference-settings#c.obs_data_release "obs_data_release") . * * * [obs\_properties\_t](reference-properties#c.obs_properties_t "obs_properties_t") \*obs\_output\_properties(const [obs\_output\_t](#c.obs_output_t "obs_output_t") \*output)[](#c.obs_output_properties "Link to this definition") [obs\_properties\_t](reference-properties#c.obs_properties_t "obs_properties_t") \*obs\_get\_output\_properties(const char \*id)[](#c.obs_get_output_properties "Link to this definition") 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. Returns: The properties list for a specific existing output. Free with [`obs_properties_destroy()`](reference-properties#c.obs_properties_destroy "obs_properties_destroy") * * * void obs\_output\_update([obs\_output\_t](#c.obs_output_t "obs_output_t") \*output, [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*settings)[](#c.obs_output_update "Link to this definition") Updates the settings for this output context. * * * bool obs\_output\_can\_pause(const [obs\_output\_t](#c.obs_output_t "obs_output_t") \*output)[](#c.obs_output_can_pause "Link to this definition") Returns: _true_ if the output can be paused, _false_ otherwise * * * bool obs\_output\_pause([obs\_output\_t](#c.obs_output_t "obs_output_t") \*output, bool pause)[](#c.obs_output_pause "Link to this definition") Pause an output (if supported by the output). Returns: _true_ if the output was paused successfully, _false_ otherwise * * * bool obs\_output\_paused(const [obs\_output\_t](#c.obs_output_t "obs_output_t") \*output)[](#c.obs_output_paused "Link to this definition") Returns: _true_ if the output is paused, _false_ otherwise * * * [obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*obs\_output\_get\_settings(const [obs\_output\_t](#c.obs_output_t "obs_output_t") \*output)[](#c.obs_output_get_settings "Link to this definition") Returns: An incremented reference to the output’s settings. Release with [`obs_data_release()`](reference-settings#c.obs_data_release "obs_data_release") . * * * [signal\_handler\_t](reference-libobs-callback#c.signal_handler_t "signal_handler_t") \*obs\_output\_get\_signal\_handler(const [obs\_output\_t](#c.obs_output_t "obs_output_t") \*output)[](#c.obs_output_get_signal_handler "Link to this definition") Returns: The signal handler of the output. Should not be manually freed, as its lifecycle is managed by libobs. * * * [proc\_handler\_t](reference-libobs-callback#c.proc_handler_t "proc_handler_t") \*obs\_output\_get\_proc\_handler(const [obs\_output\_t](#c.obs_output_t "obs_output_t") \*output)[](#c.obs_output_get_proc_handler "Link to this definition") Returns: The procedure handler of the output. Should not be manually freed, as its lifecycle is managed by libobs. * * * void obs\_output\_set\_media([obs\_output\_t](#c.obs_output_t "obs_output_t") \*output, [video\_t](reference-libobs-media-io#c.video_t "video_t") \*video, [audio\_t](reference-libobs-media-io#c.audio_t "audio_t") \*audio)[](#c.obs_output_set_media "Link to this definition") Sets the current video/audio handlers for the output (typically [`obs_get_video()`](reference-core#c.obs_get_video "obs_get_video") and [`obs_get_audio()`](reference-core#c.obs_get_audio "obs_get_audio") ). Only used with raw outputs so they can catch the raw video/audio frames. * * * [video\_t](reference-libobs-media-io#c.video_t "video_t") \*obs\_output\_video(const [obs\_output\_t](#c.obs_output_t "obs_output_t") \*output)[](#c.obs_output_video "Link to this definition") [audio\_t](reference-libobs-media-io#c.audio_t "audio_t") \*obs\_output\_audio(const [obs\_output\_t](#c.obs_output_t "obs_output_t") \*output)[](#c.obs_output_audio "Link to this definition") Gets the current video/audio handlers for the output. * * * void obs\_output\_set\_mixer([obs\_output\_t](#c.obs_output_t "obs_output_t") \*output, size\_t mixer\_idx)[](#c.obs_output_set_mixer "Link to this definition") size\_t obs\_output\_get\_mixer(const [obs\_output\_t](#c.obs_output_t "obs_output_t") \*output)[](#c.obs_output_get_mixer "Link to this definition") Sets/gets the current audio mixer for non-encoded outputs. For multi-track outputs, this would be the equivalent of setting the mask only for the specified mixer index. * * * void obs\_output\_set\_mixers([obs\_output\_t](#c.obs_output_t "obs_output_t") \*output, size\_t mixers)[](#c.obs_output_set_mixers "Link to this definition") size\_t obs\_output\_get\_mixers(const [obs\_output\_t](#c.obs_output_t "obs_output_t") \*output)[](#c.obs_output_get_mixers "Link to this definition") Sets/gets the current audio mixers (via mask) for non-encoded multi-track outputs. If used with single-track outputs, the single-track output will use either the first set mixer track in the bitmask, or the first track if none is set in the bitmask. * * * void obs\_output\_set\_video\_encoder([obs\_output\_t](#c.obs_output_t "obs_output_t") \*output, [obs\_encoder\_t](reference-encoders#c.obs_encoder_t "obs_encoder_t") \*encoder)[](#c.obs_output_set_video_encoder "Link to this definition") void obs\_output\_set\_audio\_encoder([obs\_output\_t](#c.obs_output_t "obs_output_t") \*output, [obs\_encoder\_t](reference-encoders#c.obs_encoder_t "obs_encoder_t") \*encoder, size\_t idx)[](#c.obs_output_set_audio_encoder "Link to this definition") Sets the video/audio encoders for an encoded output. Parameters: * **encoder** – The video/audio encoder * **idx** – The audio encoder index if the output supports multiple audio streams at once * * * [obs\_encoder\_t](reference-encoders#c.obs_encoder_t "obs_encoder_t") \*obs\_output\_get\_video\_encoder(const [obs\_output\_t](#c.obs_output_t "obs_output_t") \*output)[](#c.obs_output_get_video_encoder "Link to this definition") [obs\_encoder\_t](reference-encoders#c.obs_encoder_t "obs_encoder_t") \*obs\_output\_get\_audio\_encoder(const [obs\_output\_t](#c.obs_output_t "obs_output_t") \*output, size\_t idx)[](#c.obs_output_get_audio_encoder "Link to this definition") Gets the video/audio encoders for an encoded output. Parameters: * **idx** – The audio encoder index if the output supports multiple audio streams at once Returns: The video/audio encoder. The reference is not incremented * * * void obs\_output\_set\_service([obs\_output\_t](#c.obs_output_t "obs_output_t") \*output, [obs\_service\_t](reference-services#c.obs_service_t "obs_service_t") \*service)[](#c.obs_output_set_service "Link to this definition") [obs\_service\_t](reference-services#c.obs_service_t "obs_service_t") \*obs\_output\_get\_service(const [obs\_output\_t](#c.obs_output_t "obs_output_t") \*output)[](#c.obs_output_get_service "Link to this definition") Sets/gets the service for outputs that require services (such as RTMP outputs). _obs\_output\_get\_service_ does not return an incremented reference. * * * void obs\_output\_set\_reconnect\_settings([obs\_output\_t](#c.obs_output_t "obs_output_t") \*output, int retry\_count, int retry\_sec);[](#c.obs_output_set_reconnect_settings "Link to this definition") Sets the auto-reconnect settings for outputs that support it. The retry time will double on each retry to prevent overloading services. Parameters: * **retry\_count** – Maximum retry count. Set to 0 to disable reconnecting * **retry\_sec** – Starting retry wait duration, in seconds * * * uint64\_t obs\_output\_get\_total\_bytes(const [obs\_output\_t](#c.obs_output_t "obs_output_t") \*output)[](#c.obs_output_get_total_bytes "Link to this definition") Returns: Total bytes sent/processed * * * int obs\_output\_get\_frames\_dropped(const [obs\_output\_t](#c.obs_output_t "obs_output_t") \*output)[](#c.obs_output_get_frames_dropped "Link to this definition") Returns: Number of frames that were dropped due to network congestion * * * int obs\_output\_get\_total\_frames(const [obs\_output\_t](#c.obs_output_t "obs_output_t") \*output)[](#c.obs_output_get_total_frames "Link to this definition") Returns: Total frames sent/processed * * * void obs\_output\_set\_preferred\_size([obs\_output\_t](#c.obs_output_t "obs_output_t") \*output, uint32\_t width, uint32\_t height)[](#c.obs_output_set_preferred_size "Link to this definition") 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. * * * uint32\_t obs\_output\_get\_width(const [obs\_output\_t](#c.obs_output_t "obs_output_t") \*output)[](#c.obs_output_get_width "Link to this definition") uint32\_t obs\_output\_get\_height(const [obs\_output\_t](#c.obs_output_t "obs_output_t") \*output)[](#c.obs_output_get_height "Link to this definition") Returns: The width/height of the output * * * void obs\_output\_output\_caption\_text1([obs\_output\_t](#c.obs_output_t "obs_output_t") \*output, const char \*text)[](#c.obs_output_output_caption_text1 "Link to this definition") void obs\_output\_output\_caption\_text2([obs\_output\_t](#c.obs_output_t "obs_output_t") \*output, const char \*text, double display\_duration)[](#c.obs_output_output_caption_text2 "Link to this definition") Outputs captions from the specified text input. _text1_ is the same as _text2_, except that the _display\_duration_ is hardcoded to 2.0 seconds. _display\_duration_ represents the minimum quantity of time that a given caption can be displayed for before moving onto the next caption in the queue. * * * float obs\_output\_get\_congestion([obs\_output\_t](#c.obs_output_t "obs_output_t") \*output)[](#c.obs_output_get_congestion "Link to this definition") Returns: 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 * * * int obs\_output\_get\_connect\_time\_ms([obs\_output\_t](#c.obs_output_t "obs_output_t") \*output)[](#c.obs_output_get_connect_time_ms "Link to this definition") Returns: How long the output took to connect to a server, in milliseconds * * * bool obs\_output\_reconnecting(const [obs\_output\_t](#c.obs_output_t "obs_output_t") \*output)[](#c.obs_output_reconnecting "Link to this definition") Returns: _true_ if the output is currently reconnecting to a server, _false_ otherwise * * * const char \*obs\_output\_get\_supported\_video\_codecs(const [obs\_output\_t](#c.obs_output_t "obs_output_t") \*output)[](#c.obs_output_get_supported_video_codecs "Link to this definition") const char \*obs\_get\_output\_supported\_video\_codecs(const char \*id)[](#c.obs_get_output_supported_video_codecs "Link to this definition") const char \*obs\_output\_get\_supported\_audio\_codecs(const [obs\_output\_t](#c.obs_output_t "obs_output_t") \*output)[](#c.obs_output_get_supported_audio_codecs "Link to this definition") const char \*obs\_get\_output\_supported\_audio\_codecs(const char \*id)[](#c.obs_get_output_supported_audio_codecs "Link to this definition") Returns: Supported video/audio codecs of an encoded output, separated by semicolon Added in version 29.1: [`obs_get_output_supported_video_codecs()`](#c.obs_get_output_supported_video_codecs "obs_get_output_supported_video_codecs") and [`obs_get_output_supported_audio_codecs()`](#c.obs_get_output_supported_audio_codecs "obs_get_output_supported_audio_codecs") * * * uint32\_t obs\_output\_get\_flags(const [obs\_output\_t](#c.obs_output_t "obs_output_t") \*output)[](#c.obs_output_get_flags "Link to this definition") uint32\_t obs\_get\_output\_flags(const char \*id)[](#c.obs_get_output_flags "Link to this definition") Returns: The output capability flags * * * const char \*obs\_output\_get\_protocols(const [obs\_output\_t](#c.obs_output_t "obs_output_t") \*output)[](#c.obs_output_get_protocols "Link to this definition") Returns: Supported protocols, separated by semicolon. Always NULL if the output is not **OBS\_OUTPUT\_SERVICE**. Added in version 29.1. * * * bool obs\_is\_output\_protocol\_registered(const char \*protocol)[](#c.obs_is_output_protocol_registered "Link to this definition") Check if one of the registered output use the given protocol. Returns: A boolean showing if an output with the given protocol is registered Added in version 29.1. * * * bool obs\_enum\_output\_protocols(size\_t idx, char \*\*protocol)[](#c.obs_enum_output_protocols "Link to this definition") Enumerates all registered protocol. Added in version 29.1. * * * void obs\_enum\_output\_types\_with\_protocol(const char \*protocol, void \*data, bool (\*enum\_cb)(void \*data, const char \*id))[](#c.obs_enum_output_types_with_protocol "Link to this definition") Enumerates through a callback all available output types for the given protocol. Parameters: * **protocol** – Protocol of the outputs to enumerate * **data** – Data passed to the callback * **enum\_cb** – Callback used when a matching output is found, the id of the output is passed to the callback Returns: When all outputs are enumerated or if the callback return _false_ Added in version 29.1. * * * void obs\_output\_add\_packet\_callback(obs\_output\_t \*output, void (\*packet\_cb)(obs\_output\_t \*output, struct encoder\_packet \*pkt, struct encoder\_packet\_time \*pkt\_time, void \*param), void \*param) Register a packet callback function for the output. The callback is invoked for each compressed packet just before sending to the service. This packet callback mechanism is the preferred method for all packet-level processing that is not required to be implemented in libobs. Any reallocation of the packet buffer, if necessary, must be done with functions in libobsutilbmem.h, otherwise a memory leak may occur. Never use memset() to clear the packet buffer, as the buffer data is needed for subsequent callback processing. Parameters: * **output** – The output to register the packet\_cb() function against * **packet\_cb** – Function pointer to the callback function * **param** – Data passed to the callback Returns: When the callback is added packet\_cb() arguments: :param output: The output associated with the invoked callback function :param pkt: Compressed data packet (audio or video) :param pkt\_time: encoder\_packet\_time structure associated with the data packet :param param: Data passed to the callback Added in version 31.0. * * * void obs\_output\_remove\_packet\_callback(obs\_output\_t \*output, void (\*packet\_cb)(obs\_output\_t \*output, struct encoder\_packet \*pkt, struct encoder\_packet\_time \*pkt\_time, void \*param), void \*param) Remove a packet callback function for the output, that had been previously registered with obs\_output\_add\_packet\_callback(). Parameters: * **output** – The output to remove the packet\_cb() function against * **packet\_cb** – Function pointer to the callback function * **param** – Data passed to the callback Returns: When the callback is removed Added in version 31.0. Functions used by outputs[](#functions-used-by-outputs "Link to this heading") -------------------------------------------------------------------------------- void obs\_output\_set\_last\_error([obs\_output\_t](#c.obs_output_t "obs_output_t") \*output, const char \*message)[](#c.obs_output_set_last_error "Link to this definition") const char \*obs\_output\_get\_last\_error([obs\_output\_t](#c.obs_output_t "obs_output_t") \*output)[](#c.obs_output_get_last_error "Link to this definition") Sets/gets the translated error message that is presented to a user in case of disconnection, inability to connect, etc. * * * void obs\_output\_set\_video\_conversion([obs\_output\_t](#c.obs_output_t "obs_output_t") \*output, const struct video\_scale\_info \*conversion)[](#c.obs_output_set_video_conversion "Link to this definition") const struct video\_scale\_info \*obs\_output\_get\_video\_conversion([obs\_output\_t](#c.obs_output_t "obs_output_t") \*output)[](#c.obs_output_get_video_conversion "Link to this definition") Optionally sets/gets the video conversion information. Only used by raw outputs. Added in version 29.1: [`obs_output_get_video_conversion()`](#c.obs_output_get_video_conversion "obs_output_get_video_conversion") Relevant data types used with this function: enum video\_format { VIDEO\_FORMAT\_NONE, /\* planar 4:2:0 formats \*/ VIDEO\_FORMAT\_I420, /\* three-plane \*/ VIDEO\_FORMAT\_NV12, /\* two-plane, luma and packed chroma \*/ /\* packed 4:2:2 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, /\* more packed uncompressed formats \*/ VIDEO\_FORMAT\_BGR3, /\* planar 4:2:2 \*/ VIDEO\_FORMAT\_I422, /\* planar 4:2:0 with alpha \*/ VIDEO\_FORMAT\_I40A, /\* planar 4:2:2 with alpha \*/ VIDEO\_FORMAT\_I42A, /\* planar 4:4:4 with alpha \*/ VIDEO\_FORMAT\_YUVA, /\* packed 4:4:4 with alpha \*/ VIDEO\_FORMAT\_AYUV, /\* planar 4:2:0 format, 10 bpp \*/ VIDEO\_FORMAT\_I010, /\* three-plane \*/ VIDEO\_FORMAT\_P010, /\* two-plane, luma and packed chroma \*/ /\* planar 4:2:2 format, 10 bpp \*/ VIDEO\_FORMAT\_I210, /\* planar 4:4:4 format, 12 bpp \*/ VIDEO\_FORMAT\_I412, /\* planar 4:4:4:4 format, 12 bpp \*/ VIDEO\_FORMAT\_YA2L, /\* planar 4:2:2 format, 16 bpp \*/ VIDEO\_FORMAT\_P216, /\* two-plane, luma and packed chroma \*/ /\* planar 4:4:4 format, 16 bpp \*/ VIDEO\_FORMAT\_P416, /\* two-plane, luma and packed chroma \*/ /\* packed 4:2:2 format, 10 bpp \*/ VIDEO\_FORMAT\_V210, /\* packed uncompressed 10-bit format \*/ VIDEO\_FORMAT\_R10L, }; enum video\_colorspace { VIDEO\_CS\_DEFAULT, VIDEO\_CS\_601, VIDEO\_CS\_709, VIDEO\_CS\_SRGB, VIDEO\_CS\_2100\_PQ, VIDEO\_CS\_2100\_HLG, }; 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; }; * * * void obs\_output\_set\_audio\_conversion([obs\_output\_t](#c.obs_output_t "obs_output_t") \*output, const struct [audio\_convert\_info](reference-libobs-media-io#c.audio_convert_info "audio_convert_info") \*conversion)[](#c.obs_output_set_audio_conversion "Link to this definition") Optionally sets the audio conversion information. Only used by raw outputs. Relevant data types used with this function: 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\_4POINT0, 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; }; * * * bool obs\_output\_can\_begin\_data\_capture(const [obs\_output\_t](#c.obs_output_t "obs_output_t") \*output, int flags)[](#c.obs_output_can_begin_data_capture "Link to this definition") Determines whether video/audio capture (encoded or raw) is able to start. Call this before initializing any output state to ensure that the output can start. Parameters: * **output** – The output * **flags** – Reserved. Set this to 0. Returns: _true_ if data capture can begin * * * bool obs\_output\_initialize\_encoders([obs\_output\_t](#c.obs_output_t "obs_output_t") \*output, int flags)[](#c.obs_output_initialize_encoders "Link to this definition") Initializes any encoders/services associated with the output. This must be called for encoded outputs before calling [`obs_output_begin_data_capture()`](#c.obs_output_begin_data_capture "obs_output_begin_data_capture") . Parameters: * **output** – The output * **flags** – Reserved. Set this to 0. Returns: _true_ if successful, _false_ otherwise * * * bool obs\_output\_begin\_data\_capture([obs\_output\_t](#c.obs_output_t "obs_output_t") \*output, int flags)[](#c.obs_output_begin_data_capture "Link to this definition") 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. Parameters: * **output** – The output * **flags** – Reserved. Set this to 0. Returns: _true_ if successful, _false_ otherwise. Typically the return value does not need to be checked if `obs_output_can_begin_data_capture2()` was called * * * void obs\_output\_end\_data\_capture([obs\_output\_t](#c.obs_output_t "obs_output_t") \*output)[](#c.obs_output_end_data_capture "Link to this definition") 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 [Output Signals](#output-signal-handler-reference) for more information on output signals. * * * void obs\_output\_signal\_stop([obs\_output\_t](#c.obs_output_t "obs_output_t") \*output, int code)[](#c.obs_output_signal_stop "Link to this definition") 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 [Output Signals](#output-signal-handler-reference) for more information on output signals. [`obs_output_set_last_error()`](#c.obs_output_set_last_error "obs_output_set_last_error") may be used in conjunction with these error codes to optionally relay more detailed error information to the user Parameters: * **code** – Can be one of the following values: OBS\_OUTPUT\_SUCCESS - Successfully 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 * * * uint64\_t obs\_output\_get\_pause\_offset([obs\_output\_t](#c.obs_output_t "obs_output_t") \*output)[](#c.obs_output_get_pause_offset "Link to this definition") Returns the current pause offset of the output. Used with raw outputs to calculate system timestamps when using calculated timestamps (see FFmpeg output for an example). --- # Memory Management — OBS Studio 31.0.2 documentation * [](index) * [Platform/Utility API Reference (libobs/util)](reference-libobs-util) * Memory Management * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/reference-libobs-util-bmem.rst) [Previous](reference-libobs-util-base "Logging") [Next](reference-libobs-util-circlebuf "Circular Buffers") * * * Memory Management[](#memory-management "Link to this heading") ================================================================ Various functions and helpers used for memory management. #include Memory Functions[](#memory-functions "Link to this heading") -------------------------------------------------------------- void \*bmalloc(size\_t size)[](#c.bmalloc "Link to this definition") Allocates memory and increases the memory leak counter. * * * void \*brealloc(void \*ptr, size\_t size)[](#c.brealloc "Link to this definition") Reallocates memory. Use only with memory that’s been allocated by [`bmalloc()`](#c.bmalloc "bmalloc") . * * * void bfree(void \*ptr)[](#c.bfree "Link to this definition") Frees memory allocated with [`bmalloc()`](#c.bmalloc "bmalloc") . * * * long bnum\_allocs(void)[](#c.bnum_allocs "Link to this definition") Returns current number of active allocations. * * * void \*bmemdup(const void \*ptr, size\_t size)[](#c.bmemdup "Link to this definition") Duplicates memory. * * * void \*bzalloc(size\_t size)[](#c.bzalloc "Link to this definition") Inline function that allocates zeroed memory. * * * char \*bstrdup\_n(const char \*str, size\_t n)[](#c.bstrdup_n "Link to this definition") wchar\_t \*bwstrdup\_n(const wchar\_t \*str, size\_t n)[](#c.bwstrdup_n "Link to this definition") Duplicates a string of _n_ bytes and automatically zero-terminates it. * * * char \*bstrdup(const char \*str)[](#c.bstrdup "Link to this definition") wchar\_t \*bwstrdup(const wchar\_t \*str)[](#c.bwstrdup "Link to this definition") Duplicates a string. --- # Config Files — OBS Studio 31.0.2 documentation * [](index) * [Platform/Utility API Reference (libobs/util)](reference-libobs-util) * Config Files * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/reference-libobs-util-config-file.rst) [Previous](reference-libobs-util-circlebuf "Circular Buffers") [Next](reference-libobs-util-darray "Dynamic Arrays") * * * Config Files[](#config-files "Link to this heading") ====================================================== The configuration file functions are a simple implementation of the INI file format, with the addition of default values. #include type config\_t[](#c.config_t "Link to this definition") Config File Functions[](#config-file-functions "Link to this heading") ------------------------------------------------------------------------ [config\_t](#c.config_t "config_t") \*config\_create(const char \*file)[](#c.config_create "Link to this definition") Creates a new configuration object and associates it with the specified file name. Parameters: * **file** – Path to the new configuration file Returns: A new configuration file object * * * int config\_open([config\_t](#c.config_t "config_t") \*\*config, const char \*file, enum config\_open\_type open\_type)[](#c.config_open "Link to this definition") Opens a configuration file. Parameters: * **config** – Pointer that receives a pointer to a new configuration file object (if successful) * **file** – Path to the configuration file * **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. Returns: Can return the following values: * CONFIG\_SUCCESS - Successful * CONFIG\_FILENOTFOUND - File not found * CONFIG\_ERROR - Generic error * * * int config\_open\_string([config\_t](#c.config_t "config_t") \*\*config, const char \*str)[](#c.config_open_string "Link to this definition") Opens configuration data via a string rather than a file. Parameters: * **config** – Pointer that receives a pointer to a new configuration file object (if successful) * **str** – Configuration string Returns: Can return the following values: * CONFIG\_SUCCESS - Successful * CONFIG\_FILENOTFOUND - File not found * CONFIG\_ERROR - Generic error * * * int config\_save([config\_t](#c.config_t "config_t") \*config)[](#c.config_save "Link to this definition") Saves configuration data to a file (if associated with a file). Parameters: * **config** – Configuration object Returns: Can return the following values: * CONFIG\_SUCCESS - Successful * CONFIG\_FILENOTFOUND - File not found * CONFIG\_ERROR - Generic error * * * int config\_save\_safe([config\_t](#c.config_t "config_t") \*config, const char \*temp\_ext, const char \*backup\_ext)[](#c.config_save_safe "Link to this definition") Saves configuration data and minimizes overwrite corruption risk. Saves the file with the file name Parameters: * **config** – Configuration object * **temp\_ext** – Temporary extension for the new file * **backup\_ext** – Backup extension for the old file. Can be _NULL_ if no backup is desired. Returns: Can return the following values: * CONFIG\_SUCCESS - Successful * CONFIG\_FILENOTFOUND - File not found * CONFIG\_ERROR - Generic error * * * void config\_close([config\_t](#c.config_t "config_t") \*config)[](#c.config_close "Link to this definition") Closes the configuration object. Parameters: * **config** – Configuration object * * * size\_t config\_num\_sections([config\_t](#c.config_t "config_t") \*config)[](#c.config_num_sections "Link to this definition") Returns the number of sections. Parameters: * **config** – Configuration object Returns: Number of configuration sections * * * const char \*config\_get\_section([config\_t](#c.config_t "config_t") \*config, size\_t idx)[](#c.config_get_section "Link to this definition") Returns a section name based upon its index. Parameters: * **config** – Configuration object * **idx** – Index of the section Returns: The section’s name Set/Get Functions[](#set-get-functions "Link to this heading") ---------------------------------------------------------------- void config\_set\_string([config\_t](#c.config_t "config_t") \*config, const char \*section, const char \*name, const char \*value)[](#c.config_set_string "Link to this definition") Sets a string value. Parameters: * **config** – Configuration object * **section** – The section of the value * **name** – The value name * **value** – The string value * * * void config\_set\_int([config\_t](#c.config_t "config_t") \*config, const char \*section, const char \*name, int64\_t value)[](#c.config_set_int "Link to this definition") Sets an integer value. Parameters: * **config** – Configuration object * **section** – The section of the value * **name** – The value name * **value** – The integer value * * * void config\_set\_uint([config\_t](#c.config_t "config_t") \*config, const char \*section, const char \*name, uint64\_t value)[](#c.config_set_uint "Link to this definition") Sets an unsigned integer value. Parameters: * **config** – Configuration object * **section** – The section of the value * **name** – The value name * **value** – The unsigned integer value * * * void config\_set\_bool([config\_t](#c.config_t "config_t") \*config, const char \*section, const char \*name, bool value)[](#c.config_set_bool "Link to this definition") Sets a boolean value. Parameters: * **config** – Configuration object * **section** – The section of the value * **name** – The value name * **value** – The boolean value * * * void config\_set\_double([config\_t](#c.config_t "config_t") \*config, const char \*section, const char \*name, double value)[](#c.config_set_double "Link to this definition") Sets a floating point value. Parameters: * **config** – Configuration object * **section** – The section of the value * **name** – The value name * **value** – The floating point value * * * const char \*config\_get\_string([config\_t](#c.config_t "config_t") \*config, const char \*section, const char \*name)[](#c.config_get_string "Link to this definition") 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_. Parameters: * **config** – Configuration object * **section** – The section of the value * **name** – The value name Returns: The string value * * * int64\_t config\_get\_int([config\_t](#c.config_t "config_t") \*config, const char \*section, const char \*name)[](#c.config_get_int "Link to this definition") 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. Parameters: * **config** – Configuration object * **section** – The section of the value * **name** – The value name Returns: The integer value * * * uint64\_t config\_get\_uint([config\_t](#c.config_t "config_t") \*config, const char \*section, const char \*name)[](#c.config_get_uint "Link to this definition") 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. Parameters: * **config** – Configuration object * **section** – The section of the value * **name** – The value name Returns: The unsigned integer value * * * bool config\_get\_bool([config\_t](#c.config_t "config_t") \*config, const char \*section, const char \*name)[](#c.config_get_bool "Link to this definition") 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. Parameters: * **config** – Configuration object * **section** – The section of the value * **name** – The value name Returns: The boolean value * * * double config\_get\_double([config\_t](#c.config_t "config_t") \*config, const char \*section, const char \*name)[](#c.config_get_double "Link to this definition") 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. Parameters: * **config** – Configuration object * **section** – The section of the value * **name** – The value name Returns: The floating point value * * * bool config\_remove\_value([config\_t](#c.config_t "config_t") \*config, const char \*section, const char \*name)[](#c.config_remove_value "Link to this definition") Removes a value. Does not remove the default value if any. Parameters: * **config** – Configuration object * **section** – The section of the value * **name** – The value name Default Value Functions[](#default-value-functions "Link to this heading") ---------------------------------------------------------------------------- int config\_open\_defaults([config\_t](#c.config_t "config_t") \*config, const char \*file)[](#c.config_open_defaults "Link to this definition") Opens a file and uses it for default values. Parameters: * **config** – Configuration object * **file** – The file to open for default values * * * void config\_set\_default\_string([config\_t](#c.config_t "config_t") \*config, const char \*section, const char \*name, const char \*value)[](#c.config_set_default_string "Link to this definition") Sets a default string value. Parameters: * **config** – Configuration object * **section** – The section of the value * **name** – The value name * **value** – The string value * * * void config\_set\_default\_int([config\_t](#c.config_t "config_t") \*config, const char \*section, const char \*name, int64\_t value)[](#c.config_set_default_int "Link to this definition") Sets a default integer value. Parameters: * **config** – Configuration object * **section** – The section of the value * **name** – The value name * **value** – The integer value * * * void config\_set\_default\_uint([config\_t](#c.config_t "config_t") \*config, const char \*section, const char \*name, uint64\_t value)[](#c.config_set_default_uint "Link to this definition") Sets a default unsigned integer value. Parameters: * **config** – Configuration object * **section** – The section of the value * **name** – The value name * **value** – The unsigned integer value * * * void config\_set\_default\_bool([config\_t](#c.config_t "config_t") \*config, const char \*section, const char \*name, bool value)[](#c.config_set_default_bool "Link to this definition") Sets a default boolean value. Parameters: * **config** – Configuration object * **section** – The section of the value * **name** – The value name * **value** – The boolean value * * * void config\_set\_default\_double([config\_t](#c.config_t "config_t") \*config, const char \*section, const char \*name, double value)[](#c.config_set_default_double "Link to this definition") Sets a default floating point value. Parameters: * **config** – Configuration object * **section** – The section of the value * **name** – The value name * **value** – The floating point value * * * const char \*config\_get\_default\_string([config\_t](#c.config_t "config_t") \*config, const char \*section, const char \*name)[](#c.config_get_default_string "Link to this definition") Gets a default string value. If there is no default value, it will return _NULL_. Parameters: * **config** – Configuration object * **section** – The section of the value * **name** – The value name Returns: The default string value * * * int64\_t config\_get\_default\_int([config\_t](#c.config_t "config_t") \*config, const char \*section, const char \*name)[](#c.config_get_default_int "Link to this definition") Gets a default integer value. If there is no default value, it will return 0. Parameters: * **config** – Configuration object * **section** – The section of the value * **name** – The value name Returns: The integer value * * * uint64\_t config\_get\_default\_uint([config\_t](#c.config_t "config_t") \*config, const char \*section, const char \*name)[](#c.config_get_default_uint "Link to this definition") Gets a default unsigned integer value. If there is no default value, it will return 0. Parameters: * **config** – Configuration object * **section** – The section of the value * **name** – The value name Returns: The unsigned integer value * * * bool config\_get\_default\_bool([config\_t](#c.config_t "config_t") \*config, const char \*section, const char \*name)[](#c.config_get_default_bool "Link to this definition") Gets a default boolean value. If there is no default value, it will return false. Parameters: * **config** – Configuration object * **section** – The section of the value * **name** – The value name Returns: The boolean value * * * double config\_get\_default\_double([config\_t](#c.config_t "config_t") \*config, const char \*section, const char \*name)[](#c.config_get_default_double "Link to this definition") Gets a default floating point value. If there is no default value, it will return 0.0. Parameters: * **config** – Configuration object * **section** – The section of the value * **name** – The value name Returns: The floating point value * * * bool config\_has\_user\_value([config\_t](#c.config_t "config_t") \*config, const char \*section, const char \*name)[](#c.config_has_user_value "Link to this definition") Returns whether a value is user-set (true) or default/none (false). > param config: > > Configuration object > > param section: > > The section of the value > > param name: > > The value name > > return: > > Whether a user value exists * * * bool config\_has\_default\_value([config\_t](#c.config_t "config_t") \*config, const char \*section, const char \*name)[](#c.config_has_default_value "Link to this definition") Returns whether a value has a default set. > param config: > > Configuration object > > param section: > > The section of the value > > param name: > > The value name > > return: > > Whether a user value exists --- # Double-Ended Queue — OBS Studio 31.0.2 documentation * [](index) * [Platform/Utility API Reference (libobs/util)](reference-libobs-util) * Double-Ended Queue * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/reference-libobs-util-deque.rst) [Previous](reference-libobs-util-darray "Dynamic Arrays") [Next](reference-libobs-util-dstr "Dynamic Strings And String Helpers") * * * Double-Ended Queue[](#double-ended-queue "Link to this heading") ================================================================== A double-ended queue (deque) that will automatically increase in size as necessary as data is pushed to the front or back. #include Added in version 30.1. Deque Structure (struct deque)[](#deque-structure-struct-deque "Link to this heading") ---------------------------------------------------------------------------------------- struct deque[](#c.deque "Link to this definition") void \*[deque](#c.deque "deque") .data[](#c.deque.data "Link to this definition") size\_t [deque](#c.deque "deque") .size[](#c.deque.size "Link to this definition") size\_t [deque](#c.deque "deque") .start\_pos[](#c.deque.start_pos "Link to this definition") size\_t [deque](#c.deque "deque") .end\_pos[](#c.deque.end_pos "Link to this definition") size\_t [deque](#c.deque "deque") .capacity[](#c.deque.capacity "Link to this definition") Deque Inline Functions[](#deque-inline-functions "Link to this heading") -------------------------------------------------------------------------- void deque\_init(struct [deque](#c.deque "deque") \*dq)[](#c.deque_init "Link to this definition") Initializes a deque (just zeroes out the entire structure). Parameters: * **dq** – The deque * * * void deque\_free(struct [deque](#c.deque "deque") \*dq)[](#c.deque_free "Link to this definition") Frees a deque. Parameters: * **dq** – The deque * * * void deque\_reserve(struct [deque](#c.deque "deque") \*dq, size\_t capacity)[](#c.deque_reserve "Link to this definition") Reserves a specific amount of buffer space to ensure minimum upsizing. Parameters: * **dq** – The deque * **capacity** – The new capacity, in bytes * * * void deque\_upsize(struct [deque](#c.deque "deque") \*dq, size\_t size)[](#c.deque_upsize "Link to this definition") Sets the current active (not just reserved) size. Any new data is zeroed. Parameters: * **dq** – The deque * **size** – The new size, in bytes * * * void deque\_place(struct [deque](#c.deque "deque") \*dq, size\_t position, const void \*data, size\_t size)[](#c.deque_place "Link to this definition") Places data at a specific positional index (relative to the starting point) within the deque. Parameters: * **dq** – The deque * **position** – Positional index relative to starting point * **data** – Data to insert * **size** – Size of data to insert * * * void deque\_push\_back(struct [deque](#c.deque "deque") \*dq, const void \*data, size\_t size)[](#c.deque_push_back "Link to this definition") Pushes data to the end of the deque. Parameters: * **dq** – The deque * **data** – Data * **size** – Size of data * * * void deque\_push\_front(struct [deque](#c.deque "deque") \*dq, const void \*data, size\_t size)[](#c.deque_push_front "Link to this definition") Pushes data to the front of the deque. Parameters: * **dq** – The deque * **data** – Data * **size** – Size of data * * * void deque\_push\_back\_zero(struct [deque](#c.deque "deque") \*dq, size\_t size)[](#c.deque_push_back_zero "Link to this definition") Pushes zeroed data to the end of the deque. Parameters: * **dq** – The deque * **size** – Size * * * void deque\_push\_front\_zero(struct [deque](#c.deque "deque") \*dq, size\_t size)[](#c.deque_push_front_zero "Link to this definition") Pushes zeroed data to the front of the deque. Parameters: * **dq** – The deque * **size** – Size * * * void deque\_peek\_front(struct [deque](#c.deque "deque") \*dq, void \*data, size\_t size)[](#c.deque_peek_front "Link to this definition") Peeks data at the front of the deque. Parameters: * **dq** – The deque * **data** – Buffer to store data in * **size** – Size of data to retrieve * * * void deque\_peek\_back(struct [deque](#c.deque "deque") \*dq, void \*data, size\_t size)[](#c.deque_peek_back "Link to this definition") Peeks data at the back of the deque. Parameters: * **dq** – The deque * **data** – Buffer to store data in * **size** – Size of data to retrieve * * * void deque\_pop\_front(struct [deque](#c.deque "deque") \*dq, void \*data, size\_t size)[](#c.deque_pop_front "Link to this definition") Pops data from the front of the deque. Parameters: * **dq** – The deque * **data** – Buffer to store data in, or _NULL_ * **size** – Size of data to retrieve * * * void deque\_pop\_back(struct [deque](#c.deque "deque") \*dq, void \*data, size\_t size)[](#c.deque_pop_back "Link to this definition") Pops data from the back of the deque. Parameters: * **dq** – The deque * **data** – Buffer to store data in, or _NULL_ * **size** – Size of data to retrieve * * * void \*deque\_data(struct [deque](#c.deque "deque") \*dq, size\_t idx)[](#c.deque_data "Link to this definition") Gets a direct pointer to data at a specific positional index within the deque, relative to the starting point. Parameters: * **dq** – The deque * **idx** – Byte index relative to the starting point --- # Dynamic Strings And String Helpers — OBS Studio 31.0.2 documentation * [](index) * [Platform/Utility API Reference (libobs/util)](reference-libobs-util) * Dynamic Strings And String Helpers * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/reference-libobs-util-dstr.rst) [Previous](reference-libobs-util-deque "Double-Ended Queue") [Next](reference-libobs-util-platform "Platform Helpers") * * * Dynamic Strings And String Helpers[](#dynamic-strings-and-string-helpers "Link to this heading") ================================================================================================== Provides string helper structures/functions (roughly equivalent to std::string). #include Dynamic String Structure (struct dstr)[](#dynamic-string-structure-struct-dstr "Link to this heading") -------------------------------------------------------------------------------------------------------- struct dstr[](#c.dstr "Link to this definition") char \*[dstr](#c.dstr "dstr") .array[](#c.dstr.array "Link to this definition") size\_t [dstr](#c.dstr "dstr") .len[](#c.dstr.len "Link to this definition") size\_t [dstr](#c.dstr "dstr") .capacity[](#c.dstr.capacity "Link to this definition") General String Helper Functions[](#general-string-helper-functions "Link to this heading") -------------------------------------------------------------------------------------------- int astrcmpi(const char \*str1, const char \*str2)[](#c.astrcmpi "Link to this definition") Case insensitive string comparison function. * * * int wstrcmpi(const wchar\_t \*str1, const wchar\_t \*str2)[](#c.wstrcmpi "Link to this definition") Case insensitive wide string comparison function. * * * int astrcmp\_n(const char \*str1, const char \*str2, size\_t n)[](#c.astrcmp_n "Link to this definition") String comparison function for a specific number of characters. * * * int wstrcmp\_n(const wchar\_t \*str1, const wchar\_t \*str2, size\_t n)[](#c.wstrcmp_n "Link to this definition") Wide string comparison function for a specific number of characters. * * * int astrcmpi\_n(const char \*str1, const char \*str2, size\_t n)[](#c.astrcmpi_n "Link to this definition") Case insensitive string comparison function for a specific number of characters. * * * int wstrcmpi\_n(const wchar\_t \*str1, const wchar\_t \*str2, size\_t n)[](#c.wstrcmpi_n "Link to this definition") Case insensitive wide string comparison function for a specific number of characters. * * * char \*astrstri(const char \*str, const char \*find)[](#c.astrstri "Link to this definition") Case insensitive version of strstr. * * * wchar\_t \*wstrstri(const wchar\_t \*str, const wchar\_t \*find)[](#c.wstrstri "Link to this definition") Case insensitive version of wcsstr. * * * char \*strdepad(char \*str)[](#c.strdepad "Link to this definition") Removes padding characters (tab, space, CR, LF) from the front and end of a string. * * * wchar\_t \*wcsdepad(wchar\_t \*str)[](#c.wcsdepad "Link to this definition") Removes padding characters (tab, space, CR, LF) from the front and end of a wide string. * * * char \*\*strlist\_split(const char \*str, char split\_ch, bool include\_empty)[](#c.strlist_split "Link to this definition") Splits a string in to a list of multiple sub-strings, terminated by `NULL`. If `split_ch` does not exist in the string, the first sub-string will be the same as `str`. Free with [`strlist_free()`](#c.strlist_free "strlist_free") . Parameters: * **str** – The string to be split * **split\_ch** – The delimiter * **include\_empty** – If _true_, empty strings caused by having the `split_ch` right next to another will be included in the list. If _false_, they won’t be included. Sample usage: char \*\*words \= strlist\_split("OBS Studio", ' ', false); int count \= 0; for (char \*\*word \= words; \*word; ++word) { count++; blog(LOG\_DEBUG, "%s", \*word); } strlist\_free(words); // count == 2 * * * void strlist\_free(char \*\*strlist)[](#c.strlist_free "Link to this definition") Frees a string list created with [`strlist_split()`](#c.strlist_split "strlist_split") . * * * Dynamic String Functions[](#dynamic-string-functions "Link to this heading") ------------------------------------------------------------------------------ void dstr\_init(struct [dstr](#c.dstr "dstr") \*dst)[](#c.dstr_init "Link to this definition") Initializes a dynamic string variable (just zeroes the variable). Parameters: * **dst** – Dynamic string to initialize * * * void dstr\_init\_move(struct [dstr](#c.dstr "dstr") \*dst, struct [dstr](#c.dstr "dstr") \*src)[](#c.dstr_init_move "Link to this definition") Moves a _src_ to _dst_ without copying data and zeroes _src_. Parameters: * **dst** – Destination * **src** – Source * * * void dstr\_init\_move\_array(struct [dstr](#c.dstr "dstr") \*dst, char \*str)[](#c.dstr_init_move_array "Link to this definition") Sets a bmalloc-allocated string as the dynamic string without copying/reallocating. Parameters: * **dst** – Dynamic string to initialize * **str** – bmalloc-allocated string * * * void dstr\_init\_copy(struct [dstr](#c.dstr "dstr") \*dst, const char \*src)[](#c.dstr_init_copy "Link to this definition") Initializes a dynamic string with a copy of a string Parameters: * **dst** – Dynamic string to initialize * **src** – String to copy * * * void dstr\_init\_copy\_dstr(struct [dstr](#c.dstr "dstr") \*dst, const struct [dstr](#c.dstr "dstr") \*src)[](#c.dstr_init_copy_dstr "Link to this definition") Initializes a dynamic string with a copy of another dynamic string Parameters: * **dst** – Dynamic string to initialize * **src** – Dynamic string to copy * * * void dstr\_free(struct [dstr](#c.dstr "dstr") \*dst)[](#c.dstr_free "Link to this definition") Frees a dynamic string. Parameters: * **dst** – Dynamic string * * * void dstr\_copy(struct [dstr](#c.dstr "dstr") \*dst, const char \*array)[](#c.dstr_copy "Link to this definition") Copies a string. Parameters: * **dst** – Dynamic string * **array** – String to copy * * * void dstr\_copy\_dstr(struct [dstr](#c.dstr "dstr") \*dst, const struct [dstr](#c.dstr "dstr") \*src)[](#c.dstr_copy_dstr "Link to this definition") Copies another dynamic string. Parameters: * **dst** – Dynamic string * **src** – Dynamic string to copy * * * void dstr\_ncopy(struct [dstr](#c.dstr "dstr") \*dst, const char \*array, const size\_t len)[](#c.dstr_ncopy "Link to this definition") Copies a specific number of characters from a string. Parameters: * **dst** – Dynamic string * **array** – String to copy * **len** – Number of characters to copy * * * void dstr\_ncopy\_dstr(struct [dstr](#c.dstr "dstr") \*dst, const struct [dstr](#c.dstr "dstr") \*src, const size\_t len)[](#c.dstr_ncopy_dstr "Link to this definition") Copies a specific number of characters from another dynamic string. Parameters: * **dst** – Dynamic string * **src** – Dynamic string to copy * **len** – Number of characters to copy * * * void dstr\_resize(struct [dstr](#c.dstr "dstr") \*dst, const size\_t num)[](#c.dstr_resize "Link to this definition") Sets the size of the dynamic string. If the new size is bigger than current size, zeroes the new characters. Parameters: * **dst** – Dynamic string * **num** – New size * * * void dstr\_reserve(struct [dstr](#c.dstr "dstr") \*dst, const size\_t num)[](#c.dstr_reserve "Link to this definition") 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. Parameters: * **dst** – Dynamic string * **num** – New reserve size * * * bool dstr\_is\_empty(const struct [dstr](#c.dstr "dstr") \*str)[](#c.dstr_is_empty "Link to this definition") Returns whether the dynamic string is empty. Parameters: * **str** – Dynamic string Returns: _true_ if empty, _false_ otherwise * * * void dstr\_cat(struct [dstr](#c.dstr "dstr") \*dst, const char \*array)[](#c.dstr_cat "Link to this definition") Concatenates a dynamic string. Parameters: * **dst** – Dynamic string * **array** – String to concatenate with * * * void dstr\_cat\_dstr(struct [dstr](#c.dstr "dstr") \*dst, const struct [dstr](#c.dstr "dstr") \*str)[](#c.dstr_cat_dstr "Link to this definition") Concatenates a dynamic string with another dynamic string. Parameters: * **dst** – Dynamic string to concatenate to * **str** – Dynamic string to concatenate with * * * void dstr\_cat\_ch(struct [dstr](#c.dstr "dstr") \*dst, char ch)[](#c.dstr_cat_ch "Link to this definition") Concatenates a dynamic string with a single character. Parameters: * **dst** – Dynamic string to concatenate to * **ch** – Character to concatenate * * * void dstr\_ncat(struct [dstr](#c.dstr "dstr") \*dst, const char \*array, const size\_t len)[](#c.dstr_ncat "Link to this definition") Concatenates a dynamic string with a specific number of characters from a string. Parameters: * **dst** – Dynamic string to concatenate to * **array** – String to concatenate with * **len** – Number of characters to concatenate with * * * void dstr\_ncat\_dstr(struct [dstr](#c.dstr "dstr") \*dst, const struct [dstr](#c.dstr "dstr") \*str, const size\_t len)[](#c.dstr_ncat_dstr "Link to this definition") Concatenates a dynamic string with a specific number of characters from another dynamic string. Parameters: * **dst** – Dynamic string to concatenate to * **str** – Dynamic string to concatenate with * **len** – Number of characters to concatenate with * * * void dstr\_insert(struct [dstr](#c.dstr "dstr") \*dst, const size\_t idx, const char \*array)[](#c.dstr_insert "Link to this definition") Inserts a string in to a dynamic string at a specific index. Parameters: * **dst** – Dynamic string to insert in to * **idx** – Character index to insert at * **array** – String to insert * * * void dstr\_insert\_dstr(struct [dstr](#c.dstr "dstr") \*dst, const size\_t idx, const struct [dstr](#c.dstr "dstr") \*str)[](#c.dstr_insert_dstr "Link to this definition") Inserts another dynamic string in to a dynamic string at a specific index. Parameters: * **dst** – Dynamic string to insert in to * **idx** – Character index to insert at * **str** – Dynamic string to insert * * * void dstr\_insert\_ch(struct [dstr](#c.dstr "dstr") \*dst, const size\_t idx, const char ch)[](#c.dstr_insert_ch "Link to this definition") Inserts a character in to a dynamic string at a specific index. Parameters: * **dst** – Dynamic string to insert in to * **idx** – Character index to insert at * **ch** – Character to insert * * * void dstr\_remove(struct [dstr](#c.dstr "dstr") \*dst, const size\_t idx, const size\_t count)[](#c.dstr_remove "Link to this definition") Removes a specific number of characters starting from a specific index. Parameters: * **dst** – Dynamic string * **idx** – Index to start removing characters at * **count** – Number of characters to remove * * * void dstr\_printf(struct [dstr](#c.dstr "dstr") \*dst, const char \*format, ...)[](#c.dstr_printf "Link to this definition") void dstr\_vprintf(struct [dstr](#c.dstr "dstr") \*dst, const char \*format, va\_list args)[](#c.dstr_vprintf "Link to this definition") Sets a dynamic string to a formatted string. Parameters: * **dst** – Dynamic string * **format** – Format string * * * void dstr\_catf(struct [dstr](#c.dstr "dstr") \*dst, const char \*format, ...)[](#c.dstr_catf "Link to this definition") void dstr\_vcatf(struct [dstr](#c.dstr "dstr") \*dst, const char \*format, va\_list args)[](#c.dstr_vcatf "Link to this definition") Concatenates a dynamic string with a formatted string. Parameters: * **dst** – Dynamic string * **format** – Format string * * * const char \*dstr\_find\_i(const struct [dstr](#c.dstr "dstr") \*str, const char \*find)[](#c.dstr_find_i "Link to this definition") Finds a string within a dynamic string, case insensitive. Parameters: * **str** – Dynamic string * **find** – String to find Returns: Pointer to the first occurrence, or _NULL_ if not found * * * const char \*dstr\_find(const struct [dstr](#c.dstr "dstr") \*str, const char \*find)[](#c.dstr_find "Link to this definition") Finds a string within a dynamic string. Parameters: * **str** – Dynamic string * **find** – String to find Returns: Pointer to the first occurrence, or _NULL_ if not found * * * void dstr\_replace(struct [dstr](#c.dstr "dstr") \*str, const char \*find, const char \*replace)[](#c.dstr_replace "Link to this definition") Replaces all occurrences of _find_ with _replace_. Parameters: * **str** – Dynamic string * **find** – String to find * **replace** – Replacement string * * * int dstr\_cmp(const struct [dstr](#c.dstr "dstr") \*str1, const char \*str2)[](#c.dstr_cmp "Link to this definition") Compares with a string. Parameters: * **str1** – Dynamic string * **str2** – String to compare Returns: 0 if equal, nonzero otherwise * * * int dstr\_cmpi(const struct [dstr](#c.dstr "dstr") \*str1, const char \*str2)[](#c.dstr_cmpi "Link to this definition") Compares with a string, case-insensitive. Parameters: * **str1** – Dynamic string * **str2** – String to compare Returns: 0 if equal, nonzero otherwise * * * int dstr\_ncmp(const struct [dstr](#c.dstr "dstr") \*str1, const char \*str2, const size\_t n)[](#c.dstr_ncmp "Link to this definition") Compares a specific number of characters. Parameters: * **str1** – Dynamic string * **str2** – String to compare * **n** – Number of characters to compare Returns: 0 if equal, nonzero otherwise * * * int dstr\_ncmpi(const struct [dstr](#c.dstr "dstr") \*str1, const char \*str2, const size\_t n)[](#c.dstr_ncmpi "Link to this definition") Compares a specific number of characters, case-insensitive. Parameters: * **str1** – Dynamic string * **str2** – String to compare * **n** – Number of characters to compare Returns: 0 if equal, nonzero otherwise * * * void dstr\_depad(struct [dstr](#c.dstr "dstr") \*dst)[](#c.dstr_depad "Link to this definition") Removes all padding characters (tabs, spaces, CR, LF) from the front and ends of a dynamic string. Parameters: * **dst** – Dynamic string * * * void dstr\_left(struct [dstr](#c.dstr "dstr") \*dst, const struct [dstr](#c.dstr "dstr") \*str, const size\_t pos)[](#c.dstr_left "Link to this definition") Copies a certain number of characters from the left side of one dynamic string in to another. Parameters: * **dst** – Destination * **str** – Source * **pos** – Number of characters * * * void dstr\_mid(struct [dstr](#c.dstr "dstr") \*dst, const struct [dstr](#c.dstr "dstr") \*str, const size\_t start, const size\_t count)[](#c.dstr_mid "Link to this definition") Copies a certain number of characters from the middle of one dynamic string in to another. Parameters: * **dst** – Destination * **str** – Source * **start** – Starting index within _str_ * **count** – Number of characters to copy * * * void dstr\_right(struct [dstr](#c.dstr "dstr") \*dst, const struct [dstr](#c.dstr "dstr") \*str, const size\_t pos)[](#c.dstr_right "Link to this definition") Copies a certain number of characters from the right of one dynamic string in to another. Parameters: * **dst** – Destination * **str** – Source * **pos** – Index of _str_ to copy from * * * char dstr\_end(const struct [dstr](#c.dstr "dstr") \*str)[](#c.dstr_end "Link to this definition") Parameters: * **str** – Dynamic string Returns: The last character of a dynamic string * * * void dstr\_from\_wcs(struct [dstr](#c.dstr "dstr") \*dst, const wchar\_t \*wstr)[](#c.dstr_from_wcs "Link to this definition") Copies a wide string in to a dynamic string and converts it to UTF-8. Parameters: * **dst** – Dynamic string * **wstr** – Wide string * * * wchar\_t \*dstr\_to\_wcs(const struct [dstr](#c.dstr "dstr") \*str)[](#c.dstr_to_wcs "Link to this definition") Converts a dynamic array to a wide string. Free with [`bfree()`](reference-libobs-util-bmem#c.bfree "bfree") . Parameters: * **str** – Dynamic string Returns: Wide string allocation. Free with [`bfree()`](reference-libobs-util-bmem#c.bfree "bfree") * * * void dstr\_to\_upper(struct [dstr](#c.dstr "dstr") \*str)[](#c.dstr_to_upper "Link to this definition") Converts all characters within a dynamic array to uppercase. Parameters: * **str** – Dynamic string * * * void dstr\_to\_lower(struct [dstr](#c.dstr "dstr") \*str)[](#c.dstr_to_lower "Link to this definition") Converts all characters within a dynamic array to lowercase. Parameters: * **str** – Dynamic string --- # Platform Helpers — OBS Studio 31.0.2 documentation * [](index) * [Platform/Utility API Reference (libobs/util)](reference-libobs-util) * Platform Helpers * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/reference-libobs-util-platform.rst) [Previous](reference-libobs-util-dstr "Dynamic Strings And String Helpers") [Next](reference-libobs-util-profiler "Profiler") * * * Platform Helpers[](#platform-helpers "Link to this heading") ============================================================== These functions/structures/types are used to perform actions that typically don’t have shared functions across different operating systems and platforms. #include File Functions[](#file-functions "Link to this heading") ---------------------------------------------------------- FILE \*os\_wfopen(const wchar\_t \*path, const char \*mode)[](#c.os_wfopen "Link to this definition") Opens a file with a wide string path. * * * FILE \*os\_fopen(const char \*path, const char \*mode)[](#c.os_fopen "Link to this definition") Opens a file with a UTF8 string path. * * * int64\_t os\_fgetsize(FILE \*file)[](#c.os_fgetsize "Link to this definition") Returns a file’s size. * * * int os\_stat(const char \*file, struct stat \*st)[](#c.os_stat "Link to this definition") Equivalent to the posix _stat_ function. * * * int os\_fseeki64(FILE \*file, int64\_t offset, int origin)[](#c.os_fseeki64 "Link to this definition") Equivalent to fseek. * * * int64\_t os\_ftelli64(FILE \*file)[](#c.os_ftelli64 "Link to this definition") Gets the current file position. * * * size\_t os\_fread\_utf8(FILE \*file, char \*\*pstr)[](#c.os_fread_utf8 "Link to this definition") Reads a UTF8 encoded file and allocates a pointer to the UTF8 string. * * * char \*os\_quick\_read\_utf8\_file(const char \*path)[](#c.os_quick_read_utf8_file "Link to this definition") Reads a UTF8 encoded file and returns an allocated pointer to the string. * * * bool os\_quick\_write\_utf8\_file(const char \*path, const char \*str, size\_t len, bool marker)[](#c.os_quick_write_utf8_file "Link to this definition") Writes a UTF8 encoded file. * * * 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)[](#c.os_quick_write_utf8_file_safe "Link to this definition") Writes a UTF8 encoded file with overwrite corruption prevention. * * * int64\_t os\_get\_file\_size(const char \*path)[](#c.os_get_file_size "Link to this definition") Gets a file’s size. * * * int64\_t os\_get\_free\_space(const char \*path)[](#c.os_get_free_space "Link to this definition") Gets free space of a specific file path. * * * String Conversion Functions[](#string-conversion-functions "Link to this heading") ------------------------------------------------------------------------------------ size\_t os\_utf8\_to\_wcs(const char \*str, size\_t len, wchar\_t \*dst, size\_t dst\_size)[](#c.os_utf8_to_wcs "Link to this definition") Converts a UTF8 string to a wide string. * * * size\_t os\_wcs\_to\_utf8(const wchar\_t \*str, size\_t len, char \*dst, size\_t dst\_size)[](#c.os_wcs_to_utf8 "Link to this definition") Converts a wide string to a UTF8 string. * * * size\_t os\_utf8\_to\_wcs\_ptr(const char \*str, size\_t len, wchar\_t \*\*pstr)[](#c.os_utf8_to_wcs_ptr "Link to this definition") Gets an bmalloc-allocated wide string converted from a UTF8 string. * * * size\_t os\_wcs\_to\_utf8\_ptr(const wchar\_t \*str, size\_t len, char \*\*pstr)[](#c.os_wcs_to_utf8_ptr "Link to this definition") Gets an bmalloc-allocated UTF8 string converted from a wide string. * * * Number/String Conversion Functions[](#number-string-conversion-functions "Link to this heading") -------------------------------------------------------------------------------------------------- double os\_strtod(const char \*str)[](#c.os_strtod "Link to this definition") Converts a string to a double. * * * int os\_dtostr(double value, char \*dst, size\_t size)[](#c.os_dtostr "Link to this definition") Converts a double to a string. * * * Dynamic Link Library Functions[](#dynamic-link-library-functions "Link to this heading") ------------------------------------------------------------------------------------------ These functions are roughly equivalent to dlopen/dlsym/dlclose. void \*os\_dlopen(const char \*path)[](#c.os_dlopen "Link to this definition") Opens a dynamic library. * * * void \*os\_dlsym(void \*module, const char \*func)[](#c.os_dlsym "Link to this definition") Returns a symbol from a dynamic library. * * * void os\_dlclose(void \*module)[](#c.os_dlclose "Link to this definition") Closes a dynamic library. * * * bool os\_is\_obs\_plugin(const char \*path)[](#c.os_is_obs_plugin "Link to this definition") Returns true if the path is a dynamic library that looks like an OBS plugin. Currently only needed on Windows for performance reasons. * * * CPU Usage Functions[](#cpu-usage-functions "Link to this heading") -------------------------------------------------------------------- os\_cpu\_usage\_info\_t \*os\_cpu\_usage\_info\_start(void)[](#c.os_cpu_usage_info_start "Link to this definition") Creates a CPU usage information object. * * * double os\_cpu\_usage\_info\_query(os\_cpu\_usage\_info\_t \*info)[](#c.os_cpu_usage_info_query "Link to this definition") Queries the current CPU usage. * * * void os\_cpu\_usage\_info\_destroy(os\_cpu\_usage\_info\_t \*info)[](#c.os_cpu_usage_info_destroy "Link to this definition") Destroys a CPU usage information object. * * * Sleep/Time Functions[](#sleep-time-functions "Link to this heading") ---------------------------------------------------------------------- bool os\_sleepto\_ns(uint64\_t time\_target)[](#c.os_sleepto_ns "Link to this definition") Sleeps to a specific time with high precision, in nanoseconds. * * * bool os\_sleepto\_ns\_fast(uint64\_t time\_target)[](#c.os_sleepto_ns_fast "Link to this definition") Sleeps to a specific time without high precision, in nanoseconds. The function won’t return until reaching the specific time. * * * void os\_sleep\_ms(uint32\_t duration)[](#c.os_sleep_ms "Link to this definition") Sleeps for a specific number of milliseconds. * * * uint64\_t os\_gettime\_ns(void)[](#c.os_gettime_ns "Link to this definition") Gets the current high-precision system time, in nanoseconds. * * * Other Path/File Functions[](#other-path-file-functions "Link to this heading") -------------------------------------------------------------------------------- int os\_get\_config\_path(char \*dst, size\_t size, const char \*name)[](#c.os_get_config_path "Link to this definition") char \*os\_get\_config\_path\_ptr(const char \*name)[](#c.os_get_config_path_ptr "Link to this definition") Gets the user-specific application configuration data path. * * * int os\_get\_program\_data\_path(char \*dst, size\_t size, const char \*name)[](#c.os_get_program_data_path "Link to this definition") char \*os\_get\_program\_data\_path\_ptr(const char \*name)[](#c.os_get_program_data_path_ptr "Link to this definition") Gets the application configuration data path. * * * bool os\_file\_exists(const char \*path)[](#c.os_file_exists "Link to this definition") Returns true if a file/directory exists, false otherwise. * * * size\_t os\_get\_abs\_path(const char \*path, char \*abspath, size\_t size)[](#c.os_get_abs_path "Link to this definition") char \*os\_get\_abs\_path\_ptr(const char \*path)[](#c.os_get_abs_path_ptr "Link to this definition") Converts a relative path to an absolute path. * * * const char \*os\_get\_path\_extension(const char \*path)[](#c.os_get_path_extension "Link to this definition") Returns the extension portion of a path string, including the dot (.). * * * typedef struct os\_dir os\_dir\_t[](#c.os_dir_t "Link to this definition") A directory object. struct os\_dirent[](#c.os_dirent "Link to this definition") A directory entry record. char [os\_dirent](#c.os_dirent "os_dirent") .d\_name\[256\][](#c.os_dirent.d_name "Link to this definition") The directory entry name. bool [os\_dirent](#c.os_dirent "os_dirent") .directory[](#c.os_dirent.directory "Link to this definition") _true_ if the entry is a directory. * * * [os\_dir\_t](#c.os_dir_t "os_dir_t") \*os\_opendir(const char \*path)[](#c.os_opendir "Link to this definition") Opens a directory object to enumerate files within the directory. * * * struct [os\_dirent](#c.os_dirent "os_dirent") \*os\_readdir([os\_dir\_t](#c.os_dir_t "os_dir_t") \*dir)[](#c.os_readdir "Link to this definition") Returns the linked list of directory entries. * * * void os\_closedir([os\_dir\_t](#c.os_dir_t "os_dir_t") \*dir)[](#c.os_closedir "Link to this definition") Closes a directory object. * * * struct os\_globent[](#c.os_globent "Link to this definition") A glob entry. char \*[os\_globent](#c.os_globent "os_globent") .path[](#c.os_globent.path "Link to this definition") The full path to the glob entry. bool [os\_globent](#c.os_globent "os_globent") .directory[](#c.os_globent.directory "Link to this definition") _true_ if the glob entry is a directory, _false_ otherwise. struct os\_glob\_info[](#c.os_glob_info "Link to this definition") A glob object. size\_t [os\_glob\_info](#c.os_glob_info "os_glob_info") .gl\_pathc[](#c.os_glob_info.gl_pathc "Link to this definition") Number of glob entries. struct [os\_globent](#c.os_globent "os_globent") \*[os\_glob\_info](#c.os_glob_info "os_glob_info") .gl\_pathv[](#c.os_glob_info.gl_pathv "Link to this definition") Array of glob entries. typedef struct [os\_glob\_info](#c.os_glob_info "os_glob_info") os\_glob\_t[](#c.os_glob_t "Link to this definition") * * * int os\_glob(const char \*pattern, int flags, [os\_glob\_t](#c.os_glob_t "os_glob_t") \*\*pglob)[](#c.os_glob "Link to this definition") Enumerates files based upon a glob string. * * * void os\_globfree([os\_glob\_t](#c.os_glob_t "os_glob_t") \*pglob)[](#c.os_globfree "Link to this definition") Frees a glob object. * * * int os\_unlink(const char \*path)[](#c.os_unlink "Link to this definition") Deletes a file. * * * int os\_rmdir(const char \*path)[](#c.os_rmdir "Link to this definition") Deletes a directory. * * * char \*os\_getcwd(char \*path, size\_t size)[](#c.os_getcwd "Link to this definition") Returns a new bmalloc-allocated path to the current working directory. * * * int os\_chdir(const char \*path)[](#c.os_chdir "Link to this definition") Changes the current working directory. * * * int os\_mkdir(const char \*path)[](#c.os_mkdir "Link to this definition") Creates a directory. * * * int os\_mkdirs(const char \*path)[](#c.os_mkdirs "Link to this definition") Creates a full directory path if it doesn’t exist. * * * int os\_rename(const char \*old\_path, const char \*new\_path)[](#c.os_rename "Link to this definition") Renames a file. * * * int os\_copyfile(const char \*file\_in, const char \*file\_out)[](#c.os_copyfile "Link to this definition") Copies a file. * * * int os\_safe\_replace(const char \*target\_path, const char \*from\_path, const char \*backup\_path)[](#c.os_safe_replace "Link to this definition") Safely replaces a file. * * * char \*os\_generate\_formatted\_filename(const char \*extension, bool space, const char \*format)[](#c.os_generate_formatted_filename "Link to this definition") Returns a new bmalloc-allocated filename generated from specific formatting. * * * Sleep-Inhibition Functions[](#sleep-inhibition-functions "Link to this heading") ---------------------------------------------------------------------------------- These functions/types are used to inhibit the computer from going to sleep. struct os\_inhibit\_info[](#c.os_inhibit_info "Link to this definition") typedef struct [os\_inhibit\_info](#c.os_inhibit_info "os_inhibit_info") os\_inhibit\_t[](#c.os_inhibit_t "Link to this definition") * * * [os\_inhibit\_t](#c.os_inhibit_t "os_inhibit_t") \*os\_inhibit\_sleep\_create(const char \*reason)[](#c.os_inhibit_sleep_create "Link to this definition") Creates a sleep inhibition object. * * * bool os\_inhibit\_sleep\_set\_active([os\_inhibit\_t](#c.os_inhibit_t "os_inhibit_t") \*info, bool active)[](#c.os_inhibit_sleep_set_active "Link to this definition") Activates/deactivates a sleep inhibition object. * * * void os\_inhibit\_sleep\_destroy([os\_inhibit\_t](#c.os_inhibit_t "os_inhibit_t") \*info)[](#c.os_inhibit_sleep_destroy "Link to this definition") Destroys a sleep inhibition object. If the sleep inhibition object was active, it will be deactivated. * * * Other Functions[](#other-functions "Link to this heading") ------------------------------------------------------------ void os\_breakpoint(void)[](#c.os_breakpoint "Link to this definition") Triggers a debugger breakpoint (or crashes the program if no debugger present). * * * int os\_get\_physical\_cores(void)[](#c.os_get_physical_cores "Link to this definition") Returns the number of physical cores available. * * * int os\_get\_logical\_cores(void)[](#c.os_get_logical_cores "Link to this definition") Returns the number of logical cores available. * * * uint64\_t os\_get\_sys\_free\_size(void)[](#c.os_get_sys_free_size "Link to this definition") Returns the amount of memory available. * * * uint64\_t os\_get\_sys\_total\_size(void)[](#c.os_get_sys_total_size "Link to this definition") Returns the amount of memory installed. Added in version 29.0.0. * * * struct os\_proc\_memory\_usage[](#c.os_proc_memory_usage "Link to this definition") Memory usage structure. uint64\_t [os\_proc\_memory\_usage](#c.os_proc_memory_usage "os_proc_memory_usage") .resident\_size[](#c.os_proc_memory_usage.resident_size "Link to this definition") Resident size. uint64\_t [os\_proc\_memory\_usage](#c.os_proc_memory_usage "os_proc_memory_usage") .virtual\_size[](#c.os_proc_memory_usage.virtual_size "Link to this definition") Virtual size. typedef struct [os\_proc\_memory\_usage](#c.os_proc_memory_usage "os_proc_memory_usage") os\_proc\_memory\_usage\_t[](#c.os_proc_memory_usage_t "Link to this definition") * * * bool os\_get\_proc\_memory\_usage([os\_proc\_memory\_usage\_t](#c.os_proc_memory_usage_t "os_proc_memory_usage_t") \*usage)[](#c.os_get_proc_memory_usage "Link to this definition") Gets memory usage of the current process. * * * uint64\_t os\_get\_proc\_resident\_size(void)[](#c.os_get_proc_resident_size "Link to this definition") Returns the resident memory size of the current process. * * * uint64\_t os\_get\_proc\_virtual\_size(void)[](#c.os_get_proc_virtual_size "Link to this definition") Returns the virtual memory size of the current process. * * * bool os\_get\_emulation\_status(void)[](#c.os_get_emulation_status "Link to this definition") Returns true if the current process is an x64 binary and is being emulated or translated by the host operating system. On macOS, it returns true when an x64 binary is being translated by Rosetta and running on Apple Silicon Macs. On Windows, it returns true when an x64 binary is being emulated on Windows ARM64 PCs. On all other platforms, it will always returns false. * * * char \*os\_generate\_uuid(void)[](#c.os_generate_uuid "Link to this definition") Creates a version 4 UUID and returns a NULL-terminated 36-character string. Must be freed with [`bfree()`](reference-libobs-util-bmem#c.bfree "bfree") . Added in version 29.1. --- # Serializer — OBS Studio 31.0.2 documentation * [](index) * [Platform/Utility API Reference (libobs/util)](reference-libobs-util) * Serializer * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/reference-libobs-util-serializers.rst) [Previous](reference-libobs-util-profiler "Profiler") [Next](reference-libobs-util-source-profiler "Source Profiler") * * * Serializer[](#serializer "Link to this heading") ================================================== General programmable serialization functions. (A shared interface to various reading/writing to/from different inputs/outputs) #include Serializer Structure (struct serializer)[](#serializer-structure-struct-serializer "Link to this heading") ------------------------------------------------------------------------------------------------------------ struct serializer[](#c.serializer "Link to this definition") void \*[serializer](#c.serializer "serializer") .data[](#c.serializer.data "Link to this definition") size\_t (\*[serializer](#c.serializer "serializer") .read)(void\*, void\*, size\_t)[](#c.serializer.read "Link to this definition") size\_t (\*[serializer](#c.serializer "serializer") .write)(void\*, const void\*, size\_t)[](#c.serializer.write "Link to this definition") int64\_t (\*[serializer](#c.serializer "serializer") .seek)(void\*, int64\_t, enum serialize\_seek\_type)[](#c.serializer.seek "Link to this definition") int64\_t (\*[serializer](#c.serializer "serializer") .get\_pos)(void\*)[](#c.serializer.get_pos "Link to this definition") Serializer Inline Functions[](#serializer-inline-functions "Link to this heading") ------------------------------------------------------------------------------------ size\_t s\_read(struct [serializer](#c.serializer "serializer") \*s, void \*data, size\_t size)[](#c.s_read "Link to this definition") * * * size\_t s\_write(struct [serializer](#c.serializer "serializer") \*s, const void \*data, size\_t size)[](#c.s_write "Link to this definition") * * * size\_t serialize(struct [serializer](#c.serializer "serializer") \*s, void \*data, size\_t len)[](#c.serialize "Link to this definition") * * * int64\_t serializer\_seek(struct [serializer](#c.serializer "serializer") \*s, int64\_t offset, enum serialize\_seek\_type seek\_type)[](#c.serializer_seek "Link to this definition") * * * int64\_t serializer\_get\_pos(struct [serializer](#c.serializer "serializer") \*s)[](#c.serializer_get_pos "Link to this definition") * * * void s\_w8(struct [serializer](#c.serializer "serializer") \*s, uint8\_t u8)[](#c.s_w8 "Link to this definition") * * * void s\_wl16(struct [serializer](#c.serializer "serializer") \*s, uint16\_t u16)[](#c.s_wl16 "Link to this definition") * * * void s\_wl32(struct [serializer](#c.serializer "serializer") \*s, uint32\_t u32)[](#c.s_wl32 "Link to this definition") * * * void s\_wl64(struct [serializer](#c.serializer "serializer") \*s, uint64\_t u64)[](#c.s_wl64 "Link to this definition") * * * void s\_wlf(struct [serializer](#c.serializer "serializer") \*s, float f)[](#c.s_wlf "Link to this definition") * * * void s\_wld(struct [serializer](#c.serializer "serializer") \*s, double d)[](#c.s_wld "Link to this definition") * * * void s\_wb16(struct [serializer](#c.serializer "serializer") \*s, uint16\_t u16)[](#c.s_wb16 "Link to this definition") * * * void s\_wb24(struct [serializer](#c.serializer "serializer") \*s, uint32\_t u24)[](#c.s_wb24 "Link to this definition") * * * void s\_wb32(struct [serializer](#c.serializer "serializer") \*s, uint32\_t u32)[](#c.s_wb32 "Link to this definition") * * * void s\_wb64(struct [serializer](#c.serializer "serializer") \*s, uint64\_t u64)[](#c.s_wb64 "Link to this definition") * * * void s\_wbf(struct [serializer](#c.serializer "serializer") \*s, float f)[](#c.s_wbf "Link to this definition") * * * void s\_wbd(struct [serializer](#c.serializer "serializer") \*s, double d)[](#c.s_wbd "Link to this definition") * * * Array Output Serializer[](#array-output-serializer "Link to this heading") ============================================================================ Provides an output serializer used with dynamic arrays. Changed in version 30.2: Array output serializer now supports seeking. #include Array Output Serializer Structure (struct array\_output\_data)[](#array-output-serializer-structure-struct-array-output-data "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------ struct array\_output\_data[](#c.array_output_data "Link to this definition") DARRAY(uint8\_t) array\_output\_data.bytes Array Output Serializer Functions[](#array-output-serializer-functions "Link to this heading") ------------------------------------------------------------------------------------------------ void array\_output\_serializer\_init(struct [serializer](#c.serializer "serializer") \*s, struct [array\_output\_data](#c.array_output_data "array_output_data") \*data)[](#c.array_output_serializer_init "Link to this definition") * * * void array\_output\_serializer\_free(struct [array\_output\_data](#c.array_output_data "array_output_data") \*data)[](#c.array_output_serializer_free "Link to this definition") * * * void array\_output\_serializer\_reset(struct [array\_output\_data](#c.array_output_data "array_output_data") \*data)[](#c.array_output_serializer_reset "Link to this definition") Resets serializer without freeing data. Added in version 30.2. * * * File Input/Output Serializers[](#file-input-output-serializers "Link to this heading") ======================================================================================== Provides file reading/writing serializers. #include File Input Serializer Functions[](#file-input-serializer-functions "Link to this heading") -------------------------------------------------------------------------------------------- bool file\_input\_serializer\_init(struct [serializer](#c.serializer "serializer") \*s, const char \*path)[](#c.file_input_serializer_init "Link to this definition") Initializes a file input serializer. Returns: _true_ if file opened successfully, _false_ otherwise * * * void file\_input\_serializer\_free(struct [serializer](#c.serializer "serializer") \*s)[](#c.file_input_serializer_free "Link to this definition") Frees a file input serializer. * * * File Output Serializer Functions[](#file-output-serializer-functions "Link to this heading") ---------------------------------------------------------------------------------------------- bool file\_output\_serializer\_init(struct [serializer](#c.serializer "serializer") \*s, const char \*path)[](#c.file_output_serializer_init "Link to this definition") Initializes a file output serializer. Returns: _true_ if file created successfully, _false_ otherwise * * * bool file\_output\_serializer\_init\_safe(struct [serializer](#c.serializer "serializer") \*s, const char \*path, const char \*temp\_ext)[](#c.file_output_serializer_init_safe "Link to this definition") Initializes and safely writes to a temporary file (determined by the temporary extension) until freed. Returns: _true_ if file created successfully, _false_ otherwise * * * void file\_output\_serializer\_free(struct [serializer](#c.serializer "serializer") \*s)[](#c.file_output_serializer_free "Link to this definition") Frees the file output serializer and saves the file. * * * Buffered File Output Serializer[](#buffered-file-output-serializer "Link to this heading") ============================================================================================ Provides a buffered file serializer that writes data asynchronously to prevent stalls due to slow disk I/O. Writes will only block when the buffer is full. The buffer and chunk size are configurable with the defaults being 256 MiB and 1 MiB respectively. Added in version 30.2. #include Buffered File Output Serializer Functions[](#buffered-file-output-serializer-functions "Link to this heading") ---------------------------------------------------------------------------------------------------------------- bool buffered\_file\_serializer\_init\_defaults(struct [serializer](#c.serializer "serializer") \*s, const char \*path)[](#c.buffered_file_serializer_init_defaults "Link to this definition") Initializes a buffered file output serializer with default buffer and chunk sizes. Returns: _true_ if file created successfully, _false_ otherwise * * * bool buffered\_file\_serializer\_init(struct [serializer](#c.serializer "serializer") \*s, const char \*path, size\_t max\_bufsize, size\_t chunk\_size)[](#c.buffered_file_serializer_init "Link to this definition") Initialize buffered writer with specified buffer and chunk sizes. Setting either to 0 will use the default value. Returns: _true_ if file created successfully, _false_ otherwise * * * void buffered\_file\_serializer\_free(struct [serializer](#c.serializer "serializer") \*s)[](#c.buffered_file_serializer_free "Link to this definition") Frees the file output serializer and saves the file. Will block until I/O thread completes outstanding writes. --- # Profiler — OBS Studio 31.0.2 documentation * [](index) * [Platform/Utility API Reference (libobs/util)](reference-libobs-util) * Profiler * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/reference-libobs-util-profiler.rst) [Previous](reference-libobs-util-platform "Platform Helpers") [Next](reference-libobs-util-serializers "Serializer") * * * Profiler[](#profiler "Link to this heading") ============================================== The profiler is used to get information about program performance and efficiency. typedef struct profiler\_snapshot profiler\_snapshot\_t[](#c.profiler_snapshot_t "Link to this definition") typedef struct profiler\_snapshot\_entry profiler\_snapshot\_entry\_t[](#c.profiler_snapshot_entry_t "Link to this definition") typedef struct profiler\_name\_store profiler\_name\_store\_t[](#c.profiler_name_store_t "Link to this definition") typedef struct [profiler\_time\_entry](#c.profiler_time_entry "profiler_time_entry") profiler\_time\_entry\_t[](#c.profiler_time_entry_t "Link to this definition") #include Profiler Structures[](#profiler-structures "Link to this heading") -------------------------------------------------------------------- struct profiler\_time\_entry[](#c.profiler_time_entry "Link to this definition") uint64\_t [profiler\_time\_entry](#c.profiler_time_entry "profiler_time_entry") .time\_delta[](#c.profiler_time_entry.time_delta "Link to this definition") uint64\_t [profiler\_time\_entry](#c.profiler_time_entry "profiler_time_entry") .count[](#c.profiler_time_entry.count "Link to this definition") Profiler Control Functions[](#profiler-control-functions "Link to this heading") ---------------------------------------------------------------------------------- void profiler\_start(void)[](#c.profiler_start "Link to this definition") Starts the profiler. * * * void profiler\_stop(void)[](#c.profiler_stop "Link to this definition") Stops the profiler. * * * void profiler\_print([profiler\_snapshot\_t](#c.profiler_snapshot_t "profiler_snapshot_t") \*snap)[](#c.profiler_print "Link to this definition") Creates a profiler snapshot and saves it within _snap_. Parameters: * **snap** – A profiler snapshot object * * * void profiler\_print\_time\_between\_calls([profiler\_snapshot\_t](#c.profiler_snapshot_t "profiler_snapshot_t") \*snap)[](#c.profiler_print_time_between_calls "Link to this definition") Creates a profiler snapshot of time between calls and saves it within _snap_. Parameters: * **snap** – A profiler snapshot object * * * void profiler\_free(void)[](#c.profiler_free "Link to this definition") Frees the profiler. * * * Profiling Functions[](#profiling-functions "Link to this heading") -------------------------------------------------------------------- void profile\_register\_root(const char \*name, uint64\_t expected\_time\_between\_calls)[](#c.profile_register_root "Link to this definition") Registers a root profile node. Parameters: * **name** – Name of the root profile node * **expected\_time\_between\_calls** – The expected time between calls of the profile root node, or 0 if none. * * * void profile\_start(const char \*name)[](#c.profile_start "Link to this definition") Starts a profile node. This profile node will be a child of the last node that was started. Parameters: * **name** – Name of the profile node * * * void profile\_end(const char \*name)[](#c.profile_end "Link to this definition") Parameters: * **name** – Name of the profile node * * * void profile\_reenable\_thread(void)[](#c.profile_reenable_thread "Link to this definition") Because [`profiler_start()`](#c.profiler_start "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[](#profiler-name-storage-functions "Link to this heading") -------------------------------------------------------------------------------------------- [profiler\_name\_store\_t](#c.profiler_name_store_t "profiler_name_store_t") \*profiler\_name\_store\_create(void)[](#c.profiler_name_store_create "Link to this definition") Creates a profiler name storage object. Returns: Profiler name store object * * * void profiler\_name\_store\_free([profiler\_name\_store\_t](#c.profiler_name_store_t "profiler_name_store_t") \*store)[](#c.profiler_name_store_free "Link to this definition") Frees a profiler name storage object. Parameters: * **store** – Profiler name storage object * * * const char \*profile\_store\_name([profiler\_name\_store\_t](#c.profiler_name_store_t "profiler_name_store_t") \*store, const char \*format, ...)[](#c.profile_store_name "Link to this definition") Creates a formatted string and stores it within a profiler name storage object. Parameters: * **store** – Profiler name storage object * **format** – Formatted string Returns: The string created from format specifications * * * Profiler Data Access Functions[](#profiler-data-access-functions "Link to this heading") ------------------------------------------------------------------------------------------ [profiler\_snapshot\_t](#c.profiler_snapshot_t "profiler_snapshot_t") \*profile\_snapshot\_create(void)[](#c.profile_snapshot_create "Link to this definition") Creates a profile snapshot. Profiler snapshots are used to obtain data about how the active profiles performed. Returns: A profiler snapshot object * * * void profile\_snapshot\_free([profiler\_snapshot\_t](#c.profiler_snapshot_t "profiler_snapshot_t") \*snap)[](#c.profile_snapshot_free "Link to this definition") Frees a profiler snapshot object. Parameters: * **snap** – A profiler snapshot * * * bool profiler\_snapshot\_dump\_csv(const [profiler\_snapshot\_t](#c.profiler_snapshot_t "profiler_snapshot_t") \*snap, const char \*filename)[](#c.profiler_snapshot_dump_csv "Link to this definition") Creates a CSV file of the profiler snapshot. Parameters: * **snap** – A profiler snapshot * **filename** – The path to the CSV file to save Returns: _true_ if successfully written, _false_ otherwise * * * bool profiler\_snapshot\_dump\_csv\_gz(const [profiler\_snapshot\_t](#c.profiler_snapshot_t "profiler_snapshot_t") \*snap, const char \*filename)[](#c.profiler_snapshot_dump_csv_gz "Link to this definition") Creates a gzipped CSV file of the profiler snapshot. Parameters: * **snap** – A profiler snapshot * **filename** – The path to the gzipped CSV file to save Returns: _true_ if successfully written, _false_ otherwise * * * size\_t profiler\_snapshot\_num\_roots([profiler\_snapshot\_t](#c.profiler_snapshot_t "profiler_snapshot_t") \*snap)[](#c.profiler_snapshot_num_roots "Link to this definition") Parameters: * **snap** – A profiler snapshot Returns: Number of root profiler nodes in the snapshot * * * typedef bool (\*profiler\_entry\_enum\_func)(void \*context, [profiler\_snapshot\_entry\_t](#c.profiler_snapshot_entry_t "profiler_snapshot_entry_t") \*entry)[](#c.profiler_entry_enum_func "Link to this definition") 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 * * * void profiler\_snapshot\_enumerate\_roots([profiler\_snapshot\_t](#c.profiler_snapshot_t "profiler_snapshot_t") \*snap, [profiler\_entry\_enum\_func](#c.profiler_entry_enum_func "profiler_entry_enum_func") func, void \*context)[](#c.profiler_snapshot_enumerate_roots "Link to this definition") Enumerates root profile nodes. Parameters: * **snap** – A profiler snapshot * **func** – Enumeration callback * **context** – Private data to pass to the callback * * * typedef bool (\*profiler\_name\_filter\_func)(void \*data, const char \*name, bool \*remove)[](#c.profiler_name_filter_func "Link to this definition") 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 * * * void profiler\_snapshot\_filter\_roots([profiler\_snapshot\_t](#c.profiler_snapshot_t "profiler_snapshot_t") \*snap, [profiler\_name\_filter\_func](#c.profiler_name_filter_func "profiler_name_filter_func") func, void \*data)[](#c.profiler_snapshot_filter_roots "Link to this definition") Removes/filters profile roots based upon their names. Parameters: * **snap** – A profiler snapshot * **func** – Enumeration callback to filter with * **data** – Private data to pass to the callback * * * size\_t profiler\_snapshot\_num\_children([profiler\_snapshot\_entry\_t](#c.profiler_snapshot_entry_t "profiler_snapshot_entry_t") \*entry)[](#c.profiler_snapshot_num_children "Link to this definition") Parameters: * **entry** – A profiler snapshot entry Returns: Number of children for the entry * * * void profiler\_snapshot\_enumerate\_children([profiler\_snapshot\_entry\_t](#c.profiler_snapshot_entry_t "profiler_snapshot_entry_t") \*entry, [profiler\_entry\_enum\_func](#c.profiler_entry_enum_func "profiler_entry_enum_func") func, void \*context)[](#c.profiler_snapshot_enumerate_children "Link to this definition") Enumerates child entries of a profiler snapshot entry. Parameters: * **entry** – A profiler snapshot entry * **func** – Enumeration callback * **context** – Private data passed to the callback * * * const char \*profiler\_snapshot\_entry\_name([profiler\_snapshot\_entry\_t](#c.profiler_snapshot_entry_t "profiler_snapshot_entry_t") \*entry)[](#c.profiler_snapshot_entry_name "Link to this definition") Parameters: * **entry** – A profiler snapshot entry Returns: The name of the profiler snapshot entry * * * profiler\_time\_entries\_t \*profiler\_snapshot\_entry\_times([profiler\_snapshot\_entry\_t](#c.profiler_snapshot_entry_t "profiler_snapshot_entry_t") \*entry)[](#c.profiler_snapshot_entry_times "Link to this definition") Gets the time entries for a snapshot entry. Parameters: * **entry** – A profiler snapshot entry Returns: An array of profiler time entries * * * uint64\_t profiler\_snapshot\_entry\_min\_time([profiler\_snapshot\_entry\_t](#c.profiler_snapshot_entry_t "profiler_snapshot_entry_t") \*entry)[](#c.profiler_snapshot_entry_min_time "Link to this definition") Gets the minimum time for a profiler snapshot entry. Parameters: * **entry** – A profiler snapshot entry Returns: The minimum time value for the snapshot entry * * * uint64\_t profiler\_snapshot\_entry\_max\_time([profiler\_snapshot\_entry\_t](#c.profiler_snapshot_entry_t "profiler_snapshot_entry_t") \*entry)[](#c.profiler_snapshot_entry_max_time "Link to this definition") Gets the maximum time for a profiler snapshot entry. Parameters: * **entry** – A profiler snapshot entry Returns: The maximum time value for the snapshot entry * * * uint64\_t profiler\_snapshot\_entry\_overall\_count([profiler\_snapshot\_entry\_t](#c.profiler_snapshot_entry_t "profiler_snapshot_entry_t") \*entry)[](#c.profiler_snapshot_entry_overall_count "Link to this definition") Gets the overall count for a profiler snapshot entry. Parameters: * **entry** – A profiler snapshot entry Returns: The overall count value for the snapshot entry * * * profiler\_time\_entries\_t \*profiler\_snapshot\_entry\_times\_between\_calls([profiler\_snapshot\_entry\_t](#c.profiler_snapshot_entry_t "profiler_snapshot_entry_t") \*entry)[](#c.profiler_snapshot_entry_times_between_calls "Link to this definition") Gets an array of time between calls for a profiler snapshot entry. Parameters: * **entry** – A profiler snapshot entry Returns: An array of profiler time entries * * * uint64\_t profiler\_snapshot\_entry\_expected\_time\_between\_calls([profiler\_snapshot\_entry\_t](#c.profiler_snapshot_entry_t "profiler_snapshot_entry_t") \*entry)[](#c.profiler_snapshot_entry_expected_time_between_calls "Link to this definition") Gets the expected time between calls for a profiler snapshot entry. Parameters: * **entry** – A profiler snapshot entry Returns: The expected time between calls for the snapshot entry, or 0 if not set * * * uint64\_t profiler\_snapshot\_entry\_min\_time\_between\_calls([profiler\_snapshot\_entry\_t](#c.profiler_snapshot_entry_t "profiler_snapshot_entry_t") \*entry)[](#c.profiler_snapshot_entry_min_time_between_calls "Link to this definition") Gets the minimum time seen between calls for a profiler snapshot entry. Parameters: * **entry** – A profiler snapshot entry Returns: The minimum time seen between calls for the snapshot entry * * * uint64\_t profiler\_snapshot\_entry\_max\_time\_between\_calls([profiler\_snapshot\_entry\_t](#c.profiler_snapshot_entry_t "profiler_snapshot_entry_t") \*entry)[](#c.profiler_snapshot_entry_max_time_between_calls "Link to this definition") Gets the maximum time seen between calls for a profiler snapshot entry. Parameters: * **entry** – A profiler snapshot entry Returns: The maximum time seen between calls for the snapshot entry * * * uint64\_t profiler\_snapshot\_entry\_overall\_between\_calls\_count([profiler\_snapshot\_entry\_t](#c.profiler_snapshot_entry_t "profiler_snapshot_entry_t") \*entry)[](#c.profiler_snapshot_entry_overall_between_calls_count "Link to this definition") Gets the overall time between calls for a profiler snapshot entry. Parameters: * **entry** – A profiler snapshot entry Returns: The overall time between calls for the snapshot entry --- # Source Profiler — OBS Studio 31.0.2 documentation * [](index) * [Platform/Utility API Reference (libobs/util)](reference-libobs-util) * Source Profiler * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/reference-libobs-util-source-profiler.rst) [Previous](reference-libobs-util-serializers "Serializer") [Next](reference-libobs-util-text-lookup "Text Lookup Interface") * * * Source Profiler[](#source-profiler "Link to this heading") ============================================================ The source profiler is used to get information about individual source’s performance. struct profiler\_result[](#c.profiler_result "Link to this definition") uint64\_t [profiler\_result](#c.profiler_result "profiler_result") .tick\_avg[](#c.profiler_result.tick_avg "Link to this definition") uint64\_t [profiler\_result](#c.profiler_result "profiler_result") .render\_avg[](#c.profiler_result.render_avg "Link to this definition") Average execution time of this source’s tick and render functions within the sampled timeframe (5 seconds). Note that a source will be ticked only once per frame, but may be rendered multiple times. uint64\_t [profiler\_result](#c.profiler_result "profiler_result") .tick\_max[](#c.profiler_result.tick_max "Link to this definition") uint64\_t [profiler\_result](#c.profiler_result "profiler_result") .render\_max[](#c.profiler_result.render_max "Link to this definition") Maximum execution time of this source’s tick and render functions within the sampled timeframe (5 seconds). uint64\_t [profiler\_result](#c.profiler_result "profiler_result") .render\_gpu\_avg[](#c.profiler_result.render_gpu_avg "Link to this definition") uint64\_t [profiler\_result](#c.profiler_result "profiler_result") .render\_gpu\_max[](#c.profiler_result.render_gpu_max "Link to this definition") Average and maximum execution time for GPU rendering to execute within the sampled timeframe (5 seconds). Note that GPU timing is not supported on macOS and is of limited accuracy due to variations in GPU load/clock speed. uint64\_t [profiler\_result](#c.profiler_result "profiler_result") .render\_sum[](#c.profiler_result.render_sum "Link to this definition") uint64\_t [profiler\_result](#c.profiler_result "profiler_result") .render\_gpu\_sum[](#c.profiler_result.render_gpu_sum "Link to this definition") Sum of all CPU/GPU render time in a frame, averaged over the sampled timeframe (5 seconds). For example, assuming a source with perfect consistency in its render time that gets rendered twice in a frame and a value for [`profiler_result.render_avg`](#c.profiler_result.render_avg "profiler_result.render_avg") of 1000000 (1 ms), will have a value for [`profiler_result.render_sum`](#c.profiler_result.render_sum "profiler_result.render_sum") of 2000000 (2 ms). double [profiler\_result](#c.profiler_result "profiler_result") .async\_fps[](#c.profiler_result.async_fps "Link to this definition") Framerate calculated from average time delta between async frames submitted via `obs_source_output_video2()`. Only valid for async sources (e.g. Media Source). typedef struct [profiler\_result](#c.profiler_result "profiler_result") profiler\_result\_t[](#c.profiler_result_t "Link to this definition") #include Source Profiler Functions[](#source-profiler-functions "Link to this heading") -------------------------------------------------------------------------------- void source\_profiler\_enable(bool enable)[](#c.source_profiler_enable "Link to this definition") Enables or disables the source profiler. The profiler will then start or stop collecting data with the next rendered frame. Note that enabling the profiler may have a small performance penalty. Parameters: * **enable** – Whether or not to enable the source profiler. * * * void source\_profiler\_gpu\_enable(bool enable)[](#c.source_profiler_gpu_enable "Link to this definition") Enables or disables GPU profiling (not available on macOS). GPU profiling will start or stop with the next frame OBS is rendering. Note that GPU profiling may have a larger performance impact. Parameters: * **enable** – Whether or not to enable GPU profiling. * * * [profiler\_result\_t](#c.profiler_result_t "profiler_result_t") \*source\_profiler\_get\_result([obs\_source\_t](reference-sources#c.obs_source_t "obs_source_t") \*source)[](#c.source_profiler_get_result "Link to this definition") Returns profiling information for the provided source. Note that result must be freed with [`bfree()`](reference-libobs-util-bmem#c.bfree "bfree") . Parameters: * **source** – Source to get profiling information for Returns: Pointer to profiler\_result\_t with data, NULL otherwise. * * * bool source\_profiler\_fill\_result([obs\_source\_t](reference-sources#c.obs_source_t "obs_source_t") \*source, [profiler\_result\_t](#c.profiler_result_t "profiler_result_t") \*result)[](#c.source_profiler_fill_result "Link to this definition") Fill a preexisting profiler\_result\_t object with data for source. This function exists to avoid having to allocate new memory each time a profiling result is queried. Parameters: * **source** – Source to get profiling informatio for * **result** – Result object to fill Returns: _true_ if data for the source exists, _false_ otherwise --- # Text Lookup Interface — OBS Studio 31.0.2 documentation * [](index) * [Platform/Utility API Reference (libobs/util)](reference-libobs-util) * Text Lookup Interface * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/reference-libobs-util-text-lookup.rst) [Previous](reference-libobs-util-source-profiler "Source Profiler") [Next](reference-libobs-util-threading "Threading") * * * Text Lookup Interface[](#text-lookup-interface "Link to this heading") ======================================================================== Used for storing and looking up localized strings. Uses an ini-file like file format for localization lookup. struct text\_lookup[](#c.text_lookup "Link to this definition") typedef struct [text\_lookup](#c.text_lookup "text_lookup") lookup\_t[](#c.lookup_t "Link to this definition") #include Text Lookup Functions[](#text-lookup-functions "Link to this heading") ------------------------------------------------------------------------ [lookup\_t](#c.lookup_t "lookup_t") \*text\_lookup\_create(const char \*path)[](#c.text_lookup_create "Link to this definition") Creates a text lookup object from a text lookup file. Parameters: * **path** – Path to the localization file Returns: New lookup object, or _NULL_ if an error occurred * * * bool text\_lookup\_add([lookup\_t](#c.lookup_t "lookup_t") \*lookup, const char \*path)[](#c.text_lookup_add "Link to this definition") 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 [`text_lookup_create()`](#c.text_lookup_create "text_lookup_create") , and then call this function to load the actual desired language in case the desired language isn’t fully translated. Parameters: * **lookup** – Lookup object * **path** – Path to the localization file Returns: _true_ if successful, _false_ otherwise * * * void text\_lookup\_destroy([lookup\_t](#c.lookup_t "lookup_t") \*lookup)[](#c.text_lookup_destroy "Link to this definition") Destroys a text lookup object. Parameters: * **lookup** – Lookup object * * * bool text\_lookup\_getstr([lookup\_t](#c.lookup_t "lookup_t") \*lookup, const char \*lookup\_val, const char \*\*out)[](#c.text_lookup_getstr "Link to this definition") Gets a localized text string. Parameters: * **lookup** – Lookup object * **lookup\_val** – Value to look up * **out** – Pointer that receives the translated string pointer Returns: _true_ if the value exists, _false_ otherwise --- # Threading — OBS Studio 31.0.2 documentation * [](index) * [Platform/Utility API Reference (libobs/util)](reference-libobs-util) * Threading * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/reference-libobs-util-threading.rst) [Previous](reference-libobs-util-text-lookup "Text Lookup Interface") [Next](reference-libobs-callback "Callback API Reference (libobs/callback)") * * * Threading[](#threading "Link to this heading") ================================================ Libobs provides a number of helper functions/types specifically for threading. The threading header will additionally provide access to pthread functions even on Windows. #include Threading Types[](#threading-types "Link to this heading") ------------------------------------------------------------ type os\_event\_t[](#c.os_event_t "Link to this definition") type os\_sem\_t[](#c.os_sem_t "Link to this definition") General Thread Functions[](#general-thread-functions "Link to this heading") ------------------------------------------------------------------------------ void os\_set\_thread\_name(const char \*name)[](#c.os_set_thread_name "Link to this definition") Sets the name of the current thread. * * * Event Functions[](#event-functions "Link to this heading") ------------------------------------------------------------ int os\_event\_init([os\_event\_t](#c.os_event_t "os_event_t") \*\*event, enum os\_event\_type type)[](#c.os_event_init "Link to this definition") Creates an event object. Parameters: * **event** – Pointer that receives a pointer to a new event object * **type** – Can be one of the following values: * OS\_EVENT\_TYPE\_AUTO - Automatically resets when signaled * OS\_EVENT\_TYPE\_MANUAL - Stays signaled until the [`os_event_reset()`](#c.os_event_reset "os_event_reset") function is called Returns: 0 if successful, negative otherwise * * * void os\_event\_destroy([os\_event\_t](#c.os_event_t "os_event_t") \*event)[](#c.os_event_destroy "Link to this definition") Destroys an event. Parameters: * **event** – An event object * * * int os\_event\_wait([os\_event\_t](#c.os_event_t "os_event_t") \*event)[](#c.os_event_wait "Link to this definition") Waits for an event to signal. Parameters: * **event** – An event object Returns: 0 if successful, negative otherwise * * * int os\_event\_timedwait([os\_event\_t](#c.os_event_t "os_event_t") \*event, unsigned long milliseconds)[](#c.os_event_timedwait "Link to this definition") Waits a specific duration for an event to signal. Parameters: * **event** – An event object * **milliseconds** – Milliseconds to wait Returns: Can be one of the following values: * 0 - successful * ETIMEDOUT - Timed out * EINVAL - An unexpected error occurred * * * int os\_event\_try([os\_event\_t](#c.os_event_t "os_event_t") \*event)[](#c.os_event_try "Link to this definition") Checks for a signaled state without waiting. Parameters: * **event** – An event object Returns: Can be one of the following values: * 0 - successful * EAGAIN - The event is not signaled * EINVAL - An unexpected error occurred * * * int os\_event\_signal([os\_event\_t](#c.os_event_t "os_event_t") \*event)[](#c.os_event_signal "Link to this definition") Signals the event. Parameters: * **event** – An event object Returns: 0 if successful, negative otherwise * * * void os\_event\_reset([os\_event\_t](#c.os_event_t "os_event_t") \*event)[](#c.os_event_reset "Link to this definition") Resets the signaled state of the event. Parameters: * **event** – An event object * * * Semaphore Functions[](#semaphore-functions "Link to this heading") -------------------------------------------------------------------- int os\_sem\_init([os\_sem\_t](#c.os_sem_t "os_sem_t") \*\*sem, int value)[](#c.os_sem_init "Link to this definition") Creates a semaphore object. Parameters: * **sem** – Pointer that receives a pointer to the semaphore object * **value** – Initial value of the semaphore Returns: 0 if successful, negative otherwise * * * void os\_sem\_destroy([os\_sem\_t](#c.os_sem_t "os_sem_t") \*sem)[](#c.os_sem_destroy "Link to this definition") Destroys a semaphore object. Parameters: * **sem** – Semaphore object * * * int os\_sem\_post([os\_sem\_t](#c.os_sem_t "os_sem_t") \*sem)[](#c.os_sem_post "Link to this definition") Increments the semaphore. Parameters: * **sem** – Semaphore object Returns: 0 if successful, negative otherwise * * * int os\_sem\_wait([os\_sem\_t](#c.os_sem_t "os_sem_t") \*sem)[](#c.os_sem_wait "Link to this definition") Decrements the semaphore or waits until the semaphore has been incremented. Parameters: * **sem** – Semaphore object Returns: 0 if successful, negative otherwise * * * Atomic Inline Functions[](#atomic-inline-functions "Link to this heading") ---------------------------------------------------------------------------- long os\_atomic\_inc\_long(volatile long \*val)[](#c.os_atomic_inc_long "Link to this definition") Increments a long variable atomically. * * * long os\_atomic\_dec\_long(volatile long \*val)[](#c.os_atomic_dec_long "Link to this definition") Decrements a long variable atomically. * * * void os\_atomic\_store\_long(volatile long \*ptr, long val)[](#c.os_atomic_store_long "Link to this definition") Stores the value of a long variable atomically. * * * long os\_atomic\_set\_long(volatile long \*ptr, long val)[](#c.os_atomic_set_long "Link to this definition") Exchanges the value of a long variable atomically. Badly named. * * * long os\_atomic\_exchange\_long(volatile long \*ptr, long val)[](#c.os_atomic_exchange_long "Link to this definition") Exchanges the value of a long variable atomically. Properly named. * * * long os\_atomic\_load\_long(volatile const long \*ptr)[](#c.os_atomic_load_long "Link to this definition") Gets the value of a long variable atomically. * * * bool os\_atomic\_compare\_swap\_long(volatile long \*val, long old\_val, long new\_val)[](#c.os_atomic_compare_swap_long "Link to this definition") Swaps the value of a long variable atomically if its value matches. * * * void os\_atomic\_store\_bool(volatile bool \*ptr, bool val)[](#c.os_atomic_store_bool "Link to this definition") Stores the value of a boolean variable atomically. * * * bool os\_atomic\_set\_bool(volatile bool \*ptr, bool val)[](#c.os_atomic_set_bool "Link to this definition") Exchanges the value of a boolean variable atomically. Badly named. * * * bool os\_atomic\_exchange\_bool(volatile bool \*ptr, bool val)[](#c.os_atomic_exchange_bool "Link to this definition") Exchanges the value of a boolean variable atomically. Properly named. * * * bool os\_atomic\_load\_bool(volatile const bool \*ptr)[](#c.os_atomic_load_bool "Link to this definition") Gets the value of a boolean variable atomically. --- # Callback API Reference (libobs/callback) — OBS Studio 31.0.2 documentation * [](index) * Callback API Reference (libobs/callback) * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/reference-libobs-callback.rst) [Previous](reference-libobs-util-threading "Threading") [Next](reference-libobs-graphics "Graphics API Reference (libobs/graphics)") * * * Callback API Reference (libobs/callback)[](#callback-api-reference-libobs-callback "Link to this heading") ============================================================================================================ Calldata[](#calldata "Link to this heading") ---------------------------------------------- The [`calldata_t`](#c.calldata_t "calldata_t") object is used to pass parameters from signal handlers or to procedure handlers. type calldata\_t[](#c.calldata_t "Link to this definition") * * * void calldata\_init([calldata\_t](#c.calldata_t "calldata_t") \*data)[](#c.calldata_init "Link to this definition") Initializes a calldata structure (zeroes it). Parameters: * **data** – Calldata structure * * * void calldata\_free([calldata\_t](#c.calldata_t "calldata_t") \*data)[](#c.calldata_free "Link to this definition") Frees a calldata structure. Should only be used if [`calldata_init()`](#c.calldata_init "calldata_init") was used. If the object is received as a callback parameter, this function should not be used. Parameters: * **data** – Calldata structure * * * void calldata\_set\_int([calldata\_t](#c.calldata_t "calldata_t") \*data, const char \*name, long long val)[](#c.calldata_set_int "Link to this definition") Sets an integer parameter. Parameters: * **data** – Calldata structure * **name** – Parameter name * **val** – Integer value * * * void calldata\_set\_float([calldata\_t](#c.calldata_t "calldata_t") \*data, const char \*name, double val)[](#c.calldata_set_float "Link to this definition") Sets a floating point parameter. Parameters: * **data** – Calldata structure * **name** – Parameter name * **val** – Floating point value * * * void calldata\_set\_bool([calldata\_t](#c.calldata_t "calldata_t") \*data, const char \*name, bool val)[](#c.calldata_set_bool "Link to this definition") Sets a boolean parameter. Parameters: * **data** – Calldata structure * **name** – Parameter name * **val** – Boolean value * * * void calldata\_set\_ptr([calldata\_t](#c.calldata_t "calldata_t") \*data, const char \*name, void \*ptr)[](#c.calldata_set_ptr "Link to this definition") Sets a pointer parameter. Parameters: * **data** – Calldata structure * **name** – Parameter name * **val** – Pointer value * * * void calldata\_set\_string([calldata\_t](#c.calldata_t "calldata_t") \*data, const char \*name, const char \*str)[](#c.calldata_set_string "Link to this definition") Sets a string parameter. Parameters: * **data** – Calldata structure * **name** – Parameter name * **val** – String * * * long long calldata\_int(const [calldata\_t](#c.calldata_t "calldata_t") \*data, const char \*name)[](#c.calldata_int "Link to this definition") Gets an integer parameter. Parameters: * **data** – Calldata structure * **name** – Parameter name Returns: Integer value * * * double calldata\_float(const [calldata\_t](#c.calldata_t "calldata_t") \*data, const char \*name)[](#c.calldata_float "Link to this definition") Gets a floating point parameter. Parameters: * **data** – Calldata structure * **name** – Parameter name Returns: Floating point value * * * bool calldata\_bool(const [calldata\_t](#c.calldata_t "calldata_t") \*data, const char \*name)[](#c.calldata_bool "Link to this definition") Gets a boolean parameter. Parameters: * **data** – Calldata structure * **name** – Parameter name Returns: Boolean value * * * void \*calldata\_ptr(const [calldata\_t](#c.calldata_t "calldata_t") \*data, const char \*name)[](#c.calldata_ptr "Link to this definition") Gets a pointer parameter. For example, [Core OBS Signals](reference-core#core-signal-handler-reference) that have `ptr source` as a parameter requires this function to get the pointer, which can be casted to [`obs_source_t`](reference-sources#c.obs_source_t "obs_source_t") . Does not have to be freed. Parameters: * **data** – Calldata structure * **name** – Parameter name Returns: Pointer value * * * const char \*calldata\_string(const [calldata\_t](#c.calldata_t "calldata_t") \*data, const char \*name)[](#c.calldata_string "Link to this definition") Gets a string parameter. Parameters: * **data** – Calldata structure * **name** – Parameter name Returns: String value * * * Signals[](#signals "Link to this heading") -------------------------------------------- Signals are used for all event-based callbacks. #include type signal\_handler\_t[](#c.signal_handler_t "Link to this definition") * * * typedef void (\*signal\_callback\_t)(void \*data, [calldata\_t](#c.calldata_t "calldata_t") \*cd)[](#c.signal_callback_t "Link to this definition") Signal callback. Param data: Private data passed to this callback Param cd: Calldata object * * * [signal\_handler\_t](#c.signal_handler_t "signal_handler_t") \*signal\_handler\_create(void)[](#c.signal_handler_create "Link to this definition") Creates a new signal handler object. Returns: A new signal handler object * * * void signal\_handler\_destroy([signal\_handler\_t](#c.signal_handler_t "signal_handler_t") \*handler)[](#c.signal_handler_destroy "Link to this definition") Destroys a signal handler. Parameters: * **handler** – Signal handler object * * * bool signal\_handler\_add([signal\_handler\_t](#c.signal_handler_t "signal_handler_t") \*handler, const char \*signal\_decl)[](#c.signal_handler_add "Link to this definition") Adds a signal to a signal handler. Parameters: * **handler** – Signal handler object * **signal\_decl** – Signal declaration string * * * bool signal\_handler\_add\_array([signal\_handler\_t](#c.signal_handler_t "signal_handler_t") \*handler, const char \*\*signal\_decls)[](#c.signal_handler_add_array "Link to this definition") Adds multiple signals to a signal handler. Parameters: * **handler** – Signal handler object * **signal\_decls** – An array of signal declaration strings, terminated by _NULL_ * * * void signal\_handler\_connect([signal\_handler\_t](#c.signal_handler_t "signal_handler_t") \*handler, const char \*signal, [signal\_callback\_t](#c.signal_callback_t "signal_callback_t") callback, void \*data)[](#c.signal_handler_connect "Link to this definition") Connects a callback to a signal on a signal handler. Does nothing if the combination of `signal`, `callback`, and `data` is already connected to the handler. Parameters: * **handler** – Signal handler object * **signal** – Name of signal to handle * **callback** – Signal callback * **data** – Private data passed to the callback For scripting, use [`signal_handler_connect()`](scripting#signal_handler_connect "signal_handler_connect") . * * * void signal\_handler\_connect\_ref([signal\_handler\_t](#c.signal_handler_t "signal_handler_t") \*handler, const char \*signal, [signal\_callback\_t](#c.signal_callback_t "signal_callback_t") callback, void \*data)[](#c.signal_handler_connect_ref "Link to this definition") Connects a callback to a signal on a signal handler, and increments the handler’s internal reference counter, preventing it from being destroyed until the signal has been disconnected. Even if the combination of `signal`, `callback`, and `data` is already connected to the handler, the reference counter is still incremented. Parameters: * **handler** – Signal handler object * **signal** – Name of signal to handle * **callback** – Signal callback * **data** – Private data passed to the callback * * * void signal\_handler\_disconnect([signal\_handler\_t](#c.signal_handler_t "signal_handler_t") \*handler, const char \*signal, [signal\_callback\_t](#c.signal_callback_t "signal_callback_t") callback, void \*data)[](#c.signal_handler_disconnect "Link to this definition") Disconnects a callback from a signal on a signal handler. Does nothing if the combination of `signal`, `callback`, and `data` is not yet connected to the handler. Parameters: * **handler** – Signal handler object * **signal** – Name of signal that was handled * **callback** – Signal callback * **data** – Private data passed to the callback For scripting, use [`signal_handler_disconnect()`](scripting#signal_handler_disconnect "signal_handler_disconnect") . * * * void signal\_handler\_signal([signal\_handler\_t](#c.signal_handler_t "signal_handler_t") \*handler, const char \*signal, [calldata\_t](#c.calldata_t "calldata_t") \*params)[](#c.signal_handler_signal "Link to this definition") Triggers a signal, calling all connected callbacks. Parameters: * **handler** – Signal handler object * **signal** – Name of signal to trigger * **params** – Parameters to pass to the signal * * * Procedure Handlers[](#procedure-handlers "Link to this heading") ------------------------------------------------------------------ Procedure handlers are used to call functions without having to have direct access to declarations or callback pointers. #include type proc\_handler\_t[](#c.proc_handler_t "Link to this definition") * * * typedef void (\*proc\_handler\_proc\_t)(void \*data, [calldata\_t](#c.calldata_t "calldata_t") \*cd)[](#c.proc_handler_proc_t "Link to this definition") Procedure handler callback. Param data: Private data passed to this callback Param cd: Calldata object * * * [proc\_handler\_t](#c.proc_handler_t "proc_handler_t") \*proc\_handler\_create(void)[](#c.proc_handler_create "Link to this definition") Creates a new procedure handler. Returns: A new procedure handler object * * * void proc\_handler\_destroy([proc\_handler\_t](#c.proc_handler_t "proc_handler_t") \*handler)[](#c.proc_handler_destroy "Link to this definition") Destroys a procedure handler object. Parameters: * **handler** – Procedure handler object * * * void proc\_handler\_add([proc\_handler\_t](#c.proc_handler_t "proc_handler_t") \*handler, const char \*decl\_string, [proc\_handler\_proc\_t](#c.proc_handler_proc_t "proc_handler_proc_t") proc, void \*data)[](#c.proc_handler_add "Link to this definition") Adds a procedure to a procedure handler. Parameters: * **handler** – Procedure handler object * **decl\_string** – Procedure declaration string * **proc** – Procedure callback * **data** – Private data to pass to the callback * * * bool proc\_handler\_call([proc\_handler\_t](#c.proc_handler_t "proc_handler_t") \*handler, const char \*name, [calldata\_t](#c.calldata_t "calldata_t") \*params)[](#c.proc_handler_call "Link to this definition") Calls a procedure within the procedure handler. Parameters: * **handler** – Procedure handler object * **name** – Name of procedure to call * **params** – Calldata structure to pass to the procedure --- # Graphics API Reference (libobs/graphics) — OBS Studio 31.0.2 documentation * [](index) * Graphics API Reference (libobs/graphics) * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/reference-libobs-graphics.rst) [Previous](reference-libobs-callback "Callback API Reference (libobs/callback)") [Next](reference-libobs-graphics-effects "Effects (Shaders)") * * * Graphics API Reference (libobs/graphics)[](#graphics-api-reference-libobs-graphics "Link to this heading") ============================================================================================================ * [Effects (Shaders)](reference-libobs-graphics-effects) * [2-Component Vector](reference-libobs-graphics-vec2) * [3-Component Vector](reference-libobs-graphics-vec3) * [4-Component Vector](reference-libobs-graphics-vec4) * [Quaternion](reference-libobs-graphics-quat) * [Matrix](reference-libobs-graphics-matrix4) * [Extra Math Functions/Macros](reference-libobs-graphics-math) * [Image File Helper](reference-libobs-graphics-image-file) * [Axis Angle](reference-libobs-graphics-axisang) * [Core Graphics API](reference-libobs-graphics-graphics) * [Graphics Enumerations](reference-libobs-graphics-graphics#graphics-enumerations) * [Graphics Structures](reference-libobs-graphics-graphics#graphics-structures) * [Initialization Functions](reference-libobs-graphics-graphics#initialization-functions) * [Matrix Stack Functions](reference-libobs-graphics-graphics#matrix-stack-functions) * [Draw Functions](reference-libobs-graphics-graphics#draw-functions) * [Swap Chains](reference-libobs-graphics-graphics#swap-chains) * [Resource Loading](reference-libobs-graphics-graphics#resource-loading) * [Draw Functions](reference-libobs-graphics-graphics#id1) * [Texture Functions](reference-libobs-graphics-graphics#texture-functions) * [Cube Texture Functions](reference-libobs-graphics-graphics#cube-texture-functions) * [Staging Surface Functions](reference-libobs-graphics-graphics#staging-surface-functions) * [Z-Stencil Functions](reference-libobs-graphics-graphics#z-stencil-functions) * [Sampler State Functions](reference-libobs-graphics-graphics#sampler-state-functions) * [Vertex Buffer Functions](reference-libobs-graphics-graphics#vertex-buffer-functions) * [Index Buffer Functions](reference-libobs-graphics-graphics#index-buffer-functions) * [Display Duplicator (Windows Only)](reference-libobs-graphics-graphics#display-duplicator-windows-only) * [Monitor Functions](reference-libobs-graphics-graphics#monitor-functions) * [Render Helper Functions](reference-libobs-graphics-graphics#render-helper-functions) * [Graphics Types](reference-libobs-graphics-graphics#graphics-types) --- # Effects (Shaders) — OBS Studio 31.0.2 documentation * [](index) * [Graphics API Reference (libobs/graphics)](reference-libobs-graphics) * Effects (Shaders) * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/reference-libobs-graphics-effects.rst) [Previous](reference-libobs-graphics "Graphics API Reference (libobs/graphics)") [Next](reference-libobs-graphics-vec2 "2-Component Vector") * * * Effects (Shaders)[](#effects-shaders "Link to this heading") ============================================================== 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. #include typedef struct gs\_effect gs\_effect\_t[](#c.gs_effect_t "Link to this definition") Effect object. typedef struct gs\_effect\_technique gs\_technique\_t[](#c.gs_technique_t "Link to this definition") Technique object. typedef struct gs\_effect\_param gs\_eparam\_t[](#c.gs_eparam_t "Link to this definition") Effect parameter object. * * * [gs\_effect\_t](#c.gs_effect_t "gs_effect_t") \*gs\_effect\_create\_from\_file(const char \*file, char \*\*error\_string)[](#c.gs_effect_create_from_file "Link to this definition") Creates an effect from file. Parameters: * **file** – Path to the effect file * **error\_string** – Receives a pointer to the error string, which must be freed with [`bfree()`](reference-libobs-util-bmem#c.bfree "bfree") . If _NULL_, this parameter is ignored. Returns: The effect object, or _NULL_ on error * * * [gs\_effect\_t](#c.gs_effect_t "gs_effect_t") \*gs\_effect\_create(const char \*effect\_string, const char \*filename, char \*\*error\_string)[](#c.gs_effect_create "Link to this definition") Creates an effect from a string. Parameters: * **effect\_String** – Effect string * **error\_string** – Receives a pointer to the error string, which must be freed with [`bfree()`](reference-libobs-util-bmem#c.bfree "bfree") . If _NULL_, this parameter is ignored. Returns: The effect object, or _NULL_ on error * * * void gs\_effect\_destroy([gs\_effect\_t](#c.gs_effect_t "gs_effect_t") \*effect)[](#c.gs_effect_destroy "Link to this definition") Destroys the effect Parameters: * **effect** – Effect object * * * [gs\_technique\_t](#c.gs_technique_t "gs_technique_t") \*gs\_effect\_get\_technique(const [gs\_effect\_t](#c.gs_effect_t "gs_effect_t") \*effect, const char \*name)[](#c.gs_effect_get_technique "Link to this definition") Gets a technique of the effect. Parameters: * **effect** – Effect object * **name** – Name of the technique Returns: Technique object, or _NULL_ if not found * * * [gs\_technique\_t](#c.gs_technique_t "gs_technique_t") \*gs\_effect\_get\_current\_technique(const [gs\_effect\_t](#c.gs_effect_t "gs_effect_t") \*effect)[](#c.gs_effect_get_current_technique "Link to this definition") Gets the current active technique of the effect. Parameters: * **effect** – Effect object Returns: Technique object, or _NULL_ if none currently active * * * size\_t gs\_technique\_begin([gs\_technique\_t](#c.gs_technique_t "gs_technique_t") \*technique)[](#c.gs_technique_begin "Link to this definition") Begins a technique. Parameters: * **technique** – Technique object Returns: Number of passes this technique uses * * * void gs\_technique\_end([gs\_technique\_t](#c.gs_technique_t "gs_technique_t") \*technique)[](#c.gs_technique_end "Link to this definition") Ends a technique. Make sure all active passes have been ended before calling. Parameters: * **technique** – Technique object * * * bool gs\_technique\_begin\_pass([gs\_technique\_t](#c.gs_technique_t "gs_technique_t") \*technique, size\_t pass)[](#c.gs_technique_begin_pass "Link to this definition") Begins a pass. Automatically loads the vertex/pixel shaders associated with this pass. Draw after calling this function. Parameters: * **technique** – Technique object * **pass** – Pass index Returns: _true_ if the pass is valid, _false_ otherwise * * * bool gs\_technique\_begin\_pass\_by\_name([gs\_technique\_t](#c.gs_technique_t "gs_technique_t") \*technique, const char \*name)[](#c.gs_technique_begin_pass_by_name "Link to this definition") 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. Parameters: * **technique** – Technique object * **name** – Name of the pass Returns: _true_ if the pass is valid, _false_ otherwise * * * void gs\_technique\_end\_pass([gs\_technique\_t](#c.gs_technique_t "gs_technique_t") \*technique)[](#c.gs_technique_end_pass "Link to this definition") Ends a pass. Parameters: * **technique** – Technique object * * * size\_t gs\_effect\_get\_num\_params(const [gs\_effect\_t](#c.gs_effect_t "gs_effect_t") \*effect)[](#c.gs_effect_get_num_params "Link to this definition") Gets the number of parameters associated with the effect. Parameters: * **effect** – Effect object Returns: Number of parameters the effect has * * * [gs\_eparam\_t](#c.gs_eparam_t "gs_eparam_t") \*gs\_effect\_get\_param\_by\_idx(const [gs\_effect\_t](#c.gs_effect_t "gs_effect_t") \*effect, size\_t param)[](#c.gs_effect_get_param_by_idx "Link to this definition") Gets a parameter of an effect by its index. Parameters: * **effect** – Effect object * **param** – Parameter index Returns: The effect parameter object, or _NULL_ if index invalid * * * [gs\_eparam\_t](#c.gs_eparam_t "gs_eparam_t") \*gs\_effect\_get\_param\_by\_name(const [gs\_effect\_t](#c.gs_effect_t "gs_effect_t") \*effect, const char \*name)[](#c.gs_effect_get_param_by_name "Link to this definition") Gets parameter of an effect by its name. Parameters: * **effect** – Effect object * **name** – Name of the parameter Returns: The effect parameter object, or _NULL_ if not found * * * size\_t gs\_param\_get\_num\_annotations(const [gs\_eparam\_t](#c.gs_eparam_t "gs_eparam_t") \*param)[](#c.gs_param_get_num_annotations "Link to this definition") Gets the number of annotations associated with the parameter. Parameters: * **param** – Param object Returns: Number of annotations the param has * * * [gs\_eparam\_t](#c.gs_eparam_t "gs_eparam_t") \*gs\_param\_get\_annotation\_by\_idx(const [gs\_eparam\_t](#c.gs_eparam_t "gs_eparam_t") \*param, size\_t annotation)[](#c.gs_param_get_annotation_by_idx "Link to this definition") Gets an annotation of a param by its index. Parameters: * **param** – Param object * **param** – Annotation index Returns: The effect parameter object (annotation), or _NULL_ if index invalid * * * [gs\_eparam\_t](#c.gs_eparam_t "gs_eparam_t") \*gs\_param\_get\_annotation\_by\_name(const [gs\_eparam\_t](#c.gs_eparam_t "gs_eparam_t") \*param, const char \*annotation)[](#c.gs_param_get_annotation_by_name "Link to this definition") Gets parameter of an effect by its name. Parameters: * **param** – Param object * **name** – Name of the annotation Returns: The effect parameter object (annotation), or _NULL_ if not found * * * bool gs\_effect\_loop([gs\_effect\_t](#c.gs_effect_t "gs_effect_t") \*effect, const char \*name)[](#c.gs_effect_loop "Link to this definition") Helper function that automatically begins techniques/passes. Parameters: * **effect** – Effect object * **name** – Name of the technique to execute Returns: _true_ to draw, _false_ when complete Here is an example of how this function is typically used: for (gs\_effect\_loop(effect, "my\_technique")) { /\* perform drawing here \*/ \[...\] } * * * [gs\_eparam\_t](#c.gs_eparam_t "gs_eparam_t") \*gs\_effect\_get\_viewproj\_matrix(const [gs\_effect\_t](#c.gs_effect_t "gs_effect_t") \*effect)[](#c.gs_effect_get_viewproj_matrix "Link to this definition") Gets the view/projection matrix parameter (“viewproj”) of the effect. Parameters: * **effect** – Effect object Returns: The view/projection matrix parameter of the effect * * * [gs\_eparam\_t](#c.gs_eparam_t "gs_eparam_t") \*gs\_effect\_get\_world\_matrix(const [gs\_effect\_t](#c.gs_effect_t "gs_effect_t") \*effect)[](#c.gs_effect_get_world_matrix "Link to this definition") Gets the world matrix parameter (“world”) of the effect. Parameters: * **effect** – Effect object Returns: The world matrix parameter of the effect * * * void gs\_effect\_get\_param\_info(const [gs\_eparam\_t](#c.gs_eparam_t "gs_eparam_t") \*param, struct gs\_effect\_param\_info \*info)[](#c.gs_effect_get_param_info "Link to this definition") Gets information about an effect parameter. Parameters: * **param** – Effect parameter * **info** – Pointer to receive the data Relevant data types used with this function: 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; } * * * void gs\_effect\_set\_bool([gs\_eparam\_t](#c.gs_eparam_t "gs_eparam_t") \*param, bool val)[](#c.gs_effect_set_bool "Link to this definition") Sets a boolean parameter. Parameters: * **param** – Effect parameter * **val** – Boolean value * * * void gs\_effect\_set\_float([gs\_eparam\_t](#c.gs_eparam_t "gs_eparam_t") \*param, float val)[](#c.gs_effect_set_float "Link to this definition") Sets a floating point parameter. Parameters: * **param** – Effect parameter * **val** – Floating point value * * * void gs\_effect\_set\_int([gs\_eparam\_t](#c.gs_eparam_t "gs_eparam_t") \*param, int val)[](#c.gs_effect_set_int "Link to this definition") Sets a integer parameter. Parameters: * **param** – Effect parameter * **val** – Integer value * * * void gs\_effect\_set\_matrix4([gs\_eparam\_t](#c.gs_eparam_t "gs_eparam_t") \*param, const struct [matrix4](reference-libobs-graphics-matrix4#c.matrix4 "matrix4") \*val)[](#c.gs_effect_set_matrix4 "Link to this definition") Sets a matrix parameter. Parameters: * **param** – Effect parameter * **val** – Matrix * * * void gs\_effect\_set\_vec2([gs\_eparam\_t](#c.gs_eparam_t "gs_eparam_t") \*param, const struct [vec2](reference-libobs-graphics-vec2#c.vec2 "vec2") \*val)[](#c.gs_effect_set_vec2 "Link to this definition") Sets a 2-component vector parameter. Parameters: * **param** – Effect parameter * **val** – Vector * * * void gs\_effect\_set\_vec3([gs\_eparam\_t](#c.gs_eparam_t "gs_eparam_t") \*param, const struct [vec3](reference-libobs-graphics-vec3#c.vec3 "vec3") \*val)[](#c.gs_effect_set_vec3 "Link to this definition") Sets a 3-component vector parameter. Parameters: * **param** – Effect parameter * **val** – Vector * * * void gs\_effect\_set\_vec4([gs\_eparam\_t](#c.gs_eparam_t "gs_eparam_t") \*param, const struct [vec4](reference-libobs-graphics-vec4#c.vec4 "vec4") \*val)[](#c.gs_effect_set_vec4 "Link to this definition") Sets a 4-component vector parameter. Parameters: * **param** – Effect parameter * **val** – Vector * * * void gs\_effect\_set\_color([gs\_eparam\_t](#c.gs_eparam_t "gs_eparam_t") \*param, uint32\_t argb)[](#c.gs_effect_set_color "Link to this definition") Convenience function for setting a color value via an integer value. Parameters: * **param** – Effect parameter * **argb** – Integer color value (i.e. hex value would be 0xAARRGGBB) * * * void gs\_effect\_set\_texture([gs\_eparam\_t](#c.gs_eparam_t "gs_eparam_t") \*param, [gs\_texture\_t](reference-libobs-graphics-graphics#c.gs_texture_t "gs_texture_t") \*val)[](#c.gs_effect_set_texture "Link to this definition") Sets a texture parameter. Parameters: * **param** – Effect parameter * **val** – Texture * * * void gs\_effect\_set\_texture\_srgb([gs\_eparam\_t](#c.gs_eparam_t "gs_eparam_t") \*param, [gs\_texture\_t](reference-libobs-graphics-graphics#c.gs_texture_t "gs_texture_t") \*val)[](#c.gs_effect_set_texture_srgb "Link to this definition") Sets a texture parameter using SRGB view if available. Parameters: * **param** – Effect parameter * **val** – Texture * * * void gs\_effect\_set\_val([gs\_eparam\_t](#c.gs_eparam_t "gs_eparam_t") \*param, const void \*val, size\_t size)[](#c.gs_effect_set_val "Link to this definition") Sets a parameter with data manually. Parameters: * **param** – Effect parameter * **val** – Pointer to data * **size** – Size of data * * * void gs\_effect\_set\_default([gs\_eparam\_t](#c.gs_eparam_t "gs_eparam_t") \*param)[](#c.gs_effect_set_default "Link to this definition") Sets the parameter to its default value Param: Effect parameter * * * void gs\_effect\_set\_next\_sampler([gs\_eparam\_t](#c.gs_eparam_t "gs_eparam_t") \*param, [gs\_samplerstate\_t](reference-libobs-graphics-graphics#c.gs_samplerstate_t "gs_samplerstate_t") \*sampler)[](#c.gs_effect_set_next_sampler "Link to this definition") Manually changes the sampler for an effect parameter the next time it’s used. Parameters: * **param** – Effect parameter * **sampler** – Sampler state object * * * void \*gs\_effect\_get\_val([gs\_eparam\_t](#c.gs_eparam_t "gs_eparam_t") \*param)[](#c.gs_effect_get_val "Link to this definition") Returns a copy of the param’s current value. Parameters: * **param** – Effect parameter Returns: A pointer to the copied byte value of the param’s current value. Freed with [`bfree()`](reference-libobs-util-bmem#c.bfree "bfree") . * * * void gs\_effect\_get\_default\_val([gs\_eparam\_t](#c.gs_eparam_t "gs_eparam_t") \*param)[](#c.gs_effect_get_default_val "Link to this definition") Returns a copy of the param’s default value. Parameters: * **param** – Effect parameter Returns: A pointer to the copied byte value of the param’s default value. Freed with [`bfree()`](reference-libobs-util-bmem#c.bfree "bfree") . * * * size\_t gs\_effect\_get\_val\_size([gs\_eparam\_t](#c.gs_eparam_t "gs_eparam_t") \*param)[](#c.gs_effect_get_val_size "Link to this definition") Returns the size in bytes of the param’s current value. Parameters: * **param** – Effect parameter Returns: The size in bytes of the param’s current value. * * * size\_t gs\_effect\_get\_default\_val\_size([gs\_eparam\_t](#c.gs_eparam_t "gs_eparam_t") \*param)[](#c.gs_effect_get_default_val_size "Link to this definition") Returns the size in bytes of the param’s default value. Parameters: * **param** – Effect parameter Returns: The size in bytes of the param’s default value. --- # 2-Component Vector — OBS Studio 31.0.2 documentation * [](index) * [Graphics API Reference (libobs/graphics)](reference-libobs-graphics) * 2-Component Vector * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/reference-libobs-graphics-vec2.rst) [Previous](reference-libobs-graphics-effects "Effects (Shaders)") [Next](reference-libobs-graphics-vec3 "3-Component Vector") * * * 2-Component Vector[](#component-vector "Link to this heading") ================================================================ #include struct vec2[](#c.vec2 "Link to this definition") Two component vector structure. float [vec2](#c.vec2 "vec2") .x[](#c.vec2.x "Link to this definition") X component float [vec2](#c.vec2 "vec2") .y[](#c.vec2.y "Link to this definition") Y component float [vec2](#c.vec2 "vec2") .ptr\[2\][](#c.vec2.ptr "Link to this definition") Unioned array of both components * * * void vec2\_zero(struct [vec2](#c.vec2 "vec2") \*dst)[](#c.vec2_zero "Link to this definition") Zeroes a vector Parameters: * **dst** – Destination * * * void vec2\_set(struct [vec2](#c.vec2 "vec2") \*dst, float x, float y)[](#c.vec2_set "Link to this definition") Sets the individual components of a 2-component vector. Parameters: * **dst** – Destination * **x** – X component * **y** – Y component * * * void vec2\_copy(struct [vec2](#c.vec2 "vec2") \*dst, const struct [vec2](#c.vec2 "vec2") \*v)[](#c.vec2_copy "Link to this definition") Copies a vector Parameters: * **dst** – Destination * **v** – Vector to copy * * * void vec2\_add(struct [vec2](#c.vec2 "vec2") \*dst, const struct [vec2](#c.vec2 "vec2") \*v1, const struct [vec2](#c.vec2 "vec2") \*v2)[](#c.vec2_add "Link to this definition") Adds two vectors Parameters: * **dst** – Destination * **v1** – Vector 1 * **v2** – Vector 2 * * * void vec2\_sub(struct [vec2](#c.vec2 "vec2") \*dst, const struct [vec2](#c.vec2 "vec2") \*v1, const struct [vec2](#c.vec2 "vec2") \*v2)[](#c.vec2_sub "Link to this definition") Subtracts two vectors Parameters: * **dst** – Destination * **v1** – Vector being subtracted from * **v2** – Vector being subtracted * * * void vec2\_mul(struct [vec2](#c.vec2 "vec2") \*dst, const struct [vec2](#c.vec2 "vec2") \*v1, const struct [vec2](#c.vec2 "vec2") \*v2)[](#c.vec2_mul "Link to this definition") Multiplies two vectors Parameters: * **dst** – Destination * **v1** – Vector 1 * **v2** – Vector 2 * * * void vec2\_div(struct [vec2](#c.vec2 "vec2") \*dst, const struct [vec2](#c.vec2 "vec2") \*v1, const struct [vec2](#c.vec2 "vec2") \*v2)[](#c.vec2_div "Link to this definition") Divides two vectors Parameters: * **dst** – Destination * **v1** – Dividend * **v2** – Divisor * * * void vec2\_addf(struct [vec2](#c.vec2 "vec2") \*dst, const struct [vec2](#c.vec2 "vec2") \*v, float f)[](#c.vec2_addf "Link to this definition") Adds a floating point to all components Parameters: * **dst** – Destination * **dst** – Vector * **f** – Floating point * * * void vec2\_subf(struct [vec2](#c.vec2 "vec2") \*dst, const struct [vec2](#c.vec2 "vec2") \*v, float f)[](#c.vec2_subf "Link to this definition") Subtracts a floating point from all components Parameters: * **dst** – Destination * **v** – Vector being subtracted from * **f** – Floating point being subtracted * * * void vec2\_mulf(struct [vec2](#c.vec2 "vec2") \*dst, const struct [vec2](#c.vec2 "vec2") \*v, float f)[](#c.vec2_mulf "Link to this definition") Multiplies a floating point with all components Parameters: * **dst** – Destination * **dst** – Vector * **f** – Floating point * * * void vec2\_divf(struct [vec2](#c.vec2 "vec2") \*dst, const struct [vec2](#c.vec2 "vec2") \*v, float f)[](#c.vec2_divf "Link to this definition") Divides a floating point from all components Parameters: * **dst** – Destination * **v** – Vector (dividend) * **f** – Floating point (divisor) * * * void vec2\_neg(struct [vec2](#c.vec2 "vec2") \*dst, const struct [vec2](#c.vec2 "vec2") \*v)[](#c.vec2_neg "Link to this definition") Negates a vector Parameters: * **dst** – Destination * **v** – Vector to negate * * * float vec2\_dot(const struct [vec2](#c.vec2 "vec2") \*v1, const struct [vec2](#c.vec2 "vec2") \*v2)[](#c.vec2_dot "Link to this definition") Performs a dot product between two vectors Parameters: * **v1** – Vector 1 * **v2** – Vector 2 Returns: Result of the dot product * * * float vec2\_len(const struct [vec2](#c.vec2 "vec2") \*v)[](#c.vec2_len "Link to this definition") Gets the length of a vector Parameters: * **v** – Vector Returns: The vector’s length * * * float vec2\_dist(const struct [vec2](#c.vec2 "vec2") \*v1, const struct [vec2](#c.vec2 "vec2") \*v2)[](#c.vec2_dist "Link to this definition") Gets the distance between two vectors Parameters: * **v1** – Vector 1 * **v2** – Vector 2 Returns: Distance between the two vectors * * * void vec2\_minf(struct [vec2](#c.vec2 "vec2") \*dst, const struct [vec2](#c.vec2 "vec2") \*v, float val)[](#c.vec2_minf "Link to this definition") Gets the minimum values between a vector’s components and a floating point Parameters: * **dst** – Destination * **v** – Vector * **val** – Floating point * * * void vec2\_min(struct [vec2](#c.vec2 "vec2") \*dst, const struct [vec2](#c.vec2 "vec2") \*v, const struct [vec2](#c.vec2 "vec2") \*min\_v)[](#c.vec2_min "Link to this definition") Gets the minimum values between two vectors Parameters: * **dst** – Destination * **v** – Vector 1 * **min\_v** – Vector 2 * * * void vec2\_maxf(struct [vec2](#c.vec2 "vec2") \*dst, const struct [vec2](#c.vec2 "vec2") \*v, float val)[](#c.vec2_maxf "Link to this definition") Gets the maximum values between a vector’s components and a floating point Parameters: * **dst** – Destination * **v** – Vector * **val** – Floating point * * * void vec2\_max(struct [vec2](#c.vec2 "vec2") \*dst, const struct [vec2](#c.vec2 "vec2") \*v, const struct [vec2](#c.vec2 "vec2") \*max\_v)[](#c.vec2_max "Link to this definition") Gets the maximum values between two vectors Parameters: * **dst** – Destination * **v** – Vector 1 * **max\_v** – Vector 2 * * * void vec2\_abs(struct [vec2](#c.vec2 "vec2") \*dst, const struct [vec2](#c.vec2 "vec2") \*v)[](#c.vec2_abs "Link to this definition") Gets the absolute values of each component Parameters: * **dst** – Destination * **v** – Vector * * * void vec2\_floor(struct [vec2](#c.vec2 "vec2") \*dst, const struct [vec2](#c.vec2 "vec2") \*v)[](#c.vec2_floor "Link to this definition") Gets the floor values of each component Parameters: * **dst** – Destination * **v** – Vector * * * void vec2\_ceil(struct [vec2](#c.vec2 "vec2") \*dst, const struct [vec2](#c.vec2 "vec2") \*v)[](#c.vec2_ceil "Link to this definition") Gets the ceiling values of each component Parameters: * **dst** – Destination * **v** – Vector * * * int vec2\_close(const struct [vec2](#c.vec2 "vec2") \*v1, const struct [vec2](#c.vec2 "vec2") \*v2, float epsilon)[](#c.vec2_close "Link to this definition") Compares two vectors Parameters: * **v1** – Vector 1 * **v2** – Vector 2 * **epsilon** – Maximum precision for comparison * * * void vec2\_norm(struct [vec2](#c.vec2 "vec2") \*dst, const struct [vec2](#c.vec2 "vec2") \*v)[](#c.vec2_norm "Link to this definition") Normalizes a vector Parameters: * **dst** – Destination * **v** – Vector to normalize --- # 4-Component Vector — OBS Studio 31.0.2 documentation * [](index) * [Graphics API Reference (libobs/graphics)](reference-libobs-graphics) * 4-Component Vector * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/reference-libobs-graphics-vec4.rst) [Previous](reference-libobs-graphics-vec3 "3-Component Vector") [Next](reference-libobs-graphics-quat "Quaternion") * * * 4-Component Vector[](#component-vector "Link to this heading") ================================================================ #include struct vec4[](#c.vec4 "Link to this definition") Two component vector structure. float [vec4](#c.vec4 "vec4") .x[](#c.vec4.x "Link to this definition") X component float [vec4](#c.vec4 "vec4") .y[](#c.vec4.y "Link to this definition") Y component float [vec4](#c.vec4 "vec4") .z[](#c.vec4.z "Link to this definition") Z component float [vec4](#c.vec4 "vec4") .w[](#c.vec4.w "Link to this definition") W component float [vec4](#c.vec4 "vec4") .ptr\[4\][](#c.vec4.ptr "Link to this definition") Unioned array of all components * * * void vec4\_zero(struct [vec4](#c.vec4 "vec4") \*dst)[](#c.vec4_zero "Link to this definition") Zeroes a vector Parameters: * **dst** – Destination * * * void vec4\_set(struct [vec4](#c.vec4 "vec4") \*dst, float x, float y, float z, float w)[](#c.vec4_set "Link to this definition") Sets the individual components of a 4-component vector. Parameters: * **dst** – Destination * **x** – X component * **y** – Y component * **z** – Z component * **w** – W component * * * void vec4\_copy(struct [vec4](#c.vec4 "vec4") \*dst, const struct [vec4](#c.vec4 "vec4") \*v)[](#c.vec4_copy "Link to this definition") Copies a vector Parameters: * **dst** – Destination * **v** – Vector to copy * * * void vec4\_from\_vec3(struct [vec4](#c.vec4 "vec4") \*dst, const struct [vec3](reference-libobs-graphics-vec3#c.vec3 "vec3") \*v)[](#c.vec4_from_vec3 "Link to this definition") Creates a 4-component vector from a 3-component vector Parameters: * **dst** – 4-component vector destination * **v** – 3-component vector * * * void vec4\_add(struct [vec4](#c.vec4 "vec4") \*dst, const struct [vec4](#c.vec4 "vec4") \*v1, const struct [vec4](#c.vec4 "vec4") \*v2)[](#c.vec4_add "Link to this definition") Adds two vectors Parameters: * **dst** – Destination * **v1** – Vector 1 * **v2** – Vector 2 * * * void vec4\_sub(struct [vec4](#c.vec4 "vec4") \*dst, const struct [vec4](#c.vec4 "vec4") \*v1, const struct [vec4](#c.vec4 "vec4") \*v2)[](#c.vec4_sub "Link to this definition") Subtracts two vectors Parameters: * **dst** – Destination * **v1** – Vector being subtracted from * **v2** – Vector being subtracted * * * void vec4\_mul(struct [vec4](#c.vec4 "vec4") \*dst, const struct [vec4](#c.vec4 "vec4") \*v1, const struct [vec4](#c.vec4 "vec4") \*v2)[](#c.vec4_mul "Link to this definition") Multiplies two vectors Parameters: * **dst** – Destination * **v1** – Vector 1 * **v2** – Vector 2 * * * void vec4\_div(struct [vec4](#c.vec4 "vec4") \*dst, const struct [vec4](#c.vec4 "vec4") \*v1, const struct [vec4](#c.vec4 "vec4") \*v2)[](#c.vec4_div "Link to this definition") Divides two vectors Parameters: * **dst** – Destination * **v1** – Dividend * **v2** – Divisor * * * void vec4\_addf(struct [vec4](#c.vec4 "vec4") \*dst, const struct [vec4](#c.vec4 "vec4") \*v, float f)[](#c.vec4_addf "Link to this definition") Adds a floating point to all components Parameters: * **dst** – Destination * **dst** – Vector * **f** – Floating point * * * void vec4\_subf(struct [vec4](#c.vec4 "vec4") \*dst, const struct [vec4](#c.vec4 "vec4") \*v, float f)[](#c.vec4_subf "Link to this definition") Subtracts a floating point from all components Parameters: * **dst** – Destination * **v** – Vector being subtracted from * **f** – Floating point being subtracted * * * void vec4\_mulf(struct [vec4](#c.vec4 "vec4") \*dst, const struct [vec4](#c.vec4 "vec4") \*v, float f)[](#c.vec4_mulf "Link to this definition") Multiplies a floating point with all components Parameters: * **dst** – Destination * **dst** – Vector * **f** – Floating point * * * void vec4\_divf(struct [vec4](#c.vec4 "vec4") \*dst, const struct [vec4](#c.vec4 "vec4") \*v, float f)[](#c.vec4_divf "Link to this definition") Divides a floating point from all components Parameters: * **dst** – Destination * **v** – Vector (dividend) * **f** – Floating point (divisor) * * * void vec4\_neg(struct [vec4](#c.vec4 "vec4") \*dst, const struct [vec4](#c.vec4 "vec4") \*v)[](#c.vec4_neg "Link to this definition") Negates a vector Parameters: * **dst** – Destination * **v** – Vector to negate * * * float vec4\_dot(const struct [vec4](#c.vec4 "vec4") \*v1, const struct [vec4](#c.vec4 "vec4") \*v2)[](#c.vec4_dot "Link to this definition") Performs a dot product between two vectors Parameters: * **v1** – Vector 1 * **v2** – Vector 2 Returns: Result of the dot product * * * float vec4\_len(const struct [vec4](#c.vec4 "vec4") \*v)[](#c.vec4_len "Link to this definition") Gets the length of a vector Parameters: * **v** – Vector Returns: The vector’s length * * * float vec4\_dist(const struct [vec4](#c.vec4 "vec4") \*v1, const struct [vec4](#c.vec4 "vec4") \*v2)[](#c.vec4_dist "Link to this definition") Gets the distance between two vectors Parameters: * **v1** – Vector 1 * **v2** – Vector 2 Returns: Distance between the two vectors * * * void vec4\_minf(struct [vec4](#c.vec4 "vec4") \*dst, const struct [vec4](#c.vec4 "vec4") \*v, float val)[](#c.vec4_minf "Link to this definition") Gets the minimum values between a vector’s components and a floating point Parameters: * **dst** – Destination * **v** – Vector * **val** – Floating point * * * void vec4\_min(struct [vec4](#c.vec4 "vec4") \*dst, const struct [vec4](#c.vec4 "vec4") \*v, const struct [vec4](#c.vec4 "vec4") \*min\_v)[](#c.vec4_min "Link to this definition") Gets the minimum values between two vectors Parameters: * **dst** – Destination * **v** – Vector 1 * **min\_v** – Vector 2 * * * void vec4\_maxf(struct [vec4](#c.vec4 "vec4") \*dst, const struct [vec4](#c.vec4 "vec4") \*v, float val)[](#c.vec4_maxf "Link to this definition") Gets the maximum values between a vector’s components and a floating point Parameters: * **dst** – Destination * **v** – Vector * **val** – Floating point * * * void vec4\_max(struct [vec4](#c.vec4 "vec4") \*dst, const struct [vec4](#c.vec4 "vec4") \*v, const struct [vec4](#c.vec4 "vec4") \*max\_v)[](#c.vec4_max "Link to this definition") Gets the maximum values between two vectors Parameters: * **dst** – Destination * **v** – Vector 1 * **max\_v** – Vector 2 * * * void vec4\_abs(struct [vec4](#c.vec4 "vec4") \*dst, const struct [vec4](#c.vec4 "vec4") \*v)[](#c.vec4_abs "Link to this definition") Gets the absolute values of each component Parameters: * **dst** – Destination * **v** – Vector * * * void vec4\_floor(struct [vec4](#c.vec4 "vec4") \*dst, const struct [vec4](#c.vec4 "vec4") \*v)[](#c.vec4_floor "Link to this definition") Gets the floor values of each component Parameters: * **dst** – Destination * **v** – Vector * * * void vec4\_ceil(struct [vec4](#c.vec4 "vec4") \*dst, const struct [vec4](#c.vec4 "vec4") \*v)[](#c.vec4_ceil "Link to this definition") Gets the ceiling values of each component Parameters: * **dst** – Destination * **v** – Vector * * * int vec4\_close(const struct [vec4](#c.vec4 "vec4") \*v1, const struct [vec4](#c.vec4 "vec4") \*v2, float epsilon)[](#c.vec4_close "Link to this definition") Compares two vectors Parameters: * **v1** – Vector 1 * **v2** – Vector 2 * **epsilon** – Maximum precision for comparison * * * void vec4\_norm(struct [vec4](#c.vec4 "vec4") \*dst, const struct [vec4](#c.vec4 "vec4") \*v)[](#c.vec4_norm "Link to this definition") Normalizes a vector Parameters: * **dst** – Destination * **v** – Vector to normalize * * * void vec4\_transform(struct [vec4](#c.vec4 "vec4") \*dst, const struct [vec4](#c.vec4 "vec4") \*v, const struct [matrix4](reference-libobs-graphics-matrix4#c.matrix4 "matrix4") \*m)[](#c.vec4_transform "Link to this definition") Transforms a vector Parameters: * **dst** – Destination * **v** – Vector * **m** – Matrix --- # Image File Helper — OBS Studio 31.0.2 documentation * [](index) * [Graphics API Reference (libobs/graphics)](reference-libobs-graphics) * Image File Helper * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/reference-libobs-graphics-image-file.rst) [Previous](reference-libobs-graphics-math "Extra Math Functions/Macros") [Next](reference-libobs-graphics-axisang "Axis Angle") * * * Image File Helper[](#image-file-helper "Link to this heading") ================================================================ Helper functions/type for easily loading/managing image files, including animated gif files. #include struct gs\_image\_file[](#c.gs_image_file "Link to this definition") Image file structure typedef [gs\_texture\_t](reference-libobs-graphics-graphics#c.gs_texture_t "gs_texture_t") \*[gs\_image\_file](#c.gs_image_file "gs_image_file") .texture[](#c.gs_image_file.texture "Link to this definition") Texture typedef struct [gs\_image\_file](#c.gs_image_file "gs_image_file") gs\_image\_file\_t[](#c.gs_image_file_t "Link to this definition") Image file type * * * void gs\_image\_file\_init([gs\_image\_file\_t](#c.gs_image_file_t "gs_image_file_t") \*image, const char \*file)[](#c.gs_image_file_init "Link to this definition") Loads an initializes an image file helper. Does not initialize the texture; call [`gs_image_file_init_texture()`](#c.gs_image_file_init_texture "gs_image_file_init_texture") to initialize the texture. Parameters: * **image** – Image file helper to initialize * **file** – Path to the image file to load * * * void gs\_image\_file\_free([gs\_image\_file\_t](#c.gs_image_file_t "gs_image_file_t") \*image)[](#c.gs_image_file_free "Link to this definition") Frees an image file helper Parameters: * **image** – Image file helper * * * void gs\_image\_file\_init\_texture([gs\_image\_file\_t](#c.gs_image_file_t "gs_image_file_t") \*image)[](#c.gs_image_file_init_texture "Link to this definition") Initializes the texture of an image file helper. This is separate from [`gs_image_file_init()`](#c.gs_image_file_init "gs_image_file_init") because it allows deferring the graphics initialization if needed. Parameters: * **image** – Image file helper * * * bool gs\_image\_file\_tick([gs\_image\_file\_t](#c.gs_image_file_t "gs_image_file_t") \*image, uint64\_t elapsed\_time\_ns)[](#c.gs_image_file_tick "Link to this definition") Performs a tick operation on the image file helper (used primarily for animated file). Does not update the texture until [`gs_image_file_update_texture()`](#c.gs_image_file_update_texture "gs_image_file_update_texture") is called. Parameters: * **image** – Image file helper * **elapsed\_time\_ns** – Elapsed time in nanoseconds * * * void gs\_image\_file\_update\_texture([gs\_image\_file\_t](#c.gs_image_file_t "gs_image_file_t") \*image)[](#c.gs_image_file_update_texture "Link to this definition") Updates the texture (used primarily for animated files) Parameters: * **image** – Image file helper --- # Matrix — OBS Studio 31.0.2 documentation * [](index) * [Graphics API Reference (libobs/graphics)](reference-libobs-graphics) * Matrix * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/reference-libobs-graphics-matrix4.rst) [Previous](reference-libobs-graphics-quat "Quaternion") [Next](reference-libobs-graphics-math "Extra Math Functions/Macros") * * * Matrix[](#matrix "Link to this heading") ========================================== #include struct matrix4[](#c.matrix4 "Link to this definition") Matrix structure struct [vec4](reference-libobs-graphics-vec4#c.vec4 "vec4") [matrix4](#c.matrix4 "matrix4") .x[](#c.matrix4.x "Link to this definition") X component vector struct [vec4](reference-libobs-graphics-vec4#c.vec4 "vec4") [matrix4](#c.matrix4 "matrix4") .y[](#c.matrix4.y "Link to this definition") Y component vector struct [vec4](reference-libobs-graphics-vec4#c.vec4 "vec4") [matrix4](#c.matrix4 "matrix4") .z[](#c.matrix4.z "Link to this definition") Z component vector struct [vec4](reference-libobs-graphics-vec4#c.vec4 "vec4") [matrix4](#c.matrix4 "matrix4") .w[](#c.matrix4.w "Link to this definition") W component vector * * * void matrix4\_copy(struct [matrix4](#c.matrix4 "matrix4") \*dst, const struct [matrix4](#c.matrix4 "matrix4") \*m)[](#c.matrix4_copy "Link to this definition") Copies a matrix Parameters: * **dst** – Destination matrix * **m** – Matrix to copy * * * void matrix4\_identity(struct [matrix4](#c.matrix4 "matrix4") \*dst)[](#c.matrix4_identity "Link to this definition") Sets an identity matrix Parameters: * **dst** – Destination matrix * * * void matrix4\_from\_quat(struct [matrix4](#c.matrix4 "matrix4") \*dst, const struct [quat](reference-libobs-graphics-quat#c.quat "quat") \*q)[](#c.matrix4_from_quat "Link to this definition") Converts a quaternion to a matrix Parameters: * **dst** – Destination matrix * **q** – Quaternion to convert * * * void matrix4\_from\_axisang(struct [matrix4](#c.matrix4 "matrix4") \*dst, const struct [axisang](reference-libobs-graphics-axisang#c.axisang "axisang") \*aa)[](#c.matrix4_from_axisang "Link to this definition") Converts an axis angle to a matrix Parameters: * **dst** – Destination matrix * **aa** – Axis angle to convert * * * void matrix4\_mul(struct [matrix4](#c.matrix4 "matrix4") \*dst, const struct [matrix4](#c.matrix4 "matrix4") \*m1, const struct [matrix4](#c.matrix4 "matrix4") \*m2)[](#c.matrix4_mul "Link to this definition") Multiples two matrices Parameters: * **dst** – Destination matrix * **m1** – Matrix 1 * **m2** – Matrix 2 * * * float matrix4\_determinant(const struct [matrix4](#c.matrix4 "matrix4") \*m)[](#c.matrix4_determinant "Link to this definition") Gets the determinant value of a matrix Parameters: * **m** – Matrix Returns: Determinant * * * void matrix4\_translate3v(struct [matrix4](#c.matrix4 "matrix4") \*dst, const struct [matrix4](#c.matrix4 "matrix4") \*m, const struct [vec3](reference-libobs-graphics-vec3#c.vec3 "vec3") \*v)[](#c.matrix4_translate3v "Link to this definition") void matrix4\_translate3f(struct [matrix4](#c.matrix4 "matrix4") \*dst, const struct [matrix4](#c.matrix4 "matrix4") \*m, float x, float y, float z)[](#c.matrix4_translate3f "Link to this definition") Translates the matrix by a 3-component vector Parameters: * **dst** – Destination matrix * **m** – Matrix to translate * **v** – Translation vector * * * void matrix4\_translate4v(struct [matrix4](#c.matrix4 "matrix4") \*dst, const struct [matrix4](#c.matrix4 "matrix4") \*m, const struct [vec4](reference-libobs-graphics-vec4#c.vec4 "vec4") \*v)[](#c.matrix4_translate4v "Link to this definition") Translates the matrix by a 4-component vector Parameters: * **dst** – Destination matrix * **m** – Matrix to translate * **v** – Translation vector * * * void matrix4\_rotate(struct [matrix4](#c.matrix4 "matrix4") \*dst, const struct [matrix4](#c.matrix4 "matrix4") \*m, const struct [quat](reference-libobs-graphics-quat#c.quat "quat") \*q)[](#c.matrix4_rotate "Link to this definition") Rotates a matrix by a quaternion Parameters: * **dst** – Destination matrix * **m** – Matrix to rotate * **q** – Rotation quaternion * * * void matrix4\_rotate\_aa(struct [matrix4](#c.matrix4 "matrix4") \*dst, const struct [matrix4](#c.matrix4 "matrix4") \*m, const struct [axisang](reference-libobs-graphics-axisang#c.axisang "axisang") \*aa)[](#c.matrix4_rotate_aa "Link to this definition") void matrix4\_rotate\_aa4f(struct [matrix4](#c.matrix4 "matrix4") \*dst, const struct [matrix4](#c.matrix4 "matrix4") \*m, float x, float y, float z, float rot)[](#c.matrix4_rotate_aa4f "Link to this definition") Rotates a matrix by an axis angle Parameters: * **dst** – Destination matrix * **m** – Matrix to rotate * **aa** – Rotation anxis angle * * * void matrix4\_scale(struct [matrix4](#c.matrix4 "matrix4") \*dst, const struct [matrix4](#c.matrix4 "matrix4") \*m, const struct [vec3](reference-libobs-graphics-vec3#c.vec3 "vec3") \*v)[](#c.matrix4_scale "Link to this definition") void matrix4\_scale3f(struct [matrix4](#c.matrix4 "matrix4") \*dst, const struct [matrix4](#c.matrix4 "matrix4") \*m, float x, float y, float z)[](#c.matrix4_scale3f "Link to this definition") Scales each matrix component by the components of a 3-component vector Parameters: * **dst** – Destination matrix * **m** – Matrix to scale * **v** – Scale vector * * * bool matrix4\_inv(struct [matrix4](#c.matrix4 "matrix4") \*dst, const struct [matrix4](#c.matrix4 "matrix4") \*m)[](#c.matrix4_inv "Link to this definition") Inverts a matrix Parameters: * **dst** – Destination matrix * **m** – Matrix to invert * * * void matrix4\_transpose(struct [matrix4](#c.matrix4 "matrix4") \*dst, const struct [matrix4](#c.matrix4 "matrix4") \*m)[](#c.matrix4_transpose "Link to this definition") Transposes a matrix Parameters: * **dst** – Destination matrix * **m** – Matrix to transpose --- # 3-Component Vector — OBS Studio 31.0.2 documentation * [](index) * [Graphics API Reference (libobs/graphics)](reference-libobs-graphics) * 3-Component Vector * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/reference-libobs-graphics-vec3.rst) [Previous](reference-libobs-graphics-vec2 "2-Component Vector") [Next](reference-libobs-graphics-vec4 "4-Component Vector") * * * 3-Component Vector[](#component-vector "Link to this heading") ================================================================ #include struct vec3[](#c.vec3 "Link to this definition") Two component vector structure. float [vec3](#c.vec3 "vec3") .x[](#c.vec3.x "Link to this definition") X component float [vec3](#c.vec3 "vec3") .y[](#c.vec3.y "Link to this definition") Y component float [vec3](#c.vec3 "vec3") .z[](#c.vec3.z "Link to this definition") Z component float [vec3](#c.vec3 "vec3") .ptr\[3\][](#c.vec3.ptr "Link to this definition") Unioned array of all components * * * void vec3\_zero(struct [vec3](#c.vec3 "vec3") \*dst)[](#c.vec3_zero "Link to this definition") Zeroes a vector Parameters: * **dst** – Destination * * * void vec3\_set(struct [vec3](#c.vec3 "vec3") \*dst, float x, float y)[](#c.vec3_set "Link to this definition") Sets the individual components of a 3-component vector. Parameters: * **dst** – Destination * **x** – X component * **y** – Y component * **y** – Z component * * * void vec3\_copy(struct [vec3](#c.vec3 "vec3") \*dst, const struct [vec3](#c.vec3 "vec3") \*v)[](#c.vec3_copy "Link to this definition") Copies a vector Parameters: * **dst** – Destination * **v** – Vector to copy * * * void vec3\_from\_vec4(struct [vec3](#c.vec3 "vec3") \*dst, const struct [vec4](reference-libobs-graphics-vec4#c.vec4 "vec4") \*v)[](#c.vec3_from_vec4 "Link to this definition") Creates a 3-component vector from a 4-component vector Parameters: * **dst** – 3-component vector destination * **v** – 4-component vector * * * void vec3\_add(struct [vec3](#c.vec3 "vec3") \*dst, const struct [vec3](#c.vec3 "vec3") \*v1, const struct [vec3](#c.vec3 "vec3") \*v2)[](#c.vec3_add "Link to this definition") Adds two vectors Parameters: * **dst** – Destination * **v1** – Vector 1 * **v2** – Vector 2 * * * void vec3\_sub(struct [vec3](#c.vec3 "vec3") \*dst, const struct [vec3](#c.vec3 "vec3") \*v1, const struct [vec3](#c.vec3 "vec3") \*v2)[](#c.vec3_sub "Link to this definition") Subtracts two vectors Parameters: * **dst** – Destination * **v1** – Vector being subtracted from * **v2** – Vector being subtracted * * * void vec3\_mul(struct [vec3](#c.vec3 "vec3") \*dst, const struct [vec3](#c.vec3 "vec3") \*v1, const struct [vec3](#c.vec3 "vec3") \*v2)[](#c.vec3_mul "Link to this definition") Multiplies two vectors Parameters: * **dst** – Destination * **v1** – Vector 1 * **v2** – Vector 2 * * * void vec3\_div(struct [vec3](#c.vec3 "vec3") \*dst, const struct [vec3](#c.vec3 "vec3") \*v1, const struct [vec3](#c.vec3 "vec3") \*v2)[](#c.vec3_div "Link to this definition") Divides two vectors Parameters: * **dst** – Destination * **v1** – Dividend * **v2** – Divisor * * * void vec3\_addf(struct [vec3](#c.vec3 "vec3") \*dst, const struct [vec3](#c.vec3 "vec3") \*v, float f)[](#c.vec3_addf "Link to this definition") Adds a floating point to all components Parameters: * **dst** – Destination * **dst** – Vector * **f** – Floating point * * * void vec3\_subf(struct [vec3](#c.vec3 "vec3") \*dst, const struct [vec3](#c.vec3 "vec3") \*v, float f)[](#c.vec3_subf "Link to this definition") Subtracts a floating point from all components Parameters: * **dst** – Destination * **v** – Vector being subtracted from * **f** – Floating point being subtracted * * * void vec3\_mulf(struct [vec3](#c.vec3 "vec3") \*dst, const struct [vec3](#c.vec3 "vec3") \*v, float f)[](#c.vec3_mulf "Link to this definition") Multiplies a floating point with all components Parameters: * **dst** – Destination * **dst** – Vector * **f** – Floating point * * * void vec3\_divf(struct [vec3](#c.vec3 "vec3") \*dst, const struct [vec3](#c.vec3 "vec3") \*v, float f)[](#c.vec3_divf "Link to this definition") Divides a floating point from all components Parameters: * **dst** – Destination * **v** – Vector (dividend) * **f** – Floating point (divisor) * * * void vec3\_neg(struct [vec3](#c.vec3 "vec3") \*dst, const struct [vec3](#c.vec3 "vec3") \*v)[](#c.vec3_neg "Link to this definition") Negates a vector Parameters: * **dst** – Destination * **v** – Vector to negate * * * float vec3\_dot(const struct [vec3](#c.vec3 "vec3") \*v1, const struct [vec3](#c.vec3 "vec3") \*v2)[](#c.vec3_dot "Link to this definition") Performs a dot product between two vectors Parameters: * **v1** – Vector 1 * **v2** – Vector 2 Returns: Result of the dot product * * * void vec3\_cross(struct [vec3](#c.vec3 "vec3") \*dst, const struct [vec3](#c.vec3 "vec3") \*v1, const struct [vec3](#c.vec3 "vec3") \*v2)[](#c.vec3_cross "Link to this definition") Performs a cross product between two vectors Parameters: * **dst** – Destination * **v1** – Vector 1 * **v2** – Vector 2 * * * float vec3\_len(const struct [vec3](#c.vec3 "vec3") \*v)[](#c.vec3_len "Link to this definition") Gets the length of a vector Parameters: * **v** – Vector Returns: The vector’s length * * * float vec3\_dist(const struct [vec3](#c.vec3 "vec3") \*v1, const struct [vec3](#c.vec3 "vec3") \*v2)[](#c.vec3_dist "Link to this definition") Gets the distance between two vectors Parameters: * **v1** – Vector 1 * **v2** – Vector 2 Returns: Distance between the two vectors * * * void vec3\_minf(struct [vec3](#c.vec3 "vec3") \*dst, const struct [vec3](#c.vec3 "vec3") \*v, float val)[](#c.vec3_minf "Link to this definition") Gets the minimum values between a vector’s components and a floating point Parameters: * **dst** – Destination * **v** – Vector * **val** – Floating point * * * void vec3\_min(struct [vec3](#c.vec3 "vec3") \*dst, const struct [vec3](#c.vec3 "vec3") \*v, const struct [vec3](#c.vec3 "vec3") \*min\_v)[](#c.vec3_min "Link to this definition") Gets the minimum values between two vectors Parameters: * **dst** – Destination * **v** – Vector 1 * **min\_v** – Vector 2 * * * void vec3\_maxf(struct [vec3](#c.vec3 "vec3") \*dst, const struct [vec3](#c.vec3 "vec3") \*v, float val)[](#c.vec3_maxf "Link to this definition") Gets the maximum values between a vector’s components and a floating point Parameters: * **dst** – Destination * **v** – Vector * **val** – Floating point * * * void vec3\_max(struct [vec3](#c.vec3 "vec3") \*dst, const struct [vec3](#c.vec3 "vec3") \*v, const struct [vec3](#c.vec3 "vec3") \*max\_v)[](#c.vec3_max "Link to this definition") Gets the maximum values between two vectors Parameters: * **dst** – Destination * **v** – Vector 1 * **max\_v** – Vector 2 * * * void vec3\_abs(struct [vec3](#c.vec3 "vec3") \*dst, const struct [vec3](#c.vec3 "vec3") \*v)[](#c.vec3_abs "Link to this definition") Gets the absolute values of each component Parameters: * **dst** – Destination * **v** – Vector * * * void vec3\_floor(struct [vec3](#c.vec3 "vec3") \*dst, const struct [vec3](#c.vec3 "vec3") \*v)[](#c.vec3_floor "Link to this definition") Gets the floor values of each component Parameters: * **dst** – Destination * **v** – Vector * * * void vec3\_ceil(struct [vec3](#c.vec3 "vec3") \*dst, const struct [vec3](#c.vec3 "vec3") \*v)[](#c.vec3_ceil "Link to this definition") Gets the ceiling values of each component Parameters: * **dst** – Destination * **v** – Vector * * * int vec3\_close(const struct [vec3](#c.vec3 "vec3") \*v1, const struct [vec3](#c.vec3 "vec3") \*v2, float epsilon)[](#c.vec3_close "Link to this definition") Compares two vectors Parameters: * **v1** – Vector 1 * **v2** – Vector 2 * **epsilon** – Maximum precision for comparison * * * void vec3\_norm(struct [vec3](#c.vec3 "vec3") \*dst, const struct [vec3](#c.vec3 "vec3") \*v)[](#c.vec3_norm "Link to this definition") Normalizes a vector Parameters: * **dst** – Destination * **v** – Vector to normalize * * * void vec3\_transform(struct [vec3](#c.vec3 "vec3") \*dst, const struct [vec3](#c.vec3 "vec3") \*v, const struct [matrix4](reference-libobs-graphics-matrix4#c.matrix4 "matrix4") \*m)[](#c.vec3_transform "Link to this definition") Transforms a vector Parameters: * **dst** – Destination * **v** – Vector * **m** – Matrix * * * void vec3\_rotate(struct [vec3](#c.vec3 "vec3") \*dst, const struct [vec3](#c.vec3 "vec3") \*v, const struct matrix3 \*m)[](#c.vec3_rotate "Link to this definition") Rotates a vector Parameters: * **dst** – Destination * **v** – Vector * **m** – Matrix * * * void vec3\_rand(struct [vec3](#c.vec3 "vec3") \*dst, int positive\_only)[](#c.vec3_rand "Link to this definition") Generates a random vector Parameters: * **dst** – Destination * **positive\_only** – _true_ if positive only, _false_ otherwise --- # Extra Math Functions/Macros — OBS Studio 31.0.2 documentation * [](index) * [Graphics API Reference (libobs/graphics)](reference-libobs-graphics) * Extra Math Functions/Macros * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/reference-libobs-graphics-math.rst) [Previous](reference-libobs-graphics-matrix4 "Matrix") [Next](reference-libobs-graphics-image-file "Image File Helper") * * * Extra Math Functions/Macros[](#extra-math-functions-macros "Link to this heading") ==================================================================================== #include Helper functions/macros for graphics math. RAD(val)[](#c.RAD "Link to this definition") Macro that converts a floating point degrees value to radians. DEG(val)[](#c.DEG "Link to this definition") 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 * * * float rand\_float(int positive\_only)[](#c.rand_float "Link to this definition") Generates a random floating point value (from -1.0f..1.0f, or 0.0f..1.0f if _positive\_only_ is set). --- # Quaternion — OBS Studio 31.0.2 documentation * [](index) * [Graphics API Reference (libobs/graphics)](reference-libobs-graphics) * Quaternion * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/reference-libobs-graphics-quat.rst) [Previous](reference-libobs-graphics-vec4 "4-Component Vector") [Next](reference-libobs-graphics-matrix4 "Matrix") * * * Quaternion[](#quaternion "Link to this heading") ================================================== #include struct quat[](#c.quat "Link to this definition") Two component quaternion structure. float [quat](#c.quat "quat") .x[](#c.quat.x "Link to this definition") X component float [quat](#c.quat "quat") .y[](#c.quat.y "Link to this definition") Y component float [quat](#c.quat "quat") .z[](#c.quat.z "Link to this definition") Z component float [quat](#c.quat "quat") .w[](#c.quat.w "Link to this definition") W component float [quat](#c.quat "quat") .ptr\[4\][](#c.quat.ptr "Link to this definition") Unioned array of all components * * * void quat\_identity(struct [quat](#c.quat "quat") \*dst)[](#c.quat_identity "Link to this definition") Sets a quaternion to {0.0f, 0.0f, 0.0f, 1.0f}. Parameters: * **dst** – Destination * * * void quat\_set(struct [quat](#c.quat "quat") \*dst, float x, float y)[](#c.quat_set "Link to this definition") Sets the individual components of a quaternion. Parameters: * **dst** – Destination * **x** – X component * **y** – Y component * **y** – Z component * **w** – W component * * * void quat\_copy(struct [quat](#c.quat "quat") \*dst, const struct [quat](#c.quat "quat") \*v)[](#c.quat_copy "Link to this definition") Copies a quaternion Parameters: * **dst** – Destination * **v** – Quaternion to copy * * * void quat\_add(struct [quat](#c.quat "quat") \*dst, const struct [quat](#c.quat "quat") \*v1, const struct [quat](#c.quat "quat") \*v2)[](#c.quat_add "Link to this definition") Adds two quaternions Parameters: * **dst** – Destination * **v1** – Quaternion 1 * **v2** – Quaternion 2 * * * void quat\_sub(struct [quat](#c.quat "quat") \*dst, const struct [quat](#c.quat "quat") \*v1, const struct [quat](#c.quat "quat") \*v2)[](#c.quat_sub "Link to this definition") Subtracts two quaternions Parameters: * **dst** – Destination * **v1** – Quaternion being subtracted from * **v2** – Quaternion being subtracted * * * void quat\_mul(struct [quat](#c.quat "quat") \*dst, const struct [quat](#c.quat "quat") \*v1, const struct [quat](#c.quat "quat") \*v2)[](#c.quat_mul "Link to this definition") Multiplies two quaternions Parameters: * **dst** – Destination * **v1** – Quaternion 1 * **v2** – Quaternion 2 * * * void quat\_addf(struct [quat](#c.quat "quat") \*dst, const struct [quat](#c.quat "quat") \*v, float f)[](#c.quat_addf "Link to this definition") Adds a floating point to all components Parameters: * **dst** – Destination * **dst** – Quaternion * **f** – Floating point * * * void quat\_subf(struct [quat](#c.quat "quat") \*dst, const struct [quat](#c.quat "quat") \*v, float f)[](#c.quat_subf "Link to this definition") Subtracts a floating point from all components Parameters: * **dst** – Destination * **v** – Quaternion being subtracted from * **f** – Floating point being subtracted * * * void quat\_mulf(struct [quat](#c.quat "quat") \*dst, const struct [quat](#c.quat "quat") \*v, float f)[](#c.quat_mulf "Link to this definition") Multiplies a floating point with all components Parameters: * **dst** – Destination * **dst** – Quaternion * **f** – Floating point * * * void quat\_inv(struct [quat](#c.quat "quat") \*dst, const struct [quat](#c.quat "quat") \*v)[](#c.quat_inv "Link to this definition") Inverts a quaternion Parameters: * **dst** – Destination * **v** – Quaternion to invert * * * float quat\_dot(const struct [quat](#c.quat "quat") \*v1, const struct [quat](#c.quat "quat") \*v2)[](#c.quat_dot "Link to this definition") Performs a dot product between two quaternions Parameters: * **v1** – Quaternion 1 * **v2** – Quaternion 2 Returns: Result of the dot product * * * float quat\_len(const struct [quat](#c.quat "quat") \*v)[](#c.quat_len "Link to this definition") Gets the length of a quaternion Parameters: * **v** – Quaternion Returns: The quaternion’s length * * * float quat\_dist(const struct [quat](#c.quat "quat") \*v1, const struct [quat](#c.quat "quat") \*v2)[](#c.quat_dist "Link to this definition") Gets the distance between two quaternions Parameters: * **v1** – Quaternion 1 * **v2** – Quaternion 2 Returns: Distance between the two quaternions * * * void quat\_from\_axisang(struct [quat](#c.quat "quat") \*dst, const struct [axisang](reference-libobs-graphics-axisang#c.axisang "axisang") \*aa)[](#c.quat_from_axisang "Link to this definition") Converts an axis angle to a quaternion Parameters: * **dst** – Destination quaternion * **aa** – Axis angle * * * void quat\_from\_matrix4(struct [quat](#c.quat "quat") \*dst, const struct [matrix4](reference-libobs-graphics-matrix4#c.matrix4 "matrix4") \*m)[](#c.quat_from_matrix4 "Link to this definition") Converts the rotational properties of a matrix to a quaternion Parameters: * **dst** – Destination quaternion * **m** – Matrix to convert * * * void quat\_get\_dir(struct [vec3](reference-libobs-graphics-vec3#c.vec3 "vec3") \*dst, const struct [quat](#c.quat "quat") \*q)[](#c.quat_get_dir "Link to this definition") Converts a quaternion to a directional vector Parameters: * **dst** – Destination 3-component vector * **q** – Quaternion * * * void quat\_set\_look\_dir(struct [quat](#c.quat "quat") \*dst, const struct [vec3](reference-libobs-graphics-vec3#c.vec3 "vec3") \*dir)[](#c.quat_set_look_dir "Link to this definition") Creates a quaternion from a specific “look” direction Parameters: * **dst** – Destination quaternion * **dir** – 3-component vector representing the look direction * * * void quat\_interpolate(struct [quat](#c.quat "quat") \*dst, const struct [quat](#c.quat "quat") \*q1, const struct [quat](#c.quat "quat") \*q2, float t)[](#c.quat_interpolate "Link to this definition") Linearly interpolates two quaternions Parameters: * **dst** – Destination quaternion * **q1** – Quaternion 1 * **q2** – Quaternion 2 * **t** – Time value (0.0f..1.0f) * * * void quat\_get\_tangent(struct [quat](#c.quat "quat") \*dst, const struct [quat](#c.quat "quat") \*prev, const struct [quat](#c.quat "quat") \*q, const struct [quat](#c.quat "quat") \*next)[](#c.quat_get_tangent "Link to this definition") Gets a tangent value for the center of three rotational values Parameters: * **dst** – Destination quaternion * **prev** – Previous rotation * **q** – Rotation to get tangent for * **next** – Next rotation * * * void quat\_interpolate\_cubic(struct [quat](#c.quat "quat") \*dst, const struct [quat](#c.quat "quat") \*q1, const struct [quat](#c.quat "quat") \*q2, const struct [quat](#c.quat "quat") \*m1, const struct [quat](#c.quat "quat") \*m2, float t)[](#c.quat_interpolate_cubic "Link to this definition") Performs cubic interpolation between two quaternions Parameters: * **dst** – Destination quaternion * **q1** – Quaternion 1 * **q2** – Quaternion 2 * **m1** – Tangent 1 * **m2** – Tangent 2 * **t** – Time value (0.0f..1.0f) --- # Axis Angle — OBS Studio 31.0.2 documentation * [](index) * [Graphics API Reference (libobs/graphics)](reference-libobs-graphics) * Axis Angle * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/reference-libobs-graphics-axisang.rst) [Previous](reference-libobs-graphics-image-file "Image File Helper") [Next](reference-libobs-graphics-graphics "Core Graphics API") * * * Axis Angle[](#axis-angle "Link to this heading") ================================================== Provides a helper structure for conversion to quaternions. #include struct axisang[](#c.axisang "Link to this definition") float [axisang](#c.axisang "axisang") .x[](#c.axisang.x "Link to this definition") X axis float [axisang](#c.axisang "axisang") .y[](#c.axisang.y "Link to this definition") Y axis float [axisang](#c.axisang "axisang") .z[](#c.axisang.z "Link to this definition") Z axis float [axisang](#c.axisang "axisang") .w[](#c.axisang.w "Link to this definition") Angle float [axisang](#c.axisang "axisang") .ptr\[4\][](#c.axisang.ptr "Link to this definition") * * * void axisang\_zero(struct [axisang](#c.axisang "axisang") \*dst)[](#c.axisang_zero "Link to this definition") Zeroes the axis angle. Parameters: * **dst** – Axis angle * * * void axisang\_copy(struct [axisang](#c.axisang "axisang") \*dst, struct [axisang](#c.axisang "axisang") \*aa)[](#c.axisang_copy "Link to this definition") Copies an axis angle. Parameters: * **dst** – Axis angle to copy to * **aa** – Axis angle to copy from * * * void axisang\_set(struct [axisang](#c.axisang "axisang") \*dst, float x, float y, float z, float w)[](#c.axisang_set "Link to this definition") Sets an axis angle. Parameters: * **dst** – Axis angle to set * **x** – X axis * **y** – Y axis * **z** – Z axis * **w** – Angle * * * void axisang\_from\_quat(struct [axisang](#c.axisang "axisang") \*dst, const struct [quat](reference-libobs-graphics-quat#c.quat "quat") \*q)[](#c.axisang_from_quat "Link to this definition") Creates an axis angle from a quaternion. Parameters: * **dst** – Axis angle destination * **q** – Quaternion to convert --- # OBS Studio Frontend API — OBS Studio 31.0.2 documentation * [](index) * OBS Studio Frontend API * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/reference-frontend-api.rst) [Previous](reference-libobs-media-io "Media I/O API Reference (libobs/media-io)") * * * OBS Studio Frontend API[](#obs-studio-frontend-api "Link to this heading") ============================================================================ The OBS Studio frontend API is the API specific to OBS Studio itself. #include Structures/Enumerations[](#structures-enumerations "Link to this heading") ---------------------------------------------------------------------------- enum obs\_frontend\_event[](#c.obs_frontend_event "Link to this definition") Specifies a front-end event. Can be one of the following values: * **OBS\_FRONTEND\_EVENT\_STREAMING\_STARTING** Triggered when streaming is starting. * **OBS\_FRONTEND\_EVENT\_STREAMING\_STARTED** Triggered when streaming has successfully started. * **OBS\_FRONTEND\_EVENT\_STREAMING\_STOPPING** Triggered when streaming is stopping. * **OBS\_FRONTEND\_EVENT\_STREAMING\_STOPPED** Triggered when streaming has fully stopped. * **OBS\_FRONTEND\_EVENT\_RECORDING\_STARTING** Triggered when recording is starting. * **OBS\_FRONTEND\_EVENT\_RECORDING\_STARTED** Triggered when recording has successfully started. * **OBS\_FRONTEND\_EVENT\_RECORDING\_STOPPING** Triggered when recording is stopping. * **OBS\_FRONTEND\_EVENT\_RECORDING\_STOPPED** Triggered when recording has fully stopped. * **OBS\_FRONTEND\_EVENT\_RECORDING\_PAUSED** Triggered when the recording has been paused. * **OBS\_FRONTEND\_EVENT\_RECORDING\_UNPAUSED** Triggered when the recording has been unpaused. * **OBS\_FRONTEND\_EVENT\_SCENE\_CHANGED** Triggered when the current scene has changed. * **OBS\_FRONTEND\_EVENT\_SCENE\_LIST\_CHANGED** Triggered when a scenes has been added/removed/reordered by the user. * **OBS\_FRONTEND\_EVENT\_TRANSITION\_CHANGED** Triggered when the current transition has changed by the user. * **OBS\_FRONTEND\_EVENT\_TRANSITION\_STOPPED** Triggered when a transition has completed. * **OBS\_FRONTEND\_EVENT\_TRANSITION\_LIST\_CHANGED** Triggered when the user adds/removes transitions. * **OBS\_FRONTEND\_EVENT\_TRANSITION\_DURATION\_CHANGED** Triggered when the transition duration has been changed by the user. * **OBS\_FRONTEND\_EVENT\_TBAR\_VALUE\_CHANGED** Triggered when the transition bar is moved. * **OBS\_FRONTEND\_EVENT\_SCENE\_COLLECTION\_CHANGING** Triggered when the current scene collection is about to change. * **OBS\_FRONTEND\_EVENT\_SCENE\_COLLECTION\_CHANGED** Triggered when the current scene collection has changed. * **OBS\_FRONTEND\_EVENT\_SCENE\_COLLECTION\_LIST\_CHANGED** Triggered when a scene collection has been added or removed. * **OBS\_FRONTEND\_EVENT\_SCENE\_COLLECTION\_RENAMED** Triggered when a scene collection has been renamed. * **OBS\_FRONTEND\_EVENT\_PROFILE\_CHANGING** Triggered when the current profile is about to change. * **OBS\_FRONTEND\_EVENT\_PROFILE\_CHANGED** Triggered when the current profile has changed. * **OBS\_FRONTEND\_EVENT\_PROFILE\_LIST\_CHANGED** Triggered when a profile has been added or removed. * **OBS\_FRONTEND\_EVENT\_PROFILE\_RENAMED** Triggered when a profile has been renamed. * **OBS\_FRONTEND\_EVENT\_FINISHED\_LOADING** Triggered when the program has finished loading. * **OBS\_FRONTEND\_EVENT\_SCRIPTING\_SHUTDOWN** Triggered when scripts need to know that OBS is exiting. The **OBS\_FRONTEND\_EVENT\_EXIT** event is normally called after scripts have been destroyed. * **OBS\_FRONTEND\_EVENT\_EXIT** Triggered when the program is about to exit. This is the last chance to call any frontend API functions for any saving / cleanup / etc. After returning from this event callback, it is not permitted to make any further frontend API calls. * **OBS\_FRONTEND\_EVENT\_REPLAY\_BUFFER\_STARTING** Triggered when the replay buffer is starting. * **OBS\_FRONTEND\_EVENT\_REPLAY\_BUFFER\_STARTED** Triggered when the replay buffer has successfully started. * **OBS\_FRONTEND\_EVENT\_REPLAY\_BUFFER\_STOPPING** Triggered when the replay buffer is stopping. * **OBS\_FRONTEND\_EVENT\_REPLAY\_BUFFER\_STOPPED** Triggered when the replay buffer has fully stopped. * **OBS\_FRONTEND\_EVENT\_REPLAY\_BUFFER\_SAVED** Triggered when the replay buffer has been saved. * **OBS\_FRONTEND\_EVENT\_STUDIO\_MODE\_ENABLED** Triggered when the user has turned on studio mode. * **OBS\_FRONTEND\_EVENT\_STUDIO\_MODE\_DISABLED** Triggered when the user has turned off studio mode. * **OBS\_FRONTEND\_EVENT\_PREVIEW\_SCENE\_CHANGED** Triggered when the current preview scene has changed in studio mode. * **OBS\_FRONTEND\_EVENT\_SCENE\_COLLECTION\_CLEANUP** Triggered when a scene collection has been completely unloaded, and the program is either about to load a new scene collection, or the program is about to exit. * **OBS\_FRONTEND\_EVENT\_VIRTUALCAM\_STARTED** Triggered when the virtual camera is started. * **OBS\_FRONTEND\_EVENT\_VIRTUALCAM\_STOPPED** Triggered when the virtual camera is stopped. * **OBS\_FRONTEND\_EVENT\_THEME\_CHANGED** Triggered when the theme is changed. Added in version 29.0.0. * **OBS\_FRONTEND\_EVENT\_SCREENSHOT\_TAKEN** Triggered when a screenshot is taken. Added in version 29.0.0. struct obs\_frontend\_source\_list[](#c.obs_frontend_source_list "Link to this definition") * DARRAY(obs\_source\_t\*) **sources** Example usage: struct obs\_frontend\_source\_list scenes \= {0}; obs\_frontend\_get\_scenes(&scenes); for (size\_t i \= 0; i < scenes.sources.num; i++) { /\* Do NOT call \`obs\_source\_release\` or \`obs\_scene\_release\` \* on these sources \*/ obs\_source\_t \*source \= scenes.sources.array\[i\]; /\* Convert to obs\_scene\_t if needed \*/ obs\_scene\_t \*scene \= obs\_scene\_from\_source(source); \[...\] } obs\_frontend\_source\_list\_free(&scenes); typedef void (\*obs\_frontend\_cb)(void \*private\_data)[](#c.obs_frontend_cb "Link to this definition") Frontend tool menu callback typedef void (\*obs\_frontend\_event\_cb)(enum [obs\_frontend\_event](#c.obs_frontend_event "obs_frontend_event") event, void \*private\_data)[](#c.obs_frontend_event_cb "Link to this definition") Frontend event callback typedef void (\*obs\_frontend\_save\_cb)([obs\_data\_t](reference-settings#c.obs_data_t "obs_data_t") \*save\_data, bool saving, void \*private\_data)[](#c.obs_frontend_save_cb "Link to this definition") Frontend save/load callback typedef bool (\*obs\_frontend\_translate\_ui\_cb)(const char \*text, const char \*\*out)[](#c.obs_frontend_translate_ui_cb "Link to this definition") Translation callback typedef void (\*undo\_redo\_cb)(const char \*data)[](#c.undo_redo_cb "Link to this definition") Undo redo callback Functions[](#functions "Link to this heading") ------------------------------------------------ void obs\_frontend\_source\_list\_free(struct [obs\_frontend\_source\_list](#c.obs_frontend_source_list "obs_frontend_source_list") \*source\_list)[](#c.obs_frontend_source_list_free "Link to this definition") Releases sources within a source list and frees the list. Parameters: * **source\_list** – Source list to free * * * void \*obs\_frontend\_get\_main\_window(void)[](#c.obs_frontend_get_main_window "Link to this definition") Returns: The QMainWindow pointer to the OBS Studio window * * * void \*obs\_frontend\_get\_main\_window\_handle(void)[](#c.obs_frontend_get_main_window_handle "Link to this definition") Returns: The native window handle of the OBS Studio window * * * char \*\*obs\_frontend\_get\_scene\_names(void)[](#c.obs_frontend_get_scene_names "Link to this definition") Returns: The scene name list, ending with NULL. The list is stored within one contiguous segment of memory, so freeing the returned pointer with [`bfree()`](reference-libobs-util-bmem#c.bfree "bfree") will free the entire list. The order is same as the way the frontend displays it in the Scenes dock. * * * void obs\_frontend\_get\_scenes(struct [obs\_frontend\_source\_list](#c.obs_frontend_source_list "obs_frontend_source_list") \*sources)[](#c.obs_frontend_get_scenes "Link to this definition") Populates `sources` with reference-incremented scenes in the same order as the frontend displays it in the Scenes dock. Release with [`obs_frontend_source_list_free()`](#c.obs_frontend_source_list_free "obs_frontend_source_list_free") , which will automatically release all scenes with [`obs_source_release()`](reference-sources#c.obs_source_release "obs_source_release") . Do not release a scene manually to prevent double releasing, which may cause scenes to be deleted. Use [`obs_scene_from_source()`](reference-scenes#c.obs_scene_from_source "obs_scene_from_source") to access a source from the list as an [`obs_scene_t`](reference-scenes#c.obs_scene_t "obs_scene_t") object. If you wish to keep a reference to a certain scene, use [`obs_source_get_ref()`](reference-sources#c.obs_source_get_ref "obs_source_get_ref") or [`obs_scene_get_ref()`](reference-scenes#c.obs_scene_get_ref "obs_scene_get_ref") on that scene and release it with either [`obs_source_release()`](reference-sources#c.obs_source_release "obs_source_release") or [`obs_scene_release()`](reference-scenes#c.obs_scene_release "obs_scene_release") . Use only one release function, as both releases the same object. Parameters: * **sources** – Pointer to a [`obs_frontend_source_list`](#c.obs_frontend_source_list "obs_frontend_source_list") structure to receive the list of reference-incremented scenes. * * * [obs\_source\_t](reference-sources#c.obs_source_t "obs_source_t") \*obs\_frontend\_get\_current\_scene(void)[](#c.obs_frontend_get_current_scene "Link to this definition") Returns: A new reference to the currently active scene. Release with [`obs_source_release()`](reference-sources#c.obs_source_release "obs_source_release") . * * * void obs\_frontend\_set\_current\_scene([obs\_source\_t](reference-sources#c.obs_source_t "obs_source_t") \*scene)[](#c.obs_frontend_set_current_scene "Link to this definition") Parameters: * **scene** – The scene to set as the current scene * * * void obs\_frontend\_get\_transitions(struct [obs\_frontend\_source\_list](#c.obs_frontend_source_list "obs_frontend_source_list") \*sources)[](#c.obs_frontend_get_transitions "Link to this definition") Parameters: * **sources** – Pointer to a [`obs_frontend_source_list`](#c.obs_frontend_source_list "obs_frontend_source_list") structure to receive the list of reference-incremented transitions. Release with [`obs_frontend_source_list_free()`](#c.obs_frontend_source_list_free "obs_frontend_source_list_free") * * * [obs\_source\_t](reference-sources#c.obs_source_t "obs_source_t") \*obs\_frontend\_get\_current\_transition(void)[](#c.obs_frontend_get_current_transition "Link to this definition") Returns: A new reference to the currently active transition. Release with [`obs_source_release()`](reference-sources#c.obs_source_release "obs_source_release") . * * * void obs\_frontend\_set\_current\_transition([obs\_source\_t](reference-sources#c.obs_source_t "obs_source_t") \*transition)[](#c.obs_frontend_set_current_transition "Link to this definition") Parameters: * **transition** – The transition to set as the current transition * * * int obs\_frontend\_get\_transition\_duration(void)[](#c.obs_frontend_get_transition_duration "Link to this definition") Returns: The transition duration (in milliseconds) currently set in the UI * * * void obs\_frontend\_set\_transition\_duration(int duration)[](#c.obs_frontend_set_transition_duration "Link to this definition") Parameters: * **duration** – Desired transition duration, in milliseconds * * * void obs\_frontend\_release\_tbar(void)[](#c.obs_frontend_release_tbar "Link to this definition") Emulate a mouse button release on the transition bar and determine transition status. * * * void obs\_frontend\_set\_tbar\_position(int position)[](#c.obs_frontend_set_tbar_position "Link to this definition") Set the value of the transition bar. Parameters: * **position** – The position to set the T-bar to, with a range of 0-1023 * * * int obs\_frontend\_get\_tbar\_position(void)[](#c.obs_frontend_get_tbar_position "Link to this definition") Get the value of the transition bar. Returns: The value of the position of the T-bar to, with a range of 0-1023 * * * char \*\*obs\_frontend\_get\_scene\_collections(void)[](#c.obs_frontend_get_scene_collections "Link to this definition") Returns: The list of scene collection names, ending with NULL. The list is stored within one contiguous segment of memory, so freeing the returned pointer with [`bfree()`](reference-libobs-util-bmem#c.bfree "bfree") will free the entire list. * * * char \*obs\_frontend\_get\_current\_scene\_collection(void)[](#c.obs_frontend_get_current_scene_collection "Link to this definition") Returns: A new pointer to the current scene collection name. Free with [`bfree()`](reference-libobs-util-bmem#c.bfree "bfree") * * * void obs\_frontend\_set\_current\_scene\_collection(const char \*collection)[](#c.obs_frontend_set_current_scene_collection "Link to this definition") Parameters: * **collection** – Name of the scene collection to activate * * * bool obs\_frontend\_add\_scene\_collection(const char \*name)[](#c.obs_frontend_add_scene_collection "Link to this definition") Add a new scene collection, then switch to it. Parameters: * **name** – Name of the scene collection to add/create * * * char \*\*obs\_frontend\_get\_profiles(void)[](#c.obs_frontend_get_profiles "Link to this definition") Returns: The list of profile names, ending with NULL. The list is stored within one contiguous segment of memory, so freeing the returned pointer with [`bfree()`](reference-libobs-util-bmem#c.bfree "bfree") will free the entire list. * * * char \*obs\_frontend\_get\_current\_profile(void)[](#c.obs_frontend_get_current_profile "Link to this definition") Returns: A new pointer to the current profile name. Free with [`bfree()`](reference-libobs-util-bmem#c.bfree "bfree") * * * char \*obs\_frontend\_get\_current\_profile\_path(void)[](#c.obs_frontend_get_current_profile_path "Link to this definition") Returns: A new pointer to the current profile’s path on the filesystem. Free with [`bfree()`](reference-libobs-util-bmem#c.bfree "bfree") * * * void obs\_frontend\_set\_current\_profile(const char \*profile)[](#c.obs_frontend_set_current_profile "Link to this definition") Parameters: * **profile** – Name of the profile to activate * * * bool obs\_frontend\_create\_profile(const char \*name)[](#c.obs_frontend_create_profile "Link to this definition") Parameters: * **name** – Name of the new profile to create (must be unique) * * * bool obs\_frontend\_duplicate\_profile(const char \*name)[](#c.obs_frontend_duplicate_profile "Link to this definition") Parameters: * **name** – Name of the duplicate profile to create (must be unique) * * * void obs\_frontend\_delete\_profile(const char \*profile)[](#c.obs_frontend_delete_profile "Link to this definition") Parameters: * **profile** – Name of the profile to delete * * * void \*obs\_frontend\_add\_tools\_menu\_qaction(const char \*name)[](#c.obs_frontend_add_tools_menu_qaction "Link to this definition") Adds a QAction to the tools menu then returns it. Parameters: * **name** – Name for the new menu item Returns: A pointer to the added QAction * * * void obs\_frontend\_add\_tools\_menu\_item(const char \*name, [obs\_frontend\_cb](#c.obs_frontend_cb "obs_frontend_cb") callback, void \*private\_data)[](#c.obs_frontend_add_tools_menu_item "Link to this definition") Adds a tools menu item and links the ::clicked signal to the callback. Parameters: * **name** – The name for the new menu item * **callback** – Callback to use when the menu item is clicked * **private\_data** – Private data associated with the callback * * * void \*obs\_frontend\_add\_dock(void \*dock)[](#c.obs_frontend_add_dock "Link to this definition") Adds a QDockWidget to the UI’s Docks menu. Parameters: * **dock** – QDockWidget to add/create Returns: A pointer to the added QAction Deprecated since version 30.0: Prefer [`obs_frontend_add_dock_by_id()`](#c.obs_frontend_add_dock_by_id "obs_frontend_add_dock_by_id") or [`obs_frontend_add_custom_qdock()`](#c.obs_frontend_add_custom_qdock "obs_frontend_add_custom_qdock") instead. * * * bool obs\_frontend\_add\_dock\_by\_id(const char \*id, const char \*title, void \*widget)[](#c.obs_frontend_add_dock_by_id "Link to this definition") Adds a dock with the widget to the UI with a toggle in the Docks menu. When the dock is closed, a custom QEvent of type QEvent::User + QEvent::Close is sent to the widget to enable it to react to the event (e.g., unload elements to save resources). A generic QShowEvent is already sent by default when the widget is being shown (e.g., dock opened). Note: Use [`obs_frontend_remove_dock()`](#c.obs_frontend_remove_dock "obs_frontend_remove_dock") to remove the dock and the id from the UI. Parameters: * **id** – Unique identifier of the dock * **title** – Window title of the dock * **widget** – QWidget to insert in the dock Returns: _true_ if the dock was added, _false_ if the id was already used Added in version 30.0. * * * void obs\_frontend\_remove\_dock(const char \*id)[](#c.obs_frontend_remove_dock "Link to this definition") Removes the dock with this id from the UI. Parameters: * **id** – Unique identifier of the dock to remove. Added in version 30.0. * * * bool obs\_frontend\_add\_custom\_qdock(const char \*id, void \*dock)[](#c.obs_frontend_add_custom_qdock "Link to this definition") Adds a custom dock to the UI with no toggle. Note: Use [`obs_frontend_remove_dock()`](#c.obs_frontend_remove_dock "obs_frontend_remove_dock") to remove the dock reference and id from the UI. Parameters: * **id** – Unique identifier of the dock * **dock** – QDockWidget to add Returns: _true_ if the dock was added, _false_ if the id was already used Added in version 30.0. * * * void obs\_frontend\_add\_event\_callback([obs\_frontend\_event\_cb](#c.obs_frontend_event_cb "obs_frontend_event_cb") callback, void \*private\_data)[](#c.obs_frontend_add_event_callback "Link to this definition") Adds a callback that will be called when a frontend event occurs. See [`obs_frontend_event`](#c.obs_frontend_event "obs_frontend_event") on what sort of events can be triggered. Parameters: * **callback** – Callback to use when a frontend event occurs * **private\_data** – Private data associated with the callback * * * void obs\_frontend\_remove\_event\_callback([obs\_frontend\_event\_cb](#c.obs_frontend_event_cb "obs_frontend_event_cb") callback, void \*private\_data)[](#c.obs_frontend_remove_event_callback "Link to this definition") Removes an event callback. Parameters: * **callback** – Callback to remove * **private\_data** – Private data associated with the callback * * * void obs\_frontend\_add\_save\_callback([obs\_frontend\_save\_cb](#c.obs_frontend_save_cb "obs_frontend_save_cb") callback, void \*private\_data)[](#c.obs_frontend_add_save_callback "Link to this definition") Adds a callback that will be called when the current scene collection is being saved/loaded. Parameters: * **callback** – Callback to use when saving/loading a scene collection * **private\_data** – Private data associated with the callback * * * void obs\_frontend\_remove\_save\_callback([obs\_frontend\_save\_cb](#c.obs_frontend_save_cb "obs_frontend_save_cb") callback, void \*private\_data)[](#c.obs_frontend_remove_save_callback "Link to this definition") Removes a save/load callback. Parameters: * **callback** – Callback to remove * **private\_data** – Private data associated with the callback * * * void obs\_frontend\_add\_preload\_callback([obs\_frontend\_save\_cb](#c.obs_frontend_save_cb "obs_frontend_save_cb") callback, void \*private\_data)[](#c.obs_frontend_add_preload_callback "Link to this definition") Adds a callback that will be called right before a scene collection is loaded. Parameters: * **callback** – Callback to use when pre-loading * **private\_data** – Private data associated with the callback * * * void obs\_frontend\_remove\_preload\_callback([obs\_frontend\_save\_cb](#c.obs_frontend_save_cb "obs_frontend_save_cb") callback, void \*private\_data)[](#c.obs_frontend_remove_preload_callback "Link to this definition") Removes a pre-load callback. Parameters: * **callback** – Callback to remove * **private\_data** – Private data associated with the callback * * * void obs\_frontend\_push\_ui\_translation([obs\_frontend\_translate\_ui\_cb](#c.obs_frontend_translate_ui_cb "obs_frontend_translate_ui_cb") translate)[](#c.obs_frontend_push_ui_translation "Link to this definition") Pushes a UI translation callback. This allows a front-end plugin to intercept when Qt is automatically generating translating data. Typically this is just called with obs\_module\_get\_string. Parameters: * **translate** – The translation callback to use * * * void obs\_frontend\_pop\_ui\_translation(void)[](#c.obs_frontend_pop_ui_translation "Link to this definition") Pops the current UI translation callback. * * * void obs\_frontend\_streaming\_start(void)[](#c.obs_frontend_streaming_start "Link to this definition") Starts streaming. * * * void obs\_frontend\_streaming\_stop(void)[](#c.obs_frontend_streaming_stop "Link to this definition") Stops streaming. * * * bool obs\_frontend\_streaming\_active(void)[](#c.obs_frontend_streaming_active "Link to this definition") Returns: _true_ if streaming active, _false_ otherwise * * * void obs\_frontend\_recording\_start(void)[](#c.obs_frontend_recording_start "Link to this definition") Starts recording. * * * void obs\_frontend\_recording\_stop(void)[](#c.obs_frontend_recording_stop "Link to this definition") Stops recording. * * * bool obs\_frontend\_recording\_active(void)[](#c.obs_frontend_recording_active "Link to this definition") Returns: _true_ if recording active, _false_ otherwise * * * void obs\_frontend\_recording\_pause(bool pause)[](#c.obs_frontend_recording_pause "Link to this definition") Pause: _true_ to pause recording, _false_ to unpause * * * bool obs\_frontend\_recording\_paused(void)[](#c.obs_frontend_recording_paused "Link to this definition") Returns: _true_ if recording paused, _false_ otherwise * * * bool obs\_frontend\_recording\_split\_file(void)[](#c.obs_frontend_recording_split_file "Link to this definition") Asks OBS to split the current recording file. Returns: _true_ if splitting was successfully requested (this does not mean that splitting has finished or guarantee that it split successfully), _false_ if recording is inactive or paused or if file splitting is disabled. * * * bool obs\_frontend\_recording\_add\_chapter(const char \*name)[](#c.obs_frontend_recording_add_chapter "Link to this definition") Asks OBS to insert a chapter marker at the current output time into the recording. Parameters: * **name** – The name for the chapter, may be _NULL_ to use an automatically generated name (“Unnamed ” or localized equivalent). Returns: _true_ if insertion was successful, _false_ if recording is inactive, paused, or if chapter insertion is not supported by the current output. Added in version 30.2. * * * void obs\_frontend\_replay\_buffer\_start(void)[](#c.obs_frontend_replay_buffer_start "Link to this definition") Starts the replay buffer. * * * void obs\_frontend\_replay\_buffer\_stop(void)[](#c.obs_frontend_replay_buffer_stop "Link to this definition") Stops the replay buffer. * * * void obs\_frontend\_replay\_buffer\_save(void)[](#c.obs_frontend_replay_buffer_save "Link to this definition") Saves a replay if the replay buffer is active. * * * bool obs\_frontend\_replay\_buffer\_active(void)[](#c.obs_frontend_replay_buffer_active "Link to this definition") Returns: _true_ if replay buffer active, _false_ otherwise * * * void obs\_frontend\_open\_projector(const char \*type, int monitor, const char \*geometry, const char \*name)[](#c.obs_frontend_open_projector "Link to this definition") Parameters: * **type** – “Preview”, “Source”, “Scene”, “StudioProgram”, or “Multiview” (case insensitive) * **monitor** – Monitor to open the projector on. If -1, this opens a window. * **geometry** – If _monitor_ is -1, size and position of the projector window. Encoded in Base64 using Qt’s geometry encoding. * **name** – If _type_ is “Source” or “Scene”, name of the source or scene to be displayed * * * void obs\_frontend\_save(void)[](#c.obs_frontend_save "Link to this definition") Saves the current scene collection. * * * [obs\_output\_t](reference-outputs#c.obs_output_t "obs_output_t") \*obs\_frontend\_get\_streaming\_output(void)[](#c.obs_frontend_get_streaming_output "Link to this definition") Returns: A new reference to the current streaming output. Release with [`obs_output_release()`](reference-outputs#c.obs_output_release "obs_output_release") . * * * [obs\_output\_t](reference-outputs#c.obs_output_t "obs_output_t") \*obs\_frontend\_get\_recording\_output(void)[](#c.obs_frontend_get_recording_output "Link to this definition") Returns: A new reference to the current recording output. Release with [`obs_output_release()`](reference-outputs#c.obs_output_release "obs_output_release") . * * * [obs\_output\_t](reference-outputs#c.obs_output_t "obs_output_t") \*obs\_frontend\_get\_replay\_buffer\_output(void)[](#c.obs_frontend_get_replay_buffer_output "Link to this definition") Returns: A new reference to the current replay buffer output. Release with [`obs_output_release()`](reference-outputs#c.obs_output_release "obs_output_release") . * * * [config\_t](reference-libobs-util-config-file#c.config_t "config_t") \*obs\_frontend\_get\_profile\_config(void)[](#c.obs_frontend_get_profile_config "Link to this definition") Returns: The config\_t\* associated with the current profile * * * Deprecated since version 31.0. [config\_t](reference-libobs-util-config-file#c.config_t "config_t") \*obs\_frontend\_get\_global\_config(void)[](#c.obs_frontend_get_global_config "Link to this definition") Returns: The config\_t\* associated with the global config (global.ini) * * * [config\_t](reference-libobs-util-config-file#c.config_t "config_t") \*obs\_frontend\_get\_app\_config(void)[](#c.obs_frontend_get_app_config "Link to this definition") Returns: The config\_t\* associated with system-wide settings (global.ini) Added in version 31.0. * * * [config\_t](reference-libobs-util-config-file#c.config_t "config_t") \*obs\_frontend\_get\_user\_config(void)[](#c.obs_frontend_get_user_config "Link to this definition") Returns: The config\_t\* associated with user settings (user.ini) Added in version 31.0. * * * void obs\_frontend\_set\_streaming\_service([obs\_service\_t](reference-services#c.obs_service_t "obs_service_t") \*service)[](#c.obs_frontend_set_streaming_service "Link to this definition") Sets the current streaming service to stream with. Parameters: * **service** – The streaming service to set * * * [obs\_service\_t](reference-services#c.obs_service_t "obs_service_t") \*obs\_frontend\_get\_streaming\_service(void)[](#c.obs_frontend_get_streaming_service "Link to this definition") Returns: The current streaming service object. Does not increment the reference. * * * void obs\_frontend\_save\_streaming\_service(void)[](#c.obs_frontend_save_streaming_service "Link to this definition") Saves the current streaming service data. * * * bool obs\_frontend\_preview\_program\_mode\_active(void)[](#c.obs_frontend_preview_program_mode_active "Link to this definition") Returns: _true_ if studio mode is active, _false_ otherwise * * * void obs\_frontend\_set\_preview\_program\_mode(bool enable)[](#c.obs_frontend_set_preview_program_mode "Link to this definition") Activates/deactivates studio mode. Parameters: * **enable** – _true_ to activate studio mode, _false_ to deactivate studio mode * * * void obs\_frontend\_preview\_program\_trigger\_transition(void)[](#c.obs_frontend_preview_program_trigger_transition "Link to this definition") Triggers a preview-to-program transition if studio mode is active. * * * [obs\_source\_t](reference-sources#c.obs_source_t "obs_source_t") \*obs\_frontend\_get\_current\_preview\_scene(void)[](#c.obs_frontend_get_current_preview_scene "Link to this definition") Returns: A new reference to the current preview scene if studio mode is active, or _NULL_ if studio mode is not active. Release with [`obs_source_release()`](reference-sources#c.obs_source_release "obs_source_release") . * * * void obs\_frontend\_set\_current\_preview\_scene([obs\_source\_t](reference-sources#c.obs_source_t "obs_source_t") \*scene)[](#c.obs_frontend_set_current_preview_scene "Link to this definition") Sets the current preview scene in studio mode. Does nothing if studio mode is disabled. Parameters: * **scene** – The scene to set as the current preview * * * void obs\_frontend\_set\_preview\_enabled(bool enable)[](#c.obs_frontend_set_preview_enabled "Link to this definition") Sets the enable state of the preview display. Only relevant with studio mode disabled. Parameters: * **enable** – _true_ to enable preview, _false_ to disable preview * * * bool obs\_frontend\_preview\_enabled(void)[](#c.obs_frontend_preview_enabled "Link to this definition") Returns: _true_ if the preview display is enabled, _false_ otherwise * * * void \*obs\_frontend\_take\_screenshot(void)[](#c.obs_frontend_take_screenshot "Link to this definition") Takes a screenshot of the main OBS output. * * * void \*obs\_frontend\_take\_source\_screenshot([obs\_source\_t](reference-sources#c.obs_source_t "obs_source_t") \*source)[](#c.obs_frontend_take_source_screenshot "Link to this definition") Takes a screenshot of the specified source. Parameters: * **source** – The source to take screenshot of * * * [obs\_output\_t](reference-outputs#c.obs_output_t "obs_output_t") \*obs\_frontend\_get\_virtualcam\_output(void)[](#c.obs_frontend_get_virtualcam_output "Link to this definition") Returns: A new reference to the current virtual camera output. Release with [`obs_output_release()`](reference-outputs#c.obs_output_release "obs_output_release") . * * * void obs\_frontend\_start\_virtualcam(void)[](#c.obs_frontend_start_virtualcam "Link to this definition") Starts the virtual camera. * * * void obs\_frontend\_stop\_virtualcam(void)[](#c.obs_frontend_stop_virtualcam "Link to this definition") Stops the virtual camera. * * * bool obs\_frontend\_virtualcam\_active(void)[](#c.obs_frontend_virtualcam_active "Link to this definition") Returns: _true_ if virtual camera is active, _false_ otherwise * * * void obs\_frontend\_reset\_video(void)[](#c.obs_frontend_reset_video "Link to this definition") Reloads the UI canvas and resets libobs video with latest data from the current profile. * * * void \*obs\_frontend\_open\_source\_properties([obs\_source\_t](reference-sources#c.obs_source_t "obs_source_t") \*source)[](#c.obs_frontend_open_source_properties "Link to this definition") Opens the properties window of the specified source. Parameters: * **source** – The source to open the properties window of * * * void \*obs\_frontend\_open\_source\_filters([obs\_source\_t](reference-sources#c.obs_source_t "obs_source_t") \*source)[](#c.obs_frontend_open_source_filters "Link to this definition") Opens the filters window of the specified source. Parameters: * **source** – The source to open the filters window of * * * void \*obs\_frontend\_open\_source\_interaction([obs\_source\_t](reference-sources#c.obs_source_t "obs_source_t") \*source)[](#c.obs_frontend_open_source_interaction "Link to this definition") Opens the interact window of the specified source. Only call if source has the _OBS\_SOURCE\_INTERACTION_ output flag. Parameters: * **source** – The source to open the interact window of * * * void \*obs\_frontend\_open\_sceneitem\_edit\_transform([obs\_sceneitem\_t](reference-scenes#c.obs_sceneitem_t "obs_sceneitem_t") \*item)[](#c.obs_frontend_open_sceneitem_edit_transform "Link to this definition") Opens the edit transform window of the specified sceneitem. Parameters: * **item** – The sceneitem to open the edit transform window of Added in version 29.1. * * * char \*obs\_frontend\_get\_current\_record\_output\_path(void)[](#c.obs_frontend_get_current_record_output_path "Link to this definition") Returns: A new pointer to the current record output path. Free with [`bfree()`](reference-libobs-util-bmem#c.bfree "bfree") * * * const char \*obs\_frontend\_get\_locale\_string(const char \*string)[](#c.obs_frontend_get_locale_string "Link to this definition") Returns: Gets the frontend translation of a given string. * * * bool obs\_frontend\_is\_theme\_dark(void)[](#c.obs_frontend_is_theme_dark "Link to this definition") Returns: Checks if the current theme is dark or light. Added in version 29.0.0. * * * char \*obs\_frontend\_get\_last\_recording(void)[](#c.obs_frontend_get_last_recording "Link to this definition") Returns: The file path of the last recording. Free with [`bfree()`](reference-libobs-util-bmem#c.bfree "bfree") Added in version 29.0.0. * * * char \*obs\_frontend\_get\_last\_screenshot(void)[](#c.obs_frontend_get_last_screenshot "Link to this definition") Returns: The file path of the last screenshot taken. Free with [`bfree()`](reference-libobs-util-bmem#c.bfree "bfree") Added in version 29.0.0. * * * char \*obs\_frontend\_get\_last\_replay(void)[](#c.obs_frontend_get_last_replay "Link to this definition") Returns: The file path of the last replay buffer saved. Free with [`bfree()`](reference-libobs-util-bmem#c.bfree "bfree") Added in version 29.0.0. * * * void obs\_frontend\_add\_undo\_redo\_action(const char \*name, const [undo\_redo\_cb](#c.undo_redo_cb "undo_redo_cb") undo, const [undo\_redo\_cb](#c.undo_redo_cb "undo_redo_cb") redo, const char \*undo\_data, const char \*redo\_data, bool repeatable)[](#c.obs_frontend_add_undo_redo_action "Link to this definition") Parameters: * **name** – The name of the undo redo action * **undo** – Callback to use for undo * **redo** – Callback to use for redo * **undo\_data** – String with data for the undo callback * **redo\_data** – String with data for the redo callback * **repeatable** – Allow multiple actions with the same name to be merged to 1 undo redo action. This uses the undo action from the first and the redo action from the last action. Added in version 29.1. --- # Core Graphics API — OBS Studio 31.0.2 documentation * [](index) * [Graphics API Reference (libobs/graphics)](reference-libobs-graphics) * Core Graphics API * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/reference-libobs-graphics-graphics.rst) [Previous](reference-libobs-graphics-axisang "Axis Angle") [Next](reference-libobs-media-io "Media I/O API Reference (libobs/media-io)") * * * Core Graphics API[](#core-graphics-api "Link to this heading") ================================================================ #include Graphics Enumerations[](#graphics-enumerations "Link to this heading") ------------------------------------------------------------------------ enum gs\_draw\_mode[](#c.gs_draw_mode "Link to this definition") Draw mode. Can be one of the following values: * GS\_POINTS - Draws points * GS\_LINES - Draws individual lines * GS\_LINESTRIP - Draws a line strip * GS\_TRIS - Draws individual triangles * GS\_TRISTRIP - Draws a triangle strip enum gs\_color\_format[](#c.gs_color_format "Link to this definition") Color format. Can be one of the following values: * GS\_UNKNOWN - Unknown format * GS\_A8 - 8 bit alpha channel only * GS\_R8 - 8 bit red channel only * GS\_RGBA - RGBA, 8 bits per channel * GS\_BGRX - BGRX, 8 bits per channel * GS\_BGRA - BGRA, 8 bits per channel * GS\_R10G10B10A2 - RGBA, 10 bits per channel except alpha, which is 2 bits * GS\_RGBA16 - RGBA, 16 bits per channel * GS\_R16 - 16 bit red channel only * GS\_RGBA16F - RGBA, 16 bit floating point per channel * GS\_RGBA32F - RGBA, 32 bit floating point per channel * GS\_RG16F - 16 bit floating point red and green channels only * GS\_RG32F - 32 bit floating point red and green channels only * GS\_R16F - 16 bit floating point red channel only * GS\_R32F - 32 bit floating point red channel only * GS\_DXT1 - Compressed DXT1 * GS\_DXT3 - Compressed DXT3 * GS\_DXT5 - Compressed DXT5 * GS\_RGBA\_UNORM - RGBA, 8 bits per channel, no SRGB aliasing * GS\_BGRX\_UNORM - BGRX, 8 bits per channel, no SRGB aliasing * GS\_BGRA\_UNORM - BGRA, 8 bits per channel, no SRGB aliasing * GS\_RG16 - RG, 16 bits per channel enum gs\_color\_space[](#c.gs_color_space "Link to this definition") Color space. Can be one of the following values: * GS\_CS\_SRGB - sRGB * GS\_CS\_SRGB\_16F - High-precision SDR * GS\_CS\_709\_EXTENDED - Canvas, Mac EDR (HDR) * GS\_CS\_709\_SCRGB - 1.0 = 80 nits, Windows/Linux HDR enum gs\_zstencil\_format[](#c.gs_zstencil_format "Link to this definition") Z-Stencil buffer format. Can be one of the following values: * GS\_ZS\_NONE - No Z-stencil buffer * GS\_Z16 - 16 bit Z buffer * GS\_Z24\_S8 - 24 bit Z buffer, 8 bit stencil * GS\_Z32F - 32 bit floating point Z buffer * GS\_Z32F\_S8X24 - 32 bit floating point Z buffer, 8 bit stencil enum gs\_index\_type[](#c.gs_index_type "Link to this definition") Index buffer type. Can be one of the following values: * GS\_UNSIGNED\_SHORT - 16 bit index * GS\_UNSIGNED\_LONG - 32 bit index enum gs\_cull\_mode[](#c.gs_cull_mode "Link to this definition") Cull mode. Can be one of the following values: * GS\_BACK - Cull back faces * GS\_FRONT - Cull front faces * GS\_NEITHER - Cull neither enum gs\_blend\_type[](#c.gs_blend_type "Link to this definition") Blend type. Can be one of the following values: * GS\_BLEND\_ZERO * GS\_BLEND\_ONE * GS\_BLEND\_SRCCOLOR * GS\_BLEND\_INVSRCCOLOR * GS\_BLEND\_SRCALPHA * GS\_BLEND\_INVSRCALPHA * GS\_BLEND\_DSTCOLOR * GS\_BLEND\_INVDSTCOLOR * GS\_BLEND\_DSTALPHA * GS\_BLEND\_INVDSTALPHA * GS\_BLEND\_SRCALPHASAT enum gs\_depth\_test[](#c.gs_depth_test "Link to this definition") Depth test type. Can be one of the following values: * GS\_NEVER * GS\_LESS * GS\_LEQUAL * GS\_EQUAL * GS\_GEQUAL * GS\_GREATER * GS\_NOTEQUAL * GS\_ALWAYS enum gs\_stencil\_side[](#c.gs_stencil_side "Link to this definition") Stencil side. Can be one of the following values: * GS\_STENCIL\_FRONT=1 * GS\_STENCIL\_BACK * GS\_STENCIL\_BOTH enum gs\_stencil\_op\_type[](#c.gs_stencil_op_type "Link to this definition") Stencil operation type. Can be one of the following values: * GS\_KEEP * GS\_ZERO * GS\_REPLACE * GS\_INCR * GS\_DECR * GS\_INVERT enum gs\_cube\_sides[](#c.gs_cube_sides "Link to this definition") Cubemap side. Can be one of the following values: * GS\_POSITIVE\_X * GS\_NEGATIVE\_X * GS\_POSITIVE\_Y * GS\_NEGATIVE\_Y * GS\_POSITIVE\_Z * GS\_NEGATIVE\_Z enum gs\_sample\_filter[](#c.gs_sample_filter "Link to this definition") Sample filter type. Can be one of the following values: * GS\_FILTER\_POINT * GS\_FILTER\_LINEAR * GS\_FILTER\_ANISOTROPIC * GS\_FILTER\_MIN\_MAG\_POINT\_MIP\_LINEAR * GS\_FILTER\_MIN\_POINT\_MAG\_LINEAR\_MIP\_POINT * GS\_FILTER\_MIN\_POINT\_MAG\_MIP\_LINEAR * GS\_FILTER\_MIN\_LINEAR\_MAG\_MIP\_POINT * GS\_FILTER\_MIN\_LINEAR\_MAG\_POINT\_MIP\_LINEAR * GS\_FILTER\_MIN\_MAG\_LINEAR\_MIP\_POINT enum gs\_address\_mode[](#c.gs_address_mode "Link to this definition") Address mode. Can be one of the following values: * GS\_ADDRESS\_CLAMP * GS\_ADDRESS\_WRAP * GS\_ADDRESS\_MIRROR * GS\_ADDRESS\_BORDER * GS\_ADDRESS\_MIRRORONCE enum gs\_texture\_type[](#c.gs_texture_type "Link to this definition") Texture type. Can be one of the following values: * GS\_TEXTURE\_2D * GS\_TEXTURE\_3D * GS\_TEXTURE\_CUBE Graphics Structures[](#graphics-structures "Link to this heading") -------------------------------------------------------------------- struct gs\_monitor\_info[](#c.gs_monitor_info "Link to this definition") int [gs\_monitor\_info](#c.gs_monitor_info "gs_monitor_info") .rotation\_degrees[](#c.gs_monitor_info.rotation_degrees "Link to this definition") long [gs\_monitor\_info](#c.gs_monitor_info "gs_monitor_info") .x[](#c.gs_monitor_info.x "Link to this definition") long [gs\_monitor\_info](#c.gs_monitor_info "gs_monitor_info") .y[](#c.gs_monitor_info.y "Link to this definition") long [gs\_monitor\_info](#c.gs_monitor_info "gs_monitor_info") .cx[](#c.gs_monitor_info.cx "Link to this definition") long [gs\_monitor\_info](#c.gs_monitor_info "gs_monitor_info") .cy[](#c.gs_monitor_info.cy "Link to this definition") * * * struct gs\_tvertarray[](#c.gs_tvertarray "Link to this definition") size\_t [gs\_tvertarray](#c.gs_tvertarray "gs_tvertarray") .width[](#c.gs_tvertarray.width "Link to this definition") void \*[gs\_tvertarray](#c.gs_tvertarray "gs_tvertarray") .array[](#c.gs_tvertarray.array "Link to this definition") * * * struct gs\_vb\_data[](#c.gs_vb_data "Link to this definition") size\_t [gs\_vb\_data](#c.gs_vb_data "gs_vb_data") .num[](#c.gs_vb_data.num "Link to this definition") struct [vec3](reference-libobs-graphics-vec3#c.vec3 "vec3") \*[gs\_vb\_data](#c.gs_vb_data "gs_vb_data") .points[](#c.gs_vb_data.points "Link to this definition") struct [vec3](reference-libobs-graphics-vec3#c.vec3 "vec3") \*[gs\_vb\_data](#c.gs_vb_data "gs_vb_data") .normals[](#c.gs_vb_data.normals "Link to this definition") struct [vec3](reference-libobs-graphics-vec3#c.vec3 "vec3") \*[gs\_vb\_data](#c.gs_vb_data "gs_vb_data") .tangents[](#c.gs_vb_data.tangents "Link to this definition") uint32\_t \*[gs\_vb\_data](#c.gs_vb_data "gs_vb_data") .colors[](#c.gs_vb_data.colors "Link to this definition") size\_t [gs\_vb\_data](#c.gs_vb_data "gs_vb_data") .num\_tex[](#c.gs_vb_data.num_tex "Link to this definition") struct [gs\_tvertarray](#c.gs_tvertarray "gs_tvertarray") \*[gs\_vb\_data](#c.gs_vb_data "gs_vb_data") .tvarray[](#c.gs_vb_data.tvarray "Link to this definition") * * * struct gs\_sampler\_info[](#c.gs_sampler_info "Link to this definition") enum [gs\_sample\_filter](#c.gs_sample_filter "gs_sample_filter") [gs\_sampler\_info](#c.gs_sampler_info "gs_sampler_info") .filter[](#c.gs_sampler_info.filter "Link to this definition") enum [gs\_address\_mode](#c.gs_address_mode "gs_address_mode") [gs\_sampler\_info](#c.gs_sampler_info "gs_sampler_info") .address\_u[](#c.gs_sampler_info.address_u "Link to this definition") enum [gs\_address\_mode](#c.gs_address_mode "gs_address_mode") [gs\_sampler\_info](#c.gs_sampler_info "gs_sampler_info") .address\_v[](#c.gs_sampler_info.address_v "Link to this definition") enum [gs\_address\_mode](#c.gs_address_mode "gs_address_mode") [gs\_sampler\_info](#c.gs_sampler_info "gs_sampler_info") .address\_w[](#c.gs_sampler_info.address_w "Link to this definition") int [gs\_sampler\_info](#c.gs_sampler_info "gs_sampler_info") .max\_anisotropy[](#c.gs_sampler_info.max_anisotropy "Link to this definition") uint32\_t [gs\_sampler\_info](#c.gs_sampler_info "gs_sampler_info") .border\_color[](#c.gs_sampler_info.border_color "Link to this definition") * * * struct gs\_display\_mode[](#c.gs_display_mode "Link to this definition") uint32\_t [gs\_display\_mode](#c.gs_display_mode "gs_display_mode") .width[](#c.gs_display_mode.width "Link to this definition") uint32\_t [gs\_display\_mode](#c.gs_display_mode "gs_display_mode") .height[](#c.gs_display_mode.height "Link to this definition") uint32\_t [gs\_display\_mode](#c.gs_display_mode "gs_display_mode") .bits[](#c.gs_display_mode.bits "Link to this definition") uint32\_t [gs\_display\_mode](#c.gs_display_mode "gs_display_mode") .freq[](#c.gs_display_mode.freq "Link to this definition") * * * struct gs\_rect[](#c.gs_rect "Link to this definition") int [gs\_rect](#c.gs_rect "gs_rect") .x[](#c.gs_rect.x "Link to this definition") int [gs\_rect](#c.gs_rect "gs_rect") .y[](#c.gs_rect.y "Link to this definition") int [gs\_rect](#c.gs_rect "gs_rect") .cx[](#c.gs_rect.cx "Link to this definition") int [gs\_rect](#c.gs_rect "gs_rect") .cy[](#c.gs_rect.cy "Link to this definition") * * * struct gs\_window[](#c.gs_window "Link to this definition") A window structure. This structure is used with a native widget. void \*[gs\_window](#c.gs_window "gs_window") .hwnd[](#c.gs_window.hwnd "Link to this definition") (Windows only) an HWND widget. [id](#c.gs_window.id "id") [gs\_window](#c.gs_window "gs_window") .view[](#c.gs_window.view "Link to this definition") (macOS only) A view ID. uint32\_t [gs\_window](#c.gs_window "gs_window") .id[](#c.gs_window.id "Link to this definition") void \*[gs\_window](#c.gs_window "gs_window") .display[](#c.gs_window.display "Link to this definition") (Linux only) Window ID and display * * * struct gs\_init\_data[](#c.gs_init_data "Link to this definition") Swap chain initialization data. struct [gs\_window](#c.gs_window "gs_window") [gs\_init\_data](#c.gs_init_data "gs_init_data") .window[](#c.gs_init_data.window "Link to this definition") uint32\_t [gs\_init\_data](#c.gs_init_data "gs_init_data") .cx[](#c.gs_init_data.cx "Link to this definition") uint32\_t [gs\_init\_data](#c.gs_init_data "gs_init_data") .cy[](#c.gs_init_data.cy "Link to this definition") uint32\_t [gs\_init\_data](#c.gs_init_data "gs_init_data") .num\_backbuffers[](#c.gs_init_data.num_backbuffers "Link to this definition") enum [gs\_color\_format](#c.gs_color_format "gs_color_format") [gs\_init\_data](#c.gs_init_data "gs_init_data") .format[](#c.gs_init_data.format "Link to this definition") enum [gs\_zstencil\_format](#c.gs_zstencil_format "gs_zstencil_format") [gs\_init\_data](#c.gs_init_data "gs_init_data") .zsformat[](#c.gs_init_data.zsformat "Link to this definition") uint32\_t [gs\_init\_data](#c.gs_init_data "gs_init_data") .adapter[](#c.gs_init_data.adapter "Link to this definition") * * * Initialization Functions[](#initialization-functions "Link to this heading") ------------------------------------------------------------------------------ void gs\_enum\_adapters(bool (\*callback)(void \*param, const char \*name, uint32\_t id), void \*param)[](#c.gs_enum_adapters "Link to this definition") Enumerates adapters (this really only applies on Windows). Parameters: * **callback** – Enumeration callback * **param** – Private data passed to the callback * * * int gs\_create([graphics\_t](#c.graphics_t "graphics_t") \*\*graphics, const char \*module, uint32\_t adapter)[](#c.gs_create "Link to this definition") Creates a graphics context Parameters: * **graphics** – Pointer to receive the graphics context * **module** – Module name * **adapter** – Adapter index Returns: Can return one of the following values: * GS\_SUCCESS * GS\_ERROR\_FAIL * GS\_ERROR\_MODULE\_NOT\_FOUND * GS\_ERROR\_NOT\_SUPPORTED * * * void gs\_destroy([graphics\_t](#c.graphics_t "graphics_t") \*graphics)[](#c.gs_destroy "Link to this definition") Destroys a graphics context Parameters: * **graphics** – Graphics context * * * void gs\_enter\_context([graphics\_t](#c.graphics_t "graphics_t") \*graphics)[](#c.gs_enter_context "Link to this definition") Enters and locks the graphics context Parameters: * **graphics** – Graphics context * * * void gs\_leave\_context(void)[](#c.gs_leave_context "Link to this definition") Leaves and unlocks the graphics context Parameters: * **graphics** – Graphics context * * * [graphics\_t](#c.graphics_t "graphics_t") \*gs\_get\_context(void)[](#c.gs_get_context "Link to this definition") Returns: The currently locked graphics context for this thread * * * Matrix Stack Functions[](#matrix-stack-functions "Link to this heading") -------------------------------------------------------------------------- void gs\_matrix\_push(void)[](#c.gs_matrix_push "Link to this definition") Pushes the matrix stack and duplicates the current matrix. * * * void gs\_matrix\_pop(void)[](#c.gs_matrix_pop "Link to this definition") Pops the current matrix from the matrix stack. * * * void gs\_matrix\_identity(void)[](#c.gs_matrix_identity "Link to this definition") Sets the current matrix to an identity matrix. * * * void gs\_matrix\_transpose(void)[](#c.gs_matrix_transpose "Link to this definition") Transposes the current matrix. * * * void gs\_matrix\_set(const struct [matrix4](reference-libobs-graphics-matrix4#c.matrix4 "matrix4") \*matrix)[](#c.gs_matrix_set "Link to this definition") Sets the current matrix. Parameters: * **matrix** – The matrix to set * * * void gs\_matrix\_get(struct [matrix4](reference-libobs-graphics-matrix4#c.matrix4 "matrix4") \*dst)[](#c.gs_matrix_get "Link to this definition") Gets the current matrix Parameters: * **dst** – Destination matrix * * * void gs\_matrix\_mul(const struct [matrix4](reference-libobs-graphics-matrix4#c.matrix4 "matrix4") \*matrix)[](#c.gs_matrix_mul "Link to this definition") Multiplies the current matrix Parameters: * **matrix** – Matrix to multiply the current stack matrix with * * * void gs\_matrix\_rotquat(const struct [quat](reference-libobs-graphics-quat#c.quat "quat") \*rot)[](#c.gs_matrix_rotquat "Link to this definition") Multiplies the current matrix with a quaternion Parameters: * **rot** – Quaternion to multiple the current matrix stack with * * * void gs\_matrix\_rotaa(const struct [axisang](reference-libobs-graphics-axisang#c.axisang "axisang") \*rot)[](#c.gs_matrix_rotaa "Link to this definition") void gs\_matrix\_rotaa4f(float x, float y, float z, float angle)[](#c.gs_matrix_rotaa4f "Link to this definition") Multiplies the current matrix with an axis angle Parameters: * **rot** – Axis angle to multiple the current matrix stack with * * * void gs\_matrix\_translate(const struct [vec3](reference-libobs-graphics-vec3#c.vec3 "vec3") \*pos)[](#c.gs_matrix_translate "Link to this definition") void gs\_matrix\_translate3f(float x, float y, float z)[](#c.gs_matrix_translate3f "Link to this definition") Translates the current matrix Parameters: * **pos** – Vector to translate the current matrix stack with * * * void gs\_matrix\_scale(const struct [vec3](reference-libobs-graphics-vec3#c.vec3 "vec3") \*scale)[](#c.gs_matrix_scale "Link to this definition") void gs\_matrix\_scale3f(float x, float y, float z)[](#c.gs_matrix_scale3f "Link to this definition") Scales the current matrix Parameters: * **scale** – Scale value to scale the current matrix stack with * * * Draw Functions[](#draw-functions "Link to this heading") ---------------------------------------------------------- [gs\_effect\_t](reference-libobs-graphics-effects#c.gs_effect_t "gs_effect_t") \*gs\_get\_effect(void)[](#c.gs_get_effect "Link to this definition") Returns: The currently active effect, or _NULL_ if none active * * * void gs\_draw\_sprite([gs\_texture\_t](#c.gs_texture_t "gs_texture_t") \*tex, uint32\_t flip, uint32\_t width, uint32\_t height)[](#c.gs_draw_sprite "Link to this definition") Draws a 2D sprite. Sets the “image” parameter of the current effect to the texture and renders a quad. If width or height is 0, the width or height of the texture will be used. The flip value specifies whether the texture should be flipped on the U or V axis with GS\_FLIP\_U and GS\_FLIP\_V. Parameters: * **tex** – Texture to draw * **flip** – Can be 0 or a bitwise-OR combination of one of the following values: * GS\_FLIP\_U - Flips the texture horizontally * GS\_FLIP\_V - Flips the texture vertically * **width** – Width * **height** – Height * * * void gs\_draw\_sprite\_subregion([gs\_texture\_t](#c.gs_texture_t "gs_texture_t") \*tex, uint32\_t flip, uint32\_t x, uint32\_t y, uint32\_t cx, uint32\_t cy)[](#c.gs_draw_sprite_subregion "Link to this definition") Draws a subregion of a 2D sprite. Sets the “image” parameter of the current effect to the texture and renders a quad. Parameters: * **tex** – Texture to draw * **flip** – Can be 0 or a bitwise-OR combination of one of the following values: * GS\_FLIP\_U - Flips the texture horizontally * GS\_FLIP\_V - Flips the texture vertically * **x** – X value within subregion * **y** – Y value within subregion * **cx** – CX value of subregion * **cy** – CY value of subregion * * * void gs\_reset\_viewport(void)[](#c.gs_reset_viewport "Link to this definition") Sets the viewport to current swap chain size * * * void gs\_set\_2d\_mode(void)[](#c.gs_set_2d_mode "Link to this definition") Sets the projection matrix to a default screen-sized orthographic mode * * * void gs\_set\_3d\_mode(double fovy, double znear, double zfar)[](#c.gs_set_3d_mode "Link to this definition") Sets the projection matrix to a default screen-sized perspective mode Parameters: * **fovy** – Field of view (in degrees) * **znear** – Near plane * **zfar** – Far plane * * * void gs\_viewport\_push(void)[](#c.gs_viewport_push "Link to this definition") Pushes/stores the current viewport * * * void gs\_viewport\_pop(void)[](#c.gs_viewport_pop "Link to this definition") Pops/recalls the last pushed viewport * * * void gs\_perspective(float fovy, float aspect, float znear, float zfar)[](#c.gs_perspective "Link to this definition") Sets the projection matrix to a perspective mode Parameters: * **fovy** – Field of view (in degrees) * **aspect** – Aspect ratio * **znear** – Near plane * **zfar** – Far plane * * * void gs\_blend\_state\_push(void)[](#c.gs_blend_state_push "Link to this definition") Pushes/stores the current blend state * * * void gs\_blend\_state\_pop(void)[](#c.gs_blend_state_pop "Link to this definition") Pops/restores the last blend state * * * void gs\_reset\_blend\_state(void)[](#c.gs_reset_blend_state "Link to this definition") Sets the blend state to the default value: source alpha and invert source alpha. * * * Swap Chains[](#swap-chains "Link to this heading") ---------------------------------------------------- [gs\_swapchain\_t](#c.gs_swapchain_t "gs_swapchain_t") \*gs\_swapchain\_create(const struct [gs\_init\_data](#c.gs_init_data "gs_init_data") \*data)[](#c.gs_swapchain_create "Link to this definition") Creates a swap chain (display view on a native widget) Parameters: * **data** – Swap chain initialization data Returns: New swap chain object, or _NULL_ if failed * * * void gs\_swapchain\_destroy([gs\_swapchain\_t](#c.gs_swapchain_t "gs_swapchain_t") \*swapchain)[](#c.gs_swapchain_destroy "Link to this definition") Destroys a swap chain * * * void gs\_resize(uint32\_t cx, uint32\_t cy)[](#c.gs_resize "Link to this definition") Resizes the currently active swap chain Parameters: * **cx** – New width * **cy** – New height * * * void gs\_update\_color\_space(void)[](#c.gs_update_color_space "Link to this definition") Updates the color space of the swap chain based on the HDR status of the nearest monitor * * * void gs\_get\_size(uint32\_t \*cx, uint32\_t \*cy)[](#c.gs_get_size "Link to this definition") Gets the size of the currently active swap chain Parameters: * **cx** – Pointer to receive width * **cy** – Pointer to receive height * * * uint32\_t gs\_get\_width(void)[](#c.gs_get_width "Link to this definition") Gets the width of the currently active swap chain * * * uint32\_t gs\_get\_height(void)[](#c.gs_get_height "Link to this definition") Gets the height of the currently active swap chain * * * Resource Loading[](#resource-loading "Link to this heading") -------------------------------------------------------------- void gs\_load\_vertexbuffer([gs\_vertbuffer\_t](#c.gs_vertbuffer_t "gs_vertbuffer_t") \*vertbuffer)[](#c.gs_load_vertexbuffer "Link to this definition") Loads a vertex buffer Parameters: * **vertbuffer** – Vertex buffer to load, or NULL to unload * * * void gs\_load\_indexbuffer([gs\_indexbuffer\_t](#c.gs_indexbuffer_t "gs_indexbuffer_t") \*indexbuffer)[](#c.gs_load_indexbuffer "Link to this definition") Loads a index buffer Parameters: * **indexbuffer** – Index buffer to load, or NULL to unload * * * void gs\_load\_texture([gs\_texture\_t](#c.gs_texture_t "gs_texture_t") \*tex, int unit)[](#c.gs_load_texture "Link to this definition") Loads a texture (this is usually not called manually) Parameters: * **tex** – Texture to load, or NULL to unload * **unit** – Texture unit to load texture for * * * void gs\_load\_samplerstate([gs\_samplerstate\_t](#c.gs_samplerstate_t "gs_samplerstate_t") \*samplerstate, int unit)[](#c.gs_load_samplerstate "Link to this definition") Loads a sampler state (this is usually not called manually) Parameters: * **samplerstate** – Sampler state to load, or NULL to unload * **unit** – Texture unit to load sampler state for * * * void gs\_load\_swapchain([gs\_swapchain\_t](#c.gs_swapchain_t "gs_swapchain_t") \*swapchain)[](#c.gs_load_swapchain "Link to this definition") Loads a swapchain Parameters: * **swapchain** – Swap chain to load, or NULL to unload * * * Draw Functions[](#id1 "Link to this heading") ----------------------------------------------- enum [gs\_color\_space](#c.gs_color_space "gs_color_space") gs\_get\_color\_space(void)[](#c.gs_get_color_space "Link to this definition") Returns: The currently active color space * * * [gs\_texture\_t](#c.gs_texture_t "gs_texture_t") \*gs\_get\_render\_target(void)[](#c.gs_get_render_target "Link to this definition") Returns: The currently active render target * * * [gs\_zstencil\_t](#c.gs_zstencil_t "gs_zstencil_t") \*gs\_get\_zstencil\_target(void)[](#c.gs_get_zstencil_target "Link to this definition") Returns: The currently active Z-stencil target * * * void gs\_set\_render\_target([gs\_texture\_t](#c.gs_texture_t "gs_texture_t") \*tex, [gs\_zstencil\_t](#c.gs_zstencil_t "gs_zstencil_t") \*zstencil)[](#c.gs_set_render_target "Link to this definition") Sets the active render target with implicit GS\_CS\_SRGB color space Parameters: * **tex** – Texture to set as the active render target * **zstencil** – Z-stencil to use as the active render target * * * void gs\_set\_render\_target\_with\_color\_space([gs\_texture\_t](#c.gs_texture_t "gs_texture_t") \*tex, [gs\_zstencil\_t](#c.gs_zstencil_t "gs_zstencil_t") \*zstencil, enum [gs\_color\_space](#c.gs_color_space "gs_color_space") space)[](#c.gs_set_render_target_with_color_space "Link to this definition") Sets the active render target along with color space Parameters: * **tex** – Texture to set as the active render target * **zstencil** – Z-stencil to use as the active render target * **space** – Color space of the render target * * * void gs\_set\_cube\_render\_target([gs\_texture\_t](#c.gs_texture_t "gs_texture_t") \*cubetex, int side, [gs\_zstencil\_t](#c.gs_zstencil_t "gs_zstencil_t") \*zstencil)[](#c.gs_set_cube_render_target "Link to this definition") Sets a cubemap side as the active render target Parameters: * **cubetex** – Cubemap * **side** – Cubemap side * **zstencil** – Z-stencil buffer, or _NULL_ if none * * * void gs\_copy\_texture([gs\_texture\_t](#c.gs_texture_t "gs_texture_t") \*dst, [gs\_texture\_t](#c.gs_texture_t "gs_texture_t") \*src)[](#c.gs_copy_texture "Link to this definition") Copies a texture Parameters: * **dst** – Destination texture * **src** – Source texture * * * void gs\_stage\_texture([gs\_stagesurf\_t](#c.gs_stagesurf_t "gs_stagesurf_t") \*dst, [gs\_texture\_t](#c.gs_texture_t "gs_texture_t") \*src)[](#c.gs_stage_texture "Link to this definition") Copies a texture to a staging surface and copies it to RAM. Ideally best to give this a frame to process to prevent stalling. Parameters: * **dst** – Staging surface * **src** – Texture to stage * * * void gs\_begin\_scene(void)[](#c.gs_begin_scene "Link to this definition") void gs\_end\_scene(void)[](#c.gs_end_scene "Link to this definition") Begins/ends a scene (this is automatically called by libobs, there’s no need to call this manually). * * * void gs\_draw(enum [gs\_draw\_mode](#c.gs_draw_mode "gs_draw_mode") draw\_mode, uint32\_t start\_vert, uint32\_t num\_verts)[](#c.gs_draw "Link to this definition") Draws a primitive or set of primitives. Parameters: * **draw\_mode** – The primitive draw mode to use * **start\_vert** – Starting vertex index * **num\_verts** – Number of vertices * * * void gs\_clear(uint32\_t clear\_flags, const struct [vec4](reference-libobs-graphics-vec4#c.vec4 "vec4") \*color, float depth, uint8\_t stencil)[](#c.gs_clear "Link to this definition") Clears color/depth/stencil buffers. Parameters: * **clear\_flags** – Flags to clear with. Can be one of the following values: * GS\_CLEAR\_COLOR - Clears color buffer * GS\_CLEAR\_DEPTH - Clears depth buffer * GS\_CLEAR\_STENCIL - Clears stencil buffer * **color** – Color value to clear the color buffer with * **depth** – Depth value to clear the depth buffer with * **stencil** – Stencil value to clear the stencil buffer with * * * void gs\_present(void)[](#c.gs_present "Link to this definition") Displays what was rendered on to the current render target * * * void gs\_flush(void)[](#c.gs_flush "Link to this definition") Flushes GPU calls * * * void gs\_set\_cull\_mode(enum [gs\_cull\_mode](#c.gs_cull_mode "gs_cull_mode") mode)[](#c.gs_set_cull_mode "Link to this definition") Sets the current cull mode. Parameters: * **mode** – Cull mode * * * enum [gs\_cull\_mode](#c.gs_cull_mode "gs_cull_mode") gs\_get\_cull\_mode(void)[](#c.gs_get_cull_mode "Link to this definition") Returns: The current cull mode * * * void gs\_enable\_blending(bool enable)[](#c.gs_enable_blending "Link to this definition") Enables/disables blending Parameters: * **enable** – _true_ to enable, _false_ to disable * * * void gs\_enable\_depth\_test(bool enable)[](#c.gs_enable_depth_test "Link to this definition") Enables/disables depth testing Parameters: * **enable** – _true_ to enable, _false_ to disable * * * void gs\_enable\_stencil\_test(bool enable)[](#c.gs_enable_stencil_test "Link to this definition") Enables/disables stencil testing Parameters: * **enable** – _true_ to enable, _false_ to disable * * * void gs\_enable\_stencil\_write(bool enable)[](#c.gs_enable_stencil_write "Link to this definition") Enables/disables stencil writing Parameters: * **enable** – _true_ to enable, _false_ to disable * * * void gs\_enable\_color(bool red, bool green, bool blue, bool alpha)[](#c.gs_enable_color "Link to this definition") Enables/disables specific color channels Parameters: * **red** – _true_ to enable red channel, _false_ to disable * **green** – _true_ to enable green channel, _false_ to disable * **blue** – _true_ to enable blue channel, _false_ to disable * **alpha** – _true_ to enable alpha channel, _false_ to disable * * * void gs\_blend\_function(enum [gs\_blend\_type](#c.gs_blend_type "gs_blend_type") src, enum [gs\_blend\_type](#c.gs_blend_type "gs_blend_type") dest)[](#c.gs_blend_function "Link to this definition") Sets the blend function’s source and destination factors Parameters: * **src** – Blend type for the blending equation’s source factors * **dest** – Blend type for the blending equation’s destination factors * * * void gs\_blend\_function\_separate(enum [gs\_blend\_type](#c.gs_blend_type "gs_blend_type") src\_c, enum [gs\_blend\_type](#c.gs_blend_type "gs_blend_type") dest\_c, enum [gs\_blend\_type](#c.gs_blend_type "gs_blend_type") src\_a, enum [gs\_blend\_type](#c.gs_blend_type "gs_blend_type") dest\_a)[](#c.gs_blend_function_separate "Link to this definition") Sets the blend function’s source and destination factors for RGB and alpha separately Parameters: * **src\_c** – Blend type for the blending equation’s source RGB factor * **dest\_c** – Blend type for the blending equation’s destination RGB factor * **src\_a** – Blend type for the blending equation’s source alpha factor * **dest\_a** – Blend type for the blending equation’s destination alpha factor * * * void gs\_blend\_op(enum gs\_blend\_op\_type op)[](#c.gs_blend_op "Link to this definition") Sets the blend function’s operation type Parameters: * **op** – Operation type for the blending equation * * * void gs\_depth\_function(enum [gs\_depth\_test](#c.gs_depth_test "gs_depth_test") test)[](#c.gs_depth_function "Link to this definition") Sets the depth function Parameters: * **test** – Sets the depth test type * * * void gs\_stencil\_function(enum [gs\_stencil\_side](#c.gs_stencil_side "gs_stencil_side") side, enum [gs\_depth\_test](#c.gs_depth_test "gs_depth_test") test)[](#c.gs_stencil_function "Link to this definition") Sets the stencil function Parameters: * **side** – Stencil side * **test** – Depth test * * * void gs\_stencil\_op(enum [gs\_stencil\_side](#c.gs_stencil_side "gs_stencil_side") side, enum [gs\_stencil\_op\_type](#c.gs_stencil_op_type "gs_stencil_op_type") fail, enum [gs\_stencil\_op\_type](#c.gs_stencil_op_type "gs_stencil_op_type") zfail, enum [gs\_stencil\_op\_type](#c.gs_stencil_op_type "gs_stencil_op_type") zpass)[](#c.gs_stencil_op "Link to this definition") Sets the stencil operation Parameters: * **side** – Stencil side * **fail** – Operation to perform on stencil test failure * **zfail** – Operation to perform on depth test failure * **zpass** – Operation to perform on depth test success * * * void gs\_set\_viewport(int x, int y, int width, int height)[](#c.gs_set_viewport "Link to this definition") Sets the current viewport Parameters: * **x** – X position relative to upper left * **y** – Y position relative to upper left * **width** – Width of the viewport * **height** – Height of the viewport * * * void gs\_get\_viewport(struct [gs\_rect](#c.gs_rect "gs_rect") \*rect)[](#c.gs_get_viewport "Link to this definition") Gets the current viewport Parameters: * **rect** – Pointer to receive viewport rectangle * * * void gs\_set\_scissor\_rect(const struct [gs\_rect](#c.gs_rect "gs_rect") \*rect)[](#c.gs_set_scissor_rect "Link to this definition") Sets or clears the current scissor rectangle Rect: Scissor rectangle, or _NULL_ to clear * * * void gs\_ortho(float left, float right, float top, float bottom, float znear, float zfar)[](#c.gs_ortho "Link to this definition") Sets the projection matrix to an orthographic matrix * * * void gs\_frustum(float left, float right, float top, float bottom, float znear, float zfar)[](#c.gs_frustum "Link to this definition") Sets the projection matrix to a frustum matrix * * * void gs\_projection\_push(void)[](#c.gs_projection_push "Link to this definition") Pushes/stores the current projection matrix * * * void gs\_projection\_pop(void)[](#c.gs_projection_pop "Link to this definition") Pops/restores the last projection matrix pushed * * * Texture Functions[](#texture-functions "Link to this heading") ---------------------------------------------------------------- [gs\_texture\_t](#c.gs_texture_t "gs_texture_t") \*gs\_texture\_create(uint32\_t width, uint32\_t height, enum [gs\_color\_format](#c.gs_color_format "gs_color_format") color\_format, uint32\_t levels, const uint8\_t \*\*data, uint32\_t flags)[](#c.gs_texture_create "Link to this definition") Creates a texture. Parameters: * **width** – Width * **height** – Height * **color\_format** – Color format * **levels** – Number of total texture levels. Set to 1 if no mip-mapping * **data** – Pointer to array of texture data pointers * **flags** – Can be 0 or a bitwise-OR combination of one or more of the following value: * GS\_BUILD\_MIPMAPS - Automatically builds mipmaps (Note: not fully tested) * GS\_DYNAMIC - Dynamic * GS\_RENDER\_TARGET - Render target Returns: A new texture object * * * [gs\_texture\_t](#c.gs_texture_t "gs_texture_t") \*gs\_texture\_create\_from\_file(const char \*file)[](#c.gs_texture_create_from_file "Link to this definition") Creates a texture from a file. Note that this isn’t recommended for animated gifs – instead use the [Image File Helper](reference-libobs-graphics-image-file#image-file-helper) . Parameters: * **file** – Image file to open * * * void gs\_texture\_destroy([gs\_texture\_t](#c.gs_texture_t "gs_texture_t") \*tex)[](#c.gs_texture_destroy "Link to this definition") Destroys a texture Parameters: * **tex** – Texture object * * * uint32\_t gs\_texture\_get\_width(const [gs\_texture\_t](#c.gs_texture_t "gs_texture_t") \*tex)[](#c.gs_texture_get_width "Link to this definition") Gets the texture’s width Parameters: * **tex** – Texture object Returns: The texture’s width * * * uint32\_t gs\_texture\_get\_height(const [gs\_texture\_t](#c.gs_texture_t "gs_texture_t") \*tex)[](#c.gs_texture_get_height "Link to this definition") Gets the texture’s height Parameters: * **tex** – Texture object Returns: The texture’s height * * * enum [gs\_color\_format](#c.gs_color_format "gs_color_format") gs\_texture\_get\_color\_format(const [gs\_texture\_t](#c.gs_texture_t "gs_texture_t") \*tex)[](#c.gs_texture_get_color_format "Link to this definition") Gets the texture’s color format Parameters: * **tex** – Texture object Returns: The texture’s color format * * * bool gs\_texture\_map([gs\_texture\_t](#c.gs_texture_t "gs_texture_t") \*tex, uint8\_t \*\*ptr, uint32\_t \*linesize)[](#c.gs_texture_map "Link to this definition") Maps a texture. Parameters: * **tex** – Texture object * **ptr** – Pointer to receive the pointer to the texture data to write to * **linesize** – Pointer to receive the line size (pitch) of the texture * * * void gs\_texture\_unmap([gs\_texture\_t](#c.gs_texture_t "gs_texture_t") \*tex)[](#c.gs_texture_unmap "Link to this definition") Unmaps a texture. Parameters: * **tex** – Texture object * * * void gs\_texture\_set\_image([gs\_texture\_t](#c.gs_texture_t "gs_texture_t") \*tex, const uint8\_t \*data, uint32\_t linesize, bool invert)[](#c.gs_texture_set_image "Link to this definition") Sets the image of a dynamic texture Parameters: * **tex** – Texture object * **data** – Data to set as the image * **linesize** – Line size (pitch) of the data * **invert** – _true_ to invert vertically, _false_ otherwise * * * [gs\_texture\_t](#c.gs_texture_t "gs_texture_t") \*gs\_texture\_create\_from\_dmabuf(unsigned int width, unsigned int height, uint32\_t drm\_format, enum [gs\_color\_format](#c.gs_color_format "gs_color_format") color\_format, uint32\_t n\_planes, const int \*fds, const uint32\_t \*strides, const uint32\_t \*offsets, const uint64\_t \*modifiers)[](#c.gs_texture_create_from_dmabuf "Link to this definition") **only Linux, FreeBSD, DragonFly:** Creates a texture from DMA-BUF metadata. Exchanging DMA-BUFs is a verbose process because of its multiplanar nature. For example, YUV can have each plane as a color channel, or a monitor buffer can have the cursor stored in a separate plane. This function treats the OBS Studio format and the DRM format separately. This allows creating textures from DMA-BUFs with unsupported formats (e.g. YUV) and perform the color format conversion using shaders. However, be careful to always try and match the formats correctly, otherwise textures can fail to be created or rendered. All modifiers passed in the modifiers array must be equal. Passing different modifiers for each plane is unsupported. Parameters: * **width** – Width of the texture * **height** – Height of the texture * **drm\_format** – DRM format of the DMA-BUF buffer * **color\_format** – Color format compatible with OBS Studio * **n\_planes** – Number of planes of the DMA-BUF * **fds** – Array of size _n\_planes_ with the file descriptor of each plane * **strides** – Array of size _n\_planes_ with the stride of each plane * **offsets** – Array of size _n\_planes_ with the offset of each plane * **modifiers** – Array of size _n\_planes_ with the modifier of each plane Returns: A texture object on success, or _NULL_ on failure Return type: gs\_texture\_t\* * * * enum gs\_dmabuf\_flags[](#c.gs_dmabuf_flags "Link to this definition") DMA-BUF capabilities: * GS\_DMABUF\_FLAG\_NONE * GS\_DMABUF\_FLAG\_SUPPORTS\_IMPLICIT\_MODIFIERS - Renderer supports implicit modifiers * * * bool \*gs\_query\_dmabuf\_capabilities(enum [gs\_dmabuf\_flags](#c.gs_dmabuf_flags "gs_dmabuf_flags") \*dmabuf\_flags, uint32\_t \*\*drm\_formats, size\_t \*n\_formats)[](#c.gs_query_dmabuf_capabilities "Link to this definition") **only Linux, FreeBSD, DragonFly:** Queries the capabilities for DMA-BUFs. Graphics cards can optimize frame buffers by storing them in custom layouts, depending on their hardware features. These layouts can make these frame buffers unsuitable for linear processing. This function allows querying whether the graphics card in use supports implicit modifiers, and the supported texture formats. The caller must free the drm\_formats array with bfree() after use. Parameters: * **dmabuf\_flags** – Pointer to receive a capability bitmap * **drm\_formats** – Pointer to receive an array of DRM formats * **n\_formats** – Pointer to receive the number of formats Return type: bool * * * bool \*gs\_query\_dmabuf\_modifiers\_for\_format(uint32\_t drm\_format, uint64\_t \*\*modifiers, size\_t \*n\_modifiers)[](#c.gs_query_dmabuf_modifiers_for_format "Link to this definition") **only Linux, FreeBSD, DragonFly:** Queries the supported DMA-BUF modifiers for a given format. This function queries all supported explicit modifiers for a format, stores them as an array and returns the number of supported modifiers. The caller must free the modifiers array with bfree() after use. Parameters: * **drm\_format** – DRM format of the DMA-BUF buffer * **modifiers** – Pointer to receive an array of modifiers * **n\_modifiers** – Pointer to receive the number of modifiers Return type: bool * * * [gs\_texture\_t](#c.gs_texture_t "gs_texture_t") \*gs\_texture\_create\_from\_iosurface(void \*iosurf)[](#c.gs_texture_create_from_iosurface "Link to this definition") **macOS only:** Creates a texture from an IOSurface. Parameters: * **iosurf** – IOSurface object * * * bool gs\_texture\_rebind\_iosurface([gs\_texture\_t](#c.gs_texture_t "gs_texture_t") \*texture, void \*iosurf)[](#c.gs_texture_rebind_iosurface "Link to this definition") **macOS only:** Rebinds a texture to another IOSurface Parameters: * **texture** – Texture object * **iosuf** – IOSurface object * * * [gs\_texture\_t](#c.gs_texture_t "gs_texture_t") \*gs\_texture\_create\_gdi(uint32\_t width, uint32\_t height)[](#c.gs_texture_create_gdi "Link to this definition") **Windows only:** Creates a GDI-interop texture Parameters: * **width** – Width * **height** – Height * * * void \*gs\_texture\_get\_dc([gs\_texture\_t](#c.gs_texture_t "gs_texture_t") \*gdi\_tex)[](#c.gs_texture_get_dc "Link to this definition") **Windows only:** Gets the HDC of a GDI-interop texture. Call [`gs_texture_release_dc()`](#c.gs_texture_release_dc "gs_texture_release_dc") to release the HDC. Parameters: * **gdi\_tex** – GDI-interop texture object Returns: HDC object * * * void gs\_texture\_release\_dc([gs\_texture\_t](#c.gs_texture_t "gs_texture_t") \*gdi\_tex)[](#c.gs_texture_release_dc "Link to this definition") **Windows only:** Releases the HDC of the GDI-interop texture. Parameters: * **gdi\_tex** – GDI-interop texture object * * * [gs\_texture\_t](#c.gs_texture_t "gs_texture_t") \*gs\_texture\_open\_shared(uint32\_t handle)[](#c.gs_texture_open_shared "Link to this definition") **Windows only:** Creates a texture from a shared texture handle. Parameters: * **handle** – Shared texture handle Returns: A texture object * * * bool gs\_gdi\_texture\_available(void)[](#c.gs_gdi_texture_available "Link to this definition") **Windows only:** Returns whether GDI-interop textures are available. Returns: _true_ if available, _false_ otherwise * * * bool gs\_shared\_texture\_available(void)[](#c.gs_shared_texture_available "Link to this definition") **Windows only:** Returns whether shared textures are available. Returns: _true_ if available, _false_ otherwise * * * Cube Texture Functions[](#cube-texture-functions "Link to this heading") -------------------------------------------------------------------------- [gs\_texture\_t](#c.gs_texture_t "gs_texture_t") \*gs\_cubetexture\_create(uint32\_t size, enum [gs\_color\_format](#c.gs_color_format "gs_color_format") color\_format, uint32\_t levels, const uint8\_t \*\*data, uint32\_t flags)[](#c.gs_cubetexture_create "Link to this definition") Creates a cubemap texture. Parameters: * **size** – Width/height/depth value * **color\_format** – Color format * **levels** – Number of texture levels * **data** – Pointer to array of texture data pointers * **flags** – Can be 0 or a bitwise-OR combination of one or more of the following value: * GS\_BUILD\_MIPMAPS - Automatically builds mipmaps (Note: not fully tested) * GS\_DYNAMIC - Dynamic * GS\_RENDER\_TARGET - Render target Returns: A new cube texture object * * * void gs\_cubetexture\_destroy([gs\_texture\_t](#c.gs_texture_t "gs_texture_t") \*cubetex)[](#c.gs_cubetexture_destroy "Link to this definition") Destroys a cube texture. Parameters: * **cubetex** – Cube texture object * * * uint32\_t gs\_cubetexture\_get\_size(const [gs\_texture\_t](#c.gs_texture_t "gs_texture_t") \*cubetex)[](#c.gs_cubetexture_get_size "Link to this definition") Get the width/height/depth value of a cube texture. Parameters: * **cubetex** – Cube texture object Returns: The width/height/depth value of the cube texture * * * enum [gs\_color\_format](#c.gs_color_format "gs_color_format") gs\_cubetexture\_get\_color\_format(const [gs\_texture\_t](#c.gs_texture_t "gs_texture_t") \*cubetex)[](#c.gs_cubetexture_get_color_format "Link to this definition") Gets the color format of a cube texture. Parameters: * **cubetex** – Cube texture object Returns: The color format of the cube texture * * * void gs\_cubetexture\_set\_image([gs\_texture\_t](#c.gs_texture_t "gs_texture_t") \*cubetex, uint32\_t side, const void \*data, uint32\_t linesize, bool invert)[](#c.gs_cubetexture_set_image "Link to this definition") Sets an image of a cube texture side. Parameters: * **cubetex** – Cube texture object * **side** – Side * **data** – Texture data to set * **linesize** – Line size (pitch) of the texture data * **invert** – _true_ to invert texture data, _false_ otherwise * * * Staging Surface Functions[](#staging-surface-functions "Link to this heading") -------------------------------------------------------------------------------- Staging surfaces are used to efficiently copy textures from VRAM to RAM. [gs\_stagesurf\_t](#c.gs_stagesurf_t "gs_stagesurf_t") \*gs\_stagesurface\_create(uint32\_t width, uint32\_t height, enum [gs\_color\_format](#c.gs_color_format "gs_color_format") color\_format)[](#c.gs_stagesurface_create "Link to this definition") Creates a staging surface. Parameters: * **width** – Width * **height** – Height * **color\_format** – Color format Returns: The staging surface object * * * void gs\_stagesurface\_destroy([gs\_stagesurf\_t](#c.gs_stagesurf_t "gs_stagesurf_t") \*stagesurf)[](#c.gs_stagesurface_destroy "Link to this definition") Destroys a staging surface. Parameters: * **stagesurf** – Staging surface object * * * uint32\_t gs\_stagesurface\_get\_width(const [gs\_stagesurf\_t](#c.gs_stagesurf_t "gs_stagesurf_t") \*stagesurf)[](#c.gs_stagesurface_get_width "Link to this definition") uint32\_t gs\_stagesurface\_get\_height(const [gs\_stagesurf\_t](#c.gs_stagesurf_t "gs_stagesurf_t") \*stagesurf)[](#c.gs_stagesurface_get_height "Link to this definition") Gets the width/height of a staging surface object. Parameters: * **stagesurf** – Staging surface object Returns: Width/height of the staging surface * * * enum [gs\_color\_format](#c.gs_color_format "gs_color_format") gs\_stagesurface\_get\_color\_format(const [gs\_stagesurf\_t](#c.gs_stagesurf_t "gs_stagesurf_t") \*stagesurf)[](#c.gs_stagesurface_get_color_format "Link to this definition") Gets the color format of a staging surface object. Parameters: * **stagesurf** – Staging surface object Returns: Color format of the staging surface * * * bool gs\_stagesurface\_map([gs\_stagesurf\_t](#c.gs_stagesurf_t "gs_stagesurf_t") \*stagesurf, uint8\_t \*\*data, uint32\_t \*linesize)[](#c.gs_stagesurface_map "Link to this definition") Maps the staging surface texture (for reading). Call [`gs_stagesurface_unmap()`](#c.gs_stagesurface_unmap "gs_stagesurface_unmap") to unmap when complete. Parameters: * **stagesurf** – Staging surface object * **data** – Pointer to receive texture data pointer * **linesize** – Pointer to receive line size (pitch) of the texture data Returns: _true_ if map successful, _false_ otherwise * * * void gs\_stagesurface\_unmap([gs\_stagesurf\_t](#c.gs_stagesurf_t "gs_stagesurf_t") \*stagesurf)[](#c.gs_stagesurface_unmap "Link to this definition") Unmaps a staging surface. Parameters: * **stagesurf** – Staging surface object * * * Z-Stencil Functions[](#z-stencil-functions "Link to this heading") -------------------------------------------------------------------- [gs\_zstencil\_t](#c.gs_zstencil_t "gs_zstencil_t") \*gs\_zstencil\_create(uint32\_t width, uint32\_t height, enum [gs\_zstencil\_format](#c.gs_zstencil_format "gs_zstencil_format") format)[](#c.gs_zstencil_create "Link to this definition") Creates a Z-stencil surface object. Parameters: * **width** – Width * **height** – Height * **format** – Format Returns: New Z-stencil surface object, or _NULL_ if failed * * * void gs\_zstencil\_destroy([gs\_zstencil\_t](#c.gs_zstencil_t "gs_zstencil_t") \*zstencil)[](#c.gs_zstencil_destroy "Link to this definition") Destroys a Z-stencil buffer. Parameters: * **zstencil** – Z-stencil surface object * * * Sampler State Functions[](#sampler-state-functions "Link to this heading") ---------------------------------------------------------------------------- [gs\_samplerstate\_t](#c.gs_samplerstate_t "gs_samplerstate_t") \*gs\_samplerstate\_create(const struct [gs\_sampler\_info](#c.gs_sampler_info "gs_sampler_info") \*info)[](#c.gs_samplerstate_create "Link to this definition") Creates a sampler state object. Parameters: * **info** – Sampler state information Returns: New sampler state object * * * void gs\_samplerstate\_destroy([gs\_samplerstate\_t](#c.gs_samplerstate_t "gs_samplerstate_t") \*samplerstate)[](#c.gs_samplerstate_destroy "Link to this definition") Destroys a sampler state object. Parameters: * **samplerstate** – Sampler state object * * * Vertex Buffer Functions[](#vertex-buffer-functions "Link to this heading") ---------------------------------------------------------------------------- [gs\_vertbuffer\_t](#c.gs_vertbuffer_t "gs_vertbuffer_t") \*gs\_vertexbuffer\_create(struct [gs\_vb\_data](#c.gs_vb_data "gs_vb_data") \*data, uint32\_t flags)[](#c.gs_vertexbuffer_create "Link to this definition") Creates a vertex buffer. Parameters: * **data** – Vertex buffer data to create vertex buffer with. The structure should be created with gs\_vbdata\_create(), and then buffers in this structure should be allocated with [`bmalloc()`](reference-libobs-util-bmem#c.bmalloc "bmalloc") , [`bzalloc()`](reference-libobs-util-bmem#c.bzalloc "bzalloc") , or [`brealloc()`](reference-libobs-util-bmem#c.brealloc "brealloc") . The ownership of the gs\_vb\_data pointer is then passed to the function, and they should not be destroyed by the caller once passed * **flags** – Creation flags. Can be 0 or a bitwise-OR combination of any of the following values: * GS\_DYNAMIC - Can be dynamically updated in real time. * GS\_DUP\_BUFFER - Do not pass buffer ownership of the structure or the buffer pointers within the structure. Returns: A new vertex buffer object, or _NULL_ if failed * * * void gs\_vertexbuffer\_destroy([gs\_vertbuffer\_t](#c.gs_vertbuffer_t "gs_vertbuffer_t") \*vertbuffer)[](#c.gs_vertexbuffer_destroy "Link to this definition") Destroys a vertex buffer object. Parameters: * **vertbuffer** – Vertex buffer object * * * void gs\_vertexbuffer\_flush([gs\_vertbuffer\_t](#c.gs_vertbuffer_t "gs_vertbuffer_t") \*vertbuffer)[](#c.gs_vertexbuffer_flush "Link to this definition") Flushes a vertex buffer to its interval vertex data object. To modify its internal vertex data, call [`gs_vertexbuffer_get_data()`](#c.gs_vertexbuffer_get_data "gs_vertexbuffer_get_data") . Can only be used with dynamic vertex buffer objects. Parameters: * **vertbuffer** – Vertex buffer object * * * void gs\_vertexbuffer\_flush\_direct([gs\_vertbuffer\_t](#c.gs_vertbuffer_t "gs_vertbuffer_t") \*vertbuffer, const struct [gs\_vb\_data](#c.gs_vb_data "gs_vb_data") \*data)[](#c.gs_vertexbuffer_flush_direct "Link to this definition") Directly flushes a vertex buffer to the specified vertex buffer data. . Can only be used with dynamic vertex buffer objects. Parameters: * **vertbuffer** – Vertex buffer object * **data** – Vertex buffer data to flush. Components that don’t need to be flushed can be left _NULL_ * * * struct [gs\_vb\_data](#c.gs_vb_data "gs_vb_data") \*gs\_vertexbuffer\_get\_data(const [gs\_vertbuffer\_t](#c.gs_vertbuffer_t "gs_vertbuffer_t") \*vertbuffer)[](#c.gs_vertexbuffer_get_data "Link to this definition") Gets the vertex buffer data associated with a vertex buffer object. This data can be changed and vertex buffer can be updated with [`gs_vertexbuffer_flush()`](#c.gs_vertexbuffer_flush "gs_vertexbuffer_flush") . Can only be used with dynamic vertex buffer objects. Parameters: * **vertbuffer** – Vertex buffer object Returns: Vertex buffer data structure * * * Index Buffer Functions[](#index-buffer-functions "Link to this heading") -------------------------------------------------------------------------- [gs\_indexbuffer\_t](#c.gs_indexbuffer_t "gs_indexbuffer_t") \*gs\_indexbuffer\_create(enum [gs\_index\_type](#c.gs_index_type "gs_index_type") type, void \*indices, size\_t num, uint32\_t flags)[](#c.gs_indexbuffer_create "Link to this definition") Creates an index buffer. Parameters: * **type** – Index buffer type * **indices** – Index buffer data. This buffer must be allocated with [`bmalloc()`](reference-libobs-util-bmem#c.bmalloc "bmalloc") , [`bzalloc()`](reference-libobs-util-bmem#c.bzalloc "bzalloc") , or `bralloc()`, and ownership of this buffer is passed to the index buffer object. * **num** – Number of indices in the buffer * **flags** – Creation flags. Can be 0 or a bitwise-OR combination of any of the following values: * GS\_DYNAMIC - Can be dynamically updated in real time. * GS\_DUP\_BUFFER - Do not pass buffer ownership Returns: A new index buffer object, or _NULL_ if failed * * * void gs\_indexbuffer\_destroy([gs\_indexbuffer\_t](#c.gs_indexbuffer_t "gs_indexbuffer_t") \*indexbuffer)[](#c.gs_indexbuffer_destroy "Link to this definition") Destroys an index buffer object. Parameters: * **indexbuffer** – Index buffer object * * * void gs\_indexbuffer\_flush([gs\_indexbuffer\_t](#c.gs_indexbuffer_t "gs_indexbuffer_t") \*indexbuffer)[](#c.gs_indexbuffer_flush "Link to this definition") Flushes a index buffer to its interval index data object. To modify its internal index data, call [`gs_indexbuffer_get_data()`](#c.gs_indexbuffer_get_data "gs_indexbuffer_get_data") . Can only be used with dynamic index buffer objects. Parameters: * **indexbuffer** – Index buffer object * * * void gs\_indexbuffer\_flush\_direct([gs\_indexbuffer\_t](#c.gs_indexbuffer_t "gs_indexbuffer_t") \*indexbuffer, const void \*data)[](#c.gs_indexbuffer_flush_direct "Link to this definition") Flushes a index buffer to the specified index buffer data. Can only be used with dynamic index buffer objects. Parameters: * **indexbuffer** – Index buffer object * **data** – Index buffer data to flush * * * void \*gs\_indexbuffer\_get\_data(const [gs\_indexbuffer\_t](#c.gs_indexbuffer_t "gs_indexbuffer_t") \*indexbuffer)[](#c.gs_indexbuffer_get_data "Link to this definition") Gets the index buffer data associated with a index buffer object. This data can be changed and index buffer can be updated with [`gs_indexbuffer_flush()`](#c.gs_indexbuffer_flush "gs_indexbuffer_flush") . Can only be used with dynamic index buffer objects. Parameters: * **vertbuffer** – Index buffer object Returns: Index buffer data pointer * * * size\_t gs\_indexbuffer\_get\_num\_indices(const [gs\_indexbuffer\_t](#c.gs_indexbuffer_t "gs_indexbuffer_t") \*indexbuffer)[](#c.gs_indexbuffer_get_num_indices "Link to this definition") Gets the number of indices associated with this index buffer. Parameters: * **indexbuffer** – Index buffer object Returns: Number of indices the vertex buffer object has * * * enum [gs\_index\_type](#c.gs_index_type "gs_index_type") gs\_indexbuffer\_get\_type(const [gs\_indexbuffer\_t](#c.gs_indexbuffer_t "gs_indexbuffer_t") \*indexbuffer)[](#c.gs_indexbuffer_get_type "Link to this definition") Gets the type of index buffer. Parameters: * **indexbuffer** – Index buffer object Returns: Index buffer type * * * Display Duplicator (Windows Only)[](#display-duplicator-windows-only "Link to this heading") ---------------------------------------------------------------------------------------------- [gs\_duplicator\_t](#c.gs_duplicator_t "gs_duplicator_t") \*gs\_duplicator\_create(int monitor\_idx)[](#c.gs_duplicator_create "Link to this definition") * * * void gs\_duplicator\_destroy([gs\_duplicator\_t](#c.gs_duplicator_t "gs_duplicator_t") \*duplicator)[](#c.gs_duplicator_destroy "Link to this definition") * * * bool gs\_duplicator\_update\_frame([gs\_duplicator\_t](#c.gs_duplicator_t "gs_duplicator_t") \*duplicator)[](#c.gs_duplicator_update_frame "Link to this definition") * * * [gs\_texture\_t](#c.gs_texture_t "gs_texture_t") \*gs\_duplicator\_get\_texture([gs\_duplicator\_t](#c.gs_duplicator_t "gs_duplicator_t") \*duplicator)[](#c.gs_duplicator_get_texture "Link to this definition") * * * bool gs\_get\_duplicator\_monitor\_info(int monitor\_idx, struct [gs\_monitor\_info](#c.gs_monitor_info "gs_monitor_info") \*monitor\_info)[](#c.gs_get_duplicator_monitor_info "Link to this definition") * * * Monitor Functions[](#monitor-functions "Link to this heading") ---------------------------------------------------------------- bool gs\_is\_monitor\_hdr(void \*monitor)[](#c.gs_is_monitor_hdr "Link to this definition") * * * Render Helper Functions[](#render-helper-functions "Link to this heading") ---------------------------------------------------------------------------- void gs\_render\_start(bool b\_new)[](#c.gs_render_start "Link to this definition") * * * void gs\_render\_stop(enum [gs\_draw\_mode](#c.gs_draw_mode "gs_draw_mode") mode)[](#c.gs_render_stop "Link to this definition") * * * [gs\_vertbuffer\_t](#c.gs_vertbuffer_t "gs_vertbuffer_t") \*gs\_render\_save(void)[](#c.gs_render_save "Link to this definition") * * * void gs\_vertex2f(float x, float y)[](#c.gs_vertex2f "Link to this definition") * * * void gs\_vertex3f(float x, float y, float z)[](#c.gs_vertex3f "Link to this definition") * * * void gs\_normal3f(float x, float y, float z)[](#c.gs_normal3f "Link to this definition") * * * void gs\_color(uint32\_t color)[](#c.gs_color "Link to this definition") * * * void gs\_texcoord(float x, float y, int unit)[](#c.gs_texcoord "Link to this definition") * * * void gs\_vertex2v(const struct [vec2](reference-libobs-graphics-vec2#c.vec2 "vec2") \*v)[](#c.gs_vertex2v "Link to this definition") * * * void gs\_vertex3v(const struct [vec3](reference-libobs-graphics-vec3#c.vec3 "vec3") \*v)[](#c.gs_vertex3v "Link to this definition") * * * void gs\_normal3v(const struct [vec3](reference-libobs-graphics-vec3#c.vec3 "vec3") \*v)[](#c.gs_normal3v "Link to this definition") * * * void gs\_color4v(const struct [vec4](reference-libobs-graphics-vec4#c.vec4 "vec4") \*v)[](#c.gs_color4v "Link to this definition") * * * void gs\_texcoord2v(const struct [vec2](reference-libobs-graphics-vec2#c.vec2 "vec2") \*v, int unit)[](#c.gs_texcoord2v "Link to this definition") * * * Graphics Types[](#graphics-types "Link to this heading") ---------------------------------------------------------- typedef struct gs\_duplicator gs\_duplicator\_t[](#c.gs_duplicator_t "Link to this definition") typedef struct gs\_texture gs\_texture\_t[](#c.gs_texture_t "Link to this definition") typedef struct gs\_stage\_surface gs\_stagesurf\_t[](#c.gs_stagesurf_t "Link to this definition") typedef struct gs\_zstencil\_buffer gs\_zstencil\_t[](#c.gs_zstencil_t "Link to this definition") typedef struct gs\_vertex\_buffer gs\_vertbuffer\_t[](#c.gs_vertbuffer_t "Link to this definition") typedef struct gs\_index\_buffer gs\_indexbuffer\_t[](#c.gs_indexbuffer_t "Link to this definition") typedef struct gs\_sampler\_state gs\_samplerstate\_t[](#c.gs_samplerstate_t "Link to this definition") typedef struct gs\_swap\_chain gs\_swapchain\_t[](#c.gs_swapchain_t "Link to this definition") typedef struct gs\_texture\_render gs\_texrender\_t[](#c.gs_texrender_t "Link to this definition") typedef struct gs\_shader gs\_shader\_t[](#c.gs_shader_t "Link to this definition") typedef struct gs\_shader\_param gs\_sparam\_t[](#c.gs_sparam_t "Link to this definition") typedef struct gs\_device gs\_device\_t[](#c.gs_device_t "Link to this definition") typedef struct graphics\_subsystem graphics\_t[](#c.graphics_t "Link to this definition") --- # Media I/O API Reference (libobs/media-io) — OBS Studio 31.0.2 documentation * [](index) * Media I/O API Reference (libobs/media-io) * [Edit on GitHub](https://github.com/OBSProject/obs-studio/edit/master/docs/sphinx/reference-libobs-media-io.rst) [Previous](reference-libobs-graphics-graphics "Core Graphics API") [Next](reference-frontend-api "OBS Studio Frontend API") * * * Media I/O API Reference (libobs/media-io)[](#media-i-o-api-reference-libobs-media-io "Link to this heading") ============================================================================================================== #include Video Handler[](#video-handler "Link to this heading") -------------------------------------------------------- type video\_t[](#c.video_t "Link to this definition") Video output handler object * * * enum video\_format[](#c.video_format "Link to this definition") 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 * VIDEO\_FORMAT\_BGR3 * VIDEO\_FORMAT\_I422 * VIDEO\_FORMAT\_I40A * VIDEO\_FORMAT\_I42A * VIDEO\_FORMAT\_YUVA * VIDEO\_FORMAT\_AYUV * VIDEO\_FORMAT\_I010 * VIDEO\_FORMAT\_P010 * VIDEO\_FORMAT\_I210 * VIDEO\_FORMAT\_I412 * VIDEO\_FORMAT\_YA2L * VIDEO\_FORMAT\_P216 * VIDEO\_FORMAT\_P416 * VIDEO\_FORMAT\_V210 * VIDEO\_FORMAT\_R10L * * * enum video\_trc[](#c.video_trc "Link to this definition") Transfer characteristics. Can be one of the following values: * VIDEO\_TRC\_DEFAULT - sRGB TRC for SDR, PQ TRC for HDR * VIDEO\_TRC\_SRGB - sRGB TRC * VIDEO\_TRC\_PQ - PQ * VIDEO\_TRC\_HLG - HLG * * * enum video\_colorspace[](#c.video_colorspace "Link to this definition") YUV color space. Can be one of the following values: * VIDEO\_CS\_DEFAULT - Equivalent to VIDEO\_CS\_709 * VIDEO\_CS\_601 - Rec. 601 color space * VIDEO\_CS\_709 - Rec. 709 color space * VIDEO\_CS\_SRGB - sRGB color space * VIDEO\_CS\_2100\_PQ - Rec. 2100 color space, PQ transfer * VIDEO\_CS\_2100\_HLG - Rec. 2100 color space, HLG transfer * * * enum video\_range\_type[](#c.video_range_type "Link to this definition") YUV color range. * VIDEO\_RANGE\_DEFAULT - Equivalent to VIDEO\_RANGE\_PARTIAL * VIDEO\_RANGE\_PARTIAL - Partial range * VIDEO\_RANGE\_FULL - Full range * * * struct video\_data[](#c.video_data "Link to this definition") Video frame structure. uint8\_t \*[video\_data](#c.video_data "video_data") .data\[MAX\_AV\_PLANES\][](#c.video_data.data "Link to this definition") uint32\_t [video\_data](#c.video_data "video_data") .linesize\[MAX\_AV\_PLANES\][](#c.video_data.linesize "Link to this definition") uint64\_t [video\_data](#c.video_data "video_data") .timestamp[](#c.video_data.timestamp "Link to this definition") * * * struct video\_output\_info[](#c.video_output_info "Link to this definition") Video output handler information const char \*[video\_output\_info](#c.video_output_info "video_output_info") .name[](#c.video_output_info.name "Link to this definition") enum [video\_format](#c.video_format "video_format") [video\_output\_info](#c.video_output_info "video_output_info") .format[](#c.video_output_info.format "Link to this definition") uint32\_t [video\_output\_info](#c.video_output_info "video_output_info") .fps\_num[](#c.video_output_info.fps_num "Link to this definition") uint32\_t [video\_output\_info](#c.video_output_info "video_output_info") .fps\_den[](#c.video_output_info.fps_den "Link to this definition") uint32\_t [video\_output\_info](#c.video_output_info "video_output_info") .width[](#c.video_output_info.width "Link to this definition") uint32\_t [video\_output\_info](#c.video_output_info "video_output_info") .height[](#c.video_output_info.height "Link to this definition") size\_t [video\_output\_info](#c.video_output_info "video_output_info") .cache\_size[](#c.video_output_info.cache_size "Link to this definition") enum [video\_colorspace](#c.video_colorspace "video_colorspace") [video\_output\_info](#c.video_output_info "video_output_info") .colorspace[](#c.video_output_info.colorspace "Link to this definition") enum [video\_range\_type](#c.video_range_type "video_range_type") [video\_output\_info](#c.video_output_info "video_output_info") .range[](#c.video_output_info.range "Link to this definition") * * * enum [video\_format](#c.video_format "video_format") video\_format\_from\_fourcc(uint32\_t fourcc)[](#c.video_format_from_fourcc "Link to this definition") Converts a fourcc value to a video format. Parameters: * **forcecc** – Fourcc value Returns: Video format * * * bool video\_format\_get\_parameters(enum [video\_colorspace](#c.video_colorspace "video_colorspace") color\_space, enum [video\_range\_type](#c.video_range_type "video_range_type") range, float matrix\[16\], float min\_range\[3\], float max\_range\[3\])[](#c.video_format_get_parameters "Link to this definition") Converts a color space/range to matrix/min/max values. Parameters: * **color\_space** – Color space to convert * **range** – Color range to convert * **matrix** – Pointer to the matrix * **min\_range** – Pointer to get the minimum range value * **max\_range** – Pointer to get the maximum range value * * * bool video\_format\_get\_parameters\_for\_format(enum [video\_colorspace](#c.video_colorspace "video_colorspace") color\_space, enum [video\_range\_type](#c.video_range_type "video_range_type") range, enum [video\_format](#c.video_format "video_format") format, float matrix\[16\], float min\_range\[3\], float max\_range\[3\])[](#c.video_format_get_parameters_for_format "Link to this definition") Converts a color space/range to matrix/min/max values for a given video format. Parameters: * **color\_space** – Color space to convert * **range** – Color range to convert * **format** – Video format * **matrix** – Pointer to the matrix * **min\_range** – Pointer to get the minimum range value * **max\_range** – Pointer to get the maximum range value * * * bool video\_output\_connect([video\_t](#c.video_t "video_t") \*video, const struct video\_scale\_info \*conversion, void (\*callback)(void \*param, struct [video\_data](#c.video_data "video_data") \*frame), void \*param)[](#c.video_output_connect "Link to this definition") Connects a raw video callback to the video output handler. Parameters: * **video** – Video output handler object * **callback** – Callback to receive video data * **param** – Private data to pass to the callback * * * void video\_output\_disconnect([video\_t](#c.video_t "video_t") \*video, void (\*callback)(void \*param, struct [video\_data](#c.video_data "video_data") \*frame), void \*param)[](#c.video_output_disconnect "Link to this definition") Disconnects a raw video callback from the video output handler. Parameters: * **video** – Video output handler object * **callback** – Callback * **param** – Private data * * * const struct [video\_output\_info](#c.video_output_info "video_output_info") \*video\_output\_get\_info(const [video\_t](#c.video_t "video_t") \*video)[](#c.video_output_get_info "Link to this definition") Gets the full video information of the video output handler. Parameters: * **video** – Video output handler object Returns: Video output info structure pointer * * * uint64\_t video\_output\_get\_frame\_time(const [video\_t](#c.video_t "video_t") \*video)[](#c.video_output_get_frame_time "Link to this definition") Gets the frame interval of the video output handler. Parameters: * **video** – Video output handler object Returns: Video frame interval in nanoseconds * * * enum [video\_format](#c.video_format "video_format") video\_output\_get\_format(const [video\_t](#c.video_t "video_t") \*video)[](#c.video_output_get_format "Link to this definition") Gets the video format of the video output handler. Parameters: * **video** – Video output handler object Returns: Video format * * * uint32\_t video\_output\_get\_width(const [video\_t](#c.video_t "video_t") \*video)[](#c.video_output_get_width "Link to this definition") uint32\_t video\_output\_get\_height(const [video\_t](#c.video_t "video_t") \*video)[](#c.video_output_get_height "Link to this definition") Gets the width/height of the video output handler. Parameters: * **video** – Video output handler object Returns: Width/height * * * double video\_output\_get\_frame\_rate(const [video\_t](#c.video_t "video_t") \*video)[](#c.video_output_get_frame_rate "Link to this definition") Gets the frame rate (as a floating point) of the video output handler. Parameters: * **video** – Video output handler object Returns: Frame rate * * * uint32\_t video\_output\_get\_skipped\_frames(const [video\_t](#c.video_t "video_t") \*video)[](#c.video_output_get_skipped_frames "Link to this definition") Gets the skipped frame count of the video output handler. Parameters: * **video** – Video output handler object Returns: Skipped frame count * * * uint32\_t video\_output\_get\_total\_frames(const [video\_t](#c.video_t "video_t") \*video)[](#c.video_output_get_total_frames "Link to this definition") Gets the total frames processed of the video output handler. Parameters: * **video** – Video output handler object Returns: Total frames processed * * * Audio Handler[](#audio-handler "Link to this heading") -------------------------------------------------------- type audio\_t[](#c.audio_t "Link to this definition") * * * enum audio\_format[](#c.audio_format "Link to this definition") 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 * * * enum speaker\_layout[](#c.speaker_layout "Link to this definition") Speaker layout. Can be one of the following values: * SPEAKERS\_UNKNOWN * SPEAKERS\_MONO * SPEAKERS\_STEREO * SPEAKERS\_2POINT1 * SPEAKERS\_4POINT0 * SPEAKERS\_4POINT1 * SPEAKERS\_5POINT1 * SPEAKERS\_7POINT1 * * * struct audio\_data[](#c.audio_data "Link to this definition") Audio data structure. uint8\_t \*[audio\_data](#c.audio_data "audio_data") .data\[MAX\_AV\_PLANES\][](#c.audio_data.data "Link to this definition") uint32\_t [audio\_data](#c.audio_data "audio_data") .frames[](#c.audio_data.frames "Link to this definition") uint64\_t [audio\_data](#c.audio_data "audio_data") .timestamp[](#c.audio_data.timestamp "Link to this definition") * * * struct audio\_output\_data[](#c.audio_output_data "Link to this definition") float \*[audio\_output\_data](#c.audio_output_data "audio_output_data") .data\[MAX\_AUDIO\_CHANNELS\][](#c.audio_output_data.data "Link to this definition") * * * struct audio\_output\_info[](#c.audio_output_info "Link to this definition") const char \*[audio\_output\_info](#c.audio_output_info "audio_output_info") .name[](#c.audio_output_info.name "Link to this definition") uint32\_t [audio\_output\_info](#c.audio_output_info "audio_output_info") .samples\_per\_sec[](#c.audio_output_info.samples_per_sec "Link to this definition") enum [audio\_format](#c.audio_format "audio_format") [audio\_output\_info](#c.audio_output_info "audio_output_info") .format[](#c.audio_output_info.format "Link to this definition") enum [speaker\_layout](#c.speaker_layout "speaker_layout") [audio\_output\_info](#c.audio_output_info "audio_output_info") .speakers[](#c.audio_output_info.speakers "Link to this definition") [audio\_input\_callback\_t](#c.audio_input_callback_t "audio_input_callback_t") [audio\_output\_info](#c.audio_output_info "audio_output_info") .input\_callback[](#c.audio_output_info.input_callback "Link to this definition") void \*[audio\_output\_info](#c.audio_output_info "audio_output_info") .input\_param[](#c.audio_output_info.input_param "Link to this definition") * * * struct audio\_convert\_info[](#c.audio_convert_info "Link to this definition") uint32\_t [audio\_convert\_info](#c.audio_convert_info "audio_convert_info") .samples\_per\_sec[](#c.audio_convert_info.samples_per_sec "Link to this definition") enum [audio\_format](#c.audio_format "audio_format") [audio\_convert\_info](#c.audio_convert_info "audio_convert_info") .format[](#c.audio_convert_info.format "Link to this definition") enum [speaker\_layout](#c.speaker_layout "speaker_layout") [audio\_convert\_info](#c.audio_convert_info "audio_convert_info") .speakers[](#c.audio_convert_info.speakers "Link to this definition") * * * 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](#c.audio_output_data "audio_output_data") \*mixes)[](#c.audio_input_callback_t "Link to this definition") Audio input callback (typically used internally). * * * uint32\_t get\_audio\_channels(enum [speaker\_layout](#c.speaker_layout "speaker_layout") speakers)[](#c.get_audio_channels "Link to this definition") Converts a speaker layout to its audio channel count. Parameters: * **speakers** – Speaker layout enumeration Returns: Channel count * * * size\_t get\_audio\_bytes\_per\_channel(enum [audio\_format](#c.audio_format "audio_format") format)[](#c.get_audio_bytes_per_channel "Link to this definition") Gets the audio bytes per channel for a specific audio format. Parameters: * **format** – Audio format Returns: Bytes per channel * * * bool is\_audio\_planar(enum [audio\_format](#c.audio_format "audio_format") format)[](#c.is_audio_planar "Link to this definition") Returns whether the audio format is a planar format. Parameters: * **format** – Audio format Returns: _true_ if audio is planar, _false_ otherwise * * * size\_t get\_audio\_planes(enum [audio\_format](#c.audio_format "audio_format") format, enum [speaker\_layout](#c.speaker_layout "speaker_layout") speakers)[](#c.get_audio_planes "Link to this definition") Gets the number of audio planes for a specific audio format and speaker layout. Parameters: * **format** – Audio format * **speakers** – Speaker layout Returns: Number of audio planes * * * size\_t get\_audio\_size(enum [audio\_format](#c.audio_format "audio_format") format, enum [speaker\_layout](#c.speaker_layout "speaker_layout") speakers, uint32\_t frames)[](#c.get_audio_size "Link to this definition") Gets the audio block size for a specific frame out with the given format and speaker layout. Parameters: * **format** – Audio format * **speakers** – Speaker layout * **frames** – Audio frame count Returns: Audio block size * * * uint64\_t audio\_frames\_to\_ns(size\_t sample\_rate, uint64\_t frames)[](#c.audio_frames_to_ns "Link to this definition") Helper function to convert a specific number of audio frames to nanoseconds based upon its sample rate. Parameters: * **sample\_rate** – Sample rate * **frames** – Frame count Returns: Nanoseconds * * * uint64\_t ns\_to\_audio\_frames(size\_t sample\_rate, uint64\_t ns)[](#c.ns_to_audio_frames "Link to this definition") Helper function to convert a specific number of nanoseconds to audio frame count based upon its sample rate. Parameters: * **sample\_rate** – Sample rate * **ns** – Nanoseconds Returns: Frame count * * * typedef void (\*audio\_output\_callback\_t)(void \*param, size\_t mix\_idx, struct [audio\_data](#c.audio_data "audio_data") \*data)[](#c.audio_output_callback_t "Link to this definition") Audio output callback. Typically used internally. * * * bool audio\_output\_connect([audio\_t](#c.audio_t "audio_t") \*audio, size\_t mix\_idx, const struct [audio\_convert\_info](#c.audio_convert_info "audio_convert_info") \*conversion, [audio\_output\_callback\_t](#c.audio_output_callback_t "audio_output_callback_t") callback, void \*param)[](#c.audio_output_connect "Link to this definition") Connects a raw audio callback to the audio output handler. Optionally allows audio conversion if necessary. Parameters: * **audio** – Audio output handler object * **mix\_idx** – Mix index to get raw audio from * **conversion** – Audio conversion information, or _NULL_ for no conversion * **callback** – Raw audio callback * **param** – Private data to pass to the callback * * * void audio\_output\_disconnect([audio\_t](#c.audio_t "audio_t") \*audio, size\_t mix\_idx, [audio\_output\_callback\_t](#c.audio_output_callback_t "audio_output_callback_t") callback, void \*param)[](#c.audio_output_disconnect "Link to this definition") Disconnects a raw audio callback from the audio output handler. Parameters: * **audio** – Audio output handler object * **mix\_idx** – Mix index to get raw audio from * **callback** – Raw audio callback * **param** – Private data to pass to the callback * * * size\_t audio\_output\_get\_block\_size(const [audio\_t](#c.audio_t "audio_t") \*audio)[](#c.audio_output_get_block_size "Link to this definition") Gets the audio block size of an audio output handler. Parameters: * **audio** – Audio output handler object Returns: Audio block size * * * size\_t audio\_output\_get\_planes(const [audio\_t](#c.audio_t "audio_t") \*audio)[](#c.audio_output_get_planes "Link to this definition") Gets the plane count of an audio output handler. Parameters: * **audio** – Audio output handler object Returns: Audio plane count * * * size\_t audio\_output\_get\_channels(const [audio\_t](#c.audio_t "audio_t") \*audio)[](#c.audio_output_get_channels "Link to this definition") Gets the channel count of an audio output handler. Parameters: * **audio** – Audio output handler object Returns: Audio channel count * * * uint32\_t audio\_output\_get\_sample\_rate(const [audio\_t](#c.audio_t "audio_t") \*audio)[](#c.audio_output_get_sample_rate "Link to this definition") Gets the sample rate of an audio output handler. Parameters: * **audio** – Audio output handler object Returns: Audio sample rate * * * const struct [audio\_output\_info](#c.audio_output_info "audio_output_info") \*audio\_output\_get\_info(const [audio\_t](#c.audio_t "audio_t") \*audio)[](#c.audio_output_get_info "Link to this definition") Gets all audio information for an audio output handler. Parameters: * **audio** – Audio output handler object Returns: Pointer to audio output information structure * * * Resampler[](#resampler "Link to this heading") ------------------------------------------------ FFmpeg wrapper to resample audio. typedef struct audio\_resampler audio\_resampler\_t[](#c.audio_resampler_t "Link to this definition") * * * struct resample\_info[](#c.resample_info "Link to this definition") uint32\_t [resample\_info](#c.resample_info "resample_info") .samples\_per\_sec[](#c.resample_info.samples_per_sec "Link to this definition") enum [audio\_format](#c.audio_format "audio_format") [resample\_info](#c.resample_info "resample_info") .format[](#c.resample_info.format "Link to this definition") enum [speaker\_layout](#c.speaker_layout "speaker_layout") [resample\_info](#c.resample_info "resample_info") .speakers[](#c.resample_info.speakers "Link to this definition") * * * [audio\_resampler\_t](#c.audio_resampler_t "audio_resampler_t") \*audio\_resampler\_create(const struct [resample\_info](#c.resample_info "resample_info") \*dst, const struct [resample\_info](#c.resample_info "resample_info") \*src)[](#c.audio_resampler_create "Link to this definition") Creates an audio resampler. Parameters: * **dst** – Destination audio information * **src** – Source audio information Returns: Audio resampler object * * * void audio\_resampler\_destroy([audio\_resampler\_t](#c.audio_resampler_t "audio_resampler_t") \*resampler)[](#c.audio_resampler_destroy "Link to this definition") Destroys an audio resampler. Parameters: * **resampler** – Audio resampler object * * * bool audio\_resampler\_resample([audio\_resampler\_t](#c.audio_resampler_t "audio_resampler_t") \*resampler, uint8\_t \*output\[\], uint32\_t \*out\_frames, uint64\_t \*ts\_offset, const uint8\_t \*const input\[\], uint32\_t in\_frames)[](#c.audio_resampler_resample "Link to this definition") Resamples audio frames. Parameters: * **resampler** – Audio resampler object * **output** – Pointer to receive converted audio frames * **out\_frames** – Pointer to receive converted audio frame count * **ts\_offset** – Pointer to receive timestamp offset (in nanoseconds) * **input** – Input frames to convert * **in\_frames** – Input frame count ---