elm-explorations / webgl / WebGL.Settings.StencilTest

You can read more about stencil-testing in the OpenGL wiki or OpenGL docs.

Stencil Test

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:

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.

Tests


type Test

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

Operations


type Operation

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.

Separate Test

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.