Ogre::Pass Class Reference

Class defining a single pass of a Technique (of a Material), i.e. More...

#include <OgrePass.h>

Inheritance diagram for Ogre::Pass:

Classes
struct	HashFunc
	Definition of a functor for calculating the hashcode of a Pass. More...

Public Types
enum	BuiltinHashFunction { MIN_TEXTURE_CHANGE, MIN_GPU_PROGRAM_CHANGE }
	There are some default hash functions used to order passes so that render state changes are minimised, this enumerates them. More...
typedef ConstVectorIterator< TextureUnitStates >	ConstTextureUnitStateIterator
typedef std::set< Pass * >	PassSet
typedef VectorIterator< TextureUnitStates >	TextureUnitStateIterator
typedef std::vector< TextureUnitState * >	TextureUnitStates

Public Member Functions
	Pass (Technique *parent, unsigned short index)
	Default constructor. More...
	Pass (Technique *parent, unsigned short index, const Pass &oth)
	Copy constructor. More...
	~Pass ()
void	_dirtyHash (void)
	Mark the hash as dirty. More...
unsigned short	_getTextureUnitWithContentTypeIndex (TextureUnitState::ContentType contentType, unsigned short index) const
	Gets the 'nth' texture which references the given content type. More...
void	_load (void)
	Internal method for loading this pass. More...
void	_notifyIndex (unsigned short index)
	Internal method to adjust pass index. More...
void	_notifyNeedsRecompile (void)
	Tells the pass that it needs recompilation. More...
void	_prepare (void)
	Internal method for preparing to load this pass. More...
void	_recalculateHash (void)
	Internal method for recalculating the hash. More...
Pass *	_split (unsigned short numUnits)
	Splits this Pass to one which can be handled in the number of texture units specified. More...
void	_unload (void)
	Internal method for unloading this pass. More...
void	_unprepare (void)
	Internal method for undoing the load preparartion for this pass. More...
void	_updateAutoParams (const AutoParamDataSource *source, uint16 variabilityMask) const
	Update automatic parameters. More...
void	addTextureUnitState (TextureUnitState *state)
	Adds the passed in TextureUnitState, to the existing Pass. More...
bool	applyTextureAliases (const AliasTextureNamePairList &aliasList, const bool apply=true) const
	Applies texture names to Texture Unit State with matching texture name aliases. More...
size_t	calculateSize (void) const
TextureUnitState *	createTextureUnitState (const String &textureName, unsigned short texCoordSet=0)
	Inserts a new TextureUnitState object into the Pass. More...
TextureUnitState *	createTextureUnitState (void)
CompareFunction	getAlphaRejectFunction (void) const
	Gets the alpha reject function. More...
unsigned char	getAlphaRejectValue (void) const
	Gets the alpha reject value. More...
const ColourValue &	getAmbient (void) const
	Gets the ambient colour reflectance of the pass. More...
const ColourBlendState &	getBlendState () const
	Retrieves the complete blend state of this pass. More...
bool	getColourWriteEnabled (void) const
	Determines if colour buffer writing is enabled for this pass i.e. More...
void	getColourWriteEnabled (bool &red, bool &green, bool &blue, bool &alpha) const
	Determines which colour buffer channels are enabled for writing for this pass. More...
const GpuProgramPtr &	getComputeProgram (void) const
const String &	getComputeProgramName (void) const
GpuProgramParametersSharedPtr	getComputeProgramParameters (void) const
CullingMode	getCullingMode (void) const
	Returns the culling mode for geometry rendered with this pass. More...
float	getDepthBiasConstant (void) const
	Retrieves the const depth bias value as set by setDepthBias. More...
float	getDepthBiasSlopeScale (void) const
	Retrieves the slope-scale depth bias value as set by setDepthBias. More...
bool	getDepthCheckEnabled (void) const
	Returns whether or not this pass renders with depth-buffer checking on or not. More...
CompareFunction	getDepthFunction (void) const
	Returns the function used to compare depth values when depth checking is on. More...
bool	getDepthWriteEnabled (void) const
	Returns whether or not this pass renders with depth-buffer writing on or not. More...
SceneBlendFactor	getDestBlendFactor () const
	Retrieves the destination blending factor for the material. More...
SceneBlendFactor	getDestBlendFactorAlpha () const
	Retrieves the alpha destination blending factor for the material. More...
const ColourValue &	getDiffuse (void) const
	Gets the diffuse colour reflectance of the pass. More...
const ColourValue &	getEmissive (void) const
	Gets the self illumination colour of the pass. More...
const ColourValue &	getFogColour (void) const
	Returns the fog colour for the scene. More...
Real	getFogDensity (void) const
	Returns the fog density for this pass. More...
Real	getFogEnd (void) const
	Returns the fog end distance for this pass. More...
FogMode	getFogMode (void) const
	Returns the fog mode for this pass. More...
bool	getFogOverride (void) const
	Returns true if this pass is to override the scene fog settings. More...
Real	getFogStart (void) const
	Returns the fog start distance for this pass. More...
const GpuProgramPtr &	getFragmentProgram (void) const
const String &	getFragmentProgramName (void) const
GpuProgramParametersSharedPtr	getFragmentProgramParameters (void) const
const GpuProgramPtr &	getGeometryProgram (void) const
const String &	getGeometryProgramName (void) const
GpuProgramParametersSharedPtr	getGeometryProgramParameters (void) const
const GpuProgramPtr &	getGpuProgram (GpuProgramType programType) const
	Gets the Gpu program used by this pass, only available after _load() More...
const String &	getGpuProgramName (GpuProgramType type) const
	Gets the name of the program used by this pass. More...
const GpuProgramParametersSharedPtr &	getGpuProgramParameters (GpuProgramType type) const
	Gets the Gpu program parameters used by this pass. More...
uint32	getHash (void) const
	Gets the 'hash' of this pass, ie a precomputed number to use for sorting. More...
IlluminationStage	getIlluminationStage () const
	Get the manually assigned illumination stage, if any. More...
unsigned short	getIndex (void) const
	Gets the index of this Pass in the parent Technique. More...
bool	getIteratePerLight (void) const
	Does this pass run once for every light in range? More...
float	getIterationDepthBias () const
	Gets a factor which derives an additional depth bias from the number of times a pass is iterated. More...
bool	getLightClipPlanesEnabled () const
	Gets whether or not this pass will be clipped by user clips planes bounding the area covered by the light. More...
unsigned short	getLightCountPerIteration (void) const
	If light iteration is enabled, determine the number of lights per iteration. More...
bool	getLightingEnabled (void) const
	Returns whether or not dynamic lighting is enabled. More...
uint32	getLightMask () const
	Gets the light mask controlling which lights are used for this pass. More...
bool	getLightScissoringEnabled () const
	Gets whether or not this pass will be clipped by a scissor rectangle encompassing the lights that are being used in it. More...
float	getLineWidth () const
ManualCullingMode	getManualCullingMode (void) const
	Retrieves the manual culling mode for this pass. More...
unsigned short	getMaxSimultaneousLights (void) const
	Gets the maximum number of lights to be used by this pass. More...
const String &	getName (void) const
	Get the name of the pass. More...
bool	getNormaliseNormals (void) const
	Returns true if this pass has auto-normalisation of normals set. More...
unsigned short	getNumTextureUnitStates (void) const
	Returns the number of texture unit settings. More...
Light::LightTypes	getOnlyLightType () const
	Gets the single light type this pass runs for if getIteratePerLight and getRunOnlyForOneLightType are both true. More...
Technique *	getParent (void) const
	Gets the parent Technique. More...
size_t	getPassIterationCount (void) const
	Gets the pass iteration count value. More...
Real	getPointAttenuationConstant (void) const
	Returns the constant coefficient of point attenuation. More...
Real	getPointAttenuationLinear (void) const
	Returns the linear coefficient of point attenuation. More...
Real	getPointAttenuationQuadratic (void) const
	Returns the quadratic coefficient of point attenuation. More...
Real	getPointMaxSize (void) const
	Get the maximum point size, when point attenuation is in use. More...
Real	getPointMinSize (void) const
	Get the minimum point size, when point attenuation is in use. More...
Real	getPointSize (void) const
	Gets the point size of the pass. More...
bool	getPointSpritesEnabled (void) const
	Returns whether point sprites are enabled when rendering a point list. More...
PolygonMode	getPolygonMode (void) const
	Returns the type of light shading to be used. More...
bool	getPolygonModeOverrideable (void) const
	Gets whether this renderable's chosen detail level can be overridden (downgraded) by the camera setting. More...
const String &	getResourceGroup (void) const
	Gets the resource group of the ultimate parent Material. More...
bool	getRunOnlyForOneLightType (void) const
	Does this pass run only for a single light type (if getIteratePerLight is true). More...
SceneBlendOperation	getSceneBlendingOperation () const
	Returns the current blending operation. More...
SceneBlendOperation	getSceneBlendingOperationAlpha () const
	Returns the current alpha blending operation. More...
const ColourValue &	getSelfIllumination (void) const
	Gets the self illumination colour of the pass. More...
ShadeOptions	getShadingMode (void) const
	Returns the type of light shading to be used. More...
const GpuProgramPtr &	getShadowCasterFragmentProgram (void) const
	Gets the fragment program used by this pass when rendering shadow casters, only available after _load(). More...
const String &	getShadowCasterFragmentProgramName (void) const
	Gets the name of the fragment program used by this pass when rendering shadow casters. More...
GpuProgramParametersSharedPtr	getShadowCasterFragmentProgramParameters (void) const
	Gets the fragment program parameters used by this pass when rendering shadow casters. More...
const GpuProgramPtr &	getShadowCasterVertexProgram (void) const
	Gets the vertex program used by this pass when rendering shadow casters, only available after _load(). More...
const String &	getShadowCasterVertexProgramName (void) const
	Gets the name of the vertex program used by this pass when rendering shadow casters. More...
GpuProgramParametersSharedPtr	getShadowCasterVertexProgramParameters (void) const
	Gets the vertex program parameters used by this pass when rendering shadow casters. More...
const GpuProgramPtr &	getShadowReceiverFragmentProgram (void) const
	Gets the fragment program used by this pass when rendering shadow receivers, only available after _load(). More...
const String &	getShadowReceiverFragmentProgramName (void) const
	Gets the name of the fragment program used by this pass when rendering shadow receivers. More...
GpuProgramParametersSharedPtr	getShadowReceiverFragmentProgramParameters (void) const
	Gets the fragment program parameters used by this pass when rendering shadow receivers. More...
const GpuProgramPtr &	getShadowReceiverVertexProgram (void) const
	Gets the vertex program used by this pass when rendering shadow receivers, only available after _load(). More...
const String &	getShadowReceiverVertexProgramName (void) const
	Gets the name of the vertex program used by this pass when rendering shadow receivers. More...
GpuProgramParametersSharedPtr	getShadowReceiverVertexProgramParameters (void) const
	Gets the vertex program parameters used by this pass when rendering shadow receivers. More...
Real	getShininess (void) const
	Gets the 'shininess' property of the pass (affects specular highlights). More...
SceneBlendFactor	getSourceBlendFactor () const
	Retrieves the source blending factor for the material. More...
SceneBlendFactor	getSourceBlendFactorAlpha () const
	Retrieves the alpha source blending factor for the material. More...
const ColourValue &	getSpecular (void) const
	Gets the specular colour reflectance of the pass. More...
unsigned short	getStartLight (void) const
	Gets the light index that this pass will start at in the light list. More...
const GpuProgramPtr &	getTessellationDomainProgram (void) const
const String &	getTessellationDomainProgramName (void) const
GpuProgramParametersSharedPtr	getTessellationDomainProgramParameters (void) const
const GpuProgramPtr &	getTessellationHullProgram (void) const
const String &	getTessellationHullProgramName (void) const
GpuProgramParametersSharedPtr	getTessellationHullProgramParameters (void) const
TextureUnitState *	getTextureUnitState (unsigned short index) const
	Retrieves a const pointer to a texture unit state. More...
TextureUnitState *	getTextureUnitState (const String &name) const
	Retrieves the Texture Unit State matching name. More...
unsigned short	getTextureUnitStateIndex (const TextureUnitState *state) const
	Retrieve the index of the Texture Unit State in the pass. More...
TextureUnitStateIterator	getTextureUnitStateIterator (void)
	Get an iterator over the TextureUnitStates contained in this Pass. More...
ConstTextureUnitStateIterator	getTextureUnitStateIterator (void) const
	Get an iterator over the TextureUnitStates contained in this Pass. More...
const TextureUnitStates &	getTextureUnitStates () const
	Get the TextureUnitStates contained in this Pass. More...
bool	getTransparentSortingEnabled (void) const
	Returns whether or not transparent sorting is enabled. More...
bool	getTransparentSortingForced (void) const
	Returns whether or not transparent sorting is forced. More...
UserObjectBindings &	getUserObjectBindings ()
	Return an instance of user objects binding associated with this class. More...
const UserObjectBindings &	getUserObjectBindings () const
	Return an instance of user objects binding associated with this class. More...
TrackVertexColourType	getVertexColourTracking (void) const
	Gets which material properties follow the vertex colour. More...
const GpuProgramPtr &	getVertexProgram (void) const
const String &	getVertexProgramName (void) const
GpuProgramParametersSharedPtr	getVertexProgramParameters (void) const
bool	hasComputeProgram (void) const
	Returns true if this pass uses a programmable compute pipeline. More...
bool	hasFragmentProgram (void) const
	Returns true if this pass uses a programmable fragment pipeline. More...
bool	hasGeometryProgram (void) const
	Returns true if this pass uses a programmable geometry pipeline. More...
bool	hasGpuProgram (GpuProgramType programType) const
bool	hasSeparateSceneBlending () const
bool	hasSeparateSceneBlendingOperations () const
bool	hasShadowCasterFragmentProgram (void) const
	Returns true if this pass uses a shadow caster fragment program. More...
bool	hasShadowCasterVertexProgram (void) const
	Returns true if this pass uses a shadow caster vertex program. More...
bool	hasShadowReceiverFragmentProgram (void) const
	Returns true if this pass uses a shadow receiver fragment program. More...
bool	hasShadowReceiverVertexProgram (void) const
	Returns true if this pass uses a shadow receiver vertex program. More...
bool	hasTessellationDomainProgram (void) const
	Returns true if this pass uses a programmable tessellation control pipeline. More...
bool	hasTessellationHullProgram (void) const
	Returns true if this pass uses a programmable tessellation control pipeline. More...
bool	hasVertexProgram (void) const
	Returns true if this pass uses a programmable vertex pipeline. More...
bool	isAlphaToCoverageEnabled () const
	Gets whether to use alpha to coverage (A2C) when blending alpha rejected values. More...
bool	isAmbientOnly (void) const
	Returns whether this pass is ambient only. More...
bool	isLoaded (void) const
	Is this loaded? More...
bool	isPointAttenuationEnabled (void) const
	Returns whether points are attenuated with distance. More...
bool	isProgrammable (void) const
	Returns true if this pass is programmable i.e. includes either a vertex or fragment program. More...
bool	isTransparent (void) const
	Returns true if this pass has some element of transparency. More...
	OGRE_MUTEX (mTexUnitChangeMutex)
	OGRE_MUTEX (mGpuProgramChangeMutex)
	OGRE_STATIC_MUTEX (msDirtyHashListMutex)
	OGRE_STATIC_MUTEX (msPassGraveyardMutex)
Pass &	operator= (const Pass &oth)
	Operator = overload. More...
void	queueForDeletion (void)
	Queue this pass for deletion when appropriate. More...
void	removeAllTextureUnitStates (void)
	Removes all texture unit settings. More...
void	removeTextureUnitState (unsigned short index)
	Removes the indexed texture unit state from this pass. More...
void	setAlphaRejectFunction (CompareFunction func)
	Sets the alpha reject function. More...
void	setAlphaRejectSettings (CompareFunction func, unsigned char value, bool alphaToCoverageEnabled=false)
	Sets the way the pass will have use alpha to totally reject pixels from the pipeline. More...
void	setAlphaRejectValue (unsigned char val)
	Gets the alpha reject value. More...
void	setAlphaToCoverageEnabled (bool enabled)
	Sets whether to use alpha to coverage (A2C) when blending alpha rejected values. More...
void	setAmbient (float red, float green, float blue)
	Sets the ambient colour reflectance properties of this pass. More...
void	setAmbient (const ColourValue &ambient)
void	setColourWriteEnabled (bool enabled)
	Sets whether or not colour buffer writing is enabled for this Pass. More...
void	setColourWriteEnabled (bool red, bool green, bool blue, bool alpha)
	Sets which colour buffer channels are enabled for writing for this Pass. More...
void	setComputeProgram (const String &name, bool resetParams=true)
void	setComputeProgramParameters (GpuProgramParametersSharedPtr params)
void	setCullingMode (CullingMode mode)
	Sets the culling mode for this pass based on the 'vertex winding'. More...
void	setDepthBias (float constantBias, float slopeScaleBias=0.0f)
	Sets the depth bias to be used for this material. More...
void	setDepthCheckEnabled (bool enabled)
	Sets whether or not this pass renders with depth-buffer checking on or not. More...
void	setDepthFunction (CompareFunction func)
	Sets the function used to compare depth values when depth checking is on. More...
void	setDepthWriteEnabled (bool enabled)
	Sets whether or not this pass renders with depth-buffer writing on or not. More...
void	setDiffuse (float red, float green, float blue, float alpha)
	Sets the diffuse colour reflectance properties of this pass. More...
void	setDiffuse (const ColourValue &diffuse)
void	setEmissive (float red, float green, float blue)
	Sets the amount of self-illumination an object has. More...
void	setEmissive (const ColourValue &emissive)
void	setFog (bool overrideScene, FogMode mode=FOG_NONE, const ColourValue &colour=ColourValue::White, Real expDensity=0.001f, Real linearStart=0.0f, Real linearEnd=1.0f)
	Sets the fogging mode applied to this pass. More...
void	setFragmentProgram (const String &name, bool resetParams=true)
void	setFragmentProgramParameters (GpuProgramParametersSharedPtr params)
void	setGeometryProgram (const String &name, bool resetParams=true)
void	setGeometryProgramParameters (GpuProgramParametersSharedPtr params)
void	setGpuProgram (GpuProgramType type, const GpuProgramPtr &prog, bool resetParams=true)
	Sets the details of the program to use. More...
void	setGpuProgram (GpuProgramType type, const String &name, bool resetParams=true)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...
void	setGpuProgramParameters (GpuProgramType type, const GpuProgramParametersSharedPtr &params)
	Sets the Gpu program parameters. More...
void	setIlluminationStage (IlluminationStage is)
	Manually set which illumination stage this pass is a member of. More...
void	setIteratePerLight (bool enabled, bool onlyForOneLightType=true, Light::LightTypes lightType=Light::LT_POINT)
	Sets whether or not this pass should iterate per light or number of lights which can affect the object being rendered. More...
void	setIterationDepthBias (float biasPerIteration)
	Sets a factor which derives an additional depth bias from the number of times a pass is iterated. More...
void	setLightClipPlanesEnabled (bool enabled)
	Sets whether or not this pass will be clipped by user clips planes bounding the area covered by the light. More...
void	setLightCountPerIteration (unsigned short c)
	If light iteration is enabled, determine the number of lights per iteration. More...
void	setLightingEnabled (bool enabled)
	Sets whether or not dynamic lighting is enabled. More...
void	setLightMask (uint32 mask)
	Sets the light mask which can be matched to specific light flags to be handled by this pass. More...
void	setLightScissoringEnabled (bool enabled)
	Sets whether or not this pass will be clipped by a scissor rectangle encompassing the lights that are being used in it. More...
void	setLineWidth (float width)
	set the line width for this pass More...
void	setManualCullingMode (ManualCullingMode mode)
	Sets the manual culling mode, performed by CPU rather than hardware. More...
void	setMaxSimultaneousLights (unsigned short maxLights)
	Sets the maximum number of lights to be used by this pass. More...
void	setName (const String &name)
	Set the name of the pass. More...
void	setNormaliseNormals (bool normalise)
	If set to true, this forces normals to be normalised dynamically by the hardware for this pass. More...
void	setPassIterationCount (const size_t count)
	set the number of iterations that this pass should perform when doing fast multi pass operation. More...
void	setPointAttenuation (bool enabled, Real constant=0.0f, Real linear=1.0f, Real quadratic=0.0f)
	Sets how points are attenuated with distance. More...
void	setPointMaxSize (Real max)
	Set the maximum point size, when point attenuation is in use. More...
void	setPointMinSize (Real min)
	Set the minimum point size, when point attenuation is in use. More...
void	setPointSize (Real ps)
	Sets the point size of this pass. More...
void	setPointSpritesEnabled (bool enabled)
	Sets whether points will be rendered as textured quads or plain dots. More...
void	setPolygonMode (PolygonMode mode)
	Sets the type of polygon rendering required. More...
void	setPolygonModeOverrideable (bool override)
	Sets whether the PolygonMode set on this pass can be downgraded by the camera. More...
void	setSceneBlending (const SceneBlendType sbt)
	Sets the kind of blending this pass has with the existing contents of the scene. More...
void	setSceneBlending (const SceneBlendFactor sourceFactor, const SceneBlendFactor destFactor)
	Allows very fine control of blending this Pass with the existing contents of the scene. More...
void	setSceneBlendingOperation (SceneBlendOperation op)
	Sets the specific operation used to blend source and destination pixels together. More...
void	setSelfIllumination (float red, float green, float blue)
	Sets the amount of self-illumination an object has. More...
void	setSelfIllumination (const ColourValue &selfIllum)
void	setSeparateSceneBlending (const SceneBlendType sbt, const SceneBlendType sbta)
	Sets the kind of blending this pass has with the existing contents of the scene, separately for color and alpha channels. More...
void	setSeparateSceneBlending (const SceneBlendFactor sourceFactor, const SceneBlendFactor destFactor, const SceneBlendFactor sourceFactorAlpha, const SceneBlendFactor destFactorAlpha)
	Allows very fine control of blending this Pass with the existing contents of the scene. More...
void	setSeparateSceneBlendingOperation (SceneBlendOperation op, SceneBlendOperation alphaOp)
	Sets the specific operation used to blend source and destination pixels together. More...
void	setShadingMode (ShadeOptions mode)
	Sets the type of light shading required. More...
void	setShadowCasterFragmentProgram (const String &name)
	Sets the details of the fragment program to use when rendering as a shadow caster. More...
void	setShadowCasterFragmentProgramParameters (GpuProgramParametersSharedPtr params)
	Sets the fragment program parameters for rendering as a shadow caster. More...
void	setShadowCasterVertexProgram (const String &name)
	Sets the details of the vertex program to use when rendering as a shadow caster. More...
void	setShadowCasterVertexProgramParameters (GpuProgramParametersSharedPtr params)
	Sets the vertex program parameters for rendering as a shadow caster. More...
void	setShadowReceiverFragmentProgram (const String &name)
	This method allows you to specify a fragment program for use when rendering a texture shadow receiver. More...
