GL Studio C++ Runtime API
runtime_display_frame.h
Go to the documentation of this file.
1/// \file runtime_display_frame.h
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/// 12249 Science Drive; Suite 300<br>
8/// Orlando, Florida 32826<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#ifndef DISTI_INCLUDED_RUNTIME_DISPLAY_FRAME_H
40#define DISTI_INCLUDED_RUNTIME_DISPLAY_FRAME_H
41
42#include "display_frame.h"
43#include "gls_include.h"
44#include "timer.h"
45
46namespace disti
47{
48class Statistics;
49class GlsEyePoint;
50
51/** Provides basic support for runtime display frames */
53 , virtual public GlsPainter
54{
55private:
56 Statistics* _stats; ///< Keeps track of draw/predraw/calculate timing statistics.
57protected:
58 Timer _frameTimer; ///< Timer used for scheduling.
59 Timer& frameTimer; ///< For backwards compatibility.
60 float _smoothedFrameDelay; ///< Frame interval, smoothed based on actual draw performance.
61
62 /// For better control over clipping and field of view, use a GlsEyePoint, but some limited functionality is available here.
63 float _width_offset; ///< Current "width" offset of window. Used for panning of display horizontally in ortho mode.
64 float _height_offset; ///< Current "height" offset of window. Used for panning of display vertically in ortho mode.
65 Vector _viewOffset; ///< Additional offset to apply to the modelview matrix.
66 float _depthFactor; ///< Used for auto calculations.
67 double _fov; ///< Field Of View. If 0.0 (the default), fov will be auto calculated.
68 double _nearZ; ///< Near clipping plane. Only meaningful if _autoCalcNearZ is false.
69 bool _autoCalcNearZ; ///< When true a _nearZ is automatically calculated.
70 double _farZ; ///< Far clipping plane. Only meaningfull if _autoCalcVarZ is false.
71 bool _autoCalcFarZ; ///< When true a _farZ is automatically calculated.
72 int _current_view; ///< Current view of the canvas (e.g., ortho, perspective, eyepoint).
73
74 std::string _name; ///< The title of this display frame's window, if applicable.
75 float _scale; ///< Scale of the window.
76 unsigned int frameInterval; ///< The frame interval in microSeconds (inverse of frame rate).
77 GlsEyePoint* _currentEyePoint; ///< The current eyepoint for viewing the scene.
78 bool _redraw; ///< Flag indicating if the window should be redrawn.
79
80public:
81 /** Ctor for RuntimeDisplayFrame
82 * \param name The title of the display frame. Shown in the window title bar.
83 * \param width The width of the display frame window, in pixels.
84 * \param height The height of the display frame window, in pixels.
85 */
86 GLS_EXPORT RuntimeDisplayFrame( const char* name, int width, int height );
87
88 /** Dtor for RuntimeDisplayFrame */
90
91 /** Clears the window associated with the display frame.
92 * The current _clearBitfield is used */
93 virtual GLS_EXPORT void Clear();
94
95 /** \return The current eyepoint for the display frame */
97
98 /** Sets the current eyepoint for the display frame.
99 * \param eye The eyepoint to use for the display frame.
100 */
102
103 /** Set the scale for the display frame.
104 * \param scale The new scale factor. Must be non-zero. A value of zero will be ignored.
105 */
106 virtual GLS_EXPORT void Scale( float scale );
107
108 /** \return The current scale for the display frame */
110
111 /** Handles keyboard and mouse events and dispatches them to the display objects.
112 * \param ev A display event
113 * \return Pointer to the object that handled the event or NULL if no object handled it.
114 */
116
117 /** Sets the background color of the window to the given value
118 * \param r New red color (0-255 range)
119 * \param g New green color (0-255 range)
120 * \param b New blue color (0-255 range)
121 * \param a New alpha color (0-255 range)
122 */
123 virtual GLS_EXPORT void BackgroundColor( unsigned char r, unsigned char g, unsigned char b, unsigned char a );
124
125 /** Gets the background color of the window to the given value
126 * \param r Gets red color (0-255 range)
127 * \param g Gets green color (0-255 range)
128 * \param b Gets blue color (0-255 range)
129 * \param a Gets alpha color (0-255 range)
130 */
131 virtual GLS_EXPORT void GetBackgroundColor( unsigned char& r, unsigned char& g, unsigned char& b, unsigned char& a );
132
133 /** Sets the background color of the window to the given value
134 * \param color The new color
135 */
136 virtual GLS_EXPORT void BackgroundColor( const GlsColor& color );
137
138 /** Gets the title(name) of this display frame
139 * \return The name of this display frame
140 */
141 GLS_EXPORT const char* Name();
142
143 /** Sets the name(title) for this display frame
144 * \param name The new title for the display frame
145 */
146 GLS_EXPORT void Name( char* name );
147
148 /** Gets the background color of the window to the given value
149 * \return The background color
150 */
152
153 /** Returns the Frame Interval in microseconds
154 * \return The Frame Interval in microseconds
155 */
157
158 /** Sets the target Frame Interval in microseconds
159 * \param interval The frame interval in microseconds
160 */
161 virtual GLS_EXPORT void FrameInterval( int interval );
162
163 /** Creates and returns a pointer to a statistics object
164 * \return A pointer to the statistics object
165 */
167
168 /** Part of display frame statistics, for recording time used in Calculate() */
170
171 /** Part of display frame statistics, for recording time used in Calculate() */
173
174 /** Call this before deleting objects which may be being kept
175 * by the drag or focus objects */
177
178 /** Redraws the scene if the scene has changed since the last frame, and also calls WaitForNextFrame to ensure we are not drawing
179 * faster than the set frame interval allows.
180 * \returns true if we the scene was redrawn. Generally used to determine if the buffers need to be swapped
181 */
182 virtual GLS_EXPORT bool UpdateAnimate();
183
184 /** Redraw the window at the Hz rate set for the DisplayFrame, or at least
185 * try to. We might be slower if the hardware can't keep up.
186 * \return on desktop runtimes, returns true if any window is still open. On ES runtimes always returns true.
187 */
188 virtual GLS_EXPORT bool FrameAnimate();
189
190 /** Sleeps based on the Hz rate set for the DisplayFrame. */
192
193 /** Redraws the window, using the platform specific mechanism. Place holder for base class implementations. Simple implementations may draw directly, while
194 * implementations that use a window manager may tell the window manager to redraw.
195 */
196 virtual void Paint(){};
197
198 /** Pans the display horizontally
199 * \param offset The new X position at the center of the window
200 */
201 virtual GLS_EXPORT void WidthOffset( float offset );
202
203 /** Gets the horizontal position of the display at the center of the window
204 * \return The X position at the center of the window
205 */
206 virtual GLS_EXPORT float WidthOffset();
207
208 /** Pans the display vertically
209 * \param offset The new Y position of the center of the window
210 */
211 virtual GLS_EXPORT void HeightOffset( float offset );
212
213 /** Gets the vertical position of the display at the center of the window
214 * \return The Y position at the center of the window
215 */
216 virtual GLS_EXPORT float HeightOffset();
217
218 /** Sets the Depth Factor for the window
219 * \param factor The depth factor. Used for autocalculating clipping planes */
220 virtual GLS_EXPORT void DepthFactor( float factor );
221
222 /** Gets the Depth Factor for the window
223 * \return The current depth factor
224 */
225 virtual GLS_EXPORT float DepthFactor();
226
227 /** Sets the FOV (Field of View) for the window. If fov is set to 0.0, a reasonable FOV
228 * will be calculated based on width and height.
229 * \param fov New field of view in degrees
230 */
231 virtual GLS_EXPORT void FOV( double fov );
232
233 /** Gets the FOV (Field of View) for the window.
234 * \return The current field of view in degrees
235 */
236 virtual GLS_EXPORT double FOV();
237
238 /** Sets the current view mode for the window
239 * \param view The new view mode for the window.
240 * Acceptable view types are:
241 * [VIEW_EYEPOINT - The application will be viewed through an eyepoint]
242 * [VIEW_XY - The application will be viewed through a 2D orthographic view of the XY plane]
243 * [VIEW_PERSPECTIVE - The application will be viewed through a perspective projection]
244 */
245 virtual void CurrentView( const int view ) { _current_view = view; }
246
247 /** Gets the current view mode for the window.
248 * \return The current viewmode for the window (VIEW_EYEPOINT, VIEW_XY, VIEW_PERSPECTIVE)
249 */
250 virtual int CurrentView() const { return _current_view; }
251
253
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
Definition: events.h:111
Definition: display_frame.h:86
Definition: display.h:95
Definition: gls_color.h:53
Definition: gls_eyepoint.h:116
Definition: gls_painter.h:50
Definition: runtime_display_frame.h:54
RuntimeDisplayFrame(const char *name, int width, int height)
virtual void FOV(double fov)
virtual void HeightOffset(float offset)
virtual void CurrentView(const int view)
Definition: runtime_display_frame.h:245
virtual void Paint()
Definition: runtime_display_frame.h:196
void ClearDragAndFocus() override
virtual bool UpdateAnimate()
virtual int CurrentView() const
Definition: runtime_display_frame.h:250
Timer & frameTimer
For backwards compatibility.
Definition: runtime_display_frame.h:59
void Invalidate() override
Notify the painter that the scene needs to be redrawn.
bool _autoCalcFarZ
When true a _farZ is automatically calculated.
Definition: runtime_display_frame.h:71
bool _autoCalcNearZ
When true a _nearZ is automatically calculated.
Definition: runtime_display_frame.h:69
float Scale() override
bool IsInvalidated() const override
virtual void RecordCalculateEnd()
float _depthFactor
Used for auto calculations.
Definition: runtime_display_frame.h:66
bool _redraw
Flag indicating if the window should be redrawn.
Definition: runtime_display_frame.h:78
float _height_offset
Current "height" offset of window. Used for panning of display vertically in ortho mode.
Definition: runtime_display_frame.h:64
virtual void RecordCalculateStart()
virtual float HeightOffset()
virtual Statistics * Stats()
double _farZ
Far clipping plane. Only meaningfull if _autoCalcVarZ is false.
Definition: runtime_display_frame.h:70
GlsEyePoint * _currentEyePoint
The current eyepoint for viewing the scene.
Definition: runtime_display_frame.h:77
int _current_view
Current view of the canvas (e.g., ortho, perspective, eyepoint).
Definition: runtime_display_frame.h:72
double _nearZ
Near clipping plane. Only meaningful if _autoCalcNearZ is false.
Definition: runtime_display_frame.h:68
virtual void Scale(float scale)
virtual void WaitForNextFrame()
double _fov
Field Of View. If 0.0 (the default), fov will be auto calculated.
Definition: runtime_display_frame.h:67
Timer _frameTimer
Timer used for scheduling.
Definition: runtime_display_frame.h:58
virtual float DepthFactor()
virtual DisplayObject * handle(DisplayEvent *ev)
std::string _name
The title of this display frame's window, if applicable.
Definition: runtime_display_frame.h:74
virtual GlsEyePoint * CurrentEyePoint()
float _width_offset
For better control over clipping and field of view, use a GlsEyePoint, but some limited functionality...
Definition: runtime_display_frame.h:63
virtual GlsColor BackgroundColor()
virtual void WidthOffset(float offset)
virtual void DepthFactor(float factor)
float _smoothedFrameDelay
Frame interval, smoothed based on actual draw performance.
Definition: runtime_display_frame.h:60
float _scale
Scale of the window.
Definition: runtime_display_frame.h:75
virtual void GetBackgroundColor(unsigned char &r, unsigned char &g, unsigned char &b, unsigned char &a)
GlsColor _backgroundColor
Definition: runtime_display_frame.h:257
Vector _viewOffset
Additional offset to apply to the modelview matrix.
Definition: runtime_display_frame.h:65
virtual void CurrentEyePoint(GlsEyePoint *eye)
virtual float WidthOffset()
virtual bool FrameAnimate()
unsigned int frameInterval
The frame interval in microSeconds (inverse of frame rate).
Definition: runtime_display_frame.h:76
Definition: statistics.h:56
The Timer class.
Definition: timer.h:66
Definition: vertex.h:84
The disti::DisplayFrame class.
#define DISTI_METHOD_OVERRIDE
Macro to wrap the override keyword, removed on compilers that don't support it.
Definition: gls_cpp_lang_support.h:221
A file for all GL Studio files to include.
#define GLS_EXPORT
Macro denoting which functions should be visible from the runtime library.
Definition: gls_include.h:50
Definition: bmpimage.h:46
The disti::Timer class. An OS portable timing class.