Technical Overview

How does it work?

FShade makes use of F#'s quotations (see Code Quotations) for translating the source-code to target languages like GLSL.

These quotations can be obtained by either applying the ReflectedDefinition attribute to functions/modules or by defining computation expression builders having a member Quote : unit -> unit. Since we wanted shaders to be first-class we opted for the latter and defined computation expression builders for the various available shader-stages.

Let's look at a simple vertex shader example.

 1: 
 2: 
 3: 
 4: 
 5: 
 6: 
 7: 
 8: 
 9: 
10: 
11: 
12: 

type Vertex =
    {
        [<Semantic("pos")>]
        p : V4d
    }

let scaleShader (v : Vertex) =
    vertex {
        return {
            p = V4d(3.0 * v.p.XYZ, 1.0)
        }
    }

The above shader simply scales the per-vertex-value p by a factor 3 and returns it.

The record field p here is annotated with Semantic("pos") which will be used as input-name in the resulting low-level code and guides compositions (more on that below).

To obtain a compilable Effect from the shader-function we use a somewhat magical combinator.

1: 

let scaleEffect = Effect.ofFunction scaleShader

Under the hood ofFunction actually invokes the given function using Unchecked.defaultof<_> as argument value which ensures that per-vertex values are not accessed by shaders at compile-time. The transformation will raise an exception stating shader functions may not access their vertex-input statically when trying to do so.

The resulting Effect represents an assignment of shaders to the available stages. This encoding is similar to DirectX's Effects where each Effect may contain any subset of shader-stages.

The effect from above can then be compiled to a Module which in turn can be compiled to GLSL like this:

1: 
2: 
3: 
4: 
5: 
6: 
7: 
8: 

scaleEffect
    |> Effect.toModule { 
        EffectConfig.empty with 
            lastStage = ShaderStage.Vertex
            outputs = Map.ofList ["pos", (typeof<V4d>, 2) ] 
        }
    |> ModuleCompiler.compileGLSL410
    |> printfn "%s"

The EffectConfig states that we're interested only in the vertex shader (lastStage) and that we'd like the result to include the output annotated with Semantic("pos") as 4 dimensional vector (V4d) which should be bound to output-location 2.

Here we use FShade's standard GLSL410 compiler to generate the final code:

#version 410

#ifdef Vertex
layout(location = 0) in vec4 pos;
layout(location = 2) out vec4 posOut;
void main()
{
    posOut = vec4((3.0 * pos.xyz), 1.0);
}

#endif

Compositions

FShade currently provides 5 shader stages that can be used in effects.

1: 
2: 
3: 
4: 
5: 
6: 

type ShaderStage = 
    | Vertex  = 0
    | TessControl = 1
    | TessEval = 2
    | Geometry = 3 
    | Fragment = 4

Just like in standard shader languages a shader can be composed with another shader for a later stage. Therefore effects can obviously be composed whenever maxStage(left) < minStage(right).

However FShade also provides composition for other scenarios. Consider the following effects:

 1: 
 2: 
 3: 
 4: 
 5: 
 6: 
 7: 
 8: 
 9: 
10: 
11: 
12: 
13: 
14: 
15: 
16: 
17: 
18: 
19: 
20: 
21: 
22: 
23: 
24: 
25: 
26: 
27: 

module Transformation = 
    type Vertex =
        {
            // [<Position>] is a shorthand for [<Semantic("Positions")>]
            [<Position>]                pos : V4d 
            [<Semantic("Normal")>]      normal : V3d
        }

    let shader (v : Vertex) =
        vertex {
            return {
                pos = 3.0 * v.pos
                normal = 4.0 * v.normal
            }
        }
  
module Coloring =
    type Vertex =
        {
            [<Semantic("Normal")>]      n       : V3d
            [<Semantic("Color")>]       color   : V4d
        }  

    let shader (v : Vertex) =
        vertex {
            return { v with color = V4d(v.n.X, v.n.Y, v.n.Z, 1.0) }
        }

These two (admittedly strage) effects are concerned with different aspects of a vertex but both make use of the vertex's Normal.

FShade's composition allows us to compose both effects sequentially using:

1: 
2: 
3: 
4: 
5: 

let composed1 =
    Effect.compose [
        Effect.ofFunction Transformation.shader
        Effect.ofFunction Coloring.shader 
    ]

which gives us the following GLSL code:

#version 410

#ifdef Vertex
layout(location = 0) in vec3 Normal;
layout(location = 1) in vec4 Positions;
layout(location = 0) out vec4 ColorOut;
layout(location = 1) out vec3 NormalOut;
layout(location = 2) out vec4 PositionsOut;
void main()
{
    vec3 NormalC = (4.0 * Normal);
    ColorOut = vec4(NormalC.x, NormalC.y, NormalC.z, 1.0);
    NormalOut = NormalC;
    PositionsOut = (3.0 * Positions);
}

#endif

Note that Coloring here uses the normal from Transformation

When composed the other way round:

1: 
2: 
3: 
4: 
5: 

