gls_path_manager.h

Go to the documentation of this file.

/*! \file
  \brief  The disti::GlsPathManager 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 INCLUDED_GLS_PATH_MANAGER_H
#define INCLUDED_GLS_PATH_MANAGER_H
 
#include "gls_cpp_lang_support.h"
#include "gls_dynamic_path.h"
#include "group.h"
 
// Windows #defines this symbol which we use
#if defined( WIN32 ) && defined( GetObject )
#    undef GetObject
#endif
 
namespace disti
{
// SetValue enumerations
enum
{
    GLS_PATHMANAGER_FIRST_VALUE = GLS_LAST_INITIALIZER + 1,
    GLS_PATHMANAGER_PATHOBJPAIR_COUNT,
    GLS_PATHMANAGER_PATHOBJPAIR,
    GLS_PATHMANAGER_STRINGPATHOBJPAIR
};
 
/** Runtime implementation of a GlsPathManager */
class GlsPathManager : public DisplayObject
{
    friend class GlsPathManagerEditor;
 
private:
    GlsPathManager& operator=( const GlsPathManager& ) DISTI_SPECIAL_MEM_FUN_DELETE;
    GlsPathManager( const GlsPathManager& ) 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.
 
    /// Constructor
    /// \param generateInstanceName Whether or not to generate an instance name for this object.
    GLSGEN_GLSDYNAMICPATH_EXPORT GlsPathManager( bool generateInstanceName = false );
 
    /// Copy constructor
    /// \param that The object to copy from.
    /// \param generateNames Whether or not to generate an instance name for this object.
    GLSGEN_GLSDYNAMICPATH_EXPORT GlsPathManager( const GlsPathManager& that, const bool generateNames );
 
    /** Destructs a GlsPathManager object */
    virtual GLSGEN_GLSDYNAMICPATH_EXPORT ~GlsPathManager();
 
    /// \return A pointer to a new GlsPathManager 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 Draw() 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;
 
    //////////////////////////////////////////////////
    // GlsPathManager specific operations
    //////////////////////////////////////////////////
 
    /// \details The PathObjectPair class. Contains a dynamic path and the object that path animates.
    class PathObjectPair
    {
    public:
        /// Constructor
        GLSGEN_GLSDYNAMICPATH_EXPORT PathObjectPair();
 
        /// Copy constructor
        GLSGEN_GLSDYNAMICPATH_EXPORT PathObjectPair( const PathObjectPair& );
 
        /// Destructor
        GLSGEN_GLSDYNAMICPATH_EXPORT ~PathObjectPair();
 
        /// Copy assignment
        /// \return The resulting object (this).
        GLSGEN_GLSDYNAMICPATH_EXPORT const PathObjectPair& operator=( const PathObjectPair& );
 
        /// Populates the attribute dictionary for this object.
        /// \note Not normally called by users.
        GLSGEN_GLSDYNAMICPATH_EXPORT void MakeAttribDict();
 
        /// \return A reference to the attribute dictionary for this object.
        DistiAttribDict& Attributes()
        {
            if( !_attribDict )
                MakeAttribDict();
            return *_attribDict;
        };
 
        /// Assign a new GlsDynamicPath to this pair by name.
        /// \param name The name of the new path to set.
        void SetDynamicPathByName( const std::string& name )
        {
            _pathName = name;
        }
 
        /// \return The name of the path in this pair.
        std::string GetDynamicPathName() const
        {
            return _path ? _path->InstanceName() : _pathName;
        }
 
        /// Assign a new GlsDynamicPath to this pair.
        /// \param path The new path to set.
        void SetDynamicPath( GlsDynamicPath* path )
        {
            _path = path;
        }
 
        /// \return The path in this pair.
        GlsDynamicPath* GetDynamicPath() const
        {
            return _path;
        }
 
        /// Set the target object of this pair's animation.
        /// \param object The new target object to set.
        void SetObject( DisplayObject* object )
        {
            _object = object;
        }
 
        /// \return The target object of this pair.
        DisplayObject* GetObject() const
        {
            return _object;
        }
#if !defined( GLES )
        /// Assign a new GlsDynamicPath to this pair.
        /// \deprecated Use single-pointer functions instead.
        /// \param path The new path to set.
        DISTI_DEPRECATED( "Use single-pointer functions instead." )
        void SetDynamicPath( GlsDynamicPath** path )
        {
            _path = path ? *path : NULL;
        }
 
