Context Navigation

OgreFrustum.h @ 692

Revision 692, 26.2 KB checked in by mattausch, 19 years ago (diff)
adding ogre 1.2 and dependencies

Line
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-2005 The OGRE Team
8	Also see acknowledgements in Readme.html
9
10	This program is free software; you can redistribute it and/or modify it under
11	the terms of the GNU Lesser General Public License as published by the Free Software
12	Foundation; either version 2 of the License, or (at your option) any later
13	version.
14
15	This program is distributed in the hope that it will be useful, but WITHOUT
16	ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
17	FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
18
19	You should have received a copy of the GNU Lesser General Public License along with
20	this program; if not, write to the Free Software Foundation, Inc., 59 Temple
21	Place - Suite 330, Boston, MA 02111-1307, USA, or go to
22	http://www.gnu.org/copyleft/lesser.txt.
23	-----------------------------------------------------------------------------
24	*/
25	#ifndef __Frustum_H__
26	#define __Frustum_H__
27
28	#include "OgrePrerequisites.h"
29	#include "OgreMovableObject.h"
30	#include "OgreRenderable.h"
31	#include "OgreAxisAlignedBox.h"
32	#include "OgreVertexIndexData.h"
33	#include "OgreMovablePlane.h"
34
35	namespace Ogre
36	{
37	/** Specifies perspective (realistic) or orthographic (architectural) projection.
38	*/
39	enum ProjectionType
40	{
41	PT_ORTHOGRAPHIC,
42	PT_PERSPECTIVE
43	};
44
45	/** Worldspace clipping planes.
46	*/
47	enum FrustumPlane
48	{
49	FRUSTUM_PLANE_NEAR = 0,
50	FRUSTUM_PLANE_FAR = 1,
51	FRUSTUM_PLANE_LEFT = 2,
52	FRUSTUM_PLANE_RIGHT = 3,
53	FRUSTUM_PLANE_TOP = 4,
54	FRUSTUM_PLANE_BOTTOM = 5
55	};
56
57	/** A frustum represents a pyramid, capped at the near and far end which is
58	used to represent either a visible area or a projection area. Can be used
59	for a number of applications.
60	*/
61	class _OgreExport Frustum : public MovableObject, public Renderable
62	{
63	protected:
64	/// Orthographic or perspective?
65	ProjectionType mProjType;
66
67	/// y-direction field-of-view (default 45)
68	Radian mFOVy;
69	/// Far clip distance - default 10000
70	Real mFarDist;
71	/// Near clip distance - default 100
72	Real mNearDist;
73	/// x/y viewport ratio - default 1.3333
74	Real mAspect;
75	/// Off-axis frustum center offset - default (0.0, 0.0)
76	Vector2 mFrustumOffset;
77	/// Focal length of frustum (for stereo rendering, defaults to 1.0)
78	Real mFocalLength;
79
80	/// The 6 main clipping planes
81	mutable Plane mFrustumPlanes[6];
82
83	/// Stored versions of parent orientation / position
84	mutable Quaternion mLastParentOrientation;
85	mutable Vector3 mLastParentPosition;
86
87	/// Pre-calced projection matrix for the specific render system
88	mutable Matrix4 mProjMatrixRS;
89	/// Pre-calced standard projection matrix but with render system depth range
90	mutable Matrix4 mProjMatrixRSDepth;
91	/// Pre-calced standard projection matrix
92	mutable Matrix4 mProjMatrix;
93	/// Pre-calced view matrix
94	mutable Matrix4 mViewMatrix;
95	/// Something's changed in the frustrum shape?
96	mutable bool mRecalcFrustum;
97	/// Something re the view pos has changed
98	mutable bool mRecalcView;
99	/// Something re the frustum planes has changed
100	mutable bool mRecalcFrustumPlanes;
101	/// Something re the world space corners has changed
102	mutable bool mRecalcWorldSpaceCorners;
103	/// Something re the vertex data has changed
104	mutable bool mRecalcVertexData;
105	/// Are we using a custom view matrix?
106	bool mCustomViewMatrix;
107	/// Are we using a custom projection matrix?
108	bool mCustomProjMatrix;
109
110
111	// Internal functions for calcs
112	virtual void calcProjectionParameters(Real& left, Real& right, Real& bottom, Real& top) const;
113	/// Update frustum if out of date
114	virtual void updateFrustum(void) const;
115	/// Update view if out of date
116	virtual void updateView(void) const;
117	/// Implementation of updateFrustum (called if out of date)
118	virtual void updateFrustumImpl(void) const;
119	/// Implementation of updateView (called if out of date)
120	virtual void updateViewImpl(void) const;
121	virtual void updateFrustumPlanes(void) const;
122	/// Implementation of updateFrustumPlanes (called if out of date)
123	virtual void updateFrustumPlanesImpl(void) const;
124	virtual void updateWorldSpaceCorners(void) const;
125	/// Implementation of updateWorldSpaceCorners (called if out of date)
126	virtual void updateWorldSpaceCornersImpl(void) const;
127	virtual void updateVertexData(void) const;
128	virtual bool isViewOutOfDate(void) const;
129	virtual bool isFrustumOutOfDate(void) const;
130	/// Signal to update frustum information.
131	virtual void invalidateFrustum(void) const;
132	/// Signal to update view information.
133	virtual void invalidateView(void) const;
134
135	/// Shared class-level name for Movable type
136	static String msMovableType;
137
138	mutable AxisAlignedBox mBoundingBox;
139	mutable VertexData mVertexData;
140
141	MaterialPtr mMaterial;
142	mutable Vector3 mWorldSpaceCorners[8];
143
144	/// Is this frustum to act as a reflection of itself?
145	bool mReflect;
146	/// Derived reflection matrix
147	mutable Matrix4 mReflectMatrix;
148	/// Fixed reflection plane
149	mutable Plane mReflectPlane;
150	/// Pointer to a reflection plane (automatically updated)
151	const MovablePlane* mLinkedReflectPlane;
152	/// Record of the last world-space reflection plane info used
153	mutable Plane mLastLinkedReflectionPlane;
154
155	/// Is this frustum using an oblique depth projection?
156	bool mObliqueDepthProjection;
157	/// Fixed oblique projection plane
158	mutable Plane mObliqueProjPlane;
159	/// Pointer to oblique projection plane (automatically updated)
160	const MovablePlane* mLinkedObliqueProjPlane;
161	/// Record of the last world-space oblique depth projection plane info used
162	mutable Plane mLastLinkedObliqueProjPlane;
163
164
165	/** Get the derived position of this frustum. */
166	virtual const Vector3& getPositionForViewUpdate(void) const;
167	/** Get the derived orientation of this frustum. */
168	virtual const Quaternion& getOrientationForViewUpdate(void) const;
169
170
171	public:
172
173	Frustum();
174	virtual ~Frustum();
175	/** Sets the Y-dimension Field Of View (FOV) of the frustum.
176	@remarks
177	Field Of View (FOV) is the angle made between the frustum's position, and the edges
178	of the 'screen' onto which the scene is projected. High values (90+ degrees) result in a wide-angle,
179	fish-eye kind of view, low values (30- degrees) in a stretched, telescopic kind of view. Typical values
180	are between 45 and 60 degrees.
181	@par
182	This value represents the VERTICAL field-of-view. The horizontal field of view is calculated from
183	this depending on the dimensions of the viewport (they will only be the same if the viewport is square).
184	@note
185	Setting the FOV overrides the value supplied for frustum::setNearClipPlane.
186	*/
187	virtual void setFOVy(const Radian& fovy);
188	#ifndef OGRE_FORCE_ANGLE_TYPES
189	inline void setFOVy(Real fovy) {
190	setFOVy ( Angle(fovy) );
191	}
192	#endif//OGRE_FORCE_ANGLE_TYPES
193
194	/** Retrieves the frustums Y-dimension Field Of View (FOV).
195	*/
196	virtual const Radian& getFOVy(void) const;
197
198	/** Sets the position of the near clipping plane.
199	@remarks
200	The position of the near clipping plane is the distance from the frustums position to the screen
201	on which the world is projected. The near plane distance, combined with the field-of-view and the
202	aspect ratio, determines the size of the viewport through which the world is viewed (in world
203	co-ordinates). Note that this world viewport is different to a screen viewport, which has it's
204	dimensions expressed in pixels. The frustums viewport should have the same aspect ratio as the
205	screen viewport it renders into to avoid distortion.
206	@param
207	near The distance to the near clipping plane from the frustum in world coordinates.
208	*/
209	virtual void setNearClipDistance(Real nearDist);
210
211	/** Sets the position of the near clipping plane.
212	*/
213	virtual Real getNearClipDistance(void) const;
214
215	/** Sets the distance to the far clipping plane.
216	@remarks
217	The view frustrum is a pyramid created from the frustum position and the edges of the viewport.
218	This method sets the distance for the far end of that pyramid.
219	Different applications need different values: e.g. a flight sim
220	needs a much further far clipping plane than a first-person
221	shooter. An important point here is that the larger the ratio
222	between near and far clipping planes, the lower the accuracy of
223	the Z-buffer used to depth-cue pixels. This is because the
224	Z-range is limited to the size of the Z buffer (16 or 32-bit)
225	and the max values must be spread over the gap between near and
226	far clip planes. As it happens, you can affect the accuracy far
227	more by altering the near distance rather than the far distance,
228	but keep this in mind.
229	@param
230	far The distance to the far clipping plane from the frustum in
231	world coordinates.If you specify 0, this means an infinite view
232	distance which is useful especially when projecting shadows; but
233	be careful not to use a near distance too close.
234	*/
235	virtual void setFarClipDistance(Real farDist);
236
237	/** Retrieves the distance from the frustum to the far clipping plane.
238	*/
239	virtual Real getFarClipDistance(void) const;
240
241	/** Sets the aspect ratio for the frustum viewport.
242	@remarks
243	The ratio between the x and y dimensions of the rectangular area visible through the frustum
244	is known as aspect ratio: aspect = width / height .
245	@par
246	The default for most fullscreen windows is 1.3333 - this is also assumed by Ogre unless you
247	use this method to state otherwise.
248	*/
249	virtual void setAspectRatio(Real ratio);
250
251	/** Retreives the current aspect ratio.
252	*/
253	virtual Real getAspectRatio(void) const;
254
255	/** Sets frustum offsets, used in stereo rendering.
256	@remarks
257	You can set both horizontal and vertical plane offsets of "eye"; in
258	stereo rendering frustum is moved in horizontal plane. To be able to
259	render from two "eyes" you'll need two cameras rendering on two
260	RenderTargets.
261	@par
262	The frustum offsets is in world coordinates, and default to (0, 0) - no offsets.
263	@param
264	offset The horizontal and vertical plane offsets.
265	*/
266	virtual void setFrustumOffset(const Vector2& offset);
267
268	/** Sets frustum offsets, used in stereo rendering.
269	@remarks
270	You can set both horizontal and vertical plane offsets of "eye"; in
271	stereo rendering frustum is moved in horizontal plane. To be able to
272	render from two "eyes" you'll need two cameras rendering on two
273	RenderTargets.
274	@par
275	The frustum offsets is in world coordinates, and default to (0, 0) - no offsets.
276	@param
277	horizontal The horizontal plane offset.
278	@param
279	vertical The vertical plane offset.
280	*/
281	virtual void setFrustumOffset(Real horizontal = 0.0, Real vertical = 0.0);
282
283	/** Retreives the frustum offsets.
284	*/
285	virtual const Vector2& getFrustumOffset() const;
286
287	/** Sets frustum focal length (used in stereo rendering).
288	@param
289	focalLength The distance to the focal plane from the frustum in world coordinates.
290	*/
291	virtual void setFocalLength(Real focalLength = 1.0);
292
293	/** Returns focal length of frustum.
294	*/
295	virtual Real getFocalLength() const;
296
297	/** Gets the projection matrix for this frustum adjusted for the current
298	rendersystem specifics (may be right or left-handed, depth range
299	may vary).
300	@remarks
301	This method retrieves the rendering-API dependent version of the projection
302	matrix. If you want a 'typical' projection matrix then use
303	getProjectionMatrix.
304
305	*/
306	virtual const Matrix4& getProjectionMatrixRS(void) const;
307	/** Gets the depth-adjusted projection matrix for the current rendersystem,
308	but one which still conforms to right-hand rules.
309	@remarks
310	This differs from the rendering-API dependent getProjectionMatrix
311	in that it always returns a right-handed projection matrix result
312	no matter what rendering API is being used - this is required for
313	vertex and fragment programs for example. However, the resulting depth
314	range may still vary between render systems since D3D uses [0,1] and
315	GL uses [-1,1], and the range must be kept the same between programmable
316	and fixed-function pipelines.
317	*/
318	virtual const Matrix4& getProjectionMatrixWithRSDepth(void) const;
319	/** Gets the normal projection matrix for this frustum, ie the
320	projection matrix which conforms to standard right-handed rules and
321	uses depth range [-1,+1].
322	@remarks
323	This differs from the rendering-API dependent getRenderSystemProjectionMatrix
324	in that it always returns a right-handed projection matrix with depth
325	range [-1,+1], result no matter what rendering API is being used - this
326	is required for some uniform algebra for example.
327	*/
328	virtual const Matrix4& getProjectionMatrix(void) const;
329
330	/** Gets the view matrix for this frustum. Mainly for use by OGRE internally.
331	*/
332	virtual const Matrix4& getViewMatrix(void) const;
333
334	/** Set whether to use a custom view matrix on this frustum.
335	@remarks
336	This is an advanced method which allows you to manually set
337	the view matrix on this frustum, rather than having it calculate
338	itself based on it's position and orientation.
339	@note
340	After enabling a custom view matrix, the frustum will no longer
341	update on its own based on position / orientation changes. You
342	are completely responsible for keeping the view matrix up to date.
343	The custom matrix will be returned from getViewMatrix.
344	@param enable If true, the custom view matrix passed as the second
345	parameter will be used in preference to an auto calculated one. If
346	false, the frustum will revert to auto calculating the view matrix.
347	@param viewMatrix The custom view matrix to use
348	@see Frustum::setCustomProjectionMatrix
349	*/
350	virtual void setCustomViewMatrix(bool enable,
351	const Matrix4& viewMatrix = Matrix4::IDENTITY);
352	/// Returns whether a custom view matrix is in use
353	virtual bool isCustomViewMatrixEnabled(void) const
354	{ return mCustomViewMatrix; }
355
356	/** Set whether to use a custom projection matrix on this frustum.
357	@remarks
358	This is an advanced method which allows you to manually set
359	the projection matrix on this frustum, rather than having it
360	calculate itself based on it's position and orientation.
361	@note
362	After enabling a custom projection matrix, the frustum will no
363	longer update on its own based on field of view and near / far
364	distance changes. You are completely responsible for keeping the
365	projection matrix up to date if those values change. The custom
366	matrix will be returned from getProjectionMatrix and derivative
367	functions.
368	@param enable If true, the custom projection matrix passed as the
369	second parameter will be used in preference to an auto calculated
370	one. If false, the frustum will revert to auto calculating the
371	projection matrix.
372	@param projectionMatrix The custom view matrix to use
373	@see Frustum::setCustomViewMatrix
374	*/
375	virtual void setCustomProjectionMatrix(bool enable,
376	const Matrix4& projectionMatrix = Matrix4::IDENTITY);
377	/// Returns whether a custom projection matrix is in use
378	virtual bool isCustomProjectionMatrixEnabled(void) const
379	{ return mCustomProjMatrix; }
380
381	/** Retrieves the clipping planes of the frustum.
382	@remarks
383	The clipping planes are ordered as declared in enumerate constants FrustumPlane.
384	*/
385	virtual const Plane* getFrustumPlanes(void) const;
386
387	/** Retrieves a specified plane of the frustum.
388	@remarks
389	Gets a reference to one of the planes which make up the frustum frustum, e.g. for clipping purposes.
390	*/
391	virtual const Plane& getFrustumPlane( unsigned short plane ) const;
392
393	/** Tests whether the given container is visible in the Frustum.
394	@param
395	bound Bounding box to be checked
396	@param
397	culledBy Optional pointer to an int which will be filled by the plane number which culled
398	the box if the result was false;
399	@returns
400	If the box was visible, true is returned.
401	@par
402	Otherwise, false is returned.
403	*/
404	virtual bool isVisible(const AxisAlignedBox& bound, FrustumPlane* culledBy = 0) const;
405
406	/** Tests whether the given container is visible in the Frustum.
407	@param
408	bound Bounding sphere to be checked
409	@param
410	culledBy Optional pointer to an int which will be filled by the plane number which culled
411	the box if the result was false;
412	@returns
413	If the sphere was visible, true is returned.
414	@par
415	Otherwise, false is returned.
416	*/
417	virtual bool isVisible(const Sphere& bound, FrustumPlane* culledBy = 0) const;
418
419	/** Tests whether the given vertex is visible in the Frustum.
420	@param
421	vert Vertex to be checked
422	@param
423	culledBy Optional pointer to an int which will be filled by the plane number which culled
424	the box if the result was false;
425	@returns
426	If the box was visible, true is returned.
427	@par
428	Otherwise, false is returned.
429	*/
430	virtual bool isVisible(const Vector3& vert, FrustumPlane* culledBy = 0) const;
431
432
433	/** Overridden from MovableObject */
434	const AxisAlignedBox& getBoundingBox(void) const;
435
436	/** Overridden from MovableObject */
437	Real getBoundingRadius(void) const;
438
439	/** Overridden from MovableObject */
440	void _updateRenderQueue(RenderQueue* queue);
441
442	/** Overridden from MovableObject */
443	const String& getMovableType(void) const;
444
445	/** Overridden from MovableObject */
446	void _notifyCurrentCamera(Camera* cam);
447
448	/** Overridden from Renderable */
449	const MaterialPtr& getMaterial(void) const;
450
451	/** Overridden from Renderable */
452	void getRenderOperation(RenderOperation& op);
453
454	/** Overridden from Renderable */
455	void getWorldTransforms(Matrix4* xform) const;
456
457	/** Overridden from Renderable */
458	const Quaternion& getWorldOrientation(void) const;
459
460	/** Overridden from Renderable */
461	const Vector3& getWorldPosition(void) const;
462
463	/** Overridden from Renderable */
464	Real getSquaredViewDepth(const Camera* cam) const;
465
466	/** Overridden from Renderable */
467	const LightList& getLights(void) const;
468
469	/** Gets the world space corners of the frustum.
470	@remarks
471	The corners are ordered as follows: top-right near,
472	top-left near, bottom-left near, bottom-right near,
473	top-right far, top-left far, bottom-left far, bottom-right far.
474	*/
475	virtual const Vector3* getWorldSpaceCorners(void) const;
476
477	/** Sets the type of projection to use (orthographic or perspective). Default is perspective.
478	*/
479	virtual void setProjectionType(ProjectionType pt);
480
481	/** Retrieves info on the type of projection used (orthographic or perspective).
482	*/
483	virtual ProjectionType getProjectionType(void) const;
484
485	/** Modifies this frustum so it always renders from the reflection of itself through the
486	plane specified.
487	@remarks
488	This is obviously useful for performing planar reflections.
489	*/
490	virtual void enableReflection(const Plane& p);
491	/** Modifies this frustum so it always renders from the reflection of itself through the
492	plane specified. Note that this version of the method links to a plane
493	so that changes to it are picked up automatically. It is important that
494	this plane continues to exist whilst this object does; do not destroy
495	the plane before the frustum.
496	@remarks
497	This is obviously useful for performing planar reflections.
498	*/
499	virtual void enableReflection(const MovablePlane* p);
500
501	/** Disables reflection modification previously turned on with enableReflection */
502	virtual void disableReflection(void);
503
504	/// Returns whether this frustum is being reflected
505	virtual bool isReflected(void) const { return mReflect; }
506	/// Returns the reflection matrix of the frustum if appropriate
507	virtual const Matrix4& getReflectionMatrix(void) const { return mReflectMatrix; }
508	/// Returns the reflection plane of the frustum if appropriate
509	virtual const Plane& getReflectionPlane(void) const { return mReflectPlane; }
510
511	/** Project a sphere onto the near plane and get the bounding rectangle.
512	@param sphere The world-space sphere to project
513	@param radius Radius of the sphere
514	@param left, top, right, bottom Pointers to destination values, these
515	will be completed with the normalised device coordinates (in the
516	range {-1,1})
517	@returns true if the sphere was projected to a subset of the near plane,
518	false if the entire near plane was contained
519	*/
520	virtual bool projectSphere(const Sphere& sphere,
521	Real* left, Real* top, Real* right, Real* bottom) const;
522
523
524	/** Links the frustum to a custom near clip plane, which can be used
525	to clip geometry in a custom manner without using user clip planes.
526	@remarks
527	There are several applications for clipping a scene arbitrarily by
528	a single plane; the most common is when rendering a reflection to
529	a texture, and you only want to render geometry that is above the
530	water plane (to do otherwise results in artefacts). Whilst it is
531	possible to use user clip planes, they are not supported on all
532	cards, and sometimes are not hardware accelerated when they are
533	available. Instead, where a single clip plane is involved, this
534	technique uses a 'fudging' of the near clip plane, which is
535	available and fast on all hardware, to perform as the arbitrary
536	clip plane. This does change the shape of the frustum, leading
537	to some depth buffer loss of precision, but for many of the uses of
538	this technique that is not an issue.
539	@par
540	This version of the method links to a plane, rather than requiring
541	a by-value plane definition, and therefore you can
542	make changes to the plane (e.g. by moving / rotating the node it is
543	attached to) and they will automatically affect this object.
544	@note This technique only works for perspective projection.
545	@param plane The plane to link to to perform the clipping. This plane
546	must continue to exist while the camera is linked to it; do not
547	destroy it before the frustum.
548	*/
549	virtual void enableCustomNearClipPlane(const MovablePlane* plane);
550	/** Links the frustum to a custom near clip plane, which can be used
551	to clip geometry in a custom manner without using user clip planes.
552	@remarks
553	There are several applications for clipping a scene arbitrarily by
554	a single plane; the most common is when rendering a reflection to
555	a texture, and you only want to render geometry that is above the
556	water plane (to do otherwise results in artefacts). Whilst it is
557	possible to use user clip planes, they are not supported on all
558	cards, and sometimes are not hardware accelerated when they are
559	available. Instead, where a single clip plane is involved, this
560	technique uses a 'fudging' of the near clip plane, which is
561	available and fast on all hardware, to perform as the arbitrary
562	clip plane. This does change the shape of the frustum, leading
563	to some depth buffer loss of precision, but for many of the uses of
564	this technique that is not an issue.
565	@note This technique only works for perspective projection.
566	@param plane The plane to link to to perform the clipping. This plane
567	must continue to exist while the camera is linked to it; do not
568	destroy it before the frustum.
569	*/
570	virtual void enableCustomNearClipPlane(const Plane& plane);
571	/** Disables any custom near clip plane. */
572	virtual void disableCustomNearClipPlane(void);
573	/** Is a custom near clip plane in use? */
574	virtual bool isCustomNearClipPlaneEnabled(void) const
575	{ return mObliqueDepthProjection; }
576
577
578	/// Small constant used to reduce far plane projection to avoid inaccuracies
579	static const Real INFINITE_FAR_PLANE_ADJUST;
580	};
581
582
583	}
584
585	#endif

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

Context Navigation

source: OGRE/trunk/ogrenew/OgreMain/include/OgreFrustum.h @ 692

Download in other formats: