Physically-based materials

This example demonstrates the use of physically-based shading and HDR post-processing in Kanzi. Since physically-based shading and HDR post-processing are still in the development phase, use these examples as a sneak peak into a technology you will be able to use in a later version of Kanzi.

Key features:

• Physically-based materials
• High dynamic range lighting
• Shading done in linear color space
• Rendering through half-float texture
• Post-processing with bloom effect, exposure control and tone mapping

You can find the examples that show the use of physically-based materials in these example projects:

• <KanziWorkspace>/Examples/Physically_Based_Material
• <KanziWorkspace>/Examples/Post_Processing
  Note that because Nexus 7 (2012, 1st generation) device does not support bilinear filtering of half float textures, this example does not work on that device.
• <KanziWorkspace>/Examples/Post_Processing_Simple.

Limitations

• The Preview Edit mode is not fully compatible with the current implementation of post-processing. Selection, the Preview tools, and debug visualizations do not work with composers that use render to texture (including post-processing).
  Workaround: From the Project drag the main scene to the Prefabs, to create a prefab from the main scene, and in the Prefabs double-click that prefab to view only that prefab in the Preview.
  When previewing post-processing you can use some basic Edit mode features, such as free camera. However, in order for the free camera to work, in the Project select the camera in the scene.
• You have to manually optimize shaders. To make this somewhat manageable, use the material type Preprocessor Defines property. This way you can change shader features without editing the shader sources directly.
• You have to manually configure post-processing composition for each target resolution. A few examples are included in the Post_Processing example project.
• For some nodes the thumbnails are not compatible with post-processing.
• When using post-processing, clear color for main scene goes through color space conversion and tone mapping.

Required OpenGL ES extensions

Advanced materials with post-processing requires either OpenGL ES 3.x, or OpenGL ES 2.0 with a set of extensions. The following OpenGL ES extensions are required when using OpenGL ES 2.0:

• OES_texture_half_float
• OES_texture_half_float_linear
• GL_EXT_color_buffer_half_float

If these extensions are not available, it is still possible to use physically-based materials and lights, however, currently post-processing is not available without these extensions.

To use post-processing, set in the Project > Properties the Target Graphics API property to at least OpenGL ES 2.0 Extension Pack.

Overview of post-processing steps

Post-processing requires these main steps:

• Render main scene to texture. The scene is rendered almost normally, however, image is written to texture instead of the screen. Also the texture is high dynamic range, and no tone mapping is done by material shaders.
• Intermediate post-processing. The texture from the first step is blurred, and size is halved. The process is repeated using output of the previous blur as the input for the next blur, until the output texture is very small (close to 1 by 1 pixel). All intermediate blur textures are kept as separate textures.
• Final composition. The main scene output from the first step and all the intermediate blur textures from the second step are added together, to create a bloom effect. After the bloom, camera exposure, and tone mapping is applied to get the final image.

Setting up post-processing

To use post-processing you need to set up these resources:

1. Resources. Resources, such as textures, composers, render passes, material types, shaders, materials, custom property types are needed from Post_Processing example project.

   You also need the "Prefabs/Quad Scene" prefab. This scene prefab contains only one, specially prepared object: a quad with extents from (-1, -1) to (1, 1). The quad has a tag "Quad" which is used in post-processing composers to specify object source for render passes that apply the post-processing effect to a texture. Do not modify this prefab.

   There are two versions of the example project. Post_Processing_Simple is nearly minimal setup, and Post_Processing has extra pages to show the scene with and without post processing, and to show intermediate textures.

   The example projects are prepared for target resolution of 1920x1080. The debug version of the example project has resources to support a few other resolutions.

2. The main scene prefab template. The main scene must come from a prefab. In the example project this prefab is called "Prefabs/Main Scene". This is where you place content you want to render with post-processing.

   To support physically-based material shading, the scene prefab must have these properties:

   • For lights:
     • SkyLightColor
     • SkyLightScale
   • For exposure and tone mapping:
     • Inverse Exposure

   Additionally, the scene prefab template must have "Prefab preview mode" property set to 1. This value is intended to be overridden in the placeholders. This way, when previewing the prefab placeholder composition (value 1), material shaders perform additional tone mapping. Normally tone mapping is done after (or at the end of) post processing (value 0).

   For detailed descriptions of these properties, see Property Types.

3. Host node for post-processing properties. The project must have an ancestor node that contains properties to control the post-processing effect. In the example project this node is a Page Host named "Page".

4. Viewport for the "Scene to Texture". The node from the previous step ("Page") must contain a viewport for rendering scene to texture. In the Post_Processing_Simple example project this viewport is named "Page/Scene to Texture".

   The viewport must have the Layer Aspect Ratio property set to a value that matches the aspect ratio of the target resolution. In the example project the target resolution is 1920x1080 with aspect ratio of 1.777.

   The viewport should have an alias to provide an easy access to the Layer Aspect Ratio property. In the example project the resource dictionary of the "Screen" has the "Viewport" alias.

