CustomMaterial QML Type

The following functions can be implemented in a vertex shader snippet:

• void MAIN() When present, this function is called in order to set the value of POSITION, the vec4 output from the vertex shader, and, optionally, to modify the values of VERTEX, COLOR, NORMAL, UV0, UV1, TANGENT, BINORMAL, JOINTS, and WEIGHTS. Unlike in unshaded materials, writing to these makes sense because the modified values are then taken into account in the rest of the generated shader code (whereas for unshaded materials there is no additional shader code generated). For example, if the custom vertex shader displaces the vertices or the normals, it will want to store the modified values to VERTEX or NORMAL, to achieve correct lighting calculations afterwards. Additionally, the function can write to variables defined with VARYING in order to pass interpolated data to the fragment shader. When this function or a redefinition of POSITION is not present, POSITION is calculated based on VERTEX and MODELVIEWPROJECTION_MATRIX, just like a PrincipledMaterial would do.

  Example, with relying both on QML properties exposed as uniforms, and also passing data to the fragment shader:

   

  Sélectionnez

  VARYING vec3 vNormal;
  VARYING vec3 vViewVec;
  
  void MAIN()
  {
      VERTEX.x += sin(uTime * 4.0 + VERTEX.y) * uAmplitude;
      vNormal = normalize(NORMAL_MATRIX * NORMAL);
      vViewVec = CAMERA_POSITION - (MODEL_MATRIX * vec4(VERTEX, 1.0)).xyz;
      POSITION = MODELVIEWPROJECTION_MATRIX * vec4(VERTEX, 1.0);
  }

  In the above example, assigning a value to POSITION is optional as the usage in this case is identical to the default behavior.

The following functions can be implemented in a fragment shader snippet:

• void MAIN() When present, this function is called to set the values of the special writable variables BASE_COLOR, METALNESS, ROUGHNESS, SPECULAR_AMOUNT, NORMAL, and FRESNEL_POWER.

  One common use case is to set the value of BASE_COLOR based on sampling a texture, be it a base color map, SCREEN_TEXTURE, or some other kind of source. This can be relevant and convenient especially when no custom light processor functions are implemented. Setting BASE_COLOR.a to something other than the default 1.0 allows affecting the final alpha value of the fragment. (note that this will often require also enabling alpha blending in sourceBlend and destinationBlend)

  Another scenario is when there is no custom SPECULAR_LIGHT function provided, or when there is a light probe set in the SceneEnvironment. The metalness, roughness, and other values that affect the specular contribution calculation can be set in MAIN to their desired custom values.

  The function can write to the following special variables. The values written to these will typically be either hardcoded or be calculated based on QML properties mapped to uniforms. The semantics are identical to PrincipledMaterial.

  • vec4 BASE_COLOR - The base color and material alpha value. Corresponds to the built-in materials' color property. When light processor functions are not implemented, it can be convenient to set a custom base color in MAIN because that is then taken into account in the default lighting calculations. The default value is vec4(1.0), meaning white with an alpha of 1.0. The alpha value effects the final alpha of the fragment. The final alpha value is the object (model) opacity multiplied by the base color alpha. When specifying the value directly in shader code, not relying on uniform values exposed from color properties in QML, be aware that it is up to the shader to perform the sRGB to linear conversion, if needed. For example, assuming a vec3 color and float alpha this can be achieved like the following:

     

    Sélectionnez

    float C1 = 0.305306011;
    vec3 C2 = vec3(0.682171111, 0.682171111, 0.682171111);
    vec3 C3 = vec3(0.012522878, 0.012522878, 0.012522878);
    BASE_COLOR = vec4(rgb * (rgb * (rgb * C1 + C2) + C3), alpha);

  • vec3 EMISSIVE_COLOR - The color of self-illumination. Corresponds to the built-in materials' emissive color which is combined by built-in materials's emissiveFactor property and built-in materials's emissiveMap property. The default value is vec3(0.0). When specifying the value directly in shader code, not relying on uniform values exposed from color properties in QML, be aware that it is up to the shader to perform the sRGB to linear conversion, if needed.

  • float METALNESS Metalness amount in range 0.0 - 1.0. The default value is 0. Must be set to a non-zero value to have effect.

  • float ROUGHNESS Roughness value in range 0.0 - 1.0. The default value is 0.

  • float FRESNEL_POWER Specifies the fresnel power. A typical value, and also the default, is 5.0 as that is what a PrincipledMaterial would use.

  • float SPECULAR_AMOUNT Specular amount in range 0.0 - 1.0. The default value is 0.5, matching PrincipledMaterial::specularAmount. Must be set to a non-zero value to have effect.

  • vec3 NORMAL - The normal that comes from the vertex shader in world space. While this property has the same initial value as VAR_WORLD_NORMAL, only changing the value of NORMAL will have an effect on lighting.

  • vec3 TANGENT - The tanget that comes from the vertex shader in world space. This value is potentially adjusted for double-sidedness.

  • vec3 BINORMAL - The binormal that comes from the vertex shader in world space. This value is potentially adjusted for double-sidedness.

  • vec2 UV0 - The first set of texture coordinates from the vertex shader. This property is readonly in the fragment shader.

  • vec2 UV1 - The second set of texture coordinates from the vertex shader. This property is readonly in the fragment shader.

  Unlike with unshaded materials, the fragment MAIN for a shaded material has no direct control over FRAGCOLOR. Rather, it is the DIFFUSE and SPECULAR values written in the light processor functions that decide what the final fragment color is. When a light processor function is not implemented, the relevant default shading calculations are performed as with a PrincipledMaterial, taking BASE_COLOR and other values from the list above into account.

  An example of a simple, metallic custom material shader could be the following:

   

  Sélectionnez

  void MAIN()
  {
      METALNESS = 1.0;
      ROUGHNESS = 0.5;
      FRESNEL_POWER = 5.0;
  }

  Another example, where the base color and alpha are set by sampling a texture:

   

  Sélectionnez

  VARYING vec2 texcoord;
  void MAIN()
  {
      BASE_COLOR = texture(uColorMap, texcoord);
  }

