Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/ogre_src_v1-9-0/OgreMain/include/OgreViewport.h @ 148

Last change on this file since 148 was 148, checked in by patricwi, 6 years ago

Added new dependencies for ogre1.9 and cegui0.8

File size: 16.7 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-2013 Torus Knot Software Ltd
8
9Permission is hereby granted, free of charge, to any person obtaining a copy
10of this software and associated documentation files (the "Software"), to deal
11in the Software without restriction, including without limitation the rights
12to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
13copies of the Software, and to permit persons to whom the Software is
14furnished to do so, subject to the following conditions:
15
16The above copyright notice and this permission notice shall be included in
17all copies or substantial portions of the Software.
18
19THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
22AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
23LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
24OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
25THE SOFTWARE.
26-----------------------------------------------------------------------------
27*/
28#ifndef __Viewport_H__
29#define __Viewport_H__
30
31#include "OgrePrerequisites.h"
32#include "OgreCommon.h"
33#include "OgreColourValue.h"
34#include "OgreFrustum.h"
35#include "OgreHeaderPrefix.h"
36
37namespace Ogre {
38        /** \addtogroup Core
39        *  @{
40        */
41        /** \addtogroup RenderSystem
42        *  @{
43        */
44        /** An abstraction of a viewport, i.e. a rendering region on a render
45        target.
46        @remarks
47            A viewport is the meeting of a camera and a rendering surface -
48            the camera renders the scene from a viewpoint, and places its
49            results into some subset of a rendering target, which may be the
50            whole surface or just a part of the surface. Each viewport has a
51            single camera as source and a single target as destination. A
52            camera only has 1 viewport, but a render target may have several.
53            A viewport also has a Z-order, i.e. if there is more than one
54            viewport on a single render target and they overlap, one must
55            obscure the other in some predetermined way.
56    */
57        class _OgreExport Viewport : public ViewportAlloc
58    {
59    public:
60                /** Listener interface so you can be notified of Viewport changes. */
61                class _OgreExport Listener
62                {
63                public:
64                        virtual ~Listener() {}
65
66                        /** Notification of when a new camera is set to target listening Viewport. */
67                        virtual void viewportCameraChanged(Viewport* viewport) {}
68
69                        /** Notification of when target listening Viewport's dimensions changed. */
70                        virtual void viewportDimensionsChanged(Viewport* viewport) {}
71
72                        /** Notification of when target listening Viewport's is destroyed. */
73                        virtual void viewportDestroyed(Viewport* viewport) {}
74                };
75
76        /** The usual constructor.
77            @param camera
78                Pointer to a camera to be the source for the image.
79            @param target
80                Pointer to the render target to be the destination
81                for the rendering.
82            @param left, top, width, height
83                Dimensions of the viewport, expressed as a value between
84                0 and 1. This allows the dimensions to apply irrespective of
85                changes in the target's size: e.g. to fill the whole area,
86                values of 0,0,1,1 are appropriate.
87            @param ZOrder
88                Relative Z-order on the target. Lower = further to
89                the front.
90        */
91        Viewport(
92            Camera* camera,
93            RenderTarget* target,
94            Real left, Real top,
95            Real width, Real height,
96            int ZOrder);
97
98        /** Default destructor.
99        */
100        virtual ~Viewport();
101
102        /** Notifies the viewport of a possible change in dimensions.
103            @remarks
104                Used by the target to update the viewport's dimensions
105                (usually the result of a change in target size).
106            @note
107                Internal use by Ogre only.
108        */
109        void _updateDimensions(void);
110
111        /** Instructs the viewport to updates its contents.
112        */
113        void update(void);
114               
115                /** Instructs the viewport to clear itself, without performing an update.
116                 @remarks
117                        You would not normally call this method when updating the viewport,
118                        since the viewport usually clears itself when updating anyway (@see
119                    Viewport::setClearEveryFrame). However, if you wish you have the
120                        option of manually clearing the frame buffer (or elements of it)
121                    using this method.
122                 @param buffers Bitmask identifying which buffer elements to clear
123                 @param colour The colour value to clear to, if FBT_COLOUR is included
124                 @param depth The depth value to clear to, if FBT_DEPTH is included
125                 @param stencil The stencil value to clear to, if FBT_STENCIL is included
126                */
127                void clear(unsigned int buffers = FBT_COLOUR | FBT_DEPTH,
128                                   const ColourValue& colour = ColourValue::Black, 
129                                   Real depth = 1.0f, unsigned short stencil = 0);
130
131        /** Retrieves a pointer to the render target for this viewport.
132        */
133        RenderTarget* getTarget(void) const;
134
135        /** Retrieves a pointer to the camera for this viewport.
136        */
137        Camera* getCamera(void) const;
138
139        /** Sets the camera to use for rendering to this viewport. */
140        void setCamera(Camera* cam);
141
142        /** Gets the Z-Order of this viewport. */
143                int getZOrder(void) const;
144                /** Gets one of the relative dimensions of the viewport,
145            a value between 0.0 and 1.0.
146        */
147        Real getLeft(void) const;
148
149        /** Gets one of the relative dimensions of the viewport, a value
150            between 0.0 and 1.0.
151        */
152        Real getTop(void) const;
153
154        /** Gets one of the relative dimensions of the viewport, a value
155            between 0.0 and 1.0.
156        */
157
158        Real getWidth(void) const;
159        /** Gets one of the relative dimensions of the viewport, a value
160            between 0.0 and 1.0.
161        */
162
163        Real getHeight(void) const;
164        /** Gets one of the actual dimensions of the viewport, a value in
165            pixels.
166        */
167
168        int getActualLeft(void) const;
169        /** Gets one of the actual dimensions of the viewport, a value in
170            pixels.
171        */
172
173        int getActualTop(void) const;
174        /** Gets one of the actual dimensions of the viewport, a value in
175            pixels.
176        */
177        int getActualWidth(void) const;
178        /** Gets one of the actual dimensions of the viewport, a value in
179            pixels.
180        */
181
182        int getActualHeight(void) const;
183
184        /** Sets the dimensions (after creation).
185            @param
186                left Left point of viewport.
187            @param
188                top Top point of the viewport.
189            @param
190                width Width of the viewport.
191            @param
192                height Height of the viewport.
193            @note Dimensions relative to the size of the target,
194                represented as real values between 0 and 1. i.e. the full
195                target area is 0, 0, 1, 1.
196        */
197        void setDimensions(Real left, Real top, Real width, Real height);
198
199        /** Set the orientation mode of the viewport.
200        */
201        void setOrientationMode(OrientationMode orientationMode, bool setDefault = true);
202
203        /** Get the orientation mode of the viewport.
204        */
205        OrientationMode getOrientationMode() const;
206
207        /** Set the initial orientation mode of viewports.
208        */
209        static void setDefaultOrientationMode(OrientationMode orientationMode);
210
211        /** Get the initial orientation mode of viewports.
212        */
213        static OrientationMode getDefaultOrientationMode();
214
215        /** Sets the initial background colour of the viewport (before
216            rendering).
217        */
218        void setBackgroundColour(const ColourValue& colour);
219
220        /** Gets the background colour.
221        */
222        const ColourValue& getBackgroundColour(void) const;
223
224                /** Sets the initial depth buffer value of the viewport (before
225            rendering). Default is 1
226        */
227        void setDepthClear( Real depth );
228
229        /** Gets the default depth buffer value to which the viewport is cleared.
230        */
231        Real getDepthClear(void) const;
232
233        /** Determines whether to clear the viewport before rendering.
234                @remarks
235                        You can use this method to set which buffers are cleared
236                        (if any) before rendering every frame.
237        @param clear Whether or not to clear any buffers
238                @param buffers One or more values from FrameBufferType denoting
239                        which buffers to clear, if clear is set to true. Note you should
240                        not clear the stencil buffer here unless you know what you're doing.
241         */
242        void setClearEveryFrame(bool clear, unsigned int buffers = FBT_COLOUR | FBT_DEPTH);
243
244        /** Determines if the viewport is cleared before every frame.
245        */
246        bool getClearEveryFrame(void) const;
247
248                /** Gets which buffers are to be cleared each frame. */
249        unsigned int getClearBuffers(void) const;
250
251                /** Sets whether this viewport should be automatically updated
252                        if Ogre's rendering loop or RenderTarget::update is being used.
253        @remarks
254            By default, if you use Ogre's own rendering loop (Root::startRendering)
255            or call RenderTarget::update, all viewports are updated automatically.
256            This method allows you to control that behaviour, if for example you
257                        have a viewport which you only want to update periodically.
258        @param autoupdate If true, the viewport is updated during the automatic
259            render loop or when RenderTarget::update() is called. If false, the
260            viewport is only updated when its update() method is called explicitly.
261        */
262                void setAutoUpdated(bool autoupdate);
263                /** Gets whether this viewport is automatically updated if
264                        Ogre's rendering loop or RenderTarget::update is being used.
265        */
266                bool isAutoUpdated() const;
267
268                /** Set the material scheme which the viewport should use.
269                @remarks
270                        This allows you to tell the system to use a particular
271                        material scheme when rendering this viewport, which can
272                        involve using different techniques to render your materials.
273                @see Technique::setSchemeName
274                */
275                void setMaterialScheme(const String& schemeName)
276                { mMaterialSchemeName = schemeName; }
277               
278                /** Get the material scheme which the viewport should use.
279                */
280                const String& getMaterialScheme(void) const
281                { return mMaterialSchemeName; }
282
283                /** Access to actual dimensions (based on target size).
284        */
285        void getActualDimensions(
286            int &left, int &top, int &width, int &height ) const;
287
288        bool _isUpdated(void) const;
289        void _clearUpdatedFlag(void);
290
291        /** Gets the number of rendered faces in the last update.
292        */
293        unsigned int _getNumRenderedFaces(void) const;
294
295        /** Gets the number of rendered batches in the last update.
296        */
297        unsigned int _getNumRenderedBatches(void) const;
298
299        /** Tells this viewport whether it should display Overlay objects.
300        @remarks
301            Overlay objects are layers which appear on top of the scene. They are created via
302            SceneManager::createOverlay and every viewport displays these by default.
303            However, you probably don't want this if you're using multiple viewports,
304            because one of them is probably a picture-in-picture which is not supposed to
305            have overlays of it's own. In this case you can turn off overlays on this viewport
306            by calling this method.
307        @param enabled If true, any overlays are displayed, if false they are not.
308        */
309        void setOverlaysEnabled(bool enabled);
310
311        /** Returns whether or not Overlay objects (created in the SceneManager) are displayed in this
312            viewport. */
313        bool getOverlaysEnabled(void) const;
314
315        /** Tells this viewport whether it should display skies.
316        @remarks
317            Skies are layers which appear on background of the scene. They are created via
318            SceneManager::setSkyBox, SceneManager::setSkyPlane and SceneManager::setSkyDome and
319            every viewport displays these by default. However, you probably don't want this if
320            you're using multiple viewports, because one of them is probably a picture-in-picture
321            which is not supposed to have skies of it's own. In this case you can turn off skies
322            on this viewport by calling this method.
323        @param enabled If true, any skies are displayed, if false they are not.
324        */
325        void setSkiesEnabled(bool enabled);
326
327        /** Returns whether or not skies (created in the SceneManager) are displayed in this
328            viewport. */
329        bool getSkiesEnabled(void) const;
330
331        /** Tells this viewport whether it should display shadows.
332        @remarks
333            This setting enables you to disable shadow rendering for a given viewport. The global
334                        shadow technique set on SceneManager still controls the type and nature of shadows,
335                        but this flag can override the setting so that no shadows are rendered for a given
336                        viewport to save processing time where they are not required.
337        @param enabled If true, any shadows are displayed, if false they are not.
338        */
339        void setShadowsEnabled(bool enabled);
340
341        /** Returns whether or not shadows (defined in the SceneManager) are displayed in this
342            viewport. */
343        bool getShadowsEnabled(void) const;
344
345
346                /** Sets a per-viewport visibility mask.
347                @remarks
348                        The visibility mask is a way to exclude objects from rendering for
349                        a given viewport. For each object in the frustum, a check is made
350                        between this mask and the objects visibility flags
351                        (@see MovableObject::setVisibilityFlags), and if a binary 'and'
352                        returns zero, the object will not be rendered.
353                */
354                void setVisibilityMask(uint32 mask) { mVisibilityMask = mask; }
355
356                /** Gets a per-viewport visibility mask.
357                @see Viewport::setVisibilityMask
358                */
359                uint getVisibilityMask(void) const { return mVisibilityMask; }
360
361                /** Sets the use of a custom RenderQueueInvocationSequence for
362                        rendering this target.
363                @remarks
364                        RenderQueueInvocationSequence instances are managed through Root. By
365                        setting this, you are indicating that you wish this RenderTarget to
366                        be updated using a custom sequence of render queue invocations, with
367                        potentially customised ordering and render state options. You should
368                        create the named sequence through Root first, then set the name here.
369                @param sequenceName The name of the RenderQueueInvocationSequence to use. If you
370                        specify a blank string, behaviour will return to the default render
371                        queue management.
372                */
373                virtual void setRenderQueueInvocationSequenceName(const String& sequenceName);
374                /** Gets the name of the render queue invocation sequence for this target. */
375                virtual const String& getRenderQueueInvocationSequenceName(void) const;
376                /// Get the invocation sequence - will return null if using standard
377                RenderQueueInvocationSequence* _getRenderQueueInvocationSequence(void);
378
379        /** Convert oriented input point coordinates to screen coordinates. */
380        void pointOrientedToScreen(const Vector2 &v, int orientationMode, Vector2 &outv);
381        void pointOrientedToScreen(Real orientedX, Real orientedY, int orientationMode,
382                                   Real &screenX, Real &screenY);
383
384                /// Add a listener to this camera
385                void addListener(Listener* l);
386                /// Remove a listener to this camera
387                void removeListener(Listener* l);
388
389    protected:
390        Camera* mCamera;
391        RenderTarget* mTarget;
392        /// Relative dimensions, irrespective of target dimensions (0..1)
393        float mRelLeft, mRelTop, mRelWidth, mRelHeight;
394        /// Actual dimensions, based on target dimensions
395        int mActLeft, mActTop, mActWidth, mActHeight;
396        /// Z-order
397        int mZOrder;
398        /// Background options
399        ColourValue mBackColour;
400                Real mDepthClearValue;
401        bool mClearEveryFrame;
402                unsigned int mClearBuffers;
403        bool mUpdated;
404        bool mShowOverlays;
405        bool mShowSkies;
406                bool mShowShadows;
407                uint32 mVisibilityMask;
408                // Render queue invocation sequence name
409                String mRQSequenceName;
410                RenderQueueInvocationSequence* mRQSequence;
411                /// Material scheme
412                String mMaterialSchemeName;
413        /// Viewport orientation mode
414        OrientationMode mOrientationMode;
415        static OrientationMode mDefaultOrientationMode;
416
417                /// Automatic rendering on/off
418                bool mIsAutoUpdated;
419
420                typedef vector<Listener*>::type ListenerList;
421                ListenerList mListeners;
422    };
423        /** @} */
424        /** @} */
425
426}
427
428#include "OgreHeaderSuffix.h"
429
430#endif
Note: See TracBrowser for help on using the repository browser.