GLEffect

Description

abstract class Tinman.Engine.API.GLEffect
<TParameters : RenderEffectParameters>

Derived from

RenderEffectGeneric<TParameters> abstract

Extended by

OpenGLEffect abstract
OpenGLESEffect abstract

Abstract base class for IRenderEffect implementations for OpenGL 4.1 Core Profile (or newer) and OpenGLES 3.0 (or newer).

An implementing class must perform the following steps in its constructor:

Because there are no render state blocks / objects that could be created in the constructor, the render state for each pass must be setup by subclasses, using the following methods:

  • The RenderStateSet must be implemented and will be called each time the active render pass changes.

  • Use the RenderStateDefault method to establish default render state, for example when the render effect has begun.

  • Use the RenderStateApply method to set common render state values.

  • Use the GLBase subclass for setting all other render state.

If an implementation wants to use low-level parameter slots, the following steps must be performed in the constructor:

Public / Constants

CS


public constant CS → (0:int32)

Shader type index: Compute Shader (GL_COMPUTE_SHADER)

Compute shaders are not available in OpenGLES 3.0.

FS


public constant FS → (1:int32)

Shader type index: Fragment Shader (GL_FRAGMENT_SHADER)

GS


public constant GS → (2:int32)

Shader type index: Geometry Shader (GL_GEOMETRY_SHADER)

Geometry shaders are provided by an extension in OpenGLES 3.0/3.1.

MS


public constant MS → (3:int32)

Shader type index: Mesh Shader (GL_MESH_SHADER_NV)

Mesh shaders are provided by a vendor-specific extension.

TCS


public constant TCS → (4:int32)

Shader type index: Tessellation Control Shader (GL_TESS_CONTROL_SHADER)

Tessellation shaders are provided by an extension in OpenGLES 3.0/3.1.

TES


public constant TES → (5:int32)

Shader type index: Tessellation Evaluation Shader (GL_TESS_EVALUATION_SHADER)

Tessellation shaders are provided by an extension in OpenGLES 3.0/3.1.

TS


public constant TS → (6:int32)

Shader type index: Task Shader (GL_TASK_SHADER_NV)

Mesh shaders are provided by a vendor-specific extension.

VS


public constant VS → (7:int32)

Shader type index: Vertex Shader (GL_VERTEX_SHADER)

Public / Methods

Render​State​Apply


public abstract method RenderStateApply → (2)

preset in : RenderStatePreset

The render state preset to apply.

apply opt : bool = true

true applies the render state preset,
false reverts the affected render state to default, as defined by RenderStateDefault.

Applies the given render state preset.

This method assumes that default render state values are in place, as defined by the implementation of RenderStateDefault or the GL (in that order).

Render​State​Default


public abstract method RenderStateDefault → ()

Sets default render state values.

Please refer to the documentation of the concrete subclass for details on which render state is set by this method.

Render​State​Set


public virtual method RenderStateSet → (1)

context in : int32

Indicates the context in which this method is being called:
< 0 : render effect has just begun, no pass is active yet
= 0 : a render pass has been activated (see IRenderEffectBase.PassCurrent)
> 0 : render effect is about to end, no more pass is active

Sets the render state for the current render effect pass.

Render state must be set by subclasses by using a GLBase wrapper for accessing the GL API, for example GL or GLES. The default implementation calls RenderStateDefault initially (when context in is negative) and then keeps track of the current render state preset (when context in is zero, using RenderEffectParameters.EffectRenderState), calling RenderStateApply accordingly to apply resp. revert render states. Finally (when context in is greater than zero), the current render state preset is reverted. An overriding method may call RenderStateDirty to indicate that it has modified the render state in a way that conflicts with the given render state presets, so that they will be applied again, if necessary.

Sampler​State​Apply


public abstract method SamplerStateApply → (2)

sampler in : int32

The sampler object name.

preset in : SamplerStatePreset

The sampler state preset to apply.

returns → int32

sampler in

Applies the given sampler state preset.

Sampler​State​Assign

3 overloads


public method SamplerStateAssign1 → (1)

name in : string

[not-empty]
The GLSL texture resource name.

Assigns the common sampler state preset to a texture resource.

All vertex attributes must have been declared via VertexAttributeDeclare before a sampler state may be assigned. This method first calls RenderEffectParameters.EffectSamplerState to get the common sampler state preset and then calls SamplerStateAssign2.

RenderException

If a graphics subsystem error has occurred.


