RenderEffectParameters

Description

abstract class Tinman.Engine.Rendering.RenderEffectParameters

Extended by: CameraParameters ^sealed
DecalParameters ^sealed
Example_DemoParameters ^sealed
GraphicsParameters ^sealed
LightingParameters ^sealed
LineParameters ^sealed
MaterialParameters ^sealed
MaterialPartParameters ^abstract
MeshParameters ^sealed
ModelRendererParameters ^sealed
ProcessParameters ^sealed
RenderEffectParameterArray ^sealed
RendererParameters ^sealed
ShadowCascadeParameters ^sealed
ShadowParameters ^sealed
SkyParameters ^sealed
TerrainMaterialParameters ^sealed
TerrainMaterialSlotParameters ^sealed
TerrainMaterialTextureParameters ^sealed
TerrainParameters ^sealed
TerrainTextureParameters ^sealed
TextureTileParameters ^sealed
TexturingBatchParameters ^sealed

Base interface for classes that represent the parameters of a GPU program.

Render effect parameter sets are defined by implementing classes, usually by providing properties. Parameter modifications are tracked with a 64-bit integer value, where each bit may be interpreted freely by an implementing class. In most cases, there will be a dedicated modification flag for each parameter property. A subclass may declare low-level parameter slots by overriding the Declare method. The Apply method may be overridden in order to apply parameter values to the underlying GPU program.

Here is a checklist for creating an implementing class which follows the standard pattern:

Provide the human-readable name of the render effect parameter set when calling the base constructor:

/// <summary>
///   Creates a new instance of <see cref="MyEffectParameters"/>.
/// </summary>
public MyEffectParameters()
  : base("MyEffect")
{
}

Define a public constant for each render pass of the effect:

/// <summary>
///   Brief description of the render effect pass goes here.
/// </summary>
/// <remarks>
///   Additional information goes here, for example when the render effect is
///   available and which parameters must be initialized for it.
/// </remarks>
public const int PassMyName = 0;

The constant value is the pass index, see IRenderEffectBase.PassCount.

Override the PassName method, in order to provide names for the render effect passes:

public override string PassName(int pass)
{
  switch (pass)
  {
    case PassMyName:
      return "MyName";

    default:
      return base.PassName(pass);
  }
}

For each render effect parameter, add a Changed* flag, a property, a backing field and a low-level parameter slot index field:

/// <summary>
///   Changed flag of <see cref="MyParameter"/>.
/// </summary>
public const int ChangedMyParameter = 1 << ?;
...
/// <summary>
///   Brief description of the render effect parameter.
/// </summary>
/// <remarks>
///   Additional information about the parameter, for example its default value.
/// </remarks>
/// <value>Details on the parameter value.</value>
/// <seealso cref="ChangedMyParameter"/>
public Vec4F MyParameter
{
  get { return myParameter; }
  set
  {
    if (myParameter.Equals(value))
      return;

    myParameter = value;

    Set(ChangedMyParameter);
  }
}
...
Vec4F myParameter;
...
int slotMyParameter;

In the constructor, initialize all backing fields to their default values (if necessary) and all slot* fields to -1.

Override Declare and map the low-level parameters (which are defined by the GPU program) to the render effect parameters (which are defined by the enclosing RenderEffectParameters sub-class), by querying the slot index for a given parameter name, type and count:

public override void Declare(IRenderEffectParameters effect, int flags = 0)
{
  slotMyParameter = effect.ParameterDeclare(
    RenderEffectParameterType.Vector4, "g_myParameter");
}

Because this step defines the interface between the GPU program and the code behind, it should be documented:

/// <summary>
///   Render effect parameters of <see cref="IMyEffect"/>.
/// </summary>
/// <remarks>
///   The following low-level render effect parameter slots are always defined:
///   <list type="bullet">
///     <item>
///       'g_myParameter', <see cref="RenderEffectParameterType.Vector4"/>,
///       mapped to <see cref="MyParameter"/>.
///     </item>
///   </list>
/// </remarks>
public sealed class MyEffectParameters : RenderEffectParameters
{
  ...
}

Override Apply and apply the render effect parameter values to the underlying GPU program, for example by using the IRenderEffectParameters interface:
```
public override void Apply(IRenderEffectParameters effect,
  bool forceTextures = false)
{
  base.Apply(effect, forceTextures);

  if (Has(ChangedMyParameter))
    effect.ParameterVector4(slotMyParameter, 0, myParameter);
}
```
Also implement ClearResources, which must set all render effect parameters with a IResource value to null.

The following methods provide an optional way to define a render effect in a common way which does not depend on a specific render API:

EffectComponents
EffectRenderState
EffectSamplerState

By overriding these methods, redundant code can be avoided in the implementations of RenderEffect.

Public / Methods

Aggregate

