GL Studio C++ Runtime API
glsutil.h
Go to the documentation of this file.
1/// \file glsutil.h
2/// \brief GL Studio helper functions.
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_GLSUTIL_H
40#define DISTI_INCLUDED_GLSUTIL_H
41
42#include "display.h"
43
44namespace disti
45{
46/// \param angle1 The starting angle.
47/// \param angle2 The ending angle.
48/// \return The minimum angular distance between angle1 and angle2.
49GLS_EXPORT float AngularDistance( float angle1, float angle2 );
50
51/// \param angle1 The starting angle.
52/// \param angle2 The ending angle.
53/// \return The absolute value of the minimum angular distance between angle1 and angle2.
54GLS_EXPORT float AngularDistanceAbs( float angle1, float angle2 );
55
56/** Decomposes an integer into individual digits.
57 * Returns the individual digits making up the supplied integer
58 * \param source The number to break up
59 * \param _1 The pointer to the integer to contain the Least Significant Digit (rightmost digit).
60 * \param _2 (optional) The pointer to the integer to containing the second digit from the right.
61 * \param _3 (optional) The pointer to the integer to containing the third digit from the right.
62 * \param _4 (optional) The pointer to the integer to containing the fourth digit from the right.
63 * \param _5 (optional) The pointer to the integer to containing the fifth digit from the right.
64 * \param _6 (optional) The pointer to the integer to containing the sixth digit from the right.
65 * \param _7 (optional) The pointer to the integer to containing the seventh digit from the right.
66 * \param _8 (optional) The pointer to the integer to containing the eigth digit from the right.
67 */
68GLS_EXPORT void GetDigits( int source,
69 int* _1, //least significant digit
70 int* _2 = NULL,
71 int* _3 = NULL,
72 int* _4 = NULL,
73 int* _5 = NULL,
74 int* _6 = NULL,
75 int* _7 = NULL,
76 int* _8 = NULL );
77
78/** \brief Rotates a needle on a non-linear scale
79 * Rotates a needle object to the degree amount determined by
80 * the given value relative to the minimum and maximum values.
81 * Use multiple segments to map a gauge with a non-linear readout.
82 *
83 * \param obj The display object that will move (usually the needle)
84 * \param value The actual value that the needle should point to.
85 * \param gauge_values A 2 dimensional array that contains the values
86 * and the angles that correspond to the gauge. The
87 * first of the pair is the gauge value. The second
88 * of the pair is the angle the needle should be
89 * rotated in order to point to it.
90 * The first pair should be the minimal angle the
91 * needle will be rotated while the last pair should
92 * be the maximum angle the needle will be rotated.
93 * \param segments The number of pairs in the gauge_values array.
94 * \sa Uses Interpolate() internally.
95 */
96GLS_EXPORT void ChangeNeedle( DisplayObject* obj, const float value, float gauge_values[][ 2 ], const int segments );
97
98/// Clamp a value to the given range.
99#define CLAMP_VALUE( val, min, max ) ( ( val ) < ( min ) ? ( min ) : ( ( val ) > ( max ) ? ( max ) : ( val ) ) )
100
101/** The ramp functions can be used to generate
102 * varying data for testing purposes.
103 * \param time The system time (Available from the Calculate method)
104 * \param min The smallest value to return
105 * \param max The largest value to return
106 * \returns A value varying from min to max.
107 */
108GLS_EXPORT int RampInt( double time, int min, int max );
109
110/** RampBool can be used to generate
111 * varying data for testing purposes.
112 * \param time The system time (Available from the Calculate method)
113 * \returns A value varying from false to true
114 */
115GLS_EXPORT bool RampBool( double time );
116
117/** RampFloat is used to generate
118 * varying data for testing purposes.
119 * \param time The system time (Available from the Calculate method)
120 * \param min The smallest value to return
121 * \param max The largest value to return
122 * \returns A value varying from min to max.
123 */
124GLS_EXPORT float RampFloat( double time, float min, float max );
125
126/** RampDouble is used to generate
127 * varying data for testing purposes.
128 * \param time The system time (Available from the Calculate method)
129 * \param min The smallest value to return
130 * \param max The largest value to return
131 * \returns A value varying from min to max.
132 */
133GLS_EXPORT double RampDouble( double time, double min, double max );
134
135/** \brief Interpolates based on the specified array.
136 *
137 * Returns an iterpolated value determined by
138 * the given value relative to the set of specified
139 * values.
140 * Use multiple segments to map a gauge with a non-linear readout.
141 * \param value The value to be converted.
142 * \param gauge_values A 2 dimensional array that contains the values
143 * and the angles that correspond to the gauge. The
144 * first of the pair is the gauge value. The second
145 * of the pair is the angle the needle should be
146 * rotated in order to point to it.
147 * The first pair should be the minimal value while the last pair should
148 * be the maximum value.
149 * \param segments The number of pairs in the gauge_values array.
150 * \return the interpolated value.
151 * \sa Used by ChangeNeedle()
152 */
153GLS_EXPORT float Interpolate( const float value, float gauge_values[][ 2 ], const int segments );
154
155/** \brief Moves an object horizontally based on the given values.
156 * Moves a digit strip horizontally to the location determined by
157 * the given value relative to the minimum and maximum values.
158 *
159 * \param obj - The display object to move (usually a horizontal strip of digits.
160 * \param value - The value to be displayed on the digit strip.
161 * \param min - The smallest value that will be displayed
162 * \param max - The largest value that will be displayed.
163 * \param refPt - The location (x) of the object this object is attached to
164 * \param locAtMin - The location (x-coord) of the digit strip when placed so that the min value is displayed.
165 * \param locAtMax - The location (x-coord) of the digit strip when placed so that the max value is displayed.
166 */
167GLS_EXPORT void ChangeHStrip( DisplayObject* obj, float value, const float min, const float max,
168 float refPt, const float locAtMin, const float locAtMax );
169
170/** \brief Moves an object vertically based on the given values.
171 * Moves a digit strip vertically to the location determined by
172 * the given value relative to the minimum and maximum values.
173 *
174 * \param obj - The display object to move (usually a horizontal strip of digits.
175 * \param value - The value to be displayed on the digit strip.
176 * \param min - The smallest value that will be displayed
177 * \param max - The largest value that will be displayed.
178 * \param refPt - The location (y) of the object this object is attached to
179 * \param locAtMin - The location (y-coord) of the digit strip when placed so that the min value is displayed.
180 * \param locAtMax - The location (y-coord) of the digit strip when placed so that the max value is displayed.
181 */
182GLS_EXPORT void ChangeVStrip( DisplayObject* obj, float value, const float min, const float max,
183 const float refPt, const float locAtMin, const float locAtMax );
184
185/** Move a texture within an object to make the object appear to be moving in a Horizontal direction.
186 * Useful for instruments with moving digits.
187 * Assumptions:
188 * The Texture cannot be rotated,
189 * The object cannot be flipped, or reversed
190 * Min value is on the left side of the texture
191 * Max value is on the right side of the texture
192 * The Texture height and width must be powers of 2!
193 *
194 * \param obj - The object with the texture to move.
195 * \param unit_movement - How far to move the texture per unit on the scale, e.g., .007227
196 * This is specific to the texture.
197 * unit_movement = ((pixel count of largest unit) - (pixel count of smallest unit)) divided by
198 * (the pixel width of the image) divided by
199 * (number of units between the smallest and largest, e.g., 100 MPH)
200 * this then yeilds (pixel ratio) per unit
201 * \param min_units - The smallest unit displayed, e.g., 0 MPH
202 * \param max_units - The largest unit displayed, e.g., 100 MPH
203 * \param units - How many units to move the Scale, e.g. 33 MPH
204 * \param starting_x - The starting x position of the texture
205 * The following code can be used to save the starting position:
206 * Vertex *texture = obj->GetTextureCoordinates()[0].x;
207 * starting_x = texture[0].x;
208 */
210 DisplayObject* obj, // The object with the texture to move
211 const float unit_movement, // How far to move the texture per unit on the scale, e.g., .007227
212 const float min_units, // The smallest unit displayed, e.g., 0 MPH
213 const float max_units, // The largest unit displayed, e.g., 100 MPH
214 float units, // How many units to move the Scale, e.g. 33 MPH
215 const float starting_x // The starting x position of the texture
216);
217
218/// \brief Move a texture within an object to make the object appear to be moving in a Vertical direction.
219/// Useful for instruments with moving digits.
220/// Assumptions:
221/// The Texture cannot be rotated,
222/// The object cannot be flipped, or reversed
223/// Min value is on the bottom side of the texture
224/// Max value is on the top side of the texture
225/// The Texture height and width must be powers of 2!
226///
227/// \param obj - The object with the texture to move.
228/// \param unit_movement - How far to move the texture per unit on the scale, e.g., .007227
229/// This is specific to the texture.
230/// unit_movement = ((pixel count of largest unit) - (pixel count of smallest unit)) divided by
231/// (the pixel width of the image) divided by
232/// (number of units between the smallest and largest, e.g., 100 MPH)
233/// this then yields (pixel ratio) per unit
234/// \param min_units - The smallest unit displayed, e.g., 0 MPH
235/// \param max_units - The largest unit displayed, e.g., 100 MPH
236/// \param units - How many units to move the Scale, e.g. 33 MPH
237/// \param starting_y - The starting x position of the texture
238/// The following code can be used to save the starting position:
239/// Vertex *texture = obj->GetTextureCoordinates()[0].y;
240/// starting_y = texture[0].y;
241GLS_EXPORT void ChangeVTexture( DisplayObject* obj, const float unit_movement, const float min_units, const float max_units, float units, const float starting_y );
242
243/// \brief Move a texture within an object to make the object appear to be moving in a Vertical direction.
244/// Useful for instruments with moving digits.
245/// Assumptions:
246/// The Texture cannot be rotated,
247/// The object cannot be flipped, or reversed
248/// Min value is on the bottom side of the texture
249/// Max value is on the top side of the texture
250/// The Texture height and width must be powers of 2!
251///
252/// \param obj - The object with the texture to move.
253/// \param unit_movement - How far to move the texture per unit on the scale, e.g., .007227
254/// This is specific to the texture.
255/// unit_movement = ((pixel count of largest unit) - (pixel count of smallest unit)) divided by
256/// (the pixel width of the image) divided by
257/// (number of units between the smallest and largest, e.g., 100 MPH)
258/// this then yields (pixel ratio) per unit
259/// \param min_units - The smallest unit displayed, e.g., 0 MPH
260/// \param max_units - The largest unit displayed, e.g., 100 MPH
261/// \param units - How many units to move the Scale, e.g. 33 MPH
262/// \param starting_y - The starting x position of the texture
263/// The following code can be used to save the starting position:
264/// Vertex *texture = obj->GetTextureCoordinates()[0].y;
265/// starting_y = texture[0].y;
266GLS_EXPORT void ChangeVTexture( DisplayObject* obj, const float unit_movement, const float min_units, const float max_units, float units, const float* starting_y );
267
268//! Enumeration for Input Operators
269typedef enum
270{
271 INPUT_VERTICAL = 1,
272 INPUT_HORIZONTAL = 2
274
275//! Enumeration for Input Operators
276typedef enum
277{
278 INPUT_FLAG_NORMAL = 0,
279 INPUT_FLAG_SNAPBACK = 1,
280 INPUT_FLAG_WRAPAROUND = 2
282
283/// Uses event data to calculate a new switch position based on the DCS of the object.
284/// \note This is not intended to be called directly.
285/// \param self The switch being manipulated.
286/// \param ev The incoming mouse event.
287/// \param inputType INPUT_VERTICAL or INPUT_HORIZONTAL.
288/// \param numPositions The number of positions the switch can be in.
289/// \param scale Additional optional scale to be applied to position calculation.
290/// \return The resulting switch position state.
291GLS_EXPORT int CalcSwitchPosDCS( DisplayObject* self, DisplayEvent* ev, InputOrientationEnum inputType, int numPositions, float scale = 1.0f );
292
293} // namespace disti
294
295#endif
Definition: events.h:111
Definition: display.h:95
The disti::DisplayObject class and global enumerations.
#define GLS_EXPORT
Macro denoting which functions should be visible from the runtime library.
Definition: gls_include.h:50
Definition: bmpimage.h:46
float AngularDistance(float angle1, float angle2)
bool RampBool(double time)
InputPositionEnum
Enumeration for Input Operators.
Definition: glsutil.h:277
void ChangeNeedle(DisplayObject *obj, const float value, float gauge_values[][2], const int segments)
Rotates a needle on a non-linear scale Rotates a needle object to the degree amount determined by the...
float RampFloat(double time, float min, float max)
void ChangeHStrip(DisplayObject *obj, float value, const float min, const float max, float refPt, const float locAtMin, const float locAtMax)
Moves an object horizontally based on the given values. Moves a digit strip horizontally to the locat...
void ChangeVStrip(DisplayObject *obj, float value, const float min, const float max, const float refPt, const float locAtMin, const float locAtMax)
Moves an object vertically based on the given values. Moves a digit strip vertically to the location ...
void GetDigits(int source, int *_1, int *_2=NULL, int *_3=NULL, int *_4=NULL, int *_5=NULL, int *_6=NULL, int *_7=NULL, int *_8=NULL)
void ChangeHTexture(DisplayObject *obj, const float unit_movement, const float min_units, const float max_units, float units, const float starting_x)
int RampInt(double time, int min, int max)
int CalcSwitchPosDCS(DisplayObject *self, DisplayEvent *ev, InputOrientationEnum inputType, int numPositions, float scale=1.0f)
double RampDouble(double time, double min, double max)
void ChangeVTexture(DisplayObject *obj, const float unit_movement, const float min_units, const float max_units, float units, const float starting_y)
Move a texture within an object to make the object appear to be moving in a Vertical direction....
InputOrientationEnum
Enumeration for Input Operators.
Definition: glsutil.h:270
float Interpolate(const float value, float gauge_values[][2], const int segments)
Interpolates based on the specified array.
float AngularDistanceAbs(float angle1, float angle2)