#shader #graphics #gfx #gamedev #state #graphics-pipeline #debug-mode

gfx_shader_watch

GFX Utility for watching shaders and reloading pipeline state on the fly

13 releases

new 0.6.3 Nov 1, 2024
0.6.2 May 19, 2023
0.6.1 Sep 8, 2022
0.6.0 Feb 12, 2019
0.3.3 Jul 13, 2017

#393 in Graphics APIs

Apache-2.0

26KB
310 lines

gfx_shader_watch crates.io Documentation

Tool for gfx-rs providing a PsoCell container that:

  • (Debug mode) Watches for shader file changes and reloads automatically
  • (Release mode) Includes shader file bytes at compile time

Watching and auto-loading shader file changes allows faster development of shader code without full program restarts or re-compiles. However, when releasing a final binary it is more convenient to simply include the shader code in source. Naturally this library can automatically act the desired way.

How It Works

There are two PsoCell variants SimplePsoCell & WatcherPsoCell, the former simply builds it's PipelineState once and provides access. The latter refers to a shader source file that it will monitor, when changed it will reload it's PipelineState on next access. To facilitate using SimplePsoCell in release mode, and WatcherPsoCell in debug mode the debug_watcher_pso_cell! & debug_watcher_pso_cell_type! macros are available.

Code example:

#[macro_use] extern crate gfx;
#[macro_use] extern crate gfx_shader_watch;

use gfx_shader_watch::*;
use gfx::Primitive;
use gfx::state::Rasterizer;

pub fn main() {
    // {code to setup window / gfx factory etc }

    // Container has SimplePsoCell or WatcherPsoCell type, depending on compile mode
    // if you need to refer to the type, use the `debug_watcher_pso_cell_type!` macro
    let mut pso_cell = debug_watcher_pso_cell!(
        pipe = mypipeline,
        vertex_shader = "shader/vert.glsl",
        fragment_shader = "shader/frag.glsl",
        factory = factory,
        primitive = Primitive::TriangleList,
        raterizer = Rasterizer::new_fill()).expect("psocell");

    let mut running = true;
    while running {
        // ...
        encoder.draw(&slice, pso_cell.pso(), &data);
        // ...
    }
}

Examples

Try running cargo run --example watch-shaders you should see a white triangle. Now open examples/shader/frag.glsl and modify it (ie change gl_FragColor = white; -> gl_FragColor = red;). You'll see the triangle shaded with the new code without the program reloading.

Minimum supported rust compiler

This crate is maintained with latest stable rust.

Dependencies

~0.8–7.5MB
~58K SLoC