Aktuelle Version vom 13. Oktober 2013, 00:12 Uhr

glStencilFunc

Name

glStencilFunc - setzt die Funktion und Referenzwerte für den Schablonentest. (Stenciltest)

Delphi-Spezifikation

procedure glStencilFunc(func: TGLenum; ref: TGLint; mask: TGLuint);

Parameter

Beschreibung

Stenciling (Schablonierung), ähnlich der Tiefenpufferung, erlaubt bzw. verhindert das Zeichnen auf einer Per-Pixel Basis. OpenGLs Renderprimitiven werden genutzt um in den Schablonenpuffer zu schreiben, der dann genutzt werden kann um bestimmte Teile des Bildschirms vor dem Rendern zu "schützen". Stenciling wird häufig beim Multipass-Rendern genutzt, um Spezialeffekte wie z.B. Decals ("Aufkleber", z.B. Schusslöcher, Blutflecken, etc.), Umrisse oder CSG (Constructive Solid Geometry = booleansche Zusammensetzung komplexer Objekte aus Grundkörpern) zu ermöglichen.

Der Stenciltest eliminiert Pixel je nach dem Ausgang eines Tests zwischen dem Referenzwert und dem bereits im Puffer abgelegtem Wert. Um diesen Test zu aktivieren bzw. zu deaktivieren, reicht ein Aufruf von glEnable bzw. glDisable mit dem Argument GL_STENCIL_TEST. Um eine Aktion auf Basis dieses Stenciltests festzulegen nutzt man glStencilOp.

func ist eine symbolische Konstante, die die Stencil-Vergleichsfunktion angibt. Erlaubt ist hier einer der acht Werte (siehe Liste weiter unten). ref ist ein Integer-Referenzwert, der im Stencilvergleich genutzt wird und auf das Intervall [0, 2^n-1] beschränkt wird, wobei n gleiche der Anzahl an Bitflächen im Stencilpuffer ist. mask wird bitweise sowohl mit dem Referenzwert als auch dem im Stencilpuffer abgelegtem Wert UND-verknüpft, wodurch die zu vergleichenden Werte erzeugt werden.

Wenn stencil den Wert an der entsprechenden Stelle im Stencilpuffer angibt, dann zeigt die folgende Liste den Effekt der einzelnen Vergleichsfunktionen, die über func gesetzt werden. Nur wenn ein Vergleich erfolgreich ist, wird der Pixel zur nächsten Stufe des Rasterisierungsprozesses durchgelassen (siehe glStencilOp). Alle Tests behandeln Stencilwerte als vorzeichenlose Integerwert im Intervall [0, 2^n-1], wobei n gleich der Zahl an Bitflächen im Stencilpuffer.

Parameter für func

GL_NEVER

Test wird niemals bestanden.

GL_LESS

Test wird bestanden wenn ( ref & mask) < ( stencil & mask).

GL_LEQUAL

Test wird bestanden wenn ( ref & mask) <= ( stencil & mask).

GL_GREATER

Test wird bestanden wenn ( ref & mask) > ( stencil & mask).

GL_GEQUAL

Test wird bestanden wenn ( ref & mask) >= ( stencil & mask).

GL_EQUAL

Test wird bestanden wenn ( ref & mask) = ( stencil & mask).

GL_NOTEQUAL

Test wird bestanden wenn ( ref & mask) <> ( stencil & mask).

GL_ALWAYS

Test wird immer bestanden.

Hinweise

Nach der Initialisierung ist der Stenciltest deaktiviert.
Wenn es keinen Stencilbuffer gibt, werden keine Modifikationen bezüglich des Buffers durchgeführt und der Stenciltest wird immer bestanden.

Falls beim PixelFormat dem Stecil Puffer nicht genügend Bits zugeordnet werden, kann es zu erheblichen Geschwindigkeits-Einbußen kommen.

Fehlermeldungen

GL_INVALID_ENUM wird generiert wenn func ein ungültiger(keiner der 8 genannten) Wert übergeben wird.
GL_INVALID_OPERATION wird generiert wenn glStencilFunc innerhalb eines glBegin-glEnd Blocks aufgerufen wird.

Zugehörige Wertrückgaben

glGet mit Token GL_STENCIL_FUNC
glGet mit Token GL_STENCIL_VALUE_MASK
glGet mit Token GL_STENCIL_REF
glGet mit Token GL_STENCIL_BITS
glIsEnabled mit Token GL_STENCIL_TEST

Siehe auch

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