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:

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

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.

FRAG


public constant FRAG → (1:int32)

Shader type index: Fragment Shader (GL_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.

MESH


public constant MESH → (3:int32)

Shader type index: Mesh Shader (GL_MESH_SHADER_NV)

Mesh shaders are provided by a vendor-specific extension.

TASK


public constant TASK → (4:int32)

Shader type index: Task Shader (GL_TASK_SHADER_NV)

Mesh shaders are provided by a vendor-specific extension.

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.

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.

VERT


public constant VERT → (7:int32)

Shader type index: Vertex Shader (GL_VERTEX_SHADER)

Public / Methods

RenderStateApply


public abstract method RenderStateApply → (1)

preset in : 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.

SamplerStateApply


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.

SamplerStateAssign


public method SamplerStateAssign → (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.

SamplerStateCreate

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

Then, call SamplerStateCreate3.

RenderException

If sampler state creation has failed.


public method SamplerStateCreate2 → (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 SamplerStateDefault and SamplerStateApply, passing preset in. Finally, it calls SamplerStateCreate3 and returns the result.

RenderException

If sampler state creation has failed.


public method SamplerStateCreate3 → (1)

sampler in : int32

The sampler object name, as returned by SamplerStateCreate1.

returns → int32

The sampler state index, see SamplerStateCount.

Creates a sampler state (step 2 of 2).

SamplerStateDefault


public abstract method SamplerStateDefault → (1)

sampler in : int32

The sampler object name.

returns → int32

sampler in

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

VertexAttributeDeclare


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

in vec4 vs_color[2];
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

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 in : TParameters

[not-null]
The render effect parameters object.

path in : Path

[not-null]
The shader repository path.

compilationMacro in : 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 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.

BufferObjectDelete


protected abstract method BufferObjectDelete → (1)

bufferObject in : int32

The buffer object name.

Deletes the given buffer object.

BufferObjectUpdate


protected abstract method BufferObjectUpdate → (2)

bufferObject in : int32

The buffer object name.

data in : ByteBuffer

The buffer data.

Updates the content of the given buffer object.

ParameterType


protected abstract method ParameterType → (1)

type in : int32

The GL uniform type (see GL_UNIFORM_OFFSET).

returns → int32

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

Returns the render effect parameter type that corresponds

ProgramObjectCreate


protected abstract method ProgramObjectCreate → (1)

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.

ProgramObjectDelete


protected abstract method ProgramObjectDelete → (1)

programObject in : int32

The program object name.

Deletes the given program object.

ProgramObjectReflect


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.

ProgramObjectReflectAttribute


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

  1. location+size[++

Declares a program vertex attribute.

RenderException

If the given vertex attribute specification is invalid or unsupported.

ProgramObjectReflectUniform


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.

ProgramObjectReflectUniformBlock


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.

ProgramObjectUse


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.

SamplerObjectDelete


protected abstract method SamplerObjectDelete → (1)

samplerObject in : int32

The sampler object name.

Deletes the given sampler object.

ShaderObjectCreate


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.

ShaderObjectDelete


protected abstract method ShaderObjectDelete → (1)

shaderObject in : int32

The shader object name.

Deletes the given shader object.

ShaderObjectErrorMessage


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.

ShaderObjectType


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

TextureObjectApply


protected abstract method TextureObjectApply → (5)

textureUnit in : int32

The texture unit index.

texture in : int32

The texture object name or 0.

sampler in : int32

The sampler object name or 0.

target2D in : bool

Bind to GL_TEXTURE_2D_ARRAY?

targetCube in : bool

Bind to GL_TEXTURE_CUBE_MAP?

Applies the given texture object to a texture unit.

VertexAttributesApply


protected abstract method VertexAttributesApply → (2)

program in : int32

The program object name.

buffer in : IGeometryBuffer

The geometry buffer.

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

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