Castle Game Engine: CastleGLShaders: Class TGLSLProgram

# Class TGLSLProgram
Description | Hierarchy | Fields | Methods | Properties
## Unit CastleGLShaders ## Declaration `type TGLSLProgram = class(TObject)` ## Description Easily handle program in GLSL (OpenGL Shading Language). ## Hierarchy TObject TGLSLProgram ## Overview ### Methods
| `constructor Create;`
| `destructor Destroy; override;`
| `procedure AttachVertexShader(const S: string);`
| `procedure AttachGeometryShader(const S: string);`
| `procedure AttachFragmentShader(const S: string);`
| `procedure AttachShader(const ShaderType: TShaderType; const S: string);`
| `procedure AttachShader(const ShaderType: TShaderType; const Parts: TStrings);`
| `procedure DetachAllShaders;`
| `procedure Link(RequireRunningInHardware: boolean);`
| `procedure Enable;`
| `class procedure Disable;`
| `function SetupUniforms(var BoundTextureUnits: Cardinal): boolean; virtual;`
| `function DebugInfo: string;`
| `function ProgramInfoLog: string;`
| `function RunningInHardware: boolean;`
| `class function ClassSupport: TGLSupport;`
| `procedure SetUniform(const Name: string; const Value: boolean ; const ForceException: boolean = false);`
| `procedure SetUniform(const Name: string; const Value: TGLint ; const ForceException: boolean = false);`
| `procedure SetUniform(const Name: string; const Value: TVector2Integer; const ForceException: boolean = false);`
| `procedure SetUniform(const Name: string; const Value: TVector3Integer; const ForceException: boolean = false);`
| `procedure SetUniform(const Name: string; const Value: TVector4Integer; const ForceException: boolean = false);`
| `procedure SetUniform(const Name: string; const Value: TGLfloat ; const ForceException: boolean = false);`
| `procedure SetUniform(const Name: string; const Value: TVector2Single ; const ForceException: boolean = false);`
| `procedure SetUniform(const Name: string; const Value: TVector3Single ; const ForceException: boolean = false);`
| `procedure SetUniform(const Name: string; const Value: TVector4Single ; const ForceException: boolean = false);`
| `procedure SetUniform(const Name: string; const Value: TMatrix2Single ; const ForceException: boolean = false);`
| `procedure SetUniform(const Name: string; const Value: TMatrix3Single ; const ForceException: boolean = false);`
| `procedure SetUniform(const Name: string; const Value: TMatrix4Single ; const ForceException: boolean = false);`
| `procedure SetUniform(const Name: string; const Value: TBooleanList ; const ForceException: boolean = false);`
| `procedure SetUniform(const Name: string; const Value: TLongIntList ; const ForceException: boolean = false);`
| `procedure SetUniform(const Name: string; const Value: TSingleList ; const ForceException: boolean = false);`
| `procedure SetUniform(const Name: string; const Value: TVector2SingleList; const ForceException: boolean = false);`
| `procedure SetUniform(const Name: string; const Value: TVector3SingleList; const ForceException: boolean = false);`
| `procedure SetUniform(const Name: string; const Value: TVector4SingleList; const ForceException: boolean = false);`
| `procedure SetUniform(const Name: string; const Value: TMatrix3SingleList; const ForceException: boolean = false);`
| `procedure SetUniform(const Name: string; const Value: TMatrix4SingleList; const ForceException: boolean = false);`
| `function VertexAttribPointer(const Name: string; LocationOffset: TGLint; Size: TGLint; AType: TGLenum; Normalized: TGLboolean; Stride: TGLsizei; Ptr: Pointer): TGLint;`
| `class procedure DisableVertexAttribArray(Location: TGLint);`
| `procedure SetAttribute(const Name: string; const Value: TGLfloat);`
| `procedure SetAttribute(const Name: string; const Value: TVector2Single);`
| `procedure SetAttribute(const Name: string; const Value: TVector3Single);`
| `procedure SetAttribute(const Name: string; const Value: TVector4Single);`
| `procedure SetAttribute(const Name: string; const Value: TMatrix3Single);`
| `procedure SetAttribute(const Name: string; const Value: TMatrix4Single);`
| `procedure SetAttribute(const Name: string; const Value: TVector4Integer);`
| `procedure SetAttribute(const Name: string; const Value: TVector4Byte);`
| `procedure SetAttribute(const Name: string; const Value: TGLdouble);`
| `procedure SetAttribute(const Name: string; const Value: TVector2Double);`
| `procedure SetAttribute(const Name: string; const Value: TVector3Double);`
| `procedure SetAttribute(const Name: string; const Value: TVector4Double);`
### Properties
| `property Support: TGLSupport read FSupport;`
| `property UniformNotFoundAction: TUniformNotFoundAction read FUniformNotFoundAction write FUniformNotFoundAction default uaException;`
| `property UniformTypeMismatchAction: TUniformTypeMismatchAction read FUniformTypeMismatchAction write FUniformTypeMismatchAction default utGLError;`
## Description ### Methods
| `constructor Create;`
| `destructor Destroy; override;`
| `procedure AttachVertexShader(const S: string);`
Create shader from given string, compile it and attach to current program. For desktop OpenGL, you can attach more than one shader of given type, just make sure that only one main() function is among each type (otherwise link error will be raised later). For OpenGLES, this is not allowed, so don't use this if you want to work with OpenGLES too. If you want to explicitly get rid of old shaders, use DetachAllShaders. ###### Exceptions raised EGLSLShaderCompileError If the shader source code cannot be compiled, exception message contains precise description from OpenGL where the error is.
| `procedure AttachGeometryShader(const S: string);`
| `procedure AttachFragmentShader(const S: string);`
| `procedure AttachShader(const ShaderType: TShaderType; const S: string);`
| `procedure AttachShader(const ShaderType: TShaderType; const Parts: TStrings);`
Attach multiple shader parts for given type. For normal OpenGL, we can use GLSL separate compilation units. So this is equivalent to just calling ``AttachShader`(ShaderType, Parts[I])` for each part. For OpenGL ES, this is unfortunately not possible, you can only attach a single shader of a given type (see http://www.khronos.org/opengles/sdk/docs/man/xhtml/glAttachShader.xml ). So we simply concatenate the shaders into one.
| `procedure DetachAllShaders;`
| `procedure Link(RequireRunningInHardware: boolean);`
Link the program, this should be done after attaching all shaders and before actually using the program. ###### Exceptions raised EGLSLProgramLinkError If the program cannot be linked, exception message contains precise description from OpenGL where the error is. EGLSLRunningInSoftware If the program will be linked successfully, but RequireRunningInHardware = `True` and the program will be detected to be running in software.
| `procedure Enable;`
Enable (use) this program. Shortcut for `CurrentProgram := Self`.
| `class procedure Disable;`
Disable this program (use the fixed function pipeline). Shortcut for `CurrentProgram := nil`.
| `function SetupUniforms(var BoundTextureUnits: Cardinal): boolean; virtual;`
Override this to set uniform values, in particular to bind the textures used by this shader, right after each Enable call. This is automatically called after every Enable by VRML renderer (when it renders shapes) or scene manager (when it renders screen effects). If you use this TGLSLProgram directly (if you call Enable yourself), then it's your responsibility to call this method explicitly, if you want shaders using it to work. You can set any uniform values, and generally do anything you want to be done each time this shader is enabled. In particular, you can bind textures and set corresponding uniform variables of them. Increase BoundTextureUnits appropriately. Returns `False` is some texture couldn't be bound.
| `function DebugInfo: string;`
Returns multiline debug info about current program. Things like how it's supported (not at all ? ARB extension ? standard ?), names of active uniform and attribute variables etc. fglrx (Radeon closed-source OpenGL drivers) are buggy (that's not news, I know...) and they report GL_INVALID_ENUM on some queries here. We detect this, and still produce nice debug message, without raising any exception (after all, we have to workaround fglrx bugs, and try to run our program anyway...). What's important for caller is that we have to check first whether there are any OpenGL errors pending, and raise exceptions on them. ###### Exceptions raised EOpenGLError If any OpenGL error will be detected.
| `function ProgramInfoLog: string;`
This is program info log, given to you from OpenGL after the program is linked.
| `function RunningInHardware: boolean;`
After the program is linked, you can check this. Note that this is necessarily implemented in quite hacky way (by looking at ProgramInfoLog), there is no way currently (AFAIK ?) to get this information cleanly from OpenGL. In case of doubts, we try to "trust" OpenGL to execute shader in hardware. Return `False` only when we see clear indication in ProgramInfoLog that it'll run in software.
| `class function ClassSupport: TGLSupport;`
What support do we get from current OpenGL context ? This is much like Support, but it's a class function.
| `procedure SetUniform(const Name: string; const Value: boolean ; const ForceException: boolean = false);`
Set appropriate uniform variable value. The used type must match the type of this variable in GLSL program. OpenGL forces some constraints on using this: This should be used only after linking, and re-linking clears (sets to zero) all uniform variables values. This can be used only when the program is currently used. So call Enable before doing SetUniform calls. This is required by OpenGL glUniform* commands. glGetUniformLocation take program id as parameter, so they can operate on any program. But glUniform* operate only on active program. Only active uniforms variables may be set. Active means, quoting OpenGL manpages, a variable that is determined during the link operation that it may be accessed during program execution. In other words, when linking GLSL program, unused variables may be eliminated, and you cannot set them by SetUniform. Call DebugInfo to see what uniform variables are considered active for your shader. ###### Exceptions raised EGLSLUniformNotFound If the variable is not found within the program and UniformNotFoundAction = uaException (default) or ForceException. EGLSLUniformTypeMismatch If the variable type doesn't match the type declared in shader code. Raised only if UniformTypeMismatchAction = utException or ForceException. Note that both EGLSLUniformNotFound and EGLSLUniformTypeMismatch may be comfortably catched by an umbrella class EGLSLUniformInvalid.
| `procedure SetUniform(const Name: string; const Value: TGLint ; const ForceException: boolean = false);`
| `procedure SetUniform(const Name: string; const Value: TVector2Integer; const ForceException: boolean = false);`
| `procedure SetUniform(const Name: string; const Value: TVector3Integer; const ForceException: boolean = false);`
| `procedure SetUniform(const Name: string; const Value: TVector4Integer; const ForceException: boolean = false);`
| `procedure SetUniform(const Name: string; const Value: TGLfloat ; const ForceException: boolean = false);`
| `procedure SetUniform(const Name: string; const Value: TVector2Single ; const ForceException: boolean = false);`
| `procedure SetUniform(const Name: string; const Value: TVector3Single ; const ForceException: boolean = false);`
| `procedure SetUniform(const Name: string; const Value: TVector4Single ; const ForceException: boolean = false);`
| `procedure SetUniform(const Name: string; const Value: TMatrix2Single ; const ForceException: boolean = false);`
| `procedure SetUniform(const Name: string; const Value: TMatrix3Single ; const ForceException: boolean = false);`
| `procedure SetUniform(const Name: string; const Value: TMatrix4Single ; const ForceException: boolean = false);`
| `procedure SetUniform(const Name: string; const Value: TBooleanList ; const ForceException: boolean = false);`
| `procedure SetUniform(const Name: string; const Value: TLongIntList ; const ForceException: boolean = false);`
| `procedure SetUniform(const Name: string; const Value: TSingleList ; const ForceException: boolean = false);`
| `procedure SetUniform(const Name: string; const Value: TVector2SingleList; const ForceException: boolean = false);`
| `procedure SetUniform(const Name: string; const Value: TVector3SingleList; const ForceException: boolean = false);`
| `procedure SetUniform(const Name: string; const Value: TVector4SingleList; const ForceException: boolean = false);`
| `procedure SetUniform(const Name: string; const Value: TMatrix3SingleList; const ForceException: boolean = false);`
| `procedure SetUniform(const Name: string; const Value: TMatrix4SingleList; const ForceException: boolean = false);`
| `function VertexAttribPointer(const Name: string; LocationOffset: TGLint; Size: TGLint; AType: TGLenum; Normalized: TGLboolean; Stride: TGLsizei; Ptr: Pointer): TGLint;`
Load and enable vertex attribute data. This calls glVertexAttribPointer and enables it by glEnableVertexAttribArray (or ARB extension equivalents), see OpenGL reference for details. The attribute name is automatically resolved to a "location". We add LocationOffset (useful if you want to load matrix attributes, when you have to load matrix columns separately, with LocationOffset = column index). ###### Returns Attribute location (with LocationOffset already applied). You can use it with DisableVertexAttribArray. ###### Exceptions raised EGLSLAttributeNotFound If the variable is not found within the program.
| `class procedure DisableVertexAttribArray(Location: TGLint);`
| `procedure SetAttribute(const Name: string; const Value: TGLfloat);`
Set attribute variable value. The used type must match the type of this variable in GLSL program. OpenGL forces some constraints on using this, see SetUniform. In short: use this only after linking and using the program. And note that attributes declared but not actually used in shader code may be eliminated, use DebugInfo to see which attributes are actually used (active in OpenGL terminology). These should not be often useful. Usually, you should rather load attribute arrays, by VertexAttribPointer. ###### Exceptions raised EGLSLAttributeNotFound If the variable is not found within the program. Note that this is only one of the many things that can go wrong. And on most cases we don't raise any error, instead OpenGL sets it's error state and you probably want to call CheckGLErrors from time to time to catch them.
| `procedure SetAttribute(const Name: string; const Value: TVector2Single);`
| `procedure SetAttribute(const Name: string; const Value: TVector3Single);`
| `procedure SetAttribute(const Name: string; const Value: TVector4Single);`
| `procedure SetAttribute(const Name: string; const Value: TMatrix3Single);`
| `procedure SetAttribute(const Name: string; const Value: TMatrix4Single);`
| `procedure SetAttribute(const Name: string; const Value: TVector4Integer);`
| `procedure SetAttribute(const Name: string; const Value: TVector4Byte);`
| `procedure SetAttribute(const Name: string; const Value: TGLdouble);`
| `procedure SetAttribute(const Name: string; const Value: TVector2Double);`
| `procedure SetAttribute(const Name: string; const Value: TVector3Double);`
| `procedure SetAttribute(const Name: string; const Value: TVector4Double);`
### Properties
| `property Support: TGLSupport read FSupport;`
| `property UniformNotFoundAction: TUniformNotFoundAction read FUniformNotFoundAction write FUniformNotFoundAction default uaException;`
What to do when GLSL uniform variable is set (SetUniform) but doesn't exist in the shader. Note that OpenGL aggresively removes unused code and variables from the shader when compiling/linking, so this also happens for "declared but detected to not used" variables. ###### See also TUniformNotFoundAction What to do when GLSL uniform variable is set (TGLSLProgram.SetUniform) but doesn't exist in the shader.
| `property UniformTypeMismatchAction: TUniformTypeMismatchAction read FUniformTypeMismatchAction write FUniformTypeMismatchAction default utGLError;`
What to do when GLSL uniform variable is set (SetUniform) but is declared with an incompatible type in the shader source. ###### See also TUniformTypeMismatchAction What to do when GLSL uniform variable is set (by TGLSLProgram.SetUniform) to the type that doesn't match type declared in GLSL shader.
Generated by PasDoc 0.13.0 on 2015-06-15 04:43:10