glStencilOp-Funktion

Die glStencilOp-Funktion legt die Schablonentestaktionen fest.

Syntax

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

Parameter

Fehler

Die Aktion, die ausgeführt werden soll, wenn der Schablonentest fehlschlägt. Die folgenden sechs symbolischen Konstanten werden akzeptiert.

Wert	Bedeutung
GL_KEEP	Behält den aktuellen Wert bei.
GL_ZERO	Legt den Wert des Schablonenpuffers auf Null fest.
GL_REPLACE	Legt den Wert des Schablonenpuffers auf ref fest, wie von glStencilFunc angegeben.
GL_INCR	Erhöht den aktuellen Schablonenpufferwert. Klemmt an den maximal darstellbaren unsignierten Wert.
GL_DECR	Verringert den aktuellen Schablonenpufferwert. Klammern auf 0.
GL_INVERT	Bitweise invertiert den aktuellen Schablonenpufferwert.

zfail

Schablonenaktion, wenn der Schablonentest erfolgreich ist, aber der Tiefentest fehlschlägt. Akzeptiert dieselben symbolischen Konstanten wie fail.

zpass

Schablonenaktion, wenn sowohl der Schablonentest als auch der Tiefentest bestanden oder wenn der Schablonentest erfolgreich ist und entweder kein Tiefenpuffer oder Tiefentest nicht aktiviert ist. Akzeptiert dieselben symbolischen Konstanten wie fail.

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	fail, zfail oder zpass war ein anderer Wert als die sechs definierten Konstantenwerte.
GL_INVALID_OPERATION	Die Funktion wurde zwischen einem Aufruf von glBegin und dem entsprechenden Aufruf von glEnd aufgerufen.

Bemerkungen

Die Schablonen, z. B. Z-Pufferung, aktiviert und deaktiviert das Zeichnen pro Pixel. Sie zeichnen mit OpenGL-Zeichnungsgrundtypen in die Schablonenebenen und rendern dann Geometrie und Bilder, indem Sie die Schablonenebenen verwenden, um Teile des Bildschirms zu maskieren. Die Schablone wird in der Regel in Algorithmen für das Rendering mit mehreren Pässen verwendet, um spezielle Effekte wie Decals, Umrungen und konstruktives Rendern von Vollkörpergeometrien zu erzielen.

Beim Schablonentest wird ein Pixel basierend auf dem Ergebnis eines Vergleichs zwischen dem Wert im Schablonenpuffer und einem Referenzwert bedingt eliminiert. Der Test wird mit glEnable - und glDisable-Aufrufen mit Argument GL_STENCIL_TEST aktiviert und mit glStencilFunc gesteuert.

Die glStencilOp-Funktion verwendet drei Argumente, die angeben, was mit dem gespeicherten Schablonenwert geschieht, während die Schablone aktiviert ist. Wenn der Schablonentest fehlschlägt, wird keine Änderung an den Farb- oder Tiefenpuffern des Pixels vorgenommen, und ein Fehler gibt an, was mit dem Inhalt des Schablonenpuffers geschieht.

Schablonenpufferwerte werden als ganze Zahlen ohne Vorzeichen behandelt. Bei Inkrementierung und Dekrementierung werden die Werte auf 0 und 2n 1 geklemmt, wobei n der durch Abfragen von GL_STENCIL_BITS zurückgegebene Wert ist.

Die beiden anderen Argumente für glStencilOp geben Schablonenpufferaktionen an, wenn nachfolgende Tiefenpuffertests erfolgreich (zpass) oder fehlschlagen (zfail). (Siehe glDepthFunc.) Sie werden mit den gleichen sechs symbolischen Konstanten wie fail angegeben. Beachten Sie, dass zfail ignoriert wird, wenn kein Tiefenpuffer vorhanden ist oder wenn der Tiefenpuffer nicht aktiviert ist. In diesen Fällen geben fail und zpass die Schablonenaktion an, wenn der Schablonentest fehlschlägt und erfolgreich ist.

Zunächst ist der Schablonentest deaktiviert. Wenn kein Schablonenpuffer vorhanden ist, kann keine Schablonenänderung erfolgen, und es ist so, als ob die Schablonentests unabhängig vom Aufruf von glStencilOp immer erfolgreich sind.

Die folgenden Funktionen rufen Informationen im Zusammenhang mit glStencilOp ab:

glGet mit argument GL_STENCIL_FAIL

glGet mit argument GL_STENCIL_PASS_DEPTH_PASS

glGet mit Argument GL_STENCIL_PASS_DEPTH_FAIL

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

Weitere Informationen

glAlphaFunc

glBegin

glBlendFunc

glDepthFunc

glEnable

glEnd

glIsEnabled

glLogicOp

glStencilFunc