OpenGL 1.1 Reference: glStencilFunc - Talisman

glStencilFunc: set function and reference value for stencil testing. C Specification | Parameters | Description | Notes | Errors | Associated Gets | See Also. [ ... glStencilFunc glStencilFunc:setfunctionandreferencevalueforstenciltesting. CSpecification| Parameters| Description| Notes| Errors| AssociatedGets| SeeAlso CSpecification voidglStencilFunc( GLenum func, GLint ref, GLuint mask) Parameters func Specifiesthetestfunction.Eighttokensarevalid: GL_NEVER,GL_LESS, GL_LEQUAL,GL_GREATER, GL_GEQUAL,GL_EQUAL, GL_NOTEQUAL,andGL_ALWAYS.Theinitial valueisGL_ALWAYS. ref Specifiesthereferencevalueforthestenciltest.ref isclampedtotherange[0,2n1],wherenisthe numberofbitplanesinthestencilbuffer.Theinitialvalueis0. mask SpecifiesamaskthatisANDedwithboththereferencevalueandthe storedstencilvaluewhenthetestisdone.Theinitialvalueisall1s. Description Stenciling,likedepth-buffering,enablesanddisablesdrawingonaper-pixel basis.YoudrawintothestencilplanesusingGLdrawingprimitives,then rendergeometryandimages,usingthestencilplanestomaskoutportionsof thescreen.Stencilingistypicallyusedinmultipassrenderingalgorithmsto achievespecialeffects,suchasdecals,outlining,andconstructivesolid geometryrendering. Thestenciltestconditionallyeliminatesapixelbasedontheoutcomeofa comparisonbetweenthereferencevalueandthevalueinthestencilbuffer. Toenableanddisablethetest,callglEnableandglDisablewithargument GL_STENCIL_TEST.Tospecifyactionsbasedontheoutcomeof thestenciltest,callglStencilOp. funcisasymbolicconstantthatdeterminesthestencil comparisonfunction.Itacceptsoneofeightvalues,showninthefollowing list.refisanintegerreferencevaluethatisusedinthe stencilcomparison.Itisclampedtotherange[0,2n 1],wherenisthe numberofbitplanesinthestencilbuffer.maskisbitwise andedwithboththereferencevalueandthestoredstencilvalue,with theandedvaluesparticipatinginthecomparison. Ifstencilrepresentsthevaluestoredinthecorresponding stencilbufferlocation,thefollowinglistshowstheeffectofeach comparisonfunctionthatcanbespecifiedbyfunc.Onlyif thecomparisonsucceedsisthepixelpassedthroughtothenextstageinthe rasterizationprocess(seeglStencilOp).Allteststreat stencilvaluesasunsignedintegersintherange[0, 2n1],where nisthenumberofbitplanesinthestencilbuffer. Thefollowingvaluesareacceptedbyfunc: GL_NEVER Alwaysfails. GL_LESS Passesif(ref&mask)< (stencil&mask). GL_LEQUAL Passesif(ref&mask) (stencil&mask). GL_GREATER Passesif(ref&mask)> (stencil&mask). GL_GEQUAL Passesif(ref&mask) (stencil&mask). GL_EQUAL Passesif(ref&mask)= (stencil&mask). GL_NOTEQUAL Passesif(ref&mask) (stencil&mask). GL_ALWAYS Alwayspasses. Notes Initially,thestenciltestisdisabled.Ifthereisnostencilbuffer,no stencilmodificationcanoccuranditisasifthestenciltestalwayspasses. Errors GL_INVALID_ENUMisgeneratediffuncis notoneoftheeightacceptedvalues. GL_INVALID_OPERATIONisgeneratedifglStencilFuncisexecutedbetween theexecutionofglBeginandthe correspondingexecutionofglEnd. AssociatedGets glGetwithargument GL_STENCIL_FUNC glGetwithargument GL_STENCIL_VALUE_MASK glGetwithargument GL_STENCIL_REF glGetwithargument GL_STENCIL_BITS glIsEnabledwithargument GL_STENCIL_TEST SeeAlso glAlphaFunc, glBlendFunc, glDepthFunc, glEnable, glIsEnabled, glLogicOp, glStencilOp