5. Scene placeholder for the "Scene to Texture". The viewport from the previous step ("Page/Scene to Texture") must have a scene placeholder which instantiates the "Main Scene" prefab template from the step ("Prefabs/Main Scene"). In the example project this scene placeholder is named "Scene to Texture/Scene (Main Scene)".

   The scene placeholder must have the Composer property with value "Render to Texture (1920x1080) Composer".

   The scene placeholder must have the "Prefab Preview Mode" property set to 0. This directs the material shader to operate normally (without extra tone mapping).

   This node renders the contents of the main scene to the "HDR Render 1920x1080" render target texture, which is later used as input for post-processing operations.

6. Providing access to the "Inverse Exposure" property. The Preview composition for the Main Scene prefab template requires the value of the exposure value for tone mapping. Because prefabs cannot access anything outside the prefab, this property is stored in the prefab, and made available to the project using the prefab placeholder.

   The scene placeholder from the previous step ("Scene (Main Scene)") must have an alias, to provide easy access to exposure property. In the example project, the resource dictionary of the Screen has the "MainScene" alias that points to the scene placeholder.

   The node from step 3 ("Page") must have this binding for the "Inverse Exposure" property:

   {#MainScene/Exposure}

   Post-processing nodes that need the exposure setting get it from the node from step 3 ("Page") through this binding and property inheritance.

7. Viewport for "Post Processing Intermediate". The node from step 3 ("Page") must contain a viewport for the intermediate post-processing operation. In the example project, this viewport is called "Page/Post Processing Intermediate".

8. Scene placeholder for "Post Processing Intermediate". The viewport from the previous step ("Page/Post Processing Intermediate") must contain a scene placeholder for the "Prefabs/Quad Scene" prefab (from step 1). In the example project, this is the "Post Processing Intermediate/Scene (Quad Scene)".

   The scene placeholder must have the Composer property set to "Post Processing (1920x1080) Intermediate Composer".

   The shaders that create the bloom in this composer need these properties to control the bloom effect:

   • BloomBase
   • BloomShape

   These are inheritable properties and they come from the node in step 3 ("Page").

   The viewport must have a binding for the Inverse Exposure property so that it uses value from the scene:

   - {Inverse Exposure} = {../Scene/Exposure}

   For detailed descriptions of these properties, see Property Types.

9. Viewport for "Final Composition". The node from step 3 ("Page") must contain a viewport for the final composition. In the Post_Processing_Simple example project, this viewport is named "Page/Final Composition".

10. Scene placeholder for "Final Composition". The viewport from step 9 ("Page/Final Composition") should contain a scene placeholder for "Prefabs/Quad Scene" prefab (from step 1). In the example project, this scene is named "Final Composition/Scene (Quad Scene)".

    The scene placeholder must have the Composer property set to "Post Processing (1920x1080) Final Composer".

    The shader that creates the bloom composition and tone mapping needs these properties:

    • BloomScale
    • Inverse Exposure

    These are inheritable properties and they must come from the node in step 3 ("Page").

    For detailed descriptions of these properties, see Property Types.

Materials and Textures

Note that you must not modify these textures.

• Post Processing. This directory contains a set of textures used by the post-processing composer. The smallest texture size is 1x1, and is prefixed with number 00. The texture size is alternatingly doubled in width and height, and the prefix number is increased.
• black_4x4, white_4x4, and normal_flat. These are the default textures used by materials.
• HDR Render 1920x1200. This is a half-float texture, where the scene is rendered before any post-processing. This is the input for the post-processing.

Composers

• Render to Texture (1920x1080) Composer. This composer renders the scene into the HDR texture, so that later composers can read from it. Do not change this composer.
• Render to Viewport Composer. This composer renders the scene directly to the viewport. Using this composer results in an image without any post-processing effects. This is nearly the same as the <Default Composer>, except that the Render to View Composer includes customizable Clear Color. Other than Clear Color, do not change this composer.

• Post Processing (1920x1080) Intermediate Composer. This composer reads the HDR texture and produces a set of blurred and scaled textures from it.

  The composer has alternating horizontal and vertical render passes. Each render pass performs a blur filter in one dimension, reading from the input texture, and rendering to the output texture, which measures half the input in the specified dimension.

  The first pass reads from the HDR Render texture, and writes to a render target texture which best matches size of the HDR render texture with width halved.

• Post Processing (1920x1080) Final Composer. The render pass "1920x1080 Sum of Gaussians and Tonamep" performs the composition of the original HDR Render texture and the intermediate filtered textures for a bloom effect. After bloom, it applies exposure and tone mapping to get the final output which is shown in viewport. Do not change this composer.

Property Types

Physically-based lights properties:

• Light Color Scale. Physically based materials will multiply light color with the light color scale value. This can be used to create lights with high intensities.

  Note that light color scale only applies to the physically based shader. It is not recommended to mix physically based and non-physically based material shaders that involve lights.

• Point Light Radius is reserved for future use.
• Light Attenuation. Note that physically-based materials support only physically based light attenuation (Constant = 0, Linear = 0, Quadratic = 1)

Post-processing (bloom effect and tone mapping) properties:

• BloomBase controls how bright pixels need to be before they contribute to bloom. Low values mean bloom effect requires brighter pixels.
• BloomShape controls how wide the bloom effect is. Higher values make bloom effect wider, lower values make the bloom effect narrower.
• BloomScale controls the overall bloom effect strength. Higher values make stronger bloom effect.
• Inverse Exposure controls the tone mapping. Actual exposure value is inverse of the property value. Low inverse exposure value produces more bright image, higher inverse exposure value produce darker image.

Environment properties:

• EnvironmentIntensity, IrradianceCube, RadianceCube are reserved for future use.
• SkylightColor defines a color for approximation of environmental and ambient hemispherical skylight.
• SkyLightScale modulates the intensity of SkylightColor.

Material properties:

• Base Color defines the base color.

• Base Color Map (optional) texture modulates base color, when material type supports base color map.

  A white texture works as if there was no Base Color Map, however, using white texture is less efficient than creating a material type with Base Color Map disabled.

  Using Base Color Map requires that material type supports texture coordinates, and that mesh has texture coordinates (kzTextureCoordinate0).

• Roughness. Materials with low roughness values are shiny, they have strong specular highlights. Materials with high roughness values are diffuse, with little or no specular highlights.
• Metalness. Metallic materials have no diffuse, and specular highlights use base color. Non-metallic materials have diffuse. Their specular highlights are white.
• Cavity models small surface features that effectively modulate specular highlights.

• RoughnessMapScale (optional). When a material type supports Surface texture, the value of RoughnessMapScale * value of the roughness channel from Surface texture is added to the value of Roughness property. Scale can be either negative or positive.

  If you have roughness texture where shiny parts are white, and rough parts are black, start by setting Roughness to 1.0 and RoughnessMapScale to -1.0.

• MetalnessMapScale (optional). When a material type supports Surface texture, the value of MetalnessMapScale * value of the metalness channel from Surface texture is added to the value of Metalness property. Scale can be either negative or positive.
• CavityMapScale (optional). When a material type supports Surface texture, the value of CavityMapScale * value of the cavity channel from Surface texture is added to the value of the Metalness property. Scale can be either negative or positive.
• Ambient occlusion (optional). When a material type supports Surface texture, the value of the ambient occlusion channel from the Surface texture is used to modulate the environmental lighting.

• Surface texture (optional). When a material type supports the Surface texture, color channels in at are used as Roughness, Cavity, Metalness and Ambient occlusion.

  A black texture works as if there was no Base Color Map, however, using black texture is less efficient than creating a material type with surface texture disabled.

  Using surface texture requires that material type supports texture coordinates, and that mesh has texture coordinates (kzTextureCoordinate0).

• TextureTile (optional). When a material type supports base color map or surface texture, you can adjust the mapping of the texture coordinates by scaling the texture coordinates with values in the TextureTile.

• Normal Map (optional). When material type supports normal map, this property selects a normal map that is applied to the surface.

  Using tangent texture requires texture coordinates (kzTextureCoordinate0) and tangents.

  Using texture with flat color (0.5, 0.5, 1.0) works as if there was no normal map. However, this is less efficient than creating a material type with surface texture disabled.

• Normal Map Scale (optional). When material type supports normal map, this is used to adjusted strength of normal map. Value can be both negative and positive.

• Anisotropy (optional). When material type supports anisotropic light reflections, absolute value of anisotropy specifies amount of anisotropy, and sign specifies direction. Anisotropic light reflections provide look of brushed metals.

  Using anisotropic light reflections requires that mesh has tangents. You can generate tangents for any mesh that has normals and texture coordinates with Generate Tangents context menu for Mesh.

  Anisotropy value of 0.0 means surface is fully isotropic however, using 0.0 anisotropy is less efficient than creating a material type with anisotropy disabled.

• Tangent Map (optional). When material type supports tangent textures, tangents can be sourced from a texture, instead of vertex attribute.

  Using tangent texture requires texture coordinates (kzTextureCoordinate1).

  Using tangent texture voids issues with singularities such as in circularly brushed metal.

Physically-based material types

All material types in this folder use identical shader sources for physically-based material. The material types are customized with Preprocessor Defines property. The main purpose of various preprocessor defines is to allow creation of optimized shader variants. In theory, it might be possible to use one, or only few, variants of the physically-based material type. In practice, it may be necessary to create more variants of physically-based material type to reach better performance.

To create a new variant, duplicate an existing material type, adjusted preprocessor defines to minimum of required features, and click Sync with Uniforms.

The shader uses the following preprocessor defines:

• KANZI_SHADER_NUM_DIRECTIONAL_LIGHTS specifies number of supported directional lights
• KANZI_SHADER_NUM_POINT_LIGHTS specifies number of supported point lights
• KANZI_SHADER_NUM_SPOT_LIGHTS specifies number of supported spot lights

• KANZI_SHADER_USE_AMBIENT_OCCLUSION modulates environmental light such as skylight. Ambient occlusion can come from either vertex color, or from alpha channel of surface texture.

  0 disables support for ambient occlusion

  1 enables support for ambient occlusion.

• KANZI_SHADER_USE_AMBIENT_OCCLUSION_VERTEX_ATTRIBUTE. See also KANZI_SHADER_USE_AMBIENT_OCCLUSION.

  0 selects Surface texture as source for ambient occlusion

  1 selects vertex color as source for ambient occlusion

• KANZI_SHADER_USE_ANISOTROPY

  0 disables support for anisotropic light reflections and makes the shader faster.

  1 enables support for anisotropic light reflections and slows down the shader.

• KANZI_SHADER_USE_BASECOLOR_TEXTURE

  0 disables support for basecolor texture and makes the shader faster.

  1 enables support for basecolor texture and slows down the shader.

• KANZI_SHADER_USE_CAMERA_EXPOSURE controls whether material shader performs camera exposure.

  Note that KANZI_SHADER_USE_PREFAB_PREVIEW preprocessor define allows material type to control camera exposure (and linear to sRGB conversion) with a uniform, enabling camera exposure even if KANZI_SHADER_USE_CAMERA_EXPOSURE is set to 0.

  0 disables camera exposure during material shading. Use this setting when using post-processing.

  1 enables camera exposure during material shading. Use this setting when not using post-processing.

• KANZI_SHADER_USE_NORMALMAP_TEXTURE. Normalmap requires texture coordinates and tangents.

  0 enables the use of normalmap.

  1 disables the use of normalmap.

• KANZI_SHADER_USE_PREFAB_PREVIEW

  0 disables use of prefab preview and makes the shader faster.

  1 enables use of prefab preview, which allows bypassing post processing, and slows down the shader.

• KANZI_SHADER_USE_SKY_LIGHT

  0 disables environmental skylight approximation.

  1 enables environmental skylight approximation.

• KANZI_SHADER_USE_SURFACE_TEXTURE you can use to modulate material properties Roughness, Metallic, Cavity and Ambient Occlusion.

  0 disables surface texture.

  1 enables surface texture.

• KANZI_SHADER_USE_TANGENT_TEXTURE. Tangent texture can replace use of vertex tangents.

  0 disables tangent texture.

  1 enables tangent texture.

• KANZI_SHADER_USE_TEXTURE_COORDINATES. When material type has a texture, you must enable texture coordinates.

  0 disables texture coordinates.

  1 enables texture coordinates.

You can use these preprocessor defines for debugging. To enable debugging, set the values to 1:

• KANZI_SHADER_DEBUG_SHOW_VERTEX_BITANGENT
• KANZI_SHADER_DEBUG_SHOW_NORMAL
• KANZI_SHADER_DEBUG_SHOW_TEXTURE_COORDINATE0
• KANZI_SHADER_DEBUG_SHOW_TEXTURE_COORDINATE1
• KANZI_SHADER_DEBUG_SHOW_TEXTURE_TANGENT
• KANZI_SHADER_DEBUG_SHOW_VERTEX_TANGENT
• KANZI_SHADER_DEBUG_SHOW_VIEW

These preprocessor defines are required, but they are used for features that are still in development. Always use value 0 for these:

• KANZI_SHADER_USE_AREA_LIGHT
• KANZI_SHADER_USE_DISNEY_DIFFUSE
• KANZI_SHADER_USE_IOR
• KANZI_SHADER_USE_IRRADIANCE_CUBE
• KANZI_SHADER_USE_RADIANCE_CUBE
• KANZI_SHADER_USE_RGBM_ENCODE
• KANZI_SHADER_USE_SRGB_ENCODE

Post-processing material types

• Blur H, Blur V material types read from input texture, apply a small filter, and write output to a texture which is half size of the source texture.
• Bloom and Tonemap calculates the sum of the various blurred versions, which approximates sum of gaussians, which is added.

See also

Examples

Open topic with navigation