• void AMBIENT_LIGHT() When present, this function is called once for each fragment. The task of the function is to add the total ambient contribution to a writable special variable DIFFUSE. It can of course choose to calculate a different value, or not touch DIFFUSE at all (to ignore ambient lighting completely). When this function is not present at all, the ambient contribution is calculated normally, like a PrincipledMaterial would do.

  The function can write to the following special variables:

  • vec3 DIFFUSE Accumulates the diffuse light contributions, per fragment. The light processor functions will typically add (+=) to it, since overwriting the value would lose the contribution from other lights.

  The function can read the following special variables, in addition to the matrix (such as, MODEL_MATRIX) and vector (such as, CAMERA_POSITION) uniforms from the table above:

  • vec3 TOTAL_AMBIENT_COLOR The total ambient contribution in the scene.

  Example:

   

  Sélectionnez

  void AMBIENT_LIGHT()
  {
      DIFFUSE += TOTAL_AMBIENT_COLOR;
  }

• void DIRECTIONAL_LIGHT() When present, this function is called for each active directional light in the scene for each fragment. The task of the function is to add the diffuse contribution to a writable special variable DIFFUSE. The function can also choose to do nothing, in which case diffuse contributions from directional lights are ignored. When the function is not present at all, the diffuse contributions from directional lights are accumulated normally, like a PrincipledMaterial would do.

  The function can write to the following special variables:

  • vec3 DIFFUSE Accumulates the diffuse light contributions, per fragment. The light processor functions will typically add (+=) to it, since overwriting the value would lose the contribution from other lights.

  The function can read the following special variables, in addition to the matrix (such as, MODEL_MATRIX) and vector (such as, CAMERA_POSITION) uniforms from the table above:

  • vec3 LIGHT_COLOR Diffuse light color.

  • float SHADOW_CONTRIB Shadow contribution, or 1.0 if not shadowed at all or not reciving shadows.

  • vec3 TO_LIGHT_DIR Vector pointing towards the light source.

  • vec3 NORMAL The normal vector in world space.

  • vec4 BASE_COLOR The base color and material alpha value.

  • float METALNESS The Metalness amount.

  • float ROUGHNESS The Roughness amount.

  Example:

   

  Sélectionnez

  void DIRECTIONAL_LIGHT()
  {
      DIFFUSE += LIGHT_COLOR * SHADOW_CONTRIB * vec3(max(0.0, dot(normalize(VAR_WORLD_NORMAL), TO_LIGHT_DIR)));
  }

