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:

Create render effect passes with RenderEffect.PassCreate.
Create shader objects with RenderEffect.ShaderCreate and assign them to render effect passes with RenderEffect.ShaderAssign.
Declare vertex attributes with VertexAttributeDeclare. Based on the specified value semantics, vertex attributes will then be mapped to the vertex elements (see VertexElements) of the current geometry buffer (see IGeometryBuffer).
Create sampler states with SamplerStateCreate¹ and assign them to texture resources with SamplerStateAssign³.

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:

Declare low-level parameter slots with IRenderEffectParameters.ParameterDeclare, for example by calling RenderEffectParameters.Declare.

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.

See also: GL.COMPUTE_SHADER

FS

public constant FS → (1:int32)

Shader type index: Fragment Shader (GL_FRAGMENT_SHADER)

See also: GL.FRAGMENT_SHADER
GLES.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.

See also: GL.GEOMETRY_SHADER
GLES.GEOMETRY_SHADER

MS

public constant MS → (3:int32)

Shader type index: Mesh Shader (GL_MESH_SHADER_NV)

Mesh shaders are provided by a vendor-specific extension.

See also: GL.MESH_SHADER_NV
GLES.MESH_SHADER_NV

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.

See also: GL.TESS_CONTROL_SHADER
GLES.TESS_CONTROL_SHADER

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.

See also: GL.TESS_EVALUATION_SHADER
GLES.TESS_EVALUATION_SHADER

TS

public constant TS → (6:int32)

Shader type index: Task Shader (GL_TASK_SHADER_NV)

Mesh shaders are provided by a vendor-specific extension.

See also: GL.TASK_SHADER_NV
GLES.TASK_SHADER_NV

VS

public constant VS → (7:int32)

Shader type index: Vertex Shader (GL_VERTEX_SHADER)

See also: GL.VERTEX_SHADER
GLES.VERTEX_SHADER

Public / Methods

RenderStateApply

public abstract method RenderStateApply → (2)

preset ⁱⁿ : 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).

RenderStateDefault

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.

RenderStateSet

public virtual method RenderStateSet → (1)

