Shaders

A Shader represents the program sent to the GPU to render each pixel on the surface of our geometry. It can be instantiated with a base geometry and must be provided with a shader written with our custom shading language.

A simple shader might look something like this:

static SHADER: Shader = Shader {
    build_geom: Some(build_geom),
    code_to_concatenate: &[
        Cx::STD_SHADER,
        code_fragment!(
            r#"
            geometry geom: vec2;
            instance color: vec4;

            fn vertex() -> vec4 {
                return vec4(geom.x, geom.y, 0., 1.);
            }

            fn pixel() -> vec4 {
                return color;
            }
            "#
        ),
    ],
    ..Shader::DEFAULT
};

Shaders are statically defined, and consist of two fields:

• build_geom: a function that produces a Geometry. Can be omitted if you want to dynamically assign a geometry at draw time.
• code_to_concatenate: an array of CodeFragments, that get concatenated in order. Define each fragment using the code_fragment!() macro (this keeps track of filenames and line numbers, for better error messages).

Passing in data

A shader typically starts with a bunch of variable declarations. These declarations define the data that you pass into the shader, and has to exactly match the data types in Rust.

For example, to pass in instance data, you can define some instance variables in the shader:

r#"
instance pos: vec2;
instance color: vec4;
"#

Which has to exactly match the corresponding "instance struct":

#[repr(C)]
struct MyShaderIns {
    pos: Vec2,
    color: Vec4,
}

Note the use of #[repr(C)] to ensure that the data is properly laid out in memory.

When calling cx.add_instances(&SHADER, &[MyShaderIns { pos, color }]), we verify that the memory size of MyShaderIns matches that of the instance variables in the shader code.

This is how Rust types match with shader types:

Note that within a function there are more types you can use.

These are the types of variables you can declare:

• geometry: these have to match exactly the vertex_attributes fields in Geometry::new.
• instance: these have to match exactly the data fields in Cx::add_instances.
• uniform: these have to match exactly the uniforms fields in Area::write_user_uniforms.
• texture: can only be of type texture2D and gets set using Cx::write_user_uniforms.
• varying: doesn't get passed in from Rust, but can be used to pass data from fn vertex() to fn pixel().

Shader language

The shader language itself is modeled after Rust itself. You can use things like fn, struct, and so on. Two functions need to be defined for a shader to work:

• fn vertex() defines the vertex shader. This gets called for each vertex returned from build_geom. It returns vec4(x, y, z, w) where the values mean the following:
  • x, y — coordinates on the screen (from -1 to 1).
  • z — draw order (from 0 to 1). Draws with higher z will be on top.
  • w — normalization parameter. In 2d rendering this is simply set to 1.0.
• fn pixel() defines the pixel shader. It returns a color as vec4(r, g, b, a).

See Tutorial: Rendering 2D Shapes for more about the basics of drawing in a shader.

if errored > 0. {
    df.fill(error_color);
} else if loaded > 0. {
    df.fill(active_color);
} else {
    df.fill(inactive_color);
}

return #ff0000;
return #f00;
return #f;

fn pixel() -> vec4 {
    return #f00;
}

struct Df {
    pos: vec2,
    result: vec4,
}

impl Df {
    fn clear(inout self, color: vec4) {
        self.write_color(color, 1.0);
    }
}

for i from 0 to 20 step 3 {
    if float(i) >= depth {
        break;
    }
}

The following built-in functions are available: abs, acos, acos, all, any, asin, atan, ceil, clamp, cos, cross, degrees, dFdx, dFdy, distance, dot, equal, exp, exp2, faceforward, floor, fract, greaterThan, greaterThanEqual, inversesqrt, inverse, length, lessThan, lessThanEqual, log, log2, matrixCompMult, max, min, mix, mod, normalize, not, notEqual, pow, radians, reflect, refract, sample2d, sign, sin, smoothstep, sqrt, step, tan, transpose.

Swizzling is also supported, for both xyzw and rgba. So you can do things like let plane: vec2 = point.xy or let opaque: vec3 = color.rgba.

STD_SHADER

Zaplib provides STD_SHADER, a collection of common functions that are useful when writing shaders. For a complete run down on the available functions, it's best to directly look at the source, but we'll discuss some highlights.

3D space transforms

These values are useful when working in 3D space, translating an object's scene coordinates into pixel locations on the screen.

As a quick example, a basic vertex shader to convert from object to screen coordinates is:

fn vertex() -> vec4 {
    return camera_projection * camera_view * vec4(geom_position, 1.);
}

These values get set by a combination of Pass::set_matrix_mode and the actual computed dimensions of a Pass. See e.g. the Viewport3D component.

Rendering helpers

Math

Colors

Useful constants

Distance fields

Zaplib contains many functions for Signed Distance Fields (SDFs) under the Df namespace. SDFs are a comprehensive way to define flexible shapes on the GPU. While applicable in 2D and 3D contexts, Zaplib uses this only for 2D rendering.

To create a distance field, use either:

The following methods are available on the instantiated Df struct.