• void POINT_LIGHT() When present, this function is called for each active point light in the scene for each fragment. The task of the function is to add the diffuse contribution to a writable special variable DIFFUSE. The function can also choose to do nothing, in which case diffuse contributions from point lights are ignored. When the function is not present at all, the diffuse contributions from point lights are accumulated normally, like a PrincipledMaterial would do.

  The function can write to the following special variables:

  • vec3 DIFFUSE Accumulates the diffuse light contributions, per fragment.

  The function can read the following special variables, in addition to the matrix (such as, MODEL_MATRIX) and vector (such as, CAMERA_POSITION) uniforms from the table above:

  • vec3 LIGHT_COLOR Diffuse light color.

  • float LIGHT_ATTENUATION Light attenuation.

  • float SHADOW_CONTRIB Shadow contribution, or 1.0 if not shadowed at all or not reciving shadows.

  • vec3 TO_LIGHT_DIR Vector pointing towards the light source.

  • vec3 NORMAL The normal vector in world space.

  • vec4 BASE_COLOR The base color and material alpha value.

  • float METALNESS The Metalness amount.

  • float ROUGHNESS The Roughness amount.

  Example:

   

  Sélectionnez

  void POINT_LIGHT()
  {
      DIFFUSE += LIGHT_COLOR * LIGHT_ATTENUATION * SHADOW_CONTRIB * vec3(max(0.0, dot(normalize(VAR_WORLD_NORMAL), TO_LIGHT_DIR)));
  }

• void SPOT_LIGHT() When present, this function is called for each active spot light in the scene for each fragment. The task of the function is to add the diffuse contribution to a writable special variable DIFFUSE. The function can also choose to do nothing, in which case diffuse contributions from spot lights are ignored. When the function is not present at all, the diffuse contributions from spot lights are accumulated normally, like a PrincipledMaterial would do.

  The function can write to the following special variables:

  • vec3 DIFFUSE Accumulates the diffuse light contributions, per fragment.

  The function can read the following special variables, in addition to the matrix (such as, MODEL_MATRIX) and vector (such as, CAMERA_POSITION) uniforms from the table above:

  • vec3 LIGHT_COLOR Diffuse light color.

  • float LIGHT_ATTENUATION Light attenuation.

  • float SHADOW_CONTRIB Shadow contribution, or 1.0 if not shadowed at all or not reciving shadows.

  • vec3 TO_LIGHT_DIR Vector pointing towards the light source.

  • float SPOT_FACTOR Spot light factor.

  • vec3 NORMAL The normal vector in world space.

  • vec4 BASE_COLOR The base color and material alpha value.

  • float METALNESS The Metalness amount.

  • float ROUGHNESS The Roughness amount.

  Example:

   

  Sélectionnez

  void SPOT_LIGHT()
  {
      DIFFUSE += LIGHT_COLOR * LIGHT_ATTENUATION * SPOT_FACTOR * SHADOW_CONTRIB * vec3(max(0.0, dot(normalize(VAR_WORLD_NORMAL), TO_LIGHT_DIR)));
  }

• void SPECULAR_LIGHT() When present, this function is called for each active light in the scene for each fragment. The task of the function is to add the specular contribution to a writable special variable SPECULAR. The function can also choose to do nothing, in which case specular contributions from lights are ignored. When the function is not present at all, the specular contributions from lights are accumulated normally, like a PrincipledMaterial would do.

  The function can write to the following special variables:

  • vec3 SPECULAR Accumulates the specular light contributions, per frament. The light processor functions will typically add (+=) to it, since overwriting the value would lose the contribution from other lights.

  The function can read the following special variables, in addition to the matrix (such as, MODEL_MATRIX) and vector (such as, CAMERA_POSITION) uniforms from the table above:

  • vec3 LIGHT_COLOR Specular light color.

  • float LIGHT_ATTENUATION Light attenuation. For directional lights the value is 1.0. For spot lights the value is the same as LIGHT_ATTENUATION * SPOT_FACTOR of void SPOT_LIGHT().

  • float SHADOW_CONTRIB Shadow contribution, or 1.0 if not shadowed at all or not reciving shadows.

  • vec3 FRESNEL_CONTRIB Fresnel contribution from built in Fresnel calculation.

  • vec3 TO_LIGHT_DIR Vector pointing towards the light source.

  • vec3 NORMAL The normal vector in world space.

  • vec4 BASE_COLOR The base color and material alpha value.

  • float METALNESS The Metalness amount.

  • float ROUGHNESS The Roughness amount.

  • float SPECULAR_AMOUNT The specular amount. This value will be between 0.0 and 1.0 will be the same value set in the custom MAIN function. This value will useful for calculating Fresnel contributions when not using the built-in Fresnel contribution provided by FRESNEL_CONTRIB.

   

  Sélectionnez

  void SPECULAR_LIGHT()
  {
      vec3 H = normalize(VIEW_VECTOR + TO_LIGHT_DIR);
      float cosAlpha = max(0.0, dot(H, normalize(NORMAL)));
      float shine = pow(cosAlpha, exp2(15.0 * (1.0 - ROUGHNESS) + 1.0) * 0.25);
      SPECULAR += shine * LIGHT_COLOR * FRESNEL_CONTRIB * SHADOW_CONTRIB * LIGHT_ATTENUATION;
  }

• void POST_PROCESS() When present, this function is called at the end of the fragment pipeline. The task of the function is to finalize COLOR_SUM with final diffuse, specular and emissive terms. Unlike FRAGCOLOR for a unshaded material, COLOR_SUM will be automatically tonemapped before written to the framebuffer. For debugging purposes it is sometimes useful to output a value that should not be treated as a color. To avoid the tonemapping distorting this value it can be disabled by setting the tonemapMode property to TonemapModeNone

  The function can write to the following special variables:

  • vec4 COLOR_SUM the output from the fragment shader. The default value is vec4(DIFFUSE.rgb + SPECULAR + EMISSIVE, DIFFUSE.a)

  The function can read the following special variables.

  • vec4 DIFFUSE The final diffuse term of the fragment pipeline.

  • vec3 SPECULAR The final specular term of the fragment pipeline.

  • vec3 EMISSIVE The final emissive term of the fragment pipeline.

  • vec2 UV0 - The first set of texture coordinates from the vertex shader.

  • vec2 UV1 - The second set of texture coordinates from the vertex shader.

   

  Sélectionnez

  void POST_PROCESS()
  {
      float center_x = textureSize(SCREEN_TEXTURE, 0).x * 0.5;
      if (gl_FragCoord.x > center_x)
          COLOR_SUM = DIFFUSE;
      else
          COLOR_SUM = vec4(EMISSIVE, DIFFUSE.a);
  }

• void IBL_PROBE() When present, this function is called for IBL (Image-Based Lighting). The task of the function is to add both the diffuse and the specular contributions of IBL to writable special variables DIFFUSE and SPECULAR.

  The function can write to the following special variables:

  • vec3 DIFFUSE Accumulates the diffuse light contributions, per fragment.

  • vec3 SPECULAR Accumulates the specular light contributions, per frament.

  The function can read the following special variables.

  • vec4 BASE_COLOR The base color and material alpha value.

  • float AO_FACTOR The screen space occlusion factor.

  • float SPECULAR_AMOUNT The specular amount.

  • float ROUGHNESS The final emissive term of the fragment pipeline.

  • vec3 NORMAL The normal vector in world space.

  • vec3 VIEW_VECTOR Points towards the camera.

  • mat3 IBL_ORIENTATION The orientation of the light probe. It comes from SceneEnvironment::probeOrientation.

   

  Sélectionnez

  void IBL_PROBE()
  {
      vec3 smpDir = IBL_ORIENTATION * NORMAL;
      DIFFUSE += AO_FACTOR * BASE_COLOR.rgb * textureLod(IBL_TEXTURE, smpDir, IBL_MAXMIPMAP).rgb;
  }

Additional variables can be delivered from the MAIN function to the others. The SHARED_VARS keyword can be used for defining new custom variables. These user-defined variables can be accessed with SHARED.<variable name>.

For example, a shaded custom material can fetch a shared value in the MAIN and use it in other functions.

SHARED_VARS {
    vec3 colorThreshold;
};
void MAIN()
{
    BASE_COLOR = texture(baseColorMap, UV0);
    SHARED.colorThreshold = texture(thresholdMap, UV0).rgb;
}
void DIRECTIONAL_LIGHT()
{
    if (DIFFUSE >= SHARED.colorThreshold) {
        DIFFUSE = SHARED.colorThreshold;
        return;
    }
    DIFFUSE += LIGHT_COLOR * SHADOW_CONTRIB;
}

SHARED_VARS {
    float sheenIntensity;
    float sheenRoughness;
    vec3 sheenColor;
    vec3 outSheenColor;
};
void MAIN()
{
    ...
    vec4 tex = texture(uSheenMap, UV0);
    SHARED.sheenColor = tex.rgb;
    SHARED.sheenIntensity = tex.a;
    SHARED.sheenRoughness = uSheenRoughness;
    SHARED.outSheenColor = vec3(0.0);
}
void SPECULAR_LIGHT()
{
    SHARED.outSheenColor += ...;
}
void POST_PROCESS()
{
    COLOR_SUM = DIFFUSE + SPECULAR + EMISSIVE + SHARED.outSheenColor;
}

The custom fragment shader code can freely access uniforms (such as, CAMERA_DIRECTION or CAMERA_POSITION), and varyings passed on from the custom vertex shader. Additionally, there are a number of built-in varyings available as special keywords. Some of these are optional in the sense that a vertex MAIN could calculate and pass on these on its own, but to reduce duplicated data fragment shaders can also rely on these built-ins instead. These built-ins are available in light processor functions and in the fragment MAIN.

• vec3 VAR_WORLD_NORMAL - Interpolated normal transformed by NORMAL_MATRIX.

• vec3 VAR_WORLD_TANGENT - Interpolated tangent transformed by MODEL_MATRIX.

• vec3 VAR_WORLD_BINORMAL - Interpolated binormal transformed by MODEL_MATRIX

• vec3 NORMAL - Unlike VAR_WORLD_NORMAL, which is the interpolated normal as-is, this value is potentially adjusted for double-sidedness: when rendering with culling disabled, the normal will get inverted as necessary. Therefore lighting and other calculations are recommended to use NORMAL instead of VAR_WORLD_NORMAL in order behave correctly with all culling modes.

• vec3 TANGENT - Like NORMAL, this value is potentially adjusted for double-sidedness: when rendering with culling disabled, the tangent will get inverted as necessary.

• vec3 BINORMAL - Like NORMAL, this value is potentially adjusted for double-sidedness: when rendering with culling disabled, the binormal will get inverted as necessary.

• vec3 VAR_WORLD_POSITION - Interpolated world space vertex position ((MODEL_MATRIX * vec4(VERTEX, 1.0)).xyz)

• vec4 VAR_COLOR - The interpolated vertex color when colors are provided in the mesh. vec4(1.0) otherwise.

• vec3 VIEW_VECTOR - Points towards the camera. This is effectively the CAMERA_POSITION - VAR_WORLD_POSITION vector normalized.

• vec4 FRAGCOORD - Contains the window-relative coordinates of the current fragment.

• float FRAMEBUFFER_Y_UP - The value is 1 when the Y axis points up in the coordinate system for framebuffers (textures), meaning (0, 0) is the bottom-left corner. The value is -1 when the Y axis points down, (0, 0) being the top-left corner. Such differences in the underlying graphics APIs do not concern most custom materials. One notable exception is sampling SCREEN_TEXTURE with texture coordinates not based on FRAGCOORD. As the orientation of SCREEN_TEXTURE is tied to the underlying graphics API by nature, using texture coordinates from a mesh may need appropriate adjustments to the Y coordinate.

  For example, the following fragment shader, suitable for Rectangle or Cube meshes, will display the opaque objects from the scene on the model:

   

  Sélectionnez

  VARYING vec2 texcoord;
  void MAIN()
  {
      vec2 screencoord = texcoord;
      if (FRAMEBUFFER_Y_UP < 0.0) // effectively: if not OpenGL
          screencoord.y = 1.0 - screencoord.y;
      BASE_COLOR = texture(SCREEN_TEXTURE, screencoord);
  }

  When sampling textures other than SCREEN_TEXTURE and DEPTH_TEXTURE, or when FRAGCOORD is used to calculate the texture coordinate (which would be the typical use case for accessing the screen and depth textures), such an adjustment is not necessary.

