| 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 */
53 class RuntimeDisplayFrame : public DisplayFrame
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; ///< Additional offset to apply to the modelview matrix.
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();
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() DISTI_METHOD_OVERRIDE;
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();
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();
153
154 /** Returns the Frame Interval in microseconds
155 * \return The Frame Interval in microseconds
156 */
157 virtual GLS_EXPORT int FrameInterval();
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();
171
172 /** Part of display frame statistics, for recording time used in Calculate() */
173 virtual GLS_EXPORT void RecordCalculateEnd();
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() DISTI_METHOD_OVERRIDE;
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();
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();
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() const { return _current_view; }
252
253 GLS_EXPORT void Invalidate() DISTI_METHOD_OVERRIDE;
254
255 GLS_EXPORT bool IsInvalidated() const DISTI_METHOD_OVERRIDE;
256
257 /** The background clear color */
258 GlsColor _backgroundColor; // DDH: This is public yet has an accessor method....should it be protected?
259};
260
261} // namespace disti
262
263#endif
disti::DisplayEvent
Definition: events.h:113
disti::DisplayFrame
Definition: display_frame.h:87
disti::DisplayObject
Definition: display.h:96
disti::GlsColor
Definition: gls_color.h:54
disti::GlsEyePoint
Definition: gls_eyepoint.h:117
disti::GlsPainter
Definition: gls_painter.h:51
disti::RuntimeDisplayFrame
Definition: runtime_display_frame.h:55
disti::RuntimeDisplayFrame::RuntimeDisplayFrame
RuntimeDisplayFrame(const char *name, int width, int height)
disti::RuntimeDisplayFrame::FOV
virtual void FOV(double fov)
disti::RuntimeDisplayFrame::HeightOffset
virtual void HeightOffset(float offset)
disti::RuntimeDisplayFrame::CurrentView
virtual void CurrentView(const int view)
Definition: runtime_display_frame.h:246
disti::RuntimeDisplayFrame::Paint
virtual void Paint()
Definition: runtime_display_frame.h:197
disti::RuntimeDisplayFrame::UpdateAnimate
virtual bool UpdateAnimate()
disti::RuntimeDisplayFrame::FOV
virtual double FOV()
disti::RuntimeDisplayFrame::CurrentView
virtual int CurrentView() const
Definition: runtime_display_frame.h:251
disti::RuntimeDisplayFrame::~RuntimeDisplayFrame
virtual ~RuntimeDisplayFrame()
disti::RuntimeDisplayFrame::frameTimer
Timer & frameTimer
For backwards compatibility.
Definition: runtime_display_frame.h:60
disti::RuntimeDisplayFrame::Clear
virtual void Clear()
disti::RuntimeDisplayFrame::Invalidate
void Invalidate() override
Notify the painter that the scene needs to be redrawn.
disti::RuntimeDisplayFrame::_autoCalcFarZ
bool _autoCalcFarZ
When true a _farZ is automatically calculated.
Definition: runtime_display_frame.h:72
disti::RuntimeDisplayFrame::_autoCalcNearZ
bool _autoCalcNearZ
When true a _nearZ is automatically calculated.
Definition: runtime_display_frame.h:70
disti::RuntimeDisplayFrame::IsInvalidated
bool IsInvalidated() const override
disti::RuntimeDisplayFrame::RecordCalculateEnd
virtual void RecordCalculateEnd()
disti::RuntimeDisplayFrame::_depthFactor
float _depthFactor
Used for auto calculations.
Definition: runtime_display_frame.h:67
disti::RuntimeDisplayFrame::ClearDragAndFocus
virtual void ClearDragAndFocus() override
disti::RuntimeDisplayFrame::_redraw
bool _redraw
Flag indicating if the window should be redrawn.
Definition: runtime_display_frame.h:79
disti::RuntimeDisplayFrame::_height_offset
float _height_offset
Current "height" offset of window. Used for panning of display vertically in ortho mode.
Definition: runtime_display_frame.h:65
disti::RuntimeDisplayFrame::RecordCalculateStart
virtual void RecordCalculateStart()
disti::RuntimeDisplayFrame::FrameInterval
virtual int FrameInterval()
disti::RuntimeDisplayFrame::HeightOffset
virtual float HeightOffset()
disti::RuntimeDisplayFrame::Stats
virtual Statistics * Stats()
disti::RuntimeDisplayFrame::_farZ
double _farZ
Far clipping plane. Only meaningfull if _autoCalcVarZ is false.
Definition: runtime_display_frame.h:71
disti::RuntimeDisplayFrame::_currentEyePoint
GlsEyePoint * _currentEyePoint
The current eyepoint for viewing the scene.
Definition: runtime_display_frame.h:78
disti::RuntimeDisplayFrame::_current_view
int _current_view
Current view of the canvas (e.g., ortho, perspective, eyepoint).
Definition: runtime_display_frame.h:73
disti::RuntimeDisplayFrame::Scale
virtual float Scale() override
disti::RuntimeDisplayFrame::_nearZ
double _nearZ
Near clipping plane. Only meaningful if _autoCalcNearZ is false.
Definition: runtime_display_frame.h:69
disti::RuntimeDisplayFrame::Scale
virtual void Scale(float scale)
disti::RuntimeDisplayFrame::Name
const char * Name()
disti::RuntimeDisplayFrame::WaitForNextFrame
virtual void WaitForNextFrame()
disti::RuntimeDisplayFrame::_fov
double _fov
Field Of View. If 0.0 (the default), fov will be auto calculated.
Definition: runtime_display_frame.h:68
disti::RuntimeDisplayFrame::_frameTimer
Timer _frameTimer
Timer used for scheduling.
Definition: runtime_display_frame.h:59
disti::RuntimeDisplayFrame::DepthFactor
virtual float DepthFactor()
disti::RuntimeDisplayFrame::handle
virtual DisplayObject * handle(DisplayEvent *ev)
disti::RuntimeDisplayFrame::_name
std::string _name
The title of this display frame's window, if applicable.
Definition: runtime_display_frame.h:75
disti::RuntimeDisplayFrame::CurrentEyePoint
virtual GlsEyePoint * CurrentEyePoint()
disti::RuntimeDisplayFrame::_width_offset
float _width_offset
For better control over clipping and field of view, use a GlsEyePoint, but some limited functionality...
Definition: runtime_display_frame.h:64
disti::RuntimeDisplayFrame::BackgroundColor
virtual GlsColor BackgroundColor()
disti::RuntimeDisplayFrame::WidthOffset
virtual void WidthOffset(float offset)
disti::RuntimeDisplayFrame::DepthFactor
virtual void DepthFactor(float factor)
disti::RuntimeDisplayFrame::_smoothedFrameDelay
float _smoothedFrameDelay
Frame interval, smoothed based on actual draw performance.
Definition: runtime_display_frame.h:61
disti::RuntimeDisplayFrame::_scale
float _scale
Scale of the window.
Definition: runtime_display_frame.h:76
disti::RuntimeDisplayFrame::GetBackgroundColor
virtual void GetBackgroundColor(unsigned char &r, unsigned char &g, unsigned char &b, unsigned char &a)
disti::RuntimeDisplayFrame::_backgroundColor
GlsColor _backgroundColor
Definition: runtime_display_frame.h:258
disti::RuntimeDisplayFrame::_viewOffset
Vector _viewOffset
Additional offset to apply to the modelview matrix.
Definition: runtime_display_frame.h:66
disti::RuntimeDisplayFrame::CurrentEyePoint
virtual void CurrentEyePoint(GlsEyePoint *eye)
disti::RuntimeDisplayFrame::WidthOffset
virtual float WidthOffset()
disti::RuntimeDisplayFrame::FrameAnimate
virtual bool FrameAnimate()
disti::RuntimeDisplayFrame::frameInterval
unsigned int frameInterval
The frame interval in microSeconds (inverse of frame rate).
Definition: runtime_display_frame.h:77
disti::Statistics
Definition: statistics.h:57
disti::Timer
The Timer class.
Definition: timer.h:67
disti::VertexNoColor
Definition: vertex.h:85
display_frame.h
The disti::DisplayFrame class.
DISTI_METHOD_OVERRIDE
#define DISTI_METHOD_OVERRIDE
Macro to wrap the override keyword, removed on compilers that don't support it.
Definition: gls_cpp_lang_support.h:222
gls_include.h
A file for all GL Studio files to include.
GLS_EXPORT
#define GLS_EXPORT
Macro denoting which functions should be visible from the runtime library.
Definition: gls_include.h:52
disti
Definition: bmpimage.h:47
timer.h
The disti::Timer class. An OS portable timing class.