librashader

Mega Bezel SMOOTH-ADV on DirectX 11

librashader (/ˈli:brəʃeɪdɚ/) is a preprocessor, compiler, and runtime for RetroArch 'slang' shaders, rewritten in pure Rust.

Installation

For end-users, librashader is available from the Open Build Service for a variety of Linux distributions and platforms. Windows and macOS users can grab the latest binaries from GitHub Releases.

Supported Render APIs

librashader supports all modern graphics runtimes, including wgpu, Vulkan, OpenGL 3.3+ and 4.6 (with DSA), Direct3D 11, Direct3D 12, and Metal.

librashader does not support legacy render APIs such as older versions of OpenGL or Direct3D, except for limited support for Direct3D 9.

✅ Full Support — 🆗 Secondary Support

Shader compatibility is not guaranteed on render APIs with secondary support. In particular, Direct3D 9 does not support shaders that need Direct3D 10+ only features, or shaders that can not be compiled to Shader Model 3.0.

Usage

librashader provides both a Rust API under the librashader crate, and a C API. Both APIs are first-class and fully supported. The C API is geared more towards integration with existing projects. The Rust librashader crate exposes more of the internals if you wish to use parts of librashader piecemeal.

The librashader C API is best used by including librashader_ld.h in your project, which implements a loader that dynamically loads the librashader (librashader.so, librashader.dll, or librashader.dylib) implementation in the search path.

C compatibility

The recommended way of integrating librashader is by the librashader_ld single header library which implements a dynamic loader for librashader.dll / librashader.so / librashader.dylib. See the versioning policy for details on how librashader handles C ABI and API stability with regards to library updates. You can also link dynamically with just librashader.h and the equivalent of -lrashader.

Linking statically against librashader.h is possible, but is not officially supported. You will need to ensure linkage parameters are correct in order to successfully link with librashader.lib or librashader.a. The corrosion CMake package is highly recommended.

Thread safety

Except for the Metal runtime, in general, it is safe to create a filter chain instance from a different thread, but drawing frames requires external synchronization of the filter chain object.

Filter chains can be created from any thread, but requires external synchronization of the graphics device queue where applicable (in Direct3D 11, the immediate context is considered the graphics device queue), as loading LUTs requires command submission to the GPU. Initialization of GPU resources may be deferred asynchronously using the filter_chain_create_deferred functions, but the caller is responsible for submitting the recorded commands to the graphics device queue, and ensuring that the work is complete before drawing shader pass frames.

OpenGL has an additional restriction where creating the filter chain instance in a different thread is safe if and only if the thread local OpenGL context is initialized to the same context as the drawing thread. Support for deferral of GPU resource initialization is not available to OpenGL.

The Metal runtime is not thread safe. However you can still defer submission of GPU resource initialization through the filter_chain_create_deferred function.

The Direct3D 9 API is not thread safe, unless D3DCREATE_MULTITHREADED is enabled at device creation.

Quad vertices and rotations

All runtimes render intermediate passes with an identity matrix MVP and a VBO for with range [-1, 1]. The final pass uses a Quad VBO with range [0, 1] and the following projection matrix by default.

static DEFAULT_MVP: &[f32; 16] = &[
  2.0, 0.0, 0.0, 0.0,
  0.0, 2.0, 0.0, 0.0,
  0.0, 0.0, 0.0, 0.0,
  -1.0, -1.0, 0.0, 1.0,
];

As with RetroArch, a rotation on this MVP will be applied only on the final pass for these runtimes. This is the only way to pass orientation information to shaders.

Writing a librashader Runtime

If you wish to contribute a runtime implementation not already available, see the librashader-runtime crate for helpers and shared logic used across all librashader runtime implementations. Using these helpers and traits will ensure that your runtime has consistent behaviour for uniform and texture semantics bindings with the existing librashader runtimes.

These types should not be exposed to the end user in the runtime's public API, and should be kept internal to the implementation of the runtime.

Command-line interface

librashader provides a command-line interface to reflect and debug 'slang' shaders and presets.

Usage: librashader-cli <COMMAND>

Commands:
  render      Render a shader preset against an image
  compare     Compare two runtimes and get a similarity score between the two runtimes rendering the same frame
  parse       Parse a preset and get a JSON representation of the data
  pack        Create a serialized preset pack from a shader preset
  preprocess  Get the raw GLSL output of a preprocessed shader
  transpile   Transpile a shader in a given preset to the given format
  reflect     Reflect the shader relative to a preset, giving information about semantics used in a slang shader
  help        Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

For more information, see CLI.md.

The CLI is also accessible through cargo xtask

$ cargo xtask cli

Building

For Rust projects, simply add the crate to your Cargo.toml.

cargo add librashader

To build the C compatible dynamic library, run the build script.

$ cargo xtask build --profile optimized

The build script can also be run directly without cargo xtask

$ cargo run -p librashader-build-script -- --profile optimized

This will output a librashader.dll or librashader.so in the target folder. Profile can be debug, release, or optimized for full LTO.

While librashader has no build-time dependencies, using librashader_ld.h may require headers from the relevant runtime graphics API.

Building against nightly Rust

As of librashader 0.11, building on the stable MSRV is the default behaviour.

To opt in to minor optimizations with impl_trait_in_assoc_type enabled by nightly and C header generation, enable the nightly feature.

librashader = { version = "0.11", features = ["nightly"] }

When building the C API with librashader-build-script, to build with nightly features on, pass the --nightly flag when using a nightly toolchain.

cargo xtask build --profile optimized --nightly

The stable feature and --stable flag remain for backwards compatibility but no longer do anything.

Using nightly to generate the C headers is no longer encouraged due to cargo expand breaking feature flags. Please use the provided librashader.h in the include folder.

Examples

The following Rust examples show how to use each librashader runtime. * Vulkan * OpenGL * Direct3D 11 * Direct3D 12 * wgpu * Direct3D 9

Some basic examples on using the C API are also provided.

• Direct3D 11
• Metal with Objective-C

Since librashader 0.11.0, a restricted subset of librashader can run on the web via WebGPU by building a minimal subset of librashader's WGPU runtime, and pre-compiling shader presets to WGSL.

• WebGPU Demo

Compatibility

librashader implements the entire RetroArch shader pipeline and is highly compatible with existing shaders.

Please report an issue if you run into a shader that works in RetroArch, but not under librashader.

• Filter chains do not terminate at the backbuffer.
• Unlike RetroArch, librashader does not have full knowledge of the entire rendering state and is designed to be pluggable at any point in your render pipeline. Instead, filter chains terminate at a caller-provided output surface and viewport. It is the caller's responsibility to blit the surface back to the backbuffer.
• Shaders are compiled in parallel where possible. This should noticeably decrease preset compile times. Parallel shader compilation is not available to OpenGL.
• For performance reasons, mipmaps are never generated for the input texture. In theory, this means that presets with mipmap_input0 = "true" will not get a mipmapped input. In practice, no known shader presets set mipmap_input0 = "true".
• The preset parser is a substantially stricter implementation that the one in RetroArch. Not all shader presets may be compatible. If you find this is the case, please file an issue so a workaround can be added.
• Shaders are pre-linked at the SPIR-V level before being passed to the driver. Unused inputs in the fragment shader are removed, and the corresponding input in the vertex shader is downgraded to a global variable.

Runtime specific differences

• OpenGL
• Copying of in-flight framebuffer contents to history is done via glBlitFramebuffer rather than drawing a quad into an intermediate FBO.
• Sampler objects are used rather than glTexParameter.
• Sampler inputs and outputs are not renamed. This is useful for debugging shaders in RenderDoc.
• UBO and Push Constant Buffer sizes are padded to 16-byte boundaries.
• The OpenGL runtime uses the same VBOs as the other runtimes as well as the identity matrix MVP for intermediate passes. RetroArch's OpenGL driver uses only the final VBO.
• OpenGL 4.6+
• All caveats from the OpenGL 3.3+ section should be considered.
• Should work on OpenGL 4.5 but this is not guaranteed. The OpenGL 4.6 runtime may eventually switch to using ARB_spirv_extensions for loading shaders, and this will not be marked as a breaking change.
• The OpenGL 4.6 runtime uses Direct State Access to minimize changes to the OpenGL state. For GPUs released within the last 5 years, this may improve performance.
• The OpenGL runtime uses the same VBOs as the other runtimes as well as the identity matrix MVP for intermediate passes. RetroArch's OpenGL driver uses only the final VBO.
• Vulkan
• The Vulkan runtime can use VK_KHR_dynamic_rendering. This extension must be enabled at device creation. Dynamic rendering may have improved performance when enabled, and supported by the host hardware.
• Allocations within the runtime are done through gpu-allocator rather than handled manually.
• Direct3D 11
• Framebuffer copies are done via ID3D11DeviceContext::CopySubresourceRegion rather than a CPU conversion + copy.
• Shader Model 4.0 to 5.1 do not support sample calls in a non-uniform loop. These are lowered to sampleLod before being passed to the DirectX Shader Compiler. These shaders would usually fail to compile in RetroArch.
• Direct3D 12
• The Direct3D 12 runtime uses [render passes](https://learn.microsoft.com/en-us/windows/