Context Navigation

OgreSceneManager.h @ 316

Revision 316, 94.1 KB checked in by mattausch, 19 years ago (diff)
queries are realized as templates

Line
1	/*-------------------------------------------------------------------------
2	This source file is a part of OGRE
3	(Object-oriented Graphics Rendering Engine)
4
5	For the latest info, see http://www.ogre3d.org/
6
7	Copyright (c) 2000-2005 The OGRE Team
8	Also see acknowledgements in Readme.html
9
10	This library is free software; you can redistribute it and/or modify it
11	under the terms of the GNU Lesser General Public License (LGPL) as
12	published by the Free Software Foundation; either version 2.1 of the
13	License, or (at your option) any later version.
14
15	This library is distributed in the hope that it will be useful, but
16	WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
17	or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
18	License for more details.
19
20	You should have received a copy of the GNU Lesser General Public License
21	along with this library; if not, write to the Free Software Foundation,
22	Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA or go to
23	http://www.gnu.org/copyleft/lesser.txt
24	-------------------------------------------------------------------------*/
25	#ifndef __SceneManager_H__
26	#define __SceneManager_H__
27
28	// Precompiler options
29	#include "OgrePrerequisites.h"
30
31	#include "OgreString.h"
32	#include "OgreSceneNode.h"
33	#include "OgrePlane.h"
34	#include "OgreQuaternion.h"
35	#include "OgreColourValue.h"
36	#include "OgreCommon.h"
37	#include "OgreRenderQueue.h"
38	#include "OgreAnimationState.h"
39	#include "OgreSceneQuery.h"
40	#include "OgreAutoParamDataSource.h"
41	#include "OgreAnimationState.h"
42	#include "OgreRenderQueue.h"
43	#include "OgreRenderQueueSortingGrouping.h"
44	#include "OgreRectangle2D.h"
45
46	namespace Ogre {
47
48	/** Structure for holding a position & orientation pair. */
49	struct ViewPoint
50	{
51	Vector3 position;
52	Quaternion orientation;
53	};
54
55	// Forward declarations
56	class DefaultIntersectionSceneQuery;
57	class DefaultRaySceneQuery;
58	class DefaultSphereSceneQuery;
59	class DefaultAxisAlignedBoxSceneQuery;
60
61	/** Manages the rendering of a 'scene' i.e. a collection of primitives.
62	@remarks
63	This class defines the basic behaviour of the 'Scene Manager' family. These classes will
64	organise the objects in the scene and send them to the rendering system, a subclass of
65	RenderSystem. This basic superclass does no sorting, culling or organising of any sort.
66	@par
67	Subclasses may use various techniques to organise the scene depending on how they are
68	designed (e.g. BSPs, octrees etc). As with other classes, methods preceded with '_' are
69	designed to be called by other classes in the Ogre system, not by user applications,
70	although this is not forbidden.
71	@author
72	Steve Streeting
73	@version
74	1.0
75	*/
76	class _OgreExport SceneManager
77	{
78	friend class DefaultIntersectionSceneQuery;
79	friend class DefaultRaySceneQuery;
80	friend class DefaultSphereSceneQuery;
81	friend class DefaultAxisAlignedBoxSceneQuery;
82	friend class DefaultPlaneBoundedVolumeListSceneQuery;
83	public:
84	/// Query mask which will be used for world geometry @see SceneQuery
85	static unsigned long WORLD_GEOMETRY_QUERY_MASK;
86	/** Comparator for material map, for sorting materials into render order (e.g. transparent last).
87	*/
88	struct materialLess
89	{
90	_OgreExport bool operator()(const Material* x, const Material* y) const;
91	};
92	/// Comparator for sorting lights relative to a point
93	struct lightLess
94	{
95	_OgreExport bool operator()(const Light* a, const Light* b) const;
96	};
97
98	/// Describes the stage of rendering when performing complex illumination
99	enum IlluminationRenderStage
100	{
101	/// No special illumination stage
102	IRS_NONE,
103	/// Ambient stage, when background light is added
104	IRS_AMBIENT,
105	/// Diffuse / specular stage, when individual light contributions are added
106	IRS_PER_LIGHT,
107	/// Decal stage, when texture detail is added to the lit base
108	IRS_DECAL,
109	/// Render to texture stage, used for texture based shadows
110	IRS_RENDER_TO_TEXTURE,
111	/// Modulative render from shadow texture stage
112	IRS_RENDER_MODULATIVE_PASS
113	};
114
115	/** Enumeration of the possible modes allowed for processing the special case
116	render queue list.
117	@see SceneManager::setSpecialCaseRenderQueueMode
118	*/
119	enum SpecialCaseRenderQueueMode
120	{
121	/// Render only the queues in the special case list
122	SCRQM_INCLUDE,
123	/// Render all except the queues in the special case list
124	SCRQM_EXCLUDE
125	};
126	#ifdef GTP_VISIBILITY_MODIFIED_OGRE
127	/** added by matt: Render content of current scene node.
128	@param node scene node to be rendered
129	@param cam current camera
130	@param leavePassesInQueue list of passes which are left in queue
131	*/
132	void _renderSceneNode(Camera cam, SceneNode node, const int leavePassesInQueue = 0);
133	/** deletes all processed queues
134	@param leavePassesInQueue pass list which is not deleted from queue
135	@remark used to clear render queues before rendering scene node
136	*/
137	void _deleteRenderedQueueGroups(int leavePassesInQueue = 0);
138	/** Wrapper for useRenderableViewProjMde with is an
139	Internal method used by _renderVisibleObjects to deal with renderables
140	which override the camera's own view / projection materices.
141	*/
142	void useRenderableViewProjModeWrapper(Renderable* pRend); // HACK
143	/** HACK: A public wrapper method for setting up the renderstate for a rendering pass.
144	@param
145	pass The Pass details to set.
146	@returns
147	A Pass object that was used instead of the one passed in, can
148	happen when rendering shadow passes
149	@remark made public by matt
150	*/
151	virtual Pass* setPassWrapper(Pass* pass);
152
153	/** Renders an Ogre Entity.
154	*/
155	//void renderEntity(Entity *ent);
156
157	/** Renders an Ogre MovableObject.
158	@param mov the movable object to be rendered
159	@param leavePassesInQueue flag determining the passes which are left
160	in render queue after rendering
161	*/
162	void _renderMovableObject(MovableObject *mov, const int leavePassesInQueue);
163
164	/** Renders a single renderable using pass 0 of the renderable.
165	*/
166	void _renderSingleRenderable(Renderable *rend);
167
168	/** Tells the scene manager that the frame ends (i.e.,
169	one frame in the main loop.
170	*/
171	virtual void endFrame() {};
172	#endif // GTP_VISIBILITY_MODIFIED_OGRE
173
174	protected:
175
176	/// Queue of objects for rendering
177	RenderQueue* mRenderQueue;
178
179	/// Current ambient light, cached for RenderSystem
180	ColourValue mAmbientLight;
181
182	/// The rendering system to send the scene to
183	RenderSystem *mDestRenderSystem;
184
185	typedef std::map<String, Camera* > CameraList;
186
187	/** Central list of cameras - for easy memory management and lookup.
188	*/
189	CameraList mCameras;
190
191	typedef std::map<String, Light* > SceneLightList;
192
193	/** Central list of lights - for easy memory management and lookup.
194	*/
195	SceneLightList mLights;
196
197
198	typedef std::map<String, Entity* > EntityList;
199
200	/** Central list of entities - for easy memory management and lookup.
201	*/
202	EntityList mEntities;
203
204	typedef std::map<String, BillboardSet* > BillboardSetList;
205
206	/** Central list of billboard sets - for easy memory management and lookup.
207	*/
208	BillboardSetList mBillboardSets;
209
210	typedef std::map<String, StaticGeometry* > StaticGeometryList;
211	StaticGeometryList mStaticGeometryList;
212
213	typedef std::map<String, SceneNode*> SceneNodeList;
214
215	/** Central list of SceneNodes - for easy memory management.
216	@note
217	Note that this list is used only for memory management; the structure of the scene
218	is held using the hierarchy of SceneNodes starting with the root node. However you
219	can look up nodes this way.
220	*/
221	SceneNodeList mSceneNodes;
222
223	/// Camera in progress
224	Camera* mCameraInProgress;
225	/// Current Viewport
226	Viewport* mCurrentViewport;
227
228	/// Root scene node
229	SceneNode* mSceneRoot;
230
231	/// Autotracking scene nodes
232	typedef std::set<SceneNode*> AutoTrackingSceneNodes;
233	AutoTrackingSceneNodes mAutoTrackingSceneNodes;
234
235	// Sky params
236	// Sky plane
237	Entity* mSkyPlaneEntity;
238	Entity* mSkyDomeEntity[5];
239	Entity* mSkyBoxEntity[6];
240
241	SceneNode* mSkyPlaneNode;
242	SceneNode* mSkyDomeNode;
243	SceneNode* mSkyBoxNode;
244
245	bool mSkyPlaneEnabled;
246	bool mSkyPlaneDrawFirst;
247	Plane mSkyPlane;
248	// Sky box
249	bool mSkyBoxEnabled;
250	bool mSkyBoxDrawFirst;
251	Quaternion mSkyBoxOrientation;
252	// Sky dome
253	bool mSkyDomeEnabled;
254	bool mSkyDomeDrawFirst;
255	Quaternion mSkyDomeOrientation;
256	// Fog
257	FogMode mFogMode;
258	ColourValue mFogColour;
259	Real mFogStart;
260	Real mFogEnd;
261	Real mFogDensity;
262
263	typedef std::set<RenderQueueGroupID> SpecialCaseRenderQueueList;
264	SpecialCaseRenderQueueList mSpecialCaseQueueList;
265	SpecialCaseRenderQueueMode mSpecialCaseQueueMode;
266	RenderQueueGroupID mWorldGeometryRenderQueue;
267
268	/** Internal method for initialising the render queue.
269	@remarks
270	Subclasses can use this to install their own RenderQueue implementation.
271	*/
272	virtual void initRenderQueue(void);
273	/** Retrieves the internal render queue. */
274	virtual RenderQueue* getRenderQueue(void);
275
276	/** Internal method for setting up the renderstate for a rendering pass.
277	@param
278	pass The Pass details to set.
279	@returns
280	A Pass object that was used instead of the one passed in, can
281	happen when rendering shadow passes
282	*/
283	virtual Pass* setPass(Pass* pass);
284
285	/// A pass designed to let us render shadow colour on white for texture shadows
286	Pass* mShadowCasterPlainBlackPass;
287	/// A pass designed to let us render shadow receivers for texture shadows
288	Pass* mShadowReceiverPass;
289	/** Internal method for turning a regular pass into a shadow caster pass.
290	@remarks
291	This is only used for texture shadows, basically we're trying to
292	ensure that objects are rendered solid black.
293	This method will usually return the standard solid black pass for
294	all fixed function passes, but will merge in a vertex program
295	and fudge the AutpoParamDataSource to set black lighting for
296	passes with vertex programs.
297	*/
298	Pass* deriveShadowCasterPass(Pass* pass);
299	/** Internal method for turning a regular pass into a shadow receiver pass.
300	@remarks
301	This is only used for texture shadows, basically we're trying to
302	ensure that objects are rendered with a projective texture.
303	This method will usually return a standard single-texture pass for
304	all fixed function passes, but will merge in a vertex program
305	for passes with vertex programs.
306	*/
307	Pass* deriveShadowReceiverPass(Pass* pass);
308
309	/** Internal method to validate whether a Pass should be allowed to render.
310	@remarks
311	Called just before a pass is about to be used for rendering a group to
312	allow the SceneManager to omit it if required. A return value of false
313	skips this pass.
314	*/
315	bool validatePassForRendering(Pass* pass);
316
317	/** Internal method to validate whether a Renderable should be allowed to render.
318	@remarks
319	Called just before a pass is about to be used for rendering a Renderable to
320	allow the SceneManager to omit it if required. A return value of false
321	skips it.
322	*/
323	bool validateRenderableForRendering(Pass* pass, Renderable* rend);
324
325	enum BoxPlane
326	{
327	BP_FRONT = 0,
328	BP_BACK = 1,
329	BP_LEFT = 2,
330	BP_RIGHT = 3,
331	BP_UP = 4,
332	BP_DOWN = 5
333	};
334
335	/* Internal utility method for creating the planes of a skybox.
336	*/
337	MeshPtr createSkyboxPlane(
338	BoxPlane bp,
339	Real distance,
340	const Quaternion& orientation,
341	const String& groupName);
342
343	/* Internal utility method for creating the planes of a skydome.
344	*/
345	MeshPtr createSkydomePlane(
346	BoxPlane bp,
347	Real curvature, Real tiling, Real distance,
348	const Quaternion& orientation,
349	int xsegments, int ysegments, int ySegmentsToKeep,
350	const String& groupName);
351
352	// Flag indicating whether SceneNodes will be rendered as a set of 3 axes
353	bool mDisplayNodes;
354
355	/// Storage of animations, lookup by name
356	typedef std::map<String, Animation*> AnimationList;
357	AnimationList mAnimationsList;
358	AnimationStateSet mAnimationStates;
359
360	/** Internal method used by _renderVisibleObjects to deal with renderables
361	which override the camera's own view / projection materices. */
362	void useRenderableViewProjMode(Renderable* pRend);
363
364	/// Controller flag for determining if we need to set view/proj matrices
365	bool mCamChanged;
366
367	typedef std::vector<RenderQueueListener*> RenderQueueListenerList;
368	RenderQueueListenerList mRenderQueueListeners;
369
370	/// Internal method for firing the queue start event, returns true if queue is to be skipped
371	bool fireRenderQueueStarted(RenderQueueGroupID id);
372	/// Internal method for firing the queue end event, returns true if queue is to be repeated
373	bool fireRenderQueueEnded(RenderQueueGroupID id);
374
375	/** Internal method for setting the destination viewport for the next render. */
376	virtual void setViewport(Viewport *vp);
377
378	/** Flag that indicates if all of the scene node's bounding boxes should be shown as a wireframe. */
379	bool mShowBoundingBoxes;
380
381	/** Internal utility method for rendering a single object.
382	@remarks
383	Assumes that the pass has already been set up.
384	@param rend The renderable to issue to the pipeline
385	@param pass The pass which is being used
386	@param doLightIteration If true, this method will issue the renderable to
387	the pipeline possibly multiple times, if the pass indicates it should be
388	done once per light
389	@param manualLightList Only applicable if doLightIteration is false, this
390	method allows you to pass in a previously determined set of lights
391	which will be used for a single render of this object.
392	*/
393	virtual void renderSingleObject(Renderable* rend, Pass* pass, bool doLightIteration,
394	const LightList* manualLightList = 0);
395
396	/// Utility class for calculating automatic parameters for gpu programs
397	AutoParamDataSource mAutoParamDataSource;
398
399	ShadowTechnique mShadowTechnique;
400	bool mDebugShadows;
401	ColourValue mShadowColour;
402	Pass* mShadowDebugPass;
403	Pass* mShadowStencilPass;
404	Pass* mShadowModulativePass;
405	bool mShadowMaterialInitDone;
406	LightList mLightsAffectingFrustum;
407	HardwareIndexBufferSharedPtr mShadowIndexBuffer;
408	size_t mShadowIndexBufferSize;
409	Rectangle2D* mFullScreenQuad;
410	Real mShadowDirLightExtrudeDist;
411	IlluminationRenderStage mIlluminationStage;
412	unsigned short mShadowTextureSize;
413	unsigned short mShadowTextureCount;
414	PixelFormat mShadowTextureFormat;
415	typedef std::vector<RenderTexture*> ShadowTextureList;
416	ShadowTextureList mShadowTextures;
417	RenderTexture* mCurrentShadowTexture;
418	bool mShadowUseInfiniteFarPlane;
419	/** Internal method for locating a list of lights which could be affecting the frustum.
420	@remarks
421	Custom scene managers are encouraged to override this method to make use of their
422	scene partitioning scheme to more efficiently locate lights, and to eliminate lights
423	which may be occluded by word geometry.
424	*/
425	virtual void findLightsAffectingFrustum(const Camera* camera);
426	/// Internal method for setting up materials for shadows
427	virtual void initShadowVolumeMaterials(void);
428	/// Internal method for creating shadow textures (texture-based shadows)
429	virtual void createShadowTextures(unsigned short size, unsigned short count,
430	PixelFormat fmt);
431	/// Internal method for preparing shadow textures ready for use in a regular render
432	virtual void prepareShadowTextures(Camera* cam, Viewport* vp);
433
434	/** Internal method for rendering all the objects for a given light into the
435	stencil buffer.
436	@param light The light source
437	@param cam The camera being viewed from
438	*/
439	virtual void renderShadowVolumesToStencil(const Light* light, const Camera* cam);
440	/** Internal utility method for setting stencil state for rendering shadow volumes.
441	@param secondpass Is this the second pass?
442	@param zfail Should we be using the zfail method?
443	@param twosided Should we use a 2-sided stencil?
444	*/
445	virtual void setShadowVolumeStencilState(bool secondpass, bool zfail, bool twosided);
446	/** Render a set of shadow renderables. */
447	void renderShadowVolumeObjects(ShadowCaster::ShadowRenderableListIterator iShadowRenderables,
448	Pass* pass, const LightList *manualLightList, unsigned long flags,
449	bool secondpass, bool zfail, bool twosided);
450	typedef std::vector<ShadowCaster*> ShadowCasterList;
451	ShadowCasterList mShadowCasterList;
452	SphereSceneQuery* mShadowCasterSphereQuery;
453	AxisAlignedBoxSceneQuery* mShadowCasterAABBQuery;
454	Real mShadowFarDist;
455	Real mShadowFarDistSquared;
456	Real mShadowTextureOffset; // proportion of texture offset in view direction e.g. 0.4
457	Real mShadowTextureFadeStart; // as a proportion e.g. 0.6
458	Real mShadowTextureFadeEnd; // as a proportion e.g. 0.9
459	bool mShadowTextureSelfShadow;
460	Pass* mShadowTextureCustomCasterPass;
461	Pass* mShadowTextureCustomReceiverPass;
462	String mShadowTextureCustomCasterVertexProgram;
463	String mShadowTextureCustomReceiverVertexProgram;
464	GpuProgramParametersSharedPtr mShadowTextureCustomCasterVPParams;
465	GpuProgramParametersSharedPtr mShadowTextureCustomReceiverVPParams;
466	bool mShadowTextureCasterVPDirty;
467	bool mShadowTextureReceiverVPDirty;
468
469
470	GpuProgramParametersSharedPtr mInfiniteExtrusionParams;
471	GpuProgramParametersSharedPtr mFiniteExtrusionParams;
472
473	/// Inner class to use as callback for shadow caster scene query
474	class _OgreExport ShadowCasterSceneQueryListener : public SceneQueryListener
475	{
476	protected:
477	SceneManager* mSceneMgr;
478	ShadowCasterList* mCasterList;
479	bool mIsLightInFrustum;
480	const PlaneBoundedVolumeList* mLightClipVolumeList;
481	const Camera* mCamera;
482	const Light* mLight;
483	Real mFarDistSquared;
484	public:
485	ShadowCasterSceneQueryListener(SceneManager* sm) : mSceneMgr(sm),
486	mCasterList(0), mIsLightInFrustum(false), mLightClipVolumeList(0),
487	mCamera(0) {}
488	// Prepare the listener for use with a set of parameters
489	void prepare(bool lightInFrustum,
490	const PlaneBoundedVolumeList* lightClipVolumes,
491	const Light* light, const Camera* cam, ShadowCasterList* casterList,
492	Real farDistSquared)
493	{
494	mCasterList = casterList;
495	mIsLightInFrustum = lightInFrustum;
496	mLightClipVolumeList = lightClipVolumes;
497	mCamera = cam;
498	mLight = light;
499	mFarDistSquared = farDistSquared;
500	}
501	bool queryResult(MovableObject* object);
502	bool queryResult(SceneQuery::WorldFragment* fragment);
503	};
504
505	ShadowCasterSceneQueryListener* mShadowCasterQueryListener;
506
507	/** Internal method for locating a list of shadow casters which
508	could be affecting the frustum for a given light.
509	@remarks
510	Custom scene managers are encouraged to override this method to add optimisations,
511	and to add their own custom shadow casters (perhaps for world geometry)
512	*/
513	virtual const ShadowCasterList& findShadowCastersForLight(const Light* light,
514	const Camera* camera);
515	/** Render the objects in a given queue group
516	*/
517	virtual void renderQueueGroupObjects(RenderQueueGroup* group);
518	/** Render a group in the ordinary way */
519	virtual void renderBasicQueueGroupObjects(RenderQueueGroup* pGroup);
520	/** Render a group with the added complexity of additive stencil shadows. */
521	virtual void renderAdditiveStencilShadowedQueueGroupObjects(RenderQueueGroup* group);
522	/** Render a group with the added complexity of additive stencil shadows. */
523	virtual void renderModulativeStencilShadowedQueueGroupObjects(RenderQueueGroup* group);
524	/** Render a group rendering only shadow casters. */
525	virtual void renderTextureShadowCasterQueueGroupObjects(RenderQueueGroup* group);
526	/** Render a group rendering only shadow receivers. */
527	virtual void renderTextureShadowReceiverQueueGroupObjects(RenderQueueGroup* group);
528	/** Render a group with the added complexity of additive stencil shadows. */
529	virtual void renderModulativeTextureShadowedQueueGroupObjects(RenderQueueGroup* group);
530	/** Render a set of objects, see renderSingleObject for param definitions */
531	virtual void renderObjects(const RenderPriorityGroup::SolidRenderablePassMap& objs,
532	bool doLightIteration, const LightList* manualLightList = 0);
533	/** Render a set of objects, see renderSingleObject for param definitions */
534	virtual void renderObjects(const RenderPriorityGroup::TransparentRenderablePassList& objs,
535	bool doLightIteration, const LightList* manualLightList = 0);
536	/** Render those objects in the transparent pass list which have shadow casting forced on
537	@remarks
538	This function is intended to be used to render the shadows of transparent objects which have
539	transparency_casts_shadows set to 'on' in their material
540	*/
541	virtual void renderTransparentShadowCasterObjects(const RenderPriorityGroup::TransparentRenderablePassList& objs,
542	bool doLightIteration, const LightList* manualLightList = 0);
543
544	public:
545	/** Default constructor.
546	*/
547	SceneManager();
548
549	/** Default destructor.
550	*/
551	virtual ~SceneManager();
552
553	/** Creates a camera to be managed by this scene manager.
554	@remarks
555	This camera must be added to the scene at a later time using
556	the attachObject method of the SceneNode class.
557	@param
558	name Name to give the new camera.
559	*/
560	virtual Camera* createCamera(const String& name);
561
562	/** Retrieves a pointer to the named camera.
563	*/
564	virtual Camera* getCamera(const String& name);
565
566	/** Removes a camera from the scene.
567	@remarks
568	This method removes a previously added camera from the scene.
569	The camera is deleted so the caller must ensure no references
570	to it's previous instance (e.g. in a SceneNode) are used.
571	@param
572	cam Pointer to the camera to remove
573	*/
574	virtual void removeCamera(Camera *cam);
575
576	/** Removes a camera from the scene.
577	@remarks
578	This method removes an camera from the scene based on the
579	camera's name rather than a pointer.
580	*/
581	virtual void removeCamera(const String& name);
582
583	/** Removes (and destroys) all cameras from the scene.
584	*/
585	virtual void removeAllCameras(void);
586
587	/** Creates a light for use in the scene.
588	@remarks
589	Lights can either be in a fixed position and independent of the
590	scene graph, or they can be attached to SceneNodes so they derive
591	their position from the parent node. Either way, they are created
592	using this method so that the SceneManager manages their
593	existence.
594	@param
595	name The name of the new light, to identify it later.
596	*/
597	virtual Light* createLight(const String& name);
598
599	/** Returns a pointer to the named Light which has previously been added to the scene.
600	*/
601	virtual Light* getLight(const String& name);
602
603	/** Removes the named light from the scene and destroys it.
604	@remarks
605	Any pointers held to this light after calling this method will be invalid.
606	*/
607	virtual void removeLight(const String& name);
608
609	/** Removes the light from the scene and destroys it based on a pointer.
610	@remarks
611	Any pointers held to this light after calling this method will be invalid.
612	*/
613	virtual void removeLight(Light* light);
614	/** Removes and destroys all lights in the scene.
615	*/
616	virtual void removeAllLights(void);
617
618	/** Populate a light list with an ordered set of the lights which are closest
619	to the position specified.
620	@remarks
621	Note that since directional lights have no position, they are always considered
622	closer than any point lights and as such will always take precedence.
623	@par
624	Subclasses of the default SceneManager may wish to take into account other issues
625	such as possible visibility of the light if that information is included in their
626	data structures. This basic scenemanager simply orders by distance, eliminating
627	those lights which are out of range.
628	@par
629	The number of items in the list max exceed the maximum number of lights supported
630	by the renderer, but the extraneous ones will never be used. In fact the limit will
631	be imposed by Pass::getMaxSimultaneousLights.
632	@param position The position at which to evaluate the list of lights
633	@param radius The bounding radius to test
634	@param destList List to be populated with ordered set of lights; will be cleared by
635	this method before population.
636	*/
637	virtual void _populateLightList(const Vector3& position, Real radius, LightList& destList);
638
639
640	/** Creates an instance of a SceneNode.
641	@remarks
642	Note that this does not add the SceneNode to the scene hierarchy.
643	This method is for convenience, since it allows an instance to
644	be created for which the SceneManager is responsible for
645	allocating and releasing memory, which is convenient in complex
646	scenes.
647	@par
648	To include the returned SceneNode in the scene, use the addChild
649	method of the SceneNode which is to be it's parent.
650	@par
651	Note that this method takes no parameters, and the node created is unnamed (it is
652	actually given a generated name, which you can retrieve if you want).
653	If you wish to create a node with a specific name, call the alternative method
654	which takes a name parameter.
655	*/
656	virtual SceneNode* createSceneNode(void);
657
658	/** Creates an instance of a SceneNode with a given name.
659	@remarks
660	Note that this does not add the SceneNode to the scene hierarchy.
661	This method is for convenience, since it allows an instance to
662	be created for which the SceneManager is responsible for
663	allocating and releasing memory, which is convenient in complex
664	scenes.
665	@par
666	To include the returned SceneNode in the scene, use the addChild
667	method of the SceneNode which is to be it's parent.
668	@par
669	Note that this method takes a name parameter, which makes the node easier to
670	retrieve directly again later.
671	*/
672	virtual SceneNode* createSceneNode(const String& name);
673
674	/** Destroys a SceneNode with a given name.
675	@remarks
676	This allows you to physically delete an individual SceneNode if you want to.
677	Note that this is not normally recommended, it's better to allow SceneManager
678	to delete the nodes when the scene is cleared.
679	*/
680	virtual void destroySceneNode(const String& name);
681
682	/** Gets the SceneNode at the root of the scene hierarchy.
683	@remarks
684	The entire scene is held as a hierarchy of nodes, which
685	allows things like relative transforms, general changes in
686	rendering state etc (See the SceneNode class for more info).
687	In this basic SceneManager class, the application using
688	Ogre is free to structure this hierarchy however it likes,
689	since it has no real significance apart from making transforms
690	relative to each node (more specialised subclasses will
691	provide utility methods for building specific node structures
692	e.g. loading a BSP tree).
693	@par
694	However, in all cases there is only ever one root node of
695	the hierarchy, and this method returns a pointer to it.
696	*/
697	virtual SceneNode* getRootSceneNode(void) const;
698
699	/** Retrieves a named SceneNode from the scene graph.
700	@remarks
701	If you chose to name a SceneNode as you created it, or if you
702	happened to make a note of the generated name, you can look it
703	up wherever it is in the scene graph using this method.
704	*/
705	virtual SceneNode* getSceneNode(const String& name) const;
706
707	/** Create an Entity (instance of a discrete mesh).
708	@param
709	entityName The name to be given to the entity (must be unique).
710	@param
711	meshName The name of the Mesh it is to be based on (e.g. 'knot.oof'). The
712	mesh will be loaded if it is not already.
713	*/
714	virtual Entity* createEntity(const String& entityName, const String& meshName);
715
716	/** Prefab shapes available without loading a model.
717	@note
718	Minimal implementation at present.
719	@todo
720	Add more prefabs (teapots, teapots!!!)
721	*/
722	enum PrefabType {
723	PT_PLANE
724	};
725
726	/** Create an Entity (instance of a discrete mesh) from a range of prefab shapes.
727	@param
728	entityName The name to be given to the entity (must be unique).
729	@param
730	ptype The prefab type.
731	*/
732	virtual Entity* createEntity(const String& entityName, PrefabType ptype);
733	/** Retrieves a pointer to the named Entity. */
734	virtual Entity* getEntity(const String& name);
735
736	/** Removes & destroys an Entity from the SceneManager.
737	@warning
738	Must only be done if the Entity is not attached
739	to a SceneNode. It may be safer to wait to clear the whole
740	scene if you are unsure use clearScene.
741	@see
742	SceneManager::clearScene
743	*/
744	virtual void removeEntity(Entity* ent);
745
746	/** Removes & destroys an Entity from the SceneManager by name.
747	@warning
748	Must only be done if the Entity is not attached
749	to a SceneNode. It may be safer to wait to clear the whole
750	scene if you are unsure use clearScene.
751	@see
752	SceneManager::clearScene
753	*/
754	virtual void removeEntity(const String& name);
755
756	/** Removes & destroys all Entities.
757	@warning
758	Again, use caution since no Entity must be referred to
759	elsewhere e.g. attached to a SceneNode otherwise a crash
760	is likely. Use clearScene if you are unsure (it clears SceneNode
761	entries too.)
762	@see
763	SceneManager::clearScene
764	*/
765	virtual void removeAllEntities(void);
766
767	/** Empties the entire scene, inluding all SceneNodes, Entities, Lights,
768	BillboardSets etc. Cameras are not deleted at this stage since
769	they are still referenced by viewports, which are not destroyed during
770	this process.
771	*/
772	virtual void clearScene(void);
773
774	/** Sets the ambient light level to be used for the scene.
775	@remarks
776	This sets the colour and intensity of the ambient light in the scene, i.e. the
777	light which is 'sourceless' and illuminates all objects equally.
778	The colour of an object is affected by a combination of the light in the scene,
779	and the amount of light that object reflects (in this case based on the Material::ambient
780	property).
781	@remarks
782	By default the ambient light in the scene is ColourValue::Black, i.e. no ambient light. This
783	means that any objects rendered with a Material which has lighting enabled (see Material::setLightingEnabled)
784	will not be visible unless you have some dynamic lights in your scene.
785	*/
786	void setAmbientLight(const ColourValue& colour);
787
788	/** Returns the ambient light level to be used for the scene.
789	*/
790	const ColourValue& getAmbientLight(void) const;
791
792	/** Sets the source of the 'world' geometry, i.e. the large, mainly static geometry
793	making up the world e.g. rooms, landscape etc.
794	@remarks
795	Depending on the type of SceneManager (subclasses will be specialised
796	for particular world geometry types) you have requested via the Root or
797	SceneManagerEnumerator classes, you can pass a filename to this method and it
798	will attempt to load the world-level geometry for use. If you try to load
799	an inappropriate type of world data an exception will be thrown. The default
800	SceneManager cannot handle any sort of world geometry and so will always
801	throw an exception. However subclasses like BspSceneManager can load
802	particular types of world geometry e.g. "q3dm1.bsp".
803	@par
804	World geometry will be loaded via the 'common' resource paths and archives set in the
805	ResourceManager class.
806	*/
807	virtual void setWorldGeometry(const String& filename);
808
809	/** Estimate the number of loading stages required to load the named
810	world geometry.
811	@remarks
812	This method should be overridden by SceneManagers that provide
813	custom world geometry that can take some time to load. They should
814	return from this method a count of the number of stages of progress
815	they can report on whilst loading. During real loading (setWorldGeomtry),
816	they should call ResourceGroupManager::_notifyWorldGeometryProgress exactly
817	that number of times when loading the geometry for real.
818	@note
819	The default is to return 0, ie to not report progress.
820	*/
821	virtual size_t estimateWorldGeometry(const String& filename) { return 0; }
822
823	/** Asks the SceneManager to provide a suggested viewpoint from which the scene should be viewed.
824	@remarks
825	Typically this method returns the origin unless a) world geometry has been loaded using
826	SceneManager::setWorldGeometry and b) that world geometry has suggested 'start' points.
827	If there is more than one viewpoint which the scene manager can suggest, it will always suggest
828	the first one unless the random parameter is true.
829	@param
830	random If true, and there is more than one possible suggestion, a random one will be used. If false
831	the same one will always be suggested.
832	@return
833	On success, true is returned.
834	@par
835	On failiure, false is returned.
836	*/
837	virtual ViewPoint getSuggestedViewpoint(bool random = false);
838
839	/** Method for setting a specific option of the Scene Manager. These options are usually
840	specific for a certain implemntation of the Scene Manager class, and may (and probably
841	will) not exist across different implementations.
842	@param
843	strKey The name of the option to set
844	@param
845	pValue A pointer to the value - the size should be calculated by the scene manager
846	based on the key
847	@return
848	On success, true is returned.
849	@par
850	On failiure, false is returned.
851	*/
852	virtual bool setOption( const String& strKey, const void* pValue ) { return false; }
853
854	/** Method for getting the value of an implementation-specific Scene Manager option.
855	@param
856	strKey The name of the option
857	@param
858	pDestValue A pointer to a memory location where the value will
859	be copied. Currently, the memory will be allocated by the
860	scene manager, but this may change
861	@return
862	On success, true is returned and pDestValue points to the value of the given
863	option.
864	@par
865	On failiure, false is returned and pDestValue is set to NULL.
866	*/
867	virtual bool getOption( const String& strKey, void* pDestValue ) { return false; }
868
869	/** Method for verifying wether the scene manager has an implementation-specific
870	option.
871	@param
872	strKey The name of the option to check for.
873	@return
874	If the scene manager contains the given option, true is returned.
875	@remarks
876	If it does not, false is returned.
877	*/
878	virtual bool hasOption( const String& strKey ) const { return false; }
879	/** Method for getting all possible values for a specific option. When this list is too large
880	(i.e. the option expects, for example, a float), the return value will be true, but the
881	list will contain just one element whose size will be set to 0.
882	Otherwise, the list will be filled with all the possible values the option can
883	accept.
884	@param
885	strKey The name of the option to get the values for.
886	@param
887	refValueList A reference to a list that will be filled with the available values.
888	@return
889	On success (the option exists), true is returned.
890	@par
891	On failure, false is returned.
892	*/
893	virtual bool getOptionValues( const String& strKey, StringVector& refValueList ) { return false; }
894
895	/** Method for getting all the implementation-specific options of the scene manager.
896	@param
897	refKeys A reference to a list that will be filled with all the available options.
898	@return
899	On success, true is returned. On failiure, false is returned.
900	*/
901	virtual bool getOptionKeys( StringVector& refKeys ) { return false; }
902
903	/** Internal method for updating the scene graph ie the tree of SceneNode instances managed by this class.
904	@remarks
905	This must be done before issuing objects to the rendering pipeline, since derived transformations from
906	parent nodes are not updated until required. This SceneManager is a basic implementation which simply
907	updates all nodes from the root. This ensures the scene is up to date but requires all the nodes
908	to be updated even if they are not visible. Subclasses could trim this such that only potentially visible
909	nodes are updated.
910	*/
911	virtual void _updateSceneGraph(Camera* cam);
912
913	/** Internal method which parses the scene to find visible objects to render.
914	@remarks
915	If you're implementing a custom scene manager, this is the most important method to
916	override since it's here you can apply your custom world partitioning scheme. Once you
917	have added the appropriate objects to the render queue, you can let the default
918	SceneManager objects _renderVisibleObjects handle the actual rendering of the objects
919	you pick.
920	@par
921	Any visible objects will be added to a rendering queue, which is indexed by material in order
922	to ensure objects with the same material are rendered together to minimise render state changes.
923	*/
924	virtual void _findVisibleObjects(Camera* cam, bool onlyShadowCasters);
925
926	/** Internal method for applying animations to scene nodes.
927	@remarks
928	Uses the internally stored AnimationState objects to apply animation to SceneNodes.
929	*/
930	virtual void _applySceneAnimations(void);
931
932	/** Sends visible objects found in _findVisibleObjects to the rendering engine.
933	*/
934	virtual void _renderVisibleObjects(void);
935
936	/** Prompts the class to send its contents to the renderer.
937	@remarks
938	This method prompts the scene manager to send the
939	contents of the scene it manages to the rendering
940	pipeline, possibly preceded by some sorting, culling
941	or other scene management tasks. Note that this method is not normally called
942	directly by the user application; it is called automatically
943	by the Ogre rendering loop.
944	@param camera Pointer to a camera from whose viewpoint the scene is to
945	be rendered.
946	@param vp The target viewport
947	@param includeOverlays Whether or not overlay objects should be rendered
948	*/
949	virtual void _renderScene(Camera* camera, Viewport* vp, bool includeOverlays);
950
951	/** Internal method for queueing the sky objects with the params as
952	previously set through setSkyBox, setSkyPlane and setSkyDome.
953	*/
954	virtual void _queueSkiesForRendering(Camera* cam);
955
956
957
958	/** Notifies the scene manager of its destination render system
959	@remarks
960	Called automatically by RenderSystem::addSceneManager
961	this method simply notifies the manager of the render
962	system to which its output must be directed.
963	@param
964	sys Pointer to the RenderSystem subclass to be used as a render target.
965	*/
966	virtual void _setDestinationRenderSystem(RenderSystem* sys);
967
968	/** Enables / disables a 'sky plane' i.e. a plane at constant
969	distance from the camera representing the sky.
970	@remarks
971	You can create sky planes yourself using the standard mesh and
972	entity methods, but this creates a plane which the camera can
973	never get closer or further away from - it moves with the camera.
974	(NB you could create this effect by creating a world plane which
975	was attached to the same SceneNode as the Camera too, but this
976	would only apply to a single camera whereas this plane applies to
977	any camera using this scene manager).
978	@note
979	To apply scaling, scrolls etc to the sky texture(s) you
980	should use the TextureUnitState class methods.
981	@param
982	enable True to enable the plane, false to disable it
983	@param
984	plane Details of the plane, i.e. it's normal and it's
985	distance from the camera.
986	@param
987	materialName The name of the material the plane will use
988	@param
989	scale The scaling applied to the sky plane - higher values
990	mean a bigger sky plane - you may want to tweak this
991	depending on the size of plane.d and the other
992	characteristics of your scene
993	@param
994	tiling How many times to tile the texture across the sky.
995	Applies to all texture layers. If you need finer control use
996	the TextureUnitState texture coordinate transformation methods.
997	@param
998	drawFirst If true, the plane is drawn before all other
999	geometry in the scene, without updating the depth buffer.
1000	This is the safest rendering method since all other objects
1001	will always appear in front of the sky. However this is not
1002	the most efficient way if most of the sky is often occluded
1003	by other objects. If this is the case, you can set this
1004	parameter to false meaning it draws <em>after</em> all other
1005	geometry which can be an optimisation - however you must
1006	ensure that the plane.d value is large enough that no objects
1007	will 'poke through' the sky plane when it is rendered.
1008	@param
1009	bow If zero, the plane will be completely flat (like previous
1010	versions. If above zero, the plane will be curved, allowing
1011	the sky to appear below camera level. Curved sky planes are
1012	simular to skydomes, but are more compatable with fog.
1013	@param xsegments, ysegments
1014	Determines the number of segments the plane will have to it. This
1015	is most important when you are bowing the plane, but may also be useful
1016	if you need tesselation on the plane to perform per-vertex effects.
1017	@param groupName
1018	The name of the resource group to which to assign the plane mesh.
1019	*/
1020	virtual void setSkyPlane(
1021	bool enable,
1022	const Plane& plane, const String& materialName, Real scale = 1000,
1023	Real tiling = 10, bool drawFirst = true, Real bow = 0,
1024	int xsegments = 1, int ysegments = 1,
1025	const String& groupName = ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME);
1026
1027	/** Enables / disables a 'sky box' i.e. a 6-sided box at constant
1028	distance from the camera representing the sky.
1029	@remarks
1030	You could create a sky box yourself using the standard mesh and
1031	entity methods, but this creates a plane which the camera can
1032	never get closer or further away from - it moves with the camera.
1033	(NB you could create this effect by creating a world box which
1034	was attached to the same SceneNode as the Camera too, but this
1035	would only apply to a single camera whereas this skybox applies
1036	to any camera using this scene manager).
1037	@par
1038	The material you use for the skybox can either contain layers
1039	which are single textures, or they can be cubic textures, i.e.
1040	made up of 6 images, one for each plane of the cube. See the
1041	TextureUnitState class for more information.
1042	@param
1043	enable True to enable the skybox, false to disable it
1044	@param
1045	materialName The name of the material the box will use
1046	@param
1047	distance Distance in world coorinates from the camera to
1048	each plane of the box. The default is normally OK.
1049	@param
1050	drawFirst If true, the box is drawn before all other
1051	geometry in the scene, without updating the depth buffer.
1052	This is the safest rendering method since all other objects
1053	will always appear in front of the sky. However this is not
1054	the most efficient way if most of the sky is often occluded
1055	by other objects. If this is the case, you can set this
1056	parameter to false meaning it draws <em>after</em> all other
1057	geometry which can be an optimisation - however you must
1058	ensure that the distance value is large enough that no
1059	objects will 'poke through' the sky box when it is rendered.
1060	@param
1061	orientation Optional parameter to specify the orientation
1062	of the box. By default the 'top' of the box is deemed to be
1063	in the +y direction, and the 'front' at the -z direction.
1064	You can use this parameter to rotate the sky if you want.
1065	@param groupName
1066	The name of the resource group to which to assign the plane mesh.
1067	*/
1068	virtual void setSkyBox(
1069	bool enable, const String& materialName, Real distance = 5000,
1070	bool drawFirst = true, const Quaternion& orientation = Quaternion::IDENTITY,
1071	const String& groupName = ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME);
1072
1073	/** Enables / disables a 'sky dome' i.e. an illusion of a curved sky.
1074	@remarks
1075	A sky dome is actually formed by 5 sides of a cube, but with
1076	texture coordinates generated such that the surface appears
1077	curved like a dome. Sky domes are appropriate where you need a
1078	realistic looking sky where the scene is not going to be
1079	'fogged', and there is always a 'floor' of some sort to prevent
1080	the viewer looking below the horizon (the distortion effect below
1081	the horizon can be pretty horrible, and there is never anyhting
1082	directly below the viewer). If you need a complete wrap-around
1083	background, use the setSkyBox method instead. You can actually
1084	combine a sky box and a sky dome if you want, to give a positional
1085	backdrop with an overlayed curved cloud layer.
1086	@par
1087	Sky domes work well with 2D repeating textures like clouds. You
1088	can change the apparant 'curvature' of the sky depending on how
1089	your scene is viewed - lower curvatures are better for 'open'
1090	scenes like landscapes, whilst higher curvatures are better for
1091	say FPS levels where you don't see a lot of the sky at once and
1092	the exaggerated curve looks good.
1093	@param
1094	enable True to enable the skydome, false to disable it
1095	@param
1096	materialName The name of the material the dome will use
1097	@param
1098	curvature The curvature of the dome. Good values are
1099	between 2 and 65. Higher values are more curved leading to
1100	a smoother effect, lower values are less curved meaning
1101	more distortion at the horizons but a better distance effect.
1102	@param
1103	tiling How many times to tile the texture(s) across the
1104	dome.
1105	@param
1106	distance Distance in world coorinates from the camera to
1107	each plane of the box the dome is rendered on. The default
1108	is normally OK.
1109	@param
1110	drawFirst If true, the dome is drawn before all other
1111	geometry in the scene, without updating the depth buffer.
1112	This is the safest rendering method since all other objects
1113	will always appear in front of the sky. However this is not
1114	the most efficient way if most of the sky is often occluded
1115	by other objects. If this is the case, you can set this
1116	parameter to false meaning it draws <em>after</em> all other
1117	geometry which can be an optimisation - however you must
1118	ensure that the distance value is large enough that no
1119	objects will 'poke through' the sky when it is rendered.
1120	@param
1121	orientation Optional parameter to specify the orientation
1122	of the dome. By default the 'top' of the dome is deemed to
1123	be in the +y direction, and the 'front' at the -z direction.
1124	You can use this parameter to rotate the sky if you want.
1125	@param groupName
1126	The name of the resource group to which to assign the plane mesh.
1127	*/
1128	virtual void setSkyDome(
1129	bool enable, const String& materialName, Real curvature = 10,
1130	Real tiling = 8, Real distance = 4000, bool drawFirst = true,
1131	const Quaternion& orientation = Quaternion::IDENTITY,
1132	int xsegments = 16, int ysegments = 16, int ysegments_keep = -1,
1133	const String& groupName = ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME);
1134
1135	/** Sets the fogging mode applied to the scene.
1136	@remarks
1137	This method sets up the scene-wide fogging effect. These settings
1138	apply to all geometry rendered, UNLESS the material with which it
1139	is rendered has it's own fog settings (see Material::setFog).
1140	@param
1141	mode Set up the mode of fog as described in the FogMode
1142	enum, or set to FOG_NONE to turn off.
1143	@param
1144	colour The colour of the fog. Either set this to the same
1145	as your viewport background colour, or to blend in with a
1146	skydome or skybox.
1147	@param
1148	expDensity The density of the fog in FOG_EXP or FOG_EXP2
1149	mode, as a value between 0 and 1. The default is 0.001.
1150	@param
1151	linearStart Distance in world units at which linear fog starts to
1152	encroach. Only applicable if mode is
1153	FOG_LINEAR.
1154	@param
1155	linearEnd Distance in world units at which linear fog becomes completely
1156	opaque. Only applicable if mode is
1157	FOG_LINEAR.
1158	*/
1159	void setFog(
1160	FogMode mode = FOG_NONE, const ColourValue& colour = ColourValue::White,
1161	Real expDensity = 0.001, Real linearStart = 0.0, Real linearEnd = 1.0);
1162
1163	/** Returns the fog mode for the scene.
1164	*/
1165	virtual FogMode getFogMode(void) const;
1166
1167	/** Returns the fog colour for the scene.
1168	*/
1169	virtual const ColourValue& getFogColour(void) const;
1170
1171	/** Returns the fog start distance for the scene.
1172	*/
1173	virtual Real getFogStart(void) const;
1174
1175	/** Returns the fog end distance for the scene.
1176	*/
1177	virtual Real getFogEnd(void) const;
1178
1179	/** Returns the fog density for the scene.
1180	*/
1181	virtual Real getFogDensity(void) const;
1182
1183
1184	/** Creates a new BillboardSet for use with this scene manager.
1185	@remarks
1186	This method creates a new BillboardSet which is registered with
1187	the SceneManager. The SceneManager will destroy this object when
1188	it shuts down or when the SceneManager::clearScene method is
1189	called, so the caller does not have to worry about destroying
1190	this object (in fact, it definitely should not do this).
1191	@par
1192	See the BillboardSet documentations for full details of the
1193	returned class.
1194	@param
1195	name The name to give to this billboard set. Must be unique.
1196	@param
1197	poolSize The initial size of the pool of billboards (see BillboardSet for more information)
1198	@see
1199	BillboardSet
1200	*/
1201	virtual BillboardSet* createBillboardSet(const String& name, unsigned int poolSize = 20);
1202
1203	/** Retrieves a pointer to the named BillboardSet.
1204	*/
1205	virtual BillboardSet* getBillboardSet(const String& name);
1206
1207	/** Removes & destroys an BillboardSet from the SceneManager.
1208	@warning
1209	Must only be done if the BillboardSet is not attached
1210	to a SceneNode. It may be safer to wait to clear the whole
1211	scene. If you are unsure, use clearScene.
1212	*/
1213	virtual void removeBillboardSet(BillboardSet* set);
1214
1215	/** Removes & destroys an BillboardSet from the SceneManager by name.
1216	@warning
1217	Must only be done if the BillboardSet is not attached
1218	to a SceneNode. It may be safer to wait to clear the whole
1219	scene. If you are unsure, use clearScene.
1220	*/
1221	virtual void removeBillboardSet(const String& name);
1222
1223	/** Removes & destroys all BillboardSets.
1224	@warning
1225	Again, use caution since no BillboardSet must be referred to
1226	elsewhere e.g. attached to a SceneNode otherwise a crash
1227	is likely. Use clearScene if you are unsure (it clears SceneNode
1228	entries too.)
1229	@see
1230	SceneManager::clearScene
1231	*/
1232	virtual void removeAllBillboardSets(void);
1233
1234	/** Tells the SceneManager whether it should render the SceneNodes which
1235	make up the scene as well as the objects in the scene.
1236	@remarks
1237	This method is mainly for debugging purposes. If you set this to 'true',
1238	each node will be rendered as a set of 3 axes to allow you to easily see
1239	the orientation of the nodes.
1240	*/
1241	virtual void setDisplaySceneNodes(bool display);
1242
1243	/** Creates an animation which can be used to animate scene nodes.
1244	@remarks
1245	An animation is a collection of 'tracks' which over time change the position / orientation
1246	of Node objects. In this case, the animation will likely have tracks to modify the position
1247	/ orientation of SceneNode objects, e.g. to make objects move along a path.
1248	@par
1249	You don't need to use an Animation object to move objects around - you can do it yourself
1250	using the methods of the Node in your FrameListener class. However, when you need relatively
1251	complex scripted animation, this is the class to use since it will interpolate between
1252	keyframes for you and generally make the whole process easier to manage.
1253	@par
1254	A single animation can affect multiple Node objects (each AnimationTrack affects a single Node).
1255	In addition, through animation blending a single Node can be affected by multiple animations,
1256	athough this is more useful when performing skeletal animation (see Skeleton::createAnimation).
1257	@par
1258	Note that whilst it uses the same classes, the animations created here are kept separate from the
1259	skeletal animations of meshes (each Skeleton owns those animations).
1260	@param name The name of the animation, must be unique within this SceneManager.
1261	@param length The total length of the animation.
1262	*/
1263	virtual Animation* createAnimation(const String& name, Real length);
1264
1265	/** Looks up an Animation object previously created with createAnimation. */
1266	virtual Animation* getAnimation(const String& name) const;
1267
1268	/** Destroys an Animation.
1269	@remarks
1270	You should ensure that none of your code is referencing this animation objects since the
1271	memory will be freed.
1272	*/
1273	virtual void destroyAnimation(const String& name);
1274
1275	/** Removes all animations created using this SceneManager. */
1276	virtual void destroyAllAnimations(void);
1277
1278	/** Create an AnimationState object for managing application of animations.
1279	@remarks
1280	You can create Animation objects for animating SceneNode obejcts using the
1281	createAnimation method. However, in order to actually apply those animations
1282	you have to call methods on Node and Animation in a particular order (namely
1283	Node::resetToInitialState and Animation::apply). To make this easier and to
1284	help track the current time position of animations, the AnimationState object
1285	is provided. </p>
1286	So if you don't want to control animation application manually, call this method,
1287	update the returned object as you like every frame and let SceneManager apply
1288	the animation state for you.
1289	@par
1290	Remember, AnimationState objects are disabled by default at creation time.
1291	Turn them on when you want them using their setEnabled method.
1292	@par
1293	Note that any SceneNode affected by this automatic animation will have it's state
1294	reset to it's initial position before application of the animation. Unless specifically
1295	modified using Node::setInitialState the Node assumes it's initial state is at the
1296	origin. If you want the base state of the SceneNode to be elsewhere, make your changes
1297	to the node using the standard transform methods, then call setInitialState to
1298	'bake' this reference position into the node.
1299	@param animName The name of an animation created already with createAnimation.
1300	*/
1301	virtual AnimationState* createAnimationState(const String& animName);
1302
1303	/** Retrieves animation state as previously created using createAnimationState */
1304	virtual AnimationState* getAnimationState(const String& animName);
1305
1306	/** Destroys an AnimationState.
1307	@remarks
1308	You should ensure that none of your code is referencing this animation
1309	state object since the memory will be freed.
1310	*/
1311	virtual void destroyAnimationState(const String& name);
1312
1313	/** Removes all animation states created using this SceneManager. */
1314	virtual void destroyAllAnimationStates(void);
1315
1316	/** Manual rendering method, for advanced users only.
1317	@remarks
1318	This method allows you to send rendering commands through the pipeline on
1319	demand, bypassing OGRE's normal world processing. You should only use this if you
1320	really know what you're doing; OGRE does lots of things for you that you really should
1321	let it do. However, there are times where it may be useful to have this manual interface,
1322	for example overlaying something on top of the scene rendered by OGRE.
1323	@par
1324	Because this is an instant rendering method, timing is important. The best
1325	time to call it is from a RenderTargetListener event handler.
1326	@par
1327	Don't call this method a lot, it's designed for rare (1 or 2 times per frame) use.
1328	Calling it regularly per frame will cause frame rate drops!
1329	@param rend A RenderOperation object describing the rendering op
1330	@param pass The Pass to use for this render
1331	@param vp Pointer to the viewport to render to
1332	@param worldMatrix The transform to apply from object to world space
1333	@param viewMatrix The transform to apply from world to view space
1334	@param projMatrix The transform to apply from view to screen space
1335	@param doBeginEndFrame If true, beginFrame() and endFrame() are called,
1336	otherwise not. You should leave this as false if you are calling
1337	this within the main render loop.
1338	*/
1339	virtual void manualRender(RenderOperation* rend, Pass* pass, Viewport* vp,
1340	const Matrix4& worldMatrix, const Matrix4& viewMatrix, const Matrix4& projMatrix,
1341	bool doBeginEndFrame = false) ;
1342
1343	/** Registers a new RenderQueueListener which will be notified when render queues
1344	are processed.
1345	*/
1346	virtual void addRenderQueueListener(RenderQueueListener* newListener);
1347
1348	/** Removes a listener previously added with addRenderQueueListener. */
1349	virtual void removeRenderQueueListener(RenderQueueListener* delListener);
1350
1351	/** Adds an item to the 'special case' render queue list.
1352	@remarks
1353	Normally all render queues are rendered, in their usual sequence,
1354	only varying if a RenderQueueListener nominates for the queue to be
1355	repeated or skipped. This method allows you to add a render queue to
1356	a 'special case' list, which varies the behaviour. The effect of this
1357	list depends on the 'mode' in which this list is in, which might be
1358	to exclude these render queues, or to include them alone (excluding
1359	all other queues). This allows you to perform broad selective
1360	rendering without requiring a RenderQueueListener.
1361	@param qid The identifier of the queue which should be added to the
1362	special case list. Nothing happens if the queue is already in the list.
1363	*/
1364	virtual void addSpecialCaseRenderQueue(RenderQueueGroupID qid);
1365	/** Removes an item to the 'special case' render queue list.
1366	@see SceneManager::addSpecialCaseRenderQueue
1367	@param qid The identifier of the queue which should be removed from the
1368	special case list. Nothing happens if the queue is not in the list.
1369	*/
1370	virtual void removeSpecialCaseRenderQueue(RenderQueueGroupID qid);
1371	/** Clears the 'special case' render queue list.
1372	@see SceneManager::addSpecialCaseRenderQueue
1373	*/
1374	virtual void clearSpecialCaseRenderQueues(void);
1375	/** Sets the way the special case render queue list is processed.
1376	@see SceneManager::addSpecialCaseRenderQueue
1377	@param mode The mode of processing
1378	*/
1379	virtual void setSpecialCaseRenderQueueMode(SpecialCaseRenderQueueMode mode);
1380	/** Gets the way the special case render queue list is processed. */
1381	virtual SpecialCaseRenderQueueMode getSpecialCaseRenderQueueMode(void);
1382	/** Returns whether or not the named queue will be rendered based on the
1383	current 'special case' render queue list and mode.
1384	@see SceneManager::addSpecialCaseRenderQueue
1385	@param qid The identifier of the queue which should be tested
1386	@returns true if the queue will be rendered, false otherwise
1387	*/
1388	virtual bool isRenderQueueToBeProcessed(RenderQueueGroupID qid);
1389
1390	/** Sets the render queue that the world geometry (if any) this SceneManager
1391	renders will be associated with.
1392	@remarks
1393	SceneManagers which provide 'world geometry' should place it in a
1394	specialised render queue in order to make it possible to enable /
1395	disable it easily using the addSpecialCaseRenderQueue method. Even
1396	if the SceneManager does not use the render queues to render the
1397	world geometry, it should still pick a queue to represent it's manual
1398	rendering, and check isRenderQueueToBeProcessed before rendering.
1399	@note
1400	Setting this may not affect the actual ordering of rendering the
1401	world geometry, if the world geometry is being rendered manually
1402	by the SceneManager. If the SceneManager feeds world geometry into
1403	the queues, however, the ordering will be affected.
1404	*/
1405	virtual void setWorldGeometryRenderQueue(RenderQueueGroupID qid);
1406	/** Gets the render queue that the world geometry (if any) this SceneManager
1407	renders will be associated with.
1408	@remarks
1409	SceneManagers which provide 'world geometry' should place it in a
1410	specialised render queue in order to make it possible to enable /
1411	disable it easily using the addSpecialCaseRenderQueue method. Even
1412	if the SceneManager does not use the render queues to render the
1413	world geometry, it should still pick a queue to represent it's manual
1414	rendering, and check isRenderQueueToBeProcessed before rendering.
1415	*/
1416	virtual RenderQueueGroupID getWorldGeometryRenderQueue(void);
1417
1418	/** Allows all bounding boxes of scene nodes to be displayed. */
1419	virtual void showBoundingBoxes(bool bShow);
1420
1421	/** Returns if all bounding boxes of scene nodes are to be displayed */
1422	virtual bool getShowBoundingBoxes() const;
1423
1424	/** Internal method for notifying the manager that a SceneNode is autotracking. */
1425	virtual void _notifyAutotrackingSceneNode(SceneNode* node, bool autoTrack);
1426
1427
1428	/** Creates an AxisAlignedBoxSceneQuery for this scene manager.
1429	@remarks
1430	This method creates a new instance of a query object for this scene manager,
1431	for an axis aligned box region. See SceneQuery and AxisAlignedBoxSceneQuery
1432	for full details.
1433	@par
1434	The instance returned from this method must be destroyed by calling
1435	SceneManager::destroyQuery when it is no longer required.
1436	@param box Details of the box which describes the region for this query.
1437	@param mask The query mask to apply to this query; can be used to filter out
1438	certain objects; see SceneQuery for details.
1439	*/
1440	virtual AxisAlignedBoxSceneQuery*
1441	createAABBQuery(const AxisAlignedBox& box, unsigned long mask = 0xFFFFFFFF);
1442	/** Creates a SphereSceneQuery for this scene manager.
1443	@remarks
1444	This method creates a new instance of a query object for this scene manager,
1445	for a spherical region. See SceneQuery and SphereSceneQuery
1446	for full details.
1447	@par
1448	The instance returned from this method must be destroyed by calling
1449	SceneManager::destroyQuery when it is no longer required.
1450	@param sphere Details of the sphere which describes the region for this query.
1451	@param mask The query mask to apply to this query; can be used to filter out
1452	certain objects; see SceneQuery for details.
1453	*/
1454	virtual SphereSceneQuery*
1455	createSphereQuery(const Sphere& sphere, unsigned long mask = 0xFFFFFFFF);
1456	/** Creates a PlaneBoundedVolumeListSceneQuery for this scene manager.
1457	@remarks
1458	This method creates a new instance of a query object for this scene manager,
1459	for a region enclosed by a set of planes (normals pointing inwards).
1460	See SceneQuery and PlaneBoundedVolumeListSceneQuery for full details.
1461	@par
1462	The instance returned from this method must be destroyed by calling
1463	SceneManager::destroyQuery when it is no longer required.
1464	@param volumes Details of the volumes which describe the region for this query.
1465	@param mask The query mask to apply to this query; can be used to filter out
1466	certain objects; see SceneQuery for details.
1467	*/
1468	virtual PlaneBoundedVolumeListSceneQuery*
1469	createPlaneBoundedVolumeQuery(const PlaneBoundedVolumeList& volumes, unsigned long mask = 0xFFFFFFFF);
1470
1471
1472	/** Creates a RaySceneQuery for this scene manager.
1473	@remarks
1474	This method creates a new instance of a query object for this scene manager,
1475	looking for objects which fall along a ray. See SceneQuery and RaySceneQuery
1476	for full details.
1477	@par
1478	The instance returned from this method must be destroyed by calling
1479	SceneManager::destroyQuery when it is no longer required.
1480	@param ray Details of the ray which describes the region for this query.
1481	@param mask The query mask to apply to this query; can be used to filter out
1482	certain objects; see SceneQuery for details.
1483	*/
1484	virtual RaySceneQuery*
1485	createRayQuery(const Ray& ray, unsigned long mask = 0xFFFFFFFF);
1486	//PyramidSceneQuery* createPyramidQuery(const Pyramid& p, unsigned long mask = 0xFFFFFFFF);
1487	/** Creates an IntersectionSceneQuery for this scene manager.
1488	@remarks
1489	This method creates a new instance of a query object for locating
1490	intersecting objects. See SceneQuery and IntersectionSceneQuery
1491	for full details.
1492	@par
1493	The instance returned from this method must be destroyed by calling
1494	SceneManager::destroyQuery when it is no longer required.
1495	@param mask The query mask to apply to this query; can be used to filter out
1496	certain objects; see SceneQuery for details.
1497	*/
1498	virtual IntersectionSceneQuery*
1499	createIntersectionQuery(unsigned long mask = 0xFFFFFFFF);
1500
1501	/** Destroys a scene query of any type. */
1502	virtual void destroyQuery(SceneQuery* query);
1503
1504	typedef MapIterator<SceneLightList> LightIterator;
1505	typedef MapIterator<EntityList> EntityIterator;
1506	typedef MapIterator<CameraList> CameraIterator;
1507	typedef MapIterator<BillboardSetList> BillboardSetIterator;
1508	typedef MapIterator<AnimationList> AnimationIterator;
1509
1510	/** Returns a specialised MapIterator over all lights in the scene. */
1511	LightIterator getLightIterator(void) {
1512	return LightIterator(mLights.begin(), mLights.end());
1513	}
1514	/** Returns a specialised MapIterator over all entities in the scene. */
1515	EntityIterator getEntityIterator(void) {
1516	return EntityIterator(mEntities.begin(), mEntities.end());
1517	}
1518	/** Returns a specialised MapIterator over all cameras in the scene. */
1519	CameraIterator getCameraIterator(void) {
1520	return CameraIterator(mCameras.begin(), mCameras.end());
1521	}
1522	/** Returns a specialised MapIterator over all BillboardSets in the scene. */
1523	BillboardSetIterator getBillboardSetIterator(void) {
1524	return BillboardSetIterator(mBillboardSets.begin(), mBillboardSets.end());
1525	}
1526	/** Returns a specialised MapIterator over all animations in the scene. */
1527	AnimationIterator getAnimationIterator(void) {
1528	return AnimationIterator(mAnimationsList.begin(), mAnimationsList.end());
1529	}
1530	/** Returns a specialised MapIterator over all animation states in the scene. */
1531	AnimationStateIterator getAnimationStateIterator(void) {
1532	return AnimationStateIterator(mAnimationStates.begin(), mAnimationStates.end());
1533	}
1534
1535	/** Sets the general shadow technique to be used in this scene.
1536	@remarks
1537	There are multiple ways to generate shadows in a scene, and each has
1538	strengths and weaknesses.
1539	<ul><li>Stencil-based approaches can be used to
1540	draw very long, extreme shadows without loss of precision and the 'additive'
1541	version can correctly show the shadowing of complex effects like bump mapping
1542	because they physically exclude the light from those areas. However, the edges
1543	are very sharp and stencils cannot handle transparency, and they involve a
1544	fair amount of CPU work in order to calculate the shadow volumes, especially
1545	when animated objects are involved.</li>
1546	<li>Texture-based approaches are good for handling transparency (they can, for
1547	example, correctly shadow a mesh which uses alpha to represent holes), and they
1548	require little CPU overhead, and can happily shadow geometry which is deformed
1549	by a vertex program, unlike stencil shadows. However, they have a fixed precision
1550	which can introduce 'jaggies' at long range and have fillrate issues of their own.</li>
1551	</ul>
1552	@par
1553	We support 2 kinds of stencil shadows, and 2 kinds of texture-based shadows, and one
1554	simple decal approach. The 2 stencil approaches differ in the amount of multipass work
1555	that is required - the modulative approach simply 'darkens' areas in shadow after the
1556	main render, which is the least expensive, whilst the additive approach has to perform
1557	a render per light and adds the cumulative effect, whcih is more expensive but more
1558	accurate. The texture based shadows both work in roughly the same way, the only difference is
1559	that the shadowmap approach is slightly more accurate, but requires a more recent
1560	graphics card.
1561	@par
1562	Note that because mixing many shadow techniques can cause problems, only one technique
1563	is supported at once. Also, you should call this method at the start of the
1564	scene setup.
1565	@param technique The shadowing technique to use for the scene.
1566	*/
1567	virtual void setShadowTechnique(ShadowTechnique technique);
1568
1569	/** Gets the current shadow technique. */
1570	virtual ShadowTechnique getShadowTechnique(void) const { return mShadowTechnique; }
1571
1572	/** Enables / disables the rendering of debug information for shadows. */
1573	virtual void setShowDebugShadows(bool debug) { mDebugShadows = debug; }
1574	/** Are debug shadows shown? */
1575	virtual bool getShowDebugShadows(void ) const { return mDebugShadows; }
1576
1577	/** Set the colour used to modulate areas in shadow.
1578	@remarks This is only applicable for shadow techniques which involve
1579	darkening the area in shadow, as opposed to masking out the light.
1580	This colour provided is used as a modulative value to darken the
1581	areas.
1582	*/
1583	virtual void setShadowColour(const ColourValue& colour);
1584	/** Get the colour used to modulate areas in shadow.
1585	@remarks This is only applicable for shadow techniques which involve
1586	darkening the area in shadow, as opposed to masking out the light.
1587	This colour provided is used as a modulative value to darken the
1588	areas.
1589	*/
1590	virtual const ColourValue& getShadowColour(void) const;
1591	/** Sets the distance a shadow volume is extruded for a directional light.
1592	@remarks
1593	Although directional lights are essentially infinite, there are many
1594	reasons to limit the shadow extrusion distance to a finite number,
1595	not least of which is compatibility with older cards (which do not
1596	support infinite positions), and shadow caster elimination.
1597	@par
1598	The default value is 10,000 world units. This does not apply to
1599	point lights or spotlights, since they extrude up to their
1600	attenuation range.
1601	*/
1602	virtual void setShadowDirectionalLightExtrusionDistance(Real dist);
1603	/** Gets the distance a shadow volume is extruded for a directional light.
1604	*/
1605	virtual Real getShadowDirectionalLightExtrusionDistance(void) const;
1606	/** Sets the maximum distance away from the camera that shadows
1607	will be visible.
1608	@remarks
1609	Shadow techniques can be expensive, therefore it is a good idea
1610	to limit them to being rendered close to the camera if possible,
1611	and to skip the expense of rendering shadows for distance objects.
1612	This method allows you to set the distance at which shadows will no
1613	longer be rendered.
1614	@note
1615	Each shadow technique can interpret this subtely differently.
1616	For example, one technique may use this to eliminate casters,
1617	another might use it to attenuate the shadows themselves.
1618	You should tweak this value to suit your chosen shadow technique
1619	and scene setup.
1620	*/
1621	virtual void setShadowFarDistance(Real distance);
1622	/** Gets the maximum distance away from the camera that shadows
1623	will be visible.
1624	*/
1625	virtual Real getShadowFarDistance(void) const
1626	{ return mShadowFarDist; }
1627
1628	/** Sets the maximum size of the index buffer used to render shadow
1629	primitives.
1630	@remarks
1631	This method allows you to tweak the size of the index buffer used
1632	to render shadow primitives (including stencil shadow volumes). The
1633	default size is 51,200 entries, which is 100k of GPU memory, or
1634	enough to render approximately 17,000 triangles. You can reduce this
1635	as long as you do not have any models / world geometry chunks which
1636	could require more than the amount you set.
1637	@par
1638	The maximum number of triangles required to render a single shadow
1639	volume (including light and dark caps when needed) will be 3x the
1640	number of edges on the light silhouette, plus the number of
1641	light-facing triangles. On average, half the
1642	triangles will be facing toward the light, but the number of
1643	triangles in the silhouette entirely depends on the mesh -
1644	angular meshes will have a higher silhouette tris/mesh tris
1645	ratio than a smooth mesh. You can estimate the requirements for
1646	your particular mesh by rendering it alone in a scene with shadows
1647	enabled and a single light - rotate it or the light and make a note
1648	of how high the triangle count goes (remembering to subtract the
1649	mesh triangle count)
1650	@param size The number of indexes; divide this by 3 to determine the
1651	number of triangles.
1652	*/
1653	virtual void setShadowIndexBufferSize(size_t size);
1654	/// Get the size of the shadow index buffer
1655	virtual size_t getShadowIndexBufferSize(void) const
1656	{ return mShadowIndexBufferSize; }
1657	/** Set the size of the texture used for texture-based shadows.
1658	@remarks
1659	The larger the shadow texture, the better the detail on
1660	texture based shadows, but obviously this takes more memory.
1661	The default size is 512. Sizes must be a power of 2.
1662	*/
1663	virtual void setShadowTextureSize(unsigned short size);
1664	/// Get the size of the texture used for texture based shadows
1665	unsigned short getShadowTextureSize(void) const {return mShadowTextureSize; }
1666	/** Set the pixel format of the textures used for texture-based shadows.
1667	@remarks
1668	By default, a colour texture is used (PF_X8R8G8B8) for texture shadows,
1669	but if you want to use more advanced texture shadow types you can
1670	alter this. If you do, you will have to also call
1671	setShadowTextureCasterMaterial and setShadowTextureReceiverMaterial
1672	to provide shader-based materials to use these customised shadow
1673	texture formats.
1674	*/
1675	virtual void setShadowTexturePixelFormat(PixelFormat fmt);
1676	/// Get the format of the textures used for texture based shadows
1677	PixelFormat getShadowTexturePixelFormat(void) const {return mShadowTextureFormat; }
1678	/** Set the number of textures allocated for texture-based shadows.
1679	@remarks
1680	The default number of textures assigned to deal with texture based
1681	shadows is 1; however this means you can only have one light casting
1682	shadows at the same time. You can increase this number in order to
1683	make this more flexible, but be aware of the texture memory it will use.
1684	*/
1685	virtual void setShadowTextureCount(unsigned short count);
1686	/// Get the number of the textures allocated for texture based shadows
1687	unsigned short getShadowTextureCount(void) const {return mShadowTextureCount; }
1688	/** Sets the size and count of textures used in texture-based shadows.
1689	@remarks
1690	@see setShadowTextureSize and setShadowTextureCount for details, this
1691	method just allows you to change both at once, which can save on
1692	reallocation if the textures have already been created.
1693	*/
1694	virtual void setShadowTextureSettings(unsigned short size, unsigned short count,
1695	PixelFormat fmt = PF_X8R8G8B8);
1696	/** Sets the proportional distance which a texture shadow which is generated from a
1697	directional light will be offset into the camera view to make best use of texture space.
1698	@remarks
1699	When generating a shadow texture from a directional light, an approximation is used
1700	since it is not possible to render the entire scene to one texture.
1701	The texture is projected onto an area centred on the camera, and is
1702	the shadow far distance * 2 in length (it is square). This wastes
1703	a lot of texture space outside the frustum though, so this offset allows
1704	you to move the texture in front of the camera more. However, be aware
1705	that this can cause a little shadow 'jittering' during rotation, and
1706	that if you move it too far then you'll start to get artefacts close
1707	to the camera. The value is represented as a proportion of the shadow
1708	far distance, and the default is 0.6.
1709	*/
1710	virtual void setShadowDirLightTextureOffset(Real offset) { mShadowTextureOffset = offset;}
1711	/** Sets the proportional distance at which texture shadows begin to fade out.
1712	@remarks
1713	To hide the edges where texture shadows end (in directional lights)
1714	Ogre will fade out the shadow in the distance. This value is a proportional
1715	distance of the entire shadow visibility distance at which the shadow
1716	begins to fade out. The default is 0.7
1717	*/
1718	virtual void setShadowTextureFadeStart(Real fadeStart)
1719	{ mShadowTextureFadeStart = fadeStart; }
1720	/** Sets the proportional distance at which texture shadows finish to fading out.
1721	@remarks
1722	To hide the edges where texture shadows end (in directional lights)
1723	Ogre will fade out the shadow in the distance. This value is a proportional
1724	distance of the entire shadow visibility distance at which the shadow
1725	is completely invisible. The default is 0.9.
1726	*/
1727	virtual void setShadowTextureFadeEnd(Real fadeEnd)
1728	{ mShadowTextureFadeEnd = fadeEnd; }
1729
1730	/** Sets whether or not texture shadows should attempt to self-shadow.
1731	@remarks
1732	The default implementation of texture shadows uses a fixed-function
1733	colour texture projection approach for maximum compatibility, and
1734	as such cannot support self-shadowing. However, if you decide to
1735	implement a more complex shadowing technique using the
1736	setShadowTextureCasterMaterial and setShadowTextureReceiverMaterial
1737	there is a possibility you may be able to support
1738	self-shadowing (e.g by implementing a shader-based shadow map). In
1739	this case you might want to enable this option.
1740	@param selfShadow Whether to attempt self-shadowing with texture shadows
1741	*/
1742	virtual void setShadowTextureSelfShadow(bool selfShadow)
1743	{ mShadowTextureSelfShadow = selfShadow; }
1744	/// Gets whether or not texture shadows attempt to self-shadow.
1745	virtual bool getShadowTextureSelfShadow(void) const
1746	{ return mShadowTextureSelfShadow; }
1747	/** Sets the default material to use for rendering shadow casters.
1748	@remarks
1749	By default shadow casters are rendered into the shadow texture using
1750	an automatically generated fixed-function pass. This allows basic
1751	projective texture shadows, but it's possible to use more advanced
1752	shadow techniques by overriding the caster and receiver materials, for
1753	example providing vertex and fragment programs to implement shadow
1754	maps.
1755	@par
1756	You can rely on the ambient light in the scene being set to the
1757	requested texture shadow colour, if that's useful.
1758	@note
1759	Individual objects may also override the vertex program in
1760	your default material if their materials include
1761	shadow_caster_vertex_program_ref shadow_receiver_vertex_program_ref
1762	entries, so if you use both make sure they are compatible.
1763	@note
1764	Only a single pass is allowed in your material, although multiple
1765	techniques may be used for hardware fallback.
1766	*/
1767	virtual void setShadowTextureCasterMaterial(const String& name);
1768	/** Sets the default material to use for rendering shadow receivers.
1769	@remarks
1770	By default shadow receivers are rendered as a post-pass using basic
1771	modulation. This allows basic projective texture shadows, but it's
1772	possible to use more advanced shadow techniques by overriding the
1773	caster and receiver materials, for example providing vertex and
1774	fragment programs to implement shadow maps.
1775	@par
1776	You can rely on texture unit 0 containing the shadow texture, and
1777	for the unit to be set to use projective texturing from the light
1778	(only useful if you're using fixed-function, which is unlikely;
1779	otherwise you should rely on the texture_viewproj_matrix auto binding)
1780	@note
1781	Individual objects may also override the vertex program in
1782	your default material if their materials include
1783	shadow_caster_vertex_program_ref shadow_receiver_vertex_program_ref
1784	entries, so if you use both make sure they are compatible.
1785	@note
1786	Only a single pass is allowed in your material, although multiple
1787	techniques may be used for hardware fallback.
1788	*/
1789	virtual void setShadowTextureReceiverMaterial(const String& name);
1790
1791	/** Sets whether we should use an inifinite camera far plane
1792	when rendering stencil shadows.
1793	@remarks
1794	Stencil shadow coherency is very reliant on the shadow volume
1795	not being clipped by the far plane. If this clipping happens, you
1796	get a kind of 'negative' shadow effect. The best way to achieve
1797	coherency is to move the far plane of the camera out to infinity,
1798	thus preventing the far plane from clipping the shadow volumes.
1799	When combined with vertex program extrusion of the volume to
1800	infinity, which Ogre does when available, this results in very
1801	robust shadow volumes. For this reason, when you enable stencil
1802	shadows, Ogre automatically changes your camera settings to
1803	project to infinity if the card supports it. You can disable this
1804	behaviour if you like by calling this method; although you can
1805	never enable infinite projection if the card does not support it.
1806	@par
1807	If you disable infinite projection, or it is not available,
1808	you need to be far more careful with your light attenuation /
1809	directional light extrusion distances to avoid clipping artefacts
1810	at the far plane.
1811	@note
1812	Recent cards will generally support infinite far plane projection.
1813	However, we have found some cases where they do not, especially
1814	on Direct3D. There is no standard capability we can check to
1815	validate this, so we use some heuristics based on experience:
1816	<UL>
1817	<LI>OpenGL always seems to support it no matter what the card</LI>
1818	<LI>Direct3D on non-vertex program capable systems (including
1819	vertex program capable cards on Direct3D7) does not
1820	support it</LI>
1821	<LI>Direct3D on GeForce3 and GeForce4 Ti does not seem to support
1822	infinite projection<LI>
1823	</UL>
1824	Therefore in the RenderSystem implementation, we may veto the use
1825	of an infinite far plane based on these heuristics.
1826	*/
1827	virtual void setShadowUseInfiniteFarPlane(bool enable) {
1828	mShadowUseInfiniteFarPlane = enable; }
1829
1830	/** Creates a StaticGeometry instance suitable for use with this
1831	SceneManager.
1832	@remarks
1833	StaticGeometry is a way of batching up geometry into a more
1834	efficient form at the expense of being able to move it. Please
1835	read the StaticGeometry class documentation for full information.
1836	@param name The name to give the new object
1837	@returns The new StaticGeometry instance
1838	*/
1839	virtual StaticGeometry* createStaticGeometry(const String& name);
1840	/** Retrieve a previously created StaticGeometry instance. */
1841	virtual StaticGeometry* getStaticGeometry(const String& name) const;
1842	/** Remove & destroy a StaticGeometry instance. */
1843	virtual void removeStaticGeometry(StaticGeometry* geom);
1844	/** Remove & destroy a StaticGeometry instance. */
1845	virtual void removeStaticGeometry(const String& name);
1846	/** Remove & destroy all StaticGeometry instances. */
1847	virtual void removeAllStaticGeometry(void);
1848
1849
1850	};
1851
1852	/** Default implementation of IntersectionSceneQuery. */
1853	class _OgreExport DefaultIntersectionSceneQuery :
1854	public IntersectionSceneQuery
1855	{
1856	public:
1857	DefaultIntersectionSceneQuery(SceneManager* creator);
1858	~DefaultIntersectionSceneQuery();
1859
1860	/** See IntersectionSceneQuery. */
1861	void execute(IntersectionSceneQueryListener* listener);
1862	};
1863
1864	/** Default implementation of RaySceneQuery. */
1865	class _OgreExport DefaultRaySceneQuery : public RaySceneQuery
1866	{
1867	public:
1868	DefaultRaySceneQuery(SceneManager* creator);
1869	~DefaultRaySceneQuery();
1870
1871	/** See RayScenQuery. */
1872	void execute(RaySceneQueryListener* listener);
1873	};
1874	/** Default implementation of SphereSceneQuery. */
1875	class _OgreExport DefaultSphereSceneQuery : public SphereSceneQuery
1876	{
1877	public:
1878	DefaultSphereSceneQuery(SceneManager* creator);
1879	~DefaultSphereSceneQuery();
1880
1881	/** See SceneQuery. */
1882	void execute(SceneQueryListener* listener);
1883	};
1884	/** Default implementation of PlaneBoundedVolumeListSceneQuery. */
1885	class _OgreExport DefaultPlaneBoundedVolumeListSceneQuery : public PlaneBoundedVolumeListSceneQuery
1886	{
1887	public:
1888	DefaultPlaneBoundedVolumeListSceneQuery(SceneManager* creator);
1889	~DefaultPlaneBoundedVolumeListSceneQuery();
1890
1891	/** See SceneQuery. */
1892	void execute(SceneQueryListener* listener);
1893	};
1894	/** Default implementation of AxisAlignedBoxSceneQuery. */
1895	class _OgreExport DefaultAxisAlignedBoxSceneQuery : public AxisAlignedBoxSceneQuery
1896	{
1897	public:
1898	DefaultAxisAlignedBoxSceneQuery(SceneManager* creator);
1899	~DefaultAxisAlignedBoxSceneQuery();
1900
1901	/** See RayScenQuery. */
1902	void execute(SceneQueryListener* listener);
1903	};
1904
1905
1906
1907	} // Namespace
1908
1909
1910
1911	#endif

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

Context Navigation

source: trunk/VUT/work/ogre_changes/OgreMain/include/OgreSceneManager.h @ 316

Download in other formats: