DigitalSpaces::DIOGREPass Struct Reference
[Ogre]

#include <OGREInterfaces.h>

Inherits DigitalSpaces::DIObjectBase.

Public Member Functions
bool	IsProgrammable (void)
	Returns true if this pass is programmable ie includes either a vertex or fragment program.
bool	HasVertexProgram (void)
	Returns true if this pass uses a programmable vertex pipeline.
bool	HasFragmentProgram (void)
	Returns true if this pass uses a programmable fragment pipeline.
unsigned short	GetIndex (void)
	Gets the index of this Pass in the parent Technique.
void	SetAmbient (float red, float green, float blue)
	Sets the ambient colour reflectance properties of this pass.
void	SetAmbient (in_Vector3f *ambient)
	Sets the ambient colour reflectance properties of this pass.
void	SetDiffuse (float red, float green, float blue, float alpha)
	Sets the diffuse colour reflectance properties of this pass.
void	SetDiffuse (in_Vector4f *diffuse)
	Sets the diffuse colour reflectance properties of this pass.
void	SetSpecular (float red, float green, float blue, float alpha)
	Sets the specular colour reflectance properties of this pass.
void	SetSpecular (in_Vector4f *specular)
	Sets the specular colour reflectance properties of this pass.
void	SetShininess (float val)
	Sets the shininess of the pass, affecting the size of specular highlights.
void	SetSelfIllumination (float red, float green, float blue)
	Sets the amount of self-illumination an object has.
void	SetSelfIllumination (in_Vector3f *selfIllum)
	Sets the amount of self-illumination an object has.
void	GetAmbient (out_Vector3f *colour)
	Sets which material properties follow the vertex colour.
void	GetDiffuse (out_Vector4f *colour)
	Gets the diffuse colour reflectance of the pass.
void	GetSpecular (out_Vector4f *colour)
	Gets the specular colour reflectance of the pass.
void	GetSelfIllumination (out_Vector3f *colour)
	Gets the self illumination colour of the pass.
float	GetShininess (void)
	Gets the 'shininess' property of the pass (affects specular highlights).
DIOGRETextureUnitState *	CreateTextureUnitState (void)
	Gets which material properties follow the vertex colour.
DIOGRETextureUnitState *	CreateTextureUnitState (const char *textureName)
	Inserts a new TextureUnitState object into the Pass.
DIOGRETextureUnitState *	CreateTextureUnitState (const char *textureName, unsigned short texCoordSet)
void	AddTextureUnitState (DIOGRETextureUnitState *state)
	Adds the passed in TextureUnitState, to the existing Pass.
DIOGRETextureUnitState *	GetTextureUnitState (unsigned short index)
	Retrieves a pointer to a texture unit state so it may be modified.
void	RemoveTextureUnitState (unsigned short index)
	Get an iterator over the TextureUnitStates contained in this Pass.
void	RemoveAllTextureUnitStates (void)
	Removes all texture unit settings.
unsigned long	GetNumTextureUnitStates (void)
	Returns the number of texture unit settings.
void	SetSceneBlending (OGRESceneBlendType sbt)
	Sets the kind of blending this pass has with the existing contents of the scene.
void	SetSceneBlending (OGRESceneBlendFactor sourceFactor, OGRESceneBlendFactor destFactor)
	Allows very fine control of blending this Pass with the existing contents of the scene.
OGRESceneBlendFactor	GetSourceBlendFactor ()
	Retrieves the source blending factor for the material (as set using Materiall::setSceneBlending).
OGRESceneBlendFactor	GetDestBlendFactor ()
	Retrieves the destination blending factor for the material (as set using Materiall::setSceneBlending).
bool	IsTransparent (void)
	Returns true if this pass has some element of transparency.
void	SetDepthCheckEnabled (bool enabled)
	Sets whether or not this pass renders with depth-buffer checking on or not.
bool	GetDepthCheckEnabled (void)
	Returns whether or not this pass renders with depth-buffer checking on or not.
