glsutil.h

Go to the documentation of this file.

/*! \file
  \brief  GL Studio helper functions.

  \par Copyright Information

  Copyright (c) 2017 by The DiSTI Corporation.<br>
  11301 Corporate Blvd; Suite 100<br>
  Orlando, Florida 32817<br>
  USA<br>
  <br>
  All rights reserved.<br>

  This Software contains proprietary trade secrets of DiSTI and may not be
reproduced, in whole or part, in any form, or by any means of electronic,
mechanical, or otherwise, without the written permission of DiSTI.  Said
permission may be derived through the purchase of applicable DiSTI product
licenses which detail the distribution rights of this content and any
Derivative Works based on this or other copyrighted DiSTI Software.

  NO WARRANTY. THE SOFTWARE IS PROVIDED "AS-IS," WITHOUT WARRANTY OF ANY KIND,
AND ANY USE OF THIS SOFTWARE PRODUCT IS AT YOUR OWN RISK. TO THE MAXIMUM EXTENT
PERMITTED BY APPLICABLE LAW, DISTI AND ITS SUPPLIERS DISCLAIM ALL WARRANTIES
AND CONDITIONS, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY AND/OR FITNESS FOR A
PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT, WITH REGARD TO THE SOFTWARE.

  LIMITATION OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW,
IN NO EVENT SHALL DISTI OR ITS SUPPLIERS BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION,
DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS
INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR
INABILITY TO USE THE SOFTWARE, EVEN IF DISTI HAS BEEN ADVISED OF THE POSSIBILITY
OF SUCH DAMAGES.  DISTI'S ENTIRE LIABILITY AND YOUR EXCLUSIVE REMEDY SHALL NOT
EXCEED FIVE DOLLARS (US$5.00).

  The aforementioned terms and restrictions are governed by the laws of the
State of Florida and the United States of America.

*/
#ifndef __GLSUTIL_H
#define __GLSUTIL_H

#include "display.h"

