- Qt 3D Studio
- File Formats
- Effect Reference
- Qt 3D Studio 2.8 Manual

# Effect Reference

This page explains how to write effects.

## Overview

The effects specification allows writing custom effects, which are applied to layers. The effects can have multiple passes to calculate the final result. Each shader in a pass must implement the `void frag()` and `void vert()` functions for fragment and vertex shader respectively. The passes are executed in the order they are specified in the effect file. The studio shader library can also be accessed with `#include` directive to add functionality.

Note: Unlike custom materials, effects have full support for multiple render passes in the Qt 3D Studio 2.0 runtime.

## Effect Structure

     <Effect>
         <MetaData>
             <Property name="FloatParam" type="Float" formalName="Float Param" description="" default="1.0"/>
             <Property name="TextureParam" type="Texture" filter="linear" clamp="clamp"/>
             <Property name="DepthTextureParam" type="Texture" filter="nearest" clamp="clamp"/>
         </MetaData>
         <Shaders>
             <Shared></Shared>
             <VertexShaderShared></VertexShaderShared>
             <FragmentShaderShared></FragmentShaderShared>
             <Shader name="PASS1">
                 <VertexShader></VertexShader>
                 <FragmentShader></FragmentShader>
             </Shader>
             <Shader name="PASS2">
                 <VertexShader></VertexShader>
                 <FragmentShader></FragmentShader>
             </Shader>
             <Shader name="MAIN">

                 <VertexShader>
     void vert()
     {
     }
                 </VertexShader>
                 <FragmentShader>
     void frag()
     {
     }
                 </FragmentShader>
             </Shader>
         </Shaders>
         <Passes>
             <Buffer name="buffer" type="fp16" format="rg" filter="nearest" wrap="clamp" size="1.0" lifetime="frame"/>
             <Buffer name="buffer2" type="fp16" format="rg" filter="nearest" wrap="clamp" size="1.0" lifetime="frame"/>
             <Buffer name="stencilBuffer" format='depth24stencil8' lifetime="frame" />

             <Pass shader="PASS1" input="[source]" output="buffer">
                 <DepthInput param="DepthTextureParam"/>
                 <DepthStencil buffer='stencilBuffer' flags='clear-stencil' stencil-fail='replace' depth-fail='replace' depth-pass='replace' stencil-function='always' reference='1'/>
             </Pass>

             <Pass shader="PASS2" input="buffer" output="buffer2">
                 <BufferInput param="buffer" param="TextureParam" />
             </Pass>
             <Pass shader="MAIN" input="[source]" output="[dest]">
                 <Blending source="SrcAlpha" dest="One"/>
                 <SetParam name="FloatParam" value="0.0"/>
             </Pass>
         </Passes>
     </Effect>

The effect file structure follows the same pattern as custom materials, first is the metadata with parameters in `<Metadata>` element, then effect shaders in `<Shaders>` element and render passes in `<Passes>` element.

## Parameters

Effect metadata parameters are the same as for custom materials, but also have a couple of effect-specific parameters. Parameters with `Texture` type and the `<Buffer>` and `<BufferInput>` elements allow using sampler-variables in shader.

Note: The Qt 3D Studio 2.0 runtime does not support other types of buffers (shader storage buffers, indirect drawing, etc.). A temporary buffer specified via the `<Buffer>` element maps to a texture. This can be bound to a sampler variable in the shader via `<BufferInput>` in the individual passes.

## Elements

### <Shared>

This element can be used to insert block of shader code that is shared among all shaders. It gets inserted to all shaders in the effect.

### <VertexShaderShared> and <FragmentShaderShared>

These elements can be used to insert block of shader code that is shared among all vertex and fragments shaders. The code inside `<VertexShaderShared>` element gets inserted to all vertex shaders and similarly code inside `<FragmentShaderShared>` element gets inserted to all fragment shaders.

### <Shader>, <VertexShader> and <FragmentShader>

The `<Shader>` element specifies a shader with shader name specified with name attribute. The name is used inside `<Pass>` element to specify which shader to execute. `<VertexShader>` and `<FragmentShader>` elements are used to specify vertex shader code and fragment shader code respectively. The vertex shader must implement the `void vert()` function and fragment shader must implement the `void frag()` function, unless left empty.

The shader can use the `varying`, `in` and `out` specifiers to define custom variables to pass parameters between shader stages.

### <Passes>

The `<Passes>` element is used to specify render passes for the effect. Each render pass must be specified inside `<Pass>` element. The `<Passes>` element can also contain `<Buffer>` elements to specify different kinds of data storages for the effect.

Note: In the Qt 3D Studio 2.0 runtime a buffer always maps to a texture.

### <Buffer>

