render.ClearBuffersObeyStencil

render.ClearBuffersObeyStencil( number red, number green, number blue, number alpha, boolean clearDepth )

Description

Tests every pixel of the active Render Target against the current Stencil configuration and sets the Color Channel values and, optionally, the Depth Buffer values for every pixel that passes.

For more detailed information on the Stencil system, including usage examples, see the Stencils Render Reference page

This function does not clear the Stencil Buffer on its own.
If you would like to clear the Stencil Buffer, you can use render.ClearStencil

Arguments

1 number red

The red Color Channel value for each pixel that is cleared.
Must be an integer value in the range 0-255 (byte)

2 number green

The green Color Channel value for each pixel that is cleared.
Must be an integer value in the range 0-255 (byte)

3 number blue

The blue Color Channel value for each pixel that is cleared.
Must be an integer value in the range 0-255 (byte)

4 number alpha

The alpha (translucency) Color Channel value for each pixel that is cleared.
Must be an integer value in the range 0-255 (byte)

5 boolean clearDepth

If true, reset the Depth Buffer values.

Example

Clearing a section of the screen via the stencil buffer (from Lex's Stencil Tutorial).

hook.Add( "PostDrawOpaqueRenderables", "Stencil Tutorial Example", function() -- Reset everything to known good render.SetStencilWriteMask( 0xFF ) render.SetStencilTestMask( 0xFF ) render.SetStencilReferenceValue( 0 ) render.SetStencilCompareFunction( STENCIL_ALWAYS ) render.SetStencilPassOperation( STENCIL_KEEP ) render.SetStencilFailOperation( STENCIL_KEEP ) render.SetStencilZFailOperation( STENCIL_KEEP ) render.ClearStencil() -- Enable stencils render.SetStencilEnable( true ) -- Set the reference value to 1. This is what the compare function tests against render.SetStencilReferenceValue( 1 ) -- Refuse to write things to the screen unless that pixel's value is 1 render.SetStencilCompareFunction( STENCIL_EQUAL ) -- Write a 1 to the centre third of the screen. Because we cleared it earlier, everything is currently 0 local w, h = ScrW() / 3, ScrH() / 3 local x_start, y_start = w, h local x_end, y_end = x_start + w, y_start + h render.ClearStencilBufferRectangle( x_start, y_start, x_end, y_end, 1 ) -- Tell the render library to clear the screen, but obeying the stencil test function. -- This means it will only clear the centre third. render.ClearBuffersObeyStencil( 0, 148, 133, 255, false ) -- Let everything render normally again render.SetStencilEnable( false ) end )

Output: