source: GTP/trunk/Lib/Geom/OgreStuff/include/OgreViewport.h @ 1809

Revision 1809, 12.0 KB checked in by gumbau, 18 years ago (diff)
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-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 __Viewport_H__
26#define __Viewport_H__
27
28#include "OgrePrerequisites.h"
29#include "OgreCommon.h"
30#include "OgreColourValue.h"
31
32namespace Ogre {
33    /** An abstraction of a viewport, i.e. a rendering region on a render
34        target.
35        @remarks
36            A viewport is the meeting of a camera and a rendering surface -
37            the camera renders the scene from a viewpoint, and places its
38            results into some subset of a rendering target, which may be the
39            whole surface or just a part of the surface. Each viewport has a
40            single camera as source and a single target as destination. A
41            camera only has 1 viewport, but a render target may have several.
42            A viewport also has a Z-order, i.e. if there is more than one
43            viewport on a single render target and they overlap, one must
44            obscure the other in some predetermined way.
45    */
46    class _OgreExport Viewport
47    {
48    public:
49        /** The usual constructor.
50            @param
51                cam Pointer to a camera to be the source for the image.
52            @param
53                target Pointer to the render target to be the destination
54                for the rendering.
55            @param
56                left
57            @param
58                top
59            @param
60                width
61            @param
62                height
63                Dimensions of the viewport, expressed as a value between
64                0 and 1. This allows the dimensions to apply irrespective of
65                changes in the target's size: e.g. to fill the whole area,
66                values of 0,0,1,1 are appropriate.
67            @param
68                ZOrder Relative Z-order on the target. Lower = further to
69                the front.
70        */
71        Viewport(
72            Camera* camera,
73            RenderTarget* target,
74            Real left, Real top,
75            Real width, Real height,
76            int ZOrder);
77
78        /** Default destructor.
79        */
80        virtual ~Viewport();
81
82        /** Notifies the viewport of a possible change in dimensions.
83            @remarks
84                Used by the target to update the viewport's dimensions
85                (usually the result of a change in target size).
86            @note
87                Internal use by Ogre only.
88        */
89        void _updateDimensions(void);
90
91        /** Instructs the viewport to updates its contents.
92        */
93        void update(void);
94
95        /** Retrieves a pointer to the render target for this viewport.
96        */
97        RenderTarget* getTarget(void) const;
98
99        /** Retrieves a pointer to the camera for this viewport.
100        */
101        Camera* getCamera(void) const;
102
103        /** Sets the camera to use for rendering to this viewport. */
104        void setCamera(Camera* cam);
105
106        /** Gets the Z-Order of this viewport. */
107                int getZOrder(void) const;
108                /** Gets one of the relative dimensions of the viewport,
109            a value between 0.0 and 1.0.
110        */
111        Real getLeft(void) const;
112
113        /** Gets one of the relative dimensions of the viewport, a value
114            between 0.0 and 1.0.
115        */
116        Real getTop(void) const;
117
118        /** Gets one of the relative dimensions of the viewport, a value
119            between 0.0 and 1.0.
120        */
121
122        Real getWidth(void) const;
123        /** Gets one of the relative dimensions of the viewport, a value
124            between 0.0 and 1.0.
125        */
126
127        Real getHeight(void) const;
128        /** Gets one of the actual dimensions of the viewport, a value in
129            pixels.
130        */
131
132        int getActualLeft(void) const;
133        /** Gets one of the actual dimensions of the viewport, a value in
134            pixels.
135        */
136
137        int getActualTop(void) const;
138        /** Gets one of the actual dimensions of the viewport, a value in
139            pixels.
140        */
141        int getActualWidth(void) const;
142        /** Gets one of the actual dimensions of the viewport, a value in
143            pixels.
144        */
145
146        int getActualHeight(void) const;
147
148        /** Sets the dimensions (after creation).
149            @param
150                left
151            @param
152                top
153            @param
154                width
155            @param
156                height Dimensions relative to the size of the target,
157                represented as real values between 0 and 1. i.e. the full
158                target area is 0, 0, 1, 1.
159        */
160        void setDimensions(Real left, Real top, Real width, Real height);
161
162        /** Sets the initial background colour of the viewport (before
163            rendering).
164        */
165        void setBackgroundColour(const ColourValue& colour);
166
167        /** Gets the background colour.
168        */
169        const ColourValue& getBackgroundColour(void) const;
170
171        /** Determines whether to clear the viewport before rendering.
172                @remarks
173                        You can use this method to set which buffers are cleared
174                        (if any) before rendering every frame.
175        @param clear Whether or not to clear any buffers
176                @param buffers One or more values from FrameBufferType denoting
177                        which buffers to clear, if clear is set to true. Note you should
178                        not clear the stencil buffer here unless you know what you're doing.
179         */
180        void setClearEveryFrame(bool clear, unsigned int buffers = FBT_COLOUR | FBT_DEPTH);
181
182        /** Determines if the viewport is cleared before every frame.
183        */
184        bool getClearEveryFrame(void) const;
185
186                /** Gets which buffers are to be cleared each frame. */
187        unsigned int getClearBuffers(void) const;
188
189                /** Set the material scheme which the viewport should use.
190                @remarks
191                        This allows you to tell the system to use a particular
192                        material scheme when rendering this viewport, which can
193                        involve using different techniques to render your materials.
194                @see Technique::setSchemeName
195                */
196                void setMaterialScheme(const String& schemeName)
197                { mMaterialSchemeName = schemeName; }
198               
199                /** Get the material scheme which the viewport should use.
200                */
201                const String& getMaterialScheme(void) const
202                { return mMaterialSchemeName; }
203
204                /** Access to actual dimensions (based on target size).
205        */
206        void getActualDimensions(
207            int &left, int &top, int &width, int &height ) const;
208
209        bool _isUpdated(void) const;
210        void _clearUpdatedFlag(void);
211
212        /** Gets the number of rendered faces in the last update.
213        */
214        unsigned int _getNumRenderedFaces(void) const;
215
216        /** Tells this viewport whether it should display Overlay objects.
217        @remarks
218            Overlay objects are layers which appear on top of the scene. They are created via
219            SceneManager::createOverlay and every viewport displays these by default.
220            However, you probably don't want this if you're using multiple viewports,
221            because one of them is probably a picture-in-picture which is not supposed to
222            have overlays of it's own. In this case you can turn off overlays on this viewport
223            by calling this method.
224        @param enabled If true, any overlays are displayed, if false they are not.
225        */
226        void setOverlaysEnabled(bool enabled);
227
228        /** Returns whether or not Overlay objects (created in the SceneManager) are displayed in this
229            viewport. */
230        bool getOverlaysEnabled(void) const;
231
232        /** Tells this viewport whether it should display skies.
233        @remarks
234            Skies are layers which appear on background of the scene. They are created via
235            SceneManager::setSkyBox, SceneManager::setSkyPlane and SceneManager::setSkyDome and
236            every viewport displays these by default. However, you probably don't want this if
237            you're using multiple viewports, because one of them is probably a picture-in-picture
238            which is not supposed to have skies of it's own. In this case you can turn off skies
239            on this viewport by calling this method.
240        @param enabled If true, any skies are displayed, if false they are not.
241        */
242        void setSkiesEnabled(bool enabled);
243
244        /** Returns whether or not skies (created in the SceneManager) are displayed in this
245            viewport. */
246        bool getSkiesEnabled(void) const;
247
248        /** Tells this viewport whether it should display shadows.
249        @remarks
250            This setting enables you to disable shadow rendering for a given viewport. The global
251                        shadow technique set on SceneManager still controls the type and nature of shadows,
252                        but this flag can override the setting so that no shadows are rendered for a given
253                        viewport to save processing time where they are not required.
254        @param enabled If true, any shadows are displayed, if false they are not.
255        */
256        void setShadowsEnabled(bool enabled);
257
258        /** Returns whether or not shadows (defined in the SceneManager) are displayed in this
259            viewport. */
260        bool getShadowsEnabled(void) const;
261
262                /** Sets the use of a custom RenderQueueInvocationSequence for
263                        rendering this target.
264                @remarks
265                        RenderQueueInvocationSequence instances are managed through Root. By
266                        setting this, you are indicating that you wish this RenderTarget to
267                        be updated using a custom sequence of render queue invocations, with
268                        potentially customised ordering and render state options. You should
269                        create the named sequence through Root first, then set the name here.
270                @param The name of the RenderQueueInvocationSequence to use. If you
271                        specify a blank string, behaviour will return to the defaul render
272                        queue management.
273                */
274                virtual void setRenderQueueInvocationSequenceName(const String& sequenceName);
275                /** Gets the name of the render queue invocation sequence for this target. */
276                virtual const String& getRenderQueueInvocationSequenceName(void) const;
277                /// Get the invocation sequence - will return null if using standard
278                RenderQueueInvocationSequence* _getRenderQueueInvocationSequence(void);
279
280    protected:
281        Camera* mCamera;
282        RenderTarget* mTarget;
283        // Relative dimensions, irrespective of target dimensions (0..1)
284        float mRelLeft, mRelTop, mRelWidth, mRelHeight;
285        // Actual dimensions, based on target dimensions
286        int mActLeft, mActTop, mActWidth, mActHeight;
287        /// ZOrder
288        int mZOrder;
289        /// Background options
290        ColourValue mBackColour;
291        bool mClearEveryFrame;
292                unsigned int mClearBuffers;
293        bool mUpdated;
294        bool mShowOverlays;
295        bool mShowSkies;
296                bool mShowShadows;
297                // Render queue invocation sequence name
298                String mRQSequenceName;
299                RenderQueueInvocationSequence* mRQSequence;
300                /// Material scheme
301                String mMaterialSchemeName;
302    };
303
304}
305
306#endif
Note: See TracBrowser for help on using the repository browser.