<cat>Material.ShaderBasic</cat> <title>Material API</title> # What is the Material API The Material API is a collection of helper methods & texture inputs to describe the surface of your material. The main purpose of the Material API is to prepare your data and pass it to a <page>ShadingModel</page>. ⤶ The Material API is automatically used when you add the `common/pixel.hlsl` include to your pixel shader. ⤶ # How does it work? The Material API is automatically used when you add the `common/pixel.hlsl` include to your pixel shader.⤶ ⤶ ## Texture Inputs⤶ Material API handles creating & processing texture inputs for everything that PBR shading model needs. When you're including `pixel.hlsl`, Material API will automatically populate input slots for most common texture maps by default. It will also create variables for tint color and self-illumination intensity. They will show up in Material Editor when you're creating a new material using your new shader.⤶ ⤶ If you want to access any of these input maps from material specifically, here are the variable names: ⤶ ⤶ | Input Slot | Type | Note |⤶ |------------|------|----|⤶ | Albedo | float3 | |⤶ | Metalness | float | |⤶ | Roughness | float | |⤶ | Emission | float3 | |⤶ | Normal | float3 | |⤶ | TintMask | float | |⤶ | AmbientOcclusion | float | |⤶ | Transmission | float3 | does nothing |⤶ | Opacity | float | Requires translucency, see custom material inputs section |⤶ ⤶ Also, if you're **not using** custom material inputs, you'll be able to access these variables: ⤶ ⤶ | Default Variable | Type |⤶ |----|----|⤶ | g_flTintColor | float3 |⤶ | g_flSelfIllumScale | float |⤶ ⤶ # Creating & processing a material⤶ ⤶ This is an automated variant to handle the material. If you're just starting making shaders, this may be a better option for you. Before you build new material object and pass it into shading model, you need to initialize it inside the `MainPs` block first. To do it, simply create a new variable like this, using `Material::From( i )`.⤶ ⤶ ```⤶ Material m = Material::From( i );⤶ ```⤶ ⤶ After this, it will automatically build a new material object, as well as sample & store into corresponding slots your albedo, normal, and RMA maps. (Roughness + Metalness + AO)⤶ ⤶ If you have any other texture maps you want to include, you'd need to fill them yourself. For example,⤶ if you need a proper emission map for your shader, you'd have to do this:⤶ ``` PS { #include "common/pixel.hlsl"⤶ // ...⤶ ⤶ CreateInputTexture2D( Emission, Srgb, 8, "", "_em", "Material,10/60", Default3( 0.5, 0.5, 0.5 ) );⤶ Texture2D g_tEmission < Channel( RGB, Box( Emission ), Srgb ); OutputFormat( BC7 ); SrgbRead( true ); >;⤶ // ...⤶ float4 MainPs( PixelInput i ) : SV_Target0 { // Gather our texture inputs and convert them to the material struct⤶ Material m = GatherMaterial( i ); // Force our object to be metallic⤶ m.Metalness = 1.3f; // Shade our surface with lighting⤶ return FinalizePixelMaterial( i, m );⤶ // ...⤶ Material m = Material::From( i ); m.Emission = g_tEmission.Sample( g_sAniso, i.vTextureCoords.xy ) * g_flSelfIllumScale;⤶ // By default, Material API includes a float variable that we can use for changing emission intensity right from the material settings :-) // ...⤶ } } ``` ⤶ # Texture Inputs⤶ By default, the Material API provides a set of texture inputs. These texture inputs can be used to automatically populate the Material struct for you. To populate your Material object, simply call `GatherMaterial` using your `PixelInput` as the argument. GatherMaterial will automatically transform your normal map to be within object space, set up texture compression & pack different textures into one texture to reduce memory. ⤶ ⤶ You can edit any other texture map in material object even after using `::From( i )` the same way. To see all input slots material has, please check out the list above. ⤶ Once you finish configuring your material, it is ready to be passed into the shading model and then return the result. Materials are necessary for shading models, as it makes handling big piles of textures much easier.⤶ ``` Material m = GatherMaterial( i );⤶ // Always included at the end⤶ // ::Shade will return a final, shaded pixel using all textures we've included in material object.⤶ return ShadingModelStandard::Shade( i, m );⤶ ``` <upload src="653cb/8daa5101c74c705.png" size="77533" name="image.png" /> # Material⤶ ⤶ The following is an overview of the **Material** struct defined in `common/pixel.material.structs.hlsl`. It is included automatically by `common/pixel.hlsl`. ⤶ | Property | Type | Default Value | Notes |⤶ | --- | --- | --- | --- |⤶ | Albedo | float3 | (1.0, 1.0, 1.0) | |⤶ | Emission | float3 | (0.0, 0.0, 0.0) | |⤶ | Opacity | float | 1.0 | |⤶ | TintMask | float | 1.0 | |⤶ | Normal | float3 | (0.0, 0.0, 1.0) | The normal vector of the material in world space |⤶ | Roughness | float | 1.0 | |⤶ | Metalness | float | 0.0 | |⤶ | AmbientOcclusion | float3 | (1.0, 1.0, 1.0) | Can be normal AO or bent normal AO |⤶ | Sheen | float3 | (0.0, 0.0, 0.0) | |⤶ | SheenRoughness | float | 0.0 | |⤶ | Clearcoat | float | 0.0 | |⤶ | ClearcoatRoughness | float | 0.03 | |⤶ | ClearcoatNormal | float3 | (0.0, 0.0, 1.0) | |⤶ | Anisotropy | float | 0.0 | |⤶ | AnisotropyRotation | float3 | (1.0, 0.0, 0.0) | |⤶ | Thickness | float | 0.5 | |⤶ | SubsurfacePower | float | 12.234 | |⤶ | SheenColor | float3 | sqrt(baseColor) | |⤶ | SubsurfaceColor | float3 | (0.0, 0.0, 0.0) | |⤶ | Transmission | float3 | (1.0, 1.0, 1.0) | |⤶ | Absorption | float3 | (0.0, 0.0, 0.0) | |⤶ | IndexOfRefraction | float | 1.5 | |⤶ | MicroThickness | float | 0.0 | |⤶ ⤶ ## Shading Models⤶ ⤶ Different shading models may use different subsets of the properties available in the **Material** struct. ⤶ `Albedo`, `Emission`, `Opacity`, `TintMask`, `Normal`, `Roughness`, `Metalness`, and `AmbientOcclusion` are available across all shading models. ⤶ `Sheen`, `SheenRoughness`, `Clearcoat`, `ClearcoatRoughness`, `ClearcoatNormal`, `Anisotropy`, `AnisotropyRotation` are **unused by the standard shading model** at the time of writing. ⤶ | Shading Model | Thickness | Subsurface Power | Sheen Color | Subsurface Color | Transmission | Absorption | Index of Refraction | Micro Thickness |⤶ | --- | --- | --- | --- | --- | --- | --- | --- | --- |⤶ | Standard | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |⤶ | Subsurface | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |⤶ | Cloth | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |⤶ | Refraction | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ | # Custom Material Inputs⤶ ⤶ Sometimes you don't need automatically generated texture inputs, especially if your shader relies on lots of custom data that is not represented by any of the available PBR input maps. Exactly for these cases, material API allows "disabling" automatic setup and let the shader programmer do it manually. ⤶ To disable default texture inputs, add this definition: `#define CUSTOM_MATERIAL_INPUTS` in COMMON section, or right before `#include "common/pixel.hlsl"` in pixel shader block.⤶ ⤶ To initialize a material, you'll need to create a new material object using `Material::Init()`. Example: `Material m = Material::Init()`. ⤶ ⤶ ```⤶ PS ⤶ {⤶ // Do not generate texture inputs, let the developer do it themselves⤶ #define CUSTOM_MATERIAL_INPUTS⤶ #include "common/pixel.hlsl"⤶ ⤶ // <...>⤶ ```⤶ ⤶ After this, create new texture inputs and Texture2D objects for whatever you need the same way as you'd do it anywhere else:⤶ ⤶ ```⤶ PS⤶ {⤶ #define CUSTOM_MATERIAL_INPUTS⤶ #include "common/pixel.hlsl" ⤶ ⤶ // Albedo map⤶ CreateInputTexture2D( Color, Srgb, 8, "", "_color", "Material,10/10", Default3( 1.0, 1.0, 1.0 ) );⤶ Texture2D g_tColor < Channel( RGB, Box( Color ), Srgb ); OutputFormat( BC7 ); SrgbRead( true ); >;⤶ ⤶ // Amazing custom grayscale texture map ⤶ CreateInputTexture2D( Custom, Linear, 8, "", "_noise", "Material,10/20", Default( 1.0 ) );⤶ ⤶ // Normal map⤶ CreateInputTexture2D( Normal, Linear, 8, "NormalizeNormals", "_normal", "Material,10/20", Default3( 0.5, 0.5, 1.0 ) );⤶ ⤶ // Normal map has unused alpha channel, lets use it for our custom custom texture so we don't generate redundant compiled textures. Both maps don't need sRGB anyway.⤶ Texture2D g_tNormal < Channel( RGB, Box( Normal ), Linear ); Channel( A, Box( Custom ), Linear ); OutputFormat( DXT5 ); SrgbRead( false ); >; ⤶ // RMA (Roughness, Metalness, AO ) CreateInputTexture2D( Roughness, Linear, 8, "", "_rough", "Material,10/40", Default( 1 ) ); CreateInputTexture2D( Metalness, Linear, 8, "", "_metal", "Material,10/50", Default( 1 ) );⤶ CreateInputTexture2D( AmbientOcclusion, Linear, 8, "", "_rough", "Material,10/60", Default( 1 ) );⤶ Texture2D g_tRMA < Channel( R, Box( Roughness ), Linear ); Channel( G, Box( Metalness ), Linear ); Channel( B, Box( AmbientOcclusion ), Linear ); SrgbRead( false ); OutputFormat( BC7 ); >;⤶ ⤶ // <...>⤶ ```⤶ ⤶ And this is how they are going to be manually processed in pixel shader itself: ⤶ ```⤶ // <...> ⤶ ⤶ // Main function for Pixel Shader⤶ MainPs( PixelInput i ) : SV_Target0 ⤶ { ⤶ // Create a new empty material object⤶ Material m = Material::Init();⤶ ⤶ // Filling out the textures⤶ float3 rma = g_tRMA.Sample( g_sAniso, i.vTextureCoords.xy ).rgb;⤶ float4 normal = g_tNormal.Sample( g_sAniso, i.vTextureCoords.xy ).rgba;⤶ ⤶ // Lets multiply albedo by noise map that we stored in normal map alpha channel⤶ m.Albedo = g_tColor.Sample( g_sAniso, i.vTextureCoords.xy ) * normal.a;⤶ // !!! Custom material inputs mean that we must manually transform the normal map from tangent space to world space:⤶ m.Normal = TransformNormal( DecodeNormal( normal.rgb ), i.vNormalWs, i.vTangentVWs, i.vTangentUWs );⤶ m.Roughness = rma.r;⤶ m.Metalness = rma.g;⤶ m.AmbientOcclusion = rma.b;⤶ ⤶ // Shade the pixel & return it the same as anywhere else⤶ return ShadingModelStandard::Shade( i, m );⤶ }⤶ }⤶ ```⤶ ⤶ Please pay attention to the way we're storing normal map into the corresponding material slot. Before storing, we are decoding, then transforming this normal map from tangent space to world space. When custom inputs are disabled, material API will do it automatically, but when we are handling all textures by hand, this must be done manually, too. ⤶ ⤶ ## Transparency⤶ This isn't very related to material API, however if you're curious why `Opacity` input doesn't work with the example from above, it's because you need to directly change the render state in your code so shader knows it must be rendering transparency.⤶ ⤶ Above `MainPs` functiom, but below `#include "common/pixel.hlsl"`, add `RenderState( translucent, true )` and `RenderState( BlendEnable, true )`. After that, opacity will start affecting your model. ⤶ ⤶ If you need proper pixel sorting so layered transparent textures are rendering as intended, add `RenderState( AlphaToCoverageEnable, true )`. ⤶ ⤶ # Lerping⤶ Material API also has a little useful method if you want to blend two texture sets together with a given blend amount. It's called `Material::Lerp( Material a, Material b, float amount )`.⤶ ⤶ `amount` is a blend amount value: it can be anything in [0..1] range, (any value going lower or beyond this range will create funky visual errors). It can be a fixed number, or calculated weight of two blend masks - this is defined by user so you can put in there anything you need.⤶