| GL Studio C++ Runtime API

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