        /// Set the target object of this pair's animation.
        /// \deprecated Use single-pointer functions instead.
        /// \param object The new target object to set.
        DISTI_DEPRECATED( "Use single-pointer functions instead." )
        void SetObject( DisplayObject** object )
        {
            _object = object ? *object : NULL;
        }
#endif
        /// Set the target object of this pair's animation by name.
        /// \param name The name of the new target object to set.
        void SetObjectByName( const std::string& name )
        {
            _objectName = name;
        }
 
        /// \return The name of the target object.
        std::string GetObjectName() const
        {
            return _object ? _object->InstanceName() : _objectName;
        }
 
    protected:
        // The *'s are for runtime (faster).
        GlsDynamicPath* _path;   ///< The path containing the animation data.
        DisplayObject*  _object; ///< The object to be animated by the path.
 
        // the std::strings are for the editor (slower)
        std::string _pathName;   ///< The name of the path object.
        std::string _objectName; ///< The name of the animation target object.
 
        DistiAttribDict* _attribDict; ///< The attribute dictionary for the members of this object.
    };
 
    typedef DynamicArray<PathObjectPair> PathObjectPairArrayType; ///< Shorthand typedef for a list of path pairs.
 
    /// Use this array to set which path goes with what object.
    /// \return A modifiable reference to the PathObjectPairArray associated with this object.
    PathObjectPairArrayType& PathObjectPairArray() { return _pathObjectPairArray; }
 
    /// \return A const reference to the PathObjectPairArray associated with this object.
    const PathObjectPairArrayType& PathObjectPairArray() const { return _pathObjectPairArray; }
 
    /// Sets the animation value as a ratio of MinAnimationValue, MaxAnimationValue.
    /// \param pct percent of animation (0.0 -> 1.0).
    GLSGEN_GLSDYNAMICPATH_EXPORT void AnimationPct( double pct );
 
    /// Move all of the objects in the PathObjectPairArray to the given value on the associated path.
    /// \param value The value used to position the object on the path (see GlsDynamicPath::MoveObject).
    GLSGEN_GLSDYNAMICPATH_EXPORT void SetAnimationValue( float value );
 
    /// Backwards compatibility method.
    /// \see SetAnimationValue
    /// \param value The animation value to set.
    DISTI_DEPRECATED( "Renamed for clarity, use SetAnimationValue instead." )
    void CurrentTimeValue( float value ) { SetAnimationValue( value ); }
 
    /** Causes the MinAnimationValue and MaxAnimationValue to be recalculated using
      * the paths in the PathObjectPairArray.
      */
    GLSGEN_GLSDYNAMICPATH_EXPORT void RecalcMinMaxValue();
 
    /** Returns the stored minimum animation value from the PathObjectPairArray.
      * \see RecalcMinMaxValue
      * \return The minimum animation value
      */
    GLSGEN_GLSDYNAMICPATH_EXPORT float MinAnimationValue();
 
    /// Backwards compatibility method.
    /// \see MinAnimationValue
    /// \return The minimum animation value.
    DISTI_DEPRECATED( "Renamed for clarity, use MinAnimationValue instead." )
    float MinTimeValue() { return MinAnimationValue(); }
 
    /** Returns the stored maximum animation value from the PathObjectPairArray.
      * \see RecalcMinMaxValue
      * \return The maximum animation value
      */
    GLSGEN_GLSDYNAMICPATH_EXPORT float MaxAnimationValue();
 
    /// Backwards compatibility method.
    /// \see MaxAnimationValue
    /// \return The maximum animation value.
    DISTI_DEPRECATED( "Renamed for clarity, use MaxAnimationValue instead." )
    float MaxTimeValue() { return MaxAnimationValue(); }
 
protected:
    PathObjectPairArrayType _pathObjectPairArray; ///< List of animation pairs to manage.
 
    float _minValue;          ///< The minimum animation key value.
    float _maxValue;          ///< The maximum animation key value.
    bool  _recalcValueBounds; ///< If true, _minValue and _maxValue will be recalculated.
 
    /// Calculate the min and max value based on the animation pairs.
    /// \note Not normally called by users.
    void CalculateMinMaxValue();
#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
};
 
} // namespace disti
 
#endif