# RenderPassShaderQuad

Class · extends [`RenderPass`](https://api.playcanvas.com/engine/classes/RenderPass.md) · category: Graphics

Source: https://github.com/playcanvas/engine/blob/64089771243fe28a9b9d2b4de538b99b07c75097/src/scene/graphics/render-pass-shader-quad.js#L136

A render pass which draws a quad with a shader into its render target. This is how most image
processing is done, such as post effects, blurs, or generating a texture, as the shader then
runs once for each pixel the quad covers. The pass creates the quad for its
[RenderPassShaderQuad#shader](https://api.playcanvas.com/engine/classes/RenderPassShaderQuad.md#shader), sets the render states, and draws the quad when it executes.
It can be used directly, by setting its shader, or as a base class of a pass which creates the
shader and sets its parameters. For a single draw, such as generating a texture once,
[drawQuadWithShader](https://api.playcanvas.com/engine/functions/drawQuadWithShader.md) draws a quad with a shader without setting up a pass.

## The shader

The vertex shader receives the corners of the quad in an attribute using
[SEMANTIC_POSITION](https://api.playcanvas.com/engine/variables/SEMANTIC_POSITION.md). The `quadVS` shader chunk implements it, and passes the uv
coordinates of the quad to the fragment shader in the `uv0` varying. Create the shader with
[ShaderUtils.createShader](https://api.playcanvas.com/engine/classes/ShaderUtils.md#createshader), with the fragment shader in both GLSL and WGSL, so the pass
works on both WebGL2 and WebGPU. The pass does not destroy its shader, as shaders are shared.

## The shader parameters

The textures and uniforms of the shader are set on the scope of the graphics device, see
[GraphicsDevice#scope](https://api.playcanvas.com/engine/classes/GraphicsDevice.md#scope). Resolve them once, when the pass is created, and set their values
in an override of [FramePass#execute](https://api.playcanvas.com/engine/classes/FramePass.md#execute), right before the quad is drawn by calling
`super.execute()`. Other passes can set parameters with the same names, so values set earlier
might not be the values the quad is drawn with.

## Render states and the drawn area

By default, the quad covers the whole render target, and is drawn without blending, depth test
or face culling, replacing what the render target contains. As the content is then not needed,
clearing the render target with [RenderPass#setClearColor](https://api.playcanvas.com/engine/classes/RenderPass.md#setclearcolor) saves loading it. To combine
the quad with the content instead, set a [RenderPassShaderQuad#blendState](https://api.playcanvas.com/engine/classes/RenderPassShaderQuad.md#blendstate), and to test
it against the depth or the stencil of the render target, set a
[RenderPassShaderQuad#depthState](https://api.playcanvas.com/engine/classes/RenderPassShaderQuad.md#depthstate) or the stencil parameters. To draw into a part of the
render target only, set its [RenderPassShaderQuad#viewport](https://api.playcanvas.com/engine/classes/RenderPassShaderQuad.md#viewport).

## Drawing several quads

To draw many quads which differ only by the data each reads for its index, such as sprites, set
[RenderPassShaderQuad#numInstances](https://api.playcanvas.com/engine/classes/RenderPassShaderQuad.md#numinstances) to draw them in a single instanced draw. To draw
several quads with different parameters, for example one for each light, override
[FramePass#execute](https://api.playcanvas.com/engine/classes/FramePass.md#execute), and for each quad set its parameters, or its viewport, and call
`super.execute()`, which draws it with the render states of the pass.

**Example**

```javascript
// A pass drawing a texture into its render target, multiplied by a color
class TintPass extends RenderPassShaderQuad {
    constructor(device, sourceTexture) {
        super(device);
        this.name = 'TintPass';
        this.sourceTexture = sourceTexture;
        this.tint = new Float32Array([1, 0.5, 0.5]);

        this.shader = ShaderUtils.createShader(device, {
            uniqueName: 'TintShader',
            attributes: { aPosition: SEMANTIC_POSITION },
            vertexChunk: 'quadVS',
            fragmentGLSL: `
                uniform sampler2D sourceTexture;
                uniform vec3 tint;
                varying vec2 uv0;

                void main() {
                    vec4 color = texture2D(sourceTexture, uv0);
                    gl_FragColor = vec4(color.rgb * tint, color.a);
                }
            `,
            fragmentWGSL: `
                var sourceTexture: texture_2d<f32>;
                var sourceTextureSampler: sampler;
                uniform tint: vec3f;
                varying uv0: vec2f;

                @fragment fn fragmentMain(input: FragmentInput) -> FragmentOutput {
                    var output: FragmentOutput;
                    let color = textureSample(sourceTexture, sourceTextureSampler, input.uv0);
                    output.color = vec4f(color.rgb * uniform.tint, color.a);
                    return output;
                }
            `
        });

        // resolve the shader parameters once
        this.sourceTextureId = device.scope.resolve('sourceTexture');
        this.tintId = device.scope.resolve('tint');
    }

    execute() {
        // set the parameters right before the quad is drawn
        this.sourceTextureId.setValue(this.sourceTexture);
        this.tintId.setValue(this.tint);
        super.execute();
    }
}

const pass = new TintPass(device, sourceTexture);
pass.init(renderTarget);

// the quad covers the whole render target, so clear it instead of loading its content
pass.setClearColor(Color.BLACK);
pass.render();
```

**Example**

```ts
// Use the pass directly, to draw a shader into a 256x256 tile of a texture atlas. The atlas
// is loaded and not cleared, so its other tiles keep their content.
const pass = new RenderPassShaderQuad(device);
pass.name = 'AtlasTile';
pass.shader = tileShader;
pass.init(atlasRenderTarget);

pass.viewport = new Vec4(256, 0, 256, 256);
pass.render();

// blend a second shader over the same tile
pass.shader = overlayShader;
pass.blendState = BlendState.ALPHABLEND;
pass.render();

pass.destroy();
```

## Properties

### blendState

```ts
blendState: BlendState = BlendState.NOBLEND
```

A blend state to use when rendering the quad. Defaults to [BlendState.NOBLEND](https://api.playcanvas.com/engine/classes/BlendState.md#noblend).

### cullMode

```ts
cullMode: number = CULLFACE_NONE
```

The cull mode to use when rendering the quad. Defaults to [CULLFACE_NONE](https://api.playcanvas.com/engine/variables/CULLFACE_NONE.md).

### depthState

```ts
depthState: DepthState = DepthState.NODEPTH
```

A depth state to use when rendering the quad. Defaults to [DepthState.NODEPTH](https://api.playcanvas.com/engine/classes/DepthState.md#nodepth).

### frontFace

```ts
frontFace: number = FRONTFACE_CCW
```

The front face to use when rendering the quad. Defaults to [FRONTFACE_CCW](https://api.playcanvas.com/engine/variables/FRONTFACE_CCW.md).

### numInstances

```ts
numInstances: number | undefined
```

The number of instances of the quad to draw, using instanced drawing, or undefined to draw a
single quad without instancing. Each instance can read its index, `gl_InstanceID` in GLSL
and `pcInstanceIndex` in WGSL, to fetch the data of its quad, for example to place it. Zero
draws nothing, while the pass still renders, so it still clears its render target.
Defaults to undefined.

### scissor

```ts
scissor: Vec4 | undefined
```

Optional scissor rectangle (x, y, width, height). If set, pixels outside this region are
discarded. Only used when viewport is also set. Defaults to the viewport if not specified.

### stencilBack

```ts
stencilBack: StencilParameters | null = null
```

Stencil parameters for back faces to use when rendering the quad. Defaults to null.

### stencilFront

```ts
stencilFront: StencilParameters | null = null
```

Stencil parameters for front faces to use when rendering the quad. Defaults to null.

### viewport

```ts
viewport: Vec4 | undefined
```

Optional viewport rectangle (x, y, width, height). If set, the quad renders only to this
region and the original viewport is restored after rendering.

## Accessors

### shader

```ts
get shader(): Shader | null
set shader(shader: Shader | null)
```

Gets the shader used to render the quad.

## Methods

### destroy

```ts
destroy(): void
```

Releases the resources used to render the quad. The shader is not destroyed, as shaders are
shared, for example between passes created with the same unique name.

### execute

```ts
execute(): void
```

Records the work of the pass. Called while the frame renders, between
[FramePass#before](https://api.playcanvas.com/engine/classes/FramePass.md#before) and [FramePass#after](https://api.playcanvas.com/engine/classes/FramePass.md#after), and only while
[FramePass#executeEnabled](https://api.playcanvas.com/engine/classes/FramePass.md#executeenabled) is true. For a [RenderPass](https://api.playcanvas.com/engine/classes/RenderPass.md), it runs inside the GPU
render pass, which starts right before it.

## Inherited from [RenderPass](https://api.playcanvas.com/engine/classes/RenderPass.md)

- `new RenderPassShaderQuad(graphicsDevice: GraphicsDevice)`
- `afterPasses: FramePass[] = []`
- `beforePasses: FramePass[] = []`
- `device: GraphicsDevice`
- `executeEnabled: boolean = true`
- `onAfter: ((pass: FramePass) => void) | null = null`
- `onBefore: ((pass: FramePass) => void) | null = null`
- `renderTarget: RenderTarget | null | undefined`
- `get enabled(): boolean` · `set enabled(value: boolean)`
- `get name(): string` · `set name(value: string)`
- `get resizeSource(): Texture | RenderTarget | null | undefined` · `set resizeSource(value: Texture | RenderTarget | null | undefined)`
- `get scaleX(): number` · `set scaleX(value: number)`
- `get scaleY(): number` · `set scaleY(value: number)`
- `after(): void`
- `before(): void`
- `frameUpdate(): void`
- `init(renderTarget?: RenderTarget | null, options?: object): void`
- `onDisable(): void`
- `onEnable(): void`
- `postInit(): void`
- `render(): void`
- `setClearColor(color: Color | undefined, index?: number): void`
- `setClearDepth(depthValue: number | undefined): void`
- `setClearStencil(stencilValue: number | undefined): void`
- `setGenerateMipmaps(generate: boolean, index?: number): void`
- `setStoreColor(store: boolean, index?: number): void`
- `setStoreDepth(store: boolean): void`
- `setStoreStencil(store: boolean): void`
