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;

    Changed(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)
{
  long changed;

  changed = Changed();

  if ((changed & ChangedMyParameter) != 0)
    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

Apply

[EmptyBody]
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.

Changed

_2 overloads

public method Changed¹ → (1)

changed ⁱⁿ : int64: The modification bits to set.

Sets the given modification bits.

See also: RenderEffectParameters.ChangedAll

[Pure]
public virtual method Changed² → ()

returns → int64: Bitmask of changed parameters. See the Changed* constants that are defined by the respective subclass.

Returns the changed parameters.

ChangedAll

public virtual method ChangedAll → (1)

changed ⁱⁿ : bool: true to set the changed flags, false to clear them.

Sets or clears the changed flags for all parameters.

ChangedMask

[Pure]
public method ChangedMask → (1)

mask ⁱⁿ : int64: The bitmask to return.
returns → int64: The value of mask ⁱⁿ if Changed² returns non-zero,
0 zero otherwise.

Returns a bitmask if at least one parameter has changed.

ClearResources

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

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.

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.

Public / Attributes

Name

public attribute Name → (get)

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

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

Protected / Constructors