This element can be used to create a buffer to be used inside the effect. Different passes can read and write to these buffers while implementing different stages of the effect. The `<BufferInput>` element can be used to bind the buffer to shader variable so that it can be read in shader.

The element attributes are:

attribute | values | description
--- | --- | ---
name | `string` | Used to specify unique name for the buffer.
type |

- `ubyte` - 8-bit unsigned integer
- `ushort` - 16-bit unsigned integer
- `fp16` - 16-bit floating point number
- `fp32` - 32-bit floating point number

Used to specify the type of the buffer.
format |

- `source` - take format from the source
- `depth24stencil8` - combined depth24 stencil 8
- `alpha` - alpha
- `lum` - luminance
- `lum_alpha` - luminance alpha
- `rg` - 2-component RG
- `rgb` - 3-component RGB
- `rgba` - 4-component RGBA

Used to specify the format of the buffer.
filter |

- `nearest` - nearest neighbor
- `linear` - linear interpolation

Used to specify the input filtering mode.
wrap |

- `clamp` - clamp to edges
- `repeat` - repeat values

Used to specify the wrapping mode of the texture coordinates.
size | `float` | Used to specify the size of the buffer relative to the frame buffer. 1.0 corresponds to same size. 0.5 corresponds to the buffer width and height being half the size.
lifetime |

- `scene` - The buffer is allocated at the beginning of the scene
- `frame` - The buffer is allocated at the beginning of the frame

Used to specify how the buffer is allocated and deleted. Buffers with `frame` lifetime can be reused by other effects.

### <Pass>

This element specifies one render pass in effect. The passes are executed in the order they are specified in the effect file.

The element attributes are:

attribute | values | description
--- | --- | ---
shader | string | The name of the shader executed in this pass. Must match to a shader name in the `<Shaders>` element.
input | string | The name of one of the `<Buffer>` elements or [source].
output | string | The name of one of the `<Buffer>` elements or [dest].
format |

- `alpha` - alpha
- `lum` - luminance
- `lum_alpha` - luminance alpha
- `rg` - 2-component RG
- `rgb` - 3-component RGB
- `rgba` - 4-component RGBA

If output is [dest], specifies the output format.

### <BufferInput>

This element binds a buffer (texture) to one of the shader sampler variables.

The element attributes are:

attribute | values | description
--- | --- | ---
value | string | The name of one of the `<Buffer>` elements or [source].
param | string | The name of the shader variable.

### <DepthInput>

This element binds frame buffer depth as a texture to shader sampler variable.

The element attributes are:

attribute | values | description
--- | --- | ---
param | string | The name of the shader variable.

### <SetParam>

This element can be used to set render pass specific shader parameters. The parameter must match to a parameter specified in the `<Metadata>` element.

The element attributes are:

attribute | values | description
--- | --- | ---
name | string | The name of the property.
value | float or integer | Specifies the value of the property.

### <Blending>

This element can be used to change the blending of the a render pass.

The element attributes are:

attribute | values | description
--- | --- | ---
dest |

- `SrcAlpha`
- `OneMinusSrcAlpha`
- `One`

Specifies the destination blending mode.
source |

- `SrcAlpha`
- `OneMinusSrcAlpha`
- `One`

Specifies the source blending mode.

### <RenderState>

This element can be used to enable/disable a render state for a pass.

The element attributes are:

attribute | values | description
--- | --- | ---
name |

- `Stencil`
- `CullFace`

Name of the render state
value | boolean | Specifies whether to enable or disable the render state.

### <DepthStencil>

This element can be used to specify depth-stencil buffer and change the depth-stencil test for a render pass.

The element attributes are:

attribute | values | description
--- | --- | ---
buffer | string | Name of the buffer used as a depth-stencil buffer.
flags |

- `clear-stencil` - Clear stencil buffer
- `clear-depth` - Clear depth buffer

Specifies flags for the element. These can be combined with logical or('|').
stencil-fail | One of the stencil operation values | Specifies stencil fail operation.
depth-fail | One of the stencil operation values | Specifies depth fail operation.
depth-pass | One of the stencil operation values | Specifies depth pass operation.
stencil-function | One of the boolean operator values | Specifies stencil function.
reference | integer | Specifies stencil reference value.
mask | integer | Specifies stencil mask value.

The stencil operation values are:

- `keep`
- `zero`
- `replace`
- `increment`
- `increment-wrap`
- `decrement`
- `decrement-wrap`
- `invert`

The boolean operator values are:

- `never`
- `less`
- `less-than-or-equal`
- `equal`
- `not-equal`
- `greater`
- `greater-than-or-equal`
- `always`

### <Culling>

This element can be used to select which faces are culled by CullFace.

The element attributes are:

attribute | values | description
--- | --- | ---
mode |

- `Back` - Back faces.
- `Front` - Front faces.
- `All` - All faces.

Specifies CullFace mode.