RenderEffect

Description

abstract class Tinman.Engine.Rendering.RenderEffect

Derived from: Disposable ^abstract
IRenderEffectParameters
Extended by: RenderEffectGeneric ^abstract

Non-generic abstract base class of RenderEffectGeneric.

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:

Demarcation methods for activating any of the render effect passes:
IBeginEnd.Begin, IRenderEffectBase.Pass, IBeginEnd.End.
Accessor methods for setting the render effect parameters and updating them during rendering:
IRenderEffect.Parameters, IRenderEffectBase.Apply.

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.

Protected / Constructors

RenderEffect

protected constructor RenderEffect → (4)

parameters ⁱⁿ : RenderEffectParameters: [not-null]
The render effect parameters object.
repositoryPublic ⁱⁿ : Path: [not-null]
The public GPU shader repository path or Path.Unknown if none.
repositoryPrivate ⁱⁿ : Path: [not-null]
The private GPU shader repository path or Path.Unknown if none.
shaderTypeCount ⁱⁿ : int32: [>=1]
The number of shader types.

Creates a new instance of RenderEffect.

Protected / Methods

BuildComponents

protected method BuildComponents → (1)

flags ^opt : int32 = 0: Optional flags to pass to RenderEffectParameters.EffectComponents.

Builds the common render effect components by calling RenderEffectParameters.EffectComponents.

This method will be called automatically (with flags ^opt = 0) when RenderEffectParameters.Declare is called at the end of the concrete implementations constructor. Calling this method multiply times is allowed, but has no further effect.

RenderException: If a graphics subsystem error has occurred.

DoApply

protected abstract method DoApply → ()

Applies the current render effect parameter values.

DoBegin

[EmptyBody]
protected virtual method DoBegin → ()

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

DoBuildComponents

[EmptyBody]
protected virtual method DoBuildComponents → ()

returns → IRenderEffectComponents: The IRenderEffectComponents object.

Returns a IRenderEffectComponents object for building the common parts of this render effect.

DoDataFlow

protected abstract method DoDataFlow → (1)

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

DoEnd

[EmptyBody]
protected virtual method DoEnd → ()

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

DoParameterDeclare

protected abstract method DoParameterDeclare → (4)

slot ⁱⁿ : int32: The parameter slot index.
type ⁱⁿ : RenderEffectParameterType: The parameter type.
name ⁱⁿ : string: The parameter name.
size ⁱⁿ : int32: The parameter size.

Declares a render effect parameter.

RenderException: If a graphics subsystem error has occurred.

DoPassBegin

[EmptyBody]
protected virtual method DoPassBegin → ()

The current render effect pass has just begun.

See also: IRenderEffectBase.PassCurrent

DoPassEnd

[EmptyBody]
protected virtual method DoPassEnd → ()

The current render effect pass is about to end.

See also: IRenderEffectBase.PassCurrent

DoShaderCreate

protected abstract method DoShaderCreate → (3)

type ⁱⁿ : int32: The shader type.
shader ⁱⁿ : 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 ⁱⁿ : Path: Path to the shader 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.

PassCreate

protected method PassCreate → (1)

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

Creates a render effect pass.

After calling this method, IRenderEffectBase.PassAvailable will return true and IRenderEffectBase.PassCount will be equal to or greater than pass ⁱⁿ + 1. Calling this method multiple times for the same pass ⁱⁿ is allowed but has no effect.

ShaderAssign

protected method ShaderAssign → (2)

shader ⁱⁿ : int32: [0..RenderEffect.ShaderObjectCount-1]
The shader object index.
pass ⁱⁿ : int32: [0..IRenderEffectBase.PassCount-1]
The effect pass index.

Assigns a shader object to an effect pass.

The given render effect pass ⁱⁿ must have been created with PassCreate before this method may be called.

See also: RenderEffect.ShaderCreate
RenderEffect.PassCreate

ShaderCreate

protected method ShaderCreate → (3)

type ⁱⁿ : int32: [0..RenderEffect.ShaderTypeCount-1]
The shader type.
file ⁱⁿ : string: [not-empty]
The name of the shader file in the shader repository.
directory ^opt : string = null: Name of the subdirectory in the shader repository that contains file ⁱⁿ or null.
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.

ShaderGet

protected method ShaderGet → (2)

pass ⁱⁿ : int32: [-1..IRenderEffectBase.PassCount-1]
The effect pass index.
type ⁱⁿ : 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 ⁱⁿ assigned to the specified pass ⁱⁿ.

Returns a shader object for the given pass ⁱⁿ.

ShaderType

protected method ShaderType → (1)

shader ⁱⁿ : int32: [0..RenderEffect.ShaderObjectCount-1]
The shader object index.
returns → int32: The shader type.

Returns the type of the given shader.

Protected / Attributes

ShaderObjectCount

protected attribute ShaderObjectCount → (get)

value : int32: [>=1]
The number of shader objects.

The number of shader objects.

ShaderTypeCount

protected attribute ShaderTypeCount → (get)

value : int32: [>=1]
The number of shader types.

The number of shader types.

RenderEffect

Description

Protected / Constructors

Render​Effect

Protected / Methods

Build​Components

Do​Apply

Do​Begin

Do​Build​Components

Do​Data​Flow

Do​End

Do​Parameter​Declare

Do​Pass​Begin

Do​Pass​End

Do​Shader​Create

Pass​Create

Shader​Assign

Shader​Create

Shader​Get

Shader​Type

Protected / Attributes

Shader​Object​Count

Shader​Type​Count

RenderEffect

BuildComponents

DoApply

DoBegin

DoBuildComponents

DoDataFlow

DoEnd

DoParameterDeclare

DoPassBegin

DoPassEnd

DoShaderCreate

PassCreate

ShaderAssign

ShaderCreate

ShaderGet

ShaderType

ShaderObjectCount

ShaderTypeCount