RenderEffectParameters

Description

abstract class Tinman.Engine.Rendering.RenderEffectParameters

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:

  1. 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")
    {
    }
  2. 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.

  3. 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);
      }
    }
  4. 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.

  5. 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
    {
      ...
    }
  6. 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:

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

Public / Methods

Apply


[EmptyBody]
public virtual method Apply → (2)

effect in : 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 Changed1 → (1)

changed in : int64

The modification bits to set.

Sets the given modification bits.


[Pure]
public virtual method Changed2 → ()

returns → int64

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

Returns the changed parameters.

Changed​All


public virtual method ChangedAll → (1)

changed in : bool

true to set the changed flags, false to clear them.

Sets or clears the changed flags for all parameters.

Changed​Mask


[Pure]
public method ChangedMask → (1)

mask in : int64

The bitmask to return.

returns → int64

The value of mask in if Changed2 returns non-zero,
0 zero otherwise.

Returns a bitmask if at least one parameter has changed.

Clear​Resources


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

Effect​Components


[EmptyBody]
public virtual method EffectComponents → (2)

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

Effect​Render​State


[EmptyBody]
public virtual method EffectRenderState → (1)

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

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

Effect​Sampler​State


[EmptyBody]
public virtual method EffectSamplerState → (1)

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

Pass​Name


public virtual method PassName → (1)

pass in : 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

Render​Effect​Parameters


protected constructor RenderEffectParameters → (1)

name in : string

[not-empty]
Human-readable name for this set of render effect parameters.

Creates a new instance of RenderEffectParameters.