void	SetDepthWriteEnabled (bool enabled)
	Sets whether or not this pass renders with depth-buffer writing on or not.
bool	GetDepthWriteEnabled (void)
	Returns whether or not this pass renders with depth-buffer writing on or not.
void	SetDepthFunction (OGRECompareFunction func)
	Sets the function used to compare depth values when depth checking is on.
OGRECompareFunction	GetDepthFunction (void)
	Returns the function used to compare depth values when depth checking is on.
void	SetColourWriteEnabled (bool enabled)
	Sets whether or not colour buffer writing is enabled for this Pass.
bool	GetColourWriteEnabled (void)
	Determines if colour buffer writing is enabled for this pass.
void	SetCullingMode (OGRECullingMode mode)
	Sets the culling mode for this pass based on the 'vertex winding'.
OGRECullingMode	GetCullingMode (void)
	Returns the culling mode for geometry rendered with this pass.
void	SetManualCullingMode (OGREManualCullingMode mode)
	Sets the manual culling mode, performed by CPU rather than hardware.
OGREManualCullingMode	GetManualCullingMode (void)
	Retrieves the manual culling mode for this pass.
void	SetLightingEnabled (bool enabled)
	Sets whether or not dynamic lighting is enabled.
bool	GetLightingEnabled (void)
	Returns whether or not dynamic lighting is enabled.
void	SetMaxSimultaneousLights (unsigned short maxLights)
	Sets the maximum number of lights to be used by this pass.
unsigned short	GetMaxSimultaneousLights (void)
	Gets the maximum number of lights to be used by this pass.
void	SetShadingMode (OGREShadeOptions mode)
	Sets the type of light shading required.
OGREShadeOptions	GetShadingMode (void)
	Returns the type of light shading to be used.
void	SetFog (bool overrideScene)
	Sets the fogging mode applied to this pass.
void	SetFog (bool overrideScene, OGREFogMode mode, in_Vector3f *colour, float expDensity, float linearStart, float linearEnd)
bool	GetFogOverride (void)
	Returns true if this pass is to override the scene fog settings.
OGREFogMode	GetFogMode (void)
	Returns the fog mode for this pass.
void	GetFogColour (out_Vector3f *colour)
	Returns the fog colour for the scene.
float	GetFogStart (void)
	Returns the fog start distance for this pass.
float	GetFogEnd (void)
	Returns the fog end distance for this pass.
float	GetFogDensity (void)
	Returns the fog density for this pass.
void	SetDepthBias (float constantBias, float slopeScaleBias)
	Sets the depth bias to be used for this material.
float	GetDepthBiasConstant (void)
	Retrieves the depth bias value as set by setDepthValue.
float	GetDepthBiasSlopeScale (void)
void	SetAlphaRejectSettings (OGRECompareFunction func, unsigned char value)
	Sets the way the pass will have use alpha to totally reject pixels from the pipeline.
void	SetAlphaRejectFunction (OGRECompareFunction func)
	Sets the alpha reject function.
void	SetAlphaRejectValue (unsigned char val)
	Gets the alpha reject value.
OGRECompareFunction	GetAlphaRejectFunction (void)
	Gets the alpha reject function.
unsigned char	GetAlphaRejectValue (void)
	Gets the alpha reject value.
void	SetIteratePerLight (bool enabled)
	Sets whether or not this pass should be run once per light which can affect the object being rendered.
void	SetIteratePerLight (bool enabled, bool onlyForOneLightType, OGRELightTypes lightType)
bool	GetIteratePerLight (void)
	Does this pass run once for every light in range?
bool	GetRunOnlyForOneLightType (void)
	Does this pass run only for a single light type (if getRunOncePerLight is true).
OGRELightTypes	GetOnlyLightType ()
	Gets the single light type this pass runs for if getRunOncePerLight and getRunOnlyForOneLightType are both true.
DIOGRETechnique *	GetParent (void)
	Gets the parent Technique.
const char *	GetResourceGroup (void)
	Gets the resource group of the ultimate parent Material.
