BGE update: helper functions for VideoTexture render to texture feature.
[blender.git] / source / gameengine / Rasterizer / RAS_FramingManager.h
1 /**
2  * $Id$
3  *
4  * ***** BEGIN GPL LICENSE BLOCK *****
5  *
6  * This program is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU General Public License
8  * as published by the Free Software Foundation; either version 2
9  * of the License, or (at your option) any later version.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14  * GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License
17  * along with this program; if not, write to the Free Software Foundation,
18  * Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
19  *
20  * The Original Code is Copyright (C) 2001-2002 by NaN Holding BV.
21  * All rights reserved.
22  *
23  * The Original Code is: all of this file.
24  *
25  * Contributor(s): none yet.
26  *
27  * ***** END GPL LICENSE BLOCK *****
28  */
29 #ifndef RAS_FRAMINGMANAGER_H
30 #define RAS_FRAMINGMANAGER_H
31
32 class RAS_Rect;
33
34 /**
35  * @section RAS_FrameSettings
36  * This is a value type describing the framing used
37  * by a particular scene in the game engine.
38  * Each KX_Scene contains a RAS_FrameSetting describing
39  * how the frustum and viewport are to be modified 
40  * depending on the canvas size.
41  *
42  * e_frame_scale means that the viewport is set to the current
43  * canvas size. If the view frustum aspect ratio is different 
44  * to the canvas aspect this will lead to stretching.
45  *
46  * e_frame_extend means that the best fit viewport will be 
47  * computed based upon the design aspect ratio
48  * and the view frustum will be adjusted so that 
49  * more of the scene is visible.
50  *
51  * e_frame_bars means that the best fit viewport will be
52  * be computed based upon the design aspect ratio.
53  */
54
55 class RAS_FrameSettings 
56 {
57 public :
58
59         /**
60          * enum defining the policy to use 
61          * in each axis.
62          */
63         enum RAS_FrameType {
64                 e_frame_scale,
65                 e_frame_extend,
66                 e_frame_bars
67         };
68         
69         /**
70          * Contructor
71          */
72
73         RAS_FrameSettings(
74                 RAS_FrameType frame_type,
75                 float bar_r,
76                 float bar_g,
77                 float bar_b,
78                 unsigned int design_aspect_width,
79                 unsigned int design_aspect_height 
80         ):
81                 m_frame_type(frame_type),
82                 m_bar_r(bar_r),
83                 m_bar_g(bar_g),
84                 m_bar_b(bar_b),
85                 m_design_aspect_width(design_aspect_width),
86                 m_design_aspect_height(design_aspect_height)
87         {
88         };
89
90         RAS_FrameSettings(
91         ):
92                 m_frame_type(e_frame_scale),
93                 m_bar_r(0),
94                 m_bar_g(0),
95                 m_bar_b(0),
96                 m_design_aspect_width(1),
97                 m_design_aspect_height(1)
98         {
99         };
100
101         /**
102          * Accessors
103          */
104
105         const
106                 RAS_FrameType &         
107         FrameType(
108         ) const {
109                 return m_frame_type;
110         };
111
112                 void
113         SetFrameType(
114                 RAS_FrameType type
115         ) {
116                 m_frame_type = type;
117         };
118         
119                 float
120         BarRed(
121         ) const {
122                 return m_bar_r;
123         };
124                 
125                 float
126         BarGreen(
127         ) const {
128                 return m_bar_g;
129         };
130
131                 float
132         BarBlue(
133         ) const {
134                 return m_bar_b;
135         };
136
137                 unsigned int
138         DesignAspectWidth(
139         ) const {
140                 return m_design_aspect_width;   
141         };
142
143                 unsigned int
144         DesignAspectHeight(
145         ) const {
146                 return m_design_aspect_height;  
147         };
148
149 private :
150
151         RAS_FrameType m_frame_type;
152         float m_bar_r;
153         float m_bar_g;
154         float m_bar_b;
155         unsigned int m_design_aspect_width;
156         unsigned int m_design_aspect_height;
157 }; 
158
159 struct RAS_FrameFrustum
160 {
161         float camnear,camfar;
162         float x1,y1;
163         float x2,y2;
164 };      
165
166
167 /**
168  * @section RAS_FramingManager
169  * This class helps to compute a view frustum
170  * and a viewport rectangle given the 
171  * above settings and a description of the 
172  * current canvas dimensions.
173  *
174  * You do not have to instantiate this class
175  * directly, it only contains static helper functions
176  */
177
178 class RAS_FramingManager
179 {
180 public :
181
182         /**
183          * Compute a viewport given
184          * a RAS_FrameSettings and a description of the
185          * canvas.
186          */
187
188         static
189                 void
190         ComputeViewport(
191                 const RAS_FrameSettings &settings,
192                 const RAS_Rect &availableViewport,
193                 RAS_Rect &viewport
194         );
195
196         
197         /**
198          * compute a frustrum given a valid viewport,
199          * RAS_FrameSettings, canvas description 
200          * and camera description
201          */
202
203         static
204                 void
205         ComputeFrustum(
206                 const RAS_FrameSettings &settings,
207                 const RAS_Rect &availableViewport,
208                 const RAS_Rect &viewport,
209                 const float lens,
210                 const float camnear,
211                 const float camfar,
212                 RAS_FrameFrustum &frustum
213         );
214
215         static
216                 void
217         ComputeDefaultFrustum(
218                 const float camnear,
219                 const float camfar,
220                 const float lens,
221                 const float design_aspect_ratio,
222                 RAS_FrameFrustum & frustum
223         );      
224
225 private :
226
227         static
228                 void
229         ComputeBestFitViewRect(
230                 const RAS_Rect &availableViewport,
231                 const float design_aspect_ratio,
232                 RAS_Rect &viewport
233         );
234
235
236
237         /**
238          * Private constructor - this class is not meant
239          * for instanciation.
240          */
241
242         RAS_FramingManager(
243         );
244
245         RAS_FramingManager(
246                 const RAS_FramingManager &
247         );
248 };              
249                 
250 #endif
251