{{newin|[[0.10.0]]|100|type=function|text=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]].


{{notice|1=Starting with version [[11.0]], a stencil buffer must be set or requested in [[love.graphics.setCanvas]] when using stencils with a Canvas. <code>love.graphics.setCanvas{canvas, stencil=true}</code> is an easy way to use an automatically provided temporary stencil buffer in that case.}}
== Function ==
=== Synopsis ===
<source lang="lua">
love.graphics.setStencilTest( comparemode, comparevalue )
</source>
=== Arguments ===
{{param|CompareMode|comparemode|The type of comparison to make for each pixel.}}
{{param|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 ===
<source lang="lua">
love.graphics.setStencilTest( )
</source>
=== Arguments ===
None.
=== Returns ===
Nothing.

== Examples ==
=== Drawing circles masked by a rectangle ===
<source lang="lua">
local function myStencilFunction()
   love.graphics.rectangle("fill", 225, 200, 350, 300)
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(myStencilFunction, "replace", 1)

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

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

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

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

    love.graphics.setStencilTest()
end
</source>

=== Drawing a circle with a hole ===
<source lang="lua">
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
</source>

=== Drawing two masked triangles with different colors ===
<source lang="lua">
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
</source>

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

== See Also ==
* [[parent::love.graphics]]
* [[love.graphics.getStencilTest]]
* [[love.graphics.stencil]]
[[Category:Functions]]
{{#set:Description=Configures or disables stencil testing.}}
{{#set:Sub-Category=State}}
== Other Languages ==
{{i18n|love.graphics.setStencilTest}}