public method SamplerStateAssign2 → (2)

name in : string

[not-empty]
The GLSL texture resource name.

sampler in : SamplerStatePreset

The sampler state preset.

Assigns a sampler state to a texture resource.

All vertex attributes must have been declared via VertexAttributeDeclare before a sampler state may be assigned. This method first calls SamplerStateCreate3 and then passes the created sampler state object to SamplerStateAssign3.

RenderException

If a graphics subsystem error has occurred.


public method SamplerStateAssign3 → (2)

name in : string

[not-empty]
The GLSL texture resource name.

sampler in : int32

[0..GLEffect.SamplerStateCount-1]
The sampler state index.

Assigns a sampler state to a texture resource.

All vertex attributes must have been declared via VertexAttributeDeclare before a sampler state may be assigned.

RenderException

If a graphics subsystem error has occurred.

Sampler​State​Create

3 overloads


[OwnerReturn]
public abstract method SamplerStateCreate1 → ()

returns → int32

The sampler object name.

Creates a sampler state (step 1 of 2).

Use the returned sampler object name to configure the sampler state using the GL API. Then, call SamplerStateCreate2.

RenderException

If sampler state creation has failed.


public method SamplerStateCreate2 → (1)

sampler in : int32 own

The sampler object name, as returned by SamplerStateCreate1.

returns → int32

The sampler state index, see SamplerStateCount.

Creates a sampler state (step 2 of 2).


[OwnerReturn]
public method SamplerStateCreate3 → (1)

preset in : SamplerStatePreset

The sampler state preset to use.

returns → int32

The sampler state index, see SamplerStateCount.

Creates a sampler state based on a SamplerStatePreset.

This method first calls SamplerStateCreate1, then SamplerStateApply, passing preset in. Finally, it calls SamplerStateCreate2 and returns the result.

RenderException

If sampler state creation has failed.

Vertex​Attribute​Declare


public method VertexAttributeDeclare → (5)

name in : string

[not-null]
The name of the vertex attribute, as given in GLSL code, without the array size specifier suffix [n] and without the array index suffix _x_, if any. For example vs_color for an OpenGL vertex attribute like this:

in vec4 vs_color[2];

OpenGLES does not allow array as vertex shader inputs, so the example for vs_color would be this:

in vec4 vs_color_0_;
in vec4 vs_color_1_;
data in : int32

[0..1]
Specifies which vertex buffer to map as input:
0 : per-vertex data (see IGeometryBuffer.Vertices)
1 : per-instance data (see IGeometryBuffer.Instances).

usage in : VertexElementUsage

The vertex element usage to use for mapping.

first opt : int32 = 0

[>=0]
The zero-based vertex element usage index to use for mapping the first array element of the vertex attribute. Subsequent array elements will use subsequent usage indices.

count opt : int32 = 1

[>=1]
The number of array elements in the vertex attribute.

Declares a vertex attribute.

All shader objects must have been created via RenderEffect.ShaderCreate and must have been assigned to passes via RenderEffect.ShaderAssign before a vertex attribute may be declared.

RenderException

If a graphics subsystem error has occurred.

Public / Attributes

Sampler​State​Count


public attribute SamplerStateCount → (get)

value : int32

[>=0]
The number of sampler states.

Returns the number of sampler states.

Protected / Constructors

GLEffect


protected constructor GLEffect → (4)

context in : GLContext

[not-null]
The owning GLContext object.

parameters in : TParameters

[not-null]
The render effect parameters object.

compilationMacro in : string

The pre-processor macro to define for shader compilation or null for none.

repositoryPrivate in : Path

[not-null]
The private GPU shader repository path or Path.Unknown if none.

Creates a new instance of GLEffect.

Protected / Methods

Buffer​Object​Apply


protected abstract method BufferObjectApply → (2)

buffer in : int32

The buffer object name.

binding in : int32

The binding point index.

Applies the given buffer object to a shader storage block binding point.

Buffer​Object​Create


protected abstract method BufferObjectCreate → (1)

size in : int32

The buffer size, in bytes.

returns → int32

The buffer object name.

Creates a buffer object for a uniform block.

RenderException

If buffer creation has failed.

Buffer​Object​Delete


protected abstract method BufferObjectDelete → (1)

bufferObject in : int32

The buffer object name.

Deletes the given buffer object.

Buffer​Object​Update


protected abstract method BufferObjectUpdate → (2)

bufferObject in : int32

