OooglesOoogles Units Class Hierarchy Classes, Interfaces, Objects and Records Types Variables Constants Functions and Procedures Identifiers License |
record TGLProgram
Unit
Neslib.Ooogles
Declaration
type TGLProgram = record
Description
A program that combines a vertex shader and a fragment shader.
Overview
Methods
Properties
property Handle: GLuint read FHandle; |
Description
Methods
procedure New; overload; inline; |
procedure New(const AVertexShader, AFragmentShader: TGLShader); overload; inline; |
|
Creates a program object.
A program object is an object to which shader objects can be attached. This provides a mechanism to specify the shader objects that will be linked to create a program. It also provides a means for checking the compatibility of the shaders that will be used to create a program (for instance, checking the compatibility between a vertex shader and a fragment shader). When no longer needed as part of a program object, shader objects can be detached.
One or more executables are created in a program object by successfully attaching shader objects to it with AttachShader, successfully compiling the shader objects with TGLShader.Compile, and successfully linking the program object with Link. These executables are made part of current state when Use is called. Program objects can be deleted by calling Delete. The memory associated with the program object will be deleted when it is no longer part of current rendering state for any context.
Note: like texture objects, the name space for program objects may be shared across a set of contexts, as long as the server sides of the contexts share the same address space. If the name space is shared across contexts, any attached objects and the data associated with those attached objects are shared as well.
Note: applications are responsible for providing the synchronization across API calls when objects are accessed from different execution threads.
OpenGL API: glCreateProgram
Parameters
- AVertexShader
- (optional) vertex shader to attach.
- AFragmentShader
- (optional) fragment shader to attach.
See also
- TGLShader
- A vertex or fragment shader
- TGLVertexAttrib
- Represents a single vertex attribute in a TGLProgram.
- TGLUniform
- Represents a uniform in a TGLProgram.
- AttachShader
- Attach a shader object to the program.
- DetachShader
- Detach a shader object from a program object.
- Link
- Links the program.
- Use
- Installs the program object as part of current rendering state.
- Validate
- Validates the program.
|
procedure Delete; inline; |
|
Deletes the program. This frees the memory and invalidates the name associated with the program object specified by program. This command effectively undoes the effects of a call to New.
If a program object is in use as part of current rendering state, it will be flagged for deletion, but it will not be deleted until it is no longer part of current state for any rendering context. If a program object to be deleted has shader objects attached to it, those shader objects will be automatically detached but not deleted unless they have already been flagged for deletion by a previous call to TGLShader.Delete.
To determine whether a program object has been flagged for deletion, call IsFlaggedForDeletion.
OpenGL API: glDeleteProgram
See also
- New
- DetachShader
- Detach a shader object from a program object.
- Use
- Installs the program object as part of current rendering state.
|
procedure AttachShader(const AShader: TGLShader); inline; |
|
Attach a shader object to the program.
In order to create an executable, there must be a way to specify the list of things that will be linked together. Program objects provide this mechanism. Shaders that are to be linked together in a program object must first be attached to that program object. This method attaches the shader object specified by AShader to the program. This indicates that shader will be included in link operations that will be performed on program.
All operations that can be performed on a shader object are valid whether or not the shader object is attached to a program object. It is permissible to attach a shader object to a program object before source code has been loaded into the shader object or before the shader object has been compiled. Multiple shader objects of the same type may not be attached to a single program object. However, a single shader object may be attached to more than one program object. If a shader object is deleted while it is attached to a program object, it will be flagged for deletion, and deletion will not occur until DetachShader is called to detach it from all program objects to which it is attached.
OpenGL API: glAttachShader
Parameters
- AShader
- the shader object to be attached.
Exceptions raised
TGLError.InvalidOperation- if AShader is already attached to the program, or if another shader object of the same type as shader is already attached to the program.
See also
- GetAttachedShaders
- Return the shader objects attached to the program.
- TGLShader.Compile
- Compiles the shader;
Note: in DEBUG mode, any compiler warnings will be output to the debug console.
- DetachShader
- Detach a shader object from a program object.
- Link
- Links the program.
- TGLShader.SetSource
- Set or replace the source code in a shader object.
|
procedure AttachShaders(const AVertexShader, AFragmentShader: TGLShader); inline; |
|
Attaches a vertex shader and fragment shader in a single call.
This method is just a shortcut for calling AttachShader twice.
Parameters
- AVertexShader
- the vertex shader to attach.
- AFragmentShader
- the fragment shader to attach.
|
procedure DetachShader(const AShader: TGLShader); inline; |
|
Detach a shader object from a program object.
This command can be used to undo the effect of the command AttachShader.
If shader has already been flagged for deletion by a call to TGLShader.Delete and it is not attached to any other program object, it will be deleted after it has been detached.
OpenGL API: glDetachShader
Parameters
- AShader
- the shader object to be dettached.
Exceptions raised
TGLError.InvalidOperation- if AShader is not attached to this program.
See also
- GetAttachedShaders
- Return the shader objects attached to the program.
- AttachShader
- Attach a shader object to the program.
|
function GetAttachedShaders: TArray<TGLShader>; inline; |
|
Return the shader objects attached to the program.
OpenGL API: glGetAttachedShaders
Returns
An array of attached shaders. See also
- AttachShader
- Attach a shader object to the program.
- DetachShader
- Detach a shader object from a program object.
|
function Link: Boolean; |
|
Links the program.
A shader object of type TGLShaderType.Vertex attached to program is used to create an executable that will run on the programmable vertex processor. A shader object of type TGLShaderType.Fragment attached to program is used to create an executable that will run on the programmable fragment processor.
As a result of a successful link operation, all active user-defined uniform variables belonging to program will be initialized to 0, and each of the program object's active uniform variables can be accessed using TGLUniform. Also, any active user-defined attribute variables that have not been bound to a generic vertex attribute index will be bound to one at this time.
Linking of a program object can fail for a number of reasons as specified in the OpenGL ES Shading Language Specification. This will result in a EGLShaderError exception (in DEBUG mode). The following lists some of the conditions that will cause a link error.
A vertex shader and a fragment shader are not both present in the program object. The number of active attribute variables supported by the implementation has been exceeded. The storage limit for uniform variables has been exceeded. The number of active uniform variables supported by the implementation has been exceeded. The main function is missing for the vertex shader or the fragment shader. A varying variable actually used in the fragment shader is not declared in the same way (or is not declared at all) in the vertex shader. A reference to a function or variable name is unresolved. A shared global is declared with two different types or two different initial values. One or more of the attached shader objects has not been successfully compiled (via TGLShader.Compile). Binding a generic attribute matrix caused some rows of the matrix to fall outside the allowed maximum number of vertex attributes. Not enough contiguous vertex attribute slots could be found to bind attribute matrices.
When a program object has been successfully linked, the program object can be made part of current state by calling Use.
This method will also install the generated executables as part of the current rendering state if the link operation was successful and the specified program object is already currently in use as a result of a previous call to Use. If the program object currently in use is relinked unsuccessfully, its link status will be set to False, but the executables and associated state will remain part of the current state until a subsequent call to Use removes it from use. After it is removed from use, it cannot be made part of current state until it has been successfully relinked.
After the link operation, applications are free to modify attached shader objects, compile attached shader objects, detach shader objects, delete shader objects, and attach additional shader objects. None of these operations affects the information log or the program that is part of the program object.
Note: if the link operation is unsuccessful, any information about a previous link operation on program is lost (i.e., a failed link does not restore the old state of program). Certain information can still be retrieved from program even after an unsuccessful link operation.
OpenGL API: glLinkProgram, glGetProgramInfoLog, glGetProgramiv(GL_LINK_STATUS/GL_INFO_LOG_LENGTH)
Returns
In RELEASE mode: True on success, False on failure. In DEBUG mode: True on success or an EGLError exception will be raised on failure. Exceptions raised
- EGLShaderError
- when the shaders cannot be linked.
See also
- TGLVertexAttrib
- Represents a single vertex attribute in a TGLProgram.
- TGLUniform
- Represents a uniform in a TGLProgram.
- GetAttachedShaders
- Return the shader objects attached to the program.
- AttachShader
- Attach a shader object to the program.
- TGLShader.Compile
- Compiles the shader;
Note: in DEBUG mode, any compiler warnings will be output to the debug console.
- New
- Delete
- Deletes the program.
- DetachShader
- Detach a shader object from a program object.
- Use
- Installs the program object as part of current rendering state.
- Validate
- Validates the program.
|
function Validate: Boolean; |
|
Validates the program.
This method checks to see whether the executables contained in program can execute given the current OpenGL state. The validation information (exception message) may consist of an empty string, or it may be a string containing information about how the current program object interacts with the rest of current OpenGL state. This provides a way for OpenGL implementers to convey more information about why the current program is inefficient, suboptimal, failing to execute, and so on.
If validation is successful, the program is guaranteed to execute given the current state. Otherwise, the program is guaranteed to not execute.
This function is typically useful only during application development. The informational string stored in the exception message is completely implementation dependent; therefore, an application should not expect different OpenGL implementations to produce identical information strings.
Note: this function mimics the validation operation that OpenGL implementations must perform when rendering commands are issued while programmable shaders are part of current state. The error TGLError.InvalidOperation will be generated by gl.DrawArrays or gl.DrawElements if any two active samplers in the current program object are of different types, but refer to the same texture image unit.
Note: it may be difficult or cause a performance degradation for applications to catch these errors when rendering commands are issued. Therefore, applications are advised to make calls to Validate to detect these issues during application development.
OpenGL API: glValidateProgram, glGetProgramInfoLog, glGetProgramiv(GL_VALIDATE_STATUS/GL_INFO_LOG_LENGTH)
Returns
In RELEASE mode: True on success, False on failure. In DEBUG mode: True on success or an EGLError exception will be raised on failure. Exceptions raised
- EGLShaderError
- with any validation errors.
See also
- Link
- Links the program.
- Use
- Installs the program object as part of current rendering state.
|
procedure Use; inline; |
|
Installs the program object as part of current rendering state.
Executables for each stage are created in a program object by successfully attaching shader objects to it with AttachShader, successfully compiling the shader objects with Compile, and successfully linking the program object with Link.
A program object will contain executables that will run on the vertex and fragment processors if it contains one shader object of type TGLShaderType.Vertex and one shader object of type TGLShaderType.Fragment that have both been successfully compiled and linked.
While a program object is in use, applications are free to modify attached shader objects, compile attached shader objects, attach shader objects, and detach or delete shader objects. None of these operations will affect the executables that are part of the current state. However, relinking the program object that is currently in use will install the program object as part of the current rendering state if the link operation was successful (see Link). If the program object currently in use is relinked unsuccessfully, its link status will be set to False, but the executables and associated state will remain part of the current state until a subsequent call to Use removes it from use. After it is removed from use, it cannot be made part of current state until it has been successfully relinked.
Note: like texture objects and buffer objects, the name space for program objects may be shared across a set of contexts, as long as the server sides of the contexts share the same address space. If the name space is shared across contexts, any attached objects and the data associated with those attached objects are shared as well.
Note: applications are responsible for providing the synchronization across API calls when objects are accessed from different execution threads.
OpenGL API: glUseProgram
Exceptions raised
TGLError.InvalidOperation- if the program could not be made part of the current state.
See also
- TGLVertexAttrib
- Represents a single vertex attribute in a TGLProgram.
- TGLUniform
- Represents a uniform in a TGLProgram.
- GetAttachedShaders
- Return the shader objects attached to the program.
- AttachShader
- Attach a shader object to the program.
- TGLShader.Compile
- Compiles the shader;
Note: in DEBUG mode, any compiler warnings will be output to the debug console.
- New
- Delete
- Deletes the program.
- DetachShader
- Detach a shader object from a program object.
- Link
- Links the program.
- Validate
- Validates the program.
|
function GetAttributeInfo(const AIndex: Integer): TGLAttrInfo; inline; |
|
Return information about an active attribute variable.
This method returns information about an active attribute variable in the program object specified by program. The number of active attributes can be obtained by calling GetActiveAttributes. A value of 0 for AIndex selects the first active attribute variable. Permissible values for AIndex range from 0 to the number of active attribute variables minus 1.
Attribute variables have arbitrary names and obtain their values through numbered generic vertex attributes. An attribute variable is considered active if it is determined during the link operation that it may be accessed during program execution. Therefore, the program should have previously been linked by calling Link, but it is not necessary for it to have been linked successfully.
This method will return as much information as it can about the specified active attribute variable. If no information is available, the returned name will be an empty string. This situation could occur if this function is called after a link operation that failed.
OpenGL API: glGetActiveAttrib
Parameters
- AIndex
- the index of the attribute variable to be queried.
Returns
Information about attribute at the given index. Exceptions raised
TGLError.InvalidValue- if AIndex is greater than or equal to the number of active attribute variables in program.
See also
- GetActiveAttributes
- Get the number of active attribute variables in the program.
- TGLShader.GetMaxVertexAttribs
- Get the maximum number of 4-component generic vertex attributes accessible to a vertex shader.
- TGLVertexAttrib.Bind
- Initializes the vertex attribute by binding a user-defined attribute name to an attribute location.
- GetUniformInfo
- Return information about an active uniform variable.
- TGLProgram.Link
- Links the program.
- TGLVertexAttrib.SetValue
- TGLVertexAttrib.SetConfig
- TGLVertexAttrib.SetData
|
function GetUniformInfo(const AIndex: Integer): TGLUniformInfo; inline; |
|
Return information about an active uniform variable.
The number of active uniform variables can be obtained by calling GetActiveUniforms. A value of 0 for index selects the first active uniform variable. Permissible values for index range from 0 to the number of active uniform variables minus 1.
Shaders may use either built-in uniform variables, user-defined uniform variables, or both. Built-in uniform variables have a prefix of "gl_" and reference existing OpenGL state or values derived from such state (e.g., gl_DepthRange). User-defined uniform variables have arbitrary names and obtain their values from the application through calls to TGLUniform.SetValue. A uniform variable (either built-in or user-defined) is considered active if it is determined during the link operation that it may be accessed during program execution. Therefore, program should have previously been linked by calling Link, but it is not necessary for it to have been linked successfully.
Only one active uniform variable will be reported for a uniform array.
Uniform variables that are declared as structures or arrays of structures will not be returned directly by this function. Instead, each of these uniform variables will be reduced to its fundamental components containing the "." and "[]" operators such that each of the names is valid as an argument to TGLUniform.Init. Each of these reduced uniform variables is counted as one active uniform variable and is assigned an index. A valid name cannot be a structure, an array of structures, or a subcomponent of a vector or matrix.
Uniform variables other than arrays will have a Size of 1. Structures and arrays of structures will be reduced as described earlier, such that each of the names returned will be a data type in the earlier list. If this reduction results in an array, the size returned will be as described for uniform arrays; otherwise, the size returned will be 1.
The list of active uniform variables may include both built-in uniform variables (which begin with the prefix "gl_") as well as user-defined uniform variable names.
This function will return as much information as it can about the specified active uniform variable. If no information is available, the returned name will be an empty string. This situation could occur if this function is called after a link operation that failed.
OpenGL API: glGetActiveUniform
Parameters
- AIndex
- the index of the uniform variable to be queried.
Returns
Information about uniform at the given index. Exceptions raised
TGLError.InvalidValue- if AIndex is greater than or equal to the number of active uniforms in the program.
See also
- TGLUniform.GetMaxVertexUniformVectors
- Get the maximum number of four-element floating-point, integer, or boolean vectors that can be held in uniform variable storage for a vertex shader.
- TGLUniform.GetMaxFragmentUniformVectors
- Get the maximum number of four-element floating-point, integer, or boolean vectors that can be held in uniform variable storage for a fragment shader.
- GetActiveUniforms
- Get the number of active uniform variables in the program.
- GetAttributeInfo
- Return information about an active attribute variable.
- TGLUniform.GetValue
- TGLUniform.Init
- Initializes the uniform.
- Link
- Links the program.
- TGLUniform.SetValue
- Use
- Installs the program object as part of current rendering state.
|
class function GetCurrent: TGLProgram; inline; static; |
|
Get the program that is currently active.
OpenGL API: glGetProgramiv(GL_CURRENT_PROGRAM)
Returns
The currently active program. Its Handle will be 0 if there is no program active. See also
- Use
- Installs the program object as part of current rendering state.
|
Properties
property Handle: GLuint read FHandle; |
|
OpenGL handle to the program object.
|
Generated by PasDocEx, based on PasDoc 0.14.0.
|