Surface settings

Surface settings decide how the GPU renders a surface: whether it's opaque or transparent, how it blends with what's behind it, which faces are drawn, whether it casts shadows, and so on. You set them with attributes on the shader class.

[Shader]
[Surface(SurfacePreset.Transparent)]
[Blend(BlendPreset.Alpha)]
[Face(RenderFace.Both)]
public class Glass : ShaderScript.Lit { ... }

Fixed or per material

Each setting can be fixed by the shader or left to each material:

A specific value, such as SurfacePreset.Transparent, fixes the setting for every material that uses the shader. The setting isn't shown in the Material Inspector.
Override adds the setting to the Surface Options section of the Material Inspector, where each material chooses its own value, as with URP's and HDRP's Lit shaders.

// Every material chooses whether it's opaque or transparent, and how it blends.
[Surface(SurfacePreset.Override)]
[Blend(BlendPreset.Override)]

When the surface type is Override, blending, depth writing and alpha clipping also become per-material settings, unless the shader sets them with their own attributes.

Your code can check the resulting settings, for example IsTransparent or IsAlphaTestEnabled, as compile-time constants. See Compile-time switches.

The settings

Surface type

[Surface(SurfacePreset)]: Opaque (the default) or Transparent. Transparent surfaces are rendered after opaque ones and let what's behind them show through. A transparent surface also needs a blend mode, typically [Blend(BlendPreset.Alpha)].

Blending

[Blend(BlendPreset)] sets how the shader's output is combined with what's already on screen. With src for the shader's color, srcA for its alpha and dst for the color behind it:

Preset	Result	Use it for
`Off` (default)	`src`	Opaque surfaces.
`Alpha`	`src * srcA + dst * (1 - srcA)`	Standard transparency.
`Premultiply`	`src + dst * (1 - srcA)`	Colors already multiplied by alpha; keeps reflections visible on nearly transparent glass.
`Additive`	`src * srcA + dst`	Glows, fire and other light effects.
`Multiply`	`src * dst`	Tinting and darkening. On HDRP, Fullscreen shaders only.

For other combinations, pass the GPU blend factors directly, [Blend(BlendMode.One, BlendMode.One)], or separate factors for color and alpha. [BlendOp(BlendOp)] changes how the two weighted colors are combined: added (the default), subtracted, or their minimum or maximum.

Faces

[Face(RenderFace)]: Front (the default), Back or Both. Render both faces for thin, open geometry such as leaves, flags or cloth.

Alpha clipping

[AlphaClipping(AlphaClipMode)]: Off (the default) or On. Pixels whose OUT.alpha is below OUT.alphaClipThreshold (0.5 unless the shader sets it) are discarded, which cuts holes in the surface for leaves, fences and the like. Clipped surfaces cast correctly shaped shadows.

Depth

[ZWrite(ZWriteMode)] sets whether the surface writes its depth: Auto (the default) writes depth for opaque surfaces and doesn't for transparent ones; On and Off force it.

[ZTest(ZTestFunction)] sets the depth test, which decides whether a pixel is hidden by what's already been drawn. The default is the render pipeline's standard test. Always draws the object on top of everything drawn before it.

Shadows

[CastShadows(ShadowsCastMode)] sets whether objects with the shader cast shadows: Auto (the default for Lit shaders) casts them unless the material is transparent; Off is the default for Unlit shaders; On always casts them.

Emission

[Emission(EmissionMode)] sets whether the surface emits light. By default (Auto), emission is on when the shader writes OUT.emission. When emission is on, the Material Inspector also shows a Global Illumination setting, which controls whether the emitted light contributes to baked or realtime global illumination. Off turns emission off, and the compiler warns that OUT.emission is ignored.

URP-only settings

These attributes are in the Ahilevich.ShaderScript.Urp namespace and have no effect on HDRP. All of them apply to Lit shaders only.

Attribute	Effect
`[WorkflowMode(WorkflowMode)]`	`Metallic` (the default) reads `OUT.metallic`; `Specular` reads `OUT.specularColor`.
`[ReceiveShadows(ShadowsReceiveMode)]`	Whether the surface receives shadows. On by default.
`[SpecularHighlights(SpecularHighlightsMode)]`	Whether lights create highlights. Turning them off makes shading cheaper.
`[EnvironmentReflections(EnvironmentReflectionsMode)]`	Whether the surface reflects reflection probes and the sky. Turning them off makes shading cheaper.

HDRP-only settings, such as material types, clear coat, refraction, distortion and tessellation, are described in HDRP features.

Which kinds support which settings

Attribute	Lit	Unlit	Fullscreen
`Blend`, `BlendOp`, `ZTest`	✓	✓	✓
`Surface`, `Face`, `AlphaClipping`, `ZWrite`, `CastShadows`	✓	✓
`Emission`	✓	✓
URP: `WorkflowMode`, `ReceiveShadows`, `SpecularHighlights`, `EnvironmentReflections`	✓

Using a setting that the shader's kind doesn't support is reported as an error.

Table of Contents