void	setShadowReceiverFragmentProgramParameters (GpuProgramParametersSharedPtr params)
	Sets the fragment program parameters for rendering as a shadow receiver. More...
void	setShadowReceiverVertexProgram (const String &name)
	Sets the details of the vertex program to use when rendering as a shadow receiver. More...
void	setShadowReceiverVertexProgramParameters (GpuProgramParametersSharedPtr params)
	Sets the vertex program parameters for rendering as a shadow receiver. More...
void	setShininess (Real val)
	Sets the shininess of the pass, affecting the size of specular highlights. More...
void	setSpecular (float red, float green, float blue, float alpha)
	Sets the specular colour reflectance properties of this pass. More...
void	setSpecular (const ColourValue &specular)
void	setStartLight (unsigned short startLight)
	Sets the light index that this pass will start at in the light list. More...
void	setTessellationDomainProgram (const String &name, bool resetParams=true)
void	setTessellationDomainProgramParameters (GpuProgramParametersSharedPtr params)
void	setTessellationHullProgram (const String &name, bool resetParams=true)
void	setTessellationHullProgramParameters (GpuProgramParametersSharedPtr params)
void	setTextureAnisotropy (unsigned int maxAniso)
	Sets the anisotropy level to be used for all textures. More...
void	setTextureFiltering (TextureFilterOptions filterType)
	Set texture filtering for every texture unit. More...
void	setTransparentSortingEnabled (bool enabled)
	Sets whether or not transparent sorting is enabled. More...
void	setTransparentSortingForced (bool enabled)
	Sets whether or not transparent sorting is forced. More...
void	setVertexColourTracking (TrackVertexColourType tracking)
	Sets which material properties follow the vertex colour. More...
void	setVertexProgram (const String &name, bool resetParams=true)
void	setVertexProgramParameters (GpuProgramParametersSharedPtr params)

Static Public Member Functions
static void	clearDirtyHashList (void)
	Static method to reset the list of passes which need their hash values recalculated. More...
static HashFunc *	getBuiltinHashFunction (BuiltinHashFunction builtin)
	Get the builtin hash function. More...
static const PassSet &	getDirtyHashList (void)
	Static method to retrieve all the Passes which need their hash values recalculated. More...
static HashFunc *	getHashFunction (void)
	Get the hash function used for all passes. More...
static const PassSet &	getPassGraveyard (void)
	Static method to retrieve all the Passes which are pending deletion. More...
static void	processPendingPassUpdates (void)
	Process all dirty and pending deletion passes. More...
static void	setHashFunction (BuiltinHashFunction builtin)
	Sets one of the default hash functions to be used. More...
static void	setHashFunction (HashFunc *hashFunc)
	Set the hash function used for all passes. More...

Detailed Description

Class defining a single pass of a Technique (of a Material), i.e.

a single rendering call.

Remarks

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

Member Typedef Documentation

TextureUnitStates

typedef std::vector<TextureUnitState*> Ogre::Pass::TextureUnitStates

PassSet

typedef std::set<Pass*> Ogre::Pass::PassSet

TextureUnitStateIterator

typedef VectorIterator<TextureUnitStates> Ogre::Pass::TextureUnitStateIterator

ConstTextureUnitStateIterator

typedef ConstVectorIterator<TextureUnitStates> Ogre::Pass::ConstTextureUnitStateIterator

Member Enumeration Documentation

BuiltinHashFunction

enum Ogre::Pass::BuiltinHashFunction

There are some default hash functions used to order passes so that render state changes are minimised, this enumerates them.

Enumerator
MIN_TEXTURE_CHANGE	Try to minimise the number of texture changes.
MIN_GPU_PROGRAM_CHANGE	Try to minimise the number of GPU program changes. Note Only really useful if you use GPU programs for all of your materials.

Constructor & Destructor Documentation

Pass() [1/2]

Ogre::Pass::Pass	(	Technique *	parent,
		unsigned short	index
	)

Default constructor.

Pass() [2/2]

Ogre::Pass::Pass	(	Technique *	parent,
		unsigned short	index,
		const Pass &	oth
	)

Copy constructor.

~Pass()

Ogre::Pass::~Pass

(

)

Member Function Documentation

OGRE_STATIC_MUTEX() [1/2]

Ogre::Pass::OGRE_STATIC_MUTEX

(

msDirtyHashListMutex

)

OGRE_STATIC_MUTEX() [2/2]

Ogre::Pass::OGRE_STATIC_MUTEX

(

msPassGraveyardMutex

)

OGRE_MUTEX() [1/2]

Ogre::Pass::OGRE_MUTEX

(

mTexUnitChangeMutex

)

OGRE_MUTEX() [2/2]

Ogre::Pass::OGRE_MUTEX

(

mGpuProgramChangeMutex

)

operator=()

Pass& Ogre::Pass::operator=

(

const Pass &

oth

)

Operator = overload.

isProgrammable()

bool Ogre::Pass::isProgrammable ( void  ) const

inline

Returns true if this pass is programmable i.e. includes either a vertex or fragment program.

hasVertexProgram()

bool Ogre::Pass::hasVertexProgram ( void  ) const

inline

Returns true if this pass uses a programmable vertex pipeline.

References Ogre::GPT_VERTEX_PROGRAM.

hasFragmentProgram()

bool Ogre::Pass::hasFragmentProgram ( void  ) const

inline

Returns true if this pass uses a programmable fragment pipeline.

References Ogre::GPT_FRAGMENT_PROGRAM.

hasGeometryProgram()

bool Ogre::Pass::hasGeometryProgram ( void  ) const

inline

Returns true if this pass uses a programmable geometry pipeline.

References Ogre::GPT_GEOMETRY_PROGRAM.

hasTessellationHullProgram()

bool Ogre::Pass::hasTessellationHullProgram ( void  ) const

inline

Returns true if this pass uses a programmable tessellation control pipeline.

References Ogre::GPT_HULL_PROGRAM.

hasTessellationDomainProgram()

bool Ogre::Pass::hasTessellationDomainProgram ( void  ) const

inline

Returns true if this pass uses a programmable tessellation control pipeline.

References Ogre::GPT_DOMAIN_PROGRAM.

hasComputeProgram()

bool Ogre::Pass::hasComputeProgram ( void  ) const

inline

Returns true if this pass uses a programmable compute pipeline.

References Ogre::GPT_COMPUTE_PROGRAM.

hasShadowCasterVertexProgram()

bool Ogre::Pass::hasShadowCasterVertexProgram ( void  ) const

inline

Returns true if this pass uses a shadow caster vertex program.

hasShadowCasterFragmentProgram()

bool Ogre::Pass::hasShadowCasterFragmentProgram ( void  ) const

inline

Returns true if this pass uses a shadow caster fragment program.

hasShadowReceiverVertexProgram()

bool Ogre::Pass::hasShadowReceiverVertexProgram ( void  ) const

inline

Returns true if this pass uses a shadow receiver vertex program.

hasShadowReceiverFragmentProgram()

bool Ogre::Pass::hasShadowReceiverFragmentProgram ( void  ) const

inline

Returns true if this pass uses a shadow receiver fragment program.

calculateSize()

size_t Ogre::Pass::calculateSize

(

void

)

const

getIndex()

unsigned short Ogre::Pass::getIndex ( void  ) const

inline

Gets the index of this Pass in the parent Technique.

setName()

void Ogre::Pass::setName

(

const String &

name

)

Set the name of the pass.

Remarks

The name of the pass is optional. Its useful in material scripts where a material could inherit from another material and only want to modify a particular pass.

getName()

const String& Ogre::Pass::getName ( void  ) const

inline

Get the name of the pass.

setAmbient() [1/2]

void Ogre::Pass::setAmbient	(	float	red,
		float	green,
		float	blue
	)

Sets the ambient colour reflectance properties of this pass.

This property determines how much ambient light (directionless global light) is reflected. The default is full white, meaning objects are completely globally illuminated. Reduce this if you want to see diffuse or specular light effects, or change the blend of colours to make the object have a base colour other than white.

It is also possible to make the ambient reflectance track the vertex colour as defined in the mesh instead of the colour values.

Note

This setting has no effect if dynamic lighting is disabled (see Ogre::Pass::setLightingEnabled), or, if any texture layer has a Ogre::LBO_REPLACE attribute.

setAmbient() [2/2]

void Ogre::Pass::setAmbient

(

const ColourValue &

ambient

)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

setDiffuse() [1/2]

void Ogre::Pass::setDiffuse	(	float	red,
		float	green,
		float	blue,
		float	alpha
	)

Sets the diffuse colour reflectance properties of this pass.

This property determines how much diffuse light (light from instances of the Light class in the scene) is reflected. The default is full white, meaning objects reflect the maximum white light they can from Light objects.

It is also possible to make the diffuse reflectance track the vertex colour as defined in the mesh instead of the colour values.

Note

This setting has no effect if dynamic lighting is disabled (see Ogre::Pass::setLightingEnabled), or, if any texture layer has a Ogre::LBO_REPLACE attribute.

setDiffuse() [2/2]

void Ogre::Pass::setDiffuse

(

const ColourValue &

diffuse

)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

setSpecular() [1/2]

void Ogre::Pass::setSpecular	(	float	red,
		float	green,
		float	blue,
		float	alpha
	)

Sets the specular colour reflectance properties of this pass.

This property determines how much specular light (highlights from instances of the Light class in the scene) is reflected. The default is to reflect no specular light.

It is also possible to make the specular reflectance track the vertex colour as defined in the mesh instead of the colour values.

Note

The size of the specular highlights is determined by the separate 'shininess' property.

This setting has no effect if dynamic lighting is disabled (see Ogre::Pass::setLightingEnabled), or, if any texture layer has a Ogre::LBO_REPLACE attribute.

setSpecular() [2/2]

void Ogre::Pass::setSpecular

(

const ColourValue &

specular

)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

setShininess()

void Ogre::Pass::setShininess

(

Real

val

)

Sets the shininess of the pass, affecting the size of specular highlights.

The higher the value of the shininess parameter, the sharper the highlight i.e. the radius is smaller. Beware of using shininess values in the range of 0 to 1 since this causes the the specular colour to be applied to the whole surface that has the material applied to it. When the viewing angle to the surface changes, ugly flickering will also occur when shininess is in the range of 0 to 1. Shininess values between 1 and 128 work best in both DirectX and OpenGL renderers.

Note

This setting has no effect if dynamic lighting is disabled (see Ogre::Pass::setLightingEnabled), or, if any texture layer has a Ogre::LBO_REPLACE attribute.

setSelfIllumination() [1/2]

void Ogre::Pass::setSelfIllumination	(	float	red,
		float	green,
		float	blue
	)

Sets the amount of self-illumination an object has.

If an object is self-illuminating, it does not need external sources to light it, ambient or otherwise. It's like the object has it's own personal ambient light. This property is rarely useful since you can already specify per-pass ambient light, but is here for completeness.

It is also possible to make the emissive reflectance track the vertex colour as defined in the mesh instead of the colour values.

Note

This setting has no effect if dynamic lighting is disabled (see Ogre::Pass::setLightingEnabled), or, if any texture layer has a Ogre::LBO_REPLACE attribute.

setSelfIllumination() [2/2]

void Ogre::Pass::setSelfIllumination

(

const ColourValue &

selfIllum

)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

setEmissive() [1/2]

void Ogre::Pass::setEmissive ( float  red, float  green, float  blue  )

inline

Sets the amount of self-illumination an object has.

If an object is self-illuminating, it does not need external sources to light it, ambient or otherwise. It's like the object has it's own personal ambient light. This property is rarely useful since you can already specify per-pass ambient light, but is here for completeness.