The buffer object name or 0 to clear.

data in : ByteBuffer

The buffer data or null iff bufferObject in is 0.

Updates the content of the given buffer object.

For each sequence of buffer updates, the last call will receive a bufferObject in of 0.

Parameter​Type


protected abstract method ParameterType → (1)

type in : int32

The GL uniform type (see GL_UNIFORM_TYPE).

returns → int32

The RenderEffectParameterType value or -1 iff type in is not supported.

Returns the render effect parameter type that corresponds

Platform​Identifier


protected abstract method PlatformIdentifier → ()

returns → string

The identifier of the compiling platform.

Constructs a string value that identifies the platform that is compiling programs.

Cached programs are stored along with a platform hash, in order to detect when the platform has changed.

Program​Object​Binary

2 overloads


[EmptyBody]
protected virtual method ProgramObjectBinary1 → (1)

program in : int32

The program object.

returns → Pair<int32, int8 [ ]>

The retrieved binary format and content.

Tries to retrieve the binary of the given program.


[EmptyBody]
protected virtual method ProgramObjectBinary2 → (2)

format in : int32

The binary format.

binary in : ByteBuffer

The binary content.

returns → int32

> 0 : an empty program object (binary is incompatible),
< 0 : the final program object (binary has been loaded),
= 0 : if no program object has been created.

Builds a program from the given binary.

RenderException

If program creation has failed.

Program​Object​Build


protected abstract method ProgramObjectBuild → (2)

program in : int32

The empty program object to build or 0 if none.

pass in : int32

[0..IRenderEffectBase.PassCount-1]
The render effect pass index.

returns → int32

The created program object.

Creates a program object for each available render effect pass, attaches all shader objects and links the program.

RenderException

If program creation has failed.

Program​Object​Delete


protected abstract method ProgramObjectDelete → (1)

programObject in : int32

The program object name.

Deletes the given program object.

Program​Object​Reflect


protected abstract method ProgramObjectReflect → (1)

program in : int32

The program object.

Reflects the active vertex attributes, active uniforms and uniform blocks of the given program object.

An implementing method must perform the following steps, in the order given:

  1. For each active vertex attribute, call the ProgramObjectReflectAttribute method once.

  2. For each uniform block, call the ProgramObjectReflectUniformBlock method once.

  3. For each active uniform, call the ProgramObjectReflectUniform method once.

RenderException

If program reflection has failed.

Program​Object​Reflect​Attribute


protected method ProgramObjectReflectAttribute → (4)

program in : int32

The program object.

name in : string

The attribute name (see glGetActiveAttrib), not including the [0] suffix.

size in : int32

The attribute size (see glGetActiveAttrib).

location in : int32

