Difference between revisions of "love.graphics.setStencilTest"

m
(Updated for latest API changes)
Line 1: Line 1:
 
{{newin|[[0.10.0]]|100|type=function|text=Together with [[love.graphics.stencil]], it has replaced [[love.graphics.setStencil]]}}
 
{{newin|[[0.10.0]]|100|type=function|text=Together with [[love.graphics.stencil]], it has replaced [[love.graphics.setStencil]]}}
−
Enables or disables stencil testing.
+
Configures 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 via [[love.graphics.stencil]].
+
When stencil testing is enabled, the geometry of everything that is drawn afterward will be clipped / stencilled out based on the arguments of this function compared with the stencil value of each pixel that the geometry touches. The stencil values of pixels are affected via [[love.graphics.stencil]].
  
−
Each [[Canvas]] has its own stencil buffer.
+
Each [[Canvas]] has its own stencil values.
 
== Function ==
 
== Function ==
 
=== Synopsis ===
 
=== Synopsis ===
 
<source lang="lua">
 
<source lang="lua">
−
love.graphics.setStencilTest( enable, invert )
+
love.graphics.setStencilTest( comparemode, comparevalue )
 
</source>
 
</source>
 
=== Arguments ===
 
=== Arguments ===
−
{{param|boolean|enable (false)|Whether to enable stencil testing.}}
+
{{param|CompareMode|comparemode|The type of comparison to make for each pixel.}}
−
{{param|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.}}
+
{{param|number|comparevalue|The value to use when comparing with the stencil value of each pixel. Must be between 0 and 255.}}
 
=== Returns ===
 
=== Returns ===
 
Nothing.
 
Nothing.
 +
 +
== Function ==
 +
Disables stencil testing.
 +
=== Synopsis ===
 +
<source lang="lua">
 +
love.graphics.setStencilTest( )
 +
</source>
 +
=== Arguments ===
 +
None.
 +
=== Returns ===
 +
Nothing.
 +
 
== Examples ==
 
== Examples ==
 
=== Drawing circles masked by a rectangle ===
 
=== Drawing circles masked by a rectangle ===
Line 23: Line 35:
  
 
function love.draw()
 
function love.draw()
−
     -- draw a rectangle to the stencil buffer
+
     -- 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)
+
     love.graphics.stencil(myStencilFunction, "replace", 1)
  
−
     -- enable testing against the contents of the stencil buffer
+
     -- enable testing against the stencil value of each pixel.
−
     love.graphics.setStencilTest(true)
+
     love.graphics.setStencilTest("greater", 0)
  
 
     love.graphics.setColor(255, 0, 0, 120)
 
     love.graphics.setColor(255, 0, 0, 120)
Line 38: Line 50:
 
     love.graphics.circle("fill", 400, 400, 150, 50)
 
     love.graphics.circle("fill", 400, 400, 150, 50)
  
−
     love.graphics.setStencilTest(false)
+
     love.graphics.setStencilTest()
 
end
 
end
 
</source>
 
</source>
Line 44: Line 56:
 
<source lang="lua">
 
<source lang="lua">
 
local function myStencilFunction()
 
local function myStencilFunction()
−
   -- Draw a small circle to the stencil buffer. This will be the hole.
+
   -- Draw a small circle as a stencil. This will be the hole.
 
   love.graphics.circle("fill", 400, 300, 50)
 
   love.graphics.circle("fill", 400, 300, 50)
 
end
 
end
  
 
function love.draw()
 
function love.draw()
−
   love.graphics.stencil(myStencilFunction)
+
  -- 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)
  
−
   -- invert the stencil test so anything touching the geometry drawn to the stencil buffer is not rendered.
+
   -- Configure the stencil test to only allow rendering on pixels whose stencil value is equal to 0.
−
   love.graphics.setStencilTest(true, true)
+
   love.graphics.setStencilTest("equal", 0)
 
   love.graphics.circle("fill", 400, 300, 150)
 
   love.graphics.circle("fill", 400, 300, 150)
−
   love.graphics.setStencilTest(false)
+
   love.graphics.setStencilTest()
 
end
 
end
 
</source>
 
</source>
Line 64: Line 77:
  
 
function love.draw()
 
function love.draw()
−
   love.graphics.stencil(myStencilFunction)
+
  -- 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)
  
−
   love.graphics.setStencilTest(true, false)
+
  -- Only allow rendering on pixels whose stencil value is greater than 0.
 +
   love.graphics.setStencilTest("greater", 0)
 
   love.graphics.setColor(155, 0, 128)
 
   love.graphics.setColor(155, 0, 128)
 
   love.graphics.polygon("fill", 400, 200, 486, 350, 314, 350)
 
   love.graphics.polygon("fill", 400, 200, 486, 350, 314, 350)
 
   
 
   
−
   love.graphics.setStencilTest(true, true)
+
  -- Now only allow rendering on pixels whose stencil value is equal to 0.
 +
   love.graphics.setStencilTest("equal", 0)
 
   love.graphics.setColor(144, 214, 128)
 
   love.graphics.setColor(144, 214, 128)
 
   love.graphics.polygon("fill", 400, 200, 486, 350, 314, 350)
 
   love.graphics.polygon("fill", 400, 200, 486, 350, 314, 350)
  
−
   love.graphics.setStencilTest(false)
+
   love.graphics.setStencilTest()
 
end
 
end
 
</source>
 
</source>
Line 85: Line 101:
 
* [[love.graphics.stencil]]
 
* [[love.graphics.stencil]]
 
[[Category:Functions]]
 
[[Category:Functions]]
−
{{#set:Description=Enables or disables stencil testing.}}
+
{{#set:Description=Configures or disables stencil testing.}}
 
{{#set:Sub-Category=State}}
 
{{#set:Sub-Category=State}}
 
== Other Languages ==
 
== Other Languages ==
 
{{i18n|love.graphics.setStencilTest}}
 
{{i18n|love.graphics.setStencilTest}}

Revision as of 02:51, 15 December 2015

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 the arguments of this function compared with the stencil value of each pixel that the geometry touches. The stencil values of pixels are affected via love.graphics.stencil.

Each Canvas has its own stencil values.

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 a rectangle

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)

    -- enable testing against the stencil value of each pixel.
    love.graphics.setStencilTest("greater", 0)

    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()
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.
   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(155, 0, 128)
   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(144, 214, 128)
   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


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

Retrieved from "http://www.love2d.org/w/index.php?title=love.graphics.setStencilTest&oldid=15673"