It is also possible to make the emissive reflectance track the vertex colour as defined in the mesh instead of the colour values.

Note

This setting has no effect if dynamic lighting is disabled (see Ogre::Pass::setLightingEnabled), or, if any texture layer has a Ogre::LBO_REPLACE attribute.

setEmissive() [2/2]

void Ogre::Pass::setEmissive ( const ColourValue &  emissive )

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

setVertexColourTracking()

void Ogre::Pass::setVertexColourTracking

(

TrackVertexColourType

tracking

)

Sets which material properties follow the vertex colour.

setLineWidth()

void Ogre::Pass::setLineWidth ( float  width )

inline

set the line width for this pass

This property determines what width is used to render lines.

Note

some drivers only support a value of 1.0 here

getLineWidth()

float Ogre::Pass::getLineWidth ( ) const

inline

getPointSize()

Real Ogre::Pass::getPointSize

(

void

)

const

Gets the point size of the pass.

Remarks

This property determines what point size is used to render a point list.

setPointSize()

void Ogre::Pass::setPointSize

(

Real

ps

)

Sets the point size of this pass.

This setting allows you to change the size of points when rendering a point list, or a list of point sprites. The interpretation of this command depends on the Ogre::Pass::setPointAttenuation option - if it is off (the default), the point size is in screen pixels, if it is on, it expressed as normalised screen coordinates (1.0 is the height of the screen) when the point is at the origin.

Note

Some drivers have an upper limit on the size of points they support - this can even vary between APIs on the same card! Don't rely on point sizes that cause the point sprites to get very large on screen, since they may get clamped on some cards. Upper sizes can range from 64 to 256 pixels.

setPointSpritesEnabled()

void Ogre::Pass::setPointSpritesEnabled

(

bool

enabled

)

Sets whether points will be rendered as textured quads or plain dots.

This setting specifies whether or not hardware point sprite rendering is enabled for this pass. Enabling it means that a point list is rendered as a list of quads rather than a list of dots. It is very useful to use this option if you are using a BillboardSet and only need to use point oriented billboards which are all of the same size. You can also use it for any other point list render.

getPointSpritesEnabled()

bool Ogre::Pass::getPointSpritesEnabled

(

void

)

const

Returns whether point sprites are enabled when rendering a point list.

setPointAttenuation()

void Ogre::Pass::setPointAttenuation	(	bool	enabled,
		Real	constant = 0.0f,
		Real	linear = 1.0f,
		Real	quadratic = 0.0f
	)

Sets how points are attenuated with distance.

When performing point rendering or point sprite rendering, point size can be attenuated with distance. The equation for doing this is

$$attenuation = 1 / (constant + linear * dist + quadratic * d^2)$$

For example, to disable distance attenuation (constant screensize) you would set constant to 1, and linear and quadratic to 0. A standard perspective attenuation would be 0, 1, 0 respectively.

The resulting size is clamped to the minimum and maximum point size.

Parameters

enabled	Whether point attenuation is enabled
constant,linear,quadratic	Parameters to the attenuation function defined above

isPointAttenuationEnabled()

bool Ogre::Pass::isPointAttenuationEnabled

(

void

)

const

Returns whether points are attenuated with distance.

getPointAttenuationConstant()

Real Ogre::Pass::getPointAttenuationConstant

(

void

)

const

Returns the constant coefficient of point attenuation.

getPointAttenuationLinear()

Real Ogre::Pass::getPointAttenuationLinear

(

void

)

const

Returns the linear coefficient of point attenuation.

getPointAttenuationQuadratic()

Real Ogre::Pass::getPointAttenuationQuadratic

(

void

)

const

Returns the quadratic coefficient of point attenuation.

setPointMinSize()

void Ogre::Pass::setPointMinSize

(

Real

min

)

Set the minimum point size, when point attenuation is in use.

getPointMinSize()

Real Ogre::Pass::getPointMinSize

(

void

)

const

Get the minimum point size, when point attenuation is in use.

setPointMaxSize()

void Ogre::Pass::setPointMaxSize

(

Real

max

)

Set the maximum point size, when point attenuation is in use.

Remarks

Setting this to 0 indicates the max size supported by the card.

getPointMaxSize()

Real Ogre::Pass::getPointMaxSize

(

void

)

const

Get the maximum point size, when point attenuation is in use.

Remarks

0 indicates the max size supported by the card.

getAmbient()

const ColourValue& Ogre::Pass::getAmbient

(

void

)

const

Gets the ambient colour reflectance of the pass.

getDiffuse()

const ColourValue& Ogre::Pass::getDiffuse

(

void

)

const

Gets the diffuse colour reflectance of the pass.

getSpecular()

const ColourValue& Ogre::Pass::getSpecular

(

void

)

const

Gets the specular colour reflectance of the pass.

getSelfIllumination()

const ColourValue& Ogre::Pass::getSelfIllumination

(

void

)

const

Gets the self illumination colour of the pass.

getEmissive()

const ColourValue& Ogre::Pass::getEmissive ( void  ) const

inline

Gets the self illumination colour of the pass.

See also

getSelfIllumination

getShininess()

Real Ogre::Pass::getShininess

(

void

)

const

Gets the 'shininess' property of the pass (affects specular highlights).

getVertexColourTracking()

TrackVertexColourType Ogre::Pass::getVertexColourTracking

(

void

)

const

Gets which material properties follow the vertex colour.

createTextureUnitState() [1/2]

TextureUnitState* Ogre::Pass::createTextureUnitState	(	const String &	textureName,
		unsigned short	texCoordSet = 0
	)

Inserts a new TextureUnitState object into the Pass.

Remarks

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

Parameters

textureName	The basic name of the texture e.g. brickwall.jpg, stonefloor.png
texCoordSet	The index of the texture coordinate set to use.

Note

Applies to both fixed-function and programmable passes.

createTextureUnitState() [2/2]

TextureUnitState* Ogre::Pass::createTextureUnitState

(

void

)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

addTextureUnitState()

void Ogre::Pass::addTextureUnitState

(

TextureUnitState *

state

)

Adds the passed in TextureUnitState, to the existing Pass.

Parameters

state

The Texture Unit State to be attached to this pass. It must not be attached to another pass.

Note

Throws an exception if the TextureUnitState is attached to another Pass.

getTextureUnitState() [1/2]

TextureUnitState* Ogre::Pass::getTextureUnitState

(

unsigned short

index

)

const

Retrieves a const pointer to a texture unit state.

Deprecated:

use getTextureUnitStates()

getTextureUnitState() [2/2]

TextureUnitState* Ogre::Pass::getTextureUnitState

(

const String &

name

)

const

Retrieves the Texture Unit State matching name.

Returns 0 if name match is not found.

getTextureUnitStateIndex()

unsigned short Ogre::Pass::getTextureUnitStateIndex

(

const TextureUnitState *

state

)

const

Retrieve the index of the Texture Unit State in the pass.

Parameters

state

The Texture Unit State this is attached to this pass.

Note

Throws an exception if the state is not attached to the pass.

Deprecated:

use getTextureUnitStates()

getTextureUnitStateIterator() [1/2]

TextureUnitStateIterator Ogre::Pass::getTextureUnitStateIterator

(

void

)

Get an iterator over the TextureUnitStates contained in this Pass.

Deprecated:

use getTextureUnitStates()

getTextureUnitStateIterator() [2/2]

ConstTextureUnitStateIterator Ogre::Pass::getTextureUnitStateIterator

(

void

)

const

Get an iterator over the TextureUnitStates contained in this Pass.

Deprecated:

use getTextureUnitStates()

getTextureUnitStates()

const TextureUnitStates& Ogre::Pass::getTextureUnitStates ( ) const

inline

Get the TextureUnitStates contained in this Pass.

removeTextureUnitState()

void Ogre::Pass::removeTextureUnitState

(

unsigned short

index

)

Removes the indexed texture unit state from this pass.

Remarks

Note that removing a texture which is not the topmost will have a larger performance impact.

removeAllTextureUnitStates()

void Ogre::Pass::removeAllTextureUnitStates

(

void

)

Removes all texture unit settings.

getNumTextureUnitStates()

unsigned short Ogre::Pass::getNumTextureUnitStates ( void  ) const

inline

Returns the number of texture unit settings.

Deprecated:

use getTextureUnitStates()

setSceneBlending() [1/2]

void Ogre::Pass::setSceneBlending

(

const SceneBlendType

sbt

)

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.

Note

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

Parameters

sbt	One of the predefined SceneBlendType blending types

setSeparateSceneBlending() [1/2]

void Ogre::Pass::setSeparateSceneBlending	(	const SceneBlendType	sbt,
		const SceneBlendType	sbta
	)

Sets the kind of blending this pass has with the existing contents of the scene, separately for color and alpha channels.

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.

Parameters

sbt	One of the predefined SceneBlendType blending types for the color channel
sbta	One of the predefined SceneBlendType blending types for the alpha channel

setSceneBlending() [2/2]

void Ogre::Pass::setSceneBlending	(	const SceneBlendFactor	sourceFactor,
		const SceneBlendFactor	destFactor
	)

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

This version of the method allows complete control over the blending operation, by specifying the source and destination blending factors.

By default the operation is Ogre::SBO_ADD, which creates this equation

$$final = (passOutput * sourceFactor) + (frameBuffer * destFactor)$$

Each of the factors is specified as one of Ogre::SceneBlendFactor.

By setting a different Ogre::SceneBlendOperation you can achieve a different effect.

Parameters

sourceFactor	The source factor in the above calculation, i.e. multiplied by the output of the Pass.
destFactor	The destination factor in the above calculation, i.e. multiplied by the Frame Buffer contents.

setSeparateSceneBlending() [2/2]

void Ogre::Pass::setSeparateSceneBlending	(	const SceneBlendFactor	sourceFactor,
		const SceneBlendFactor	destFactor,
		const SceneBlendFactor	sourceFactorAlpha,
		const SceneBlendFactor	destFactorAlpha
	)

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

This version of the method allows complete control over the blending operation, by specifying the source and destination blending factors.

By default the operation is Ogre::SBO_ADD, which creates this equation

$$final = (passOutput * sourceFactor) + (frameBuffer * destFactor)$$

Each of the factors is specified as one of Ogre::SceneBlendFactor.

By setting a different Ogre::SceneBlendOperation you can achieve a different effect.

Parameters

sourceFactor	The source factor in the above calculation, i.e. multiplied by the output of the Pass.
destFactor	The destination factor in the above calculation, i.e. multiplied by the Frame Buffer contents.
sourceFactorAlpha	The alpha source factor in the above calculation, i.e. multiplied by the output of the Pass.
destFactorAlpha	The alpha destination factor in the above calculation, i.e. multiplied by the Frame Buffer alpha.

hasSeparateSceneBlending()

bool Ogre::Pass::hasSeparateSceneBlending

(

)

const

Deprecated:

getBlendState()

const ColourBlendState& Ogre::Pass::getBlendState ( ) const

inline

Retrieves the complete blend state of this pass.

getSourceBlendFactor()

SceneBlendFactor Ogre::Pass::getSourceBlendFactor

(

)

const

Retrieves the source blending factor for the material.

getDestBlendFactor()

SceneBlendFactor Ogre::Pass::getDestBlendFactor

(

)

const

Retrieves the destination blending factor for the material.

getSourceBlendFactorAlpha()

SceneBlendFactor Ogre::Pass::getSourceBlendFactorAlpha

(

)

const

Retrieves the alpha source blending factor for the material.

getDestBlendFactorAlpha()