The attribute location (glGetAttribLocation) of the first vertex attribute element, which defines the range of attribute locations to use for the vertex attribute: [location .. location+size[

Declares a program vertex attribute.

RenderException

If the given vertex attribute specification is invalid or unsupported.

Program​Object​Reflect​Shader​Storage​Block


protected method ProgramObjectReflectShaderStorageBlock → (5)

program in : int32

The program object.

location in : int32

The shader storage block binding point.

name in : string

[not-empty]
The shader storage block name.

fields in : int32

The number of block fields.

size in : int32

The byte size of the block.

Declares a program shader storage block.

RenderException

If the given shader storage block specification is invalid.

Program​Object​Reflect​Uniform


protected method ProgramObjectReflectUniform → (10)

program in : int32

The program object.

location in : int32

The uniform location in program in (see glGetUniformLocation).

block in : string

Name of the containing uniform block (see GL_UNIFORM_BLOCK_INDEX) or null.

name in : string

The uniform name (see glGetActiveUniform).

type in : int32

The uniform type (see GL_UNIFORM_TYPE).

size in : int32

The uniform array size (see GL_UNIFORM_SIZE).

offset in : int32

Byte offset of uniform in block (see GL_UNIFORM_OFFSET).

arrayStride in : int32

Byte offset between consecutive array elements (see GL_UNIFORM_ARRAY_STRIDE).

matrixStride in : int32

Byte offset between consecutive major matrix elements (see GL_UNIFORM_MATRIX_STRIDE).

isRowMajor in : bool

Using row-major (true) or column-major (false) matrix layout (see GL_UNIFORM_IS_ROW_MAJOR)?

Declares a program uniform variable.

RenderException

If the given uniform specification is invalid or unsupported.

Program​Object​Reflect​Uniform​Block


protected method ProgramObjectReflectUniformBlock → (4)

program in : int32

The program object.

index in : int32

The uniform block index in program in (see GL_ACTIVE_UNIFORM_BLOCKS), which is expected to be equal to the binding point index (see glUniformBlockBinding).

name in : string

[not-empty]
The uniform block name (see glGetActiveUniformBlockName).

size in : int32

[>0]
The uniform block size, in bytes (see GL_UNIFORM_BLOCK_DATA_SIZE).

Declares a program uniform block.

RenderException

If the given uniform block specification is invalid.

Program​Object​Use


protected abstract method ProgramObjectUse → (1)

program in : int32

The program object name or 0 for none.

Applies the given program in for subsequent use.

The following steps must be performed, in the order given:

  1. Activate the given program in by calling glUseProgram.

  2. Apply the uniform block buffers for the given program in, using uniformBlockBinding and uniformBlockGpu.

  3. Apply the sampler objects for the given program in, using samplerBinding.

  4. Apply the texture units to the uniform variables of the given program in, using uniformTextures.

Render​State​Dirty


protected method RenderStateDirty → (1)

preset in : RenderStatePreset

The render state presets to mark as dirty.

Marks the given render state presets as dirty.

Sampler​Object​Delete


protected abstract method SamplerObjectDelete → (1)

samplerObject in : int32

The sampler object name.

Deletes the given sampler object.

Shader​Object​Create


protected abstract method ShaderObjectCreate → (3)

shaderType in : int32

The shader type, as returned by ShaderObjectType.

code in : string [ ]

The GLSL source code parts.

path in : Path

The GLSL source file, for error reporting.

returns → int32

The compiled shader object.

Compiles the given GLSL shader.

RenderException

If shader creation has failed.

Shader​Object​Delete


protected abstract method ShaderObjectDelete → (1)

shaderObject in : int32

The shader object name.

Deletes the given shader object.

Shader​Object​Error​Message


protected method ShaderObjectErrorMessage → (3)

path in : Path

The file path of the shader.

code in : string

The pre-processed shader code.

infoLog in : string

The shader info log.

returns → string

The failure message.

Builds a failure message for shader compilation.

Shader​Object​Type


Returns the GL shader type for the given shader type index.

Texture​Object​Apply


protected abstract method TextureObjectApply → (3)

textureUnit in : int32

The texture unit index.

texture in : int32

The texture object name or 0 to clear.

target in : int32

The texture bind target (e.g. GL_TEXTURE_2D) or 0 for none.

Applies the given texture object to a texture unit.

Protected / Attributes

Can​Vertex​Attribute​Declare​Array


protected abstract attribute CanVertexAttributeDeclareArray → (get)

value : bool

true if vertex attribute arrays can be consumed,
false if vertex attribute arrays cannot be used.

Can the GL API consume arrays as vertex attribute declarations?

Render​Effect​Identifier


protected virtual attribute RenderEffectIdentifier → (get)

value : string

The render effect identifier or null to disable caching.

Returns the identifier of this render effect that shall be used for naming files in the program binary cache.

sampler​Binding


protected attribute samplerBinding → (Mapping2D<int32>)

Mapping from program object and texture unit to sampler object:

first.X := program object name
first.Y := texture unit index
second  :=  sampler object name

shader​Objects


protected attribute shaderObjects → (Mapping1D<int32>)

Mapping from render effect shader to shader object:

first  := render effect shader index
second := shader object name

shader​Storage​Block​Binding


protected attribute shaderStorageBlockBinding → (Mapping2D<int32>)

Mapping from program and shader storage block index to binding point:

first.X := program object name
first.Y := program-agnostic shader storage block index
second  := shader storage block binding point index

uniform​Block​Binding


protected attribute uniformBlockBinding → (Mapping2D<int32>)

Mapping from program object and uniform block to uniform block binding:

first.X := program object name
first.Y := program-agnostic uniform block index
second  := uniform block binding point index or -1 if not used

uniform​Block​Gpu


protected attribute uniformBlockGpu → (Mapping1D<int32>)

Mapping from uniform block to buffer object:

first  := program-agnostic uniform block index
second := GL buffer object name

uniform​Textures


protected attribute uniformTextures → (Mapping2D<int32 [ ]>)

Mapping from program object and uniform location to associated texture units:

first.X := program object name
first.Y := uniform location
second  := the texture unit index of each uniform element