You can read more about stencil-testing in the OpenGL wiki or OpenGL docs.
test : { ref : Basics.Int, mask : Basics.Int, test : Test, fail : Operation, zfail : Operation, zpass : Operation, writeMask : Basics.Int } -> WebGL.Settings.Setting
When you need to draw an intercection of two entities, e.g. a reflection in
the mirror, you can test against the stencil buffer, that has to be enabled
with stencil
option in toHtmlWith
.
Stencil test decides if the pixel should be drawn on the screen. Depending on the results, it performs one of the following operations on the stencil buffer:
fail
—the operation to use when the stencil test fails;zfail
—the operation to use when the stencil test passes, but the depth
test fails;zpass
—the operation to use when both the stencil test and the depth test
pass, or when the stencil test passes and there is no depth buffer or depth
testing is disabled.For example, draw the mirror Entity
on the screen and fill the stencil buffer
with all 1's:
test
{ ref = 1
, mask = 0xFF
, test = always -- pass for each pixel
, fail = keep -- noop
, zfail = keep -- noop
, zpass = replace -- write ref to the stencil buffer
, writeMask = 0xFF -- enable all stencil bits for writing
}
Crop the reflection Entity
using the values from the stencil buffer:
test
{ ref = 1
, mask = 0xFF
, test = equal -- pass when the stencil value is equal to ref = 1
, fail = keep -- noop
, zfail = keep -- noop
, zpass = keep -- noop
, writeMask = 0 -- disable writing to the stencil buffer
}
You can see the complete example here.
The Test
allows you to define how to compare the reference value
with the stencil buffer value, in order to set the conditions under which
the pixel will be drawn.
always -- Always pass
equal -- ref & mask == stencil & mask
never -- Never pass
less -- ref & mask < stencil & mask
greater -- ref & mask > stencil & mask
notEqual -- ref & mask != stencil & mask
lessOrEqual -- ref & mask <= stencil & mask
greaterOrEqual -- ref & mask >= stencil & mask
always : Test
equal : Test
never : Test
less : Test
greater : Test
notEqual : Test
lessOrEqual : Test
greaterOrEqual : Test
Defines how to update the value in the stencil buffer.
replace : Operation
Sets the stencil buffer value to ref
from the stencil test.
keep : Operation
Keeps the current stencil buffer value. Use this as a noop.
zero : Operation
Sets the stencil buffer value to 0.
increment : Operation
Increments the current stencil buffer value. Clamps to the maximum representable unsigned value.
decrement : Operation
Decrements the current stencil buffer value. Clamps to 0.
invert : Operation
Bitwise inverts the current stencil buffer value.
incrementWrap : Operation
Increments the current stencil buffer value. Wraps stencil buffer value to zero when incrementing the maximum representable unsigned value.
decrementWrap : Operation
Decrements the current stencil buffer value. Wraps stencil buffer value to the maximum representable unsigned value when decrementing a stencil buffer value of zero.
testSeparate : { ref : Basics.Int, mask : Basics.Int, writeMask : Basics.Int } -> { test : Test, fail : Operation, zfail : Operation, zpass : Operation } -> { test : Test, fail : Operation, zfail : Operation, zpass : Operation } -> WebGL.Settings.Setting
Different options for front and back facing polygons.