gls_3d_cable.h

Go to the documentation of this file.

/*! \file
  \brief  The disti::Gls3DCable class.
 
  \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 _GLS3DCABLE_H
#define _GLS3DCABLE_H
 
#include <vector>
 
#include "glpolygon.h"
#include "gls_cpp_lang_support.h"
#include "gls_quaternion.h"
#include "gltrimesh.h"
#include "group.h"
 
/// Provides support for creating DLLs.
#if( defined( GLSGEN_EXPORT_GLS3DCABLE ) || defined( GLSGEN_IMPORT_GLS3DCABLE ) || defined( GLS_EXPORT_GENERATED ) || defined( GLS_IMPORT_GENERATED ) ) \
    && defined( _MSC_VER )
#    if defined( GLSGEN_EXPORT_GLS3DCABLE ) || defined( GLS_EXPORT_GENERATED )
#        define GLSGEN_GLS3DCABLE_EXPORT __declspec( dllexport )
#    else
#        define GLSGEN_GLS3DCABLE_EXPORT __declspec( dllimport )
#    endif
#else
#    define GLSGEN_GLS3DCABLE_EXPORT
#endif
///////////////////////////////////////////////////////////////////////////////
 
/// Automatically link the runtime library plugin (on Windows).
#define LIB_BASE_NAME "gls_3d_cable"
#include "gls_auto_lib.h"
#undef LIB_BASE_NAME
 
namespace disti
{
// SetValue enumerations
enum
{
    GLS_3DCABLE_FIRST_VALUE = GLS_LAST_INITIALIZER + 1,
 
    GLS_3DCABLE_FLEXIBILITY,
    GLS_3DCABLE_NUMBEROFSEGMENTS,
    GLS_3DCABLE_NUMBEROFSIDES,
    GLS_3DCABLE_RADIUS,
    GLS_3DCABLE_LENGTH,
    GLS_3DCABLE_GRAVITY,
    GLS_3DCABLE_SECTIONSLACKPCT,
    GLS_3DCABLE_SECTIONFLOORDIST,
    GLS_3DCABLE_COLLISIONSTYLE,
    GLS_3DCABLE_FILLCOLOR,
    GLS_3DCABLE_LINECOLOR
};
 
typedef DynamicArray<double> DynamicDoubleArray; ///< Typedef for dynamic array of slack percentages.
 
/// \details The PreciseVertex class. Uses fuzzy floating point comparison rather than exact matches.
class PreciseVertex : public VertexNoColor
{
public:
    PreciseVertex()
        : VertexNoColor()
    {}
 
    /// Constructor from Vector
    /// \param vector The vector to construct from.
    PreciseVertex( const Vector& vector )
        : VertexNoColor( vector.x, vector.y, vector.z )
    {}
 
    /// Constructor from three floats
    /// \param x The x component to construct from.
    /// \param y The y component to construct from.
    /// \param z The z component to construct from.
    PreciseVertex( float x, float y, float z )
        : VertexNoColor( x, y, z )
    {}
 
    /**
        If the values are near zero, force them to be Zero!
        \pre
        \post
    */
    void NearZero()
    {
        const float DIFF = 0.0001f;
 
        if( BETWEEN( x, 0.0 - DIFF, 0.0 + DIFF ) )
        {
            x = 0.0f;
        }
 
        if( BETWEEN( y, 0.0 - DIFF, 0.0 + DIFF ) )
        {
            y = 0.0f;
        }
 
        if( BETWEEN( z, 0.0 - DIFF, 0.0 + DIFF ) )
        {
            z = 0.0f;
        }
    }
 
    /** Normalizes the vector into a unit vector */
    void Normalize()
    {
        double length = Magnitude();
 
        // how close to zero do we want to be?
        const double DIFF = 0.0001;
 
        if( !BETWEEN( length, 0.0 - DIFF, 0.0 + DIFF ) )
        {
            // Divide is slow so calculate 1/length and multiply to save time
            double inv_length = 1.0 / length;
 
            x = float( x * inv_length );
            y = float( y * inv_length );
            z = float( z * inv_length );
        }
        else
        {
            x = 0.0f;
            y = 0.0f;
            z = 0.0f;
        }
    }
 
    /** Determines if the vertex is identical to the supplied vertex, ignoring color
      \param arg vertex to compare to
      \return TRUE if equal, else FALSE
      */
    bool operator==( const VertexNoColor& arg ) const
    {
        const double DIFF = 0.0001;
        return ( BETWEEN( x, arg.x - DIFF, arg.x + DIFF ) && BETWEEN( y, arg.y - DIFF, arg.y + DIFF ) && BETWEEN( z, arg.z - DIFF, arg.z + DIFF ) );
    }
 
    /** Determines if the vertex is identical to the supplied vertex, ignoring color
      \param arg vertex to compare to
      \return TRUE if equal, else FALSE
      */
    bool operator!=( const VertexNoColor& arg ) const
    {
        const double DIFF = 0.0001;
        return ( !BETWEEN( x, arg.x - DIFF, arg.x + DIFF ) || !BETWEEN( y, arg.y - DIFF, arg.y + DIFF ) || !BETWEEN( z, arg.z - DIFF, arg.z + DIFF ) );
    }
};
 