let composed2 =
    Effect.compose [
        Effect.ofFunction Coloring.shader 
        Effect.ofFunction Transformation.shader
    ]

the resulting code looks like:

#version 410

#ifdef Vertex
layout(location = 0) in vec3 Normal;
layout(location = 1) in vec4 Positions;
layout(location = 0) out vec4 ColorOut;
layout(location = 1) out vec3 NormalOut;
layout(location = 2) out vec4 PositionsOut;
void main()
{
    ColorOut = vec4(Normal.x, Normal.y, Normal.z, 1.0);
    NormalOut = (4.0 * Normal);
    PositionsOut = (3.0 * Positions);
}

#endif

From a high-level point of view compose [a; b] is similar to F#'s a >> b since it pipes the outputs of a into b.

However compose works on n-ary functions taking an arbitrary number of inputs and producing an arbitrary number of outputs. Matching values are identified using the Semantic annotations defined in the types.

Currently only compositions for a subset of shader combinations are implemented.

• compose [Vertex; Vertex] -> Vertex
• compose [Geometry; Geometry] -> Geometry
• compose [Geometry; Vertex] -> Geometry
• compose [Fragment; Fragment] -> Fragment
• compose [a; b] when a < b -> Effect [a;b]

However these seem sufficient in all cases we encountered so far ;)

Linking

As you may have noticed in the above composed effects tend to have a lot of outputs which may (partly) not be needed for rendering.

Therefore FShade provides functions for removing unused outputs and adding unspecified outputs by passing them along.

A little example:

 1: 
 2: 
 3: 
 4: 
 5: 
 6: 
 7: 
 8: 
 9: 
10: 
11: 
12: 
13: 
14: 
15: 
16: 
17: 
18: 
19: 
20: 

module Example = 
    type Vertex =
        {
            [<Semantic("Normal")>] n : V3d
        }

    type Fragment =
        {
            [<Color>] c : V4d
            [<Semantic("Normal")>] n : V3d
        }

    let normalColor (v : Vertex) =
        fragment {
            let n = v.n
            return {
                c = V4d(n.X, n.Y, n.Z, 1.0)
                n = n
            }
        }

Here our fragment shader needs an input Normal and returns Colors and Normal.

In our config we declare only Colors to be used and bind it to location 0.

1: 
2: 
3: 
4: 
5: 
6: 
7: 
8: 
9: 

Example.normalColor
    |> Effect.ofFunction
    |> Effect.toModule {
        EffectConfig.empty with
            lastStage = ShaderStage.Fragment
            outputs = Map.ofList ["Colors", (typeof<V4d>, 0)]
       }
    |> ModuleCompiler.compileGLSL410
    |> printfn "%s"

The compiler now automatically removes the output Normal from the effect and creates a vertex shader passing the remaining inputs along. Since fragment shaders always implicitly require a position the vertex shader will finally pass Positions and Normal.

We refer to this process as linking since it links all shaders together creating a tight set of in-/outputs.

#version 410

#ifdef Vertex
layout(location = 0) in vec3 Normal;
layout(location = 1) in vec4 Positions;
layout(location = 0) out vec3 fs_Normal;
void main()
{
    fs_Normal = Normal;
    gl_Position = Positions;
}

#endif

#ifdef Fragment
layout(location = 0) in vec3 fs_Normal;
layout(location = 0) out vec4 ColorsOut;
void main()
{
    ColorsOut = vec4(fs_Normal.x, fs_Normal.y, fs_Normal.z, 1.0);
}

#endif

Note that passing along inputs is simple for vertex/fragment shaders but can be rather complicated for other stages.

When passing values through a GeometryShader FShade looks for an output annotated with [<SourceVertexIndex>] and uses its value to determine the corresponding input vertex for the output vertex in question. For Point inputs the SourceVertexIndex is always 0.

FShade can also pass values through tessellation shaders as long as they can be interpolated linearly. (e.g. are floating point values)

Uniforms

FShade uses F#'s (?) operator for accessing uniforms on the global value uniform.

1: 
2: 
3: 
4: 
5: 

let trafoShader1 (v : Vertex) =
    vertex {
        let mvp : M44d = uniform?MyUniformBuffer?MVPMatrix
        return { v with p = mvp * v.p }
    }

this shader accesses the uniform named MVPMatrix which will be part of a uniform buffer MyUniformBuffer having type M44d.

Since the return type for (?) is generic the value mvp needs a type annotation. To avoid these annotations one may simply define extension properties for uniforms like:

1: 
2: 
3: 
4: 
5: 
6: 
7: 

type UniformScope with
    member x.MVPMatrix : M44d = uniform?MyUniformBuffer?MVPMatrix

let trafoShader2 (v : Vertex) =
    vertex {
        return { v with p = uniform.MVPMatrix * v.p }
    }

Note that FShade does not contain any typed uniform-accessors like that but rendering frameworks may define their available uniform values like that.

• FShade
• Home page
• Get Library via NuGet
• Source Code on GitHub
• Documentation
• Technical Overview
• Composition
• Types
• Tessellation Shaders
• Compute Shaders