public method Aggregate → (2)

child ⁱⁿ : RenderEffectParameters: [not-null]
The child RenderEffectParameters object.
changed ⁱⁿ : int64: The child modification bits.

Aggregates the given child RenderEffectParameters object.

Adding a modification bit via Set will automatically set the corresponding modification bit in the parent. The default implementations of the Apply and ClearResources methods forward calls to the aggregated children.

See also: RenderEffectParameters.Parent
RenderEffectParameters.ChangedParent

Apply

public virtual method Apply → (2)

effect ⁱⁿ : IRenderEffectParameters: The effect.
forceTextures ^opt : bool = false: Force setting of texture parameters, even if their changed flag is not set?

Updates the low-level render effect parameter slots according to the changed parameter values in this object.

This method may optionally be used to provide a standardized mechanism for setting low-level render effect parameters, which can be used for multiple rendering APIs.

The parameter slots must have been declared with Declare. If not, this method will return silently, without applying any parameter values.

The default implementation calls Apply on all changed aggregated children.

ClearResources

public virtual method ClearResources → ()

Clears all resources by setting the corresponding parameters to null.

All parameters that reference resources (see IResource) must be cleared to null by this method.

The default implementation calls ClearResources on all aggregated children.

Declare

[EmptyBody]
public virtual method Declare → (2)

effect ⁱⁿ : IRenderEffectParameters: The render effect for which to declare the low-level parameter slots.
flags ^opt : int32 = 0: Optional flags, to be interpreted by overriding methods. Please refer to the documentation of the respective subclass for details.

Declares all low-level render effect parameter slots.

This method may optionally be used to provide a standardized mechanism for setting low-level render effect parameters, which can be used for multiple rendering APIs.

Different instances of the same RenderEffectParameters class may use different slot indices, which allows instances to be aggregated into different render effects.

RenderException: If an error has occurred while declaring low-level render effect parameter slots.

See also: IRenderEffectParameters.ParameterDeclare

EffectComponents

[EmptyBody]
public virtual method EffectComponents → (2)

effect ⁱⁿ : IRenderEffectComponents: [not-null]
The render effect builder to use.
flags ^opt : int32 = 0: Optional flags, to be interpreted by overriding methods. Please refer to the documentation of the respective subclass for details.

Builds the common render effect components.

The common render effect components do not depend on a specific render API.

RenderException: If an error has occurred while building the common render effect components.

EffectRenderState

[EmptyBody]
public virtual method EffectRenderState → (1)

pass ⁱⁿ : int32: The pass index.
returns → RenderStatePreset: The common render state preset or RenderStatePreset.None if there is none.

Returns the common render state preset for the given render pass ⁱⁿ.

The common render state preset does not depend on a specific render API.

EffectSamplerState

[EmptyBody]
public virtual method EffectSamplerState → (1)

name ⁱⁿ : string: The name of a low-level texture parameter.
returns → SamplerStatePreset: The common sampler state preset or SamplerStatePreset.None if there is none.

Returns the common sampler state preset for the given low-level texture parameter.

The common sampler state preset does not depend on a specific render API.

Has

[Pure]
public method Has → (1)

changed ⁱⁿ : int64: The modification bits to check.
returns → bool: true if one or more modification bits are set,
false if no modification bits are set.

Checks whether any of the given modification bits is set.

See also: RenderEffectParameters.Set

PassName

public virtual method PassName → (1)

pass ⁱⁿ : int32: The pass index.
returns → string: The human-readable name.

Returns a human-readable name for the given pass.

The default implementation returns a string in the form 'Pass-#', where '#' is the zero-based pass index.

Reset

public method Reset → (1)

setOrClear ⁱⁿ : bool: true to set all modification flags, false to clear them.

Sets or clears the modification flags for all parameters.

The default implementation resets the modification flags of all aggregated children.

Public / Attributes

ChangedParent

[Constant]
public attribute ChangedParent → (get)

value : int64: The modification bit or 0 if Parent is 0.

Returns the modification bit of this RenderEffectParameters object in its parent.

See also: RenderEffectParameters.Aggregate

FullName

public attribute FullName → (get)

value : string: [not-null]
The full name.

Returns the full name of this set of render effect parameters.

The full name includes Name, Parent and ChangedParent for the whole chain of aggregated objects.

Name

[Constant]
public attribute Name → (get)

value : string: [not-empty]
The name.

Human-readable name for this set of render effect parameters.

Parent

[Constant]
public attribute Parent → (get)

value : RenderEffectParameters: The parent or null if none.

Returns the parent of this RenderEffectParameters object.

Each time a call to Set adds a modification bit, the change is propagated to the parent (see ChangedParent).

See also: RenderEffectParameters.ChangedParent
RenderEffectParameters.Aggregate

Protected / Constructors