glStencilOp.3gl

Name

  glStencilOp -	set stencil test actions

C Specification

  void glStencilOp( GLenum fail,
		    GLenum zfail,
		    GLenum zpass )

Parameters

  fail	 Specifies the action to take when the stencil test fails.  Six
	 symbolic constants are	accepted: GL_KEEP, GL_ZERO, GL_REPLACE,
	 GL_INCR, GL_DECR, and GL_INVERT.

  zfail	 Specifies stencil action when the stencil test	passes,	but the	depth
	 test fails.  zfail accepts the	same symbolic constants	as fail.

  zpass	 Specifies 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 fail.

Description

  Stenciling, like z-buffering,	enables	and disables drawing on	a per-pixel
  basis.  You draw into	the stencil planes using GL drawing primitives,	then
  render geometry and images, using the	stencil	planes to mask out portions
  of the screen.  Stenciling is	typically used in multipass rendering
  algorithms to	achieve	special	effects, such as decals, outlining, and
  constructive solid geometry rendering.

  The stencil test conditionally eliminates a pixel based on the outcome of a
  comparison between the value in the stencil buffer and a reference value.
  The test is enabled with glEnable and	glDisable calls	with argument
  GL_STENCIL_TEST, and controlled with glStencilFunc.

  glStencilOp takes three arguments that indicate what happens to the stored
  stencil value	while stenciling is enabled.  If the stencil test fails, no
  change is made to the	pixel's	color or depth buffers,	and fail specifies
  what happens to the stencil buffer contents.	The six	possible actions are
  as follows:

  GL_KEEP	  Keeps	the current value.

  GL_ZERO	  Sets the stencil buffer value	to zero.

  GL_REPLACE	  Sets the stencil buffer value	to ref,	as specified by
		  glStencilFunc.

  GL_INCR	  Increments the current stencil buffer	value.	Clamps to the
		  maximum representable	unsigned value.

  GL_DECR	  Decrements the current stencil buffer	value.	Clamps to
		  zero.

  GL_INVERT	  Bitwise inverts the current stencil buffer value.

  Stencil buffer values	are treated as unsigned	integers.  When	incremented
  and decremented, values are clamped to 0 and 2n-1, where n is	the value
  returned by querying GL_STENCIL_BITS.

  The other two	arguments to glStencilOp specify stencil buffer	actions
  should subsequent depth buffer tests succeed (zpass) or fail (zfail).	 (See
  glDepthFunc.)	They are specified using the same six symbolic constants as
  fail.	 Note that zfail is ignored when there is no depth buffer, or when
  the depth buffer is not enabled.  In these cases, fail and zpass specify
  stencil action when the stencil test fails and passes, respectively.

Notes

  Initially the	stencil	test is	disabled.  If there is no stencil buffer, no
  stencil modification can occur and it	is as if the stencil tests always
  pass,	regardless of any call to glStencilOp.

Errors

  GL_INVALID_ENUM is generated if fail,	zfail, or zpass	is any value other
  than the six defined constant	values.

  GL_INVALID_OPERATION is generated if glStencilOp is executed between the
  execution of glBegin and the corresponding execution of glEnd.

Associated Gets

  glGet	with argument GL_STENCIL_FAIL
  glGet	with argument GL_STENCIL_PASS_DEPTH_PASS
  glGet	with argument GL_STENCIL_PASS_DEPTH_FAIL
  glGet	with argument GL_STENCIL_BITS
  glIsEnabled with argument GL_STENCIL_TEST

See Also

  glAlphaFunc, glBlendFunc, glDepthFunc, glEnable, glLogicOp, glStencilFunc

Introduction | Alphabetic | Specification

Last Edited: Fri Dec 6 11:18:03 EST 1996 by AFV
Look here for legal stuff: Legal