Context Navigation

OgrePass.h

Last change on this file was 148, checked in by patricwi, 6 years ago
Added new dependencies for ogre1.9 and cegui0.8
File size: 88.9 KB

Rev	Line
[148]	1	/*
	2	-----------------------------------------------------------------------------
	3	This source file is part of OGRE
	4	(Object-oriented Graphics Rendering Engine)
	5	For the latest info, see http://www.ogre3d.org
	6
	7	Copyright (c) 2000-2013 Torus Knot Software Ltd
	8
	9	Permission is hereby granted, free of charge, to any person obtaining a copy
	10	of this software and associated documentation files (the "Software"), to deal
	11	in the Software without restriction, including without limitation the rights
	12	to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
	13	copies of the Software, and to permit persons to whom the Software is
	14	furnished to do so, subject to the following conditions:
	15
	16	The above copyright notice and this permission notice shall be included in
	17	all copies or substantial portions of the Software.
	18
	19	THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
	20	IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
	21	FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
	22	AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
	23	LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
	24	OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
	25	THE SOFTWARE.
	26	-----------------------------------------------------------------------------
	27	*/
	28	#ifndef __Pass_H__
	29	#define __Pass_H__
	30
	31	#include "OgrePrerequisites.h"
	32	#include "OgreGpuProgram.h"
	33	#include "OgreColourValue.h"
	34	#include "OgreBlendMode.h"
	35	#include "OgreCommon.h"
	36	#include "OgreLight.h"
	37	#include "OgreTextureUnitState.h"
	38	#include "OgreUserObjectBindings.h"
	39
	40	namespace Ogre {
	41
	42	/** \addtogroup Core
	43	* @{
	44	*/
	45	/** \addtogroup Materials
	46	* @{
	47	*/
	48	/// Categorisation of passes for the purpose of additive lighting
	49	enum IlluminationStage
	50	{
	51	/// Part of the rendering which occurs without any kind of direct lighting
	52	IS_AMBIENT,
	53	/// Part of the rendering which occurs per light
	54	IS_PER_LIGHT,
	55	/// Post-lighting rendering
	56	IS_DECAL,
	57	/// Not determined
	58	IS_UNKNOWN
	59	};
	60
	61	/** Class defining a single pass of a Technique (of a Material), i.e.
	62	a single rendering call.
	63	@remarks
	64	Rendering can be repeated with many passes for more complex effects.
	65	Each pass is either a fixed-function pass (meaning it does not use
	66	a vertex or fragment program) or a programmable pass (meaning it does
	67	use either a vertex and fragment program, or both).
	68	@par
	69	Programmable passes are complex to define, because they require custom
	70	programs and you have to set all constant inputs to the programs (like
	71	the position of lights, any base material colours you wish to use etc), but
	72	they do give you much total flexibility over the algorithms used to render your
	73	pass, and you can create some effects which are impossible with a fixed-function pass.
	74	On the other hand, you can define a fixed-function pass in very little time, and
	75	you can use a range of fixed-function effects like environment mapping very
	76	easily, plus your pass will be more likely to be compatible with older hardware.
	77	There are pros and cons to both, just remember that if you use a programmable
	78	pass to create some great effects, allow more time for definition and testing.
	79	*/
	80	class _OgreExport Pass : public PassAlloc
	81	{
	82	public:
	83	/** Definition of a functor for calculating the hashcode of a Pass.
	84	@remarks
	85	The hashcode of a Pass is used to sort Passes for rendering, in order
	86	to reduce the number of render state changes. Each Pass represents a
	87	single unique set of states, but by ordering them, state changes can
	88	be minimised between passes. An implementation of this functor should
	89	order passes so that the elements that you want to keep constant are
	90	sorted next to each other.
	91	@see Pass::setHashFunc
	92	*/
	93	struct HashFunc
	94	{
	95	virtual uint32 operator()(const Pass* p) const = 0;
	96	/// Need virtual destructor in case subclasses use it
	97	virtual ~HashFunc() {}
	98	};
	99	protected:
	100	Technique* mParent;
	101	unsigned short mIndex; /// Pass index
	102	String mName; /// Optional name for the pass
	103	uint32 mHash; /// Pass hash
	104	bool mHashDirtyQueued; /// Needs to be dirtied when next loaded
	105	//-------------------------------------------------------------------------
	106	// Colour properties, only applicable in fixed-function passes
	107	ColourValue mAmbient;
	108	ColourValue mDiffuse;
	109	ColourValue mSpecular;
	110	ColourValue mEmissive;
	111	Real mShininess;
	112	TrackVertexColourType mTracking;
	113	//-------------------------------------------------------------------------
	114
	115	//-------------------------------------------------------------------------
	116	// Blending factors
	117	SceneBlendFactor mSourceBlendFactor;
	118	SceneBlendFactor mDestBlendFactor;
	119	SceneBlendFactor mSourceBlendFactorAlpha;
	120	SceneBlendFactor mDestBlendFactorAlpha;
	121
	122	// Used to determine if separate alpha blending should be used for color and alpha channels
	123	bool mSeparateBlend;
	124
	125	//-------------------------------------------------------------------------
	126	// Blending operations
	127	SceneBlendOperation mBlendOperation;
	128	SceneBlendOperation mAlphaBlendOperation;
	129
	130	/// Determines if we should use separate blending operations for color and alpha channels
	131	bool mSeparateBlendOperation;
	132
	133	//-------------------------------------------------------------------------
	134
	135	//-------------------------------------------------------------------------
	136	// Depth buffer settings
	137	bool mDepthCheck;
	138	bool mDepthWrite;
	139	CompareFunction mDepthFunc;
	140	float mDepthBiasConstant;
	141	float mDepthBiasSlopeScale;
	142	float mDepthBiasPerIteration;
	143
	144	/// Colour buffer settings
	145	bool mColourWrite;
	146
	147	// Alpha reject settings
	148	CompareFunction mAlphaRejectFunc;
	149	unsigned char mAlphaRejectVal;
	150	bool mAlphaToCoverageEnabled;
	151
	152	/// Transparent depth sorting
	153	bool mTransparentSorting;
	154	/// Transparent depth sorting forced
	155	bool mTransparentSortingForced;
	156	//-------------------------------------------------------------------------
	157
	158	//-------------------------------------------------------------------------
	159	// Culling mode
	160	CullingMode mCullMode;
	161	ManualCullingMode mManualCullMode;
	162	//-------------------------------------------------------------------------
	163
	164	/// Lighting enabled?
	165	bool mLightingEnabled;
	166	/// Max simultaneous lights
	167	unsigned short mMaxSimultaneousLights;
	168	/// Starting light index
	169	unsigned short mStartLight;
	170	/// Run this pass once per light?
	171	bool mIteratePerLight;
	172	/// Iterate per how many lights?
	173	unsigned short mLightsPerIteration;
	174	/// Should it only be run for a certain light type?
	175	bool mRunOnlyForOneLightType;
	176	Light::LightTypes mOnlyLightType;
	177	/// With a specific light mask?
	178	uint32 mLightMask;
	179
	180	/// Shading options
	181	ShadeOptions mShadeOptions;
	182	/// Polygon mode
	183	PolygonMode mPolygonMode;
	184	/// Normalisation
	185	bool mNormaliseNormals;
	186	bool mPolygonModeOverrideable;
	187	//-------------------------------------------------------------------------
	188	// Fog
	189	bool mFogOverride;
	190	FogMode mFogMode;
	191	ColourValue mFogColour;
	192	Real mFogStart;
	193	Real mFogEnd;
	194	Real mFogDensity;
	195	//-------------------------------------------------------------------------
	196
	197	/// Storage of texture unit states
	198	typedef vector<TextureUnitState*>::type TextureUnitStates;
	199	TextureUnitStates mTextureUnitStates;
	200
	201	/// Vertex program details
	202	GpuProgramUsage *mVertexProgramUsage;
	203	/// Vertex program details
	204	GpuProgramUsage *mShadowCasterVertexProgramUsage;
	205	/// Fragment program details
	206	GpuProgramUsage *mShadowCasterFragmentProgramUsage;
	207	/// Vertex program details
	208	GpuProgramUsage *mShadowReceiverVertexProgramUsage;
	209	/// Fragment program details
	210	GpuProgramUsage *mFragmentProgramUsage;
	211	/// Fragment program details
	212	GpuProgramUsage *mShadowReceiverFragmentProgramUsage;
	213	/// Geometry program details
	214	GpuProgramUsage *mGeometryProgramUsage;
	215	/// Tesselation hull program details
	216	GpuProgramUsage *mTesselationHullProgramUsage;
	217	/// Tesselation domain program details
	218	GpuProgramUsage *mTesselationDomainProgramUsage;
	219	/// Compute program details
	220	GpuProgramUsage *mComputeProgramUsage;
	221	/// Is this pass queued for deletion?
	222	bool mQueuedForDeletion;
	223	/// Number of pass iterations to perform
	224	size_t mPassIterationCount;
	225	/// Point size, applies when not using per-vertex point size
	226	Real mPointSize;
	227	Real mPointMinSize;
	228	Real mPointMaxSize;
	229	bool mPointSpritesEnabled;
	230	bool mPointAttenuationEnabled;
	231	/// Constant, linear, quadratic coeffs
	232	Real mPointAttenuationCoeffs[3];
	233	// TU Content type lookups
	234	typedef vector<unsigned short>::type ContentTypeLookup;
	235	mutable ContentTypeLookup mShadowContentTypeLookup;
	236	mutable bool mContentTypeLookupBuilt;
	237	/// Scissoring for the light?
	238	bool mLightScissoring;
	239	/// User clip planes for light?
	240	bool mLightClipPlanes;
	241	/// Illumination stage?
	242	IlluminationStage mIlluminationStage;
	243	/// User objects binding.
	244	UserObjectBindings mUserObjectBindings;
	245
	246
	247	/// Used to get scene blending flags from a blending type
	248	void _getBlendFlags(SceneBlendType type, SceneBlendFactor& source, SceneBlendFactor& dest);
	249
	250	public:
	251	typedef set<Pass*>::type PassSet;
	252	protected:
	253	/// List of Passes whose hashes need recalculating
	254	static PassSet msDirtyHashList;
	255	/// The place where passes go to die
	256	static PassSet msPassGraveyard;
	257	/// The Pass hash functor
	258	static HashFunc* msHashFunc;
	259	public:
	260	OGRE_STATIC_MUTEX(msDirtyHashListMutex);
	261	OGRE_STATIC_MUTEX(msPassGraveyardMutex);
	262	OGRE_MUTEX(mTexUnitChangeMutex);
	263	OGRE_MUTEX(mGpuProgramChangeMutex);
	264	/// Default constructor
	265	Pass(Technique* parent, unsigned short index);
	266	/// Copy constructor
	267	Pass(Technique* parent, unsigned short index, const Pass& oth );
	268	/// Operator = overload
	269	Pass& operator=(const Pass& oth);
	270	virtual ~Pass();
	271
	272	/// Returns true if this pass is programmable i.e. includes either a vertex or fragment program.
	273	bool isProgrammable(void) const { return mVertexProgramUsage \|\| mFragmentProgramUsage \|\| mGeometryProgramUsage \|\|
	274	mTesselationHullProgramUsage \|\| mTesselationDomainProgramUsage \|\| mComputeProgramUsage; }
	275
	276	/// Returns true if this pass uses a programmable vertex pipeline
	277	bool hasVertexProgram(void) const { return mVertexProgramUsage != NULL; }
	278	/// Returns true if this pass uses a programmable fragment pipeline
	279	bool hasFragmentProgram(void) const { return mFragmentProgramUsage != NULL; }
	280	/// Returns true if this pass uses a programmable geometry pipeline
	281	bool hasGeometryProgram(void) const { return mGeometryProgramUsage != NULL; }
	282	/// Returns true if this pass uses a programmable tesselation control pipeline
	283	bool hasTesselationHullProgram(void) const { return mTesselationHullProgramUsage != NULL; }
	284	/// Returns true if this pass uses a programmable tesselation control pipeline
	285	bool hasTesselationDomainProgram(void) const { return mTesselationDomainProgramUsage != NULL; }
	286	/// Returns true if this pass uses a programmable compute pipeline
	287	bool hasComputeProgram(void) const { return mComputeProgramUsage != NULL; }
	288	/// Returns true if this pass uses a shadow caster vertex program
	289	bool hasShadowCasterVertexProgram(void) const { return mShadowCasterVertexProgramUsage != NULL; }
	290	/// Returns true if this pass uses a shadow caster fragment program
	291	bool hasShadowCasterFragmentProgram(void) const { return mShadowCasterFragmentProgramUsage != NULL; }
	292	/// Returns true if this pass uses a shadow receiver vertex program
	293	bool hasShadowReceiverVertexProgram(void) const { return mShadowReceiverVertexProgramUsage != NULL; }
	294	/// Returns true if this pass uses a shadow receiver fragment program
	295	bool hasShadowReceiverFragmentProgram(void) const { return mShadowReceiverFragmentProgramUsage != NULL; }
	296
	297	size_t calculateSize(void) const;
	298
	299	/// Gets the index of this Pass in the parent Technique
	300	unsigned short getIndex(void) const { return mIndex; }
	301	/* Set the name of the pass
	302	@remarks
	303	The name of the pass is optional. Its useful in material scripts where a material could inherit
	304	from another material and only want to modify a particular pass.
	305	*/
	306	void setName(const String& name);
	307	/// Get the name of the pass
	308	const String& getName(void) const { return mName; }
	309
	310	/** Sets the ambient colour reflectance properties of this pass.
	311	@remarks
	312	The base colour of a pass is determined by how much red, green and blue light is reflects
	313	(provided texture layer #0 has a blend mode other than LBO_REPLACE). This property determines how
	314	much ambient light (directionless global light) is reflected. The default is full white, meaning
	315	objects are completely globally illuminated. Reduce this if you want to see diffuse or specular light
	316	effects, or change the blend of colours to make the object have a base colour other than white.
	317	@note
	318	This setting has no effect if dynamic lighting is disabled (see Pass::setLightingEnabled),
	319	or if this is a programmable pass.
	320	*/
	321	void setAmbient(Real red, Real green, Real blue);
	322
	323	/** Sets the ambient colour reflectance properties of this pass.
	324	@remarks
	325	The base colour of a pass is determined by how much red, green and blue light is reflects
	326	(provided texture layer #0 has a blend mode other than LBO_REPLACE). This property determines how
	327	much ambient light (directionless global light) is reflected. The default is full white, meaning
	328	objects are completely globally illuminated. Reduce this if you want to see diffuse or specular light
	329	effects, or change the blend of colours to make the object have a base colour other than white.
	330	@note
	331	This setting has no effect if dynamic lighting is disabled (see Pass::setLightingEnabled),
	332	or if this is a programmable pass.
	333	*/
	334
	335	void setAmbient(const ColourValue& ambient);
	336
	337	/** Sets the diffuse colour reflectance properties of this pass.
	338	@remarks
	339	The base colour of a pass is determined by how much red, green and blue light is reflects
	340	(provided texture layer #0 has a blend mode other than LBO_REPLACE). This property determines how
	341	much diffuse light (light from instances of the Light class in the scene) is reflected. The default
	342	is full white, meaning objects reflect the maximum white light they can from Light objects.
	343	@note
	344	This setting has no effect if dynamic lighting is disabled (see Pass::setLightingEnabled),
	345	or if this is a programmable pass.
	346	*/
	347	void setDiffuse(Real red, Real green, Real blue, Real alpha);
	348
	349	/** Sets the diffuse colour reflectance properties of this pass.
	350	@remarks
	351	The base colour of a pass is determined by how much red, green and blue light is reflects
	352	(provided texture layer #0 has a blend mode other than LBO_REPLACE). This property determines how
	353	much diffuse light (light from instances of the Light class in the scene) is reflected. The default
	354	is full white, meaning objects reflect the maximum white light they can from Light objects.
	355	@note
	356	This setting has no effect if dynamic lighting is disabled (see Pass::setLightingEnabled),
	357	or if this is a programmable pass.
	358	*/
	359	void setDiffuse(const ColourValue& diffuse);
	360
	361	/** Sets the specular colour reflectance properties of this pass.
	362	@remarks
	363	The base colour of a pass is determined by how much red, green and blue light is reflects
	364	(provided texture layer #0 has a blend mode other than LBO_REPLACE). This property determines how
	365	much specular light (highlights from instances of the Light class in the scene) is reflected.
	366	The default is to reflect no specular light.
	367	@note
	368	The size of the specular highlights is determined by the separate 'shininess' property.
	369	@note
	370	This setting has no effect if dynamic lighting is disabled (see Pass::setLightingEnabled),
	371	or if this is a programmable pass.
	372	*/
	373	void setSpecular(Real red, Real green, Real blue, Real alpha);
	374
	375	/** Sets the specular colour reflectance properties of this pass.
	376	@remarks
	377	The base colour of a pass is determined by how much red, green and blue light is reflects
	378	(provided texture layer #0 has a blend mode other than LBO_REPLACE). This property determines how
	379	much specular light (highlights from instances of the Light class in the scene) is reflected.
	380	The default is to reflect no specular light.
	381	@note
	382	The size of the specular highlights is determined by the separate 'shininess' property.
	383	@note
	384	This setting has no effect if dynamic lighting is disabled (see Pass::setLightingEnabled),
	385	or if this is a programmable pass.
	386	*/
	387	void setSpecular(const ColourValue& specular);
	388
	389	/** Sets the shininess of the pass, affecting the size of specular highlights.
	390	@note
	391	This setting has no effect if dynamic lighting is disabled (see Pass::setLightingEnabled),
	392	or if this is a programmable pass.
	393	*/
	394	void setShininess(Real val);
	395
	396	/** Sets the amount of self-illumination an object has.
	397	@remarks
	398	If an object is self-illuminating, it does not need external sources to light it, ambient or
	399	otherwise. It's like the object has it's own personal ambient light. This property is rarely useful since
	400	you can already specify per-pass ambient light, but is here for completeness.
	401	@note
	402	This setting has no effect if dynamic lighting is disabled (see Pass::setLightingEnabled),
	403	or if this is a programmable pass.
	404	*/
	405	void setSelfIllumination(Real red, Real green, Real blue);
	406
	407	/** Sets the amount of self-illumination an object has.
	408	@see
	409	setSelfIllumination
	410	*/
	411	void setEmissive(Real red, Real green, Real blue)
	412	{
	413	setSelfIllumination(red, green, blue);
	414	}
	415
	416	/** Sets the amount of self-illumination an object has.
	417	@remarks
	418	If an object is self-illuminating, it does not need external sources to light it, ambient or
	419	otherwise. It's like the object has it's own personal ambient light. This property is rarely useful since
	420	you can already specify per-pass ambient light, but is here for completeness.
	421	@note
	422	This setting has no effect if dynamic lighting is disabled (see Pass::setLightingEnabled),
	423	or if this is a programmable pass.
	424	*/
	425	void setSelfIllumination(const ColourValue& selfIllum);
	426
	427	/** Sets the amount of self-illumination an object has.
	428	@see
	429	setSelfIllumination
	430	*/
	431	void setEmissive(const ColourValue& emissive)
	432	{
	433	setSelfIllumination(emissive);
	434	}
	435
	436	/** Sets which material properties follow the vertex colour
	437	*/
	438	void setVertexColourTracking(TrackVertexColourType tracking);
	439
	440	/** Gets the point size of the pass.
	441	@remarks
	442	This property determines what point size is used to render a point
	443	list.
	444	*/
	445	Real getPointSize(void) const;
	446
	447	/** Sets the point size of this pass.
	448	@remarks
	449	This setting allows you to change the size of points when rendering
	450	a point list, or a list of point sprites. The interpretation of this
	451	command depends on the Pass::setPointSizeAttenuation option - if it
	452	is off (the default), the point size is in screen pixels, if it is on,
	453	it expressed as normalised screen coordinates (1.0 is the height of
	454	the screen) when the point is at the origin.
	455	@note
	456	Some drivers have an upper limit on the size of points they support
	457	- this can even vary between APIs on the same card! Don't rely on
	458	point sizes that cause the point sprites to get very large on screen,
	459	since they may get clamped on some cards. Upper sizes can range from
	460	64 to 256 pixels.
	461	*/
	462	void setPointSize(Real ps);
	463
	464	/** Sets whether or not rendering points using OT_POINT_LIST will
	465	render point sprites (textured quads) or plain points (dots).
	466	@param enabled True enables point sprites, false returns to normal
	467	point rendering.
	468	*/
	469	void setPointSpritesEnabled(bool enabled);
	470
	471	/** Returns whether point sprites are enabled when rendering a
	472	point list.
	473	*/
	474	bool getPointSpritesEnabled(void) const;
	475
	476	/** Sets how points are attenuated with distance.
	477	@remarks
	478	When performing point rendering or point sprite rendering,
	479	point size can be attenuated with distance. The equation for
	480	doing this is attenuation = 1 / (constant + linear * dist + quadratic * d^2).
	481	@par
	482	For example, to disable distance attenuation (constant screensize)
	483	you would set constant to 1, and linear and quadratic to 0. A
	484	standard perspective attenuation would be 0, 1, 0 respectively.
	485	@note
	486	The resulting size is clamped to the minimum and maximum point
	487	size.
	488	@param enabled Whether point attenuation is enabled
	489	@param constant Parameters to the attenuation function defined above
	490	@param linear Parameters to the attenuation function defined above
	491	@param quadratic Parameters to the attenuation function defined above
	492	*/
	493	void setPointAttenuation(bool enabled,
	494	Real constant = 0.0f, Real linear = 1.0f, Real quadratic = 0.0f);
	495
	496	/** Returns whether points are attenuated with distance. */
	497	bool isPointAttenuationEnabled(void) const;
	498
	499	/** Returns the constant coefficient of point attenuation. */
	500	Real getPointAttenuationConstant(void) const;
	501	/** Returns the linear coefficient of point attenuation. */
	502	Real getPointAttenuationLinear(void) const;
	503	/** Returns the quadratic coefficient of point attenuation. */
	504	Real getPointAttenuationQuadratic(void) const;
	505
	506	/** Set the minimum point size, when point attenuation is in use. */
	507	void setPointMinSize(Real min);
	508	/** Get the minimum point size, when point attenuation is in use. */
	509	Real getPointMinSize(void) const;
	510	/** Set the maximum point size, when point attenuation is in use.
	511	@remarks Setting this to 0 indicates the max size supported by the card.
	512	*/
	513	void setPointMaxSize(Real max);
	514	/** Get the maximum point size, when point attenuation is in use.
	515	@remarks 0 indicates the max size supported by the card.
	516	*/
	517	Real getPointMaxSize(void) const;
	518
	519	/** Gets the ambient colour reflectance of the pass.
	520	*/
	521	const ColourValue& getAmbient(void) const;
	522
	523	/** Gets the diffuse colour reflectance of the pass.
	524	*/
	525	const ColourValue& getDiffuse(void) const;
	526
	527	/** Gets the specular colour reflectance of the pass.
	528	*/
	529	const ColourValue& getSpecular(void) const;
	530
	531	/** Gets the self illumination colour of the pass.
	532	*/
	533	const ColourValue& getSelfIllumination(void) const;
	534
	535	/** Gets the self illumination colour of the pass.
	536	@see
	537	getSelfIllumination
	538	*/
	539	const ColourValue& getEmissive(void) const
	540	{
	541	return getSelfIllumination();
	542	}
	543
	544	/** Gets the 'shininess' property of the pass (affects specular highlights).
	545	*/
	546	Real getShininess(void) const;
	547
	548	/** Gets which material properties follow the vertex colour
	549	*/
	550	TrackVertexColourType getVertexColourTracking(void) const;
	551
	552	/** Inserts a new TextureUnitState object into the Pass.
	553	@remarks
	554	This unit is is added on top of all previous units.
	555	*/
	556	TextureUnitState* createTextureUnitState(void);
	557	/** Inserts a new TextureUnitState object into the Pass.
	558	@remarks
	559	This unit is is added on top of all previous units.
	560	@param textureName
	561	The basic name of the texture e.g. brickwall.jpg, stonefloor.png
	562	@param texCoordSet
	563	The index of the texture coordinate set to use.
	564	@note
	565	Applies to both fixed-function and programmable passes.
	566	*/
	567	TextureUnitState* createTextureUnitState( const String& textureName, unsigned short texCoordSet = 0);
	568	/** Adds the passed in TextureUnitState, to the existing Pass.
	569	@param
	570	state The Texture Unit State to be attached to this pass. It must not be attached to another pass.
	571	@note
	572	Throws an exception if the TextureUnitState is attached to another Pass.*/
	573	void addTextureUnitState(TextureUnitState* state);
	574	/** Retrieves a pointer to a texture unit state so it may be modified.
	575	*/
	576	TextureUnitState* getTextureUnitState(unsigned short index);
	577	/** Retrieves the Texture Unit State matching name.
	578	Returns 0 if name match is not found.
	579	*/
	580	TextureUnitState* getTextureUnitState(const String& name);
	581	/** Retrieves a const pointer to a texture unit state.
	582	*/
	583	const TextureUnitState* getTextureUnitState(unsigned short index) const;
	584	/** Retrieves the Texture Unit State matching name.
	585	Returns 0 if name match is not found.
	586	*/
	587	const TextureUnitState* getTextureUnitState(const String& name) const;
	588
	589	/** Retrieve the index of the Texture Unit State in the pass.
	590	@param
	591	state The Texture Unit State this is attached to this pass.
	592	@note
	593	Throws an exception if the state is not attached to the pass.
	594	*/
	595	unsigned short getTextureUnitStateIndex(const TextureUnitState* state) const;
	596
	597	typedef VectorIterator<TextureUnitStates> TextureUnitStateIterator;
	598	/** Get an iterator over the TextureUnitStates contained in this Pass. */
	599	TextureUnitStateIterator getTextureUnitStateIterator(void);
	600
	601	typedef ConstVectorIterator<TextureUnitStates> ConstTextureUnitStateIterator;
	602	/** Get an iterator over the TextureUnitStates contained in this Pass. */
	603	ConstTextureUnitStateIterator getTextureUnitStateIterator(void) const;
	604
	605	/** Removes the indexed texture unit state from this pass.
	606	@remarks
	607	Note that removing a texture which is not the topmost will have a larger performance impact.
	608	*/
	609	void removeTextureUnitState(unsigned short index);
	610
	611	/** Removes all texture unit settings.
	612	*/
	613	void removeAllTextureUnitStates(void);
	614
	615	/** Returns the number of texture unit settings.
	616	*/
	617	unsigned short getNumTextureUnitStates(void) const
	618	{
	619	return static_cast<unsigned short>(mTextureUnitStates.size());
	620	}
	621
	622	/** Sets the kind of blending this pass has with the existing contents of the scene.
	623	@remarks
	624	Whereas the texture blending operations seen in the TextureUnitState class are concerned with
	625	blending between texture layers, this blending is about combining the output of the Pass
	626	as a whole with the existing contents of the rendering target. This blending therefore allows
	627	object transparency and other special effects. If all passes in a technique have a scene
	628	blend, then the whole technique is considered to be transparent.
	629	@par
	630	This method allows you to select one of a number of predefined blending types. If you require more
	631	control than this, use the alternative version of this method which allows you to specify source and
	632	destination blend factors.
	633	@note
	634	This method is applicable for both the fixed-function and programmable pipelines.
	635	@param
	636	sbt One of the predefined SceneBlendType blending types
	637	*/
	638	void setSceneBlending( const SceneBlendType sbt );
	639
	640	/** Sets the kind of blending this pass has with the existing contents of the scene, separately for color and alpha channels
	641	@remarks
	642	Whereas the texture blending operations seen in the TextureUnitState class are concerned with
	643	blending between texture layers, this blending is about combining the output of the Pass
	644	as a whole with the existing contents of the rendering target. This blending therefore allows
	645	object transparency and other special effects. If all passes in a technique have a scene
	646	blend, then the whole technique is considered to be transparent.
	647	@par
	648	This method allows you to select one of a number of predefined blending types. If you require more
	649	control than this, use the alternative version of this method which allows you to specify source and
	650	destination blend factors.
	651	@note
	652	This method is applicable for both the fixed-function and programmable pipelines.
	653	@param
	654	sbt One of the predefined SceneBlendType blending types for the color channel
	655	@param
	656	sbta One of the predefined SceneBlendType blending types for the alpha channel
	657	*/
	658	void setSeparateSceneBlending( const SceneBlendType sbt, const SceneBlendType sbta );
	659
	660	/** Allows very fine control of blending this Pass with the existing contents of the scene.
	661	@remarks
	662	Whereas the texture blending operations seen in the TextureUnitState class are concerned with
	663	blending between texture layers, this blending is about combining the output of the material
	664	as a whole with the existing contents of the rendering target. This blending therefore allows
	665	object transparency and other special effects.
	666	@par
	667	This version of the method allows complete control over the blending operation, by specifying the
	668	source and destination blending factors. The result of the blending operation is:
	669	<span align="center">
	670	final = (texture * sourceFactor) + (pixel * destFactor)
	671	</span>
	672	@par
	673	Each of the factors is specified as one of a number of options, as specified in the SceneBlendFactor
	674	enumerated type.
	675	@param
	676	sourceFactor The source factor in the above calculation, i.e. multiplied by the texture colour components.
	677	@param
	678	destFactor The destination factor in the above calculation, i.e. multiplied by the pixel colour components.
	679	@note
	680	This method is applicable for both the fixed-function and programmable pipelines.
	681	*/
	682	void setSceneBlending( const SceneBlendFactor sourceFactor, const SceneBlendFactor destFactor);
	683
	684	/** Allows very fine control of blending this Pass with the existing contents of the scene.
	685	@remarks
	686	Whereas the texture blending operations seen in the TextureUnitState class are concerned with
	687	blending between texture layers, this blending is about combining the output of the material
	688	as a whole with the existing contents of the rendering target. This blending therefore allows
	689	object transparency and other special effects.
	690	@par
	691	This version of the method allows complete control over the blending operation, by specifying the
	692	source and destination blending factors. The result of the blending operation is:
	693	<span align="center">
	694	final = (texture * sourceFactor) + (pixel * destFactor)
	695	</span>
	696	@par
	697	Each of the factors is specified as one of a number of options, as specified in the SceneBlendFactor
	698	enumerated type.
	699	@param
	700	sourceFactor The source factor in the above calculation, i.e. multiplied by the texture colour components.
	701	@param
	702	destFactor The destination factor in the above calculation, i.e. multiplied by the pixel colour components.
	703	@param
	704	sourceFactorAlpha The alpha source factor in the above calculation, i.e. multiplied by the texture alpha component.
	705	@param
	706	destFactorAlpha The alpha destination factor in the above calculation, i.e. multiplied by the pixel alpha component.
	707	@note
	708	This method is applicable for both the fixed-function and programmable pipelines.
	709	*/
	710	void setSeparateSceneBlending( const SceneBlendFactor sourceFactor, const SceneBlendFactor destFactor, const SceneBlendFactor sourceFactorAlpha, const SceneBlendFactor destFactorAlpha );
	711
	712	/** Return true if this pass uses separate scene blending */
	713	bool hasSeparateSceneBlending() const;
	714
	715	/** Retrieves the source blending factor for the material (as set using Materiall::setSceneBlending).
	716	*/
	717	SceneBlendFactor getSourceBlendFactor() const;
	718
	719	/** Retrieves the destination blending factor for the material (as set using Materiall::setSceneBlending).
	720	*/
	721	SceneBlendFactor getDestBlendFactor() const;
	722
	723	/** Retrieves the alpha source blending factor for the material (as set using Materiall::setSeparateSceneBlending).
	724	*/
	725	SceneBlendFactor getSourceBlendFactorAlpha() const;
	726
	727	/** Retrieves the alpha destination blending factor for the material (as set using Materiall::setSeparateSceneBlending).
	728	*/
	729	SceneBlendFactor getDestBlendFactorAlpha() const;
	730
	731	/** Sets the specific operation used to blend source and destination pixels together.
	732	@remarks
	733	By default this operation is +, which creates this equation
	734	<span align="center">
	735	final = (texture * sourceFactor) + (pixel * destFactor)
	736	</span>
	737	By setting this to something other than SBO_ADD you can change the operation to achieve
	738	a different effect.
	739	@param op The blending operation mode to use for this pass
	740	*/
	741	void setSceneBlendingOperation(SceneBlendOperation op);
	742
	743	/** Sets the specific operation used to blend source and destination pixels together.
	744	@remarks
	745	By default this operation is +, which creates this equation
	746	<span align="center">
	747	final = (texture * sourceFactor) + (pixel * destFactor)
	748	</span>
	749	By setting this to something other than SBO_ADD you can change the operation to achieve
	750	a different effect.
	751	This function allows more control over blending since it allows you to select different blending
	752	modes for the color and alpha channels
	753	@param op The blending operation mode to use for color channels in this pass
	754	@param alphaOp The blending operation mode to use for alpha channels in this pass
	755	*/
	756	void setSeparateSceneBlendingOperation(SceneBlendOperation op, SceneBlendOperation alphaOp);
	757
	758	/** Returns true if this pass uses separate scene blending operations. */
	759	bool hasSeparateSceneBlendingOperations() const;
	760
	761	/** Returns the current blending operation */
	762	SceneBlendOperation getSceneBlendingOperation() const;
	763
	764	/** Returns the current alpha blending operation */
	765	SceneBlendOperation getSceneBlendingOperationAlpha() const;
	766
	767	/** Returns true if this pass has some element of transparency. */
	768	bool isTransparent(void) const;
	769
	770	/** Sets whether or not this pass renders with depth-buffer checking on or not.
	771	@remarks
	772	If depth-buffer checking is on, whenever a pixel is about to be written to the frame buffer
	773	the depth buffer is checked to see if the pixel is in front of all other pixels written at that
	774	point. If not, the pixel is not written.
	775	@par
	776	If depth checking is off, pixels are written no matter what has been rendered before.
	777	Also see setDepthFunction for more advanced depth check configuration.
	778	@see
	779	setDepthFunction
	780	*/
	781	void setDepthCheckEnabled(bool enabled);
	782
	783	/** Returns whether or not this pass renders with depth-buffer checking on or not.
	784	@see
	785	setDepthCheckEnabled
	786	*/
	787	bool getDepthCheckEnabled(void) const;
	788
	789	/** Sets whether or not this pass renders with depth-buffer writing on or not.
	790	@remarks
	791	If depth-buffer writing is on, whenever a pixel is written to the frame buffer
	792	the depth buffer is updated with the depth value of that new pixel, thus affecting future
	793	rendering operations if future pixels are behind this one.
	794	@par
	795	If depth writing is off, pixels are written without updating the depth buffer Depth writing should
	796	normally be on but can be turned off when rendering static backgrounds or when rendering a collection
	797	of transparent objects at the end of a scene so that they overlap each other correctly.
	798	*/
	799	void setDepthWriteEnabled(bool enabled);
	800
	801	/** Returns whether or not this pass renders with depth-buffer writing on or not.
	802	@see
	803	setDepthWriteEnabled
	804	*/
	805	bool getDepthWriteEnabled(void) const;
	806
	807	/** Sets the function used to compare depth values when depth checking is on.
	808	@remarks
	809	If depth checking is enabled (see setDepthCheckEnabled) a comparison occurs between the depth
	810	value of the pixel to be written and the current contents of the buffer. This comparison is
	811	normally CMPF_LESS_EQUAL, i.e. the pixel is written if it is closer (or at the same distance)
	812	than the current contents. If you wish you can change this comparison using this method.
	813	*/
	814	void setDepthFunction( CompareFunction func );
	815	/** Returns the function used to compare depth values when depth checking is on.
	816	@see
	817	setDepthFunction
	818	*/
	819	CompareFunction getDepthFunction(void) const;
	820
	821	/** Sets whether or not colour buffer writing is enabled for this Pass.
	822	@remarks
	823	For some effects, you might wish to turn off the colour write operation
	824	when rendering geometry; this means that only the depth buffer will be
	825	updated (provided you have depth buffer writing enabled, which you
	826	probably will do, although you may wish to only update the stencil
	827	buffer for example - stencil buffer state is managed at the RenderSystem
	828	level only, not the Material since you are likely to want to manage it
	829	at a higher level).
	830	*/
	831	void setColourWriteEnabled(bool enabled);
	832	/** Determines if colour buffer writing is enabled for this pass. */
	833	bool getColourWriteEnabled(void) const;
	834
	835	/** Sets the culling mode for this pass based on the 'vertex winding'.
	836	@remarks
	837	A typical way for the rendering engine to cull triangles is based on the 'vertex winding' of
	838	triangles. Vertex winding refers to the direction in which the vertices are passed or indexed
	839	to in the rendering operation as viewed from the camera, and will wither be clockwise or
	840	anticlockwise (that's 'counterclockwise' for you Americans out there ;) The default is
	841	CULL_CLOCKWISE i.e. that only triangles whose vertices are passed/indexed in anticlockwise order
	842	are rendered - this is a common approach and is used in 3D studio models for example. You can
	843	alter this culling mode if you wish but it is not advised unless you know what you are doing.
	844	@par
	845	You may wish to use the CULL_NONE option for mesh data that you cull yourself where the vertex
	846	winding is uncertain.
	847	*/
	848	void setCullingMode( CullingMode mode );
	849
	850	/** Returns the culling mode for geometry rendered with this pass. See setCullingMode for more information.
	851	*/
	852	CullingMode getCullingMode(void) const;
	853
	854	/** Sets the manual culling mode, performed by CPU rather than hardware.
	855	@remarks
	856	In some situations you want to use manual culling of triangles rather than sending the
	857	triangles to the hardware and letting it cull them. This setting only takes effect on SceneManager's
	858	that use it (since it is best used on large groups of planar world geometry rather than on movable
	859	geometry since this would be expensive), but if used can cull geometry before it is sent to the
	860	hardware.
	861	@note
	862	The default for this setting is MANUAL_CULL_BACK.
	863	@param
	864	mode The mode to use - see enum ManualCullingMode for details
	865
	866	*/
	867	void setManualCullingMode( ManualCullingMode mode );
	868
	869	/** Retrieves the manual culling mode for this pass
	870	@see
	871	setManualCullingMode
	872	*/
	873	ManualCullingMode getManualCullingMode(void) const;
	874
	875	/** Sets whether or not dynamic lighting is enabled.
	876	@param
	877	enabled
	878	If true, dynamic lighting is performed on geometry with normals supplied, geometry without
	879	normals will not be displayed.
	880	@par
	881	If false, no lighting is applied and all geometry will be full brightness.
	882	*/
	883	void setLightingEnabled(bool enabled);
	884
	885	/** Returns whether or not dynamic lighting is enabled.
	886	*/
	887	bool getLightingEnabled(void) const;
	888
	889	/** Sets the maximum number of lights to be used by this pass.
	890	@remarks
	891	During rendering, if lighting is enabled (or if the pass uses an automatic
	892	program parameter based on a light) the engine will request the nearest lights
	893	to the object being rendered in order to work out which ones to use. This
	894	parameter sets the limit on the number of lights which should apply to objects
	895	rendered with this pass.
	896	*/
	897	void setMaxSimultaneousLights(unsigned short maxLights);
	898	/** Gets the maximum number of lights to be used by this pass. */
	899	unsigned short getMaxSimultaneousLights(void) const;
	900
	901	/** Sets the light index that this pass will start at in the light list.
	902	@remarks
	903	Normally the lights passed to a pass will start from the beginning
	904	of the light list for this object. This option allows you to make this
	905	pass start from a higher light index, for example if one of your earlier
	906	passes could deal with lights 0-3, and this pass dealt with lights 4+.
	907	This option also has an interaction with pass iteration, in that
	908	if you choose to iterate this pass per light too, the iteration will
	909	only begin from light 4.
	910	*/
	911	void setStartLight(unsigned short startLight);
	912	/** Gets the light index that this pass will start at in the light list. */
	913	unsigned short getStartLight(void) const;
	914
	915	/** Sets the light mask which can be matched to specific light flags to be handled by this pass */
	916	void setLightMask(uint32 mask);
	917	/** Gets the light mask controlling which lights are used for this pass */
	918	uint32 getLightMask() const;
	919
	920	/** Sets the type of light shading required
	921	@note
	922	The default shading method is Gouraud shading.
	923	*/
	924	void setShadingMode( ShadeOptions mode );
	925
	926	/** Returns the type of light shading to be used.
	927	*/
	928	ShadeOptions getShadingMode(void) const;
	929
	930	/** Sets the type of polygon rendering required
	931	@note
	932	The default shading method is Solid
	933	*/
	934	void setPolygonMode( PolygonMode mode );
	935
	936	/** Returns the type of light shading to be used.
	937	*/
	938	PolygonMode getPolygonMode(void) const;
	939
	940	/** Sets whether this pass's chosen detail level can be
	941	overridden (downgraded) by the camera setting.
	942	@param override true means that a lower camera detail will override this
	943	pass's detail level, false means it won't (default true).
	944	*/
	945	virtual void setPolygonModeOverrideable(bool override)
	946	{
	947	mPolygonModeOverrideable = override;
	948	}
	949
	950	/** Gets whether this renderable's chosen detail level can be
	951	overridden (downgraded) by the camera setting.
	952	*/
	953	virtual bool getPolygonModeOverrideable(void) const
	954	{
	955	return mPolygonModeOverrideable;
	956	}
	957	/** Sets the fogging mode applied to this pass.
	958	@remarks
	959	Fogging is an effect that is applied as polys are rendered. Sometimes, you want
	960	fog to be applied to an entire scene. Other times, you want it to be applied to a few
	961	polygons only. This pass-level specification of fog parameters lets you easily manage
	962	both.
	963	@par
	964	The SceneManager class also has a setFog method which applies scene-level fog. This method
	965	lets you change the fog behaviour for this pass compared to the standard scene-level fog.
	966	@param
	967	overrideScene If true, you authorise this pass to override the scene's fog params with it's own settings.
	968	If you specify false, so other parameters are necessary, and this is the default behaviour for passes.
	969	@param
	970	mode Only applicable if overrideScene is true. You can disable fog which is turned on for the
	971	rest of the scene by specifying FOG_NONE. Otherwise, set a pass-specific fog mode as
	972	defined in the enum FogMode.
	973	@param
	974	colour The colour of the fog. Either set this to the same as your viewport background colour,
	975	or to blend in with a skydome or skybox.
	976	@param
	977	expDensity The density of the fog in FOG_EXP or FOG_EXP2 mode, as a value between 0 and 1.
	978	The default is 0.001.
	979	@param
	980	linearStart Distance in world units at which linear fog starts to encroach.
	981	Only applicable if mode is FOG_LINEAR.
	982	@param
	983	linearEnd Distance in world units at which linear fog becomes completely opaque.
	984	Only applicable if mode is FOG_LINEAR.
	985	*/
	986	void setFog(
	987	bool overrideScene,
	988	FogMode mode = FOG_NONE,
	989	const ColourValue& colour = ColourValue::White,
	990	Real expDensity = 0.001, Real linearStart = 0.0, Real linearEnd = 1.0 );
	991
	992	/** Returns true if this pass is to override the scene fog settings.
	993	*/
	994	bool getFogOverride(void) const;
	995
	996	/** Returns the fog mode for this pass.
	997	@note
	998	Only valid if getFogOverride is true.
	999	*/
	1000	FogMode getFogMode(void) const;
	1001
	1002	/** Returns the fog colour for the scene.
	1003	*/
	1004	const ColourValue& getFogColour(void) const;
	1005
	1006	/** Returns the fog start distance for this pass.
	1007	@note
	1008	Only valid if getFogOverride is true.
	1009	*/
	1010	Real getFogStart(void) const;
	1011
	1012	/** Returns the fog end distance for this pass.
	1013	@note
	1014	Only valid if getFogOverride is true.
	1015	*/
	1016	Real getFogEnd(void) const;
	1017
	1018	/** Returns the fog density for this pass.
	1019	@note
	1020	Only valid if getFogOverride is true.
	1021	*/
	1022	Real getFogDensity(void) const;
	1023
	1024	/** Sets the depth bias to be used for this material.
	1025	@remarks
	1026	When polygons are coplanar, you can get problems with 'depth fighting' where
	1027	the pixels from the two polys compete for the same screen pixel. This is particularly
	1028	a problem for decals (polys attached to another surface to represent details such as
	1029	bulletholes etc.).
	1030	@par
	1031	A way to combat this problem is to use a depth bias to adjust the depth buffer value
	1032	used for the decal such that it is slightly higher than the true value, ensuring that
	1033	the decal appears on top. There are two aspects to the biasing, a constant
	1034	bias value and a slope-relative biasing value, which varies according to the
	1035	maximum depth slope relative to the camera, ie:
	1036	<pre>finalBias = maxSlope * slopeScaleBias + constantBias</pre>
	1037	Note that slope scale bias, whilst more accurate, may be ignored by old hardware.
	1038	@param constantBias The constant bias value, expressed as a factor of the
	1039	minimum observable depth
	1040	@param slopeScaleBias The slope-relative bias value, expressed as a factor
	1041	of the depth slope
	1042	*/
	1043	void setDepthBias(float constantBias, float slopeScaleBias = 0.0f);
	1044
	1045	/** Retrieves the const depth bias value as set by setDepthBias. */
	1046	float getDepthBiasConstant(void) const;
	1047	/** Retrieves the slope-scale depth bias value as set by setDepthBias. */
	1048	float getDepthBiasSlopeScale(void) const;
	1049	/** Sets a factor which derives an additional depth bias from the number
	1050	of times a pass is iterated.
	1051	@remarks
	1052	The Final depth bias will be the constant depth bias as set through
	1053	setDepthBias, plus this value times the iteration number.
	1054	*/
	1055	void setIterationDepthBias(float biasPerIteration);
	1056	/** Gets a factor which derives an additional depth bias from the number
	1057	of times a pass is iterated.
	1058	*/
	1059	float getIterationDepthBias() const;
	1060
	1061	/** Sets the way the pass will have use alpha to totally reject pixels from the pipeline.
	1062	@remarks
	1063	The default is CMPF_ALWAYS_PASS i.e. alpha is not used to reject pixels.
	1064	@param func The comparison which must pass for the pixel to be written.
	1065	@param value 1 byte value against which alpha values will be tested(0-255)
	1066	@param alphaToCoverageEnabled Whether to enable alpha to coverage support
	1067	@note
	1068	This option applies in both the fixed function and the programmable pipeline.
	1069	*/
	1070	void setAlphaRejectSettings(CompareFunction func, unsigned char value, bool alphaToCoverageEnabled = false);
	1071
	1072	/** Sets the alpha reject function. See setAlphaRejectSettings for more information.
	1073	*/
	1074	void setAlphaRejectFunction(CompareFunction func);
	1075
	1076	/** Gets the alpha reject value. See setAlphaRejectSettings for more information.
	1077	*/
	1078	void setAlphaRejectValue(unsigned char val);
	1079
	1080	/** Gets the alpha reject function. See setAlphaRejectSettings for more information.
	1081	*/
	1082	CompareFunction getAlphaRejectFunction(void) const { return mAlphaRejectFunc; }
	1083
	1084	/** Gets the alpha reject value. See setAlphaRejectSettings for more information.
	1085	*/
	1086	unsigned char getAlphaRejectValue(void) const { return mAlphaRejectVal; }
	1087
	1088	/** Sets whether to use alpha to coverage (A2C) when blending alpha rejected values.
	1089	@remarks
	1090	Alpha to coverage performs multisampling on the edges of alpha-rejected
	1091	textures to produce a smoother result. It is only supported when multisampling
	1092	is already enabled on the render target, and when the hardware supports
	1093	alpha to coverage (see RenderSystemCapabilities).
	1094	*/
	1095	void setAlphaToCoverageEnabled(bool enabled);
	1096
	1097	/** Gets whether to use alpha to coverage (A2C) when blending alpha rejected values.
	1098	*/
	1099	bool isAlphaToCoverageEnabled() const { return mAlphaToCoverageEnabled; }
	1100
	1101	/** Sets whether or not transparent sorting is enabled.
	1102	@param enabled
	1103	If false depth sorting of this material will be disabled.
	1104	@remarks
	1105	By default all transparent materials are sorted such that renderables furthest
	1106	away from the camera are rendered first. This is usually the desired behaviour
	1107	but in certain cases this depth sorting may be unnecessary and undesirable. If
	1108	for example it is necessary to ensure the rendering order does not change from
	1109	one frame to the next.
	1110	@note
	1111	This will have no effect on non-transparent materials.
	1112	*/
	1113	void setTransparentSortingEnabled(bool enabled);
	1114
	1115	/** Returns whether or not transparent sorting is enabled.
	1116	*/
	1117	bool getTransparentSortingEnabled(void) const;
	1118
	1119	/** Sets whether or not transparent sorting is forced.
	1120	@param enabled
	1121	If true depth sorting of this material will be depend only on the value of
	1122	getTransparentSortingEnabled().
	1123	@remarks
	1124	By default even if transparent sorting is enabled, depth sorting will only be
	1125	performed when the material is transparent and depth write/check are disabled.
	1126	This function disables these extra conditions.
	1127	*/
	1128	void setTransparentSortingForced(bool enabled);
	1129
	1130	/** Returns whether or not transparent sorting is forced.
	1131	*/
	1132	bool getTransparentSortingForced(void) const;
	1133
	1134	/** Sets whether or not this pass should iterate per light or number of
	1135	lights which can affect the object being rendered.
	1136	@remarks
	1137	The default behaviour for a pass (when this option is 'false'), is
	1138	for a pass to be rendered only once (or the number of times set in
	1139	setPassIterationCount), with all the lights which could
	1140	affect this object set at the same time (up to the maximum lights
	1141	allowed in the render system, which is typically 8).
	1142	@par
	1143	Setting this option to 'true' changes this behaviour, such that
	1144	instead of trying to issue render this pass once per object, it
	1145	is run <b>per light</b>, or for a group of 'n' lights each time
	1146	which can affect this object, the number of
	1147	times set in setPassIterationCount (default is once). In
	1148	this case, only light index 0 is ever used, and is a different light
	1149	every time the pass is issued, up to the total number of lights
	1150	which is affecting this object. This has 2 advantages:
	1151	<ul><li>There is no limit on the number of lights which can be
	1152	supported</li>
	1153	<li>It's easier to write vertex / fragment programs for this because
	1154	a single program can be used for any number of lights</li>
	1155	</ul>
	1156	However, this technique is more expensive, and typically you
	1157	will want an additional ambient pass, because if no lights are
	1158	affecting the object it will not be rendered at all, which will look
	1159	odd even if ambient light is zero (imagine if there are lit objects
	1160	behind it - the objects silhouette would not show up). Therefore,
	1161	use this option with care, and you would be well advised to provide
	1162	a less expensive fallback technique for use in the distance.
	1163	@note
	1164	The number of times this pass runs is still limited by the maximum
	1165	number of lights allowed as set in setMaxSimultaneousLights, so
	1166	you will never get more passes than this. Also, the iteration is
	1167	started from the 'start light' as set in Pass::setStartLight, and
	1168	the number of passes is the number of lights to iterate over divided
	1169	by the number of lights per iteration (default 1, set by
	1170	setLightCountPerIteration).
	1171	@param enabled Whether this feature is enabled
	1172	@param onlyForOneLightType If true, the pass will only be run for a single type
	1173	of light, other light types will be ignored.
	1174	@param lightType The single light type which will be considered for this pass
	1175	*/
	1176	void setIteratePerLight(bool enabled,
	1177	bool onlyForOneLightType = true, Light::LightTypes lightType = Light::LT_POINT);
	1178
	1179	/** Does this pass run once for every light in range? */
	1180	bool getIteratePerLight(void) const { return mIteratePerLight; }
	1181	/** Does this pass run only for a single light type (if getIteratePerLight is true). */
	1182	bool getRunOnlyForOneLightType(void) const { return mRunOnlyForOneLightType; }
	1183	/** Gets the single light type this pass runs for if getIteratePerLight and
	1184	getRunOnlyForOneLightType are both true. */
	1185	Light::LightTypes getOnlyLightType() const { return mOnlyLightType; }
	1186
	1187	/** If light iteration is enabled, determine the number of lights per
	1188	iteration.
	1189	@remarks
	1190	The default for this setting is 1, so if you enable light iteration
	1191	(Pass::setIteratePerLight), the pass is rendered once per light. If
	1192	you set this value higher, the passes will occur once per 'n' lights.
	1193	The start of the iteration is set by Pass::setStartLight and the end
	1194	by Pass::setMaxSimultaneousLights.
	1195	*/
	1196	void setLightCountPerIteration(unsigned short c);
	1197	/** If light iteration is enabled, determine the number of lights per
	1198	iteration.
	1199	*/
	1200	unsigned short getLightCountPerIteration(void) const;
	1201
	1202	/// Gets the parent Technique
	1203	Technique* getParent(void) const { return mParent; }
	1204
	1205	/// Gets the resource group of the ultimate parent Material
	1206	const String& getResourceGroup(void) const;
	1207
	1208	/** Sets the details of the vertex program to use.
	1209	@remarks
	1210	Only applicable to programmable passes, this sets the details of
	1211	the vertex program to use in this pass. The program will not be
	1212	loaded until the parent Material is loaded.
	1213	@param name The name of the program - this must have been
	1214	created using GpuProgramManager by the time that this Pass
	1215	is loaded. If this parameter is blank, any vertex program in this pass is disabled.
	1216	@param resetParams
	1217	If true, this will create a fresh set of parameters from the
	1218	new program being linked, so if you had previously set parameters
	1219	you will have to set them again. If you set this to false, you must
	1220	be absolutely sure that the parameters match perfectly, and in the
	1221	case of named parameters refers to the indexes underlying them,
	1222	not just the names.
	1223	*/
	1224	void setVertexProgram(const String& name, bool resetParams = true);
	1225	/** Sets the vertex program parameters.
	1226	@remarks
	1227	Only applicable to programmable passes, and this particular call is
	1228	designed for low-level programs; use the named parameter methods
	1229	for setting high-level program parameters.
	1230	*/
	1231	void setVertexProgramParameters(GpuProgramParametersSharedPtr params);
	1232	/** Gets the name of the vertex program used by this pass. */
	1233	const String& getVertexProgramName(void) const;
	1234	/** Gets the vertex program parameters used by this pass. */
	1235	GpuProgramParametersSharedPtr getVertexProgramParameters(void) const;
	1236	/** Gets the vertex program used by this pass, only available after _load(). */
	1237	const GpuProgramPtr& getVertexProgram(void) const;
	1238
	1239
	1240	/** Sets the details of the vertex program to use when rendering as a
	1241	shadow caster.
	1242	@remarks
	1243	Texture-based shadows require that the caster is rendered to a texture
	1244	in a solid colour (the shadow colour in the case of modulative texture
	1245	shadows). Whilst Ogre can arrange this for the fixed function
	1246	pipeline, passes which use vertex programs might need the vertex
	1247	programs still to run in order to preserve any deformation etc
	1248	that it does. However, lighting calculations must be a lot simpler,
	1249	with only the ambient colour being used (which the engine will ensure
	1250	is bound to the shadow colour).
	1251	@par
	1252	Therefore, it is up to implementors of vertex programs to provide an
	1253	alternative vertex program which can be used to render the object
	1254	to a shadow texture. Do all the same vertex transforms, but set the
	1255	colour of the vertex to the ambient colour, as bound using the
	1256	standard auto parameter binding mechanism.
	1257	@note
	1258	Some vertex programs will work without doing this, because Ogre ensures
	1259	that all lights except for ambient are set black. However, the chances
	1260	are that your vertex program is doing a lot of unnecessary work in this
	1261	case, since the other lights are having no effect, and it is good practice
	1262	to supply an alternative.
	1263	@note
	1264	This is only applicable to programmable passes.
	1265	@par
	1266	The default behaviour is for Ogre to switch to fixed-function
	1267	rendering if an explicit vertex program alternative is not set.
	1268	*/
	1269	void setShadowCasterVertexProgram(const String& name);
	1270	/** Sets the vertex program parameters for rendering as a shadow caster.
	1271	@remarks
	1272	Only applicable to programmable passes, and this particular call is
	1273	designed for low-level programs; use the named parameter methods
	1274	for setting high-level program parameters.
	1275	*/
	1276	void setShadowCasterVertexProgramParameters(GpuProgramParametersSharedPtr params);
	1277	/** Gets the name of the vertex program used by this pass when rendering shadow casters. */
	1278	const String& getShadowCasterVertexProgramName(void) const;
	1279	/** Gets the vertex program parameters used by this pass when rendering shadow casters. */
	1280	GpuProgramParametersSharedPtr getShadowCasterVertexProgramParameters(void) const;
	1281	/** Gets the vertex program used by this pass when rendering shadow casters,
	1282	only available after _load(). */
	1283	const GpuProgramPtr& getShadowCasterVertexProgram(void) const;
	1284
	1285	/** Sets the details of the fragment program to use when rendering as a
	1286	shadow caster.
	1287	@remarks
	1288	Texture-based shadows require that the caster is rendered to a texture
	1289	in a solid colour (the shadow colour in the case of modulative texture
	1290	shadows). Whilst Ogre can arrange this for the fixed function
	1291	pipeline, passes which use vertex programs might need the vertex
	1292	programs still to run in order to preserve any deformation etc
	1293	that it does. However, lighting calculations must be a lot simpler,
	1294	with only the ambient colour being used (which the engine will ensure
	1295	is bound to the shadow colour).
	1296	@par
	1297	Therefore, it is up to implementors of vertex programs to provide an
	1298	alternative vertex program which can be used to render the object
	1299	to a shadow texture. Do all the same vertex transforms, but set the
	1300	colour of the vertex to the ambient colour, as bound using the
	1301	standard auto parameter binding mechanism.
	1302	@note
	1303	Some vertex programs will work without doing this, because Ogre ensures
	1304	that all lights except for ambient are set black. However, the chances
	1305	are that your vertex program is doing a lot of unnecessary work in this
	1306	case, since the other lights are having no effect, and it is good practice
	1307	to supply an alternative.
	1308	@note
	1309	This is only applicable to programmable passes.
	1310	@par
	1311	The default behaviour is for Ogre to switch to fixed-function
	1312	rendering if an explicit fragment program alternative is not set.
	1313	*/
	1314	void setShadowCasterFragmentProgram(const String& name);
	1315	/** Sets the fragment program parameters for rendering as a shadow caster.
	1316	@remarks
	1317	Only applicable to programmable passes, and this particular call is
	1318	designed for low-level programs; use the named parameter methods
	1319	for setting high-level program parameters.
	1320	*/
	1321	void setShadowCasterFragmentProgramParameters(GpuProgramParametersSharedPtr params);
	1322	/** Gets the name of the fragment program used by this pass when rendering shadow casters. */
	1323	const String& getShadowCasterFragmentProgramName(void) const;
	1324	/** Gets the fragment program parameters used by this pass when rendering shadow casters. */
	1325	GpuProgramParametersSharedPtr getShadowCasterFragmentProgramParameters(void) const;
	1326	/** Gets the fragment program used by this pass when rendering shadow casters,
	1327	only available after _load(). */
	1328	const GpuProgramPtr& getShadowCasterFragmentProgram(void) const;
	1329
	1330	/** Sets the details of the vertex program to use when rendering as a
	1331	shadow receiver.
	1332	@remarks
	1333	Texture-based shadows require that the shadow receiver is rendered using
	1334	a projective texture. Whilst Ogre can arrange this for the fixed function
	1335	pipeline, passes which use vertex programs might need the vertex
	1336	programs still to run in order to preserve any deformation etc
	1337	that it does. So in this case, we need a vertex program which does the
	1338	appropriate vertex transformation, but generates projective texture
	1339	coordinates.
	1340	@par
	1341	Therefore, it is up to implementors of vertex programs to provide an
	1342	alternative vertex program which can be used to render the object
	1343	as a shadow receiver. Do all the same vertex transforms, but generate
	1344	<strong>2 sets</strong> of texture coordinates using the auto parameter
	1345	ACT_TEXTURE_VIEWPROJ_MATRIX, which Ogre will bind to the parameter name /
	1346	index you supply as the second parameter to this method. 2 texture
	1347	sets are needed because Ogre needs to use 2 texture units for some
	1348	shadow effects.
	1349	@note
	1350	This is only applicable to programmable passes.
	1351	@par
	1352	The default behaviour is for Ogre to switch to fixed-function
	1353	rendering if an explict vertex program alternative is not set.
	1354	*/
	1355	void setShadowReceiverVertexProgram(const String& name);
	1356	/** Sets the vertex program parameters for rendering as a shadow receiver.
	1357	@remarks
	1358	Only applicable to programmable passes, and this particular call is
	1359	designed for low-level programs; use the named parameter methods
	1360	for setting high-level program parameters.
	1361	*/
	1362	void setShadowReceiverVertexProgramParameters(GpuProgramParametersSharedPtr params);
	1363
	1364	/** This method allows you to specify a fragment program for use when
	1365	rendering a texture shadow receiver.
	1366	@remarks
	1367	Texture shadows are applied by rendering the receiver. Modulative texture
	1368	shadows are performed as a post-render darkening pass, and as such
	1369	fragment programs are generally not required per-object. Additive
	1370	texture shadows, however, are applied by accumulating light masked
	1371	out using a texture shadow (black & white by default, unless you
	1372	customise this using SceneManager::setCustomShadowCasterMaterial).
	1373	OGRE can do this for you for most materials, but if you use a custom
	1374	lighting program (e.g. per pixel lighting) then you'll need to provide
	1375	a custom version for receiving shadows. You don't need to provide
	1376	this for shadow casters if you don't use self-shadowing since they
	1377	will never be shadow receivers too.
	1378	@par
	1379	The shadow texture is always bound to texture unit 0 when rendering
	1380	texture shadow passes. Therefore your custom shadow receiver program
	1381	may well just need to shift it's texture unit usage up by one unit,
	1382	and take the shadow texture into account in its calculations.
	1383	*/
	1384	void setShadowReceiverFragmentProgram(const String& name);
	1385	/** Sets the fragment program parameters for rendering as a shadow receiver.
	1386	@remarks
	1387	Only applicable to programmable passes, and this particular call is
	1388	designed for low-level programs; use the named parameter methods
	1389	for setting high-level program parameters.
	1390	*/
	1391	void setShadowReceiverFragmentProgramParameters(GpuProgramParametersSharedPtr params);
	1392
	1393	/** Gets the name of the vertex program used by this pass when rendering shadow receivers. */
	1394	const String& getShadowReceiverVertexProgramName(void) const;
	1395	/** Gets the vertex program parameters used by this pass when rendering shadow receivers. */
	1396	GpuProgramParametersSharedPtr getShadowReceiverVertexProgramParameters(void) const;
	1397	/** Gets the vertex program used by this pass when rendering shadow receivers,
	1398	only available after _load(). */
	1399	const GpuProgramPtr& getShadowReceiverVertexProgram(void) const;
	1400
	1401	/** Gets the name of the fragment program used by this pass when rendering shadow receivers. */
	1402	const String& getShadowReceiverFragmentProgramName(void) const;
	1403	/** Gets the fragment program parameters used by this pass when rendering shadow receivers. */
	1404	GpuProgramParametersSharedPtr getShadowReceiverFragmentProgramParameters(void) const;
	1405	/** Gets the fragment program used by this pass when rendering shadow receivers,
	1406	only available after _load(). */
	1407	const GpuProgramPtr& getShadowReceiverFragmentProgram(void) const;
	1408
	1409	/** Sets the details of the fragment program to use.
	1410	@remarks
	1411	Only applicable to programmable passes, this sets the details of
	1412	the fragment program to use in this pass. The program will not be
	1413	loaded until the parent Material is loaded.
	1414	@param name The name of the program - this must have been
	1415	created using GpuProgramManager by the time that this Pass
	1416	is loaded. If this parameter is blank, any fragment program in this pass is disabled.
	1417	@param resetParams
	1418	If true, this will create a fresh set of parameters from the
	1419	new program being linked, so if you had previously set parameters
	1420	you will have to set them again. If you set this to false, you must
	1421	be absolutely sure that the parameters match perfectly, and in the
	1422	case of named parameters refers to the indexes underlying them,
	1423	not just the names.
	1424	*/
	1425	void setFragmentProgram(const String& name, bool resetParams = true);
	1426	/** Sets the fragment program parameters.
	1427	@remarks
	1428	Only applicable to programmable passes.
	1429	*/
	1430	void setFragmentProgramParameters(GpuProgramParametersSharedPtr params);
	1431	/** Gets the name of the fragment program used by this pass. */
	1432	const String& getFragmentProgramName(void) const;
	1433	/** Gets the fragment program parameters used by this pass. */
	1434	GpuProgramParametersSharedPtr getFragmentProgramParameters(void) const;
	1435	/** Gets the fragment program used by this pass, only available after _load(). */
	1436	const GpuProgramPtr& getFragmentProgram(void) const;
	1437
	1438	/** Sets the details of the geometry program to use.
	1439	@remarks
	1440	Only applicable to programmable passes, this sets the details of
	1441	the geometry program to use in this pass. The program will not be
	1442	loaded until the parent Material is loaded.
	1443	@param name The name of the program - this must have been
	1444	created using GpuProgramManager by the time that this Pass
	1445	is loaded. If this parameter is blank, any geometry program in this pass is disabled.
	1446	@param resetParams
	1447	If true, this will create a fresh set of parameters from the
	1448	new program being linked, so if you had previously set parameters
	1449	you will have to set them again. If you set this to false, you must
	1450	be absolutely sure that the parameters match perfectly, and in the
	1451	case of named parameters refers to the indexes underlying them,
	1452	not just the names.
	1453	*/
	1454	void setGeometryProgram(const String& name, bool resetParams = true);
	1455	/** Sets the geometry program parameters.
	1456	@remarks
	1457	Only applicable to programmable passes.
	1458	*/
	1459	void setGeometryProgramParameters(GpuProgramParametersSharedPtr params);
	1460	/** Gets the name of the geometry program used by this pass. */
	1461	const String& getGeometryProgramName(void) const;
	1462	/** Gets the geometry program parameters used by this pass. */
	1463	GpuProgramParametersSharedPtr getGeometryProgramParameters(void) const;
	1464	/** Gets the geometry program used by this pass, only available after _load(). */
	1465	const GpuProgramPtr& getGeometryProgram(void) const;
	1466
	1467	/** Splits this Pass to one which can be handled in the number of
	1468	texture units specified.
	1469	@remarks
	1470	Only works on non-programmable passes, programmable passes cannot be
	1471	split, it's up to the author to ensure that there is a fallback Technique
	1472	for less capable cards.
	1473	@param numUnits The target number of texture units
	1474	@return A new Pass which contains the remaining units, and a scene_blend
	1475	setting appropriate to approximate the multitexture. This Pass will be
	1476	attached to the parent Technique of this Pass.
	1477	*/
	1478	Pass* _split(unsigned short numUnits);
	1479
	1480	/** Internal method to adjust pass index. */
	1481	void _notifyIndex(unsigned short index);
	1482
	1483	/** Internal method for preparing to load this pass. */
	1484	void _prepare(void);
	1485	/** Internal method for undoing the load preparartion for this pass. */
	1486	void _unprepare(void);
	1487	/** Internal method for loading this pass. */
	1488	void _load(void);
	1489	/** Internal method for unloading this pass. */
	1490	void _unload(void);
	1491	/// Is this loaded?
	1492	bool isLoaded(void) const;
	1493
	1494	/** Gets the 'hash' of this pass, ie a precomputed number to use for sorting
	1495	@remarks
	1496	This hash is used to sort passes, and for this reason the pass is hashed
	1497	using firstly its index (so that all passes are rendered in order), then
	1498	by the textures which it's TextureUnitState instances are using.
	1499	*/
	1500	uint32 getHash(void) const { return mHash; }
	1501	/// Mark the hash as dirty
	1502	void _dirtyHash(void);
	1503	/** Internal method for recalculating the hash.
	1504	@remarks
	1505	Do not call this unless you are sure the old hash is not still being
	1506	used by anything. If in doubt, call _dirtyHash if you want to force
	1507	recalculation of the has next time.
	1508	*/
	1509	void _recalculateHash(void);
	1510	/** Tells the pass that it needs recompilation. */
	1511	void _notifyNeedsRecompile(void);
	1512
	1513	/** Update automatic parameters.
	1514	@param source The source of the parameters
	1515	@param variabilityMask A mask of GpuParamVariability which identifies which autos will need updating
	1516	*/
	1517	void _updateAutoParams(const AutoParamDataSource* source, uint16 variabilityMask) const;
	1518
	1519	/** Gets the 'nth' texture which references the given content type.
	1520	@remarks
	1521	If the 'nth' texture unit which references the content type doesn't
	1522	exist, then this method returns an arbitrary high-value outside the
	1523	valid range to index texture units.
	1524	*/
	1525	unsigned short _getTextureUnitWithContentTypeIndex(
	1526	TextureUnitState::ContentType contentType, unsigned short index) const;
	1527
	1528	/** Set texture filtering for every texture unit
	1529	@note
	1530	This property actually exists on the TextureUnitState class
	1531	For simplicity, this method allows you to set these properties for
	1532	every current TeextureUnitState, If you need more precision, retrieve the
	1533	TextureUnitState instance and set the property there.
	1534	@see TextureUnitState::setTextureFiltering
	1535	*/
	1536	void setTextureFiltering(TextureFilterOptions filterType);
	1537	/** Sets the anisotropy level to be used for all textures.
	1538	@note
	1539	This property has been moved to the TextureUnitState class, which is accessible via the
	1540	Technique and Pass. For simplicity, this method allows you to set these properties for
	1541	every current TeextureUnitState, If you need more precision, retrieve the Technique,
	1542	Pass and TextureUnitState instances and set the property there.
	1543	@see TextureUnitState::setTextureAnisotropy
	1544	*/
	1545	void setTextureAnisotropy(unsigned int maxAniso);
	1546	/** If set to true, this forces normals to be normalised dynamically
	1547	by the hardware for this pass.
	1548	@remarks
	1549	This option can be used to prevent lighting variations when scaling an
	1550	object - normally because this scaling is hardware based, the normals
	1551	get scaled too which causes lighting to become inconsistent. By default the
	1552	SceneManager detects scaled objects and does this for you, but
	1553	this has an overhead so you might want to turn that off through
	1554	SceneManager::setNormaliseNormalsOnScale(false) and only do it per-Pass
	1555	when you need to.
	1556	*/
	1557	void setNormaliseNormals(bool normalise) { mNormaliseNormals = normalise; }
	1558
	1559	/** Returns true if this pass has auto-normalisation of normals set. */
	1560	bool getNormaliseNormals(void) const {return mNormaliseNormals; }
	1561
	1562	/** Static method to retrieve all the Passes which need their
	1563	hash values recalculated.
	1564	*/
	1565	static const PassSet& getDirtyHashList(void)
	1566	{ return msDirtyHashList; }
	1567	/** Static method to retrieve all the Passes which are pending deletion.
	1568	*/
	1569	static const PassSet& getPassGraveyard(void)
	1570	{ return msPassGraveyard; }
	1571	/** Static method to reset the list of passes which need their hash
	1572	values recalculated.
	1573	@remarks
	1574	For performance, the dirty list is not updated progressively as
	1575	the hashes are recalculated, instead we expect the processor of the
	1576	dirty hash list to clear the list when they are done.
	1577	*/
	1578	static void clearDirtyHashList(void);
	1579
	1580	/** Process all dirty and pending deletion passes. */
	1581	static void processPendingPassUpdates(void);
	1582
	1583	/** Queue this pass for deletion when appropriate. */
	1584	void queueForDeletion(void);
	1585
	1586	/** Returns whether this pass is ambient only.
	1587	*/
	1588	bool isAmbientOnly(void) const;
	1589
	1590	/** set the number of iterations that this pass
	1591	should perform when doing fast multi pass operation.
	1592	@remarks
	1593	Only applicable for programmable passes.
	1594	@param count number of iterations to perform fast multi pass operations.
	1595	A value greater than 1 will cause the pass to be executed count number of
	1596	times without changing the render state. This is very useful for passes
	1597	that use programmable shaders that have to iterate more than once but don't
	1598	need a render state change. Using multi pass can dramatically speed up rendering
	1599	for materials that do things like fur, blur.
	1600	A value of 1 turns off multi pass operation and the pass does
	1601	the normal pass operation.
	1602	*/
	1603	void setPassIterationCount(const size_t count) { mPassIterationCount = count; }
	1604
	1605	/** Gets the pass iteration count value.
	1606	*/
	1607	size_t getPassIterationCount(void) const { return mPassIterationCount; }
	1608
	1609	/** Applies texture names to Texture Unit State with matching texture name aliases.
	1610	All Texture Unit States within the pass are checked.
	1611	If matching texture aliases are found then true is returned.
	1612
	1613	@param
	1614	aliasList is a map container of texture alias, texture name pairs
	1615	@param
	1616	apply set true to apply the texture aliases else just test to see if texture alias matches are found.
	1617	@return
	1618	True if matching texture aliases were found in the pass.
	1619	*/
	1620	bool applyTextureAliases(const AliasTextureNamePairList& aliasList, const bool apply = true) const;
	1621
	1622	/** Sets whether or not this pass will be clipped by a scissor rectangle
	1623	encompassing the lights that are being used in it.
	1624	@remarks
	1625	In order to cut down on fillrate when you have a number of fixed-range
	1626	lights in the scene, you can enable this option to request that
	1627	during rendering, only the region of the screen which is covered by
	1628	the lights is rendered. This region is the screen-space rectangle
	1629	covering the union of the spheres making up the light ranges. Directional
	1630	lights are ignored for this.
	1631	@par
	1632	This is only likely to be useful for multipass additive lighting
	1633	algorithms, where the scene has already been 'seeded' with an ambient
	1634	pass and this pass is just adding light in affected areas.
	1635	@note
	1636	When using SHADOWTYPE_STENCIL_ADDITIVE or SHADOWTYPE_TEXTURE_ADDITIVE,
	1637	this option is implicitly used for all per-light passes and does
	1638	not need to be specified. If you are not using shadows or are using
	1639	a modulative or an integrated shadow technique then this could be useful.
	1640
	1641	*/
	1642	void setLightScissoringEnabled(bool enabled) { mLightScissoring = enabled; }
	1643	/** Gets whether or not this pass will be clipped by a scissor rectangle
	1644	encompassing the lights that are being used in it.
	1645	*/
	1646	bool getLightScissoringEnabled() const { return mLightScissoring; }
	1647
	1648	/** Gets whether or not this pass will be clipped by user clips planes
	1649	bounding the area covered by the light.
	1650	@remarks
	1651	In order to cut down on the geometry set up to render this pass
	1652	when you have a single fixed-range light being rendered through it,
	1653	you can enable this option to request that during triangle setup,
	1654	clip planes are defined to bound the range of the light. In the case
	1655	of a point light these planes form a cube, and in the case of
	1656	a spotlight they form a pyramid. Directional lights are never clipped.
	1657	@par
	1658	This option is only likely to be useful for multipass additive lighting
	1659	algorithms, where the scene has already been 'seeded' with an ambient
	1660	pass and this pass is just adding light in affected areas. In addition,
	1661	it will only be honoured if there is exactly one non-directional light
	1662	being used in this pass. Also, these clip planes override any user clip
	1663	planes set on Camera.
	1664	@note
	1665	When using SHADOWTYPE_STENCIL_ADDITIVE or SHADOWTYPE_TEXTURE_ADDITIVE,
	1666	this option is automatically used for all per-light passes if you
	1667	enable SceneManager::setShadowUseLightClipPlanes and does
	1668	not need to be specified. It is disabled by default since clip planes have
	1669	a cost of their own which may not always exceed the benefits they give you.
	1670	*/
	1671	void setLightClipPlanesEnabled(bool enabled) { mLightClipPlanes = enabled; }
	1672	/** Gets whether or not this pass will be clipped by user clips planes
	1673	bounding the area covered by the light.
	1674	*/
	1675	bool getLightClipPlanesEnabled() const { return mLightClipPlanes; }
	1676
	1677	/** Manually set which illumination stage this pass is a member of.
	1678	@remarks
	1679	When using an additive lighting mode (SHADOWTYPE_STENCIL_ADDITIVE or
	1680	SHADOWTYPE_TEXTURE_ADDITIVE), the scene is rendered in 3 discrete
	1681	stages, ambient (or pre-lighting), per-light (once per light, with
	1682	shadowing) and decal (or post-lighting). Usually OGRE figures out how
	1683	to categorise your passes automatically, but there are some effects you
	1684	cannot achieve without manually controlling the illumination. For example
	1685	specular effects are muted by the typical sequence because all textures
	1686	are saved until the IS_DECAL stage which mutes the specular effect.
	1687	Instead, you could do texturing within the per-light stage if it's
	1688	possible for your material and thus add the specular on after the
	1689	decal texturing, and have no post-light rendering.
	1690	@par
	1691	If you assign an illumination stage to a pass you have to assign it
	1692	to all passes in the technique otherwise it will be ignored. Also note
	1693	that whilst you can have more than one pass in each group, they cannot
	1694	alternate, ie all ambient passes will be before all per-light passes,
	1695	which will also be before all decal passes. Within their categories
	1696	the passes will retain their ordering though.
	1697	*/
	1698	void setIlluminationStage(IlluminationStage is) { mIlluminationStage = is; }
	1699	/// Get the manually assigned illumination stage, if any
	1700	IlluminationStage getIlluminationStage() const { return mIlluminationStage; }
	1701	/** There are some default hash functions used to order passes so that
	1702	render state changes are minimised, this enumerates them.
	1703	*/
	1704	enum BuiltinHashFunction
	1705	{
	1706	/** Try to minimise the number of texture changes. */
	1707	MIN_TEXTURE_CHANGE,
	1708	/** Try to minimise the number of GPU program changes.
	1709	@note Only really useful if you use GPU programs for all of your
	1710	materials.
	1711	*/
	1712	MIN_GPU_PROGRAM_CHANGE
	1713	};
	1714	/** Sets one of the default hash functions to be used.
	1715	@remarks
	1716	You absolutely must not change the hash function whilst any Pass instances
	1717	exist in the render queue. The only time you can do this is either
	1718	before you render anything, or directly after you manuall call
	1719	RenderQueue::clear(true) to completely destroy the queue structures.
	1720	The default is MIN_TEXTURE_CHANGE.
	1721	@note
	1722	You can also implement your own hash function, see the alternate version
	1723	of this method.
	1724	@see HashFunc
	1725	*/
	1726	static void setHashFunction(BuiltinHashFunction builtin);
	1727
	1728	/** Set the hash function used for all passes.
	1729	@remarks
	1730	You absolutely must not change the hash function whilst any Pass instances
	1731	exist in the render queue. The only time you can do this is either
	1732	before you render anything, or directly after you manuall call
	1733	RenderQueue::clear(true) to completely destroy the queue structures.
	1734	@note
	1735	You can also use one of the built-in hash functions, see the alternate version
	1736	of this method. The default is MIN_TEXTURE_CHANGE.
	1737	@see HashFunc
	1738	*/
	1739	static void setHashFunction(HashFunc* hashFunc) { msHashFunc = hashFunc; }
	1740
	1741	/** Get the hash function used for all passes.
	1742	*/
	1743	static HashFunc* getHashFunction(void) { return msHashFunc; }
	1744
	1745	/** Get the builtin hash function.
	1746	*/
	1747	static HashFunc* getBuiltinHashFunction(BuiltinHashFunction builtin);
	1748
	1749	/** Return an instance of user objects binding associated with this class.
	1750	You can use it to associate one or more custom objects with this class instance.
	1751	@see UserObjectBindings::setUserAny.
	1752	*/
	1753	UserObjectBindings& getUserObjectBindings() { return mUserObjectBindings; }
	1754
	1755	/** Return an instance of user objects binding associated with this class.
	1756	You can use it to associate one or more custom objects with this class instance.
	1757	@see UserObjectBindings::setUserAny.
	1758	*/
	1759	const UserObjectBindings& getUserObjectBindings() const { return mUserObjectBindings; }
	1760
	1761	/// Support for shader model 5.0, hull and domain shaders
	1762	/** Sets the details of the tesselation control program to use.
	1763	@remarks
	1764	Only applicable to programmable passes, this sets the details of
	1765	the Tesselation Hull program to use in this pass. The program will not be
	1766	loaded until the parent Material is loaded.
	1767	@param name The name of the program - this must have been
	1768	created using GpuProgramManager by the time that this Pass
	1769	is loaded. If this parameter is blank, any Tesselation Hull program in this pass is disabled.
	1770	@param resetParams
	1771	If true, this will create a fresh set of parameters from the
	1772	new program being linked, so if you had previously set parameters
	1773	you will have to set them again. If you set this to false, you must
	1774	be absolutely sure that the parameters match perfectly, and in the
	1775	case of named parameters refers to the indexes underlying them,
	1776	not just the names.
	1777	*/
	1778	void setTesselationHullProgram(const String& name, bool resetParams = true);
	1779	/** Sets the Tesselation Hull program parameters.
	1780	@remarks
	1781	Only applicable to programmable passes.
	1782	*/
	1783	void setTesselationHullProgramParameters(GpuProgramParametersSharedPtr params);
	1784	/** Gets the name of the Tesselation Hull program used by this pass. */
	1785	const String& getTesselationHullProgramName(void) const;
	1786	/** Gets the Tesselation Hull program parameters used by this pass. */
	1787	GpuProgramParametersSharedPtr getTesselationHullProgramParameters(void) const;
	1788	/** Gets the Tesselation Hull program used by this pass, only available after _load(). */
	1789	const GpuProgramPtr& getTesselationHullProgram(void) const;
	1790
	1791	/** Sets the details of the tesselation domain program to use.
	1792	@remarks
	1793	Only applicable to programmable passes, this sets the details of
	1794	the Tesselation domain program to use in this pass. The program will not be
	1795	loaded until the parent Material is loaded.
	1796	@param name The name of the program - this must have been
	1797	created using GpuProgramManager by the time that this Pass
	1798	is loaded. If this parameter is blank, any Tesselation domain program in this pass is disabled.
	1799	@param resetParams
	1800	If true, this will create a fresh set of parameters from the
	1801	new program being linked, so if you had previously set parameters
	1802	you will have to set them again. If you set this to false, you must
	1803	be absolutely sure that the parameters match perfectly, and in the
	1804	case of named parameters refers to the indexes underlying them,
	1805	not just the names.
	1806	*/
	1807	void setTesselationDomainProgram(const String& name, bool resetParams = true);
	1808	/** Sets the Tesselation Domain program parameters.
	1809	@remarks
	1810	Only applicable to programmable passes.
	1811	*/
	1812	void setTesselationDomainProgramParameters(GpuProgramParametersSharedPtr params);
	1813	/** Gets the name of the Domain Evaluation program used by this pass. */
	1814	const String& getTesselationDomainProgramName(void) const;
	1815	/** Gets the Tesselation Domain program parameters used by this pass. */
	1816	GpuProgramParametersSharedPtr getTesselationDomainProgramParameters(void) const;
	1817	/** Gets the Tesselation Domain program used by this pass, only available after _load(). */
	1818	const GpuProgramPtr& getTesselationDomainProgram(void) const;
	1819
	1820	/** Sets the details of the compute program to use.
	1821	@remarks
	1822	Only applicable to programmable passes, this sets the details of
	1823	the compute program to use in this pass. The program will not be
	1824	loaded until the parent Material is loaded.
	1825	@param name The name of the program - this must have been
	1826	created using GpuProgramManager by the time that this Pass
	1827	is loaded. If this parameter is blank, any compute program in this pass is disabled.
	1828	@param resetParams
	1829	If true, this will create a fresh set of parameters from the
	1830	new program being linked, so if you had previously set parameters
	1831	you will have to set them again. If you set this to false, you must
	1832	be absolutely sure that the parameters match perfectly, and in the
	1833	case of named parameters refers to the indexes underlying them,
	1834	not just the names.
	1835	*/
	1836	void setComputeProgram(const String& name, bool resetParams = true);
	1837	/** Sets the Tesselation Evaluation program parameters.
	1838	@remarks
	1839	Only applicable to programmable passes.
	1840	*/
	1841	void setComputeProgramParameters(GpuProgramParametersSharedPtr params);
	1842	/** Gets the name of the Tesselation Hull program used by this pass. */
	1843	const String& getComputeProgramName(void) const;
	1844	/** Gets the Tesselation Hull program parameters used by this pass. */
	1845	GpuProgramParametersSharedPtr getComputeProgramParameters(void) const;
	1846	/** Gets the Tesselation EHull program used by this pass, only available after _load(). */
	1847	const GpuProgramPtr& getComputeProgram(void) const;
	1848	};
	1849
	1850	/** Struct recording a pass which can be used for a specific illumination stage.
	1851	@remarks
	1852	This structure is used to record categorised passes which fit into a
	1853	number of distinct illumination phases - ambient, diffuse / specular
	1854	(per-light) and decal (post-lighting texturing).
	1855	An original pass may fit into one of these categories already, or it
	1856	may require splitting into its component parts in order to be categorised
	1857	properly.
	1858	*/
	1859	struct IlluminationPass : public PassAlloc
	1860	{
	1861	IlluminationStage stage;
	1862	/// The pass to use in this stage
	1863	Pass* pass;
	1864	/// Whether this pass is one which should be deleted itself
	1865	bool destroyOnShutdown;
	1866	/// The original pass which spawned this one
	1867	Pass* originalPass;
	1868
	1869	IlluminationPass() {}
	1870	};
	1871
	1872	typedef vector<IlluminationPass*>::type IlluminationPassList;
	1873
	1874	/** @} */
	1875	/** @} */
	1876
	1877	}
	1878
	1879	#endif

Note: See TracBrowser for help on using the repository browser.

Context Navigation

source: downloads/ogre_src_v1-9-0/OgreMain/include/OgrePass.h

Download in other formats: