love.graphics.stencil (日本語)

LÖVE 0.10.0 から使用可能

love.graphics.setStencilTest および love.graphics.setStencil から変更。

ステンシルとして幾何学的形状を描きます。

幾何学的形状はピクセルの色を設定する代わりに、与えられた関数へ不可視のピクセル値を設定することにより描画されます。 ステンシルバッファ (ステンシル値を有するもの) は、マスク / ステンシルのように機能させることができます。 ― love.graphics.setStencilTest は、以降の描画で各ピクセルにおいてステンシル値により、どのような影響を受けるのを決定するために使用することができます。

ステンシル値は [0, 255] の範囲内にある整数です。

version 11.0 より、ステンシル・バッファの設定、または Canvas でステンシルを用いるときは love.graphics.setCanvas で指定してください。この場合、 love.graphics.setCanvas{canvas, stencil=true} は自動作成された一時作業用のステンシル・バッファを用いるのに簡単な方法です。

関数

概要

love.graphics.stencil( stencilfunction, action, value, keepvalues )

引数

function stencilfunction

幾何学的形状を描画するための関数。ピクセルのステンシル値は、各ピクセルの色よりも幾何学的形状の影響を受けます。

StencilAction action ("replace")

ステンシル関数で描画されたものに接触しているピクセルに対して任意のステンシル値で変更する方法。

number value (1)

"replace" によるステンシルの動作で使用される場合にピクセルに対して使用される新規ステンシル値。その他のステンシルに対する動作には影響はありません。値の範囲は 0 から 255 までにする必要があります。

boolean keepvalues (false)

true ならばピクセルの古いステンシル値を保存しますが、 false ならばステンシル値の実行前に、全てのピクセルにステンシル値を 0 にして初期状態へ戻します。同様に love.graphics.clear (日本語) は全てのステンシル値に対して初期状態へ戻します。

返値

ありません。

注釈

ピクセルおよびステンシル値の同時描画は、ステンシル関数の内側で love.graphics.setColorMask を使用すると、全ての色の要素に対する描画は有効することで可能になります。

用例

長方形でマスクされた円を描画します

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

function love.draw()
    -- love.draw() 関数はステンシルとして長方形を描画します。長方形に接触している各ピクセルのステンシル値は 1 に設定されます。それ以外は 0 になります。
    love.graphics.stencil(myStencilFunction, "replace", 1)

   -- 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, 1, 0, 0.45)
    love.graphics.circle("fill", 500, 300, 150, 50)

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

    love.graphics.setStencilTest()
end

Image をステンシルマスクとして使用します

-- 白 / 黒色のマスク画像: 黒はマスクされますが、白はマスクされません。
local mask = love.graphics.newImage("mymask.png")

local mask_shader = love.graphics.newShader[[
   vec4 effect(vec4 color, Image texture, vec2 texture_coords, vec2 screen_coords) {
      if (Texel(texture, texture_coords).rgb == vec3(0.0)) {
         // 破棄されたピクセルをステンシルとして適用されません。
         discard;
      }
      return vec4(1.0);
   }
]]

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

function love.draw()
    love.graphics.stencil(myStencilFunction, "replace", 1)
    love.graphics.setStencilTest("greater", 0)
    love.graphics.rectangle("fill", 0, 0, 256, 256)
    love.graphics.setStencilTest()
end

複数の円が交差する部分以外を全て描画できるようにします

local function myStencilFunction()
   -- ステンシルとして 4 つ重なり合っている円を描画します。
   love.graphics.circle("fill", 200, 250, 100)
   love.graphics.circle("fill", 300, 250, 100)
   love.graphics.circle("fill", 250, 200, 100)
   love.graphics.circle("fill", 250, 300, 100)
end
 
function love.draw()
   -- 円ごとに接触している各ピクセルは 1 加算されているステンシル値を有しています。
   -- 円が重なり合っているピクセルのステンシル値は最低でも 2 です。
   love.graphics.stencil(myStencilFunction, "increment")
 
   -- 2 以下のステンシル値を有する領域のみ描画できるようにします。
   love.graphics.setStencilTest("less", 2)
 
   -- 大きい長方形を描画します。
   love.graphics.rectangle("fill", 0, 0, 500, 500)
 
   love.graphics.setStencilTest()
end

追加の用例は love.graphics.setStencilTest Wiki ページに掲載されています。

関連

• love.graphics (日本語)
• love.graphics.setStencilTest (日本語)
• love.graphics.clear (日本語)

そのほかの言語

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