GrabPass is a command that creates a special type of Pass that grabs the contents of the frame buffer into a texture. This texture can be used in subsequent Passes to do advanced image based effects.
This command can significantly increase both CPU and GPU frame times. You should generally avoid using this command other than for quick prototyping, and attempt to achieve your effect in other ways. If you do use this command, try to reduce the number of screen grabbing operations as much as possible; either by reducing your usage of this command, or by using the signature that grabs the screen to a named texture if applicable.
| Feature name | Built-in Render PipelineA series of operations that take the contents of a Scene, and displays them on a screen. Unity lets you choose from pre-built render pipelines, or write your own. More info See in Glossary |
Universal Render Pipeline (URP) | High Definition Render Pipeline (HDRP) | Custom SRP |
|---|---|---|---|---|
| GrabPass | Yes | No | No | No |
Use this command in a SubShader block.
GrabPass works only on the frame buffer. You cannot use this command to grab the contents of other render targets, the depth bufferA memory store that holds the z-value depth of each pixel in an image, where the z-value is the depth for each rendered pixel from the projection plane. More info
See in Glossary, and so on.
Note that the two different signatures have different functionality, and different performance implications. Using a named texture can result in significantly fewer screen grabbing operations, which can reduce the impact of this resource-intensive command.
| Signature | Function |
|---|---|
GrabPass { } |
Grabs the frame buffer contents into a texture that you can use in subsequent Passes in the same SubShader. Reference the texture using the name _GrabTexture. When you use this signature, Unity grabs the screen every time it renders a batch that contains this command. This means that Unity can grab the screen multiple times per frame: once for each batch. |
GrabPass { "ExampleTextureName" } |
Grabs the frame buffer contents into a texture that you can access in subsequent Passes in the same frame, across multiple SubShaders. Reference the texture using the given name. When you use this signature, Unity grabs the screen the first time in a frame that it renders a batch that contains this command with a given texture name. |
This example for the Built-in Render Pipeline demonstrates using GrabPass to invert the colors of the render target. Note that this is not an efficient way to achieve this effect, and is intended only to demonstrate the use of GrabPass; the same effect could be achieved more efficiently using an invert blend mode.
Shader "GrabPassInvert"
{
SubShader
{
// Draw after all opaque geometry
Tags { "Queue" = "Transparent" }
// Grab the screen behind the object into _BackgroundTexture
GrabPass
{
"_BackgroundTexture"
}
// Render the object with the texture generated above, and invert the colors
Pass
{
CGPROGRAM
#pragma vertex vert
#pragma fragment frag
#include "UnityCG.cginc"
struct v2f
{
float4 grabPos : TEXCOORD0;
float4 pos : SV_POSITION;
};
v2f vert(appdata_base v) {
v2f o;
// use UnityObjectToClipPos from UnityCG.cginc to calculate
// the clip-space of the vertex
o.pos = UnityObjectToClipPos(v.vertex);
// use ComputeGrabScreenPos function from UnityCG.cginc
// to get the correct texture coordinate
o.grabPos = ComputeGrabScreenPos(o.pos);
return o;
}
sampler2D _BackgroundTexture;
half4 frag(v2f i) : SV_Target
{
half4 bgcolor = tex2Dproj(_BackgroundTexture, i.grabPos);
return 1 - bgcolor;
}
ENDCG
}
}
}