Class TGLSLProgram

Unit

Declaration

type TGLSLProgram = class(TObject)

Description

Manage (build, use) a program in GLSL (OpenGL Shading Language).

Hierarchy

  • TObject
  • TGLSLProgram

Overview

Fields

Public Name: String;
Public FragmentShaderRequired: Boolean;

Methods

Public constructor Create;
Public destructor Destroy; override;
Public procedure AttachVertexShader(const S: string);
Public procedure AttachGeometryShader(const S: string);
Public procedure AttachFragmentShader(const S: string);
Public procedure AttachShader(const ShaderType: TShaderType; S: string); overload;
Public procedure AttachShader(const ShaderType: TShaderType; const Parts: TStrings); overload;
Public procedure DetachAllShaders;
Public procedure SetTransformFeedbackVaryings(const Varyings: array of PAnsiChar; const IsSingleBufferMode: Boolean = True);
Public procedure Link; overload; virtual;
Public procedure Link(Ignored: boolean); overload; deprecated 'use parameterless Link method';
Public procedure Enable;
Public class procedure Disable;
Public function SetupUniforms(var BoundTextureUnits: Cardinal): boolean; virtual;
Public function DebugInfo: string;
Public function ProgramInfoLog: string;
Public function RunningInHardware: boolean;
Public function Uniform(const AName: string): TGLSLUniform; overload;
Public function Uniform(const AName: string; const AUniformMissing: TUniformMissing): TGLSLUniform; overload;
Public procedure SetUniform(const AName: string; const Value: boolean ; const AUniformMissing: TUniformMissing); overload;
Public procedure SetUniform(const AName: string; const Value: TGLint ; const AUniformMissing: TUniformMissing); overload;
Public procedure SetUniform(const AName: string; const Value: TVector2Integer; const AUniformMissing: TUniformMissing); overload;
Public procedure SetUniform(const AName: string; const Value: TVector3Integer; const AUniformMissing: TUniformMissing); overload;
Public procedure SetUniform(const AName: string; const Value: TVector4Integer; const AUniformMissing: TUniformMissing); overload;
Public procedure SetUniform(const AName: string; const Value: TGLfloat ; const AUniformMissing: TUniformMissing); overload;
Public procedure SetUniform(const AName: string; const Value: TVector2 ; const AUniformMissing: TUniformMissing); overload;
Public procedure SetUniform(const AName: string; const Value: TVector3 ; const AUniformMissing: TUniformMissing); overload;
Public procedure SetUniform(const AName: string; const Value: TVector4 ; const AUniformMissing: TUniformMissing); overload;
Public procedure SetUniform(const AName: string; const Value: TMatrix2 ; const AUniformMissing: TUniformMissing); overload;
Public procedure SetUniform(const AName: string; const Value: TMatrix3 ; const AUniformMissing: TUniformMissing); overload;
Public procedure SetUniform(const AName: string; const Value: TMatrix4 ; const AUniformMissing: TUniformMissing); overload;
Public procedure SetUniform(const AName: string; const Value: TBooleanList; const AUniformMissing: TUniformMissing); overload;
Public procedure SetUniform(const AName: string; const Value: TInt32List ; const AUniformMissing: TUniformMissing); overload;
Public procedure SetUniform(const AName: string; const Value: TSingleList ; const AUniformMissing: TUniformMissing); overload;
Public procedure SetUniform(const AName: string; const Value: TVector2List; const AUniformMissing: TUniformMissing); overload;
Public procedure SetUniform(const AName: string; const Value: TVector3List; const AUniformMissing: TUniformMissing); overload;
Public procedure SetUniform(const AName: string; const Value: TVector4List; const AUniformMissing: TUniformMissing); overload;
Public procedure SetUniform(const AName: string; const Value: TMatrix3List; const AUniformMissing: TUniformMissing); overload;
Public procedure SetUniform(const AName: string; const Value: TMatrix4List; const AUniformMissing: TUniformMissing); overload;
Public procedure SetUniform(const AName: string; const Value: boolean ); overload;
Public procedure SetUniform(const AName: string; const Value: TGLint ); overload;
Public procedure SetUniform(const AName: string; const Value: TVector2Integer); overload;
Public procedure SetUniform(const AName: string; const Value: TVector3Integer); overload;
Public procedure SetUniform(const AName: string; const Value: TVector4Integer); overload;
Public procedure SetUniform(const AName: string; const Value: TGLfloat ); overload;
Public procedure SetUniform(const AName: string; const Value: TVector2 ); overload;
Public procedure SetUniform(const AName: string; const Value: TVector3 ); overload;
Public procedure SetUniform(const AName: string; const Value: TVector4 ); overload;
Public procedure SetUniform(const AName: string; const Value: TMatrix2 ); overload;
Public procedure SetUniform(const AName: string; const Value: TMatrix3 ); overload;
Public procedure SetUniform(const AName: string; const Value: TMatrix4 ); overload;
Public procedure SetUniform(const AName: string; const Value: TBooleanList); overload;
Public procedure SetUniform(const AName: string; const Value: TInt32List ); overload;
Public procedure SetUniform(const AName: string; const Value: TSingleList ); overload;
Public procedure SetUniform(const AName: string; const Value: TVector2List); overload;
Public procedure SetUniform(const AName: string; const Value: TVector3List); overload;
Public procedure SetUniform(const AName: string; const Value: TVector4List); overload;
Public procedure SetUniform(const AName: string; const Value: TMatrix3List); overload;
Public procedure SetUniform(const AName: string; const Value: TMatrix4List); overload;
Public function Attribute(const AName: string): TGLSLAttribute;
Public function AttributeOptional(const AName: string): TGLSLAttribute;
Public procedure SetAttribute(const AName: string; const Value: TGLfloat); overload; deprecated 'use TGLSLAttribute.SetValue';
Public procedure SetAttribute(const AName: string; const Value: TVector2); overload; deprecated 'use TGLSLAttribute.SetValue';
Public procedure SetAttribute(const AName: string; const Value: TVector3); overload; deprecated 'use TGLSLAttribute.SetValue';
Public procedure SetAttribute(const AName: string; const Value: TVector4); overload; deprecated 'use TGLSLAttribute.SetValue';
Public procedure SetAttribute(const AName: string; const Value: TMatrix3); overload; deprecated 'use TGLSLAttribute.SetValue';
Public procedure SetAttribute(const AName: string; const Value: TMatrix4); overload; deprecated 'use TGLSLAttribute.SetValue';
Public procedure SetAttribute(const AName: string; const Value: TVector4Integer); overload; deprecated 'use TGLSLAttribute.SetValue';
Public procedure SetAttribute(const AName: string; const Value: TVector4Byte); overload; deprecated 'use TGLSLAttribute.SetValue';
Public procedure SetAttribute(const AName: string; const Value: TGLdouble); overload; deprecated 'use TGLSLAttribute.SetValue';

Properties

Public property UniformMissing: TUniformMissing read FUniformMissing write FUniformMissing default umWarning;
Public class property Current: TGLSLProgram read GetCurrent write SetCurrent; deprecated 'use RenderContext.CurrentProgram';

Description

Fields

Public Name: String;

Shader name is used in log messages. Any String is OK.

Public FragmentShaderRequired: Boolean;

Is fragment shader required to link successfully.

By default this is False (for now) and you can attempt to link a shader with only vertex shader, without fragment shader. This makes sense on OpenGL ( https://www.khronos.org/opengl/wiki/Fragment_Shader#Optional ). Only OpenGLES, or OpenGL on macOS with Core profile, strictly requires fragment shader to be present.

Setting this to True is useful when you know shader really requires fragment shader and you want to get more clear error message. CGE then knows to abort linking early, with clear error message, when fragment shader is missing.

Methods

Public constructor Create;

This item has no description.

Public destructor Destroy; override;

This item has no description.

Public 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.
Public procedure AttachGeometryShader(const S: string);

This item has no description.

Public procedure AttachFragmentShader(const S: string);

This item has no description.

Public procedure AttachShader(const ShaderType: TShaderType; S: string); overload;

This item has no description.

Public procedure AttachShader(const ShaderType: TShaderType; const Parts: TStrings); overload;

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.

Public procedure DetachAllShaders;

This item has no description.

Public procedure SetTransformFeedbackVaryings(const Varyings: array of PAnsiChar; const IsSingleBufferMode: Boolean = True);

Specify values to record in transform feedback buffers. This must be called before Link method.

Public procedure Link; overload; virtual;

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.
Public procedure Link(Ignored: boolean); overload; deprecated 'use parameterless Link method';

Warning: this symbol is deprecated: use parameterless Link method

This item has no description.

Public procedure Enable;

Enable (use) this program. Shortcut for RenderContext.CurrentProgram := Self.

Public class procedure Disable;

Disable this program (use the fixed function pipeline). Shortcut for RenderContext.CurrentProgram := nil.

Public 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 our renderer (when it renders shapes) or TCastleScreenEffect (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.

Public function DebugInfo: string;

Returns multiline debug info about current program. Reports whether shaders are supported, names of active uniform and attribute variables etc.

Exceptions raised
Exception
If any OpenGL error will be detected.
Public function ProgramInfoLog: string;

This is program info log, given to you from OpenGL after the program is linked.

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

Public function Uniform(const AName: string): TGLSLUniform; overload;

Get the uniform instance. It can be used to make repeated TGLSLUniform.SetValue calls. You must link the program first.

If the uniform doesn't exist (or is unused), the action we take depends on UniformMissing property (by default – umWarning). The overloaded version with extra AUniformMissing parameter follows this parameter value.

Public function Uniform(const AName: string; const AUniformMissing: TUniformMissing): TGLSLUniform; overload;

This item has no description.

Public procedure SetUniform(const AName: string; const Value: boolean ; const AUniformMissing: TUniformMissing); overload;

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 GLSL program must be currently enabled for this to work. So calling this automatically calls Enable and sets RenderContext.CurrentProgram.

    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.

    You can change UniformMissing not to silently ignore setting of inactive (or not existing) uniform values.

This will make warning if the variable is not found within the program and UniformMissing = umWarning. The overloaded version with explicit AUniformMissing parameter uses that to decide whether to show warning.

Public procedure SetUniform(const AName: string; const Value: TGLint ; const AUniformMissing: TUniformMissing); overload;

This item has no description.

Public procedure SetUniform(const AName: string; const Value: TVector2Integer; const AUniformMissing: TUniformMissing); overload;

This item has no description.

Public procedure SetUniform(const AName: string; const Value: TVector3Integer; const AUniformMissing: TUniformMissing); overload;

This item has no description.

Public procedure SetUniform(const AName: string; const Value: TVector4Integer; const AUniformMissing: TUniformMissing); overload;

This item has no description.

Public procedure SetUniform(const AName: string; const Value: TGLfloat ; const AUniformMissing: TUniformMissing); overload;

This item has no description.

Public procedure SetUniform(const AName: string; const Value: TVector2 ; const AUniformMissing: TUniformMissing); overload;

This item has no description.

Public procedure SetUniform(const AName: string; const Value: TVector3 ; const AUniformMissing: TUniformMissing); overload;

This item has no description.

Public procedure SetUniform(const AName: string; const Value: TVector4 ; const AUniformMissing: TUniformMissing); overload;

This item has no description.

Public procedure SetUniform(const AName: string; const Value: TMatrix2 ; const AUniformMissing: TUniformMissing); overload;

This item has no description.

Public procedure SetUniform(const AName: string; const Value: TMatrix3 ; const AUniformMissing: TUniformMissing); overload;

This item has no description.

Public procedure SetUniform(const AName: string; const Value: TMatrix4 ; const AUniformMissing: TUniformMissing); overload;

This item has no description.

Public procedure SetUniform(const AName: string; const Value: TBooleanList; const AUniformMissing: TUniformMissing); overload;

This item has no description.

Public procedure SetUniform(const AName: string; const Value: TInt32List ; const AUniformMissing: TUniformMissing); overload;

This item has no description.

Public procedure SetUniform(const AName: string; const Value: TSingleList ; const AUniformMissing: TUniformMissing); overload;

This item has no description.

Public procedure SetUniform(const AName: string; const Value: TVector2List; const AUniformMissing: TUniformMissing); overload;

This item has no description.

Public procedure SetUniform(const AName: string; const Value: TVector3List; const AUniformMissing: TUniformMissing); overload;

This item has no description.

Public procedure SetUniform(const AName: string; const Value: TVector4List; const AUniformMissing: TUniformMissing); overload;

This item has no description.

Public procedure SetUniform(const AName: string; const Value: TMatrix3List; const AUniformMissing: TUniformMissing); overload;

This item has no description.

Public procedure SetUniform(const AName: string; const Value: TMatrix4List; const AUniformMissing: TUniformMissing); overload;

This item has no description.

Public procedure SetUniform(const AName: string; const Value: boolean ); overload;

This item has no description.

Public procedure SetUniform(const AName: string; const Value: TGLint ); overload;

This item has no description.

Public procedure SetUniform(const AName: string; const Value: TVector2Integer); overload;

This item has no description.

Public procedure SetUniform(const AName: string; const Value: TVector3Integer); overload;

This item has no description.

Public procedure SetUniform(const AName: string; const Value: TVector4Integer); overload;

This item has no description.

Public procedure SetUniform(const AName: string; const Value: TGLfloat ); overload;

This item has no description.

Public procedure SetUniform(const AName: string; const Value: TVector2 ); overload;

This item has no description.

Public procedure SetUniform(const AName: string; const Value: TVector3 ); overload;

This item has no description.

Public procedure SetUniform(const AName: string; const Value: TVector4 ); overload;

This item has no description.

Public procedure SetUniform(const AName: string; const Value: TMatrix2 ); overload;

This item has no description.

Public procedure SetUniform(const AName: string; const Value: TMatrix3 ); overload;

This item has no description.

Public procedure SetUniform(const AName: string; const Value: TMatrix4 ); overload;

This item has no description.

Public procedure SetUniform(const AName: string; const Value: TBooleanList); overload;

This item has no description.

Public procedure SetUniform(const AName: string; const Value: TInt32List ); overload;

This item has no description.

Public procedure SetUniform(const AName: string; const Value: TSingleList ); overload;

This item has no description.

Public procedure SetUniform(const AName: string; const Value: TVector2List); overload;

This item has no description.

Public procedure SetUniform(const AName: string; const Value: TVector3List); overload;

This item has no description.

Public procedure SetUniform(const AName: string; const Value: TVector4List); overload;

This item has no description.

Public procedure SetUniform(const AName: string; const Value: TMatrix3List); overload;

This item has no description.

Public procedure SetUniform(const AName: string; const Value: TMatrix4List); overload;

This item has no description.

Public function Attribute(const AName: string): TGLSLAttribute;

Get the attribute instance. It can be used to make repeated TGLSLAttribute.SetValue and TGLSLAttribute.EnableArray.

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.

Public function AttributeOptional(const AName: string): TGLSLAttribute;

Get the attribute instance. It can be used to make repeated TGLSLAttribute.SetValue and TGLSLAttribute.EnableArray.

Returned attribute has TGLSLAttribute.Location equal to -1. All the calls to TGLSLAttribute.SetValue or TGLSLAttribute.EnableArray or TGLSLAttribute.DisableArray methods are silently ignored.

Public procedure SetAttribute(const AName: string; const Value: TGLfloat); overload; deprecated 'use TGLSLAttribute.SetValue';

Warning: this symbol is deprecated: use TGLSLAttribute.SetValue

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 the program. The program is automatically enabled (set as RenderContext.CurrentProgram) by this. 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 used. Usually, you should rather load attribute arrays, by VertexAttribPointer. You should also get attribute by the Attribute method, as TGLSLAttribute, and then call TGLSLAttribute.SetValue or TGLSLAttribute.EnableArray.

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.

Public procedure SetAttribute(const AName: string; const Value: TVector2); overload; deprecated 'use TGLSLAttribute.SetValue';

Warning: this symbol is deprecated: use TGLSLAttribute.SetValue

This item has no description.

Public procedure SetAttribute(const AName: string; const Value: TVector3); overload; deprecated 'use TGLSLAttribute.SetValue';

Warning: this symbol is deprecated: use TGLSLAttribute.SetValue

This item has no description.

Public procedure SetAttribute(const AName: string; const Value: TVector4); overload; deprecated 'use TGLSLAttribute.SetValue';

Warning: this symbol is deprecated: use TGLSLAttribute.SetValue

This item has no description.

Public procedure SetAttribute(const AName: string; const Value: TMatrix3); overload; deprecated 'use TGLSLAttribute.SetValue';

Warning: this symbol is deprecated: use TGLSLAttribute.SetValue

This item has no description.

Public procedure SetAttribute(const AName: string; const Value: TMatrix4); overload; deprecated 'use TGLSLAttribute.SetValue';

Warning: this symbol is deprecated: use TGLSLAttribute.SetValue

This item has no description.

Public procedure SetAttribute(const AName: string; const Value: TVector4Integer); overload; deprecated 'use TGLSLAttribute.SetValue';

Warning: this symbol is deprecated: use TGLSLAttribute.SetValue

This item has no description.

Public procedure SetAttribute(const AName: string; const Value: TVector4Byte); overload; deprecated 'use TGLSLAttribute.SetValue';

Warning: this symbol is deprecated: use TGLSLAttribute.SetValue

This item has no description.

Public procedure SetAttribute(const AName: string; const Value: TGLdouble); overload; deprecated 'use TGLSLAttribute.SetValue';

Warning: this symbol is deprecated: use TGLSLAttribute.SetValue

This item has no description.

Properties

Public property UniformMissing: TUniformMissing read FUniformMissing write FUniformMissing default umWarning;

What to do when GLSL uniform variable is accessed (by SetUniform or Uniform) 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 unused" variables.

This is only the default value, each Uniform method call may explicitly use other TUniformMissing.

See also
TUniformMissing
What to do when shader uniform variable is set but doesn't exist in the shader.
Public class property Current: TGLSLProgram read GetCurrent write SetCurrent; deprecated 'use RenderContext.CurrentProgram';

Warning: this symbol is deprecated: use RenderContext.CurrentProgram

Currently enabled GLSL program. Nil if fixed-function pipeline should be used. Setting this property encapsulates the OpenGL glUseProgram (or equivalent ARB extension), additionally preventing redundant glUseProgram calls.


Generated by PasDoc 0.16.0-snapshot.