C# Class Axiom.Graphics.Pass

Class defining a single pass of a Technique (of a Material), ie a single rendering call.
Rendering can be repeated with many passes for more complex effects. Each pass is either a fixed-function pass (meaning it does not use a vertex or fragment program) or a programmable pass (meaning it does use either a vertex or a fragment program, or both).

Programmable passes are complex to define, because they require custom programs and you have to set all constant inputs to the programs (like the position of lights, any base material colors you wish to use etc), but they do give you much total flexibility over the algorithms used to render your pass, and you can create some effects which are impossible with a fixed-function pass. On the other hand, you can define a fixed-function pass in very little time, and you can use a range of fixed-function effects like environment mapping very easily, plus your pass will be more likely to be compatible with older hardware. There are pros and cons to both, just remember that if you use a programmable pass to create some great effects, allow more time for definition and testing.

Inheritance: DisposableObject
Datei anzeigen Open project: mono-soc-2011/axiom Class Usage Examples

Public Properties

Property Type Description
passId int

Protected Properties

Property Type Description
nextPassId int
passLock Object
queuedForDeletion bool
shadowCasterVertexProgramUsage GpuProgramUsage
textureUnitStates TextureUnitStateList

Private Properties

Property Type Description
Load void
NotifyNeedsRecompile void
RecalculateHash void
Unload void
UpdateAutoParams void

Public Methods

Method Description
AddTextureUnitState ( TextureUnitState state ) : void

Adds the passed in TextureUnitState, to the existing Pass.
ApplyTextureAliases ( string>.Dictionary aliasList, bool apply ) : bool
Clone ( Technique parent, int index ) : Pass

Method for cloning a Pass object.
CopyTo ( Pass target ) : void

Copy the details of this pass to the target pass.
CreateTextureUnitState ( ) : TextureUnitState

Overloaded method.
CreateTextureUnitState ( string textureName ) : TextureUnitState

Overloaded method.
CreateTextureUnitState ( string textureName, int texCoordSet ) : TextureUnitState

Inserts a new TextureUnitState object into the Pass.

This unit is is added on top of all previous texture units.

Applies to both fixed-function and programmable passes.

DirtyHash ( ) : void

Mark the hash for this pass as dirty.
GetHashCode ( ) : int

Gets the 'hash' of this pass, ie a precomputed number to use for sorting.

This hash is used to sort passes, and for this reason the pass is hashed using firstly its index (so that all passes are rendered in order), then by the textures which it's TextureUnitState instances are using.

GetTextureUnitState ( int index ) : TextureUnitState

Gets a reference to the TextureUnitState for this pass at the specified indx.
Pass ( Technique parent, int index ) : System

Default constructor.
ProcessPendingUpdates ( ) : void

Process all dirty and pending deletion passes.
QueueForDeletion ( ) : void

Queue this pass for deletion when appropriate.
RemoveAllTextureUnitStates ( ) : void

Removes all texture unit settings from this pass.
RemoveTextureUnitState ( TextureUnitState state ) : void

Removes the specified TextureUnitState from this pass.
RemoveTextureUnitState ( int index ) : void

Removes the specified TextureUnitState from this pass.
SetAlphaRejectSettings ( CompareFunction alphaRejectFunction, int value ) : void

Sets the way the pass will have use alpha to totally reject pixels from the pipeline.

The default is i.e. alpha is not used to reject pixels.

This option applies in both the fixed function and the programmable pipeline.
SetDepthBias ( float constantBias ) : void
SetDepthBias ( float constantBias, float slopeBias ) : void

Sets the depth bias to be used for this Pass.

When polygons are coplanar, you can get problems with 'depth fighting' (or 'z fighting') where the pixels from the two polys compete for the same screen pixel. This is particularly a problem for decals (polys attached to another surface to represent details such as bulletholes etc.).

A way to combat this problem is to use a depth bias to adjust the depth buffer value used for the decal such that it is slightly higher than the true value, ensuring that the decal appears on top. There are two aspects to the biasing, a constant bias value and a slope-relative biasing value, which varies according to the maximum depth slope relative to the camera, ie: 

finalBias = maxSlope * slopeScaleBias + constantBias
Note that slope scale bias, whilst more accurate, may be ignored by old hardware.
SetFog ( bool overrideScene ) : void

Overloaded method.
SetFog ( bool overrideScene, FogMode mode ) : void

Overloaded method.
SetFog ( bool overrideScene, FogMode mode, ColorEx color ) : void

Overloaded method.
SetFog ( bool overrideScene, FogMode mode, ColorEx color, float density ) : void

Overloaded method.
SetFog ( bool overrideScene, FogMode mode, ColorEx color, float density, float start, float end ) : void

Sets the fogging mode applied to this pass.

Fogging is an effect that is applied as polys are rendered. Sometimes, you want fog to be applied to an entire scene. Other times, you want it to be applied to a few polygons only. This pass-level specification of fog parameters lets you easily manage both.

The SceneManager class also has a SetFog method which applies scene-level fog. This method lets you change the fog behavior for this pass compared to the standard scene-level fog.

SetFragmentProgram ( string name ) : void

SetFragmentProgram ( string name, bool resetParams ) : void

SetGeometryProgram ( string name ) : void

SetGeometryProgram ( string name, bool resetParams ) : void

SetRunOncePerLight ( bool enabled ) : void
SetRunOncePerLight ( bool enabled, bool onlyForOneLightType ) : void
SetRunOncePerLight ( bool enabled, bool onlyForOneLightType, LightType lightType ) : void

Sets whether or not this pass should be run once per light which can affect the object being rendered.

The default behavior for a pass (when this option is 'false'), is for a pass to be rendered only once, with all the lights which could affect this object set at the same time (up to the maximum lights allowed in the render system, which is typically 8).

Setting this option to 'true' changes this behavior, such that instead of trying to issue render this pass once per object, it is run once per light which can affect this object. In this case, only light index 0 is ever used, and is a different light every time the pass is issued, up to the total number of lights which is affecting this object. This has 2 advantages:

  • There is no limit on the number of lights which can be supported
  • It's easier to write vertex / fragment programs for this because a single program can be used for any number of lights
However, this technique is a lot more expensive, and typically you will want an additional ambient pass, because if no lights are affecting the object it will not be rendered at all, which will look odd even if ambient light is zero (imagine if there are lit objects behind it - the objects silhouette would not show up). Therefore, use this option with care, and you would be well advised to provide a less expensive fallback technique for use in the distance.

Note: The number of times this pass runs is still limited by the maximum number of lights allowed as set in MaxLights, so you will never get more passes than this.

SetSceneBlending ( SceneBlendFactor src, SceneBlendFactor dest ) : void

Allows very fine control of blending this Pass with the existing contents of the scene.

Wheras the texture blending operations seen in the TextureUnitState class are concerned with blending between texture layers, this blending is about combining the output of the material as a whole with the existing contents of the rendering target. This blending therefore allows object transparency and other special effects.

This version of the method allows complete control over the blending operation, by specifying the source and destination blending factors. The result of the blending operation is: final = (texture * sourceFactor) + (pixel * destFactor)

Each of the factors is specified as one of a number of options, as specified in the SceneBlendFactor enumerated type.

This method is applicable for both the fixed-function and programmable pipelines.

SetSceneBlending ( SceneBlendType type ) : void

Sets the kind of blending this pass has with the existing contents of the scene.

Whereas the texture blending operations seen in the TextureUnitState class are concerned with blending between texture layers, this blending is about combining the output of the Pass as a whole with the existing contents of the rendering target. This blending therefore allows object transparency and other special effects. If all passes in a technique have a scene blend, then the whole technique is considered to be transparent.

This method allows you to select one of a number of predefined blending types. If you require more control than this, use the alternative version of this method which allows you to specify source and destination blend factors.

This method is applicable for both the fixed-function and programmable pipelines.

SetShadowCasterFragmentProgram ( string name ) : void

SetShadowCasterVertexProgram ( string name ) : void

SetShadowReceiverFragmentProgram ( string name ) : void

SetShadowReceiverVertexProgram ( string name ) : void

SetVertexProgram ( string name ) : void

SetVertexProgram ( string name, bool resetParams ) : void

Split ( int numUnits ) : Pass

Splits this Pass to one which can be handled in the number of texture units specified.
UpdateAutoParamsLightsOnly ( AutoParamDataSource source ) : void

Update any automatic light parameters on this pass.
UpdateAutoParamsNoLights ( AutoParamDataSource source ) : void

Update any automatic parameters (except lights) on this pass.

Private Methods

Method Description
Load ( ) : void

Internal method for loading this pass.
NotifyNeedsRecompile ( ) : void

Tells the pass that it needs recompilation.
RecalculateHash ( ) : void

Internal method for recalculating the hash code used for sorting passes.
Unload ( ) : void

Internal method for unloaded this pass.
UpdateAutoParams ( AutoParamDataSource source, GpuProgramParameters mask ) : void

Method Details

AddTextureUnitState() public method

Adds the passed in TextureUnitState, to the existing Pass.
public AddTextureUnitState ( TextureUnitState state ) : void
state TextureUnitState TextureUnitState to add to this pass.
return void

