source: GTP/trunk/App/Demos/Geom/include/OgreCamera.h @ 1030

Revision 1030, 19.0 KB checked in by gumbau, 18 years ago (diff)

Ogre Stuff initial import

Line 
1/*
2-----------------------------------------------------------------------------
3This source file is part of OGRE
4    (Object-oriented Graphics Rendering Engine)
5For the latest info, see http://ogre.sourceforge.net/
6
7Copyright (c) 2000-2005 The OGRE Team
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-----------------------------------------------------------------------------
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
44namespace 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 positions of parent orientation / position
91        mutable Quaternion mDerivedOrientation;
92        mutable Vector3 mDerivedPosition;
93
94        /// Whether to yaw around a fixed axis.
95        bool mYawFixed;
96        /// Fixed axis to yaw around
97        Vector3 mYawFixedAxis;
98
99        /// Rendering type
100        SceneDetailLevel mSceneDetail;
101
102        /// Stored number of visible faces in the last render
103        unsigned int mVisFacesLastRender;
104
105        /// Shared class-level name for Movable type
106        static String msMovableType;
107
108        /// SceneNode which this Camera will automatically track
109        SceneNode* mAutoTrackTarget;
110        /// Tracking offset for fine tuning
111        Vector3 mAutoTrackOffset;
112
113                // Scene LOD factor used to adjust overall LOD
114                Real mSceneLodFactor;
115                /// Inverted scene LOD factor, can be used by Renderables to adjust their LOD
116                Real mSceneLodFactorInv;
117
118
119        /** Viewing window.
120        @remarks
121        Generalize camera class for the case, when viewing frustum doesn't cover all viewport.
122        */
123        Real mWLeft, mWTop, mWRight, mWBottom;
124        /// Is viewing window used.
125        bool mWindowSet;
126        /// Windowed viewport clip planes
127        mutable std::vector<Plane> mWindowClipPlanes;
128        // Was viewing window changed.
129        mutable bool mRecalcWindow;
130        /// The last viewport to be added using this camera
131        Viewport* mLastViewport;
132        /** Whether aspect ratio will automaticaally be recalculated
133            when a vieport changes its size
134        */
135        bool mAutoAspectRatio;
136
137        // Internal functions for calcs
138        void updateFrustum(void) const;
139        void updateView(void) const;
140        bool isViewOutOfDate(void) const;
141        /// Signal to update frustum information.
142        void invalidateFrustum(void) const;
143        /// Signal to update view information.
144        void invalidateView(void) const;
145
146
147        /** Do actual window setting, using parameters set in SetWindow call
148        @remarks
149        The method is called after projection matrix each change
150        */
151        virtual void setWindowImpl(void) const;
152        /** Get the derived position of this frustum. */
153        const Vector3& getPositionForViewUpdate(void) const;
154        /** Get the derived orientation of this frustum. */
155        const Quaternion& getOrientationForViewUpdate(void) const;
156
157
158    public:
159        /** Standard constructor.
160        */
161        Camera( const String& name, SceneManager* sm);
162
163        /** Standard destructor.
164        */
165        virtual ~Camera();
166
167
168        /** Returns a pointer to the SceneManager this camera is rendering through.
169        */
170        SceneManager* getSceneManager(void) const;
171
172        /** Gets the camera's name.
173        */
174        virtual const String& getName(void) const;
175
176
177        /** Sets the level of rendering detail required from this camera.
178            @remarks
179                Each camera is set to render at full detail by default, that is
180                with full texturing, lighting etc. This method lets you change
181                that behaviour, allowing you to make the camera just render a
182                wireframe view, for example.
183        */
184        void setDetailLevel(SceneDetailLevel sd);
185
186        /** Retrieves the level of detail that the camera will render.
187        */
188        SceneDetailLevel getDetailLevel(void) const;
189
190        /** Sets the camera's position.
191        */
192        void setPosition(Real x, Real y, Real z);
193
194        /** Sets the camera's position.
195        */
196        void setPosition(const Vector3& vec);
197
198        /** Retrieves the camera's position.
199        */
200        const Vector3& getPosition(void) const;
201
202        /** Moves the camera's position by the vector offset provided along world axes.
203        */
204        void move(const Vector3& vec);
205
206        /** Moves the camera's position by the vector offset provided along it's own axes (relative to orientation).
207        */
208        void moveRelative(const Vector3& vec);
209
210        /** Sets the camera's direction vector.
211            @remarks
212                Note that the 'up' vector for the camera will automatically be recalculated based on the
213                current 'up' vector (i.e. the roll will remain the same).
214        */
215        void setDirection(Real x, Real y, Real z);
216
217        /** Sets the camera's direction vector.
218        */
219        void setDirection(const Vector3& vec);
220
221        /* Gets the camera's direction.
222        */
223        Vector3 getDirection(void) const;
224
225        /** Gets the camera's up vector.
226        */
227        Vector3 getUp(void) const;
228
229        /** Gets the camera's right vector.
230        */
231        Vector3 getRight(void) const;
232
233        /** Points the camera at a location in worldspace.
234            @remarks
235                This is a helper method to automatically generate the
236                direction vector for the camera, based on it's current position
237                and the supplied look-at point.
238            @param
239                targetPoint A vector specifying the look at point.
240        */
241        void lookAt( const Vector3& targetPoint );
242        /** Points the camera at a location in worldspace.
243            @remarks
244                This is a helper method to automatically generate the
245                direction vector for the camera, based on it's current position
246                and the supplied look-at point.
247            @param
248                x
249            @param
250                y
251            @param
252                z Co-ordinates of the point to look at.
253        */
254        void lookAt(Real x, Real y, Real z);
255
256        /** Rolls the camera anticlockwise, around its local z axis.
257        */
258        void roll(const Radian& angle);
259#ifndef OGRE_FORCE_ANGLE_TYPES
260        void roll(Real degrees) { roll ( Angle(degrees) ); }
261#endif//OGRE_FORCE_ANGLE_TYPES
262
263        /** Rotates the camera anticlockwise around it's local y axis.
264        */
265        void yaw(const Radian& angle);
266#ifndef OGRE_FORCE_ANGLE_TYPES
267        void yaw(Real degrees) { yaw ( Angle(degrees) ); }
268#endif//OGRE_FORCE_ANGLE_TYPES
269
270        /** Pitches the camera up/down anticlockwise around it's local z axis.
271        */
272        void pitch(const Radian& angle);
273#ifndef OGRE_FORCE_ANGLE_TYPES
274        void pitch(Real degrees) { pitch ( Angle(degrees) ); }
275#endif//OGRE_FORCE_ANGLE_TYPES
276
277        /** Rotate the camera around an arbitrary axis.
278        */
279        void rotate(const Vector3& axis, const Radian& angle);
280#ifndef OGRE_FORCE_ANGLE_TYPES
281        void rotate(const Vector3& axis, Real degrees) { rotate ( axis, Angle(degrees) ); }
282#endif//OGRE_FORCE_ANGLE_TYPES
283
284        /** Rotate the camera around an aritrary axis using a Quarternion.
285        */
286        void rotate(const Quaternion& q);
287
288        /** Tells the camera whether to yaw around it's own local Y axis or a
289                        fixed axis of choice.
290            @remarks
291                This method allows you to change the yaw behaviour of the camera
292                                - by default, the camera yaws around a fixed Y axis. This is
293                                often what you want - for example if you're making a first-person
294                                shooter, you really don't want the yaw axis to reflect the local
295                                camera Y, because this would mean a different yaw axis if the
296                                player is looking upwards rather than when they are looking
297                straight ahead. You can change this behaviour by calling this
298                                method, which you will want to do if you are making a completely
299                                free camera like the kind used in a flight simulator.
300            @param
301                useFixed If true, the axis passed in the second parameter will
302                                always be the yaw axis no matter what the camera orientation.
303                                If false, the camera yaws around the local Y.
304            @param
305                fixedAxis The axis to use if the first parameter is true.
306        */
307        void setFixedYawAxis( bool useFixed, const Vector3& fixedAxis = Vector3::UNIT_Y );
308
309
310        /** Returns the camera's current orientation.
311        */
312        const Quaternion& getOrientation(void) const;
313
314        /** Sets the camera's orientation.
315        */
316        void setOrientation(const Quaternion& q);
317
318        /** Tells the Camera to contact the SceneManager to render from it's viewpoint.
319        @param vp The viewport to render to
320        @param includeOverlays Whether or not any overlay objects should be included
321        */
322        void _renderScene(Viewport *vp, bool includeOverlays);
323
324        /** Function for outputting to a stream.
325        */
326        friend std::ostream& operator<<(std::ostream& o, Camera& c);
327
328        /** Internal method to notify camera of the visible faces in the last render.
329        */
330        void _notifyRenderedFaces(unsigned int numfaces);
331
332        /** Internal method to retrieve the number of visible faces in the last render.
333        */
334        unsigned int _getNumRenderedFaces(void) const;
335
336        /** Gets the derived orientation of the camera, including any
337            rotation inherited from a node attachment. */
338        const Quaternion& getDerivedOrientation(void) const;
339        /** Gets the derived position of the camera, including any
340            translation inherited from a node attachment. */
341        const Vector3& getDerivedPosition(void) const;
342        /** Gets the derived direction vector of the camera, including any
343            translation inherited from a node attachment. */
344        Vector3 getDerivedDirection(void) const;
345
346        /** Overridden from MovableObject */
347        const String& getMovableType(void) const;
348
349        /** Enables / disables automatic tracking of a SceneNode.
350        @remarks
351            If you enable auto-tracking, this Camera will automatically rotate to
352            look at the target SceneNode every frame, no matter how
353            it or SceneNode move. This is handy if you want a Camera to be focused on a
354            single object or group of objects. Note that by default the Camera looks at the
355            origin of the SceneNode, if you want to tweak this, e.g. if the object which is
356            attached to this target node is quite big and you want to point the camera at
357            a specific point on it, provide a vector in the 'offset' parameter and the
358            camera's target point will be adjusted.
359        @param enabled If true, the Camera will track the SceneNode supplied as the next
360            parameter (cannot be null). If false the camera will cease tracking and will
361            remain in it's current orientation.
362        @param target Pointer to the SceneNode which this Camera will track. Make sure you don't
363            delete this SceneNode before turning off tracking (e.g. SceneManager::clearScene will
364            delete it so be careful of this). Can be null if and only if the enabled param is false.
365        @param offset If supplied, the camera targets this point in local space of the target node
366            instead of the origin of the target node. Good for fine tuning the look at point.
367        */
368        void setAutoTracking(bool enabled, SceneNode* target = 0,
369            const Vector3& offset = Vector3::ZERO);
370
371
372                /** Sets the level-of-detail factor for this Camera.
373                @remarks
374                        This method can be used to influence the overall level of detail of the scenes
375                        rendered using this camera. Various elements of the scene have level-of-detail
376                        reductions to improve rendering speed at distance; this method allows you
377                        to hint to those elements that you would like to adjust the level of detail that
378                        they would normally use (up or down).
379                @par
380                        The most common use for this method is to reduce the overall level of detail used
381                        for a secondary camera used for sub viewports like rear-view mirrors etc.
382                        Note that scene elements are at liberty to ignore this setting if they choose,
383                        this is merely a hint.
384                @param factor The factor to apply to the usual level of detail calculation. Higher
385                        values increase the detail, so 2.0 doubles the normal detail and 0.5 halves it.
386                */
387                void setLodBias(Real factor = 1.0);
388
389                /** Returns the level-of-detail bias factor currently applied to this camera.
390                @remarks
391                        See Camera::setLodBias for more details.
392                */
393                Real getLodBias(void) const;
394
395
396
397        /** Gets a world space ray as cast from the camera through a viewport position.
398        @param screenx, screeny The x and y position at which the ray should intersect the viewport,
399            in normalised screen coordinates [0,1]
400        */
401        Ray getCameraToViewportRay(Real screenx, Real screeny) const;
402
403                /** Internal method for OGRE to use for LOD calculations. */
404                Real _getLodBiasInverse(void) const;
405
406
407        /** Internal method used by OGRE to update auto-tracking cameras. */
408        void _autoTrack(void);
409
410
411        /** Sets the viewing window inside of viewport.
412        @remarks
413        This method can be used to set a subset of the viewport as the rendering
414        target.
415        @param Left Relative to Viewport - 0 corresponds to left edge, 1 - to right edge (default - 0).
416        @param Top Relative to Viewport - 0 corresponds to top edge, 1 - to bottom edge (default - 0).
417        @param Right Relative to Viewport - 0 corresponds to left edge, 1 - to right edge (default - 1).
418        @param Bottom Relative to Viewport - 0 corresponds to top edge, 1 - to bottom edge (default - 1).
419        */
420        virtual void setWindow (Real Left, Real Top, Real Right, Real Bottom);
421        /// Cancel view window.
422        virtual void resetWindow (void);
423        /// Returns if a viewport window is being used
424        virtual bool isWindowSet(void) const { return mWindowSet; }
425        /// Gets the window clip planes, only applicable if isWindowSet == true
426        const std::vector<Plane>& getWindowPlanes(void) const;
427
428        /** Overridden from MovableObject */
429        Real getBoundingRadius(void) const;
430                /** Get the auto tracking target for this camera, if any. */
431        SceneNode* getAutoTrackTarget(void) const { return mAutoTrackTarget; }
432                /** Get the auto tracking offset for this camera, if it is auto tracking. */
433                const Vector3& getAutoTrackOffset(void) const { return mAutoTrackOffset; }
434               
435        /** Get the last viewport which was attached to this camera.
436        @note This is not guaranteed to be the only viewport which is
437        using this camera, just the last once which was created referring
438        to it.
439        */
440        Viewport* getViewport(void) const {return mLastViewport;}
441        /** Notifies this camera that a viewport is using it.*/
442        void _notifyViewport(Viewport* viewport) {mLastViewport = viewport;}
443
444        /** If set to true a vieport that owns this frustum will be able to
445            recalculate the aspect ratio whenever the frustum is resized.
446        @remarks
447            You should set this to true only if the frustum / camera is used by
448            one viewport at the same time. Otherwise the aspect ratio for other
449            viewports may be wrong.
450        */   
451        void setAutoAspectRatio(bool autoratio);
452
453        /** Retreives if AutoAspectRatio is currently set or not
454        */
455        bool getAutoAspectRatio(void) const;
456     };
457
458} // namespace Ogre
459#endif
Note: See TracBrowser for help on using the repository browser.