/** 
    Runtime implementation of a Gls3DCable.  The Gls3DCable is a cable mesh between
    two or more endpoint objects.  The user controls the length, the flexibility, the
    diameter, the smoothness (segments and sides), and the droop of the cable.
*/
class Gls3DCable : public Group
{
public:
    DISTI_DEPRECATED( "This identifier is forbidden by the C++ standard. Use BaseClass instead." )
    typedef Group _BaseClass; ///< Deprecated typedef for the base class.
    typedef Group BaseClass;  ///< Typedef for the base class.
 
    enum
    {
        TEXTUREPOINT_MULT = 50
    };
 
    /** Sides limits */
    enum
    {
        MIN_NUMBER_OF_SIDES = 1,
        MAX_NUMBER_OF_SIDES = 100 // visually 50 looked good, 100 gives the user room
    };
 
    /** Segement limits */
    enum
    {
        MIN_SEGEMENTS = 1,
        MAX_SEGEMENTS = 10000 // Seems like 10,000 segements should be way big enough
    };
 
    /// Collision model
    enum ECollisionStyle
    {
        COLLISIONSTYLE_NONE = 0,
        COLLISIONSTYLE_FAST
#if defined( USE_COLLISIONSTYLE_SLOW )
        ,
        COLLISIONSTYLE_SLOW
#endif
    };
 
    friend class Gls3DCableEditor;
 
    /// Create a new Gls3DCable.
    /// \param generateInstance Whether or not to generate an instance name for this object.
    GLSGEN_GLS3DCABLE_EXPORT Gls3DCable( bool generateInstance = false );
 
    /// Copy constructor for Gls3DCable
    /// \param that The Gls3DCable to be copied from.
    /// \param generateNames Whether or not to generate a new instance name.
    GLSGEN_GLS3DCABLE_EXPORT Gls3DCable( const Gls3DCable& that, const bool generateNames );
 
    /** Destructs a Gls3DCable object */
    virtual GLSGEN_GLS3DCABLE_EXPORT ~Gls3DCable();
 
    /// \return A pointer to a new Gls3DCable.
    static GLSGEN_GLS3DCABLE_EXPORT DisplayObject* CreateInstance();
 
    //////////////////////////////////////////////////
    // Overridden base class methods
    // The base class methods are overridden so that the Group Class methods
    // are not called, generally DisplayObject methods are called, there
    // are a few exceptions.
    //////////////////////////////////////////////////
 
