IRenderEffectComponents

Description

interface Tinman.Engine.Rendering.Effects.IRenderEffectComponents

Extended by: RenderEffectComponents ^abstract

Base interface for classes that can build components of a IRenderEffect through a common interface which does not depend on a specific render API.

An implementation of IRenderEffect for a specific render API provide an object of this interface to its RenderEffectParameters object, which then build common render effect components. The purpose of this is to extract all common code into a single location, instead of having similar code spread over multiple classes which are distributed over (usually non-related) projects.

See also: RenderEffectParameters.EffectComponents
RenderEffectParameters.EffectRenderState
RenderEffectParameters.EffectSamplerState

Public / Methods

Buffer

public method Buffer → (1)

name ⁱⁿ : string: [not-empty]
The constant buffer name.

The render effect is using a constant buffer of the given name ⁱⁿ.

If a render effect implementation does not require declaration of used constant buffers, calls to this method will be ignored silently. Constant buffer declaration is required for:

Direct3D 9 : no
Direct3D 11 : yes
Direct3D 12 : yes
OpenGL : no
OpenGLES : no

RenderException: If a graphics subsystem error has occurred.

Finish

public method Finish → ()

Finished building of common render effect components.

RenderException: If a graphics subsystem error has occurred.

Manual

public method Manual → (1)

pass ⁱⁿ : int32: [>=0]
The pass index.

Specifies that render state will be set up manually for the given render pass ⁱⁿ.

Pass

public method Pass → (6)

pass ⁱⁿ : int32: [>=0]
The pass index.
s1 ^opt : string = null: A shader specification or null.
s2 ^opt : string = null: A shader specification or null.
s3 ^opt : string = null: A shader specification or null.
s4 ^opt : string = null: A shader specification or null.
s5 ^opt : string = null: A shader specification or null.

Creates shader objects and render passes and associated them with another.

The shader specifications are simple strings, using the following Grammar:

shader := type '|' name '|' id ;

name   := id .. '.' ;
type   := 'VS' | 'TP' | 'TV' | 'GS' | 'PS' | 'SS' | 'CS' ;

id     := char+ ;

char   := 'a'..'z' | 'A'..'Z' | '0'..'9' | '_' | '-' ;

Each call to this method causes a call to RenderEffect.ShaderCreate for each new shader specification, followed by zero or more calls RenderEffect.ShaderAssign. The type mnemonics of a shader specification have the following meaning:

VS : Vertex Shader
TP : Tessellation Patch Shader (aka. Hull Shader, Tessellation Control Shader)
TV : Tessellation Vertex Shader (aka. Domain Shader, Tessellation Evaluation Shader)
GS : Geometry Shader
PS : Pixel Shader (aka. Fragment Shader)
SS : Pixel Shader (running at sample frequency)
CS : Compute Shader

For example, the shader specification…

"VS | My-Shader | Folder"

will use the following shader binary resp. source:

"$(ShaderRepository)/glsl.gl41/Folder/My-Shader{-GL}.glsl"   (OpenGL 4.1)
...
"$(ShaderRepository)/glsl.gl46/Folder/My-Shader{-GL}.glsl"   (OpenGL 4.6)
"$(ShaderRepository)/glsl.gles30/Folder/My-Shader{-GL}.glsl" (OpenGLES 3.0)
...
"$(ShaderRepository)/glsl.gles32/Folder/My-Shader{-GL}.glsl" (OpenGLES 3.2)
"$(ShaderRepository)/hlsl.dx9/Folder/My-Shader.cso"          (Direct3D 9)
"$(ShaderRepository)/hlsl.dx11/Folder/My-Shader.cso"         (Direct3D 11)
"$(ShaderRepository)/hlsl.dx12/Folder/My-Shader.cso"         (Direct3D 12)

The {-GL} token is replaced with a name tag, according to the following rules:

For a shader that is attached to the Geometry Shader stage as input, the -GS tag is used.
For a shader that is attached to the Pixel Shader stage as input, -SF tag is used, if running at sample frequency.
In all other cases, the token is removed and the original shader name is used.

RenderException: If a graphics subsystem error has occurred.

Resource

public method Resource → (2)

name ⁱⁿ : string: [not-empty]
The shader resource name.
buffer ^opt : bool = false: Declare a buffer resource (true) with direct read/write access by the GPU, or a regular texture resource (false)?

Declares a shader resource.

If a render effect implementation does not require declaration of shader resources, calls to this method will be ignored silently. Shader resource declaration is required for:

Direct3D 9 : no
Direct3D 11 : yes
Direct3D 12 : yes
OpenGL : no
OpenGLES : no

Any additional state setup for the shader resource must be performed manually by the IRenderEffect implementation, such as sampler state.

RenderException: If a graphics subsystem error has occurred.

Texture

public method Texture → (2)

name ⁱⁿ : string: [not-empty]
The shader resource name.
sampler ^opt : string = null: The sampler name. If null, name ⁱⁿ will be used after adding the "Sampler" suffix.

Declares a texture resource with a sampler state preset.

The sampler state of the given texture resource will be created automatically, based on RenderEffectParameters.EffectSamplerState.

RenderException: If a graphics subsystem error has occurred.

Vertex

_2 overloads

public method Vertex¹ → (3)

name ⁱⁿ : string: [not-empty]
The name of the vertex attribute, as given in the shader code, without any array size specifier suffixes (e.g. [n]).
data ^opt : int32 = 0: [0..1]
Specifies which vertex buffer to map as input:
0 : per-vertex data (see IGeometryBuffer.Vertices)
1 : per-instance data (see IGeometryBuffer.Instances).
count ^opt : int32 = 1: [>=1]
The number of array elements in the vertex attribute.

Declares an input vertex attribute with implicit usage and index.

This method delegates to Vertex², after inferring the vertex element usage and index from the given vertex attribute name ⁱⁿ, by analysing it with the following Grammar:

vertex := 'semantic_' usage '_' index ;
index  := '0'..'9'[1..2] ;
usage  := @'color' | @'normal' | @'position' | @'tangent' | @'texture' ;

RenderException: If a graphics subsystem error has occurred.

See also: VertexElements
IGeometryBuffer

public method Vertex² → (5)

name ⁱⁿ : string: [not-empty]
The name of the vertex attribute, as given in the shader code, without any array size specifier suffixes (e.g. [n]).
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 an input vertex attribute with explicit usage and index.

If a render effect implementation does not require declaration of vertex attributes, calls to this method will be ignored silently. Vertex attribute declaration is required for:

Direct3D 9 : no
Direct3D 11 : no
Direct3D 12 : no
OpenGL : yes
OpenGLES : yes

RenderException: If a graphics subsystem error has occurred.

See also: VertexElements
IGeometryBuffer