Shader reference

Changelog

Full changelog file

Warm up

In Substance 3D Painter, you can write your own shaders in GLSL. We allow you to write only a portion of the fragment shader, which is sometimes called a surface shader. Without further ado, let's introduce the "Hello world" Substance 3D Painter surface shader:

void shade(V2F inputs) {
   diffuseShadingOutput(vec3(1.0, 0.0, 1.0));
 }
Copied to your clipboard
void shade(V2F inputs) {
   diffuseShadingOutput(vec3(1.0, 0.0, 1.0));
 }

Now, if you save this snippet into a .glsl file and load it into Substance 3D Painter by dropping it into your shelf's shader tab, you can now use it and see a beautiful uniform pink color on your mesh.

Surface shader

surface-shader.glsl

Engine provided data

In Substance 3D Painter, you can access rendering engine parameters (document's channels, additional textures, camera-related data and the like). Here is an exhaustive list of all engine provided parameters :

all-engine-params.glsl

Engine settings

In some cases you may want to use a specific rendering configuration (culling, blending, sampling locality, and the like) for an effect. Some rendering states are exposed and can be set in the shader. Here is an exhaustive list of all exposed rendering states :

all-rendering-states-params.glsl

Custom tweaks

It's usual to have custom tweaks in a shader. To do so in Substance 3D Painter's shaders, we have introduced a way to specify custom tweaks. Here is an exhaustive list of all custom shader tweaks types :

all-custom-params.glsl

Custom qualifiers

Beside regular GLSL qualifiers, we added a custom uniform_specialization qualifier that can be used as drop-in replacement of uniform to optimize uber shaders :

all-custom-qualifiers.glsl

Embedded libraries

In order to avoid writing a lot of boilerplate code in all of your shaders, we created a small yet practical library of useful functions. Please note that you can't edit it nor create your own at the moment.

lib-alpha-test.glsl : contains alpha test related helpers
lib-bayer.glsl : contains bayer matrix helpers
lib-bent-normal.glsl : contains bent normal helpers
lib-coat.glsl : contains coating layer helpers
lib-defines.glsl : contains useful math constants and base defines
lib-emissive.glsl : contains emissive properties helpers
lib-env.glsl : contains environment map related helpers
lib-normal.glsl : contains normal map related helpers (and height-map generated normal map)
lib-pbr.glsl : contains physically based rendering helpers
lib-pbr-aniso.glsl : contains anisotropic physically based rendering helpers
lib-pom.glsl : contains parallax occlusion mapping helpers
lib-random.glsl : contains random utilities (low discrepancy sequences)
lib-sampler.glsl : contains channel getters helpers
lib-sheen.glsl : contains sheen model reflection helpers
lib-sparse.glsl : contains safe sparse texture sampling helpers
lib-sss.glsl : contains subsurface scattering helpers
lib-utils.glsl : contains color utility functions (sRGB conversions, tone mapping)
lib-vectors.glsl : contains common vectors helpers

Metadata

You can declare additional non required information to give some hint to the rendering system. Here is the syntax:

//: metadata {
 //:   "key1":"value1",
 //:   "key2":"value2"
 //: }
Copied to your clipboard
//: metadata {
 //:   "key1":"value1",
 //:   "key2":"value2"
 //: }

Supported keys are:

custom-ui: Replace the standard shader parameters user interface with a custom view written as a QML module (see scripting documentation). The path can be absolute or relative to one of your shelf custom-ui folder.
mdl: define the Iray mdl material to use with the shader. The path syntax is as follow: mdl::folder1::folder2::mdl_filename::material_name where folder1::folder2::mdl_filename is the path inside one of your shelf mdl folder to a mdl file and ::material_name is the name of a material declared inside this mdl file. (ex: "mdl" : "mdl::alg::materials::painter::pbr::physically_metallic_roughness")

Example shaders

To better understand how to write a complete shader, here are a few examples, ordered by increasing complexity:

pixelated.glsl : a pixelating shader.
toon.glsl : a toon shader.
pbr-metal-rough.glsl : the legacy PBR shader.
asm-metal-rough.glsl : the default PBR shader, which implements the Adobe Standard Material Definition.

Dynamic material layering

The Dynamic Material Layering is a specific workflow where materials are mixed together inside a shader and let the user dynamically edit blending masks in Substance 3D Painter. To enable this workflow, there are two new functionalities: