Difference between revisions of "Program Introspection"

From OpenGL.org
Jump to: navigation, search
(Page for program introspection.)
 
(Old style: Data from GLSL Object page.)
Line 6: Line 6:
  
 
=== Attributes ===
 
=== Attributes ===
 +
 +
If a program has a [[Vertex Shader]], vertex shader inputs, aka [[Vertex Attribute]]s, can be queried. Vertex attributes can be active or inactive. Attributes that are unused are inactive; they do not have a binding. The number of active attributes in a program can be retrieved with {{apifunc|glGetProgram|iv}} with {{enum|GL_ACTIVE_ATTRIBUTES}}.
 +
 +
To retrieve information about an attribute, call this function:
 +
 +
  void {{apifunc|glGetActiveAttrib}}( GLuint {{param|program}}, GLuint {{param|index}}, GLsizei {{param|bufSize}}, GLsizei *{{param|length}}, GLint *{{param|size}}, GLenum *{{param|type}}, char *{{param|name}} );
 +
 +
The {{param|index}} is a number on the half-open range [0, {{enum|GL_ACTIVE_ATTRIBUTES}}); it represents a particular active attribute. {{param|name}} will be filled in with the name of the attribute; {{param|bufSize}} is the size of this character array. If {{param|length}} is not NULL, it will be filled in with the number of characters written to {{param|name}}. The {{param|size}} will be filled with the number of elements in the attribute array, if the attribute is an array type. Otherwise, it will be set to 1. The {{param|type}} will be set to the OpenGL enumeration for the GLSL type of the attribute.
 +
 +
To get the attribute location (the one used by {{apifunc|glVertexAttribPointer}}, not the {{param|index}} field used above), we use this function:
 +
 +
  GLint {{apifunc|glGetAttribLocation}}( GLuint {{param|program}}, const char *{{param|name}} );
 +
 +
If {{param|name}} is not an active attribute in {{param|program}}, the function will return -1.
  
 
=== Fragment Outputs ===
 
=== Fragment Outputs ===
 +
 +
[[Fragment_Shader#Output_buffers|Fragment color numbers]] and [[Fragment_Shader#Dual-source blending|indices]] can be queried with these functions:
 +
 +
  GLint {{apifunc|glGetFragDataLocation}}(GLuint {{param|program}}, const char * {{param|name}});
 +
  GLint {{apifunc|glGetFragDataIndex}}(GLuint {{param|program}}, const char * {{param|name}});
 +
 +
Note that you must provide a name for these functions. Unlike with attributes, the old-style query mechanism cannot be used to enumerate the names and properties of fragment shader outputs.
  
 
=== Uniforms and blocks ===
 
=== Uniforms and blocks ===
 +
 +
  
 
=== Subroutines ===
 
=== Subroutines ===

Revision as of 01:13, 5 October 2012

Program Introspection is a mechanism for taking a program object and querying information about it, so as to be able to interface and interact with it. For example, if there is a uniform, you may need to query its location so that you can set its value.

Old style

The APIs in this section represent an older interface to this information. If GL 4.3 or ARB_program_interface_query are not available, you should use these. Be advised that the new APIs provide access to more information than can be queried here.

Attributes

If a program has a Vertex Shader, vertex shader inputs, aka Vertex Attributes, can be queried. Vertex attributes can be active or inactive. Attributes that are unused are inactive; they do not have a binding. The number of active attributes in a program can be retrieved with glGetProgramiv with GL_ACTIVE_ATTRIBUTES.

To retrieve information about an attribute, call this function:

 void glGetActiveAttrib( GLuint program​, GLuint index​, GLsizei bufSize​, GLsizei *length​, GLint *size​, GLenum *type​, char *name​ );

The index​ is a number on the half-open range [0, GL_ACTIVE_ATTRIBUTES); it represents a particular active attribute. name​ will be filled in with the name of the attribute; bufSize​ is the size of this character array. If length​ is not NULL, it will be filled in with the number of characters written to name​. The size​ will be filled with the number of elements in the attribute array, if the attribute is an array type. Otherwise, it will be set to 1. The type​ will be set to the OpenGL enumeration for the GLSL type of the attribute.

To get the attribute location (the one used by glVertexAttribPointer, not the index​ field used above), we use this function:

 GLint glGetAttribLocation( GLuint program​, const char *name​ );

If name​ is not an active attribute in program​, the function will return -1.

Fragment Outputs

Fragment color numbers and indices can be queried with these functions:

 GLint glGetFragDataLocation(GLuint program​, const char * name​);
 GLint glGetFragDataIndex(GLuint program​, const char * name​);

Note that you must provide a name for these functions. Unlike with attributes, the old-style query mechanism cannot be used to enumerate the names and properties of fragment shader outputs.

Uniforms and blocks

Subroutines

Atomic counters

Interface query

Interface Query
Core in version 4.5
Core since version 4.3
Core ARB extension ARB_program_interface_query

This new interface provides a uniform mechanism for querying just about everything from a program. At least, you can query everything that external OpenGL code can interface with. You can't query information about number of functions (unless they're subroutines) or global variables or things like that. But uniforms, inputs/outputs, etc? All of those are made available through this consistent interface.