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:

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

Render​Effect


protected constructor RenderEffect → (4)

parameters in : RenderEffectParameters

[not-null]
The render effect parameters object.

repositoryPublic in : Path

[not-null]
The public GPU shader repository path or Path.Unknown if none.

repositoryPrivate in : Path

[not-null]
The private GPU shader repository path or Path.Unknown if none.

shaderTypeCount in : int32

[>=1]
The number of shader types.

Creates a new instance of RenderEffect.

Protected / Methods

Build​Components


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.

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​Build​Components


[EmptyBody]
protected virtual method DoBuildComponents → ()

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

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

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

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.

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

Shader​Create


protected method ShaderCreate → (3)

type in : int32

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

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

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.