namespace disti
{
/** Returns the minimum angular distance 
  *    between angle1 and angle2.
  */
GLS_EXPORT float AngularDistance( float angle1, float angle2 );

/** Returns the absolute value of the minimum angular distance 
  *    between angle1 and angle2.
  */
GLS_EXPORT float AngularDistanceAbs( float angle1, float angle2 );

/** Decomposes an integer into individual digits.
  * Returns the individual digits making up the supplied integer
  * \param source The number to break up
  * \param _1 The pointer to the integer to contain the Least Significant Digit (rightmost digit).
  * \param _2 (optional) The pointer to the integer to containing the second digit from the right.
  * \param _3 (optional) The pointer to the integer to containing the third digit from the right.
  * \param _4 (optional) The pointer to the integer to containing the fourth digit from the right.
  * \param _5 (optional) The pointer to the integer to containing the fifth digit from the right.
  * \param _6 (optional) The pointer to the integer to containing the sixth digit from the right.
  * \param _7 (optional) The pointer to the integer to containing the seventh digit from the right.
  * \param _8 (optional) The pointer to the integer to containing the eigth digit from the right.
  */
GLS_EXPORT void GetDigits( int source,
    int*                       _1, //least significant digit
    int*                       _2 = NULL,
    int*                       _3 = NULL,
    int*                       _4 = NULL,
    int*                       _5 = NULL,
    int*                       _6 = NULL,
    int*                       _7 = NULL,
    int*                       _8 = NULL );

/** \brief Rotates a needle on a non-linear scale
  * Rotates a needle object to the degree amount determined by
  * the given value relative to the minimum and maximum values.
  * Use multiple segments to map a gauge with a non-linear readout.
  *    
  * \param obj The display object that will move (usually the needle)
  * \param value The actual value that the needle should point to.
  * \param gauge_values A 2 dimensional array that contains the values
  *     and the angles that correspond to the gauge. The
  *     first of the pair is the gauge value.  The second
  *     of the pair is the angle the needle should be
  *     rotated in order to point to it.
  *     The first pair should be the minimal angle the
  *     needle will be rotated while the last pair should
  *     be the maximum angle the needle will be rotated.
  * \param segments The number of pairs in the gauge_values array.
  * \sa Uses Interpolate() internally.
  */
GLS_EXPORT void ChangeNeedle( DisplayObject* obj, const float value, float gauge_values[][ 2 ], const int segments );

// Clamp a value to the given range
#define CLAMP_VALUE( val, min, max ) ( ( val ) < ( min ) ? ( min ) : ( ( val ) > ( max ) ? ( max ) : ( val ) ) )

/** The ramp functions can be used to generate 
  * varying data for testing purposes.
  * \param time The system time (Available from the Calculate method)
  * \param min The smallest value to return
  * \param max The largest value to return
  * \returns A value varying from min to max.
  */
GLS_EXPORT int RampInt( double time, int min, int max );

/** RampBool can be used to generate 
  * varying data for testing purposes.
  * \param time The system time (Available from the Calculate method)
  * \returns A value varying from false to true
  */
GLS_EXPORT bool RampBool( double time );

/** RampFloat is used to generate 
  * varying data for testing purposes.
  * \param time The system time (Available from the Calculate method)
  * \param min The smallest value to return
  * \param max The largest value to return
  * \returns A value varying from min to max.
  */
GLS_EXPORT float RampFloat( double time, float min, float max );

/** RampDouble is used to generate 
  * varying data for testing purposes.
  * \param time The system time (Available from the Calculate method)
  * \param min The smallest value to return
  * \param max The largest value to return
  * \returns A value varying from min to max.
  */
GLS_EXPORT double RampDouble( double time, double min, double max );

/** \brief Interpolates based on the specified array.
  *
  * Returns an iterpolated value determined by
  * the given value relative to the set of specified 
  * values.
  * Use multiple segments to map a gauge with a non-linear readout.
  * \param value The value to be converted.
  * \param gauge_values A 2 dimensional array that contains the values
  *  and the angles that correspond to the gauge. The
  *  first of the pair is the gauge value.  The second
  *  of the pair is the angle the needle should be
  *  rotated in order to point to it.
  *  The first pair should be the minimal value while the last pair should
  *  be the maximum value.
  *  \param segments The number of pairs in the gauge_values array.
  *  \return the interpolated value.
  *  \sa Used by ChangeNeedle()
  */
GLS_EXPORT float Interpolate( const float value, float gauge_values[][ 2 ], const int segments );

/** \brief Moves an object horizontally based on the given values.
  * Moves a digit strip horizontally to the location determined by
  * the given value relative to the minimum and maximum values.
  * 
  * \param obj - The display object to move (usually a horizontal strip of digits.
  * \param value - The value to be displayed on the digit strip.
  * \param min - The smallest value that will be displayed
  * \param max - The largest value that will be displayed.
  * \param refPt -    The location (x) of the object this object is attached to
  * \param locAtMin - The location (x-coord) of the digit strip when placed so that the min value is displayed.
  * \param locAtMax - The location (x-coord) of the digit strip when placed so that the max value is displayed.
  */
GLS_EXPORT void ChangeHStrip( DisplayObject* obj, float value, const float min, const float max,
    float refPt, const float locAtMin, const float locAtMax );

/** \brief Moves an object vertically based on the given values.
  * Moves a digit strip vertically to the location determined by
  * the given value relative to the minimum and maximum values.
  *
  * \param obj - The display object to move (usually a horizontal strip of digits.
  * \param value - The value to be displayed on the digit strip.
  * \param min - The smallest value that will be displayed
  * \param max - The largest value that will be displayed.
  * \param refPt -    The location (y) of the object this object is attached to
  * \param locAtMin - The location (y-coord) of the digit strip when placed so that the min value is displayed.
  * \param locAtMax - The location (y-coord) of the digit strip when placed so that the max value is displayed.
  */
GLS_EXPORT void ChangeVStrip( DisplayObject* obj, float value, const float min, const float max,
    const float refPt, const float locAtMin, const float locAtMax );

/**  Move a texture within an object to make the object appear to be moving in a Horizontal direction.
  *  Useful for instruments with moving digits.
  *  Assumptions:
  *    The Texture cannot be rotated,
  *    The object cannot be flipped, or reversed
  *    Min value is on the left side of the texture
  *    Max value is on the right side of the texture
  *    The Texture height and width must be powers of 2!
  *
  *  \param obj - The object with the texture to move.
  *  \param unit_movement - How far to move the texture per unit on the scale, e.g., .007227
  *        This is specific to the texture.
  *        unit_movement = ((pixel count of largest unit) - (pixel count of smallest unit)) divided by
  *                         (the pixel width of the image) divided by
  *                         (number of units between the smallest and largest, e.g., 100 MPH)
  *                     this then yeilds (pixel ratio) per unit
  *  \param min_units - The smallest unit displayed, e.g., 0 MPH
  *  \param max_units - The largest unit displayed,  e.g., 100 MPH
  *  \param units - How many units to move the Scale, e.g. 33 MPH
  *  \param starting_x - The starting x position of the texture
  *     The following code can be used to save the starting position:
  *         Vertex *texture = obj->GetTextureCoordinates()[0].x;
  *         starting_x = texture[0].x;
  */
GLS_EXPORT void ChangeHTexture(
    DisplayObject* obj,           // The object with the texture to move
    const float    unit_movement, // How far to move the texture per unit on the scale, e.g., .007227
    const float    min_units,     // The smallest unit displayed, e.g., 0 MPH
    const float    max_units,     // The largest unit displayed,  e.g., 100 MPH
    float          units,         // How many units to move the Scale, e.g. 33 MPH
    const float    starting_x     // The starting x position of the texture
);

/** \brief Move a texture within an object to make the object appear to be moving in a Vertical direction.
  *  Useful for instruments with moving digits.
  *  Assumptions:
  *    The Texture cannot be rotated,
  *    The object cannot be flipped, or reversed
  *    Min value is on the bottom side of the texture
  *    Max value is on the top side of the texture
  *    The Texture height and width must be powers of 2!
  *
  *  \param obj - The object with the texture to move.
  *  \param unit_movement - How far to move the texture per unit on the scale, e.g., .007227
  *        This is specific to the texture.
  *        unit_movement = ((pixel count of largest unit) - (pixel count of smallest unit)) divided by
  *                         (the pixel width of the image) divided by
  *                         (number of units between the smallest and largest, e.g., 100 MPH)
  *                     this then yeilds (pixel ratio) per unit
  *  \param min_units - The smallest unit displayed, e.g., 0 MPH
  *  \param max_units - The largest unit displayed,  e.g., 100 MPH
  *  \param units - How many units to move the Scale, e.g. 33 MPH
  *  \param starting_y - The starting x position of the texture
  *     The following code can be used to save the starting position:
  *         Vertex *texture = obj->GetTextureCoordinates()[0].y;
  *         starting_y = texture[0].y;
  */
GLS_EXPORT void ChangeVTexture(
    DisplayObject* obj,           // The object with the texture to move
    const float    unit_movement, // How far to move the texture per unit on the scale, e.g., .007227
    const float    min_units,     // The smallest unit displayed, e.g., 0 MPH
    const float    max_units,     // The largest unit displayed,  e.g., 100 MPH
    float          units,         // How many units to move the Scale, e.g. 33 MPH
    const float    starting_y     // The starting Y ratio of the texture
);

GLS_EXPORT void ChangeVTexture(
    DisplayObject* obj,           // The object with the texture to move
    const float    unit_movement, // How far to move the texture per unit on the scale, e.g., .007227
    const float    min_units,     // The smallest unit displayed, e.g., 0 MPH
    const float    max_units,     // The largest unit displayed,  e.g., 100 MPH
    float          units,         // How many units to move the Scale, e.g. 33 MPH
    const float*   starting_y     // array of starting Ys ratio of the texture (4 elements)
);

//! Enumeration for Input Operators
typedef enum
{
    INPUT_VERTICAL   = 1,
    INPUT_HORIZONTAL = 2
} InputOrientationEnum;

//! Enumeration for Input Operators
typedef enum
{
    INPUT_FLAG_NORMAL     = 0,
    INPUT_FLAG_SNAPBACK   = 1,
    INPUT_FLAG_WRAPAROUND = 2
} InputPositionEnum;

/**    Uses event data to calculate a new switch position based on the DCS of the object.
  * This is not intended to be called directly.
  */
GLS_EXPORT int CalcSwitchPosDCS( DisplayObject* self, DisplayEvent* ev,
    InputOrientationEnum inputType, int numPositions,
    float scale = 1.0f );

} // namespace disti

#endif