glGetActiveUniform

glGetActiveUniform

Name

glGetActiveUniform - Liefert Informationen über eine aktive Uniform-Variable im spezifizierten Programmobjekt

Delphi-Spezifikation

procedure glGetActiveUniform(program : GLuint; 
                             index : GLuint; 
                             bufSize : GLsizei;
                             length : PGLsizei; 
                             size : PGLint; 
                             type : PGLenum; 
                             name : PGLchar)

Parameter

program	Gibt das abzufragende Programmobjekt an.
index	Gibt den Index der Uniformvariable an, die abgefragt werden soll.
bufSize	Gibt die maximal Anzahl an Zeichen an, die OpenGL in den mit name bezeichneten Zeichenpuffer schreiben darf.
length	Liefert die Anzahl der Zeichen, die OpenGL in den mit name bezeichneten String geschrieben hat (ausschließlich der Null-Terminierung), wenn ein anderer Wart als nil angegeben wird.
size	Liefert die Größe der Uniformvariable.
type	Liefert den Datentyp der Uniformvariable.
name	Liefert einen null-terminierten String, der den Namen der Uniformvariable enthält.

Beschreibung

glGetActiveUniform liefert Informationen über eine aktive Uniformvariable im mit program spezifizierten Programmobjekt. Die Anzahl der aktiven Uniformvariablen kann man durch einen Aufruf von glGetProgram mit dem Argument GL_ACTIVE_PROGRAM. Für index 0 wird die erste aktive Uniformvariable ausgewählt. Zulässige Werte für index sind der Bereich 0 bis zur Anzahl der aktiven Uniformvariablen minus 1.

Shader können entweder Standard-Uniformvariablen, benutzerdefinierte Uniformvariablen oder beide verwenden. Standard-Uniformvariablen haben das Präfix "gl_" und referenzieren den existierenden OpenGL-State oder Werte, die von diesem State stammen (zum Beispiel gl_Fog, gl_ModelViewmatrix, etc., siehe die OpenGL-Shading-Language-Specification für eine komplette Liste). Benutzerdefinierte Uniformvariablen haben willkürliche Namen und erhalten ihre Werte aus der Anwendung durch Aufrufe von glUniform. Eine Uniformvariable (entweder Standard oder benutzerdefiniert) wird als aktiv angenommen, wenn sie durch das Linken bestimmt wurde und während der Ausführung des Programms auf sie zugegriffen wird. Deswegen sollte program vorher das Ziel eines Aufrufes von glLinkProgram gewesen sein, aber es ist nicht notwendig, dass erfolgreich gelinkt wurde.

Die benötigte Größe des Zeichenpuffers, um den längsten Uniformvariablenamen in program abzuspeichern, kann man durch einen Aufruf von glGetProgram mit dem Argument GL_ACTIVE_UNIFORM_MAX_LENGTH erhalten. Dieser Wert sollte verwendet werden, einen Puffer ausreichender Größe zu reservieren, um die ausgegebenen Uniformvariablennamen abzuspeichern. Die Größe dieses Zeichenpuffers wird in bufSize, ein Pointer zum Puffer in name angegeben.

glGetActiveUniform speichert den Namen der Uniformvariable, die durch index indiziert wird, in den mit name spezifizierten Zeichenpuffer. Der ausgegebene String ist null-terminiert. Die Anzahl der Zeichen - ausschließlich der Null-Terminierung, die in den Puffer gespeichert wurden, wird in length geschrieben. Wenn die Länge des ausgegebenen Strings nicht von Interesse ist, kann nil als length-Argument verwendet werden.

