GL Studio C++ Runtime API
runtime_display_frame.h
Go to the documentation of this file.
1 /*! \file
2  \brief The disti::RuntimeDisplayFrame class, parent class of all DisplayFrames used in runtime code.
3 
4  \par Copyright Information
5 
6  Copyright (c) 2017 by The DiSTI Corporation.<br>
7  11301 Corporate Blvd; Suite 100<br>
8  Orlando, Florida 32817<br>
9  USA<br>
10  <br>
11  All rights reserved.<br>
12 
13  This Software contains proprietary trade secrets of DiSTI and may not be
14 reproduced, in whole or part, in any form, or by any means of electronic,
15 mechanical, or otherwise, without the written permission of DiSTI. Said
16 permission may be derived through the purchase of applicable DiSTI product
17 licenses which detail the distribution rights of this content and any
18 Derivative Works based on this or other copyrighted DiSTI Software.
19 
20  NO WARRANTY. THE SOFTWARE IS PROVIDED "AS-IS," WITHOUT WARRANTY OF ANY KIND,
21 AND ANY USE OF THIS SOFTWARE PRODUCT IS AT YOUR OWN RISK. TO THE MAXIMUM EXTENT
22 PERMITTED BY APPLICABLE LAW, DISTI AND ITS SUPPLIERS DISCLAIM ALL WARRANTIES
23 AND CONDITIONS, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
24 IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY AND/OR FITNESS FOR A
25 PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT, WITH REGARD TO THE SOFTWARE.
26 
27  LIMITATION OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW,
28 IN NO EVENT SHALL DISTI OR ITS SUPPLIERS BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
29 INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION,
30 DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS
31 INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR
32 INABILITY TO USE THE SOFTWARE, EVEN IF DISTI HAS BEEN ADVISED OF THE POSSIBILITY
33 OF SUCH DAMAGES. DISTI'S ENTIRE LIABILITY AND YOUR EXCLUSIVE REMEDY SHALL NOT
34 EXCEED FIVE DOLLARS (US$5.00).
35 
36  The aforementioned terms and restrictions are governed by the laws of the
37 State of Florida and the United States of America.
38 
39 */
40 #ifndef _RUNTIME_DISPLAY_FRAME_H
41 #define _RUNTIME_DISPLAY_FRAME_H
42 
43 #include "display_frame.h"
44 #include "gls_include.h"
45 #include "timer.h"
46 
47 namespace disti
48 {
49 class Statistics;
50 class GlsEyePoint;
51 
52 /** Provides basic support for runtime display frames */
54  , virtual public GlsPainter
55 {
56 private:
57  Statistics* _stats; /**< Keeps track of draw/predraw/calculate timing statistics */
58 protected:
59  Timer _frameTimer; /**< Timer used for scheduling */
60  Timer& frameTimer; /** for backwards compatibility */
61  float _smoothedFrameDelay; /**< Frame interval, smoothed based on actual draw performance */
62 
63  /** For better control over clipping and field of view, use a GlsEyePoint, but some limited functionality is available here */
64  float _width_offset; /**< Current "width" offset of window. Used for panning of display horizontally in ortho mode. */
65  float _height_offset; /**< Current "height" offset of window. Used for panning of display vertically in ortho mode. */
66  Vector _viewOffset;
67  float _depthFactor; /**< Used for auto calculations */
68  double _fov; /**< Field Of View. If 0.0 (the default), fov will be auto calculated. */
69  double _nearZ; /**< Near clipping plane. Only meaningful if _autoCalcNearZ is false */
70  bool _autoCalcNearZ; /**< When true a _nearZ is automatically calculated. */
71  double _farZ; /**< Far clipping plane. Only meaningfull if _autoCalcVarZ is false */
72  bool _autoCalcFarZ; /**< When true a _farZ is automatically calculated. */
73  int _current_view; /**< Current view of the canvas (e.g., ortho, perspective, eyepoint) */
74 
75  std::string _name; /**< The title of this display frame's window, if applicable */
76  float _scale; /**< Scale of the window */
77  unsigned int frameInterval; /**< The frame interval in microSeconds (inverse of frame rate) */
78  GlsEyePoint* _currentEyePoint; /**< The current eyepoint for viewing the scene */
79  bool _redraw; /**< Flag indicating if the window should be redrawn */
80 
81 public:
82  /** Ctor for RuntimeDisplayFrame
83  * \param name The title of the display frame. Shown in the window title bar.
84  * \param width The width of the display frame window, in pixels.
85  * \param height The height of the display frame window, in pixels.
86  */
87  GLS_EXPORT RuntimeDisplayFrame( const char* name, int width, int height );
88 
89  /** Dtor for RuntimeDisplayFrame */
90  virtual GLS_EXPORT ~RuntimeDisplayFrame();
91 
92  /** Clears the window associated with the display frame.
93  * The current _clearBitfield is used */
94  virtual GLS_EXPORT void Clear( void );
95 
96  /** \return The current eyepoint for the display frame */
97  virtual GLS_EXPORT GlsEyePoint* CurrentEyePoint();
98 
99  /** Sets the current eyepoint for the display frame.
100  * \param eye The eyepoint to use for the display frame.
101  */
102  virtual GLS_EXPORT void CurrentEyePoint( GlsEyePoint* eye );
103 
104  /** Set the scale for the display frame.
105  * \param scale The new scale factor. Must be non-zero. A value of zero will be ignored.
106  */
107  virtual GLS_EXPORT void Scale( float scale );
108 
109  /** \return The current scale for the display frame */
110  virtual GLS_EXPORT float Scale( void );
111 
112  /** Handles keyboard and mouse events and dispatches them to the display objects.
113  * \param ev A display event
114  * \return Pointer to the object that handled the event or NULL if no object handled it.
115  */
116  virtual GLS_EXPORT DisplayObject* handle( DisplayEvent* ev );
117 
118  /** Sets the background color of the window to the given value
119  * \param r New red color (0-255 range)
120  * \param g New green color (0-255 range)
121  * \param b New blue color (0-255 range)
122  * \param a New alpha color (0-255 range)
123  */
124  virtual GLS_EXPORT void BackgroundColor( unsigned char r, unsigned char g, unsigned char b, unsigned char a );
125 
126  /** Gets the background color of the window to the given value
127  * \param r Gets red color (0-255 range)
128  * \param g Gets green color (0-255 range)
129  * \param b Gets blue color (0-255 range)
130  * \param a Gets alpha color (0-255 range)
131  */
132  virtual GLS_EXPORT void GetBackgroundColor( unsigned char& r, unsigned char& g, unsigned char& b, unsigned char& a );
133 
134  /** Sets the background color of the window to the given value
135  * \param color The new color
136  */
137  virtual GLS_EXPORT void BackgroundColor( const GlsColor& color );
138 
139  /** Gets the title(name) of this display frame
140  * \return The name of this display frame
141  */
142  GLS_EXPORT const char* Name( void );
143 
144  /** Sets the name(title) for this display frame
145  * \param name The new title for the display frame
146  */
147  GLS_EXPORT void Name( char* name );
148 
149  /** Gets the background color of the window to the given value
150  * \return The background color
151  */
152  virtual GLS_EXPORT GlsColor BackgroundColor( void );
153 
154  /** Returns the Frame Interval in microseconds
155  * \return The Frame Interval in microseconds
156  */
157  virtual GLS_EXPORT int FrameInterval( void );
158 
159  /** Sets the target Frame Interval in microseconds
160  * \param interval The frame interval in microseconds
161  */
162  virtual GLS_EXPORT void FrameInterval( int interval );
163 
164  /** Creates and returns a pointer to a statistics object
165  * \return A pointer to the statistics object
166  */
167  virtual GLS_EXPORT Statistics* Stats();
168 
169  /** Part of display frame statistics, for recording time used in Calculate() */
170  virtual GLS_EXPORT void RecordCalculateStart( void );
171 
172  /** Part of display frame statistics, for recording time used in Calculate() */
173  virtual GLS_EXPORT void RecordCalculateEnd( void );
174 
175  /** Call this before deleting objects which may be being kept
176  * by the drag or focus objects */
177  virtual GLS_EXPORT void ClearDragAndFocus();
178 
179  /** Redraws the scene if the scene has changed since the last frame, and also calls WaitForNextFrame to ensure we are not drawing
180  * faster than the set frame interval allows.
181  * \returns true if we the scene was redrawn. Generally used to determine if the buffers need to be swapped
182  */
183  virtual GLS_EXPORT bool UpdateAnimate();
184 
185  /** Redraw the window at the Hz rate set for the DisplayFrame, or at least
186  * try to. We might be slower if the hardware can't keep up.
187  * \return on desktop runtimes, returns true if any window is still open. On ES runtimes always returns true.
188  */
189  virtual GLS_EXPORT bool FrameAnimate();
190 
191  /** Sleeps based on the Hz rate set for the DisplayFrame. */
192  virtual GLS_EXPORT void WaitForNextFrame();
193 
194  /** Redraws the window, using the platform specific mechanism. Place holder for base class implementations. Simple implementations may draw directly, while
195  * implementations that use a window manager may tell the window manager to redraw.
196  */
197  virtual GLS_EXPORT void Paint(){};
198 
199  /** Pans the display horizontally
200  * \param offset The new X position at the center of the window
201  */
202  virtual GLS_EXPORT void WidthOffset( float offset );
203 
204  /** Gets the horizontal position of the display at the center of the window
205  * \return The X position at the center of the window
206  */
207  virtual GLS_EXPORT float WidthOffset( void );
208 
209  /** Pans the display vertically
210  * \param offset The new Y position of the center of the window
211  */
212  virtual GLS_EXPORT void HeightOffset( float offset );
213 
214  /** Gets the vertical position of the display at the center of the window
215  * \return The Y position at the center of the window
216  */
217  virtual GLS_EXPORT float HeightOffset( void );
218 
219  /** Sets the Depth Factor for the window
220  * \param factor The depth factor. Used for autocalculating clipping planes */
221  virtual GLS_EXPORT void DepthFactor( float factor );
222 
223  /** Gets the Depth Factor for the window
224  * \return The current depth factor
225  */
226  virtual GLS_EXPORT float DepthFactor();
227 
228  /** Sets the FOV (Field of View) for the window. If fov is set to 0.0, a reasonable FOV
229  * will be calculated based on width and height.
230  * \param fov New field of view in degrees
231  */
232  virtual GLS_EXPORT void FOV( double fov );
233 
234  /** Gets the FOV (Field of View) for the window.
235  * \return The current field of view in degrees
236  */
237  virtual GLS_EXPORT double FOV();
238 
239  /** Sets the current view mode for the window
240  * \param view The new view mode for the window.
241  * Acceptable view types are:
242  * [VIEW_EYEPOINT - The application will be viewed through an eyepoint]
243  * [VIEW_XY - The application will be viewed through a 2D orthographic view of the XY plane]
244  * [VIEW_PERSPECTIVE - The application will be viewed through a perspective projection]
245  */
246  virtual GLS_EXPORT void CurrentView( const int view ) { _current_view = view; }
247 
248  /** Gets the current view mode for the window.
249  * \return The current viewmode for the window (VIEW_EYEPOINT, VIEW_XY, VIEW_PERSPECTIVE)
250  */
251  virtual GLS_EXPORT int CurrentView( void ) const { return _current_view; }
252 
253  /** \see GlsPainter */
254  GLS_EXPORT void Invalidate() DISTI_METHOD_OVERRIDE;
255 
256  /** The background clear color */
257  GlsColor _backgroundColor; // DDH: This is public yet has an accessor method....should it be protected?
258 };
259 
260 } // namespace disti
261 
262 #endif
virtual void Clear(void)
virtual int CurrentView(void) const
Definition: runtime_display_frame.h:251
Definition: display_frame.h:85
virtual Statistics * Stats()
virtual float Scale(void)
virtual void Paint()
Definition: runtime_display_frame.h:197
float _depthFactor
Definition: runtime_display_frame.h:67
const char * Name(void)
std::string _name
Definition: runtime_display_frame.h:75
virtual float WidthOffset(void)
virtual float HeightOffset(void)
Definition: display.h:98
virtual DisplayObject * handle(DisplayEvent *ev)
RuntimeDisplayFrame(const char *name, int width, int height)
double _nearZ
Definition: runtime_display_frame.h:69
virtual GlsColor BackgroundColor(void)
The disti::Timer class. An OS portable timing class.
Definition: statistics.h:56
Definition: runtime_display_frame.h:53
virtual int FrameInterval(void)
double _fov
Definition: runtime_display_frame.h:68
virtual void CurrentView(const int view)
Definition: runtime_display_frame.h:246
A file for all GL Studio files to include.
float _smoothedFrameDelay
Definition: runtime_display_frame.h:61
bool _autoCalcNearZ
Definition: runtime_display_frame.h:70
virtual void GetBackgroundColor(unsigned char &r, unsigned char &g, unsigned char &b, unsigned char &a)
virtual float DepthFactor()
Definition: gls_painter.h:51
virtual void WaitForNextFrame()
virtual void RecordCalculateStart(void)
Definition: timer.h:66
float _height_offset
Definition: runtime_display_frame.h:65
bool _redraw
Definition: runtime_display_frame.h:79
float _width_offset
Definition: runtime_display_frame.h:64
Definition: gls_eyepoint.h:115
GlsColor _backgroundColor
Definition: runtime_display_frame.h:257
Definition: events.h:111
Definition: gls_color.h:53
bool _autoCalcFarZ
Definition: runtime_display_frame.h:72
unsigned int frameInterval
Definition: runtime_display_frame.h:77
Timer _frameTimer
Definition: runtime_display_frame.h:59
The disti::DisplayFrame class.
int _current_view
Definition: runtime_display_frame.h:73
float _scale
Definition: runtime_display_frame.h:76
Definition: vertex.h:83
virtual bool UpdateAnimate()
virtual GlsEyePoint * CurrentEyePoint()
virtual bool FrameAnimate()
virtual void RecordCalculateEnd(void)
Definition: bmpimage.h:46
double _farZ
Definition: runtime_display_frame.h:71
virtual void ClearDragAndFocus()
GlsEyePoint * _currentEyePoint
Definition: runtime_display_frame.h:78