Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/OgreMain/include/OgreCamera.h @ 3

Last change on this file since 3 was 3, checked in by anonymous, 17 years ago

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