Das Argument typ gibt einen Pointer auf den Datentyp der Uniformvariable aus. Die symbolischen Konstanten GL_FLOAT, GL_FLOAT_VEC2, GL_FLOAT_VEC3, GL_FLOAT_VEC4, GL_INT, GL_INT_VEC2, GL_INT_VEC3, GL_INT_VEC4, GL_BOOL, GL_BOOL_VEC2, GL_BOOL_VEC3, GL_BOOL_VEC4, GL_FLOAT_MAT2, GL_FLOAT_MAT3, GL_FLOAT_MAT4, GL_SAMPLER_1D, GL_SAMPLER_2D, GL_SAMPLER_3D, GL_SAMPLER_CUBE, GL_SAMPLER_1D_SHADOW oder GL_SAMPLER_2D_SHADOW können zurückgeliefert werden.

Wenn ein oder mehr Elemente eines Arrays aktiv sind, wird der Name des Arrays nach name und der Typ nach type ausgegeben und der Parameter size liefert den höchsten verwendeten Array-Element-Index plus eins, der vom Compiler und/oder Linker bestimmt wurde. Nur eine aktive Uniformvariable kann für ein Uniform-Array ausgegeben werden.

Uniformvariablen, die als Strukturen oder Strukturenarrays deklariert sind, werden von dieser Funktion nicht direkt ausgegeben. Stattdessen wird jede dieser Uniformvariablen auf ihre ihre grundlegenden Komponenten - einschließlich der "." und "[]" Operatoren - reduziert, so dass jeder der Namen ein zulässiges Argument für glGetUniformLocation ist. Jede dieser reduzierten Uniformvariablen zählt als eine aktive Uniformvariable und wird einem Index zugewiesen. Ein zulässiger Name kann keine Struktur, kein Array von Strukturen oder eine Subkomponente eines Vektors oder einer Matrix sein.

Die Größe einer Uniformvariable wird nach size ausgegeben. Uniformvariablen - ausschließlich Arrays - haben die Größe 1. Strukturen und Strukturenarrays werden wie oben beschrieben reduziert, so dass jeder der ausgegebenen Namen ein Datentyp wie in obiger Liste ist. Wenn diese Reduzierung in einem Array resultiert, ist die ausgegene Größe wie für Uniformarrays beschrieben; anderenfalls ist die Größe 1.

Die Liste der aktiven Uniformvariablen kann sowohl Standard- (die mit dem Präfix "gl_" beginnen) als auch benutzerdefinierte Uniformvariablennamen enthalten.

Diese Funktion liefert so viele Informationen wie möglich über die angegebene aktive Uniformvariable. Wenn keine Informationen verfügbar sind, ist length 0 und name ein leerer String. Dieses Situation könnte auftreten, wenn diese Funktion nach einer fehlgeschlagenen Link-Operation aufgerufen wird. Wenn ein Fehler auftritt, bleiben die Werte length, size, type und name unangetastet.

Hinweise

glGetActiveUniform ist nur verfügbar, wenn die installierte OpenGL-Version größer gleich 2.0 ist.

Fehlermeldungen

GL_INVALID_VALUE wird generiert, wenn program kein von OpenGL erzeugter Wert ist.

GL_INVALID_OPERATION wird generiert, wenn program kein Programmobjekt ist.

GL_INVALID_VALUE wird generiert, wenn index größer oder gleich der Anzahl der aktiven Uniformvariablen in program ist.

GL_INVALID_OPERATION wird generiert, wenn glGetActiveUniform innerhalb eines glBegin-glEnd Blocks aufgerufen wird.

GL_INVALID_VALUE wird generiert, wenn bufSize kleiner 0 ist.

Zugehörige Wertrückgaben

glGet mit Token GL_MAX_VERTEX_UNIFORM_COMPONENTS

glGet mit Token GL_MAX_FRAGMENT_UNIFORM_COMPONENTS

glGetProgram mit Token GL_ACTIVE_UNIFORMS

glGetProgram mit Token GL_ACTIVE_UNIFORM_MAX_LENGTH

glIsProgram

Siehe auch

glGetUniform, glGetUniformLocation, glLinkProgram, glUniform, glUseProgram