GLEffect

Description

abstract class Tinman.AddOns.API.GLEffect
→ <TParameters : RenderEffectParameters>

Derived from: RenderEffect<TParameters> ^abstract
Extended by: OpenGLEffect ^abstract
OpenGLESEffect ^abstract

Full source code is included in the Tinman 3D SDK download.

Abstract base class for IRenderEffect implementations for OpenGL 4.1 Core Profile and OpenGLES 3.0.

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.

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

COMP

public constant COMP → (0:int32)

Shader type index: Compute Shader (GL_COMPUTE_SHADER)

Compute shaders are not available in OpenGLES 3.0.

See also: GL.COMPUTE_SHADER

FRAG

public constant FRAG → (1:int32)

Shader type index: Fragment Shader (GL_FRAGMENT_SHADER)

See also: GL.FRAGMENT_SHADER
GLES.FRAGMENT_SHADER

GEOM

public constant GEOM → (2:int32)

Shader type index: Geometry Shader (GL_GEOMETRY_SHADER)

Geometry shaders are provided by an extension in OpenGLES 3.0.

See also: GL.GEOMETRY_SHADER
GLES.GEOMETRY_SHADER_EXT

MESH

public constant MESH → (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

TASK

public constant TASK → (4: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

TESC

public constant TESC → (5:int32)

Shader type index: Tessellation Control Shader (GL_TESS_CONTROL_SHADER)

Tessellation shaders are provided by an extension in OpenGLES 3.0.

See also: GL.TESS_CONTROL_SHADER
GLES.TESS_CONTROL_SHADER_EXT

TESE

public constant TESE → (6:int32)

Shader type index: Tessellation Evaluation Shader (GL_TESS_EVALUATION_SHADER)

Tessellation shaders are provided by an extension in OpenGLES 3.0.

See also: GL.TESS_EVALUATION_SHADER
GLES.TESS_EVALUATION_SHADER_EXT

VERT

public constant VERT → (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 → (1)

preset ⁱⁿ : RenderStatePreset: The render state preset to apply.

Applies the given render state preset.

RenderStateDefault

public abstract method RenderStateDefault → ()

Applies default render state values.

See the documentation of the implementing subclass of GLEffect for details on which default render state values are set, because the set of default render state values is different between GL APIs (e.g. OpenGL 4.1 vs. OpenGLES 3.0).

RenderStateSet

public abstract method RenderStateSet → ()

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.

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

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

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 and the following helpers:

Then, call SamplerStateCreate³.

RenderException: If sampler state creation has failed.

See also: GLEffect.SamplerStateCreate²

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 SamplerStateDefault and SamplerStateApply, passing preset ⁱⁿ. Finally, it calls SamplerStateCreate³ and returns the result.

RenderException: If sampler state creation has failed.

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

SamplerStateDefault

public abstract method SamplerStateDefault → (1)

sampler ⁱⁿ : int32: The sampler object name.
returns → int32: sampler ⁱⁿ

Applies default sampler state values.

See the documentation of the implementing subclass of GLEffect for details on which default sampler state values are set, because the set of default sampler state values is different between GL APIs (e.g. OpenGL 4.1 vs. OpenGLES 3.0).

See also: GLEffect.SamplerStateCreate¹

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], if any. For example, vs_color for a vertex attribute like:

in vec4 vs_color[2];

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 → (3)

parameters ⁱⁿ : TParameters: [not-null]
The render effect parameters object.
path ⁱⁿ : Path: [not-null]
The shader repository path.
compilationMacro ⁱⁿ : string: [not-empty]
The pre-processor macro to define for shader compilation.

Creates a new instance of GLEffect.

Protected / Methods

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.
data ⁱⁿ : ByteBuffer: The buffer data.

Updates the content of the given buffer object.

ParameterType

protected abstract method ParameterType → (1)

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

Returns the render effect parameter type that corresponds

ProgramObjectCreate

protected abstract method ProgramObjectCreate → (1)

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

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.

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 → (5)

textureUnit ⁱⁿ : int32: The texture unit index.
texture ⁱⁿ : int32: The texture object name or 0.
sampler ⁱⁿ : int32: The sampler object name or 0.
target2D ⁱⁿ : bool: Bind to GL_TEXTURE_2D_ARRAY?
targetCube ⁱⁿ : bool: Bind to GL_TEXTURE_CUBE_MAP?

Applies the given texture object to a texture unit.

VertexAttributesApply

protected abstract method VertexAttributesApply → (2)

program ⁱⁿ : int32: The program object name.
buffer ⁱⁿ : IGeometryBuffer: The geometry buffer.

Applies the vertex attribute specification for the given program ⁱⁿ and geometry buffer ⁱⁿ.

See also: GLEffect.vertexAttributeLocation

Protected / Attributes

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

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

uniformSlot

protected attribute uniformSlot → (Mapping2D<int32>)

Mapping from render effect parameter to uniform index:

first.X := render effect parameter slot index
first.Y := program object name or 0
second := if first.Y is 0:
          program-agnostic uniform index or -1 if none
          otherwise:
          program-specific uniform location or -1 if none

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.

vertexAttributeLocation

protected attribute vertexAttributeLocation → (Mapping2D<int32>)

Mapping from program object and vertex element usage ID to vertex attribute location:

first.X := program object name
first.Y := vertex element usage ID
second  := vertex attribute location index

See also: VertexElements.UsageId

GLEffect

Description

Public / Constants

COMP

FRAG

GEOM

MESH

TASK

TESC

TESE

VERT

Public / Methods

Render​State​Apply

Render​State​Default

Render​State​Set

Sampler​State​Apply

Sampler​State​Assign

Sampler​State​Create

Sampler​State​Default

Vertex​Attribute​Declare

Public / Attributes

Sampler​State​Count

Protected / Constructors

GLEffect

Protected / Methods

Buffer​Object​Create

Buffer​Object​Delete

Buffer​Object​Update

Parameter​Type

Program​Object​Create

Program​Object​Delete

Program​Object​Reflect

Program​Object​Reflect​Attribute

Program​Object​Reflect​Uniform

Program​Object​Reflect​Uniform​Block

Program​Object​Use

Sampler​Object​Delete

Shader​Object​Create

Shader​Object​Delete

Shader​Object​Error​Message

Shader​Object​Type

Texture​Object​Apply

Vertex​Attributes​Apply

Protected / Attributes

sampler​Binding

shader​Objects

uniform​Block​Binding

uniform​Block​Gpu

uniform​Slot

uniform​Textures

vertex​Attribute​Location

RenderStateApply

RenderStateDefault

RenderStateSet

SamplerStateApply

SamplerStateAssign

SamplerStateCreate

SamplerStateDefault

VertexAttributeDeclare

SamplerStateCount

BufferObjectCreate

BufferObjectDelete

BufferObjectUpdate

ParameterType

ProgramObjectCreate

ProgramObjectDelete

ProgramObjectReflect

ProgramObjectReflectAttribute

ProgramObjectReflectUniform

ProgramObjectReflectUniformBlock

ProgramObjectUse

SamplerObjectDelete

ShaderObjectCreate

ShaderObjectDelete

ShaderObjectErrorMessage

ShaderObjectType

TextureObjectApply

VertexAttributesApply

samplerBinding

shaderObjects

uniformBlockBinding

uniformBlockGpu

uniformSlot

uniformTextures

vertexAttributeLocation