context ⁱⁿ : 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 ⁱⁿ is negative) and then keeps track of the current render state preset (when context ⁱⁿ is zero, using RenderEffectParameters.EffectRenderState), calling RenderStateApply accordingly to apply resp. revert render states. Finally (when context ⁱⁿ 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.

See also: IRenderEffectBase.PassCurrent
GLEffect.RenderStateDefault
GLEffect.RenderStateApply
GLEffect.RenderStateDirty

SamplerStateApply

public abstract method SamplerStateApply → (2)

sampler ⁱⁿ : int32: The sampler object name.
preset ⁱⁿ : SamplerStatePreset: The sampler state preset to apply.
returns → int32: sampler ⁱⁿ

Applies the given sampler state preset.

See also: GLEffect.SamplerStateCreate¹

SamplerStateAssign

_3 overloads

public method SamplerStateAssign¹ → (1)

name ⁱⁿ : 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 SamplerStateAssign².

RenderException: If a graphics subsystem error has occurred.

public method SamplerStateAssign² → (2)

name ⁱⁿ : string: [not-empty]
The GLSL texture resource name.
sampler ⁱⁿ : 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 SamplerStateCreate³ and then passes the created sampler state object to SamplerStateAssign³.

RenderException: If a graphics subsystem error has occurred.

public method SamplerStateAssign³ → (2)

name ⁱⁿ : string: [not-empty]
The GLSL texture resource name.
sampler ⁱⁿ : 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.

SamplerStateCreate

_3 overloads

[OwnerReturn]
public abstract method SamplerStateCreate¹ → ()

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 SamplerStateCreate².

RenderException: If sampler state creation has failed.

See also: GLEffect.SamplerStateCreate³

public method SamplerStateCreate² → (1)

sampler ⁱⁿ : int32 ^own: The sampler object name, as returned by SamplerStateCreate¹.
returns → int32: The sampler state index, see SamplerStateCount.

Creates a sampler state (step 2 of 2).

[OwnerReturn]
public method SamplerStateCreate³ → (1)

preset ⁱⁿ : 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 SamplerStateCreate¹, then SamplerStateApply, passing preset ⁱⁿ. Finally, it calls SamplerStateCreate² and returns the result.

RenderException: If sampler state creation has failed.

VertexAttributeDeclare

public method VertexAttributeDeclare → (5)

name ⁱⁿ : 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 ⁱⁿ : 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 ⁱⁿ : 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.

See also: VertexElements
IGeometryBuffer

Public / Attributes

SamplerStateCount

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 ⁱⁿ : GLContext: [not-null]
The owning GLContext object.
parameters ⁱⁿ : TParameters: [not-null]
The render effect parameters object.
compilationMacro ⁱⁿ : string: The pre-processor macro to define for shader compilation or null for none.
repositoryPrivate ⁱⁿ : Path: [not-null]
The private GPU shader repository path or Path.Unknown if none.

Creates a new instance of GLEffect.

Protected / Methods

BufferObjectApply

protected abstract method BufferObjectApply → (2)

buffer ⁱⁿ : int32: The buffer object name.
binding ⁱⁿ : int32: The binding point index.

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

BufferObjectCreate

protected abstract method BufferObjectCreate → (1)

size ⁱⁿ : 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.

BufferObjectDelete

protected abstract method BufferObjectDelete → (1)

bufferObject ⁱⁿ : int32: The buffer object name.

Deletes the given buffer object.

BufferObjectUpdate

protected abstract method BufferObjectUpdate → (2)

bufferObject ⁱⁿ : int32: The buffer object name or 0 to clear.
data ⁱⁿ : ByteBuffer: The buffer data or null iff bufferObject ⁱⁿ is 0.

Updates the content of the given buffer object.

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

ParameterType

protected abstract method ParameterType → (1)

type ⁱⁿ : int32: The GL uniform type (see GL_UNIFORM_TYPE).
returns → int32: The RenderEffectParameterType value or -1 iff type ⁱⁿ is not supported.

Returns the render effect parameter type that corresponds

PlatformIdentifier

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.

ProgramObjectBinary

_2 overloads

[EmptyBody]
protected virtual method ProgramObjectBinary¹ → (1)

program ⁱⁿ : 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 ProgramObjectBinary² → (2)

format ⁱⁿ : int32: The binary format.
binary ⁱⁿ : 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.

ProgramObjectBuild

protected abstract method ProgramObjectBuild → (2)

program ⁱⁿ : int32: The empty program object to build or 0 if none.
pass ⁱⁿ : 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.

See also: GLEffect.shaderObjects

ProgramObjectDelete

protected abstract method ProgramObjectDelete → (1)

programObject ⁱⁿ : int32: The program object name.

Deletes the given program object.

ProgramObjectReflect

protected abstract method ProgramObjectReflect → (1)

program ⁱⁿ : 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:

For each active vertex attribute, call the ProgramObjectReflectAttribute method once.
For each uniform block, call the ProgramObjectReflectUniformBlock method once.
For each active uniform, call the ProgramObjectReflectUniform method once.

RenderException: If program reflection has failed.

ProgramObjectReflectAttribute

protected method ProgramObjectReflectAttribute → (4)

program ⁱⁿ : int32: The program object.
name ⁱⁿ : string: The attribute name (see glGetActiveAttrib), not including the [0] suffix.
size ⁱⁿ : int32: The attribute size (see glGetActiveAttrib).
location ⁱⁿ : 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.

See also: GLEffect.ProgramObjectReflect

ProgramObjectReflectShaderStorageBlock

protected method ProgramObjectReflectShaderStorageBlock → (5)

program ⁱⁿ : int32: The program object.
location ⁱⁿ : int32: The shader storage block binding point.
name ⁱⁿ : string: [not-empty]
The shader storage block name.
fields ⁱⁿ : int32: The number of block fields.
size ⁱⁿ : int32: The byte size of the block.

Declares a program shader storage block.

RenderException: If the given shader storage block specification is invalid.

ProgramObjectReflectUniform

protected method ProgramObjectReflectUniform → (10)

program ⁱⁿ : int32: The program object.
location ⁱⁿ : int32: The uniform location in program ⁱⁿ (see glGetUniformLocation).
block ⁱⁿ : string: Name of the containing uniform block (see GL_UNIFORM_BLOCK_INDEX) or null.
name ⁱⁿ : string: The uniform name (see glGetActiveUniform).
type ⁱⁿ : int32: The uniform type (see GL_UNIFORM_TYPE).
size ⁱⁿ : int32: The uniform array size (see GL_UNIFORM_SIZE).
offset ⁱⁿ : int32: Byte offset of uniform in block (see GL_UNIFORM_OFFSET).
arrayStride ⁱⁿ : int32: Byte offset between consecutive array elements (see GL_UNIFORM_ARRAY_STRIDE).
matrixStride ⁱⁿ : int32: Byte offset between consecutive major matrix elements (see GL_UNIFORM_MATRIX_STRIDE).
isRowMajor ⁱⁿ : 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.

See also: GLEffect.ProgramObjectReflect

ProgramObjectReflectUniformBlock

protected method ProgramObjectReflectUniformBlock → (4)

program ⁱⁿ : int32: The program object.
index ⁱⁿ : int32: The uniform block index in program ⁱⁿ (see GL_ACTIVE_UNIFORM_BLOCKS), which is expected to be equal to the binding point index (see glUniformBlockBinding).
name ⁱⁿ : string: [not-empty]
The uniform block name (see glGetActiveUniformBlockName).
size ⁱⁿ : 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.

See also: GLEffect.ProgramObjectReflect

ProgramObjectUse

protected abstract method ProgramObjectUse → (1)

program ⁱⁿ : int32: The program object name or 0 for none.

Applies the given program ⁱⁿ for subsequent use.

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

Activate the given program ⁱⁿ by calling glUseProgram.
Apply the uniform block buffers for the given program ⁱⁿ, using uniformBlockBinding and uniformBlockGpu.
Apply the sampler objects for the given program ⁱⁿ, using samplerBinding.
Apply the texture units to the uniform variables of the given program ⁱⁿ, using uniformTextures.

RenderStateDirty

protected method RenderStateDirty → (1)

preset ⁱⁿ : RenderStatePreset: The render state presets to mark as dirty.

Marks the given render state presets as dirty.

See also: GLEffect.RenderStateApply
GLEffect.RenderStateSet

SamplerObjectDelete

protected abstract method SamplerObjectDelete → (1)

samplerObject ⁱⁿ : int32: The sampler object name.

Deletes the given sampler object.

ShaderObjectCreate

protected abstract method ShaderObjectCreate → (3)

shaderType ⁱⁿ : int32: The shader type, as returned by ShaderObjectType.
code ⁱⁿ : string [ ]: The GLSL source code parts.
path ⁱⁿ : 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.

ShaderObjectDelete

protected abstract method ShaderObjectDelete → (1)

shaderObject ⁱⁿ : int32: The shader object name.

Deletes the given shader object.

ShaderObjectErrorMessage

protected method ShaderObjectErrorMessage → (3)

path ⁱⁿ : Path: The file path of the shader.
code ⁱⁿ : string: The pre-processed shader code.
infoLog ⁱⁿ : string: The shader info log.
returns → string: The failure message.

Builds a failure message for shader compilation.

ShaderObjectType

protected abstract method ShaderObjectType → (1)

type ⁱⁿ : int32

[0..RenderEffect.ShaderTypeCount-1]
The shader type index.

returns → int32

The shader type, one of:

If the given shader type is not supported, 0 is returned.

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

TextureObjectApply

protected abstract method TextureObjectApply → (3)

textureUnit ⁱⁿ : int32: The texture unit index.
texture ⁱⁿ : int32: The texture object name or 0 to clear.
target ⁱⁿ : 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

CanVertexAttributeDeclareArray

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?

RenderEffectIdentifier

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.

samplerBinding

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

shaderObjects

protected attribute shaderObjects → (Mapping1D<int32>)

Mapping from render effect shader to shader object:

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

shaderStorageBlockBinding

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

uniformBlockBinding

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

uniformBlockGpu

protected attribute uniformBlockGpu → (Mapping1D<int32>)

Mapping from uniform block to buffer object:

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

uniformTextures

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

GLEffect

Description

Public / Constants

CS

FS

GS

MS

TCS

TES

TS

VS

Public / Methods

Render​State​Apply

Render​State​Default

Render​State​Set

Sampler​State​Apply

Sampler​State​Assign

Sampler​State​Create

Vertex​Attribute​Declare

Public / Attributes

Sampler​State​Count

Protected / Constructors

GLEffect

Protected / Methods

Buffer​Object​Apply

Buffer​Object​Create

Buffer​Object​Delete

Buffer​Object​Update

Parameter​Type

Platform​Identifier

Program​Object​Binary

Program​Object​Build

Program​Object​Delete

Program​Object​Reflect

Program​Object​Reflect​Attribute

Program​Object​Reflect​Shader​Storage​Block

Program​Object​Reflect​Uniform

Program​Object​Reflect​Uniform​Block

Program​Object​Use

Render​State​Dirty

Sampler​Object​Delete

Shader​Object​Create

Shader​Object​Delete

Shader​Object​Error​Message

Shader​Object​Type

Texture​Object​Apply

Protected / Attributes

Can​Vertex​Attribute​Declare​Array

Render​Effect​Identifier

sampler​Binding

shader​Objects

shader​Storage​Block​Binding

uniform​Block​Binding

uniform​Block​Gpu

uniform​Textures

RenderStateApply

RenderStateDefault

RenderStateSet

SamplerStateApply

SamplerStateAssign

SamplerStateCreate

VertexAttributeDeclare

SamplerStateCount

BufferObjectApply

BufferObjectCreate

BufferObjectDelete

BufferObjectUpdate

ParameterType

PlatformIdentifier

ProgramObjectBinary

ProgramObjectBuild

ProgramObjectDelete

ProgramObjectReflect

ProgramObjectReflectAttribute

ProgramObjectReflectShaderStorageBlock

ProgramObjectReflectUniform

ProgramObjectReflectUniformBlock

ProgramObjectUse

RenderStateDirty

SamplerObjectDelete

ShaderObjectCreate

ShaderObjectDelete

ShaderObjectErrorMessage

ShaderObjectType

TextureObjectApply

CanVertexAttributeDeclareArray

RenderEffectIdentifier

samplerBinding

shaderObjects

shaderStorageBlockBinding

uniformBlockBinding

uniformBlockGpu

uniformTextures