glStencilFunc-Funktion

Die glStencilFunc-Funktion legt die Funktion und den Referenzwert für Schablonentests fest.

Syntax

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

Parameter

func

Die Testfunktion. Die folgenden acht Token sind gültig.

Wert	Bedeutung
GL_NEVER	Immer ein Fehler.
GL_LESS	Übergibt if (Ref-Maske&) < (Schablonenmaske&).
GL_LEQUAL	Übergibt if (Ref-Maske&) = (Schablonenmaske&).
GL_GREATER	Übergibt if (Ref-Maske&) > (Schablonenmaske&).
GL_GEQUAL	Übergibt if (Ref-Maske&) = (Schablonenmaske&).
GL_EQUAL	Übergibt if (Ref-Maske&) = (Schablonenmaske&).
GL_NOTEQUAL	Besteht, wenn (Ref-Maske&) ? (Schablone&) mask).
GL_ALWAYS	Immer durch.

ref

Der Referenzwert für den Schablonentest. Der Ref-Parameter wird an den Bereich [0, 2n 1] geklemmt, wobei n die Anzahl der Bitebenen im Schablonenpuffer ist.

mask

Eine Maske, die anded ist und sowohl den Verweiswert als auch den gespeicherten Schablonenwert aufweist, wenn der Test abgeschlossen ist.

Rückgabewert

Diese Funktion gibt keinen Wert zurück.

Fehlercodes

Die folgenden Fehlercodes können von der glGetError-Funktion abgerufen werden.

Name	Bedeutung
GL_INVALID_ENUM	func war keiner der acht akzeptierten Werte.
GL_INVALID_OPERATION	Die Funktion wurde zwischen einem Aufruf von glBegin und dem entsprechenden Aufruf von glEnd aufgerufen.

Bemerkungen

Schablonen wie Z-Puffern aktivieren und deaktivieren das Zeichnen pro Pixel. Sie zeichnen in die Schablonenebenen mithilfe von OpenGL-Zeichnungsgrundtypen und rendern dann Geometrie und Bilder, indem Sie die Schablonenebenen verwenden, um Teile des Bildschirms zu maskieren. Schablonen werden in der Regel in Multipass-Renderingalgorithmen verwendet, um Spezialeffekte zu erzielen, z. B. Decals, Gliederungen und konstruktives Rendern von einfarbigen Geometrien.

Der Schablonentest eliminiert bedingt ein Pixel basierend auf dem Ergebnis eines Vergleichs zwischen dem Verweiswert und dem Wert im Schablonenpuffer. Der Test wird durch glEnable und glDisable mit argument GL_STENCIL_TEST aktiviert. Aktionen, die auf der Grundlage des Ergebnisses des Schablonentests durchgeführt werden, werden mit glStencilOp angegeben.

Der func-Parameter ist eine symbolische Konstante, die die Schablonenvergleichsfunktion bestimmt. Es akzeptiert einen der acht oben gezeigten Werte. Der Ref-Parameter ist ein ganzzahliger Verweiswert, der im Schablonenvergleich verwendet wird. Es wird auf den Bereich [0, 2n 1] geklemmt, wobei n die Anzahl der Bitebenen im Schablonenpuffer ist. Der Mask-Parameter ist bitweise ANDed mit dem Verweiswert und dem gespeicherten Schablonenwert, wobei die AND-Werteam Vergleich beteiligt sind.

Wenn schablone den Wert darstellt, der an der entsprechenden Schablonenpufferposition gespeichert ist, zeigt die obige Liste die Auswirkungen jeder Vergleichsfunktion, die von func angegeben werden kann. Nur wenn der Vergleich erfolgreich ist, wird das Pixel an die nächste Phase des Rasterisierungsprozesses übergeben (siehe glStencilOp). Alle Tests behandeln Schablonenwerte als ganze Zahlen ohne Vorzeichen im Bereich [0, 2n 1], wobei n die Anzahl der Bitebenen im Schablonenpuffer ist.

Zunächst ist der Schablonentest deaktiviert. Wenn kein Schablonenpuffer vorhanden ist, kann keine Schablonenänderung erfolgen, und es ist so, als ob der Schablonentest immer erfolgreich ist.

Die folgenden Funktionen rufen Informationen im Zusammenhang mit glStencilFunc ab:

glGet mit argument GL_STENCIL_FUNC

glGet mit Argument GL_STENCIL_VALUE_MASK

glGet mit argument GL_STENCIL_REF

glGet mit argument GL_STENCIL_BITS

glIsEnabled mit Argument GL_STENCIL_TEST

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Header	Gl.h
Bibliothek	Opengl32.lib
DLL	Opengl32.dll

Siehe auch

glAlphaFunc

glBegin

glBlendFunc

glDepthFunc

glEnable

glEnd

glIsEnabled

glLogicOp

glStencilOp