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