OBS ShaderFilter Plus is a plugin for Open Broadcaster Software. It can be used to apply effects to sources using manually created GLSL/HLSL shaders.
Example shaders may be found in the examples
directory of this repository. It is a good starting point for the creation of custom effects.
Shaders are programs executed on the GPU. They can be used to apply customizable special visual effects. The shaders used by this plugin are a special subset of shaders called fragment shaders. These shaders are executed once for each pixel of the source, every frame. See Usage Guide for examples.
Different graphics interfaces, such as OpenGL and DirectX, use different shader languages with incompatible syntax, so it is important to be aware of the graphics interfaces OBS makes use of.
Shaders are executed using OpenGL (GLSL shaders) or DirectX (HLSL shaders), depending on your platform.
When OBS is run with OpenGL, it performs primitive translation of HLSL sources to GLSL. However, this translation is limited and performed via basic string substitution, and therefore may not result in correct behavior. Despite these limitations, cross platform shaders could be written in HLSL, as long as they are simple.
OBS on Windows may be forced to use OpenGL by launching the program with the --allow-opengl
launch parameter. This can be done by creating a shortcut to the executable and appending the parameter to the path, for example: "C:\Program Files\obs-studio\bin\64bit\obs64.exe" --allow-opengl
. After launching OBS this way, the OpenGL renderer must be selected in the Advanced Settings. After restarting OBS with these settings applied, GLSL shaders will work properly.
_windows_x64.dll
_linux_x64.so
C:\Program Files\obs-studio\obs-plugins\64bit
/usr/lib/obs-plugins
The structure of a shader is simple. All, that is required, is the following render
function.
float4 render(float2 uv) {
// sample the source texture and return its color to be displayed
return image.Sample(builtin_texture_sampler, uv);
}
Every shader loaded by this plugin has access to the following uniform variables.
uniform texture2d image; // the source texture (the image we are filtering)
uniform int builtin_frame; // the current frame number
uniform float builtin_framerate; // the current output framerate
uniform float builtin_elapsed_time; // the current elapsed time
uniform float builtin_elapsed_time_previous; // the elapsed time in the previous frame
uniform float builtin_elapsed_time_since_shown; // the time since the source this filter is applied to was shown
uniform float builtin_elapsed_time_since_shown_previous; // the time since the source this filter is applied to was shown of the previous frame
uniform float builtin_elapsed_time_since_enabled; // the time since the filter itself was shown
uniform float builtin_elapsed_time_since_enabled_previous; // the time since the filter itself was shown of the previous frame
uniform int2 builtin_uv_size; // the source dimensions
sampler_state builtin_texture_sampler { ... }; // a texture sampler with linear filtering
These uniform variables will be assigned data by the plugin. If they are not defined, they do not use up processing resources.
uniform texture2d builtin_texture_fft_<NAME>; // audio output frequency spectrum
uniform texture2d builtin_texture_fft_<NAME>_previous; // output from the previous frame (requires builtin_texture_fft_<NAME> to be defined)
Builtin FFT variables have specific properties. See the the section below on properties.
Example:
#pragma shaderfilter set myfft__mix__description Main Mix/Track
#pragma shaderfilter set myfft__channel__description Main Channel
#pragma shaderfilter set myfft__dampening_factor_attack__step 0.0001
#pragma shaderfilter set myfft__dampening_factor_attack__default 0.05
#pragma shaderfilter set myfft__dampening_factor_release 0.0001
uniform texture2d builtin_texture_fft_myfft;
See the examples
directory for more examples.
These uniform variables may be used to let the user provide values to the shader using the OBS UI. The allowed types are:
bool
: A boolean variableint
: A signed 32-bit integer variablefloat
: A single precision floating point variablefloat4
/vec4
: A color variable, shown as a color picker in the UIExample:
#pragma shaderfilter set my_color__description My Color
#pragma shaderfilter set my_color__default 7FFF00FF
uniform float4 my_color;
See the examples
directory for more examples.
This plugin uses a simple preprocessor to process #pragma shaderfilter
macros.
It is not a fully-featured C preprocessor. It is executed before the shader is
compiled. The shader compilation includes an actual C preprocessing step.
Do not expect to be able to use macros within #pragma shaderfilter
.
Most properties can be specified in the shader source code. The syntax is as follows:
#pragma shaderfilter set <PROPERTY> <VALUE>
These properties can be applied to any user-defined uniform variable.
default
: The default value of the uniform variable.description
: The user-facing text describing the variable. Displayed in the OBS UI.min
(integer): The minimum allowed valuemax
(integer): The maximum allowed valuestep
(integer): The stride when changing the valueslider
(true/false): Whether to display a slider or notmin
(float): The minimum allowed valuemax
(float): The maximum allowed valuestep
(float): The stride when changing the valueslider
(true/false): Whether to display a slider or notmix
: The Mix/Track number corresponding to checkboxes in OBS' Advanced Audio Properties
channel
: The channel number (0 = Left, 1 = Right for stereo)dampening_factor_attack
: The linear interpolation coefficient (in percentage) used to blend the previous FFT sample with the current sample, if it is larger than the previousdampening_factor_release
: The linear interpolation coefficient (in percentage) used to blend the previous FFT sample with the current sample, if it is lesser than the previousMSVC v142 - VS 2019 C++ x64/x86 build tools (v14.25)
or laterMSVC v142 - VS 2019 C++ x64/x86 Spectre-mitigated libs (v14.25)
or laterMSVC v142 - VS 2019 C++ x64/x86 build tools (v14.25)
or laterMSVC v142 - VS 2019 C++ x64/x86 Spectre-mitigated libs (v14.25)
or laterC++ ATL for latest v142 build tools (x86 & x64)
or laterC++ ATL for latest v142 build tools with Spectre Mitigations (x86 & x64)
or latercmake-gui
, set the following variables:
DISABLE_PYTHON=TRUE
, unless you are not getting errors while trying to build with Python enabled<OBS_BUILD_DIR>
with the path to the directory where you built OBS:
set RUSTFLAGS=-L native=<OBS_BUILD_DIR>\libobs\Debug
cargo build --release
target/release/libobs_shaderfilter_plus.dll
to the OBS plugin directory.
libobs.so
resides to the LD_LIBRARY_PATH
environment variable.cargo build --release
target/release/libobs_shaderfilter_plus.so
to the OBS plugin directory.These steps should not be necessary if you just want to compile OBS ShaderFilter Plus from source.
Ensure OBS is uninstalled using:
sudo apt remove obs-studio
Compile OBS using:
cmake -DUNIX_STRUCTURE=1 -DCMAKE_INSTALL_PREFIX=/usr -DBUILD_BROWSER=ON -DCEF_ROOT_DIR="../../cef_binary_3770_linux64" ..; and make -j24; and sudo checkinstall --default --pkgname=obs-studio --fstrans=no --backup=no --pkgversion=(date +%Y%m%d)"-git" --deldoc=yes
Then recompile and install using:
make -j24; and sudo make install