Context Navigation

OgreCamera.h @ 692

Revision 692, 23.3 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://ogre.sourceforge.net/
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 __Camera_H__
26	#define __Camera_H__
27
28	// Default options
29	#include "OgrePrerequisites.h"
30
31	#include "OgreString.h"
32	#include "OgreMovableObject.h"
33
34	// Matrices & Vectors
35	#include "OgreMatrix4.h"
36	#include "OgreVector3.h"
37	#include "OgrePlane.h"
38	#include "OgreQuaternion.h"
39	#include "OgreCommon.h"
40	#include "OgreFrustum.h"
41	#include "OgreRay.h"
42
43
44	namespace Ogre {
45
46
47
48	/** A viewpoint from which the scene will be rendered.
49	@remarks
50	OGRE renders scenes from a camera viewpoint into a buffer of
51	some sort, normally a window or a texture (a subclass of
52	RenderTarget). OGRE cameras support both perspective projection (the default,
53	meaning objects get smaller the further away they are) and
54	orthographic projection (blueprint-style, no decrease in size
55	with distance). Each camera carries with it a style of rendering,
56	e.g. full textured, flat shaded, wireframe), field of view,
57	rendering distances etc, allowing you to use OGRE to create
58	complex multi-window views if required. In addition, more than
59	one camera can point at a single render target if required,
60	each rendering to a subset of the target, allowing split screen
61	and picture-in-picture views.
62	@par
63	Cameras maintain their own aspect ratios, field of view, and frustrum,
64	and project co-ordinates into a space measured from -1 to 1 in x and y,
65	and 0 to 1 in z. At render time, the camera will be rendering to a
66	Viewport which will translate these parametric co-ordinates into real screen
67	co-ordinates. Obviously it is advisable that the viewport has the same
68	aspect ratio as the camera to avoid distortion (unless you want it!).
69	@par
70	Note that a Camera can be attached to a SceneNode, using the method
71	SceneNode::attachObject. If this is done the Camera will combine it's own
72	position/orientation settings with it's parent SceneNode.
73	This is useful for implementing more complex Camera / object
74	relationships i.e. having a camera attached to a world object.
75	*/
76	class _OgreExport Camera : public Frustum
77	{
78	protected:
79	/// Camera name
80	String mName;
81	/// Scene manager responsible for the scene
82	SceneManager *mSceneMgr;
83
84	/// Camera orientation, quaternion style
85	Quaternion mOrientation;
86
87	/// Camera position - default (0,0,0)
88	Vector3 mPosition;
89
90	/// Derived orientation/position of the camera, including reflection
91	mutable Quaternion mDerivedOrientation;
92	mutable Vector3 mDerivedPosition;
93
94	/// Real world orientation/position of the camera
95	mutable Quaternion mRealOrientation;
96	mutable Vector3 mRealPosition;
97
98	/// Whether to yaw around a fixed axis.
99	bool mYawFixed;
100	/// Fixed axis to yaw around
101	Vector3 mYawFixedAxis;
102
103	/// Rendering type
104	PolygonMode mSceneDetail;
105
106	/// Stored number of visible faces in the last render
107	unsigned int mVisFacesLastRender;
108
109	/// Shared class-level name for Movable type
110	static String msMovableType;
111
112	/// SceneNode which this Camera will automatically track
113	SceneNode* mAutoTrackTarget;
114	/// Tracking offset for fine tuning
115	Vector3 mAutoTrackOffset;
116
117	// Scene LOD factor used to adjust overall LOD
118	Real mSceneLodFactor;
119	/// Inverted scene LOD factor, can be used by Renderables to adjust their LOD
120	Real mSceneLodFactorInv;
121
122
123	/** Viewing window.
124	@remarks
125	Generalize camera class for the case, when viewing frustum doesn't cover all viewport.
126	*/
127	Real mWLeft, mWTop, mWRight, mWBottom;
128	/// Is viewing window used.
129	bool mWindowSet;
130	/// Windowed viewport clip planes
131	mutable std::vector<Plane> mWindowClipPlanes;
132	// Was viewing window changed.
133	mutable bool mRecalcWindow;
134	/// The last viewport to be added using this camera
135	Viewport* mLastViewport;
136	/** Whether aspect ratio will automaticaally be recalculated
137	when a vieport changes its size
138	*/
139	bool mAutoAspectRatio;
140	/// Custom culling frustum
141	Frustum *mCullFrustum;
142	/// Whether or not the rendering distance of objects should take effect for this camera
143	bool mUseRenderingDistance;
144
145
146	// Internal functions for calcs
147	bool isViewOutOfDate(void) const;
148	/// Signal to update frustum information.
149	void invalidateFrustum(void) const;
150	/// Signal to update view information.
151	void invalidateView(void) const;
152
153
154	/** Do actual window setting, using parameters set in SetWindow call
155	@remarks
156	The method will called on demand.
157	*/
158	virtual void setWindowImpl(void) const;
159	/** Get the derived position of this frustum. */
160	const Vector3& getPositionForViewUpdate(void) const;
161	/** Get the derived orientation of this frustum. */
162	const Quaternion& getOrientationForViewUpdate(void) const;
163
164
165	public:
166	/** Standard constructor.
167	*/
168	Camera( const String& name, SceneManager* sm);
169
170	/** Standard destructor.
171	*/
172	virtual ~Camera();
173
174
175	/** Returns a pointer to the SceneManager this camera is rendering through.
176	*/
177	SceneManager* getSceneManager(void) const;
178
179	/** Gets the camera's name.
180	*/
181	virtual const String& getName(void) const;
182
183
184	/** Sets the level of rendering detail required from this camera.
185	@remarks
186	Each camera is set to render at full detail by default, that is
187	with full texturing, lighting etc. This method lets you change
188	that behaviour, allowing you to make the camera just render a
189	wireframe view, for example.
190	*/
191	void setPolygonMode(PolygonMode sd);
192
193	/** Retrieves the level of detail that the camera will render.
194	*/
195	PolygonMode getPolygonMode(void) const;
196
197	/** Sets the camera's position.
198	*/
199	void setPosition(Real x, Real y, Real z);
200
201	/** Sets the camera's position.
202	*/
203	void setPosition(const Vector3& vec);
204
205	/** Retrieves the camera's position.
206	*/
207	const Vector3& getPosition(void) const;
208
209	/** Moves the camera's position by the vector offset provided along world axes.
210	*/
211	void move(const Vector3& vec);
212
213	/** Moves the camera's position by the vector offset provided along it's own axes (relative to orientation).
214	*/
215	void moveRelative(const Vector3& vec);
216
217	/** Sets the camera's direction vector.
218	@remarks
219	Note that the 'up' vector for the camera will automatically be recalculated based on the
220	current 'up' vector (i.e. the roll will remain the same).
221	*/
222	void setDirection(Real x, Real y, Real z);
223
224	/** Sets the camera's direction vector.
225	*/
226	void setDirection(const Vector3& vec);
227
228	/* Gets the camera's direction.
229	*/
230	Vector3 getDirection(void) const;
231
232	/** Gets the camera's up vector.
233	*/
234	Vector3 getUp(void) const;
235
236	/** Gets the camera's right vector.
237	*/
238	Vector3 getRight(void) const;
239
240	/** Points the camera at a location in worldspace.
241	@remarks
242	This is a helper method to automatically generate the
243	direction vector for the camera, based on it's current position
244	and the supplied look-at point.
245	@param
246	targetPoint A vector specifying the look at point.
247	*/
248	void lookAt( const Vector3& targetPoint );
249	/** Points the camera at a location in worldspace.
250	@remarks
251	This is a helper method to automatically generate the
252	direction vector for the camera, based on it's current position
253	and the supplied look-at point.
254	@param
255	x
256	@param
257	y
258	@param
259	z Co-ordinates of the point to look at.
260	*/
261	void lookAt(Real x, Real y, Real z);
262
263	/** Rolls the camera anticlockwise, around its local z axis.
264	*/
265	void roll(const Radian& angle);
266	#ifndef OGRE_FORCE_ANGLE_TYPES
267	void roll(Real degrees) { roll ( Angle(degrees) ); }
268	#endif//OGRE_FORCE_ANGLE_TYPES
269
270	/** Rotates the camera anticlockwise around it's local y axis.
271	*/
272	void yaw(const Radian& angle);
273	#ifndef OGRE_FORCE_ANGLE_TYPES
274	void yaw(Real degrees) { yaw ( Angle(degrees) ); }
275	#endif//OGRE_FORCE_ANGLE_TYPES
276
277	/** Pitches the camera up/down anticlockwise around it's local z axis.
278	*/
279	void pitch(const Radian& angle);
280	#ifndef OGRE_FORCE_ANGLE_TYPES
281	void pitch(Real degrees) { pitch ( Angle(degrees) ); }
282	#endif//OGRE_FORCE_ANGLE_TYPES
283
284	/** Rotate the camera around an arbitrary axis.
285	*/
286	void rotate(const Vector3& axis, const Radian& angle);
287	#ifndef OGRE_FORCE_ANGLE_TYPES
288	void rotate(const Vector3& axis, Real degrees) { rotate ( axis, Angle(degrees) ); }
289	#endif//OGRE_FORCE_ANGLE_TYPES
290
291	/** Rotate the camera around an aritrary axis using a Quarternion.
292	*/
293	void rotate(const Quaternion& q);
294
295	/** Tells the camera whether to yaw around it's own local Y axis or a
296	fixed axis of choice.
297	@remarks
298	This method allows you to change the yaw behaviour of the camera
299	- by default, the camera yaws around a fixed Y axis. This is
300	often what you want - for example if you're making a first-person
301	shooter, you really don't want the yaw axis to reflect the local
302	camera Y, because this would mean a different yaw axis if the
303	player is looking upwards rather than when they are looking
304	straight ahead. You can change this behaviour by calling this
305	method, which you will want to do if you are making a completely
306	free camera like the kind used in a flight simulator.
307	@param
308	useFixed If true, the axis passed in the second parameter will
309	always be the yaw axis no matter what the camera orientation.
310	If false, the camera yaws around the local Y.
311	@param
312	fixedAxis The axis to use if the first parameter is true.
313	*/
314	void setFixedYawAxis( bool useFixed, const Vector3& fixedAxis = Vector3::UNIT_Y );
315
316
317	/** Returns the camera's current orientation.
318	*/
319	const Quaternion& getOrientation(void) const;
320
321	/** Sets the camera's orientation.
322	*/
323	void setOrientation(const Quaternion& q);
324
325	/** Tells the Camera to contact the SceneManager to render from it's viewpoint.
326	@param vp The viewport to render to
327	@param includeOverlays Whether or not any overlay objects should be included
328	*/
329	void _renderScene(Viewport *vp, bool includeOverlays);
330
331	/** Function for outputting to a stream.
332	*/
333	friend std::ostream& operator<<(std::ostream& o, Camera& c);
334
335	/** Internal method to notify camera of the visible faces in the last render.
336	*/
337	void _notifyRenderedFaces(unsigned int numfaces);
338
339	/** Internal method to retrieve the number of visible faces in the last render.
340	*/
341	unsigned int _getNumRenderedFaces(void) const;
342
343	/** Gets the derived orientation of the camera, including any
344	rotation inherited from a node attachment and reflection matrix. */
345	const Quaternion& getDerivedOrientation(void) const;
346	/** Gets the derived position of the camera, including any
347	translation inherited from a node attachment and reflection matrix. */
348	const Vector3& getDerivedPosition(void) const;
349	/** Gets the derived direction vector of the camera, including any
350	rotation inherited from a node attachment and reflection matrix. */
351	Vector3 getDerivedDirection(void) const;
352	/** Gets the derived up vector of the camera, including any
353	rotation inherited from a node attachment and reflection matrix. */
354	Vector3 getDerivedUp(void) const;
355	/** Gets the derived right vector of the camera, including any
356	rotation inherited from a node attachment and reflection matrix. */
357	Vector3 getDerivedRight(void) const;
358
359	/** Gets the real world orientation of the camera, including any
360	rotation inherited from a node attachment */
361	const Quaternion& getRealOrientation(void) const;
362	/** Gets the real world position of the camera, including any
363	translation inherited from a node attachment. */
364	const Vector3& getRealPosition(void) const;
365	/** Gets the real world direction vector of the camera, including any
366	rotation inherited from a node attachment. */
367	Vector3 getRealDirection(void) const;
368	/** Gets the real world up vector of the camera, including any
369	rotation inherited from a node attachment. */
370	Vector3 getRealUp(void) const;
371	/** Gets the real world right vector of the camera, including any
372	rotation inherited from a node attachment. */
373	Vector3 getRealRight(void) const;
374
375	/** Overridden from MovableObject */
376	const String& getMovableType(void) const;
377
378	/** Enables / disables automatic tracking of a SceneNode.
379	@remarks
380	If you enable auto-tracking, this Camera will automatically rotate to
381	look at the target SceneNode every frame, no matter how
382	it or SceneNode move. This is handy if you want a Camera to be focused on a
383	single object or group of objects. Note that by default the Camera looks at the
384	origin of the SceneNode, if you want to tweak this, e.g. if the object which is
385	attached to this target node is quite big and you want to point the camera at
386	a specific point on it, provide a vector in the 'offset' parameter and the
387	camera's target point will be adjusted.
388	@param enabled If true, the Camera will track the SceneNode supplied as the next
389	parameter (cannot be null). If false the camera will cease tracking and will
390	remain in it's current orientation.
391	@param target Pointer to the SceneNode which this Camera will track. Make sure you don't
392	delete this SceneNode before turning off tracking (e.g. SceneManager::clearScene will
393	delete it so be careful of this). Can be null if and only if the enabled param is false.
394	@param offset If supplied, the camera targets this point in local space of the target node
395	instead of the origin of the target node. Good for fine tuning the look at point.
396	*/
397	void setAutoTracking(bool enabled, SceneNode* target = 0,
398	const Vector3& offset = Vector3::ZERO);
399
400
401	/** Sets the level-of-detail factor for this Camera.
402	@remarks
403	This method can be used to influence the overall level of detail of the scenes
404	rendered using this camera. Various elements of the scene have level-of-detail
405	reductions to improve rendering speed at distance; this method allows you
406	to hint to those elements that you would like to adjust the level of detail that
407	they would normally use (up or down).
408	@par
409	The most common use for this method is to reduce the overall level of detail used
410	for a secondary camera used for sub viewports like rear-view mirrors etc.
411	Note that scene elements are at liberty to ignore this setting if they choose,
412	this is merely a hint.
413	@param factor The factor to apply to the usual level of detail calculation. Higher
414	values increase the detail, so 2.0 doubles the normal detail and 0.5 halves it.
415	*/
416	void setLodBias(Real factor = 1.0);
417
418	/** Returns the level-of-detail bias factor currently applied to this camera.
419	@remarks
420	See Camera::setLodBias for more details.
421	*/
422	Real getLodBias(void) const;
423
424
425
426	/** Gets a world space ray as cast from the camera through a viewport position.
427	@param screenx, screeny The x and y position at which the ray should intersect the viewport,
428	in normalised screen coordinates [0,1]
429	*/
430	Ray getCameraToViewportRay(Real screenx, Real screeny) const;
431
432	/** Internal method for OGRE to use for LOD calculations. */
433	Real _getLodBiasInverse(void) const;
434
435
436	/** Internal method used by OGRE to update auto-tracking cameras. */
437	void _autoTrack(void);
438
439
440	/** Sets the viewing window inside of viewport.
441	@remarks
442	This method can be used to set a subset of the viewport as the rendering
443	target.
444	@param Left Relative to Viewport - 0 corresponds to left edge, 1 - to right edge (default - 0).
445	@param Top Relative to Viewport - 0 corresponds to top edge, 1 - to bottom edge (default - 0).
446	@param Right Relative to Viewport - 0 corresponds to left edge, 1 - to right edge (default - 1).
447	@param Bottom Relative to Viewport - 0 corresponds to top edge, 1 - to bottom edge (default - 1).
448	*/
449	virtual void setWindow (Real Left, Real Top, Real Right, Real Bottom);
450	/// Cancel view window.
451	virtual void resetWindow (void);
452	/// Returns if a viewport window is being used
453	virtual bool isWindowSet(void) const { return mWindowSet; }
454	/// Gets the window clip planes, only applicable if isWindowSet == true
455	const std::vector<Plane>& getWindowPlanes(void) const;
456
457	/** Overridden from MovableObject */
458	Real getBoundingRadius(void) const;
459	/** Get the auto tracking target for this camera, if any. */
460	SceneNode* getAutoTrackTarget(void) const { return mAutoTrackTarget; }
461	/** Get the auto tracking offset for this camera, if it is auto tracking. */
462	const Vector3& getAutoTrackOffset(void) const { return mAutoTrackOffset; }
463
464	/** Get the last viewport which was attached to this camera.
465	@note This is not guaranteed to be the only viewport which is
466	using this camera, just the last once which was created referring
467	to it.
468	*/
469	Viewport* getViewport(void) const {return mLastViewport;}
470	/** Notifies this camera that a viewport is using it.*/
471	void _notifyViewport(Viewport* viewport) {mLastViewport = viewport;}
472
473	/** If set to true a vieport that owns this frustum will be able to
474	recalculate the aspect ratio whenever the frustum is resized.
475	@remarks
476	You should set this to true only if the frustum / camera is used by
477	one viewport at the same time. Otherwise the aspect ratio for other
478	viewports may be wrong.
479	*/
480	void setAutoAspectRatio(bool autoratio);
481
482	/** Retreives if AutoAspectRatio is currently set or not
483	*/
484	bool getAutoAspectRatio(void) const;
485
486	/** Tells the camera to use a separate Frustum instance to perform culling.
487	@remarks
488	By calling this method, you can tell the camera to perform culling
489	against a different frustum to it's own. This is mostly useful for
490	debug cameras that allow you to show the culling behaviour of another
491	camera, or a manual frustum instance.
492	@param frustum Pointer to a frustum to use; this can either be a manual
493	Frustum instance (which you can attach to scene nodes like any other
494	MovableObject), or another camera. If you pass 0 to this method it
495	reverts the camera to normal behaviour.
496	*/
497	void setCullingFrustum(Frustum* frustum) { mCullFrustum = frustum; }
498	/** Returns the custom culling frustum in use. */
499	Frustum* getCullingFrustum(void) { return mCullFrustum; }
500
501	/// @copydoc Frustum::isVisible
502	bool isVisible(const AxisAlignedBox& bound, FrustumPlane* culledBy = 0) const;
503	/// @copydoc Frustum::isVisible
504	bool isVisible(const Sphere& bound, FrustumPlane* culledBy = 0) const;
505	/// @copydoc Frustum::isVisible
506	bool isVisible(const Vector3& vert, FrustumPlane* culledBy = 0) const;
507	/// @copydoc Frustum::getWorldSpaceCorners
508	const Vector3* getWorldSpaceCorners(void) const;
509	/// @copydoc Frustum::getFrustumPlane
510	const Plane& getFrustumPlane( unsigned short plane ) const;
511	/// @copydoc Frustum::projectSphere
512	bool projectSphere(const Sphere& sphere,
513	Real* left, Real* top, Real* right, Real* bottom) const;
514	/// @copydoc Frustum::getNearClipDistance
515	Real getNearClipDistance(void) const;
516	/// @copydoc Frustum::getFarClipDistance
517	Real getFarClipDistance(void) const;
518	/// @copydoc Frustum::getViewMatrix
519	const Matrix4& getViewMatrix(void) const;
520	/** Specialised version of getViewMatrix allowing caller to differentiate
521	whether the custom culling frustum should be allowed or not.
522	@remarks
523	The default behaviour of the standard getViewMatrix is to delegate to
524	the alternate culling frustum, if it is set. This is expected when
525	performing CPU calculations, but the final rendering must be performed
526	using the real view matrix in order to display the correct debug view.
527	*/
528	const Matrix4& getViewMatrix(bool ownFrustumOnly) const;
529	/** Set whether this camera should use the 'rendering distance' on
530	objects to exclude distant objects from the final image. The
531	default behaviour is to use it.
532	@param use True to use the rendering distance, false not to.
533	*/
534	virtual void setUseRenderingDistance(bool use) { mUseRenderingDistance = use; }
535	/** Get whether this camera should use the 'rendering distance' on
536	objects to exclude distant objects from the final image.
537	*/
538	virtual bool getUseRenderingDistance(void) const { return mUseRenderingDistance; }
539	};
540
541	} // namespace Ogre
542	#endif

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

Context Navigation

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

Download in other formats: