gls_dynamic_path.h

Go to the documentation of this file.

/*! \file
  \brief  The disti::GlsDynamicPath class and global enumerations.
 
  \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 _GLSDYNAMICPATH_H
#define _GLSDYNAMICPATH_H
 
#include "gls_cpp_lang_support.h"
#include "group.h"
 
/// Provides support for creating DLLs.
#if( defined( GLSGEN_EXPORT_GLSDYNAMICPATH ) || defined( GLSGEN_IMPORT_GLSDYNAMICPATH ) || defined( GLS_EXPORT_GENERATED ) || defined( GLS_IMPORT_GENERATED ) ) \
    && defined( _MSC_VER )
#    if defined( GLSGEN_EXPORT_GLSDYNAMICPATH ) || defined( GLS_EXPORT_GENERATED )
#        define GLSGEN_GLSDYNAMICPATH_EXPORT __declspec( dllexport )
#    else
#        define GLSGEN_GLSDYNAMICPATH_EXPORT __declspec( dllimport )
#    endif
#else
#    define GLSGEN_GLSDYNAMICPATH_EXPORT
#endif
///////////////////////////////////////////////////////////////////////////////
 
/// Automatically link the runtime library plugin (on Windows).
#define LIB_BASE_NAME "gls_dynamic_path"
#include "gls_auto_lib.h"
#undef LIB_BASE_NAME
 
namespace disti
{
// SetValue enumerations
enum
{
    GLS_DYNAMICPATH_FIRST_VALUE = GLS_LAST_INITIALIZER + 1,
    GLS_DYNAMICPATH_AFFECTS_LOCATION_X,
    GLS_DYNAMICPATH_AFFECTS_LOCATION_Y,
    GLS_DYNAMICPATH_AFFECTS_LOCATION_Z,
    GLS_DYNAMICPATH_AFFECTS_ROTATION_X,
    GLS_DYNAMICPATH_AFFECTS_ROTATION_Y,
    GLS_DYNAMICPATH_AFFECTS_ROTATION_Z,
    GLS_DYNAMICPATH_AFFECTS_SCALE_X,
    GLS_DYNAMICPATH_AFFECTS_SCALE_Y,
    GLS_DYNAMICPATH_AFFECTS_SCALE_Z,
    GLS_DYNAMICPATH_USE_SHORT_ROTATION_PATHS,
    GLS_DYNAMICPATH_STATE_COUNT,
    GLS_DYNAMICPATH_STATE
};
 
/** Runtime implementation of a GlsDynamicPath */
class GlsDynamicPath : public DisplayObject
{
    friend class GlsDynamicPathEditor;
 
private:
    GlsDynamicPath& operator=( const GlsDynamicPath& ) DISTI_SPECIAL_MEM_FUN_DELETE;
    GlsDynamicPath( const GlsDynamicPath& ) DISTI_SPECIAL_MEM_FUN_DELETE;
 
public:
    DISTI_DEPRECATED( "This identifier is forbidden by the C++ standard. Use BaseClass instead." )
    typedef DisplayObject _BaseClass; ///< Deprecated typedef for the base class.
    typedef DisplayObject BaseClass;  ///< Typedef for the base class.
 
    /** Create a new GlsDynamicPath.
      * \param generateInstanceName  Whether or not to generate an instance name
      * for this inputdevice */
    GLSGEN_GLSDYNAMICPATH_EXPORT GlsDynamicPath( bool generateInstanceName = false );
 
    /** The copy constructor for GlsDynamicPath
      * 
      * \param that          The GlsDynamicPath object that is being copied
      * \param generateNames Whether or not to generate a new instance name
      */
    GLSGEN_GLSDYNAMICPATH_EXPORT GlsDynamicPath( const GlsDynamicPath& that, const bool generateNames );
 
    /** Destructs a GlsDynamicPath object */
    virtual GLSGEN_GLSDYNAMICPATH_EXPORT ~GlsDynamicPath();
 
    /// \return A pointer to a new GlsDynamicPath object.
    static GLSGEN_GLSDYNAMICPATH_EXPORT DisplayObject* CreateInstance();
 
    virtual GLSGEN_GLSDYNAMICPATH_EXPORT void SetAvailableAttributes( unsigned int value ) DISTI_METHOD_OVERRIDE;
    virtual GLSGEN_GLSDYNAMICPATH_EXPORT DisplayObject* CloneObject( bool generateNames = false ) DISTI_METHOD_OVERRIDE;
    virtual GLSGEN_GLSDYNAMICPATH_EXPORT void           CopyProperties( DisplayObject* src ) DISTI_METHOD_OVERRIDE;
 
#ifndef GLES
    virtual GLSGEN_GLSDYNAMICPATH_EXPORT InterfaceListType* GetCppInterfaceDescription( InterfaceListType* addToThisList = NULL ) DISTI_METHOD_OVERRIDE;
    virtual GLSGEN_GLSDYNAMICPATH_EXPORT void               GetCppInterfaceDescriptionFree( InterfaceListType* array ) DISTI_METHOD_OVERRIDE;
#endif
 
    virtual GLSGEN_GLSDYNAMICPATH_EXPORT void PreDraw( const OpenGLMatrices& parentMatrices, Culler& culler ) DISTI_METHOD_OVERRIDE;
    virtual GLSGEN_GLSDYNAMICPATH_EXPORT void Draw() DISTI_METHOD_OVERRIDE;
    virtual GLSGEN_GLSDYNAMICPATH_EXPORT DisplayObject* handle( DisplayEvent* ev ) DISTI_METHOD_OVERRIDE;
    virtual GLSGEN_GLSDYNAMICPATH_EXPORT bool           Hit( float x, float y, float z, float scale, const Vector& directionVector, Vector* collisionPoint ) DISTI_METHOD_OVERRIDE;
    virtual GLSGEN_GLSDYNAMICPATH_EXPORT void           SetValue( int spec, va_list& args ) DISTI_METHOD_OVERRIDE;
    virtual GLSGEN_GLSDYNAMICPATH_EXPORT DistiAttributeBase& Resource( const char* name ) DISTI_METHOD_OVERRIDE;
    virtual GLSGEN_GLSDYNAMICPATH_EXPORT void                GetResources( std::ostream& outstr, GlsResourceFilter* filter ) DISTI_METHOD_OVERRIDE;
 
    //////////////////////////////////////////////////
    // GlsDynamicPath specific operations
    //////////////////////////////////////////////////
 
    /// Set whether the path will affect the X component of the object's dynamic translation.
    /// \param value The new component value.
    GLSGEN_GLSDYNAMICPATH_EXPORT void AffectsLocationX( const bool& value );
 
    /// \return Whether the path will affect the X component of the object's dynamic translation.
    GLSGEN_GLSDYNAMICPATH_EXPORT bool AffectsLocationX() const { return _affectsLocationX; }
 
    /// Set whether the path will affect the Y component of the object's dynamic translation.
    /// \param value The new component value.
    GLSGEN_GLSDYNAMICPATH_EXPORT void AffectsLocationY( const bool& value );
 
    /// \return Whether the path will affect the Y component of the object's dynamic translation.
    GLSGEN_GLSDYNAMICPATH_EXPORT bool AffectsLocationY() const { return _affectsLocationY; }
 
    /// Set whether the path will affect the Z component of the object's dynamic translation.
    /// \param value The new component value.
    GLSGEN_GLSDYNAMICPATH_EXPORT void AffectsLocationZ( const bool& value );
 
    /// \return Whether the path will affect the Z component of the object's dynamic translation.
    GLSGEN_GLSDYNAMICPATH_EXPORT bool AffectsLocationZ() const { return _affectsLocationZ; }
 
    /// Set whether the path will affect the X component of the object's dynamic rotation.
    /// \param value The new component value.
    GLSGEN_GLSDYNAMICPATH_EXPORT void AffectsRotationX( const bool& value );
 
    /// \return Whether the path will affect the X component of the object's dynamic rotation.
    GLSGEN_GLSDYNAMICPATH_EXPORT bool AffectsRotationX() const { return _affectsRotationX; }
 
    /// Set whether the path will affect the Y component of the object's dynamic rotation.
    /// \param value The new component value.
    GLSGEN_GLSDYNAMICPATH_EXPORT void AffectsRotationY( const bool& value );
 
    /// \return Whether the path will affect the Y component of the object's dynamic rotation.
    GLSGEN_GLSDYNAMICPATH_EXPORT bool AffectsRotationY() const { return _affectsRotationY; }
 
    /// Set whether the path will affect the Z component of the object's dynamic rotation.
    /// \param value The new component value.
    GLSGEN_GLSDYNAMICPATH_EXPORT void AffectsRotationZ( const bool& value );
 