• float NDC_Y_UP - The value is 1 when the Y axis points up in normalized device coordinate space, and -1 when the Y axis points down. Y pointing down is the case when rendering happens with Vulkan. Most materials do not need to be concerned by this, but being able to branch based on this can become useful in certain advanced use cases.

• float NEAR_CLIP_VALUE - The value is -1 for when the clipping plane range's starts at -1 and goes to 1. This is true when using OpenGL for rendering. For other rendering backends the value of this property will be 0 meaning the clipping plane range is 0 to 1. This value is useful with certain techniques involving the DEPTH_TEXTURE

  For example, the following fragment shader demonstrates a technique for reconstructing the position of a value from the depth buffer to determine the distance from the current position being rendered. When used in combination with INVERSE_PROJECTION_MATRIX the value of depth needs to be in normalized device coordinates so it is important to make sure that the range of depth value reflects that. When the NEAR_CLIP_VALUE is -1 then the depth value gets scaled to be between -1 and 1.

   

  Sélectionnez

  void MAIN() {
      vec2 screen_uv = FRAGCOORD.xy / vec2(textureSize(SCREEN_TEXTURE, 0));
      float depth = texture(DEPTH_TEXTURE, screen_uv).r;
  
      if (NEAR_CLIP_VALUE < 0.0) // effectively: if opengl
          depth = depth * 2.0 - 1.0;
  
      vec4 unproject = INVERSE_PROJECTION_MATRIX * vec4(screen_uv, depth, 1.0);
      depth = (unproject.xyz / unproject.w).z;
      float viewVectorZ = (VIEW_MATRIX * vec4(VAR_WORLD_POSITION, 1.0)).z;
      depth = viewVectorZ - depth;
  
      BASE_COLOR = vec4(depth, depth, depth, 1.0);
  }

• float IBL_EXPOSE - The amount of light emitted by the light probe. It comes from SceneEnvironment::probeExposure.

   

  Sélectionnez

  DIFFUSE += AO_FACTOR * IBL_EXPOSE * BASE_COLOR.rgb * textureLod(IBL_TEXTURE, NORMAL, IBL_MAXMIPMAP).rgb;

• float IBL_HORIZON - The horizontal cut-off value of reflections from the lower half environment. It comes from Horizon Cut-Off but remapped to [-1, 0).

   

  Sélectionnez

  vec3 diffuse += AO_FACTOR * IBL_EXPOSE * BASE_COLOR.rgb * textureLod(IBL_TEXTURE, NORMAL, IBL_MAXMIPMAP).rgb;
  if (IBL_HORIZON > -1.0) {
      float ctr = 0.5 + 0.5 * IBL_HORIZON;
      float vertWt = smoothstep(ctr * 0.25, ctr + 0.25, NORMAL.y);
      float wtScaled = mix(1.0, vertWt, IBL_HORIZON + 1.0);
      diffuse *= wtScaled;
  }

• float IBL_MAXMIPMAP - The maximum mipmap level of IBL_TEXTURE.

When doing instanced rendering, some of the keywords above do not apply. The following keywords are only available with instancing:

• INSTANCE_MODEL_MATRIX -> mat4, replacement for MODEL_MATRIX, including the instancing transformation.

• INSTANCE_MODELVIEWPROJECTION_MATRIX -> mat4, replacement for MODELVIEWPROJECTION_MATRIX, including the instancing transformation.

• INSTANCE_COLOR -> vec4, the instance color: to be combined with COLOR.

• INSTANCE_DATA -> vec4, instance custom data.

• INSTANCE_INDEX -> int, the instance number, and index into the instancing table.

See also vertexShader

See also fragmentShader