Material API

<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.
```
PS
{
	#include "common/pixel.hlsl"
	
	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 );
	}
}
```

# 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.

```
Material m = GatherMaterial( i );
```

<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 | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ |

Material API

Account Management

Special Pages

Wiki List

S&box Wiki