Add README.md

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_<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:
+
+```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 <PROPERTY> <VALUE>
+```
+
+#### 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

examples/blit.glsl → 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);
 }

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;