RenderEffect

Description

abstract class Tinman.Engine.Rendering.RenderEffect
<TParameters : RenderEffectParameters>

Derived from

Disposable abstract
IRenderEffect<TParameters>
IRenderEffectParameters

Extended by

DirectX9Effect abstract
DirectXEffect abstract
GLEffect abstract

Abstract base class for IRenderEffect implementations.

From a high-level perspective, a render effect object provides an abstraction that makes it possible to use the effect in a uniform way, regardless of the actual GPU/API-specific implementation underneath:

Seen from a low-level perspective, a render effect object encapsulates the following GPU entities:

  • One or more shader programs of different types (e.g. pixel shader, vertex shader). Usually written in a shading language (e.g. HLSL, GLSL), shader programs are compiled into shader binaries at build-time using an external tool (e.g. fxc, dxc, glslc) or at run-time using some compiler service of the API (e.g. OpenGL). The shader binaries are loaded by the render effect object.

  • Management of logical parameter slots, based on the parameters that are defined in the shader programs. For example, the same parameter definition in a Direct3D9 shader program may be mapped to different shader types (VS, PS) and passes.

  • GPU render states for each render effect pass (e.g. state block management for Direct3D 9).

  • Handling of render effect parameter values (e.g. constant buffer management for Direct3D 11).

  • Handling of input resources, such as textures and samplers.

The default implementation of IRenderEffectBase.PassAvailable always returns true.

Protected / Constructors

Render​Effect


protected constructor RenderEffect → (3)

parameters in : TParameters

[not-null]
The render effect parameters object.

path in : Path

[not-null]
The shader repository path.

shaderTypeCount in : int32

[>=1]
The number of shader types.

Creates a new instance of RenderEffect.

Protected / Methods

Do​Apply


protected abstract method DoApply → ()

Applies the current render effect parameter values.

Do​Begin


[EmptyBody]
protected virtual method DoBegin → ()

This method is called when the top-most call to IBeginEnd.Begin has been made.

Do​Data​Flow


protected abstract method DoDataFlow → (1)

type in : int32

The source shader type or -1-N to return the first shader type of the N-th pipeline.

returns → int32

The target shader type or -1 if none.

Queries the pipeline data-flow for the given shader type.

Do​End


[EmptyBody]
protected virtual method DoEnd → ()

This method is called when the top-most call to IBeginEnd.End has been made.

Do​Parameter​Declare


protected abstract method DoParameterDeclare → (4)

slot in : int32

The parameter slot index.

type in : RenderEffectParameterType

The parameter type.

name in : string

The parameter name.

size in : int32

The parameter size.

Declares a render effect parameter.

RenderException

If a graphics subsystem error has occurred.

Do​Pass​Begin


[EmptyBody]
protected virtual method DoPassBegin → ()

The current render effect pass has just begun.

Do​Pass​End


[EmptyBody]
protected virtual method DoPassEnd → ()

The current render effect pass is about to end.

Do​Shader​Create


protected abstract method DoShaderCreate → (3)

type in : int32

The shader type.

shader in : int32

The shader object index. Will be 0 for the shader that is created first and will increase by one for each additional shader.

binary in : Path

Path to the shader binary file.

Creates a shader object.

IOException

If an error has occurred while loading the shader binary and/or metadata.

ValidatingException

If the shader metadata has an unsupported format and cannot be decoded.

RenderException

If a graphics subsystem error has occurred.

Pass​Create


protected method PassCreate → (1)

pass in : int32

[>=0]
The render effect pass index.

Creates a render effect pass.

Shader​Assign


protected method ShaderAssign → (2)

shader in : int32

[0..RenderEffect.ShaderObjectCount-1]
The shader object index.

pass in : int32

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

Assigns a shader object to an effect pass.

Render effect passes are created implicitly by assigning shader objects to them.

Shader​Create


protected method ShaderCreate → (2)

type in : int32

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

binary in : string

[not-empty]
The file name of the compiled shader binary in the shader repository.

returns → int32

The shader object index.

Creates a shader object.

IOException

If an error has occurred while loading the shader binary and/or metadata.

ValidatingException

If the shader metadata has an unsupported format and cannot be decoded.

RenderException

If a graphics subsystem error has occurred.

Shader​Get


protected method ShaderGet → (2)

pass in : int32

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

type in : int32

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

returns → int32

The shader object index or -1 iff there is no shader of the given type in assigned to the specified pass in.

Returns a shader object for the given pass in.

Shader​Type


protected method ShaderType → (1)

shader in : int32

[0..RenderEffect.ShaderObjectCount-1]
The shader object index.

returns → int32

The shader type.

Returns the type of the given shader.

Protected / Attributes

Shader​Object​Count


protected attribute ShaderObjectCount → (get)

value : int32

[>=1]
The number of shader objects.

The number of shader objects.

Shader​Type​Count


protected attribute ShaderTypeCount → (get)

value : int32

[>=1]
The number of shader types.

The number of shader types.