    /// \copydoc DisplayObject::GetResources
    virtual void GetResources( std::ostream& outstr, GlsResourceFilter* filter ) DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::Resource
    virtual DistiAttributeBase& Resource( const char* name ) DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::SetAvailableAttributes
    virtual GLSGEN_GLS3DCABLE_EXPORT void SetAvailableAttributes( unsigned int value ) DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::CloneObject
    virtual GLSGEN_GLS3DCABLE_EXPORT DisplayObject* CloneObject( bool generateNames = false ) DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::CopyProperties
    virtual GLSGEN_GLS3DCABLE_EXPORT void CopyProperties( DisplayObject* src ) DISTI_METHOD_OVERRIDE;
#ifndef GLES
    /// \copydoc DisplayObject::GetCppInterfaceDescription
    virtual GLSGEN_GLS3DCABLE_EXPORT InterfaceListType* GetCppInterfaceDescription( InterfaceListType* addToThisList = NULL ) DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::GetCppInterfaceDescriptionFree
    virtual GLSGEN_GLS3DCABLE_EXPORT void GetCppInterfaceDescriptionFree( InterfaceListType* array ) DISTI_METHOD_OVERRIDE;
#endif
    /// \copydoc DisplayObject::PreDraw
    virtual GLSGEN_GLS3DCABLE_EXPORT void PreDraw( const OpenGLMatrices& current, Culler& culler ) DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::Draw
    virtual GLSGEN_GLS3DCABLE_EXPORT void Draw() DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::Calculate
    virtual GLSGEN_GLS3DCABLE_EXPORT void Calculate( double time ) DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::handle
    virtual GLSGEN_GLS3DCABLE_EXPORT DisplayObject* handle( DisplayEvent* ev ) DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::SetValue
    virtual GLSGEN_GLS3DCABLE_EXPORT void SetValue( int spec, va_list& args ) DISTI_METHOD_OVERRIDE;
    /// \copydoc Group::CalculateBoundingBox
    virtual GLSGEN_GLS3DCABLE_EXPORT void CalculateBoundingBox() DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::Hit
    virtual GLSGEN_GLS3DCABLE_EXPORT bool Hit( float x, float y, float z, float scale, const Vector& directionVector, Vector* collisionPoint ) DISTI_METHOD_OVERRIDE;
 
    /// \copydoc DisplayObject::Pick3D
    virtual GLSGEN_GLS3DCABLE_EXPORT DisplayObject* Pick3D( const Vector& winLoc, const Vector& logicalCoords, float scale,
        const Vector& directionVector, Vector& collisionWinLoc, const OpenGLMatrices& drawnMatrices ) DISTI_METHOD_OVERRIDE;
 
    /// \copydoc DisplayObject::CalculateTextureCoordinates
    virtual GLSGEN_GLS3DCABLE_EXPORT void CalculateTextureCoordinates() DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::LineWidth(float)
    virtual GLSGEN_GLS3DCABLE_EXPORT void LineWidth( float width ) DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::LineWidth()
    virtual GLSGEN_GLS3DCABLE_EXPORT float LineWidth() DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::LineStipplePattern(int)
    virtual GLSGEN_GLS3DCABLE_EXPORT void LineStipplePattern( int pattern ) DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::LineStipplePattern()
    virtual GLSGEN_GLS3DCABLE_EXPORT int LineStipplePattern() DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::LineStippleMultiplier(int)
    virtual GLSGEN_GLS3DCABLE_EXPORT void LineStippleMultiplier( int mult ) DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::LineStippleMultiplier()
    virtual GLSGEN_GLS3DCABLE_EXPORT int LineStippleMultiplier() DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::PolygonMode()
    virtual GLSGEN_GLS3DCABLE_EXPORT int PolygonMode() DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::PolygonMode(int)
    virtual GLSGEN_GLS3DCABLE_EXPORT void PolygonMode( int mode ) DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::PolygonEnd(const int)
    virtual GLSGEN_GLS3DCABLE_EXPORT void PolygonEnd( const int end ) DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::PolygonEnd()
    virtual GLSGEN_GLS3DCABLE_EXPORT int PolygonEnd() DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::Shading(const int)
    virtual GLSGEN_GLS3DCABLE_EXPORT void Shading( const int shading ) DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::Shading()
    virtual GLSGEN_GLS3DCABLE_EXPORT int Shading() DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::DepthTest(unsigned char)
    virtual GLSGEN_GLS3DCABLE_EXPORT void DepthTest( unsigned char zbuf ) DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::DepthTest()
    virtual GLSGEN_GLS3DCABLE_EXPORT int DepthTest() DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::AntiAlias(bool)
    virtual GLSGEN_GLS3DCABLE_EXPORT void AntiAlias( bool alias ) DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::AntiAlias()
    virtual GLSGEN_GLS3DCABLE_EXPORT bool AntiAlias() DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::AlphaMode(int)
    virtual GLSGEN_GLS3DCABLE_EXPORT void AlphaMode( int mode ) DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::AlphaMode()
    virtual GLSGEN_GLS3DCABLE_EXPORT int AlphaMode() DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::CullBackFace(const bool)
    virtual GLSGEN_GLS3DCABLE_EXPORT void CullBackFace( const bool val ) DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::CullBackFace()
    virtual GLSGEN_GLS3DCABLE_EXPORT bool CullBackFace() DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::LightingEnabled()
    virtual GLSGEN_GLS3DCABLE_EXPORT bool LightingEnabled() DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::LightingEnabled(bool)
    virtual GLSGEN_GLS3DCABLE_EXPORT void LightingEnabled( bool lighting ) DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::SetBlendColor(const GlsColor&)
    virtual GLSGEN_GLS3DCABLE_EXPORT void SetBlendColor( const GlsColor& color ) DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::GetBlendColor()
    virtual GLSGEN_GLS3DCABLE_EXPORT GlsColor GetBlendColor() DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::SetColor(const GlsColor&)
    virtual GLSGEN_GLS3DCABLE_EXPORT void SetColor( const GlsColor& color ) DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::GetColor()
    virtual GLSGEN_GLS3DCABLE_EXPORT GlsColor GetColor() DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::SetFillColor(const GlsColor&)
    virtual GLSGEN_GLS3DCABLE_EXPORT void SetFillColor( const GlsColor& color ) DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::GetFillColor()
    virtual GLSGEN_GLS3DCABLE_EXPORT GlsColor GetFillColor() DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::TextureRepeat(const int)
    virtual GLSGEN_GLS3DCABLE_EXPORT void TextureRepeat( const int rep ) DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::TextureRepeat()
    virtual GLSGEN_GLS3DCABLE_EXPORT bool TextureRepeat() DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::TextureMappingTechnique(const int)
    virtual GLSGEN_GLS3DCABLE_EXPORT void TextureMappingTechnique( const int map ) DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::TextureMappingTechnique()
    virtual GLSGEN_GLS3DCABLE_EXPORT int TextureMappingTechnique() DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::TextureMinificationFilter(const int)
    virtual GLSGEN_GLS3DCABLE_EXPORT void TextureMinificationFilter( const int filter ) DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::TextureMinificationFilter()
    virtual GLSGEN_GLS3DCABLE_EXPORT int TextureMinificationFilter() DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::TextureMagnificationFilter(const int)
    virtual GLSGEN_GLS3DCABLE_EXPORT void TextureMagnificationFilter( const int filter ) DISTI_METHOD_OVERRIDE;
    /// \copydoc DisplayObject::TextureMagnificationFilter()
    virtual GLSGEN_GLS3DCABLE_EXPORT int TextureMagnificationFilter() DISTI_METHOD_OVERRIDE;
 
    //////////////////////////////////////////////////
    // Gls3DCable specific operations
    //////////////////////////////////////////////////
 
    /** Sets flexibility.
      * \param value Controls how stiff the cable is.  The value should be in the 
         range of 0 to 1, inclusive.  0 is very inflexible, while 1 is very flexible.
        \pre value must be in the range of 0 to 1
        \post None
    */
    GLSGEN_GLS3DCABLE_EXPORT void Flexibility( const float& value );
    /** Gets flexibility.
      * \return How stiff the cable is. 
      */
    GLSGEN_GLS3DCABLE_EXPORT float Flexibility();
 
    /** Sets Number of Segements.
      * \param value The number of cylindrical segments that will traverse 
      * the entire length of the cable.  A cable with one section 
      * (that is, with only two control objects) would be a straight cylinder 
      * connecting two points, incapable of bending.  
      * The higher this number, the smoother your cable will appear.
        \pre value must be in the range MIN_SEGEMENTS to MAX_SEGEMENTS
        \post none
    */
    GLSGEN_GLS3DCABLE_EXPORT void NumberOfSegments( const unsigned int& value );
 
    /** Gets the Number of Segements.
      * \return The Number of Segments
      */
    GLSGEN_GLS3DCABLE_EXPORT unsigned int NumberOfSegments();
 
    /** Sets the Number Of Sides. 
      * \param value The number of sides the cable "tube" will have.  
      * The more sides, the smoother the cable will appear.  
      * A value of two will produce a ribbon-like cable.  
      * A value of one will render only a line.
        \pre value must be in the range of 1 to 100 inclusive.
        \post None
    */
    GLSGEN_GLS3DCABLE_EXPORT void NumberOfSides( const unsigned int& value );
 
    /** Gets the Number of Sides.
      * \return The number of sides
      */
    GLSGEN_GLS3DCABLE_EXPORT unsigned int NumberOfSides();
 
    /** Sets the Radius of the cable in logical units
        \param value The radius in logical units.
        \pre value must be plus/minus MAX_FLT
        \post none
    */
    GLSGEN_GLS3DCABLE_EXPORT void Radius( const float& value );
 
    /** Gets the Radius of the cable
      * \return The radius in logical units
      */
    GLSGEN_GLS3DCABLE_EXPORT float Radius();
 
    /** Sets the Length of the cable.
      * when not under duress (the cable will stretch when the end-points 
      * are moved too far from each other).
      * \param value The approximate length of the cable in logical units 
        \pre value must be 0.0 to MAX_FLT
        \post None
    */
    GLSGEN_GLS3DCABLE_EXPORT void Length( const float& value );
 
    /** Gets the Length of the cable.
      * \return The length of the cable in logical units
      */
    GLSGEN_GLS3DCABLE_EXPORT float Length();
 
    /** Sets the CollisionStyle.
      * \param value The collision mode for the cable.  
      * COLLISIONSTYLE_NONE will disable all collision detection and 
      * therefore any cable deformation caused thereby.  
      * COLLISIONSTYLE_FAST will check for collisions with other objects in 
      * the scene, but will only move / orient the cable midpoint such that it 
      * appears as though the cable is laying flat on a single surface.  
      * 
      * Check if USE_COLLISIONSTYLE_SLOW is defined before using Slow.
      */
    GLSGEN_GLS3DCABLE_EXPORT void CollisionStyle( const int& value );
 
    /** Gets the Collision Style
      * \return The current Collision Style
      */
    GLSGEN_GLS3DCABLE_EXPORT int CollisionStyle();
 
    /** Sets the Slack Percentage
      * \param section Which section of the cable, 0 based
      * \param pct The percent of the slace (0.0 -> 1.0)
      * This will adjust the slack percentage in the cable for the section, 
      * the caller must ensure that all percents sum up to 1.0.
        \pre section must be < _sectionSlackPct.Count(), and pct must be 0.0-1.0 
        \post Slack percentage will not change if preconditions are not met.
    */
    GLSGEN_GLS3DCABLE_EXPORT void SlackPct( unsigned int section, double pct );
 
    /** Gets the Slack Percentage for a particular section
      * \param section The section of interest.
      * \return The slack percentage for the specified section.
        \pre section must be < _sectionSlackPct.Count()
        \post if preconditions are not met 0.0 is returned
    */
    GLSGEN_GLS3DCABLE_EXPORT double SlackPct( unsigned int section );
 
    /** 
        How many Slack Sections are there?  Can be used with SlackPct() to
        get set Slack Sections.
        \return Return the number of Slack Sections, 0 to N
        \pre none
        \post none
    */
    GLSGEN_GLS3DCABLE_EXPORT unsigned int SlackSectionCount() const;
 
    /**
        Sometimes an outside source may need to recalculate the cable, such as
        when the scene changes and the cable may not be colliding with another
        object in the scene.
        \pre None
        \post None
    */
    GLSGEN_GLS3DCABLE_EXPORT void ForceCableRecalc();
 
    /// Whether or not to simulate gravity on the cable.
    /// \param value The new gravity flag value.
    GLSGEN_GLS3DCABLE_EXPORT void Gravity( const bool& value );
 
    /** 
        Returns wether or not gavity is simulated on the cable.
        \return Returns wether or not gavity is simulated on the cable
        \pre none
        \post none
    */
    GLSGEN_GLS3DCABLE_EXPORT bool Gravity()
    {
        return _gravity;
    }
 
private:
    /**
        Reallocate, but do not set the vertices that make up the cable line
        \pre None
        \post Will clear _needNewLineVerts, and will set _needCableRecalc
    */
    void AllocateLineVertices();
 
    /**
        \param *root Pointer to a list of objects to search for a collision
        \param &pos Starting point of the ray
        \param &vec Direction vector of the ray
        \param *mag_pct_chg If a float pointer is provided, this will return the percent 
                            change between the new/old Ray magnitude.
                            This is an optional parameter.
        \return Return true if the new magnitude is smaller than the old
        \pre root must exist
        \post
    */
    bool RaycastAdjusted( DisplayObject* root, Vector& pos, Vector& vec, float* mag_pct_chg = NULL );
 
    /**
        Determine if something is colliding with the cable.
        \param *root Pointer to a list of objects to search for a collision
        \param x  The x starting location of the ray
        \param y  The y starting location of the ray
        \param z  The z starting location of the ray
        \param scale The Scale factor of the window
        \param directionVector Direction vector of the ray
        \param &collideDist Return the distance to the collision point from the start point
        \param *collisionPoint Return the closest collision point
        \return true if a hit occurs
        \pre root must exist
        \post None
    */
    bool GlobalHit( DisplayObject* root, float x, float y, float z, float scale, const Vector& directionVector, float& collideDist, Vector* collisionPoint );
 
