glStencilFunc

glStencilFunc

Name

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

Delphi-Spezifikation

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

Parameter

func	Bestimmt die Funktion für den Stenciltest. Acht symbolische Namen werden akzeptiert: GL_NEVER, GL_LESS, GL_LEQUAL, GL_GREATER, GL_GEQUAL, GL_EQUAL, GL_NOTEQUAL, und GL_ALWAYS
ref	Gibt den Referenzwert für den Stenciltest an. ref ist auf das Intervall[0, 2^n-1] beschränkt, wobei n die Anzahl der Bitplanes im Schablonenpuffer angibt. Vorgabewert ist 0.
mask	Spezifiziert eine Maske die mit den Referenzwert und dem gespeicherten Wert UND-Verknüpft wird, nachdem der Test durchgeführt wurde. Vorgabewert ist eine mit einsen gefüllte Bitmaske.

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).

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, recith ein Aufruf von glEnable bzw. glEnable 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. Erlabut ist hier einer der acht Wert (siehe Liste weiter unten). ref ust ein Integer-Referenzwert, der im Stencilvergleiuch genutzt wird und auf den 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, und den Werten die an dem Vergleich teilnehmen.

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