    /// \return Whether the path will affect the Z component of the object's dynamic rotation.
    GLSGEN_GLSDYNAMICPATH_EXPORT bool AffectsRotationZ() const { return _affectsRotationZ; }
 
    /// Set whether the path will affect the X component of the object's dynamic scale.
    /// \param value The new component value.
    GLSGEN_GLSDYNAMICPATH_EXPORT void AffectsScaleX( const bool& value );
 
    /// \return Whether the path will affect the X component of the object's dynamic scale.
    GLSGEN_GLSDYNAMICPATH_EXPORT bool AffectsScaleX() const { return _affectsScaleX; }
 
    /// Set whether the path will affect the Y component of the object's dynamic scale.
    /// \param value The new component value.
    GLSGEN_GLSDYNAMICPATH_EXPORT void AffectsScaleY( const bool& value );
 
    /// \return Whether the path will affect the Y component of the object's dynamic scale.
    GLSGEN_GLSDYNAMICPATH_EXPORT bool AffectsScaleY() const { return _affectsScaleY; }
 
    /// Set whether the path will affect the Z component of the object's dynamic scale.
    /// \param value The new component value.
    GLSGEN_GLSDYNAMICPATH_EXPORT void AffectsScaleZ( const bool& value );
 
    /// \return Whether the path will affect the Z component of the object's dynamic scale.
    GLSGEN_GLSDYNAMICPATH_EXPORT bool AffectsScaleZ() const { return _affectsScaleZ; }
 
    /// If true, the shortest path between rotations is taken (360 degrees = no net rotation). If false, the long path is taken.
    /// \param value The new rotation behavior.
    GLSGEN_GLSDYNAMICPATH_EXPORT void UseShortRotationPaths( const bool& value );
 
    /// \return True if the shortest path between rotations is taken (360 degrees = no net rotation), otherwise false.
    GLSGEN_GLSDYNAMICPATH_EXPORT bool UseShortRotationPaths() const { return _useShortRotationPaths; }
 
    /// \details The State class. Contains the data for a state along the path.
    class State
    {
        friend class GlsDynamicPath;
 
    public:
        GLSGEN_GLSDYNAMICPATH_EXPORT State();
 
        /// Copy constructor
        GLSGEN_GLSDYNAMICPATH_EXPORT State( const State& );
 
        GLSGEN_GLSDYNAMICPATH_EXPORT ~State();
 
        /// Assignment operator
        /// \return The resulting object (this).
        GLSGEN_GLSDYNAMICPATH_EXPORT const State& operator=( const State& );
 
        /// Sets up DistiAttributes associated with each member of this class.
        GLSGEN_GLSDYNAMICPATH_EXPORT void MakeAttribDict();
 
        /// \return The attribute dictionary associated with the members of this class.
        DistiAttribDict& Attributes()
        {
            if( !_attribDict )
                MakeAttribDict();
            return *_attribDict;
        };
 
        /// Set the location value of this animation state.
        /// \param value The new location value.
        void Location( const Vector& value ) { _location = value; }
 
        /// \deprecated Use the const version instead.
        /// \return The location value of this animation state.
        Vector Location() { return _location; }
 
        /// \return The location value of this animation state.
        Vector Location() const { return _location; }
 
        /// Set the rotation value of this animation state.
        /// \param value The new rotation value.
        void Rotation( const Vector& value ) { _rotation = value; }
 
        /// \deprecated Use the const version instead.
        /// \return The rotation value of this animation state.
        Vector Rotation() { return _rotation; }
 
        /// \return The rotation value of this animation state.
        Vector Rotation() const { return _rotation; }
 
        /// Set the scale value of this animation state.
        /// \param value The new scale value.
        void Scale( const Vector& value ) { _scale = value; }
 
        /// \deprecated Use the const version instead.
        /// \return The scale value of this animation state.
        Vector Scale() { return _scale; }
 
        /// \return The scale value of this animation state.
        Vector Scale() const { return _scale; }
 
        /// Set the key value of this animation state
        /// \param value The new key value.
        void Value( const float& value ) { _value = value; }
 
        /// \deprecated Use the const version instead.
        /// \return The key value of this animation state.
        float Value() { return _value; }
 
        /// \return The key value of this animation state.
        float Value() const { return _value; }
 