SceneBlendFactor Ogre::Pass::getDestBlendFactorAlpha

(

)

const

Retrieves the alpha destination blending factor for the material.

setSceneBlendingOperation()

void Ogre::Pass::setSceneBlendingOperation

(

SceneBlendOperation

op

)

Sets the specific operation used to blend source and destination pixels together.

See also

Ogre::ColourBlendState

Parameters

op	The blending operation mode to use for this pass

setSeparateSceneBlendingOperation()

void Ogre::Pass::setSeparateSceneBlendingOperation	(	SceneBlendOperation	op,
		SceneBlendOperation	alphaOp
	)

Sets the specific operation used to blend source and destination pixels together.

This function allows more control over blending since it allows you to select different blending modes for the color and alpha channels

See also

Ogre::ColourBlendState

Parameters

op	The blending operation mode to use for this pass
alphaOp	The blending operation mode to use for alpha channels in this pass

hasSeparateSceneBlendingOperations()

bool Ogre::Pass::hasSeparateSceneBlendingOperations

(

)

const

Deprecated:

getSceneBlendingOperation()

SceneBlendOperation Ogre::Pass::getSceneBlendingOperation

(

)

const

Returns the current blending operation.

getSceneBlendingOperationAlpha()

SceneBlendOperation Ogre::Pass::getSceneBlendingOperationAlpha

(

)

const

Returns the current alpha blending operation.

isTransparent()

bool Ogre::Pass::isTransparent

(

void

)

const

Returns true if this pass has some element of transparency.

setDepthCheckEnabled()

void Ogre::Pass::setDepthCheckEnabled

(

bool

enabled

)

Sets whether or not this pass renders with depth-buffer checking on or not.

If depth-buffer checking is on, whenever a pixel is about to be written to the frame buffer the depth buffer is checked to see if the pixel is in front of all other pixels written at that point. If not, the pixel is not written.

If depth checking is off, pixels are written no matter what has been rendered before. Also see setDepthFunction for more advanced depth check configuration.

See also

Ogre::CompareFunction

getDepthCheckEnabled()

bool Ogre::Pass::getDepthCheckEnabled

(

void

)

const

Returns whether or not this pass renders with depth-buffer checking on or not.

setDepthWriteEnabled()

void Ogre::Pass::setDepthWriteEnabled

(

bool

enabled

)

Sets whether or not this pass renders with depth-buffer writing on or not.

If depth-buffer writing is on, whenever a pixel is written to the frame buffer the depth buffer is updated with the depth value of that new pixel, thus affecting future rendering operations if future pixels are behind this one.

If depth writing is off, pixels are written without updating the depth buffer Depth writing should normally be on but can be turned off when rendering static backgrounds or when rendering a collection of transparent objects at the end of a scene so that they overlap each other correctly.

getDepthWriteEnabled()

bool Ogre::Pass::getDepthWriteEnabled

(

void

)

const

Returns whether or not this pass renders with depth-buffer writing on or not.

setDepthFunction()

void Ogre::Pass::setDepthFunction

(

CompareFunction

func

)

Sets the function used to compare depth values when depth checking is on.

If depth checking is enabled (see setDepthCheckEnabled) a comparison occurs between the depth value of the pixel to be written and the current contents of the buffer. This comparison is normally Ogre::CMPF_LESS_EQUAL.

getDepthFunction()

CompareFunction Ogre::Pass::getDepthFunction

(

void

)

const

Returns the function used to compare depth values when depth checking is on.

See also

setDepthFunction

setColourWriteEnabled() [1/2]

void Ogre::Pass::setColourWriteEnabled

(

bool

enabled

)

Sets whether or not colour buffer writing is enabled for this Pass.

If colour writing is off no visible pixels are written to the screen during this pass. You might think this is useless, but if you render with colour writing off, and with very minimal other settings, you can use this pass to initialise the depth buffer before subsequently rendering other passes which fill in the colour data. This can give you significant performance boosts on some newer cards, especially when using complex fragment programs, because if the depth check fails then the fragment program is never run.

getColourWriteEnabled() [1/2]

bool Ogre::Pass::getColourWriteEnabled

(

void

)

const

Determines if colour buffer writing is enabled for this pass i.e.

when at least one colour channel is enabled for writing.

setColourWriteEnabled() [2/2]

void Ogre::Pass::setColourWriteEnabled	(	bool	red,
		bool	green,
		bool	blue,
		bool	alpha
	)

Sets which colour buffer channels are enabled for writing for this Pass.

getColourWriteEnabled() [2/2]

void Ogre::Pass::getColourWriteEnabled	(	bool &	red,
		bool &	green,
		bool &	blue,
		bool &	alpha
	)		const

Determines which colour buffer channels are enabled for writing for this pass.

setCullingMode()

void Ogre::Pass::setCullingMode

(

CullingMode

mode

)

Sets the culling mode for this pass based on the 'vertex winding'.

