love.graphics.setStencilTest

Available since LÖVE 0.10.0

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

Enables or disables stencil testing.

When stencil testing is enabled, the geometry of everything that is drawn will be clipped / stencilled out based on whether it intersects with what has been previously drawn to the stencil buffer.

Each Canvas has its own stencil buffer.

Function

Synopsis

love.graphics.setStencilTest( enable, invert )

Arguments

boolean enable (false)

Whether to enable stencil testing.

boolean invert (false)

Whether to invert the stencil test. If true, the parts of drawn geometry that touch what has been previously drawn to the stencil buffer will be clipped. Otherwise everything else will be clipped.

Returns

Nothing.

Examples

Drawing circles masked by a rectangle

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

function love.draw()
    -- draw a rectangle to the stencil buffer
    love.graphics.stencil(myStencilFunction)

    -- enable testing against the contents of the stencil buffer
    love.graphics.setStencilTest(true)

    love.graphics.setColor(255, 0, 0, 120)
    love.graphics.circle("fill", 300, 300, 150, 50)

    love.graphics.setColor(0, 255, 0, 120)
    love.graphics.circle("fill", 500, 300, 150, 50)

    love.graphics.setColor(0, 0, 255, 120)
    love.graphics.circle("fill", 400, 400, 150, 50)

    love.graphics.setStencilTest(false)
end

Drawing a circle with a hole

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

function love.draw()
   love.graphics.stencil(myStencilFunction)

   -- invert the stencil test so anything touching the geometry drawn to the stencil buffer is not rendered.
   love.graphics.setStencilTest(true, true)
   love.graphics.circle("fill", 400, 300, 150)
   love.graphics.setStencilTest(false)
end

Drawing two masked triangles with different colors

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

function love.draw()
   love.graphics.stencil(myStencilFunction)

   love.graphics.setStencilTest(true, false)
   love.graphics.setColor(155, 0, 128)
   love.graphics.polygon("fill", 400, 200, 486, 350, 314, 350)
 
   love.graphics.setStencilTest(true, true)
   love.graphics.setColor(144, 214, 128)
   love.graphics.polygon("fill", 400, 200, 486, 350, 314, 350)

   love.graphics.setStencilTest(false)
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