ApplyTextureAliases() public method

public ApplyTextureAliases ( string>.Dictionary aliasList, bool apply ) : bool
aliasList string>.Dictionary
apply bool
return bool

Clone() public method

Method for cloning a Pass object.
public Clone ( Technique parent, int index ) : Pass
parent Technique Parent technique that will own this cloned Pass.
index int
return Pass

CopyTo() public method

Copy the details of this pass to the target pass.
public CopyTo ( Pass target ) : void
target Pass Destination pass to copy this pass's attributes to.
return void

CreateTextureUnitState() public method

Overloaded method.
public CreateTextureUnitState ( ) : TextureUnitState
return TextureUnitState

CreateTextureUnitState() public method

Overloaded method.
public CreateTextureUnitState ( string textureName ) : TextureUnitState
textureName string The basic name of the texture (i.e. brickwall.jpg)
return TextureUnitState

CreateTextureUnitState() public method

Inserts a new TextureUnitState object into the Pass.
This unit is is added on top of all previous texture units.

Applies to both fixed-function and programmable passes.

public CreateTextureUnitState ( string textureName, int texCoordSet ) : TextureUnitState
textureName string The basic name of the texture (i.e. brickwall.jpg)
texCoordSet int The index of the texture coordinate set to use.
return TextureUnitState

DirtyHash() public method

Mark the hash for this pass as dirty.
public DirtyHash ( ) : void
return void

GetHashCode() public method

Gets the 'hash' of this pass, ie a precomputed number to use for sorting.
This hash is used to sort passes, and for this reason the pass is hashed using firstly its index (so that all passes are rendered in order), then by the textures which it's TextureUnitState instances are using.
public GetHashCode ( ) : int
return int

GetTextureUnitState() public method

Gets a reference to the TextureUnitState for this pass at the specified indx.
public GetTextureUnitState ( int index ) : TextureUnitState
index int Index of the state to retreive.
return TextureUnitState

Pass() public method

Default constructor.
public Pass ( Technique parent, int index ) : System
parent Technique Technique that owns this Pass.
index int Index of this pass.
return System

ProcessPendingUpdates() public static method

Process all dirty and pending deletion passes.
public static ProcessPendingUpdates ( ) : void
return void

QueueForDeletion() public method

Queue this pass for deletion when appropriate.
public QueueForDeletion ( ) : void
return void

RemoveAllTextureUnitStates() public method

Removes all texture unit settings from this pass.
public RemoveAllTextureUnitStates ( ) : void
return void

RemoveTextureUnitState() public method

Removes the specified TextureUnitState from this pass.
public RemoveTextureUnitState ( TextureUnitState state ) : void
state TextureUnitState A reference to the TextureUnitState to remove from this pass.
return void

RemoveTextureUnitState() public method

Removes the specified TextureUnitState from this pass.
public RemoveTextureUnitState ( int index ) : void
index int Index of the TextureUnitState to remove from this pass.
return void

SetAlphaRejectSettings() public method

Sets the way the pass will have use alpha to totally reject pixels from the pipeline.
The default is i.e. alpha is not used to reject pixels.

This option applies in both the fixed function and the programmable pipeline.

