Vizard 7 » Command Index » Vizard objects » node3d » <node3d>.stencilFunc
7.7

<node3d>.stencilFunc

Sets the OpenGL stencil function of node

<node3d>.stencilFunc(  
stencil  
node = ''  
op = viz.OP_DEFAULT  
)  
stencil
A viz.StencilFunc object. See remarks for more details.
node = ''
Name of sub-node to apply changes to
op = viz.OP_DEFAULT
Can be viz.OP_DEFAULT to use the nodes default op mode or a combination of the following values:

Op modes

viz.OP_TRAVERSE

When performing an operation on a node, traverse the entire subgraph and process all subnodes as well. This is the default value.

viz.OP_OVERRIDE

When applying attributes, have them override attributes of subnodes.

viz.OP_ROOT

When performing an operation on the node, start at the root transform of the node, instead of the model. Processing the root will include all child Vizard nodes.

Remarks

This command is used to enable stencil operations when rendering the node. In order to use stencil operations, you must enable the stencil buffer.

The stencil buffer can be enabled by passing the viz.STENCIL_BUFFER flag to <viz>.go. This will ensure that a stencil buffer with at least 1-bit is allocated.

If you need a stencil buffer with more than 1 bit, then use the viz.display.stencil option before calling <viz>.go. For example, if you need an 8-bit stencil buffer, then you would use the following code:

viz.setOption('viz.display.stencil',8)
viz.go()

Depending on how you are using the stencil buffer, you might need to clear the stencil buffer at the beginning of every frame. By default, only the depth and color buffers are cleared. To enable the clearing of the stencil buffer, you will need to use the <window>.setClearMask command as follows:

viz.MainWindow.setClearMask(viz.GL_STENCIL_BUFFER_BIT,viz.MASK_ADD)

The viz.StencilFunc object contains the following attributes for controlling the stencil operation:

Attribute

Description

func

Specifies the test function. Eight symbolic constants are valid: viz.GL_NEVER, viz.GL_LESS, viz.GL_LEQUAL, viz.GL_GREATER, viz.GL_GEQUAL, viz.GL_EQUAL, viz.GL_NOTEQUAL, and viz.GL_ALWAYS. The initial value is viz.GL_ALWAYS.

funcRef

Specifies the reference value for the stencil test. The value is clamped to the range 0 2 n - 1 , where n is the number of bitplanes in the stencil buffer. The initial value is 0.

funcMask

Specifies a mask that is ANDed with both the reference value and the stored stencil value when the test is done. The initial value is all 1's.

sfail

Specifies the action to take when the stencil test fails. Eight symbolic constants are accepted: viz.GL_KEEP, viz.GL_ZERO, viz.GL_REPLACE, viz.GL_INCR, viz.GL_INCR_WRAP, viz.GL_DECR, viz.GL_DECR_WRAP, and viz.GL_INVERT. The initial value is viz.GL_KEEP.

zfail

Specifies the stencil action when the stencil test passes, but the depth test fails. zfail accepts the same symbolic constants as sfail. The initial value is viz.GL_KEEP.

zpass

Specifies the stencil action when both the stencil test and the depth test pass, or when the stencil test passes and either there is no depth buffer or depth testing is not enabled. zpass accepts the same symbolic constants as sfail. The initial value is viz.GL_KEEP.

writeMask

Specifies a bit mask to enable and disable writing of individual bits in the stencil planes. Initially, the mask is all 1's.



The viz.StencilFunc object also contains the following static methods for creating the object with commonly used settings:

Method

Description

RenderMask(mask=1)

Writes the specified mask value to the stencil buffer wherever the node is rendered.

RenderInsideMask(mask=1)

Only renders the node wherever any of the specified mask bits are set.

RenderOutsideMask(mask=1)

Only renders the node wherever none of the specified mask bits are set.



For more information about how these parameters work, see the OpenGL documentation for glStencilFunc, glStencilOp, and glStencilMask.

Return Value

None

Example

import viz
import vizshape

#Request stencil buffer with at least 1 bit
viz.setOption('viz.display.stencil',1)
viz.go()

#Clear stencil buffer every frame
viz.MainWindow.setClearMask(viz.GL_STENCIL_BUFFER_BIT,viz.MASK_ADD)

#Add invisible doorway that renders the stencil mask
door = viz.addTexQuad(pos=(0,0,-2),scale=(2,3,1),align=viz.ALIGN_CENTER_BOTTOM)
door.stencilFunc(viz.StencilFunc.RenderMask())
door.disable([viz.COLOR_WRITE,viz.DEPTH_WRITE])
door.enable(viz.CULL_FACE)

#Give door negative draw order to ensure mask is rendered before other models
door.drawOrder(-1)

#Add model that render inside stencil mask
model = viz.addChild('gallery.osgb')
model.stencilFunc(viz.StencilFunc.RenderInsideMask())
model.clipPlane([0,0,1,-2]) #Clip model at location of door

#Add grid plane that renders outside stencil mask
grid = vizshape.addGrid(color=[0.2]*3)
grid.stencilFunc(viz.StencilFunc.RenderOutsideMask())

#Add model that renders regardless of mask
male = viz.add('vcc_male2.cfg',euler=(180,0,0),pos=(0,0,4))
male.state(1)

viz.clearcolor(viz.GRAY)
viz.MainView.move(0,0,-10)