Version

A shader is a program used to compute the color of the pixels of a primitive.

See the GpuShader page for the shader API documentation.

Shader langage

Harfang uses a slightly modified GLSL syntax.

File format

A shader file is a tree of named sections of the form section_name { ...content... }.

Global sections

The following sections are declared globally (not in the scope of another section) when describing a shader:

  • in: This section is used to describe the inputs to the shader.
  • variant: This section contains a single shader variant code. There must be at least one variant declared in a shader for it to be valid.

Declaring inputs through the global in section

Inputs to the shader are declared in the global in section. These variables can be modified from script using the SetShader* group of functions of the Renderer class.

Here is an example of declaring a vec3 input value named user_value:

in {
  vec3 user_value;
}

Variables can be default initialized using the assignment operator.

in {
  vec3 user_value = vec3(0.5, 0, 0);
  tex2D u_tex = "mytex.jpg";
}

Extra type configuration

Depending on the variable type, additional parameters might be available and optionally specified.

Type Parameter Values Default Description
tex2D, tex3D, texCube wrap-u repeat, clamp clamp UV wrapping on the U (horizontal) axis.
wrap-v repeat, clamp clamp UV wrapping on the V (vertical) axis.
wrap repeat, clamp clamp UV wrapping on both texture axis.
filter nearest, linear, trilinear, anisotropic linear Texture filtering when minified or magnified.
min-filter nearest, linear, trilinear, anisotropic linear Texture filtering when minified.
mag-filter nearest, linear, trilinear, anisotropic linear Texture filtering when magnified.

Example of declaring a texture input with wrapping set to repeat on the U axis and clamp on the V axis.

in {
  tex2D u_tex [wrap-u: repeat, wrap-v: clamp];
}

Customizing a type UI

An extra hint parameter is available to specialize the control used to edit a paremeter in the editor, depending on the type it can take the following values:

Type Values Description
vec4 color Hint that a vec4 value is used as a color by the shader.

Example to declare that a vec4 input may be displayed and edited as a color.

in {
  vec4 diffuse [hint: color];
}

The variant section

This section holds the code to a shader. As its name implies it can be tagged so that different variant may be used depending on the running platform or other filtering criterias.

A shader must declare at least one variant. A variant that does not specify any tag is the shader default variant.

The variant section contains a sub-section for each stage of the rendering pipeline (vertex, pixel). Each of these section describes the shader for the stage it corresponds to.

All stage sections follow the same structure.

Sub-section Description
source The shader code for this stage. This block of code may not contain any function declaration.
global The shader global source for the stage. This is a good place for function declaration.
out Outputs from the shader stage. Variables declared in this section will implicitely appear in the next stage in section. The variable value is usually interpolated from one stage to the next by the graphic hardware.

Note: In the final generated shader the global section content appears before the source section content.

Shader output

A shader must at least provide a color for each fragment it processes. This is done by writing to the %out.color% variable. The fragment depth can optionally be modified by writing to the %out.depth% variable.

Note: When drawing with a shader outputting alpha values remember to enable alpha blending, see EnableBlending and SetBlendFunc.

Symbol Type Description
%out.color% vec4 Fragment color with alpha
%out.depth% float Fragment depth value

Accessing engine state from a shader

A shader can read many parts of the current engine state by using the variables listed here.

Primitive attributes

The following variables are available to access the attributes of the primitive being drawn.

Symbol Type Description
vPosition vec3 Position
vNormal vec3 Normal
vUV0 vec2 UV coordinates channel 0
vUV1 vec2 UV coordinates channel 1
vUV2 vec2 UV coordinates channel 2
vUV3 vec2 UV coordinates channel 3
vColor0 vec4 Color channel 0
vColor1 vec4 Color channel 1
vColor2 vec4 Color channel 2
vColor3 vec4 Color channel 3
vTangent vec3 Tangent
vBitangent vec3 Bitangent
vBoneIndex vec4 Bone indices as vec4 (4 indices)
vBoneWeight vec4 Bone weights as vec4 (4 weights)

Engine state

The following variables are available to access the current engine state.

Warning: When using the Renderer API make sure to call SetShaderEngineValues before calling any draw function so that the engine state variables values for the shader are set. The RenderSystem drawing functions perform this call automatically.

Symbol Type Description
vClock float Frame clock (in seconds)
vViewVector vec3 View front vector in world space
vViewPosition vec4 View position in world space
vViewport vec4 vec4(x, y, width, height) (in pixels)
vViewState vec3 vec3(near, far, eye)
vTechniqueIsForward int 1 if the current render technique is forward, 0 otherwise
vFxScale float
vInverseInternalResolution vec4 vec4(inv. width, inv. height, ratio x, ratio y)
vInverseViewportSize vec4 vec4(inv.width, inv.height, ratio x, ratio y)
vAmbientColor vec3
vFogColor vec3
vFogState vec3 vec3(near, far, inverse range)
vDepthBuffer tex2D
vFrameBuffer tex2D
vGBuffer0 tex2D
vGBuffer1 tex2D
vGBuffer2 tex2D
vGBuffer3 tex2D
vNormalMatrix mat3 Model to world matrix (rotation only)
vNormalViewMatrix mat3 Model to view matrix (rotation only)
vModelMatrix mat4 Model to world matrix
vInverseModelMatrix mat4 World to model matrix
vViewMatrix mat4 World to view matrix
vInverseViewMatrix mat4 View to world matrix
vProjectionMatrix mat4 View projection matrix
vModelViewMatrix mat4 Model to view matrix
vModelViewProjectionMatrix mat4 Model to view matrix with projection
vPreviousModelViewMatrix mat4 Previous model to view matrix
vPreviousModelViewProjectionMatrix mat4 Previous model to view matrix with projection
vLightState vec4 vec4(range, spot inner angle, spot outer angle, shadow bias)
vLightDiffuseColor vec3
vLightSpecularColor vec3
vLightShadowColor vec3
vLightViewPosition vec3
vLightViewDirection vec3
vLightShadowMatrix0 mat4
vLightShadowMatrix1 mat4
vLightShadowMatrix2 mat4
vLightShadowMatrix3 mat4
vLightShadowMatrix4 mat4
vLightShadowMatrix5 mat4
vInverseShadowMapSize float
vLightShadowMap0 tex2D
vLightShadowMap1 tex2D
vLightShadowMap2 tex2D
vLightShadowMap3 tex2D
vLightShadowMap4 tex2D
vLightShadowMap5 tex2D
vLightPSSMSliceDistance vec4 vec4(slice 0, slice 1, slice 2, slice 3)
vViewToLightMatrix mat4 View to light matrix
vLightProjectionMap tex2D Light projection matrix
vBoneMatrix mat4 Model to world matrix (with bone influence)
vPreviousBoneMatrix mat4 Previous model to world matrix (with bone influence)
vNodeId vec4 Current node uid

Examples

A simple texture+Gouraud shader.

// texture_gouraud.isl
in { tex2D u_tex; }

variant {
  vertex {
    out {
      vec2 v_uv;
      vec4 v_color;
    }

    source %{
      // read from the UV channel 0 and send to the pixel shader
      v_uv = vUV0;
      // read from the color channel 0 and send to the pixel shader
      v_color = vColor0;
      // transform the vertex position by the model view projection matrix
      %out.position% = _mtx_mul(vModelViewProjectionMatrix, vec4(vPosition, 1.0));
    %}
  }

  pixel {
    source %{
      // sample the texture and multiply with the interpolated vertex color
      %out.color% = texture2D(u_tex, v_uv) * v_color;
    %}
  }
}