    /**
        Recompute the line vertices of the cable.
        \return success or failure
        \pre
        \post will clear _needCableRecalc
    */
    bool RecalculateCable();
 
    /**
        Fill out/calculate the cable mesh.
        \pre None
        \post None
    */
    void TubeGeneration();
 
protected:
    /**
       How flexibile is the cable, more flexibility gives a more rounded cable
       This has a range of 0 to 1, 0 is inflexible, 1 is flexible.
    */
    float _flexibility;
 
    /**
        The number of pieces that the entire cable has, the more
        segements the more smooth a cable will appear, e.g., 1 segment
        gives you a straight line, two gives you a 'V', etc.
        This has a range of MIN_SEGEMENTS to MAX_SEGEMENTS
    */
    unsigned int _numberOfSegments;
 
    /**
        How many sides does the cable have.  1 is a wire
        2 is a ribbon cable, 3 a triangle, 4 a sqaure, etc. the more
        sides the closer to a circle you get.
        This has a range of MIN_NUMBER_OF_SIDES to MAX_NUMBER_OF_SIDES.
    */
    unsigned int _numberOfSides;
 
    /**
        The Radius of the cable.   Units are in pixels.
        This has a range of plus/minus FLT_MAX
    */
    float _radius;
 
    /**
        The requested length of the cable, the cable may be longer, if needed to 
        reach between the end points.  A zero length cable can be used to "hide"
        the cable, while leaving the end points intact.  Units are in logical units.
        This has a range of zero to FLT_MAX.
    */
    float _length;
 
    /**
        Does RecalculateCable () need to be called next frame?
    */
    bool _needCableRecalc;
 
    /**
        Does TubeGeneration () need to be called next frame?
    */
    bool _needTubeGeneration;
 
    /**
       Prevents "Hit()" from being called from within RecalculateCable()
    */
    bool _inCableRecalc;
 
    /**
        The _lineVerts are stored in the _line object.  The _line object is used
        for drawing if sides == 1.
    */
    GLPolygon _line;
 
    /**
        The Mesh Verts, Normals, and TexCoords are stored in this object.  The _mesh object
        is used for drawing when sides > 1.
    */
    GLTriMesh _mesh;
 
    /**
        Stores the locations of all of the "EndPoint" objects for ease of use in future calculations.
        Also used to check if any of the positions have changed.
        Endpoints, can be in the middle section of the cable, by "endpoints" it is meant the ends of the sections.
    */
    std::vector<Vector> _endPointPos;
 
    /**
        Stores the dcs orientations of all of the "EndPoint" objects for ease of use in future calculations.
        Also used to check if any of the orientations have changed.
        Endpoints, can be in the middle section of the cable, by "endpoints" it is meant the ends of the sections.
    */
    std::vector<GlsMatrixAffineD> _endPointOri;
 
    /**
        The percentage of slack that each cable segment has (starts out equally divided)...
        but the User can set the percentages.  
        This has a range of >= 0 and <= 1.  The total of all sections should add to 1.
    */
    DynamicDoubleArray _sectionSlackPct;
 
    /**
        Store the DCS Rotation matrix used to calculate the mesh object.  The
        Z is the direction of gravity, so this will effect the slack in the cable.
        Compare this old DCS with the current to determine if we need to recalculate
        the mesh.
    */
    GlsMatrixAffineD _cableDcs;
 
    /**
        The collision type.
    */
    ECollisionStyle _collisionStyle;
 
    bool _gravity; ///< If true, gravity will be simulated on this cable.
 
    /// The number of vertices in the cable line, for each section of the cable.
    /// This INCLUDES the first vertex and the last vertex of each section.
    int _lineVertsPerSection;
 
    /// This will be the summed arc length for all sections.
    /// It is stored because it is used for tube generation.
    float _realCableLength;
 
private:
    // Disable implicit generated Members
    Gls3DCable& operator=( const Gls3DCable& rhs ) DISTI_SPECIAL_MEM_FUN_DELETE;
    Gls3DCable( const Gls3DCable& src ) DISTI_SPECIAL_MEM_FUN_DELETE;
};
 
} // namespace disti
 
#endif