diff --git a/README.md b/README.md index 80ebf5a..e8ff1a8 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,133 @@ -# Building +# OBS ShaderFilter Plus +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. +Add a filter to a source by right-clicking a source, going to `Filters`, and adding `ShaderFilter Plus`. +Shaders are run executed in OpenGL (GLSL shaders) or DirectX (HLSL shaders), +depending on your platform. +OBS on Windows usually uses DirectX, but can be compiled with OpenGL support. +OBS on Linux uses OpenGL. + +When OBS is compiled with OpenGL support, it performs primitive translation of HLSL sources to GLSL. +Therefore, if you would like your shaders to run with both graphics APIs, you should write your sources in HLSL. +However, if you only care about using them on Linux, for example, GLSL is fine. + +## Usage Guide +The structure of a shader is simple. All, that is required, is the following `render` function. + +```hlsl +float4 render(float2 uv) { + // sample the source texture and return its color to be displayed + return image.Sample(builtin_texture_sampler, uv); +} +``` + +### Builtin Variables +Every shader loaded by this plugin has access to the following uniform variables. + +```hlsl +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 int2 builtin_uv_size; // the source dimensions + +sampler_state builtin_texture_sampler { ... }; // a texture sampler with linear filtering +``` + +#### On-Request Builtin Variables +These uniform variables will be assigned data by the plugin. +If they are not defined, they do not use up processing resources. + +```hlsl +uniform texture2d builtin_texture_fft_; // audio output frequency spectrum +uniform texture2d builtin_texture_fft__previous; // output from the previous frame (requires builtin_texture_fft_ to be defined) +``` + +Builtin FFT variables have specific properties. See the the section below on properties. + +Example: + +```hlsl +#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. + +#### Custom Variables +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 variable +* `int`: A signed 32-bit integer variable +* `float`: A single precision floating point variable +* `float4`/`vec4`: A color variable, shown as a color picker in the UI + +Example: + +```hlsl +#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. + +### Defining Properties in the Source Code +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 +``` + +#### Universal Properties +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. + +#### Integer Properties +* `min` (integer): The minimum allowed value +* `max` (integer): The maximum allowed value +* `step` (integer): The stride when changing the value +* `slider` (true/false): Whether to display a slider or not + +#### Float Properties +* `min` (float): The minimum allowed value +* `max` (float): The maximum allowed value +* `step` (float): The stride when changing the value +* `slider` (true/false): Whether to display a slider or not + +#### FFT Properties +* `mix`: 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 previous +* `dampening_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 previous + + + +## Planned Features +* Access to raw audio signal, without FFT +* Specifying textures by a path to an image file + +## Development +### Building +1. Install Rust (the package manager Cargo should be bundled with it) +2. Clone this repository and open it in the terminal +3. Compile using `cargo build --release` +4. Move `target/release/libobs_shaderfilter_plus.so` or `target/release/libobs_shaderfilter_plus.dll` to the OBS plugin directory. + +### Tips on building OBS (fish shell, Ubuntu) +These steps should not be necessary if you just want to compile OBS ShaderFilter Plus from source. -# Development Ensure OBS is uninstalled using: ```fish sudo apt remove obs-studio diff --git a/examples/blit.glsl b/examples/blit.hlsl similarity index 75% rename from examples/blit.glsl rename to examples/blit.hlsl index 9bb4990..e787967 100644 --- a/examples/blit.glsl +++ b/examples/blit.hlsl @@ -1,4 +1,4 @@ // A minimal shader example. -vec4 render(vec2 uv) { +float4 render(float2 uv) { return image.Sample(builtin_texture_sampler, uv); } diff --git a/src/effect_template.effect b/src/effect_template.effect index 46e6c07..8750e2e 100644 --- a/src/effect_template.effect +++ b/src/effect_template.effect @@ -1,11 +1,11 @@ uniform float4x4 ViewProj; uniform texture2d image; -uniform int builtin_frame; -uniform float builtin_framerate; -uniform float builtin_elapsed_time; -uniform float builtin_elapsed_time_previous; -uniform int2 builtin_uv_size; +uniform int builtin_frame; +uniform float builtin_framerate; +uniform float builtin_elapsed_time; +uniform float builtin_elapsed_time_previous; +uniform int2 builtin_uv_size; sampler_state builtin_texture_sampler { Filter = Linear;