love.graphics.setStencilTest

Available since LÖVE 0.10.0

Together with love.graphics.stencil, it has replaced love.graphics.setStencil.

Configures or disables stencil testing.

When stencil testing is enabled, the geometry of everything that is drawn afterward will be clipped / stencilled out based on a comparison between the arguments of this function and the stencil value of each pixel that the geometry touches. The stencil values of pixels are affected via love.graphics.stencil.

Starting with version 11.0, a stencil buffer must be set or requested in love.graphics.setCanvas when using stencils with a Canvas. love.graphics.setCanvas{canvas, stencil=true} is an easy way to use an automatically provided temporary stencil buffer in that case.

Function

Synopsis

love.graphics.setStencilTest( comparemode, comparevalue )

Arguments

CompareMode comparemode

The type of comparison to make for each pixel.

number comparevalue

The value to use when comparing with the stencil value of each pixel. Must be between 0 and 255.

Returns

Nothing.

Function

Disables stencil testing.

Synopsis

love.graphics.setStencilTest( )

Arguments

None.

Returns

Nothing.

Examples

Drawing circles masked by rectangle, polygon and circle

local function myStencilFunction1()
	love.graphics.rectangle("fill", 225, 200, 350, 300)
end

local function myStencilFunction2()
	love.graphics.polygon ("fill", 225, 200, 400, 100, 575, 200)
end

local function myStencilFunction3()
	love.graphics.circle ("fill", 400, 200, 60)
end

function love.draw()
	
    -- draw a rectangle as a stencil. Each pixel touched by the rectangle will have its stencil value set to 1. The rest will be 0.
    love.graphics.stencil (myStencilFunction1, "replace", 1)
	
	-- draw polygon as a stencil. Each pixel touched by the polygon will have its stencil value set to 1. The rest will be not changed.
    love.graphics.stencil (myStencilFunction2, "replace", 2, true)
	
	-- remove circle from stencil. Each pixel touched by the circle will have its stencil value decrement to 1. The rest will be not changed.
    love.graphics.stencil (myStencilFunction3, "decrement", 1, true)

    -- Only allow rendering on pixels whose stencil value is greater than 0.
    love.graphics.setStencilTest ("greater", 0)

    love.graphics.setColor(1, 0, 0, 0.8)
    love.graphics.circle("fill", 300, 300, 150)

    love.graphics.setColor(0, 1, 0, 0.6)
    love.graphics.circle("fill", 500, 300, 150)

    love.graphics.setColor(0, 0, 1, 0.6)
    love.graphics.circle("fill", 400, 400, 150)
	
    love.graphics.setColor(1, 1, 1, 1)
    love.graphics.circle("fill", 400, 100, 117)

    love.graphics.setStencilTest()
end

Drawing a circle with a hole

local function myStencilFunction()
   -- Draw a small circle as a stencil. This will be the hole.
   love.graphics.circle("fill", 400, 300, 50)
end

function love.draw()
   -- Each pixel touched by the circle will have its stencil value set to 1. The rest will be 0.
   love.graphics.stencil(myStencilFunction, "replace", 1)

   -- Configure the stencil test to only allow rendering on pixels whose stencil value is equal to 0.
   -- This will end up being every pixel *except* ones that were touched by the circle drawn as a stencil.
   love.graphics.setStencilTest("equal", 0)
   love.graphics.circle("fill", 400, 300, 150)
   love.graphics.setStencilTest()
end

Drawing two masked triangles with different colors

local function myStencilFunction()
   love.graphics.circle("fill", 400, 300, 60, 25)
end

function love.draw()
   -- Each pixel touched by the circle will have its stencil value set to 1. The rest will be 0.
   love.graphics.stencil(myStencilFunction, "replace", 1)

   -- Only allow rendering on pixels whose stencil value is greater than 0.
   love.graphics.setStencilTest("greater", 0)
   love.graphics.setColor(0.6, 0, 0.5)
   love.graphics.polygon("fill", 400, 200, 486, 350, 314, 350)
 
   -- Now only allow rendering on pixels whose stencil value is equal to 0.
   love.graphics.setStencilTest("equal", 0)
   love.graphics.setColor(0.55, 0.85, 0.5)
   love.graphics.polygon("fill", 400, 200, 486, 350, 314, 350)

   love.graphics.setStencilTest()
end

The love.graphics.stencil wiki page includes more examples.

See Also

• love.graphics
• love.graphics.getStencilTest
• love.graphics.stencil

Other Languages

Dansk – Deutsch – English – Español – Français – Indonesia – Italiano – Lietuviškai – Magyar – Nederlands – Polski – Português – Română – Slovenský – Suomi – Svenska – Türkçe – Česky – Ελληνικά – Български – Русский – Српски – Українська – עברית – ไทย – 日本語 – 正體中文 – 简体中文 – Tiếng Việt – 한국어
More info