Difference between revisions of "love.graphics.setStencil"

m
m (Function)
 
(11 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{newin|[[0.8.0]]|080|type=function}}
+
{{newinoldin|[[0.8.0]]|080|[[0.10.0]]|100|type=function|text=It has been replaced by [[love.graphics.stencil]] and [[love.graphics.setStencilTest]]}}
 
Defines or releases a stencil for the drawing operations.
 
Defines or releases a stencil for the drawing operations.
  
The passed function draws to the stencil instead of the screen, creating an image with transparent and opaque pixel. While active, it is used to test where pixel will be drawn or discarded.<br>
+
The passed function draws to the stencil instead of the screen, creating an image with transparent and opaque pixels. While active, it is used to test where pixels will be drawn or discarded. Image contents do not directly affect the stencil, but see below for a workaround.
 +
 
 
Calling the function without arguments releases the active stencil.
 
Calling the function without arguments releases the active stencil.
 
== Function ==
 
== Function ==
Line 14: Line 15:
 
Nothing.
 
Nothing.
 
== Function ==
 
== Function ==
 +
Releases the active stencil.
 
=== Synopsis ===
 
=== Synopsis ===
 
<source lang="lua">
 
<source lang="lua">
Line 22: Line 24:
 
=== Returns ===
 
=== Returns ===
 
Nothing.
 
Nothing.
=== Notes ===
+
 
Releases the active stencil.
 
 
== Examples ==
 
== Examples ==
 
=== Drawing circles masked by a rectangle ===
 
=== Drawing circles masked by a rectangle ===
Line 31: Line 32:
 
end
 
end
  
myStencil = love.graphics.newStencil(myStencilFunction)
+
love.graphics.setStencil(myStencilFunction)
 
 
love.graphics.setStencil(myStencil)
 
  
 
love.graphics.setColor(255, 0, 0, 120)
 
love.graphics.setColor(255, 0, 0, 120)
Line 48: Line 47:
 
end
 
end
  
myStencil = love.graphics.newStencil(myStencilFunction)
+
love.graphics.setInvertedStencil(myStencilFunction)
 
 
love.graphics.setInvertedStencil(myStencil)
 
 
love.graphics.circle("fill", 400, 300, 150)
 
love.graphics.circle("fill", 400, 300, 150)
 
</source>
 
</source>
Line 59: Line 56:
 
end
 
end
  
myStencil = love.graphics.newStencil(myStencilFunction)
+
love.graphics.setStencil(myStencilFunction)
 
 
love.graphics.setStencil(myStencil)
 
 
love.graphics.setColor(155, 0, 128)
 
love.graphics.setColor(155, 0, 128)
love.graphics.triangle("fill", 400, 200, 486, 350, 314, 350)
+
love.graphics.polygon("fill", 400, 200, 486, 350, 314, 350)
  
  
love.graphics.setInvertedStencil(myStencil)
+
love.graphics.setInvertedStencil(myStencilFunction)
 
love.graphics.setColor(144, 214, 128)
 
love.graphics.setColor(144, 214, 128)
love.graphics.triangle("fill", 400, 200, 486, 350, 314, 350)
+
love.graphics.polygon("fill", 400, 200, 486, 350, 314, 350)
 
</source>
 
</source>
 +
=== Using an Image as a stencil mask ===
 +
<source lang="lua">
 +
-- a black/white mask image: black pixels will mask, white pixels will pass.
 +
local mask = love.graphics.newImage("mymask.png")
 +
 +
local mask_effect = love.graphics.newShader[[
 +
  vec4 effect (vec4 color, Image texture, vec2 texture_coords, vec2 screen_coords) {
 +
      if (Texel(texture, texture_coords).rgb == vec3(0.0)) {
 +
        // a discarded pixel wont be applied as the stencil.
 +
        discard;
 +
      }
 +
      return vec4(1.0);
 +
  }
 +
]]
 +
 +
function myStencilFunction()
 +
  love.graphics.setShader(mask_effect)
 +
  love.graphics.draw(mask, 0, 0)
 +
  love.graphics.setShader()
 +
end
 +
 +
love.graphics.setStencil(myStencilFunction)
 +
love.graphics.rectangle("fill", 0, 0, 256, 256)
 +
love.graphics.setStencil()
 +
</source>
 +
 
== See Also ==
 
== See Also ==
 
* [[parent::love.graphics]]
 
* [[parent::love.graphics]]
* [[parent::love.graphics.newStencil]]
+
* [[love.graphics.setInvertedStencil]]
* [[parent::love.graphics.setInvertedStencil]]
 
 
[[Category:Functions]]
 
[[Category:Functions]]
 
{{#set:Description=Defines or releases a stencil.}}
 
{{#set:Description=Defines or releases a stencil.}}
 
{{#set:Since=080}}
 
{{#set:Since=080}}
 +
{{#set:Sub-Category=State}}
 
== Other Languages ==
 
== Other Languages ==
 
{{i18n|love.graphics.setStencil}}
 
{{i18n|love.graphics.setStencil}}

Latest revision as of 04:07, 26 September 2016

Available since LÖVE 0.8.0 and removed in LÖVE 0.10.0
It has been replaced by love.graphics.stencil and love.graphics.setStencilTest.

Defines or releases a stencil for the drawing operations.

The passed function draws to the stencil instead of the screen, creating an image with transparent and opaque pixels. While active, it is used to test where pixels will be drawn or discarded. Image contents do not directly affect the stencil, but see below for a workaround.

Calling the function without arguments releases the active stencil.

Function

Synopsis

love.graphics.setStencil( stencilFunction )

Arguments

function stencilFunction
Function that draws the stencil.

Returns

Nothing.

Function

Releases the active stencil.

Synopsis

love.graphics.setStencil( )

Arguments

None.

Returns

Nothing.

Examples

Drawing circles masked by a rectangle

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

love.graphics.setStencil(myStencilFunction)

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)

Drawing a circle with a hole

myStencilFunction = function()
   love.graphics.circle("fill", 400, 300, 50)
end

love.graphics.setInvertedStencil(myStencilFunction)
love.graphics.circle("fill", 400, 300, 150)

Drawing two masked triangles with different colors

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

love.graphics.setStencil(myStencilFunction)
love.graphics.setColor(155, 0, 128)
love.graphics.polygon("fill", 400, 200, 486, 350, 314, 350)


love.graphics.setInvertedStencil(myStencilFunction)
love.graphics.setColor(144, 214, 128)
love.graphics.polygon("fill", 400, 200, 486, 350, 314, 350)

Using an Image as a stencil mask

-- a black/white mask image: black pixels will mask, white pixels will pass.
local mask = love.graphics.newImage("mymask.png")

local mask_effect = love.graphics.newShader[[
   vec4 effect (vec4 color, Image texture, vec2 texture_coords, vec2 screen_coords) {
      if (Texel(texture, texture_coords).rgb == vec3(0.0)) {
         // a discarded pixel wont be applied as the stencil.
         discard;
      }
      return vec4(1.0);
   }
]]

function myStencilFunction()
   love.graphics.setShader(mask_effect)
   love.graphics.draw(mask, 0, 0)
   love.graphics.setShader()
end

love.graphics.setStencil(myStencilFunction)
love.graphics.rectangle("fill", 0, 0, 256, 256)
love.graphics.setStencil()

See Also


Other Languages