A typical way for the rendering engine to cull triangles is based on the 'vertex winding' of triangles. Vertex winding refers to the direction in which the vertices are passed or indexed to in the rendering operation as viewed from the camera, and will wither be clockwise or anticlockwise (that's 'counterclockwise' for you Americans out there ;) The default is Ogre::CULL_CLOCKWISE i.e. that only triangles whose vertices are passed/indexed in anticlockwise order are rendered - this is a common approach and is used in 3D studio models for example. You can alter this culling mode if you wish but it is not advised unless you know what you are doing.

You may wish to use the Ogre::CULL_NONE option for mesh data that you cull yourself where the vertex winding is uncertain or for creating 2-sided passes.

getCullingMode()

CullingMode Ogre::Pass::getCullingMode

(

void

)

const

Returns the culling mode for geometry rendered with this pass.

See setCullingMode for more information.

setManualCullingMode()

void Ogre::Pass::setManualCullingMode

(

ManualCullingMode

mode

)

Sets the manual culling mode, performed by CPU rather than hardware.

In some situations you want to use manual culling of triangles rather than sending the triangles to the hardware and letting it cull them. This setting only takes effect on SceneManager's that use it (since it is best used on large groups of planar world geometry rather than on movable geometry since this would be expensive), but if used can cull geometry before it is sent to the hardware.

In this case the culling is based on whether the ’back’ or ’front’ of the triangle is facing the camera - this definition is based on the face normal (a vector which sticks out of the front side of the polygon perpendicular to the face). Since Ogre expects face normals to be on anticlockwise side of the face, Ogre::MANUAL_CULL_BACK is the software equivalent of Ogre::CULL_CLOCKWISE setting, which is why they are both the default. The naming is different to reflect the way the culling is done though, since most of the time face normals are pre-calculated and they don’t have to be the way Ogre expects - you could set Ogre::CULL_NONE and completely cull in software based on your own face normals, if you have the right SceneManager which uses them.

getManualCullingMode()

ManualCullingMode Ogre::Pass::getManualCullingMode

(

void

)

const

Retrieves the manual culling mode for this pass.

See also

setManualCullingMode

setLightingEnabled()

void Ogre::Pass::setLightingEnabled

(

bool

enabled

)

Sets whether or not dynamic lighting is enabled.

Turning dynamic lighting off makes any ambient, diffuse, specular, emissive and shading properties for this pass redundant. If lighting is turned off, all objects rendered using the pass will be fully lit. When lighting is turned on, objects are lit according to their vertex normals for diffuse and specular light, and globally for ambient and emissive.

getLightingEnabled()

bool Ogre::Pass::getLightingEnabled

(

void

)

const

Returns whether or not dynamic lighting is enabled.

setMaxSimultaneousLights()

void Ogre::Pass::setMaxSimultaneousLights

(

unsigned short

maxLights

)

Sets the maximum number of lights to be used by this pass.

Remarks

During rendering, if lighting is enabled (or if the pass uses an automatic program parameter based on a light) the engine will request the nearest lights to the object being rendered in order to work out which ones to use. This parameter sets the limit on the number of lights which should apply to objects rendered with this pass.

getMaxSimultaneousLights()

unsigned short Ogre::Pass::getMaxSimultaneousLights

(

void

)

const

Gets the maximum number of lights to be used by this pass.

setStartLight()

void Ogre::Pass::setStartLight

(

unsigned short

startLight

)

Sets the light index that this pass will start at in the light list.

Normally the lights passed to a pass will start from the beginning of the light list for this object. This option allows you to make this pass start from a higher light index, for example if one of your earlier passes could deal with lights 0-3, and this pass dealt with lights 4+. This option also has an interaction with pass iteration, in that if you choose to iterate this pass per light too, the iteration will only begin from light 4.

getStartLight()

unsigned short Ogre::Pass::getStartLight

(

void

)

const

Gets the light index that this pass will start at in the light list.

setLightMask()

void Ogre::Pass::setLightMask

(

uint32

mask

)

Sets the light mask which can be matched to specific light flags to be handled by this pass.

getLightMask()

uint32 Ogre::Pass::getLightMask

(

)

const

Gets the light mask controlling which lights are used for this pass.

setShadingMode()

void Ogre::Pass::setShadingMode

(

ShadeOptions

mode

)

Sets the type of light shading required.

When dynamic lighting is turned on, the effect is to generate colour values at each vertex. Whether these values are interpolated across the face (and how) depends on this setting. The default shading method is Ogre::SO_GOURAUD.

getShadingMode()

ShadeOptions Ogre::Pass::getShadingMode

(

void

)

const

Returns the type of light shading to be used.

setPolygonMode()

void Ogre::Pass::setPolygonMode

(

PolygonMode

mode

)

Sets the type of polygon rendering required.

Sets how polygons should be rasterised, i.e. whether they should be filled in, or just drawn as lines or points. The default shading method is Ogre::PM_SOLID.

getPolygonMode()

PolygonMode Ogre::Pass::getPolygonMode

(

void

)

const

Returns the type of light shading to be used.

setPolygonModeOverrideable()

void Ogre::Pass::setPolygonModeOverrideable ( bool  override )

inline

Sets whether the PolygonMode set on this pass can be downgraded by the camera.

Parameters

override

If set to false, this pass will always be rendered at its own chosen polygon mode no matter what the camera says. The default is true.

getPolygonModeOverrideable()

bool Ogre::Pass::getPolygonModeOverrideable ( void  ) const

inline

Gets whether this renderable's chosen detail level can be overridden (downgraded) by the camera setting.

References Ogre::FOG_NONE, and Ogre::ColourValue::White.

setFog()

void Ogre::Pass::setFog	(	bool	overrideScene,
		FogMode	mode = FOG_NONE,
		const ColourValue &	colour = ColourValue::White,
		Real	expDensity = 0.001f,
		Real	linearStart = 0.0f,
		Real	linearEnd = 1.0f
	)

Sets the fogging mode applied to this pass.

Remarks

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 behaviour for this pass compared to the standard scene-level fog.

Parameters

overrideScene	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 passes.
mode	Only applicable if overrideScene is true. You can disable fog which is turned on for the rest of the scene by specifying FOG_NONE. Otherwise, set a pass-specific fog mode as defined in the enum FogMode.
colour	The colour of the fog. Either set this to the same as your viewport background colour, or to blend in with a skydome or skybox.
expDensity	The density of the fog in FOG_EXP or FOG_EXP2 mode, as a value between 0 and 1. The default is 0.001.
linearStart	Distance in world units at which linear fog starts to encroach. Only applicable if mode is FOG_LINEAR.
linearEnd	Distance in world units at which linear fog becomes completely opaque. Only applicable if mode is FOG_LINEAR.

getFogOverride()

bool Ogre::Pass::getFogOverride

(

void

)

const

Returns true if this pass is to override the scene fog settings.

getFogMode()

FogMode Ogre::Pass::getFogMode

(

void

)

const

Returns the fog mode for this pass.

Note

Only valid if getFogOverride is true.

getFogColour()

const ColourValue& Ogre::Pass::getFogColour

(

void

)

const

Returns the fog colour for the scene.

getFogStart()

Real Ogre::Pass::getFogStart

(

void

)

const

Returns the fog start distance for this pass.

Note

Only valid if getFogOverride is true.

getFogEnd()

Real Ogre::Pass::getFogEnd

(

void

)

const

Returns the fog end distance for this pass.

Note

Only valid if getFogOverride is true.

getFogDensity()

Real Ogre::Pass::getFogDensity

(

void

)

const

Returns the fog density for this pass.

Note

Only valid if getFogOverride is true.

setDepthBias()

void Ogre::Pass::setDepthBias	(	float	constantBias,
		float	slopeScaleBias = 0.0f
	)

Sets the depth bias to be used for this material.

When polygons are coplanar, you can get problems with 'depth 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$$

Slope scale biasing is relative to the angle of the polygon to the camera, which makes for a more appropriate bias value, but this is ignored on some older hardware. Constant biasing is expressed as a factor of the minimum depth value, so a value of 1 will nudge the depth by one ’notch’ if you will.

Parameters

constantBias	The constant bias value
slopeScaleBias	The slope-relative bias value

getDepthBiasConstant()

float Ogre::Pass::getDepthBiasConstant

(

void

)

const

Retrieves the const depth bias value as set by setDepthBias.

getDepthBiasSlopeScale()

float Ogre::Pass::getDepthBiasSlopeScale

(

void

)

const

Retrieves the slope-scale depth bias value as set by setDepthBias.

setIterationDepthBias()

void Ogre::Pass::setIterationDepthBias

(

float

biasPerIteration

)

Sets a factor which derives an additional depth bias from the number of times a pass is iterated.

Remarks

The Final depth bias will be the constant depth bias as set through setDepthBias, plus this value times the iteration number.

getIterationDepthBias()

float Ogre::Pass::getIterationDepthBias

(

)

const

Gets a factor which derives an additional depth bias from the number of times a pass is iterated.

setAlphaRejectSettings()

void Ogre::Pass::setAlphaRejectSettings	(	CompareFunction	func,
		unsigned char	value,
		bool	alphaToCoverageEnabled = false
	)

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

Remarks

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

Parameters

func	The comparison which must pass for the pixel to be written.
value	1 byte value against which alpha values will be tested(0-255)
alphaToCoverageEnabled	Whether to enable alpha to coverage support

Note

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

setAlphaRejectFunction()

void Ogre::Pass::setAlphaRejectFunction

(

CompareFunction

func

)

Sets the alpha reject function.

See also

setAlphaRejectSettings for more information.

setAlphaRejectValue()

void Ogre::Pass::setAlphaRejectValue

(

unsigned char

val

)

Gets the alpha reject value.

See also

setAlphaRejectSettings for more information.

getAlphaRejectFunction()

CompareFunction Ogre::Pass::getAlphaRejectFunction ( void  ) const

inline

Gets the alpha reject function.

See also

setAlphaRejectSettings for more information.

getAlphaRejectValue()

unsigned char Ogre::Pass::getAlphaRejectValue ( void  ) const

inline

Gets the alpha reject value.

See also

setAlphaRejectSettings for more information.

setAlphaToCoverageEnabled()

void Ogre::Pass::setAlphaToCoverageEnabled

(

bool

enabled

)

Sets whether to use alpha to coverage (A2C) when blending alpha rejected values.

Alpha to coverage performs multisampling on the edges of alpha-rejected textures to produce a smoother result. It is only supported when multisampling is already enabled on the render target, and when the hardware supports alpha to coverage (see RenderSystemCapabilities). The common use for alpha to coverage is foliage rendering and chain-link fence style textures.

isAlphaToCoverageEnabled()

bool Ogre::Pass::isAlphaToCoverageEnabled ( ) const

inline

Gets whether to use alpha to coverage (A2C) when blending alpha rejected values.

References Ogre::Light::LT_POINT.

setTransparentSortingEnabled()

void Ogre::Pass::setTransparentSortingEnabled

(

bool

enabled

)

Sets whether or not transparent sorting is enabled.

Parameters

enabled

If false depth sorting of this material will be disabled.

Remarks

By default all transparent materials are sorted such that renderables furthest away from the camera are rendered first. This is usually the desired behaviour but in certain cases this depth sorting may be unnecessary and undesirable. If for example it is necessary to ensure the rendering order does not change from one frame to the next.

Note

This will have no effect on non-transparent materials.

getTransparentSortingEnabled()

bool Ogre::Pass::getTransparentSortingEnabled

(

void

)

const

Returns whether or not transparent sorting is enabled.

setTransparentSortingForced()

void Ogre::Pass::setTransparentSortingForced

(

bool

enabled

)

Sets whether or not transparent sorting is forced.

Parameters

enabled

If true depth sorting of this material will be depend only on the value of getTransparentSortingEnabled().

Remarks

By default even if transparent sorting is enabled, depth sorting will only be performed when the material is transparent and depth write/check are disabled. This function disables these extra conditions.

getTransparentSortingForced()

bool Ogre::Pass::getTransparentSortingForced

(

void

)

const

Returns whether or not transparent sorting is forced.

setIteratePerLight()

void Ogre::Pass::setIteratePerLight	(	bool	enabled,
		bool	onlyForOneLightType = true,
		Light::LightTypes	lightType = Light::LT_POINT
	)

Sets whether or not this pass should iterate per light or number of lights which can affect the object being rendered.

Remarks

The default behaviour for a pass (when this option is 'false'), is for a pass to be rendered only once (or the number of times set in setPassIterationCount), 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 behaviour, such that instead of trying to issue render this pass once per object, it is run per light, or for a group of 'n' lights each time which can affect this object, the number of times set in setPassIterationCount (default is once). 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 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 setMaxSimultaneousLights, so you will never get more passes than this. Also, the iteration is started from the 'start light' as set in Pass::setStartLight, and the number of passes is the number of lights to iterate over divided by the number of lights per iteration (default 1, set by setLightCountPerIteration).

Parameters

enabled	Whether this feature is enabled
onlyForOneLightType	If true, the pass will only be run for a single type of light, other light types will be ignored.
lightType	The single light type which will be considered for this pass

getIteratePerLight()

bool Ogre::Pass::getIteratePerLight ( void  ) const

inline

Does this pass run once for every light in range?

getRunOnlyForOneLightType()

bool Ogre::Pass::getRunOnlyForOneLightType ( void  ) const

inline

Does this pass run only for a single light type (if getIteratePerLight is true).

getOnlyLightType()

Light::LightTypes Ogre::Pass::getOnlyLightType ( ) const

inline

Gets the single light type this pass runs for if getIteratePerLight and getRunOnlyForOneLightType are both true.

setLightCountPerIteration()

void Ogre::Pass::setLightCountPerIteration

(

unsigned short

c

)

If light iteration is enabled, determine the number of lights per iteration.

Remarks

The default for this setting is 1, so if you enable light iteration (Pass::setIteratePerLight), the pass is rendered once per light. If you set this value higher, the passes will occur once per 'n' lights. The start of the iteration is set by Pass::setStartLight and the end by Pass::setMaxSimultaneousLights.

getLightCountPerIteration()

unsigned short Ogre::Pass::getLightCountPerIteration

(

void

)

const

If light iteration is enabled, determine the number of lights per iteration.

getParent()

Technique* Ogre::Pass::getParent ( void  ) const

inline

Gets the parent Technique.

getResourceGroup()

const String& Ogre::Pass::getResourceGroup

(

void

)

const

Gets the resource group of the ultimate parent Material.

getGpuProgram()

const GpuProgramPtr& Ogre::Pass::getGpuProgram

(

GpuProgramType

programType

)

const

Gets the Gpu program used by this pass, only available after _load()

getVertexProgram()

const GpuProgramPtr& Ogre::Pass::getVertexProgram

(

void

)

const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

getFragmentProgram()

const GpuProgramPtr& Ogre::Pass::getFragmentProgram

(

void

)

const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

getGeometryProgram()

const GpuProgramPtr& Ogre::Pass::getGeometryProgram

(

void

)

const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

getTessellationHullProgram()

const GpuProgramPtr& Ogre::Pass::getTessellationHullProgram

(

void

)

const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

getTessellationDomainProgram()

const GpuProgramPtr& Ogre::Pass::getTessellationDomainProgram

(

void

)

const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

getComputeProgram()

const GpuProgramPtr& Ogre::Pass::getComputeProgram

(

void

)

const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

hasGpuProgram()

bool Ogre::Pass::hasGpuProgram

(

GpuProgramType

programType

)

const

setShadowCasterVertexProgram()

void Ogre::Pass::setShadowCasterVertexProgram

(

const String &

name

)

Sets the details of the vertex program to use when rendering as a shadow caster.

Remarks

Texture-based shadows require that the caster is rendered to a texture in a solid colour (the shadow colour in the case of modulative texture shadows). Whilst Ogre can arrange this for the fixed function pipeline, passes which use vertex programs might need the vertex programs still to run in order to preserve any deformation etc that it does. However, lighting calculations must be a lot simpler, with only the ambient colour being used (which the engine will ensure is bound to the shadow colour).

Therefore, it is up to implementors of vertex programs to provide an alternative vertex program which can be used to render the object to a shadow texture. Do all the same vertex transforms, but set the colour of the vertex to the ambient colour, as bound using the standard auto parameter binding mechanism.

Note

Some vertex programs will work without doing this, because Ogre ensures that all lights except for ambient are set black. However, the chances are that your vertex program is doing a lot of unnecessary work in this case, since the other lights are having no effect, and it is good practice to supply an alternative.

This is only applicable to programmable passes.

The default behaviour is for Ogre to switch to fixed-function rendering if an explicit vertex program alternative is not set.

setShadowCasterVertexProgramParameters()

void Ogre::Pass::setShadowCasterVertexProgramParameters

(

GpuProgramParametersSharedPtr

params

)

Sets the vertex program parameters for rendering as a shadow caster.

Remarks

Only applicable to programmable passes, and this particular call is designed for low-level programs; use the named parameter methods for setting high-level program parameters.

getShadowCasterVertexProgramName()

const String& Ogre::Pass::getShadowCasterVertexProgramName

(

void

)

const

Gets the name of the vertex program used by this pass when rendering shadow casters.

getShadowCasterVertexProgramParameters()

GpuProgramParametersSharedPtr Ogre::Pass::getShadowCasterVertexProgramParameters

(

void

)

const

Gets the vertex program parameters used by this pass when rendering shadow casters.

getShadowCasterVertexProgram()

const GpuProgramPtr& Ogre::Pass::getShadowCasterVertexProgram

(

void

)

const

Gets the vertex program used by this pass when rendering shadow casters, only available after _load().

setShadowCasterFragmentProgram()

void Ogre::Pass::setShadowCasterFragmentProgram

(

const String &

name

)

Sets the details of the fragment program to use when rendering as a shadow caster.

Remarks

Texture-based shadows require that the caster is rendered to a texture in a solid colour (the shadow colour in the case of modulative texture shadows). Whilst Ogre can arrange this for the fixed function pipeline, passes which use vertex programs might need the vertex programs still to run in order to preserve any deformation etc that it does. However, lighting calculations must be a lot simpler, with only the ambient colour being used (which the engine will ensure is bound to the shadow colour).

Therefore, it is up to implementors of vertex programs to provide an alternative vertex program which can be used to render the object to a shadow texture. Do all the same vertex transforms, but set the colour of the vertex to the ambient colour, as bound using the standard auto parameter binding mechanism.

Note

Some vertex programs will work without doing this, because Ogre ensures that all lights except for ambient are set black. However, the chances are that your vertex program is doing a lot of unnecessary work in this case, since the other lights are having no effect, and it is good practice to supply an alternative.

This is only applicable to programmable passes.

The default behaviour is for Ogre to switch to fixed-function rendering if an explicit fragment program alternative is not set.

setShadowCasterFragmentProgramParameters()

void Ogre::Pass::setShadowCasterFragmentProgramParameters

(

GpuProgramParametersSharedPtr

params

)

Sets the fragment program parameters for rendering as a shadow caster.

Remarks

Only applicable to programmable passes, and this particular call is designed for low-level programs; use the named parameter methods for setting high-level program parameters.

getShadowCasterFragmentProgramName()

const String& Ogre::Pass::getShadowCasterFragmentProgramName

(

void

)

const

Gets the name of the fragment program used by this pass when rendering shadow casters.

getShadowCasterFragmentProgramParameters()

GpuProgramParametersSharedPtr Ogre::Pass::getShadowCasterFragmentProgramParameters

(

void

)

const

Gets the fragment program parameters used by this pass when rendering shadow casters.

getShadowCasterFragmentProgram()

const GpuProgramPtr& Ogre::Pass::getShadowCasterFragmentProgram

(

void

)

const

Gets the fragment program used by this pass when rendering shadow casters, only available after _load().

setShadowReceiverVertexProgram()

void Ogre::Pass::setShadowReceiverVertexProgram

(

const String &

name

)

Sets the details of the vertex program to use when rendering as a shadow receiver.

Remarks

Texture-based shadows require that the shadow receiver is rendered using a projective texture. Whilst Ogre can arrange this for the fixed function pipeline, passes which use vertex programs might need the vertex programs still to run in order to preserve any deformation etc that it does. So in this case, we need a vertex program which does the appropriate vertex transformation, but generates projective texture coordinates.

Therefore, it is up to implementors of vertex programs to provide an alternative vertex program which can be used to render the object as a shadow receiver. Do all the same vertex transforms, but generate 2 sets of texture coordinates using the auto parameter ACT_TEXTURE_VIEWPROJ_MATRIX, which Ogre will bind to the parameter name / index you supply as the second parameter to this method. 2 texture sets are needed because Ogre needs to use 2 texture units for some shadow effects.

Note

This is only applicable to programmable passes.

The default behaviour is for Ogre to switch to fixed-function rendering if an explict vertex program alternative is not set.

setShadowReceiverVertexProgramParameters()

void Ogre::Pass::setShadowReceiverVertexProgramParameters

(

GpuProgramParametersSharedPtr

params

)

Sets the vertex program parameters for rendering as a shadow receiver.

Remarks

Only applicable to programmable passes, and this particular call is designed for low-level programs; use the named parameter methods for setting high-level program parameters.

setShadowReceiverFragmentProgram()

void Ogre::Pass::setShadowReceiverFragmentProgram

(

const String &

name

)

This method allows you to specify a fragment program for use when rendering a texture shadow receiver.

Remarks

Texture shadows are applied by rendering the receiver. Modulative texture shadows are performed as a post-render darkening pass, and as such fragment programs are generally not required per-object. Additive texture shadows, however, are applied by accumulating light masked out using a texture shadow (black & white by default, unless you customise this using SceneManager::setCustomShadowCasterMaterial). OGRE can do this for you for most materials, but if you use a custom lighting program (e.g. per pixel lighting) then you'll need to provide a custom version for receiving shadows. You don't need to provide this for shadow casters if you don't use self-shadowing since they will never be shadow receivers too.

The shadow texture is always bound to texture unit 0 when rendering texture shadow passes. Therefore your custom shadow receiver program may well just need to shift it's texture unit usage up by one unit, and take the shadow texture into account in its calculations.

setShadowReceiverFragmentProgramParameters()

void Ogre::Pass::setShadowReceiverFragmentProgramParameters

(

GpuProgramParametersSharedPtr

params

)

Sets the fragment program parameters for rendering as a shadow receiver.

Remarks

Only applicable to programmable passes, and this particular call is designed for low-level programs; use the named parameter methods for setting high-level program parameters.

getShadowReceiverVertexProgramName()

const String& Ogre::Pass::getShadowReceiverVertexProgramName

(

void

)

const

Gets the name of the vertex program used by this pass when rendering shadow receivers.

getShadowReceiverVertexProgramParameters()

GpuProgramParametersSharedPtr Ogre::Pass::getShadowReceiverVertexProgramParameters

(

void

)

const

Gets the vertex program parameters used by this pass when rendering shadow receivers.

getShadowReceiverVertexProgram()

const GpuProgramPtr& Ogre::Pass::getShadowReceiverVertexProgram

(

void

)

const

Gets the vertex program used by this pass when rendering shadow receivers, only available after _load().

getShadowReceiverFragmentProgramName()

const String& Ogre::Pass::getShadowReceiverFragmentProgramName

(

void

)

const

Gets the name of the fragment program used by this pass when rendering shadow receivers.

getShadowReceiverFragmentProgramParameters()

GpuProgramParametersSharedPtr Ogre::Pass::getShadowReceiverFragmentProgramParameters

(

void

)

const

Gets the fragment program parameters used by this pass when rendering shadow receivers.

getShadowReceiverFragmentProgram()

const GpuProgramPtr& Ogre::Pass::getShadowReceiverFragmentProgram

(

void

)

const

Gets the fragment program used by this pass when rendering shadow receivers, only available after _load().

setGpuProgram() [1/2]

void Ogre::Pass::setGpuProgram	(	GpuProgramType	type,
		const GpuProgramPtr &	prog,
		bool	resetParams = true
	)

Sets the details of the program to use.

Remarks

Only applicable to programmable passes, this sets the details of the program to use in this pass. The program will not be loaded until the parent Material is loaded.

Parameters

resetParams

If true, this will create a fresh set of parameters from the new program being linked, so if you had previously set parameters you will have to set them again. If you set this to false, you must be absolutely sure that the parameters match perfectly, and in the case of named parameters refers to the indexes underlying them, not just the names.

setGpuProgram() [2/2]

void Ogre::Pass::setGpuProgram	(	GpuProgramType	type,
		const String &	name,
		bool	resetParams = true
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

name	The name of the program - this must have been created using GpuProgramManager by the time that this Pass is loaded. If this parameter is blank, any program of the type in this pass is disabled.

setFragmentProgram()

void Ogre::Pass::setFragmentProgram	(	const String &	name,
		bool	resetParams = true
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

setGeometryProgram()

void Ogre::Pass::setGeometryProgram	(	const String &	name,
		bool	resetParams = true
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

setTessellationDomainProgram()

void Ogre::Pass::setTessellationDomainProgram	(	const String &	name,
		bool	resetParams = true
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

setTessellationHullProgram()

void Ogre::Pass::setTessellationHullProgram	(	const String &	name,
		bool	resetParams = true
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

setVertexProgram()

void Ogre::Pass::setVertexProgram	(	const String &	name,
		bool	resetParams = true
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

setComputeProgram()

void Ogre::Pass::setComputeProgram	(	const String &	name,
		bool	resetParams = true
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

getGpuProgramName()

const String& Ogre::Pass::getGpuProgramName

(

GpuProgramType

type

)

const

Gets the name of the program used by this pass.

getFragmentProgramName()

const String& Ogre::Pass::getFragmentProgramName ( void  ) const

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

References Ogre::GPT_FRAGMENT_PROGRAM.

getGeometryProgramName()

const String& Ogre::Pass::getGeometryProgramName ( void  ) const

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

References Ogre::GPT_GEOMETRY_PROGRAM.

getTessellationDomainProgramName()

const String& Ogre::Pass::getTessellationDomainProgramName ( void  ) const

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

References Ogre::GPT_DOMAIN_PROGRAM.

getTessellationHullProgramName()

const String& Ogre::Pass::getTessellationHullProgramName ( void  ) const

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

References Ogre::GPT_HULL_PROGRAM.

getVertexProgramName()

const String& Ogre::Pass::getVertexProgramName ( void  ) const

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

References Ogre::GPT_VERTEX_PROGRAM.

getComputeProgramName()

const String& Ogre::Pass::getComputeProgramName ( void  ) const

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

References Ogre::GPT_COMPUTE_PROGRAM.

setGpuProgramParameters()

void Ogre::Pass::setGpuProgramParameters	(	GpuProgramType	type,
		const GpuProgramParametersSharedPtr &	params
	)

Sets the Gpu program parameters.

Remarks

Only applicable to programmable passes, and this particular call is designed for low-level programs; use the named parameter methods for setting high-level program parameters.

setVertexProgramParameters()

void Ogre::Pass::setVertexProgramParameters

(

GpuProgramParametersSharedPtr

params

)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

setFragmentProgramParameters()

void Ogre::Pass::setFragmentProgramParameters

(

GpuProgramParametersSharedPtr

params

)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

setGeometryProgramParameters()

void Ogre::Pass::setGeometryProgramParameters

(

GpuProgramParametersSharedPtr

params

)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

setTessellationHullProgramParameters()

void Ogre::Pass::setTessellationHullProgramParameters

(

GpuProgramParametersSharedPtr

params

)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

setTessellationDomainProgramParameters()

void Ogre::Pass::setTessellationDomainProgramParameters

(

GpuProgramParametersSharedPtr

params

)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

setComputeProgramParameters()

void Ogre::Pass::setComputeProgramParameters

(

GpuProgramParametersSharedPtr

params

)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

getGpuProgramParameters()

const GpuProgramParametersSharedPtr& Ogre::Pass::getGpuProgramParameters

(

GpuProgramType

type

)

const

Gets the Gpu program parameters used by this pass.

getVertexProgramParameters()

GpuProgramParametersSharedPtr Ogre::Pass::getVertexProgramParameters

(

void

)

const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

getFragmentProgramParameters()

GpuProgramParametersSharedPtr Ogre::Pass::getFragmentProgramParameters

(

void

)

const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

getGeometryProgramParameters()

GpuProgramParametersSharedPtr Ogre::Pass::getGeometryProgramParameters

(

void

)

const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

getTessellationHullProgramParameters()

GpuProgramParametersSharedPtr Ogre::Pass::getTessellationHullProgramParameters

(

void

)

const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

getTessellationDomainProgramParameters()

GpuProgramParametersSharedPtr Ogre::Pass::getTessellationDomainProgramParameters

(

void

)

const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

getComputeProgramParameters()

GpuProgramParametersSharedPtr Ogre::Pass::getComputeProgramParameters

(

void

)

const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

_split()

Pass* Ogre::Pass::_split

(

unsigned short

numUnits

)

Splits this Pass to one which can be handled in the number of texture units specified.

Remarks

Only works on non-programmable passes, programmable passes cannot be split, it's up to the author to ensure that there is a fallback Technique for less capable cards.

Parameters

numUnits

The target number of texture units

Returns

A new Pass which contains the remaining units, and a scene_blend setting appropriate to approximate the multitexture. This Pass will be attached to the parent Technique of this Pass.

_notifyIndex()

void Ogre::Pass::_notifyIndex

(

unsigned short

index

)

Internal method to adjust pass index.

_prepare()

void Ogre::Pass::_prepare

(

void

)

Internal method for preparing to load this pass.

_unprepare()

void Ogre::Pass::_unprepare

(

void

)

Internal method for undoing the load preparartion for this pass.

_load()

void Ogre::Pass::_load

(

void

)

Internal method for loading this pass.

_unload()

void Ogre::Pass::_unload

(

void

)

Internal method for unloading this pass.

isLoaded()

bool Ogre::Pass::isLoaded

(

void

)

const

Is this loaded?

getHash()

uint32 Ogre::Pass::getHash ( void  ) const

inline

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

Remarks

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.

_dirtyHash()

void Ogre::Pass::_dirtyHash

(

void

)

Mark the hash as dirty.

_recalculateHash()

void Ogre::Pass::_recalculateHash

(

void

)

Internal method for recalculating the hash.

Remarks

Do not call this unless you are sure the old hash is not still being used by anything. If in doubt, call _dirtyHash if you want to force recalculation of the has next time.

_notifyNeedsRecompile()

void Ogre::Pass::_notifyNeedsRecompile

(

void

)

Tells the pass that it needs recompilation.

_updateAutoParams()

void Ogre::Pass::_updateAutoParams	(	const AutoParamDataSource *	source,
		uint16	variabilityMask
	)		const

Update automatic parameters.

Parameters

source	The source of the parameters
variabilityMask	A mask of GpuParamVariability which identifies which autos will need updating

_getTextureUnitWithContentTypeIndex()

unsigned short Ogre::Pass::_getTextureUnitWithContentTypeIndex	(	TextureUnitState::ContentType	contentType,
		unsigned short	index
	)		const

Gets the 'nth' texture which references the given content type.

Remarks

If the 'nth' texture unit which references the content type doesn't exist, then this method returns an arbitrary high-value outside the valid range to index texture units.

setTextureFiltering()

void Ogre::Pass::setTextureFiltering

(

TextureFilterOptions

filterType

)

Set texture filtering for every texture unit.

Note

This property actually exists on the TextureUnitState class For simplicity, this method allows you to set these properties for every current TeextureUnitState, If you need more precision, retrieve the TextureUnitState instance and set the property there.

See also

TextureUnitState::setTextureFiltering

setTextureAnisotropy()

void Ogre::Pass::setTextureAnisotropy

(

unsigned int

maxAniso

)

Sets the anisotropy level to be used for all textures.

Note

This property has been moved to the TextureUnitState class, which is accessible via the Technique and Pass. For simplicity, this method allows you to set these properties for every current TeextureUnitState, If you need more precision, retrieve the Technique, Pass and TextureUnitState instances and set the property there.

See also

TextureUnitState::setTextureAnisotropy

setNormaliseNormals()

void Ogre::Pass::setNormaliseNormals ( bool  normalise )

inline

If set to true, this forces normals to be normalised dynamically by the hardware for this pass.

This option can be used to prevent lighting variations when scaling an object - normally because this scaling is hardware based, the normals get scaled too which causes lighting to become inconsistent. By default the SceneManager detects scaled objects and does this for you, but this has an overhead so you might want to turn that off through Ogre::SceneManager::setNormaliseNormalsOnScale(false) and only do it per-Pass when you need to.

getNormaliseNormals()

bool Ogre::Pass::getNormaliseNormals ( void  ) const

inline

Returns true if this pass has auto-normalisation of normals set.

getDirtyHashList()

static const PassSet& Ogre::Pass::getDirtyHashList ( void  )

inlinestatic

Static method to retrieve all the Passes which need their hash values recalculated.

getPassGraveyard()

static const PassSet& Ogre::Pass::getPassGraveyard ( void  )

inlinestatic

Static method to retrieve all the Passes which are pending deletion.

clearDirtyHashList()

static void Ogre::Pass::clearDirtyHashList ( void  )

static

Static method to reset the list of passes which need their hash values recalculated.

Remarks

For performance, the dirty list is not updated progressively as the hashes are recalculated, instead we expect the processor of the dirty hash list to clear the list when they are done.

processPendingPassUpdates()

static void Ogre::Pass::processPendingPassUpdates ( void  )

static

Process all dirty and pending deletion passes.

queueForDeletion()

void Ogre::Pass::queueForDeletion

(

void

)

Queue this pass for deletion when appropriate.

isAmbientOnly()

bool Ogre::Pass::isAmbientOnly

(

void

)

const

Returns whether this pass is ambient only.

setPassIterationCount()

void Ogre::Pass::setPassIterationCount ( const size_t  count )

inline

set the number of iterations that this pass should perform when doing fast multi pass operation.

Remarks

Only applicable for programmable passes.

Parameters

count

number of iterations to perform fast multi pass operations. A value greater than 1 will cause the pass to be executed count number of times without changing the render state. This is very useful for passes that use programmable shaders that have to iterate more than once but don't need a render state change. Using multi pass can dramatically speed up rendering for materials that do things like fur, blur. A value of 1 turns off multi pass operation and the pass does the normal pass operation.

getPassIterationCount()

size_t Ogre::Pass::getPassIterationCount ( void  ) const

inline

Gets the pass iteration count value.

applyTextureAliases()

bool Ogre::Pass::applyTextureAliases	(	const AliasTextureNamePairList &	aliasList,
		const bool	apply = true
	)		const

Applies texture names to Texture Unit State with matching texture name aliases.

All Texture Unit States within the pass are checked. If matching texture aliases are found then true is returned.

Parameters

aliasList	is a map container of texture alias, texture name pairs
apply	set true to apply the texture aliases else just test to see if texture alias matches are found.

Returns

True if matching texture aliases were found in the pass.

setLightScissoringEnabled()

void Ogre::Pass::setLightScissoringEnabled ( bool  enabled )

inline

Sets whether or not this pass will be clipped by a scissor rectangle encompassing the lights that are being used in it.

In order to cut down on fillrate when you have a number of fixed-range lights in the scene, you can enable this option to request that during rendering, only the region of the screen which is covered by the lights is rendered. This region is the screen-space rectangle covering the union of the spheres making up the light ranges. Directional lights are ignored for this.

This is only likely to be useful for multipass additive lighting algorithms, where the scene has already been 'seeded' with an ambient pass and this pass is just adding light in affected areas.

When using Ogre::SHADOWTYPE_STENCIL_ADDITIVE or Ogre::SHADOWTYPE_TEXTURE_ADDITIVE, this option is implicitly used for all per-light passes and does not need to be specified. If you are not using shadows or are using a modulative or Integrated Texture Shadows then this could be useful.

getLightScissoringEnabled()

bool Ogre::Pass::getLightScissoringEnabled ( ) const

inline

Gets whether or not this pass will be clipped by a scissor rectangle encompassing the lights that are being used in it.

setLightClipPlanesEnabled()

void Ogre::Pass::setLightClipPlanesEnabled ( bool  enabled )

inline

Sets whether or not this pass will be clipped by user clips planes bounding the area covered by the light.

This option will only function if there is a single non-directional light being used in this pass. If there is more than one light, or only directional lights, then no clipping will occur. If there are no lights at all then the objects won’t be rendered at all.

In order to cut down on the geometry set up to render this pass when you have a single fixed-range light being rendered through it, you can enable this option to request that during triangle setup, clip planes are defined to bound the range of the light. In the case of a point light these planes form a cube, and in the case of a spotlight they form a pyramid. Directional lights are never clipped.

This option is only likely to be useful for multipass additive lighting algorithms, where the scene has already been 'seeded' with an ambient pass and this pass is just adding light in affected areas. In addition, it will only be honoured if there is exactly one non-directional light being used in this pass. Also, these clip planes override any user clip planes set on Camera.

When using Ogre::SHADOWTYPE_STENCIL_ADDITIVE or Ogre::SHADOWTYPE_TEXTURE_ADDITIVE, this option is automatically used for all per-light passes if you enable Ogre::SceneManager::setShadowUseLightClipPlanes and does not need to be specified. It is disabled by default since clip planes have a cost of their own which may not always exceed the benefits they give you. Generally the smaller your lights are the more chance you’ll see a benefit rather than a penalty from clipping.

Note

A specific note about OpenGL: user clip planes are completely ignored when you use an ARB vertex program. This means light clip planes won’t help much if you use ARB vertex programs on GL, although OGRE will perform some optimisation of its own, in that if it sees that the clip volume is completely off-screen, it won’t perform a render at all. When using GLSL, user clipping can be used but you have to use gl_ClipVertex in your shader, see the GLSL documentation for more information. In Direct3D user clip planes are always respected.

getLightClipPlanesEnabled()

bool Ogre::Pass::getLightClipPlanesEnabled ( ) const

inline

Gets whether or not this pass will be clipped by user clips planes bounding the area covered by the light.

setIlluminationStage()

void Ogre::Pass::setIlluminationStage ( IlluminationStage  is )

inline

Manually set which illumination stage this pass is a member of.

When using an additive lighting mode (Ogre::SHADOWTYPE_STENCIL_ADDITIVE or Ogre::SHADOWTYPE_TEXTURE_ADDITIVE), the scene is rendered in 3 discrete stages, ambient (or pre-lighting), per-light (once per light, with shadowing) and decal (or post-lighting). Usually OGRE figures out how to categorise your passes automatically, but there are some effects you cannot achieve without manually controlling the illumination. For example specular effects are muted by the typical sequence because all textures are saved until the Ogre::IS_DECAL stage which mutes the specular effect. Instead, you could do texturing within the per-light stage if it's possible for your material and thus add the specular on after the decal texturing, and have no post-light rendering.

If you assign an illumination stage to a pass you have to assign it to all passes in the technique otherwise it will be ignored. Also note that whilst you can have more than one pass in each group, they cannot alternate, ie all ambient passes will be before all per-light passes, which will also be before all decal passes. Within their categories the passes will retain their ordering though.

getIlluminationStage()

IlluminationStage Ogre::Pass::getIlluminationStage ( ) const

inline

Get the manually assigned illumination stage, if any.

setHashFunction() [1/2]

static void Ogre::Pass::setHashFunction ( BuiltinHashFunction  builtin )

static

Sets one of the default hash functions to be used.

Remarks

You absolutely must not change the hash function whilst any Pass instances exist in the render queue. The only time you can do this is either before you render anything, or directly after you manuall call RenderQueue::clear(true) to completely destroy the queue structures. The default is MIN_GPU_PROGRAM_CHANGE.

Note

You can also implement your own hash function, see the alternate version of this method.

See also

HashFunc

setHashFunction() [2/2]

static void Ogre::Pass::setHashFunction ( HashFunc *  hashFunc )

inlinestatic

Set the hash function used for all passes.

Remarks

You absolutely must not change the hash function whilst any Pass instances exist in the render queue. The only time you can do this is either before you render anything, or directly after you manuall call RenderQueue::clear(true) to completely destroy the queue structures.

Note

You can also use one of the built-in hash functions, see the alternate version of this method. The default is MIN_GPU_PROGRAM_CHANGE.

See also

HashFunc

getHashFunction()

static HashFunc* Ogre::Pass::getHashFunction ( void  )

inlinestatic

Get the hash function used for all passes.

getBuiltinHashFunction()

static HashFunc* Ogre::Pass::getBuiltinHashFunction ( BuiltinHashFunction  builtin )

static

Get the builtin hash function.

getUserObjectBindings() [1/2]

UserObjectBindings& Ogre::Pass::getUserObjectBindings ( )

inline

Return an instance of user objects binding associated with this class.

You can use it to associate one or more custom objects with this class instance.

See also

UserObjectBindings::setUserAny.

getUserObjectBindings() [2/2]

const UserObjectBindings& Ogre::Pass::getUserObjectBindings ( ) const

inline

Return an instance of user objects binding associated with this class.

You can use it to associate one or more custom objects with this class instance.

See also

UserObjectBindings::setUserAny.

---

The documentation for this class was generated from the following file:

• OgrePass.h