public SetAlphaRejectSettings ( CompareFunction alphaRejectFunction, int value ) : void
alphaRejectFunction CompareFunction The comparison which must pass for the pixel to be written.
value int value against which alpha values will be tested [(0-255]
return void

SetDepthBias() public method

public SetDepthBias ( float constantBias ) : void
constantBias float
return void

SetDepthBias() public method

Sets the depth bias to be used for this Pass.
When polygons are coplanar, you can get problems with 'depth fighting' (or 'z fighting') where the pixels from the two polys compete for the same screen pixel. This is particularly a problem for decals (polys attached to another surface to represent details such as bulletholes etc.).

A way to combat this problem is to use a depth bias to adjust the depth buffer value used for the decal such that it is slightly higher than the true value, ensuring that the decal appears on top. There are two aspects to the biasing, a constant bias value and a slope-relative biasing value, which varies according to the maximum depth slope relative to the camera, ie: 

finalBias = maxSlope * slopeScaleBias + constantBias
Note that slope scale bias, whilst more accurate, may be ignored by old hardware.
public SetDepthBias ( float constantBias, float slopeBias ) : void
constantBias float The constant bias value, expressed as a factor of the minimum observable depth
slopeBias float The slope-relative bias value, expressed as a factor of the depth slope
return void

SetFog() public method

Overloaded method.
public SetFog ( bool overrideScene ) : void
overrideScene bool /// If true, you authorise this pass to override the scene's fog params with it's own settings. /// If you specify false, so other parameters are necessary, and this is the default behaviour for passs. ///
return void

SetFog() public method

Overloaded method.
public SetFog ( bool overrideScene, FogMode mode ) : void
overrideScene bool /// If true, you authorise this pass to override the scene's fog params with it's own settings. /// If you specify false, so other parameters are necessary, and this is the default behaviour for passs. ///
mode FogMode /// Only applicable if is true. You can disable fog which is turned on for the /// rest of the scene by specifying FogMode.None. Otherwise, set a pass-specific fog mode as /// defined in the enum FogMode. ///
return void

SetFog() public method

Overloaded method.
public SetFog ( bool overrideScene, FogMode mode, ColorEx color ) : void
overrideScene bool /// If true, you authorise this pass to override the scene's fog params with it's own settings. /// If you specify false, so other parameters are necessary, and this is the default behaviour for passs. ///
mode FogMode /// Only applicable if is true. You can disable fog which is turned on for the /// rest of the scene by specifying FogMode.None. Otherwise, set a pass-specific fog mode as /// defined in the enum FogMode. ///
color ColorEx /// The color of the fog. Either set this to the same as your viewport background color, /// or to blend in with a skydome or skybox. ///
return void

SetFog() public method

Overloaded method.
public SetFog ( bool overrideScene, FogMode mode, ColorEx color, float density ) : void
overrideScene bool /// If true, you authorise this pass to override the scene's fog params with it's own settings. /// If you specify false, so other parameters are necessary, and this is the default behaviour for passs. ///
mode FogMode /// Only applicable if is true. You can disable fog which is turned on for the /// rest of the scene by specifying FogMode.None. Otherwise, set a pass-specific fog mode as /// defined in the enum FogMode. ///
color ColorEx /// The color of the fog. Either set this to the same as your viewport background color, /// or to blend in with a skydome or skybox. ///
density float /// The density of the fog in FogMode.Exp or FogMode.Exp2 mode, as a value between 0 and 1. /// The default is 0.001. ///
return void

SetFog() public method

Sets the fogging mode applied to this pass.
Fogging is an effect that is applied as polys are rendered. Sometimes, you want fog to be applied to an entire scene. Other times, you want it to be applied to a few polygons only. This pass-level specification of fog parameters lets you easily manage both.

The SceneManager class also has a SetFog method which applies scene-level fog. This method lets you change the fog behavior for this pass compared to the standard scene-level fog.

public SetFog ( bool overrideScene, FogMode mode, ColorEx color, float density, float start, float end ) : void
overrideScene bool /// If true, you authorise this pass to override the scene's fog params with it's own settings. /// If you specify false, so other parameters are necessary, and this is the default behaviour for passs. ///
mode FogMode /// Only applicable if is true. You can disable fog which is turned on for the /// rest of the scene by specifying FogMode.None. Otherwise, set a pass-specific fog mode as /// defined in the enum FogMode. ///
color ColorEx /// The color of the fog. Either set this to the same as your viewport background color, /// or to blend in with a skydome or skybox. ///
density float /// The density of the fog in FogMode.Exp or FogMode.Exp2 mode, as a value between 0 and 1. /// The default is 0.001. ///
start float /// Distance in world units at which linear fog starts to encroach. /// Only applicable if mode is FogMode.Linear. ///
end float /// Distance in world units at which linear fog becomes completely opaque. /// Only applicable if mode is FogMode.Linear. ///
return void

SetFragmentProgram() public method

public SetFragmentProgram ( string name ) : void
name string
return void

SetFragmentProgram() public method

public SetFragmentProgram ( string name, bool resetParams ) : void
name string
resetParams bool
return void

SetGeometryProgram() public method

public SetGeometryProgram ( string name ) : void
name string
return void

SetGeometryProgram() public method

public SetGeometryProgram ( string name, bool resetParams ) : void
name string
resetParams bool
return void

SetRunOncePerLight() public method

public SetRunOncePerLight ( bool enabled ) : void
enabled bool
return void

SetRunOncePerLight() public method

public SetRunOncePerLight ( bool enabled, bool onlyForOneLightType ) : void
enabled bool
onlyForOneLightType bool
return void

SetRunOncePerLight() public method

Sets whether or not this pass should be run once per light which can affect the object being rendered.
The default behavior for a pass (when this option is 'false'), is for a pass to be rendered only once, with all the lights which could affect this object set at the same time (up to the maximum lights allowed in the render system, which is typically 8).

Setting this option to 'true' changes this behavior, such that instead of trying to issue render this pass once per object, it is run once per light which can affect this object. In this case, only light index 0 is ever used, and is a different light every time the pass is issued, up to the total number of lights which is affecting this object. This has 2 advantages:

  • There is no limit on the number of lights which can be supported
  • It's easier to write vertex / fragment programs for this because a single program can be used for any number of lights
However, this technique is a lot more expensive, and typically you will want an additional ambient pass, because if no lights are affecting the object it will not be rendered at all, which will look odd even if ambient light is zero (imagine if there are lit objects behind it - the objects silhouette would not show up). Therefore, use this option with care, and you would be well advised to provide a less expensive fallback technique for use in the distance.

Note: The number of times this pass runs is still limited by the maximum number of lights allowed as set in MaxLights, so you will never get more passes than this.

public SetRunOncePerLight ( bool enabled, bool onlyForOneLightType, LightType lightType ) : void
enabled bool Whether this feature is enabled.
onlyForOneLightType bool /// If true, the pass will only be run for a single type of light, other light types will be ignored. ///
lightType LightType The single light type which will be considered for this pass.
return void

SetSceneBlending() public method

Allows very fine control of blending this Pass with the existing contents of the scene.
Wheras the texture blending operations seen in the TextureUnitState class are concerned with blending between texture layers, this blending is about combining the output of the material as a whole with the existing contents of the rendering target. This blending therefore allows object transparency and other special effects.

This version of the method allows complete control over the blending operation, by specifying the source and destination blending factors. The result of the blending operation is: final = (texture * sourceFactor) + (pixel * destFactor)

Each of the factors is specified as one of a number of options, as specified in the SceneBlendFactor enumerated type.

This method is applicable for both the fixed-function and programmable pipelines.

public SetSceneBlending ( SceneBlendFactor src, SceneBlendFactor dest ) : void
src SceneBlendFactor The source factor in the above calculation, i.e. multiplied by the texture color components.
dest SceneBlendFactor The destination factor in the above calculation, i.e. multiplied by the pixel color components.
return void

SetSceneBlending() public method

Sets the kind of blending this pass has with the existing contents of the scene.
Whereas the texture blending operations seen in the TextureUnitState class are concerned with blending between texture layers, this blending is about combining the output of the Pass as a whole with the existing contents of the rendering target. This blending therefore allows object transparency and other special effects. If all passes in a technique have a scene blend, then the whole technique is considered to be transparent.

This method allows you to select one of a number of predefined blending types. If you require more control than this, use the alternative version of this method which allows you to specify source and destination blend factors.

This method is applicable for both the fixed-function and programmable pipelines.

public SetSceneBlending ( SceneBlendType type ) : void
type SceneBlendType One of the predefined SceneBlendType blending types.
return void

SetShadowCasterFragmentProgram() public method

public SetShadowCasterFragmentProgram ( string name ) : void
name string
return void

SetShadowCasterVertexProgram() public method

public SetShadowCasterVertexProgram ( string name ) : void
name string
return void

SetShadowReceiverFragmentProgram() public method

public SetShadowReceiverFragmentProgram ( string name ) : void
name string
return void

SetShadowReceiverVertexProgram() public method

public SetShadowReceiverVertexProgram ( string name ) : void
name string
return void

SetVertexProgram() public method

public SetVertexProgram ( string name ) : void
name string
return void

SetVertexProgram() public method

public SetVertexProgram ( string name, bool resetParams ) : void
name string
resetParams bool
return void

Split() public method

Splits this Pass to one which can be handled in the number of texture units specified.
public Split ( int numUnits ) : Pass
numUnits int /// The target number of texture units. ///
return Pass

UpdateAutoParamsLightsOnly() public method

Update any automatic light parameters on this pass.
public UpdateAutoParamsLightsOnly ( AutoParamDataSource source ) : void
source AutoParamDataSource
return void

UpdateAutoParamsNoLights() public method

Update any automatic parameters (except lights) on this pass.
public UpdateAutoParamsNoLights ( AutoParamDataSource source ) : void
source AutoParamDataSource
return void

Property Details

nextPassId protected_oe static_oe property

protected static int nextPassId
return int

passId public_oe property

public int passId
return int

passLock protected_oe static_oe property

protected static Object passLock
return Object

queuedForDeletion protected_oe property

Is this pass queued for deletion?
protected bool queuedForDeletion
return bool

shadowCasterVertexProgramUsage protected_oe property

Details on the shadow caster vertex program to be used for this pass.
protected GpuProgramUsage shadowCasterVertexProgramUsage
return GpuProgramUsage

textureUnitStates protected_oe property

List of fixed function texture unit states for this pass.
protected TextureUnitStateList textureUnitStates
return TextureUnitStateList