void	SetVertexProgram (const char *name)
	Sets the details of the vertex program to use.
void	SetVertexProgram (const char *name, bool resetParams)
const char *	GetVertexProgramName (void)
	Sets the vertex program parameters.
const DIOGREGpuProgram *	GetVertexProgram (void)
	Gets the vertex program parameters used by this pass.
void	SetShadowCasterVertexProgram (const char *name)
	Sets the details of the vertex program to use when rendering as a shadow caster.
const char *	GetShadowCasterVertexProgramName (void)
	Sets the vertex program parameters for rendering as a shadow caster.
const DIOGREGpuProgram *	GetShadowCasterVertexProgram (void)
	Gets the vertex program parameters used by this pass when rendering shadow casters.
void	SetShadowReceiverVertexProgram (const char *name)
	Sets the details of the vertex program to use when rendering as a shadow receiver.
const char *	GetShadowReceiverVertexProgramName (void)
	Sets the vertex program parameters for rendering as a shadow receiver.
const DIOGREGpuProgram *	GetShadowReceiverVertexProgram (void)
	Gets the vertex program parameters used by this pass when rendering shadow receivers.
void	SetFragmentProgram (const char *name)
	Sets the details of the fragment program to use.
void	SetFragmentProgram (const char *name, bool resetParams)
const char *	GetFragmentProgramName (void)
	Sets the vertex program parameters.
const DIOGREGpuProgram *	GetFragmentProgram (void)
	Gets the vertex program parameters used by this pass.
bool	IsLoaded (void)
	Is this loaded?
unsigned long	GetHash (void)
	Gets the 'hash' of this pass, ie a precomputed number to use for sorting.
void	SetTextureFiltering (OGRETextureFilterOptions filterType)
	Set texture filtering for every texture unit.
void	SetTextureAnisotropy (unsigned int maxAniso)
	Sets the anisotropy level to be used for all textures.
void	QueueForDeletion (void)
	Queue this pass for deletion when appropriate.
bool	IsAmbientOnly (void)
	Returns whether this pass is ambient only.

---

Member Function Documentation

bool DigitalSpaces::DIOGREPass::IsProgrammable

(

void

)

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

bool DigitalSpaces::DIOGREPass::HasVertexProgram

(

void

)

Returns true if this pass uses a programmable vertex pipeline.

bool DigitalSpaces::DIOGREPass::HasFragmentProgram

(

void

)

Returns true if this pass uses a programmable fragment pipeline.

unsigned short DigitalSpaces::DIOGREPass::GetIndex

(

void

)

Gets the index of this Pass in the parent Technique.

void DigitalSpaces::DIOGREPass::SetAmbient	(	float	red,
		float	green,
		float	blue
	)

Sets the ambient colour reflectance properties of this pass.

Remarks:

The base colour of a pass is determined by how much red, green and blue light is reflects (provided texture layer #0 has a blend mode other than LBO_REPLACE). 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.

Note:

This setting has no effect if dynamic lighting is disabled (see Pass::setLightingEnabled), or if this is a programmable pass.

void DigitalSpaces::DIOGREPass::SetAmbient

(

in_Vector3f *

ambient

)

Sets the ambient colour reflectance properties of this pass.

Remarks:

The base colour of a pass is determined by how much red, green and blue light is reflects (provided texture layer #0 has a blend mode other than LBO_REPLACE). 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.

Note:

This setting has no effect if dynamic lighting is disabled (see Pass::setLightingEnabled), or if this is a programmable pass.

void DigitalSpaces::DIOGREPass::SetDiffuse	(	float	red,
		float	green,
		float	blue,
		float	alpha
	)

Sets the diffuse colour reflectance properties of this pass.

Remarks:

The base colour of a pass is determined by how much red, green and blue light is reflects (provided texture layer #0 has a blend mode other than LBO_REPLACE). 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.

Note:

This setting has no effect if dynamic lighting is disabled (see Pass::setLightingEnabled), or if this is a programmable pass.

void DigitalSpaces::DIOGREPass::SetDiffuse

(

in_Vector4f *

diffuse

)

Sets the diffuse colour reflectance properties of this pass.

Remarks:

The base colour of a pass is determined by how much red, green and blue light is reflects (provided texture layer #0 has a blend mode other than LBO_REPLACE). 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.

Note:

This setting has no effect if dynamic lighting is disabled (see Pass::setLightingEnabled), or if this is a programmable pass.

void DigitalSpaces::DIOGREPass::SetSpecular	(	float	red,
		float	green,
		float	blue,
		float	alpha
	)

Sets the specular colour reflectance properties of this pass.

Remarks:

The base colour of a pass is determined by how much red, green and blue light is reflects (provided texture layer #0 has a blend mode other than LBO_REPLACE). 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.

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 Pass::setLightingEnabled), or if this is a programmable pass.

void DigitalSpaces::DIOGREPass::SetSpecular

(

in_Vector4f *

specular

)

Sets the specular colour reflectance properties of this pass.

Remarks:

The base colour of a pass is determined by how much red, green and blue light is reflects (provided texture layer #0 has a blend mode other than LBO_REPLACE). 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.

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 Pass::setLightingEnabled), or if this is a programmable pass.

void DigitalSpaces::DIOGREPass::SetShininess

(

float

val

)

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

Note:

This setting has no effect if dynamic lighting is disabled (see Pass::setLightingEnabled), or if this is a programmable pass.

void DigitalSpaces::DIOGREPass::SetSelfIllumination	(	float	red,
		float	green,
		float	blue
	)

Sets the amount of self-illumination an object has.

Remarks:

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.

Note:

This setting has no effect if dynamic lighting is disabled (see Pass::setLightingEnabled), or if this is a programmable pass.

void DigitalSpaces::DIOGREPass::SetSelfIllumination

(

in_Vector3f *

selfIllum

)

Sets the amount of self-illumination an object has.

Remarks:

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.

Note:

This setting has no effect if dynamic lighting is disabled (see Pass::setLightingEnabled), or if this is a programmable pass.

void DigitalSpaces::DIOGREPass::GetAmbient

(

out_Vector3f *

colour

)

Sets which material properties follow the vertex colour.

Gets the ambient colour reflectance of the pass.

void DigitalSpaces::DIOGREPass::GetDiffuse

(

out_Vector4f *

colour

)

Gets the diffuse colour reflectance of the pass.

void DigitalSpaces::DIOGREPass::GetSpecular

(

out_Vector4f *

colour

)

Gets the specular colour reflectance of the pass.

void DigitalSpaces::DIOGREPass::GetSelfIllumination

(

out_Vector3f *

colour

)

Gets the self illumination colour of the pass.

float DigitalSpaces::DIOGREPass::GetShininess

(

void

)

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

DIOGRETextureUnitState* DigitalSpaces::DIOGREPass::CreateTextureUnitState

(

void

)

Gets which material properties follow the vertex colour.

Inserts a new TextureUnitState object into the Pass.

Remarks:

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

DIOGRETextureUnitState* DigitalSpaces::DIOGREPass::CreateTextureUnitState

(

const char *

textureName

)

Inserts a new TextureUnitState object into the Pass.

Remarks:

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

Parameters:

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

DIOGRETextureUnitState* DigitalSpaces::DIOGREPass::CreateTextureUnitState	(	const char *	textureName,
		unsigned short	texCoordSet
	)

void DigitalSpaces::DIOGREPass::AddTextureUnitState

(

DIOGRETextureUnitState *

state

)

Adds the passed in TextureUnitState, to the existing Pass.

DIOGRETextureUnitState* DigitalSpaces::DIOGREPass::GetTextureUnitState

(

unsigned short

index

)

Retrieves a pointer to a texture unit state so it may be modified.

void DigitalSpaces::DIOGREPass::RemoveTextureUnitState

(

unsigned short

index

)

Get an iterator over the TextureUnitStates contained in this Pass.

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.

void DigitalSpaces::DIOGREPass::RemoveAllTextureUnitStates

(

void

)

Removes all texture unit settings.

unsigned long DigitalSpaces::DIOGREPass::GetNumTextureUnitStates

(

void

)

Returns the number of texture unit settings.

void DigitalSpaces::DIOGREPass::SetSceneBlending

(

OGRESceneBlendType

sbt

)

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

Remarks:

Wheras the texture blending operations seen in the TextureUnitState class are concerned with blending between texture layers, this blending is about combining the output of the 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 OGRESceneBlendType blending types

void DigitalSpaces::DIOGREPass::SetSceneBlending	(	OGRESceneBlendFactor	sourceFactor,
		OGRESceneBlendFactor	destFactor
	)

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

Remarks:

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

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

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

Parameters:

	sourceFactor	The source factor in the above calculation, i.e. multiplied by the texture colour components.
	destFactor	The destination factor in the above calculation, i.e. multiplied by the pixel colour components.

Note:

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

OGRESceneBlendFactor DigitalSpaces::DIOGREPass::GetSourceBlendFactor

(

)

Retrieves the source blending factor for the material (as set using Materiall::setSceneBlending).

OGRESceneBlendFactor DigitalSpaces::DIOGREPass::GetDestBlendFactor

(

)

Retrieves the destination blending factor for the material (as set using Materiall::setSceneBlending).

bool DigitalSpaces::DIOGREPass::IsTransparent

(

void

)

Returns true if this pass has some element of transparency.

void DigitalSpaces::DIOGREPass::SetDepthCheckEnabled

(

bool

enabled

)

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

Remarks:

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:

setDepthFunction

bool DigitalSpaces::DIOGREPass::GetDepthCheckEnabled

(

void

)

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

See also:

setDepthCheckEnabled

void DigitalSpaces::DIOGREPass::SetDepthWriteEnabled

(

bool

enabled

)

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

Remarks:

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.

bool DigitalSpaces::DIOGREPass::GetDepthWriteEnabled

(

void

)

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

See also:

setDepthWriteEnabled

void DigitalSpaces::DIOGREPass::SetDepthFunction

(

OGRECompareFunction

func

)

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

Remarks:

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 CMPF_LESS_EQUAL, i.e. the pixel is written if it is closer (or at the same distance) than the current contents. If you wish you can change this comparison using this method.

OGRECompareFunction DigitalSpaces::DIOGREPass::GetDepthFunction

(

void

)

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

See also:

setDepthFunction

void DigitalSpaces::DIOGREPass::SetColourWriteEnabled

(

bool

enabled

)

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

Remarks:

For some effects, you might wish to turn off the colour write operation when rendering geometry; this means that only the depth buffer will be updated (provided you have depth buffer writing enabled, which you probably will do, although you may wish to only update the stencil buffer for example - stencil buffer state is managed at the RenderSystem level only, not the Material since you are likely to want to manage it at a higher level).

bool DigitalSpaces::DIOGREPass::GetColourWriteEnabled

(

void

)

Determines if colour buffer writing is enabled for this pass.

void DigitalSpaces::DIOGREPass::SetCullingMode

(

OGRECullingMode

mode

)

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

Remarks:

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 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 CULL_NONE option for mesh data that you cull yourself where the vertex winding is uncertain.

OGRECullingMode DigitalSpaces::DIOGREPass::GetCullingMode

(

void

)

Returns the culling mode for geometry rendered with this pass.

See setCullingMode for more information.

void DigitalSpaces::DIOGREPass::SetManualCullingMode

(

OGREManualCullingMode

mode

)

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

Remarks:

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.

Note:

The default for this setting is MANUAL_CULL_BACK.

Parameters:

mode

The mode to use - see enum OGREManualCullingMode for details

OGREManualCullingMode DigitalSpaces::DIOGREPass::GetManualCullingMode

(

void

)

Retrieves the manual culling mode for this pass.

See also:

setManualCullingMode

void DigitalSpaces::DIOGREPass::SetLightingEnabled

(

bool

enabled

)

Sets whether or not dynamic lighting is enabled.

Parameters:

enabled

If true, dynamic lighting is performed on geometry with normals supplied, geometry without normals will not be displayed.

If false, no lighting is applied and all geometry will be full brightness.

bool DigitalSpaces::DIOGREPass::GetLightingEnabled

(

void

)

Returns whether or not dynamic lighting is enabled.

void DigitalSpaces::DIOGREPass::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.

unsigned short DigitalSpaces::DIOGREPass::GetMaxSimultaneousLights

(

void

)

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

void DigitalSpaces::DIOGREPass::SetShadingMode

(

OGREShadeOptions

mode

)

Sets the type of light shading required.

Note:

The default shading method is Gouraud shading.

OGREShadeOptions DigitalSpaces::DIOGREPass::GetShadingMode

(

void

)

Returns the type of light shading to be used.

void DigitalSpaces::DIOGREPass::SetFog

(

bool

overrideScene

)

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 passs.
	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 OGREFogMode.
	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.

void DigitalSpaces::DIOGREPass::SetFog	(	bool	overrideScene,
		OGREFogMode	mode,
		in_Vector3f *	colour,
		float	expDensity,
		float	linearStart,
		float	linearEnd
	)

bool DigitalSpaces::DIOGREPass::GetFogOverride

(

void

)

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

OGREFogMode DigitalSpaces::DIOGREPass::GetFogMode

(

void

)

Returns the fog mode for this pass.

Note:

Only valid if getFogOverride is true.

void DigitalSpaces::DIOGREPass::GetFogColour

(

out_Vector3f *

colour

)

Returns the fog colour for the scene.

float DigitalSpaces::DIOGREPass::GetFogStart

(

void

)

Returns the fog start distance for this pass.

Note:

Only valid if getFogOverride is true.

float DigitalSpaces::DIOGREPass::GetFogEnd

(

void

)

Returns the fog end distance for this pass.

Note:

Only valid if getFogOverride is true.

float DigitalSpaces::DIOGREPass::GetFogDensity

(

void

)

Returns the fog density for this pass.

Note:

Only valid if getFogOverride is true.

void DigitalSpaces::DIOGREPass::SetDepthBias	(	float	constantBias,
		float	slopeScaleBias
	)

Sets the depth bias to be used for this material.

Remarks:

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.

Parameters:

bias

The bias value, should be between 0 and 16.

float DigitalSpaces::DIOGREPass::GetDepthBiasConstant

(

void

)

Retrieves the depth bias value as set by setDepthValue.

float DigitalSpaces::DIOGREPass::GetDepthBiasSlopeScale

(

void

)

void DigitalSpaces::DIOGREPass::SetAlphaRejectSettings	(	OGRECompareFunction	func,
		unsigned char	value
	)

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)

Note:

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

void DigitalSpaces::DIOGREPass::SetAlphaRejectFunction

(

OGRECompareFunction

func

)

Sets the alpha reject function.

See setAlphaRejectSettings for more information.

void DigitalSpaces::DIOGREPass::SetAlphaRejectValue

(

unsigned char

val

)

Gets the alpha reject value.

See setAlphaRejectSettings for more information.

OGRECompareFunction DigitalSpaces::DIOGREPass::GetAlphaRejectFunction

(

void

)

Gets the alpha reject function.

See setAlphaRejectSettings for more information.

unsigned char DigitalSpaces::DIOGREPass::GetAlphaRejectValue

(

void

)

Gets the alpha reject value.

See setAlphaRejectSettings for more information.

void DigitalSpaces::DIOGREPass::SetIteratePerLight

(

bool

enabled

)

Sets whether or not this pass should be run once per light 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, 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 once per light which can affect this object. In this case, only light index 0 is ever used, and is a different light every time the pass is issued, up to the total number of lights which is affecting this object. This has 2 advantages:

• There is no limit on the number of lights which can be supported
• It's easier to write vertex / fragment programs for this because a single program can be used for any number of lights

However, this technique is a lot more expensive, and typically you will want an additional ambient pass, because if no lights are affecting the object it will not be rendered at all, which will look odd even if ambient light is zero (imagine if there are lit objects behind it - the objects silhouette would not show up). Therefore, use this option with care, and you would be well advised to provide a less expensive fallback technique for use in the distance.

Note:

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

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

void DigitalSpaces::DIOGREPass::SetIteratePerLight	(	bool	enabled,
		bool	onlyForOneLightType,
		OGRELightTypes	lightType
	)

bool DigitalSpaces::DIOGREPass::GetIteratePerLight

(

void

)

Does this pass run once for every light in range?

bool DigitalSpaces::DIOGREPass::GetRunOnlyForOneLightType

(

void

)

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

OGRELightTypes DigitalSpaces::DIOGREPass::GetOnlyLightType

(

)

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

DIOGRETechnique* DigitalSpaces::DIOGREPass::GetParent

(

void

)

Gets the parent Technique.

const char* DigitalSpaces::DIOGREPass::GetResourceGroup

(

void

)

Gets the resource group of the ultimate parent Material.

void DigitalSpaces::DIOGREPass::SetVertexProgram

(

const char *

name

)

Sets the details of the vertex program to use.

Remarks:

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

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 vertex program in this pass is disabled.
	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.

void DigitalSpaces::DIOGREPass::SetVertexProgram	(	const char *	name,
		bool	resetParams
	)

const char* DigitalSpaces::DIOGREPass::GetVertexProgramName

(

void

)

Sets the vertex 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. Gets the name of the vertex program used by this pass.

const DIOGREGpuProgram* DigitalSpaces::DIOGREPass::GetVertexProgram

(

void

)

Gets the vertex program parameters used by this pass.

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

void DigitalSpaces::DIOGREPass::SetShadowCasterVertexProgram

(

const char *

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 implemetors 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 explict vertex program alternative is not set.

const char* DigitalSpaces::DIOGREPass::GetShadowCasterVertexProgramName

(

void

)

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. Gets the name of the vertex program used by this pass when rendering shadow casters.

const DIOGREGpuProgram* DigitalSpaces::DIOGREPass::GetShadowCasterVertexProgram

(

void

)

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

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

void DigitalSpaces::DIOGREPass::SetShadowReceiverVertexProgram

(

const char *

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 implemetors 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.

const char* DigitalSpaces::DIOGREPass::GetShadowReceiverVertexProgramName

(

void

)

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. Gets the name of the vertex program used by this pass when rendering shadow receivers.

const DIOGREGpuProgram* DigitalSpaces::DIOGREPass::GetShadowReceiverVertexProgram

(

void

)

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

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

void DigitalSpaces::DIOGREPass::SetFragmentProgram

(

const char *

name

)

Sets the details of the fragment program to use.

Remarks:

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

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 fragment program in this pass is disabled.
	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.

void DigitalSpaces::DIOGREPass::SetFragmentProgram	(	const char *	name,
		bool	resetParams
	)

const char* DigitalSpaces::DIOGREPass::GetFragmentProgramName

(

void

)

Sets the vertex program parameters.

Remarks:

Only applicable to programmable passes. Gets the name of the fragment program used by this pass.

const DIOGREGpuProgram* DigitalSpaces::DIOGREPass::GetFragmentProgram

(

void

)

Gets the vertex program parameters used by this pass.

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

bool DigitalSpaces::DIOGREPass::IsLoaded

(

void

)

Is this loaded?

unsigned long DigitalSpaces::DIOGREPass::GetHash

(

void

)

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.

void DigitalSpaces::DIOGREPass::SetTextureFiltering

(

OGRETextureFilterOptions

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

void DigitalSpaces::DIOGREPass::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

void DigitalSpaces::DIOGREPass::QueueForDeletion

(

void

)

Queue this pass for deletion when appropriate.

bool DigitalSpaces::DIOGREPass::IsAmbientOnly

(

void

)

Returns whether this pass is ambient only.

---

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

• OGREInterfaces/OGREInterfaces.h