glStencilFunc.3gl

Name

  glStencilFunc	- set function and reference value for stencil testing

C Specification

  void glStencilFunc( GLenum func,
		      GLint ref,
		      GLuint mask )

Parameters

  func	Specifies the test function.  Eight tokens are valid: GL_NEVER,
	GL_LESS, GL_LEQUAL, GL_GREATER,	GL_GEQUAL, GL_EQUAL, GL_NOTEQUAL, and
	GL_ALWAYS.

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

  mask	Specifies a mask that is ANDed with both the reference value and the
	stored stencil value when the test is done.

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 reference value and the value in the stencil buffer.
  The test is enabled by glEnable and glDisable	with argument
  GL_STENCIL_TEST.  Actions taken based	on the outcome of the stencil test
  are specified	with glStencilOp.

  func is a symbolic constant that determines the stencil comparison
  function.  It	accepts	one of eight values, shown below.  ref is an integer
  reference value that is used in the stencil comparison.  It is clamped to
  the range [0,2n-1], where n is the number of bitplanes in the	stencil
  buffer.  mask	is bitwise ANDed with both the reference value and the stored
  stencil value, with the ANDed	values participating in	the comparison.

  If stencil represents	the value stored in the	corresponding stencil buffer
  location, the	following list shows the effect	of each	comparison function
  that can be specified	by func.  Only if the comparison succeeds is the
  pixel	passed through to the next stage in the	rasterization process (see
  glStencilOp).	 All tests treat stencil values	as unsigned integers in	the
  range	[0,2n-1], where	n is the number	of bitplanes in the stencil buffer.


  Here are the values accepted by func:

  GL_NEVER	    Always fails.

  GL_LESS	    Passes if ( ref & mask ) < ( stencil & mask ).

  GL_LEQUAL	    Passes if ( ref & mask ) <= ( stencil & mask ).

  GL_GREATER	    Passes if ( ref & mask ) > ( stencil & mask ).

  GL_GEQUAL	    Passes if ( ref & mask ) >= ( stencil & mask ).

  GL_EQUAL	    Passes if ( ref & mask ) = ( stencil & mask ).

  GL_NOTEQUAL	    Passes if ( ref & mask ) != ( stencil & mask ).

  GL_ALWAYS	    Always passes.

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 test always
  passes.

Errors

  GL_INVALID_ENUM is generated if func is not one of the eight accepted
  values.

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

Associated Gets

  glGet	with argument GL_STENCIL_FUNC
  glGet	with argument GL_STENCIL_VALUE_MASK
  glGet	with argument GL_STENCIL_REF
  glGet	with argument GL_STENCIL_BITS
  glIsEnabled with argument GL_STENCIL_TEST

See Also

  glAlphaFunc, glBlendFunc, glDepthFunc, glEnable, glIsEnabled,	glLogicOp,
  glStencilOp

Introduction | Alphabetic | Specification

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