    protected:
        Vector           _location;   ///< The location of the animation state.
        Vector           _rotation;   ///< The rotation of the animation state.
        Vector           _scale;      ///< The scale of the animation state.
        float            _value;      ///< The key value of the animation state.
        DistiAttribDict* _attribDict; ///< Attribute storage for the members of this class.
    };
 
    typedef DynamicArray<State> StateArrayType; ///< Typedef for a list of States.
 
    /// \returns the StateArray associated with this object. Use this array to modify the states that make up the path.
    StateArrayType& StateArray() { return _stateArray; }
 
    /// \returns the const StateArray associated with this object.
    const StateArrayType& StateArray() const { return _stateArray; }
 
    /// Iterates through the path segments and returns the first one found
    /// that contains the given value.
    /// Special cases:
    ///     value is before start of the path: index1 == index2 == 0
    ///     value is past the end of the path: index1 == index2 == (StateArray().Count()-1)
    /// \param value The value to search for.
    /// \param index1 Returns the index of the state at the start of the segment or -1 if no segments are found.
    /// \param index2 Returns the index of the state at the end the segment or -1 if no segments are found.
    GLSGEN_GLSDYNAMICPATH_EXPORT void FindFirstPathSegmentContainingValue( float value, int* index1, int* index2 );
 
    /// \return The Value for the first state or 0 if there are no states.
    float FirstStateValue()
    {
        if( _stateArray.Count() )
        {
            return _stateArray[ 0 ].Value();
        }
        else
        {
            return 0;
        }
    }
 
    /// \return The Value for the last state or 0 if there are no states.
    float LastStateValue()
    {
        if( _stateArray.Count() )
        {
            return _stateArray[ _stateArray.Count() - 1 ].Value();
        }
        else
        {
            return 0;
        }
    }
 
    /// \return The linearly interpolated location along the path for the given value.
    /// \param value The value used to get the path location.
    GLSGEN_GLSDYNAMICPATH_EXPORT Vector GetPathLocation( float value );
 
    /// \return The linearly interpolated rotation along the path for the given value.
    /// \param value The value used to get the path rotation.
    GLSGEN_GLSDYNAMICPATH_EXPORT Vector GetPathRotation( float value );
 
    /// \return The linearly interpolated scale along the path for the given value.
    /// \param value The value used to get the path scale.
    GLSGEN_GLSDYNAMICPATH_EXPORT Vector GetPathScale( float value );
 
    /** Moves a DisplayObject to the position along the path corresponding with the given value.
     * \param obj the DisplayObject to move
     * \param value The value used to position the object on the path
     */
    GLSGEN_GLSDYNAMICPATH_EXPORT void MoveObject( DisplayObject* obj, float value );
 
    /** Sets the object to the position corresponding with the given state. 
     * Which values are applied is controlled by the AffectsLocation* and AffectsRotation* properties.
     * \param obj Pointer to the object to move.
     * \param stateNumber The index of the state to set the object to.  If this value is outside the range [0,StateArray().Count()-1] nothing is done.
     */
    GLSGEN_GLSDYNAMICPATH_EXPORT void MoveObjectToState( DisplayObject* obj, int stateNumber );
 
protected:
#ifdef GLES
    /** Set a single attribute from the GLO file.
     * \param data The attribute to set and its associated data.
     */
    virtual GLS_EXPORT void SetFromGloData( GlsGloFileAttribute& data ) DISTI_METHOD_OVERRIDE;
#endif
 
    bool _affectsLocationX; ///< If true, this path will affect an object's X location.
    bool _affectsLocationY; ///< If true, this path will affect an object's Y location.
    bool _affectsLocationZ; ///< If true, this path will affect an object's Z location.
    bool _affectsRotationX; ///< If true, this path will affect an object's X rotation.
    bool _affectsRotationY; ///< If true, this path will affect an object's Y rotation.
    bool _affectsRotationZ; ///< If true, this path will affect an object's Z rotation.
    bool _affectsScaleX;    ///< If true, this path will affect an object's X scale.
    bool _affectsScaleY;    ///< If true, this path will affect an object's Y scale.
    bool _affectsScaleZ;    ///< If true, this path will affect an object's Z scale.
 
    bool _useShortRotationPaths; ///< If true, this state will rotate in the direction that will reach the desired angle the fastest.
 
    StateArrayType _stateArray; ///< The list of animation states for this path.
};
 
} // namespace disti
 
#endif