display.h

Go to the documentation of this file.

/*! \file
  \brief  The disti::DisplayObject 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 _DISPLAY_H
#define _DISPLAY_H

#include "cull.h"
#include "display_types.h"
#include "disti_metadata.h"
#include "dynamic_array.h"
#include "editor_object_base.h"
#include "gls_gl.h"
#include "gls_matrix_affine.h"
#include "util.h"
#include "vertex.h"
#include "weak_referenceable_mixin.h"

#ifdef GLES
#    include "gls_state_manager.h"
#endif

/** \namespace disti
  * Contains GL Studio classes and other DiSTI code.
  */
namespace disti
{
// Forward declarations
class DisplayObject;
class DisplayFrame;
class Group;
class DisplayEvent;
class TexturePalette;
class CallbackMethodCallerBase;
class GlsResourceFilter;
class DisplayObjectEditor;
class Culler;
#ifdef GLES
class GlsGloFile;
class GlsGloFileAttribute;
#endif

// Call this to unlock the GL Studio Runtime library.
// It must be called before any DisplayObject is constructed.
GLS_EXPORT void InitializeLibrary( const char* unlockString = NULL, const DisplayFrame* frame = NULL, bool checkLicense = false );

// Returns a string with the name of the company which
// was passed in inside the unlockString of InitializeLibrary().
// Do not free the returned pointer
GLS_EXPORT const char* LicenseUnlockedBy();

typedef DisplayObject*                 DisplayObjectPtr;
typedef DynamicArray<DisplayObjectPtr> DisplayObjectArray;
typedef DynamicArray<int>              DynamicIntArray;

/** \class DisplayObject
    Base Class for all graphical objects. It is an abstract class. Each
    object drawn in the editor will have a corresponding object.  All drawn objects
    are derived from this class.
*/

class DisplayObject : virtual public AttributeChangedNotifier
    , public WeakReferenceableMixin
{
    friend class DisplayObjectEditor;

public:
    /** The default constructor for display objects.  Generally invoked
      * by constructors of derived classes. 
      * \param x  X coordinate of object location
      * \param y  Y coordinate of object location
      * \param z  Z coordinate of object location
      */
    GLS_EXPORT DisplayObject( float x, float y, float z );

    /** The copy constructor for display objects
      * 
      * \param object           The display object that is being copied
      * \param generateNames    Whether or not to generate a new instance name
     */
    GLS_EXPORT DisplayObject( const DisplayObject& object, const bool generateNames );

    /** Virtual destructor for display object */
    virtual GLS_EXPORT ~DisplayObject( void );

    /** Call this to delete objects, as it handles special cases
      * like cleanup of LiveComponents.*/
    GLS_EXPORT void Destroy();

#ifndef GLES
    static GLS_EXPORT InterfaceListType* StaticGetCppInterfaceDescription( InterfaceListType* addToThisList = NULL );
#endif
    /** Sets and retrieves the current setting used for determining what attributes get
      * created for each object.*/
    typedef enum
    {
        GLS_ATTRIBUTES_BASIC       = 1,
        GLS_ATTRIBUTES_DYNAMIC     = 2,
        GLS_ATTRIBUTES_APPEARANCE  = 4,
        GLS_ATTRIBUTES_GEOMETRY    = 8,
        GLS_ATTRIBUTES_SPECIALIZED = 16,
        GLS_ATTRIBUTES_ALL         = ~0,
        GLS_ATTRIBUTES_NONE        = 0
    } AvailableAttributesEnum;

    /** Specifies which attributes are available for the object.
      * Currently the available attributes cannot be changed after they have been set.
      * (Only the first call has an effect.)
      * \param value A bitfield specifying which types of attributes to make available.
      * \sa AvailableAttributesEnum
      */
    virtual GLS_EXPORT void SetAvailableAttributes( unsigned int value );

    /** Set the alpha mode state for this object
      * \param mode which alpha mode to use when drawing 
      * \sa AlphaMode_e
      */
    virtual GLS_EXPORT void AlphaMode( int mode );

    /** Get the alpha mode for this object
      * \return Whether or not alpha testing or blending is enabled when drawing
      * \sa AlphaMode_e
      */
    virtual GLS_EXPORT int AlphaMode( void );

    /** Get the anti aliasing state this object
      * \return Whether or not this object will be drawn antialiased
      */
    virtual GLS_EXPORT bool AntiAlias( void );

    /** Set the anti aliasing state for this object
      * \param alias  Whether or not to perform anti aliasing
      */
    virtual GLS_EXPORT void AntiAlias( bool alias );

    /** Second half of texture setup.  Applies texture modes like modulate, decal, etc.
      * \param textureIndex  Index of the texture to apply
      */
    GLS_EXPORT void ApplyTextureSettings( int textureIndex = -1 /* will use _textureIndex by default */ );

    /** Gets the full list of attributes for this object
      * \return A reference to the attribute dictionary in this object
      */
    inline DistiAttribDict&       Attributes() { return *_attribDict; };
    inline const DistiAttribDict& Attributes() const { return *_attribDict; };

    /** Sets the texture blend color for the object 
      * \param color A GlsColor
      */
    virtual GLS_EXPORT void SetBlendColor( const GlsColor& color );

    /** Gets the texture blend color for the object
      * \param color Filled in with RGBA (0-255 range)
      * NOTE: Not Virtual.  Simply calls void GetBlendColor(const GlsColor& color);
      */
    GLS_EXPORT void GetBlendColor( unsigned char color[] );

    /** Gets the texture blend color for the object
      * \param r Returns red color component (0-255 range)
      * \param g Returns Green color component (0-255 range)
      * \param b Returns Blue color component (0-255 range)
      * \param a Returns Alpha color component (0-255 range)
      * NOTE: Not Virtual.  Simply calls void GetBlendColor(const GlsColor& color);
      */
    GLS_EXPORT void GetBlendColor( unsigned char& r, unsigned char& g, unsigned char& b, unsigned char& a );

    /** Gets the texture blend color for the object
      * \return Returns the current texture blend color.
      */
    virtual GLS_EXPORT GlsColor GetBlendColor();

    /** Sets the texture blend color for the object
      * \param color  RGBA color (0-255 range)
      * NOTE: Not Virtual.  Simply calls void SetBlendColor(const GlsColor& color);
      */
    GLS_EXPORT void SetBlendColor( unsigned char color[] );

    /** Sets the texture blend color for the object
      * \param r Red color component (0-255 range)
      * \param g Green color component (0-255 range)
      * \param b Blue color component (0-255 range)
      * \param a Alpha color component (0-255 range)
      * NOTE: Not Virtual.  Simply calls void SetBlendColor(const GlsColor& color);
      */
    GLS_EXPORT void SetBlendColor( unsigned char r, unsigned char g, unsigned char b, unsigned char a );

    /** Determines if the object is blinked on or off */
    GLS_EXPORT bool BlinkedOff( void );

    /** Get the blinking state this object
      * \return Whether or not this object is blinking    
      */
    virtual GLS_EXPORT bool Blinking( void );

    /** Set the blinking state for this object
      * \param blink  Whether or not to blink this object
      */
    virtual GLS_EXPORT void Blinking( const bool blink );

    /** Get the blinking rate this object
      * \return The rate at which this object is blinking
      */
    virtual GLS_EXPORT float BlinkRate( void );

    /** Set the blinking rate for this object
      * \param rate  Number of times per second to blink this object
      */
    virtual GLS_EXPORT void BlinkRate( const float rate );

    /** Sets whether the application should use the system time or a manual time
      * for calculating the blink state of objects
      */
    static GLS_EXPORT void UseManualBlinkElapsedTime( bool useManualTime );

    /** Sets the time the application will use to determine the blink state of
      * objects.  Has no effect if UseManualBlinkElapsedTime was not set to true.
      */
    static GLS_EXPORT void SetManualBlinkElapsedTime( double elapsedTime );

    /** Get the current bounding volume center 
      * \return The current bounding volume center
      */
    inline const Vector& BoundingVolumeCenter() const { return _boundingVolumeCenter; }

    /** Set the current bounding volume center 
      * \param center The new center
      */
    void GLS_EXPORT BoundingVolumeCenter( const Vector& center );

    /** Determines if the given ray hits this bounding volume
      * \param start     Starting point of the ray
      * \param direction Direction vector of the ray
      * \return  True if this bounding volume hit by the ray
      */
    bool GLS_EXPORT BoundingVolumeHit( const Vector& start, const Vector& direction );

    /** Get the bounding sphere radius
      * \return The bounding sphere radius
      */
    inline float BoundingVolumeRadius() const { return _boundingVolumeRadius; }

    /** Set the bounding sphere radius
      * \param radius The bounding sphere radius
      */
    void GLS_EXPORT BoundingVolumeRadius( float radius );

    /** Provides a mechanism for performing regular calculations, seperate 
      * from drawing.  In a standalone applicaton Calculate is recursively 
      * called by the main loop before the objects are drawn.
      * \param  time The elaspsed time in seconds since program start
      */
    virtual GLS_EXPORT void Calculate( double time );

    /** Calculates where the pick vector hit this object 
      * \param pickLoc  Start of the pick vector
      * \param directionVector  Direction of the pick vector
      * \param collisionPoint  Returns the collision point
      */
    GLS_EXPORT void CalculateCollisionPoint( const Vector& pickLoc, const Vector& directionVector, Vector* collisionPoint );

    /** Calculates the bounding box of the parent group object.
      */
    virtual GLS_EXPORT void CalculateParentBoundingBox( void );

    /** Recalculates the texture coordinates for the object based on the TexturePoints.
      */
    virtual GLS_EXPORT void CalculateTextureCoordinates( void );

    /** Converts the object's texture points into a transformation matrix
      * for use in calculating the object's texture coordinates
      */
    GLS_EXPORT bool GetTexturePointTransformationMatrix( GlsMatrixType& world2tex );

    /** \return The current callback method for this object */
    inline CallbackMethodCallerBase* CallbackCaller() const { return _callbackCaller; }

    /** Sets the callback method for this object.  cb MUST be dynamically allocated since
    * memory management will be passed to this display object.  cb will be deleted when
    * a new callback is registered via this method or when the display object is
    * destructed.
    * \param cb The new callback method for this object 
    */
    GLS_EXPORT void CallbackCaller( CallbackMethodCallerBase* cb );

    /** Gets the location of the center of the object in logical units.  Value is based on the 
      * extents of the object and does not take into consideration dynamic rotation
      * \param center  Will contain the center coordinate on return
      */
    virtual GLS_EXPORT void GetCenter( Vector& center );

    /** Copy+Create operation in one method. In derived classes, this
      * method will create a new instance of the derived class and then
      * copy the object into the new instance. The cut,copy,paste and undo
      * operations use this method.
      * \param generateNames  Whether or not to generate new names for cloned objects
      * \return A new object, identical to the original, except for the instance name
      */
    virtual DisplayObject* CloneObject( bool generateNames = false ) = 0;

    /** Gets the color for the object outline
      * \return The outline color
      */
    virtual GLS_EXPORT GlsColor GetColor();

    /** Gets the RGBA color for the object outline
      * \param c4  Gets the RGBA line color (0-255 range) for the object
      * NOTE: Not Virtual.  Simply calls void GetColor(const GlsColor& color)
      */
    GLS_EXPORT void GetColor( unsigned char c4[] );

    /** Gets the RGBA color for the object outline
      * \param r  Gets the red component (0-255 range) of the line color for the object
      * \param g  Gets the blue component (0-255 range) of the line color for the object
      * \param b  Gets the green component (0-255 range) of the line color for the object
      * \param a  Gets the alpha component (0-255 range) of the line color for the object
     * NOTE: Not Virtual.  Simply calls void GetColor(const GlsColor& color)
      */
    GLS_EXPORT void GetColor( unsigned char& r, unsigned char& g, unsigned char& b, unsigned char& a );

    /** Sets the RGBA color for the object outline
      * \param color The new color 
      */
    virtual GLS_EXPORT void SetColor( const GlsColor& color );

    /** Sets the RGBA color for the object outline
      * \param c4  The new RGBA (0-255 range) line color for the object
      * NOTE: Not Virtual.  Simply calls void SetColor(const GlsColor& color)
      */
    inline void SetColor( unsigned char c4[] ) { SetColor( GlsColor( c4 ) ); }

    /** Sets the RGBA color for the object outline
      * \param r  The new red component (0-255 range) of the line color for the object
      * \param g  The new blue component (0-255 range) of the line color for the object
      * \param b  The new green component (0-255 range) of the line color for the object
      * \param a  The new alpha component (0-255 range) of the line color for the object
      * NOTE: Not Virtual.  Simply calls void SetColor(const GlsColor& color)
      */
    inline void SetColor( unsigned char r, unsigned char g, unsigned char b, unsigned char a ) { SetColor( GlsColor( r, g, b, a ) ); }

    /** Copies the geometry information from one object to another. Used by
      * the undo mechanism to allow user to undo a geometry change.
      * \param src   The object to copy geometry from */
    virtual GLS_EXPORT void CopyGeometry( DisplayObject* src );

    /** Copies the hierarchy information from one object to another
      * \param src  The object to copy from
      * \param copyName  Whether or not to copy the object name
      */
    virtual GLS_EXPORT void CopyHierarchyProperties( DisplayObject* src, bool copyName );

    /** Copies the attributes except for geometry attributes from one object
      * to another. Used by the undo mechanism to undo most attribute change
      * operations.
      * \param src   The object to copy properties from */
    virtual GLS_EXPORT void CopyProperties( DisplayObject* src );

#ifndef GLES
    /** Get the details of the Cpp Interface
      * The actual interface is exposed in compiled code.
      * \param addToThisList If not NULL this list will be added to then returned.  If NULL a new list will be created.
      * \return A templated list.  
      * The caller must call the corresponding free method to
      * safely free the memory.
      */
    virtual GLS_EXPORT InterfaceListType* GetCppInterfaceDescription( InterfaceListType* addToThisList = NULL );

    /** Frees the memory allocated by a previous call to GetCppInterfaceDescription
      * \param array  Memory allocated by a previous call to GetCppInterfaceDescription
      */
    virtual GLS_EXPORT void GetCppInterfaceDescriptionFree( InterfaceListType* array );
#endif

    /** Sets if back faces should be removed 
      * \param val True if back faces should be removed
      */
    virtual GLS_EXPORT void CullBackFace( const bool val );

    /** Returns if back faces should be removed 
      * \return True if backfaces are removed 
      */
    virtual GLS_EXPORT bool CullBackFace( void );

    /** Whether or not this object is currently culled */
    inline bool Culled() const { return _culled; }
    inline void Culled( bool val ) { _culled = val; }

    /** This is the cull test normally performed within PreDraw()
      * \param matrix transformation from vertices to the frustrums coordinate system
      * \param culler Culler to perform the test
      */
    inline bool CullTest( const GlsMatrixType* matrix, const Culler& culler )
    {
        // Make some vectors representing a unit sphere
        Vector loc( _boundingVolumeCenter + _location );
        Vector i( loc );
        Vector j( loc );
        Vector k( loc );

        i.x += 1.0f;
        j.y += 1.0f;
        k.z += 1.0f;

        // Transform into the frustrums coordinate system
        matrix->Transform( loc );
        matrix->Transform( i );
        matrix->Transform( j );
        matrix->Transform( k );

        // Subtract the location to get the radius vectors
        i -= loc;
        j -= loc;
        k -= loc;

        // Find the largest radius of the transformed sphere
#ifdef SUNOS
        float maxRadius = sqrt( MAX( i.MagnitudeSquared(), MAX( j.MagnitudeSquared(), k.MagnitudeSquared() ) ) );
#else
        float maxRadius = sqrtf( MAX( i.MagnitudeSquared(), MAX( j.MagnitudeSquared(), k.MagnitudeSquared() ) ) );
#endif
        return culler.SphereOutsideFrustum( loc, maxRadius * _boundingVolumeRadius );
    }

    /** Gets the objects Dynamic Coordinate System (DCS) Matrix
      * \return A reference to the Dcs Matrix stored in the object
      */
    GlsMatrixType& DcsMatrix() { return _dcsMatrix; } // deprecated
    GlsMatrixType  DcsMatrix() const { return _dcsMatrix; }

    /** Sets the dcs matrix
      * \param matrix the dcs matrix
      */
    void GLS_EXPORT DcsMatrix( const GlsMatrixType& matrix );

    /** Remove the Vertex at the given index.
      * \param index The index to remove (1 based)   
      */
    virtual GLS_EXPORT void DeleteVertex( unsigned int index );

    /** Get the z buffering state for this object
      * \return Whether or not this object will be draw Z buffered
      */
    virtual GLS_EXPORT int DepthTest( void );

    /** Set the z buffering state for this object
      * \param zbuf  Whether or not to perform z buffering
      */
    virtual GLS_EXPORT void DepthTest( unsigned char zbuf );

    /** Draws this object on the current display frame (_parent member).
        Pure virtual method */
    virtual void Draw( void ) = 0;

    /** \returns This object's _drawMatrix (it's contribution to the ModelMatrix)
      * or NULL if the object does not have a _drawMatrix.
      */
    inline const GlsMatrixType* DrawMatrix() { return _drawMatrix; }

    /** \returns True if the draw matrix needs to be calculated 
      */
    inline bool NeedCalcDrawMatrix() { return _needCalcDrawMatrix; }

    /** Sets the dynamic rotation to the specified value for the specified axis (in degrees)
      * \param angle The new dynamic rotation angle for the object
      * \param axis The axis to change
      * NOTE: Not virtual
      */
    GLS_EXPORT void DynamicRotate( float angle, int axis );

    /** Sets the dynamic rotation to the specified value for all axes (in degrees)
      * \param v Vector containing the new dynamic rotation angles for each axis
      */
    GLS_EXPORT void DynamicRotate( const Vector& v );

    /** Sets the dynamic rotation to the specified value for all axes (in degrees)
      * \param angle Array of three floats containing the new dynamic rotation angles for each axis
      */
    GLS_EXPORT void DynamicRotate( float angle[] );

    /** Sets the dynamic rotation to the specified value for all axes (in degrees)
      * \param  x The new dynamic rotation angle for the X axis
      * \param  y The new dynamic rotation angle for the Y axis
      * \param  z The new dynamic rotation angle for the Z axis
      * NOTE: Is virtual.  If needed overload this method.
      */
    virtual GLS_EXPORT void DynamicRotate( float x, float y, float z );

    /** Changes the dynamic rotation by the specified value for the specified axis (in degrees)
      * \param angle The change in dynamic rotation angle for the object
      * \param axis  The axis to change
      */
    virtual GLS_EXPORT void DynamicRotateRelative( float angle, int axis );

    /** Gets the dynamic rotation to the specified value for
      * the specified axis. 
      * \param axis The axis to get the rotation from 
      * \return The dynamic rotation angle for the axis (in degrees)
      */
    virtual GLS_EXPORT float DynamicRotation( int axis );
    virtual GLS_EXPORT Vector DynamicRotation();

    /** Returns the dynamic scale values in a Vertex
      * \return The dynamic scale values
      * NOTE: Not virtual
      */
    virtual GLS_EXPORT Vector DynamicScale();

    /** Sets the dynamic scale values for an object.
      * \param x X scale
      * \param y Y scale
      * \param z Z scale
      */
    virtual GLS_EXPORT void DynamicScale( float x, float y, float z );

    /** Sets the dynamic scale values for an object.
      * \param scale The new dynamic scale for the object
      */
    GLS_EXPORT void DynamicScale( const Vector& scale );

    /** Sets the dynamic translation to the specified value for all axes (in logical units)
      * \note Make sure to pass float values for x,y,z here, 
              or the compiler may choose an unexpected method signature. 
      * \sa DynamicTranslate(float, int, bool)
      * \param  x The new dynamic translation for the X axis
      * \param  y The new dynamic translation for the Y axis
      * \param  z The new dynamic translation for the Z axis
      * \param  relative If true will add to existing dynamic translation
      */
    virtual GLS_EXPORT void DynamicTranslate( float x, float y, float z, bool relative = false );

    /** Sets the dynamic translation to the specified value for all axes (in logical units)
      * \param  amount The new dynamic translation for the X, Y, and Z axes
      * \param  relative If true will add to existing dynamic translation
      * NOTE: Not virtual
      */
    GLS_EXPORT void DynamicTranslate( const Vertex& amount, bool relative );

    /** Sets the dynamic translation to the specified value for all axes (in logical units).  Equivalent to DynamicTranslate( amount, false );
      * \param  amount The new dynamic translation for the X, Y, and Z axes
      * NOTE: Not virtual
      */
    GLS_EXPORT void DynamicTranslate( const Vector& amount );

    /** Sets the dynamic translation to the specified value for the specified axis
      * \param  amount The new dynamic translation for the axis
      * \param  axis Z_AXIS, Y_AXIS, or X_AXIS
      * \param  relative If true will add to existing dynamic translation
      */
#ifdef GLES
    virtual GLS_EXPORT void DynamicTranslateAxis( float amount, int axis, bool relative );
#else
    virtual GLS_EXPORT void DynamicTranslate( float amount, int axis, bool relative = false );
#endif
    /** Returns the current dynamic translation for the specified axis
      * \param axis Z_AXIS, Y_AXIS, or X_AXIS
      * \returns the translation
      */
    virtual GLS_EXPORT float DynamicTranslation( int axis );

    /** Returns the current dynamic translation for all axes
      * \returns the translation
      */
    virtual GLS_EXPORT Vector DynamicTranslation();

    /** Used in the editor to access editor functionality.  Gets the editor object pointer.
     * USER CODE SHOULD NOT USE THIS METHOD!
     * \return Pointer to editor object.
     */
    GLS_EXPORT DisplayObjectEditor* Editor();

    /** Used in the editor to access editor functionality.  Gets the editor object pointer.
     * USER CODE SHOULD NOT USE THIS METHOD!
     * \return Pointer to editor object.
     */
    GLS_EXPORT const DisplayObjectEditor* Editor() const;

    /** Used in the editor to access editor functionality.  Sets the editor object pointer.
     * USER CODE SHOULD NOT USE THIS METHOD!
     * \param editor Pointer to editor object.
     */
    GLS_EXPORT void Editor( DisplayObjectEditor* editor );

    /** Figure out the static extents for the object.
      * Used by the editor as part of the pick operation and
      * for figuring out the size of groups.
      * \param x   Gets the minimum x extent
      * \param y   Gets the minimum y extent
      * \param z   Gets the minimum z extent
      * \param x1  Gets the maximum x extent
      * \param y1  Gets the maximum y extent
      * \param z1  Gets the maximum z extent
      */
    virtual GLS_EXPORT void GetExtents( float& x, float& y, float& z, float& x1, float& y1, float& z1 );

    /** Determines the static extents of geometry projected to the XY plane of the object's DCS.
      * \param min Returns the minimum values found in the traversal
      * \param max Returns the maximum values found in the traversal
      */
    GLS_EXPORT void GetExtentsDCS( Vector& min, Vector& max );

    /** Gets the RGBA color for filling the object
      * \param r  Gets the red component (0-255 range) of the fill color for the object
      * \param g  Gets the blue component (0-255 range) of the fill color for the object
      * \param b  Gets the green component (0-255 range) of the fill color for the object
      * \param a  Gets the alpha component (0-255 range) of the fill color for the object
      * NOTE: NOT Virtual Simply calls GlsColor GetFillColor()
      */
    GLS_EXPORT void GetFillColor( unsigned char& r, unsigned char& g,
        unsigned char& b, unsigned char& a );

    /** Gets the RGBA color for filling the object
      * \param c4  Gets the RGBA fill color (0-255 range) for the object
      * NOTE: NOT Virtual.  Simply calls GlsColor GetFillColor()
      */
    GLS_EXPORT void GetFillColor( unsigned char c4[] );

    /** Gets the fill color of the object
      * \return The fill color
      */
    virtual GLS_EXPORT GlsColor GetFillColor( void );

    /** Sets the RGBA color for filling the object
      * \param r  The new red component (0-255 range) of the fill color for the object
      * \param g  The new blue component (0-255 range) of the fill color for the object
      * \param b  The new green component (0-255 range) of the fill color for the object
      * \param a  The new alpha component (0-255 range) of the fill color for the object
      * NOTE: Not Virtual.  Simply calls void SetFillColor(const GlsColor& color)
      */
    inline void SetFillColor( unsigned char r, unsigned char g, unsigned char b, unsigned char a ) { SetFillColor( GlsColor( r, g, b, a ) ); }

    /** Sets the RGBA color for filling the object
      * \param c4  The new RGBA fill color (0-255 range) for the object
      * NOTE: Not Virtual.  Simply calls void SetFillColor(const GlsColor& color)
      */
    inline void SetFillColor( unsigned char c4[] ) { SetFillColor( GlsColor( c4 ) ); }

    /** Sets the RGBA color for filling the object
      * \param color  The new RGBA fill color (0-255 range) for the object
      */
    virtual GLS_EXPORT void SetFillColor( const GlsColor& color );

    /* Dynamically generate a name for the object, based on the current time
      */
    virtual GLS_EXPORT void GenerateInstanceName( void );

    /** Handles an event that is sent to the object.
      * \param ev  The event to send to the object
      * \returns   Which object handled the event
      */
    virtual GLS_EXPORT DisplayObject* handle( DisplayEvent* ev );

    /** Determines if the object is hit by a pick ray starting at (x,y,z) and pointing towards directionVector in object logical coordinate system.
      * If Pickable() == PICK_BEST it will return the closest point that was hit, otherwise it returns the first point that was hit.
      * This method should not pick points behind the viewer.
      *
      * \param x  X coordinate of pick ray start in logical coordinates.
      * \param y  Y coordinate of pick ray start in logical coordinates.
      * \param y  Y coordinate of pick ray start in logical coordinates.
      * \param z  Z coordinate of pick ray start in logical coordinates.
      * \param scale The scale factor of the window. Affects picking of outlines.  Standard value is 1.0.
      * \param directionVector  The direction of the pick ray.
      * \param collisionPoint If this method returns true, this Vector will contain the location that was hit in logical coordinates.
      * \return boolean indicating if the object was hit by the pick ray.
      */
    virtual GLS_EXPORT bool Hit( float x, float y, float z, float scale, const Vector& directionVector, Vector* collisionPoint );

    /** Determines if the object is hit by a pick ray starting at (x,y,z) and pointing towards directionVector in the object logical coordinate system
      * If Pickable() == PICK_BEST it will return the closest point that was hit, otherwise it returns the first point that was hit.
      * This method should not pick points behind the viewer.
      *
      * \param x  X coordinate of pick ray start in logical coordinates.
      * \param y  Y coordinate of pick ray start in logical coordinates.
      * \param y  Y coordinate of pick ray start in logical coordinates.
      * \param z  Z coordinate of pick ray start in logical coordinates.
      * \param scale The scale factor of the window. Affects picking of outlines.  Standard value is 1.0.
      * \param vertices An array of vertices describing the Object.
      * \param vertex_cnt Size of the vertices array.
      * \param directionVector  The direction of the pick vector.
      * \param collisionPoint If this method returns true, this Vector will contain the location that was hit in logical coordinates.
      * \return True if click is inside, false otherwise.
      *
      * Comment:   The hit determination algorithm is based on the principle
      *            that a point is inside a polygon if a line drawn through the
      *            point intersects an even number of edges.
      */
    virtual GLS_EXPORT bool HitUtil( float x, float y, float z, float scale, Vertex* vertices, unsigned int vertex_cnt, const Vector& directionVector, Vector* collisionPoint );

    /** Insert a vertex at an index.  Duplicate the vertex pointed to
      * by index, so that there are two vertices that are exactly the same.
      * \param index  The index to insert the vertex at (1 based, not zero)
      */
    virtual GLS_EXPORT void InsertVertex( unsigned int index );

    /** Gets the name for the object.
      * \return The name of the object
      */
    GLS_EXPORT char*       InstanceName( void );
    GLS_EXPORT const char* InstanceName( void ) const;

    /** Sets the name for the object. This name corresponds to the name
      * that is generated in the source code.
      * \param name The new name for the object
      */
    GLS_EXPORT void InstanceName( const char* name );

    /** Gets the lighting state */
    virtual GLS_EXPORT bool LightingEnabled();

    /** Sets the lighting state */
    virtual GLS_EXPORT void LightingEnabled( bool lighting );

    /** Get the line stipple multiplier for this object
      * \return The line stipple multiplier for this object
      */
    virtual GLS_EXPORT int LineStippleMultiplier( void );

    /** Set the line stipple multiplier for this object
      * \param mult   The new line stipple pattern
      */
    virtual GLS_EXPORT void LineStippleMultiplier( int mult );

    /** Get the line stipple pattern for this object
      * \return The line stipple pattern for this object
      */
    virtual GLS_EXPORT int LineStipplePattern( void );

    /** Set the line stipple pattern for this object
      * \param pattern   The new line stipple pattern
      */
    virtual GLS_EXPORT void LineStipplePattern( int pattern );

    /** Gets the width of lines in the object.
      * \return  The line width of the object in logical units
      */
    virtual GLS_EXPORT float LineWidth( void );

    /** Sets the width of lines in the object.
      * \param width  The new line width of the object in logical units
      */
    virtual GLS_EXPORT void LineWidth( float width );

    /** \return  The location of the origin of the object
      * Lifetime is guaranteed to coincide with the DisplayObject's lifetime.
      */
    virtual GLS_EXPORT const Vertex& Location( void ) const;

    /** Sets the location of the origin of the object
      * \param v   The new location
      */
    virtual GLS_EXPORT void Location( const Vertex& v );

    /** Sets the location of the origin of the object
      * \param x X Coordinate of the new location
      * \param y Y Coordinate of the new location
      * \param z Z Coordinate of the new location
      */
    virtual GLS_EXPORT void Location( float x, float y, float z );

    /** Gets the location of the origin of the object
      * \param v   Will be filled in with the current location
      */
    virtual GLS_EXPORT void GetLocation( Vertex& v );

    /** Gets the location of the origin of the object
      * \param x   Will be filled in with the x coordinate
      * \param y   Will be filled in with the y coordinate
      * \param z   Will be filled in with the z coordinate
      */
    virtual GLS_EXPORT void GetLocation( float& x, float& y, float& z );

    /** \return X component of location */
    inline float X( void ) const { return Location().x; }

    /** \return Y component of location */
    inline float Y( void ) const { return Location().y; }

    /** \return Z component of location */
    inline float Z( void ) const { return Location().z; }

    /** Sets x component of location */
    inline void X( const float x ) { Location( x, Y(), Z() ); }

    /** Sets y component of location */
    inline void Y( const float y ) { Location( X(), y, Z() ); }

    /** Sets z component of location */
    inline void Z( const float z ) { Location( X(), Y(), z ); }

    /** Gets material index.  Returns -1 if multiple are applied. */
    virtual GLS_EXPORT int MaterialIndex();

    /** Sets the material index. */
    virtual GLS_EXPORT void MaterialIndex( int index );

    /** Gets a vector of material indices. */
    virtual GLS_EXPORT DynamicArray<int>& MaterialIndices();

    /** Sets the vector of material indices. */
    virtual GLS_EXPORT void MaterialIndices( DynamicArray<int> indices );

    /** \return The saved Model matrix, if any. Normally not used by the user.*/
    GLS_EXPORT GlsMatrixType* ModelMatrix();

    /** \return true if Calculate() needs to be called on this object */
    inline bool NeedCalculate() { return _needCalculate; }

    /** Gets the object's normals.
      * \return  Pointer to the object's normal vertex array
      */
    inline Vector* Normals() { return ( _normals ); }

    /** Sets the vertex normal data for this object
      * \param nPoints  The number of vertices in the object
      * \param vertices  The vertex normals for the object
      */
    virtual GLS_EXPORT void SetNormals( unsigned int nPoints, Vector* vertices );

    /** Sets the vertex normal data for this object
      * \param nPoints  The number of vertices in the object
      * \param ...  X,Y,Z for each vertex normal
      */
    GLS_EXPORT void VaSetNormals( unsigned int nPoints, ... );

    /** Gets the object's number of vertices.
      * \return  The integer number of vertices in the object
      */
    inline unsigned int NumberOfVertices() const { return ( _nVertices ); }

    /** Get the depth (in the Z Dimension) of the object in logical units.  Value is based on the 
      * extents of the object and does not take into consideration dynamic rotation
      * \return  The depth in logical units (based on extents in the Z Dimension)
      */
    virtual GLS_EXPORT float ObjectDepth( void );

    /** Get the height (in the Y Dimension) of the object in logical units.  Value is based on the 
      * extents of the object and does not take into consideration dynamic rotation
      * \return  The height in logical units (based on extents in the Y Dimension)
      */
    virtual GLS_EXPORT float ObjectHeight( void );

    /** Get the width (in the X Dimension) of the object in logical units.  Value is based on the 
      * extents of the object and does not take into consideration dynamic rotation
      * \return  The width in logical units (based on extents in the X Dimension)
      */
    virtual GLS_EXPORT float ObjectWidth( void );

    /** Redefines the frame of reference for the object.  Since the vertices in the object are 
      * specified relative to the _location member, this routine allows you to specify the 
      * absolute coordinate for _location and then recalculates the vertices to be relative to that 
      * new location
      * \param vert  The new origin point for the object
      */
    virtual GLS_EXPORT void SetOrigin( const Vertex& vert );

    /** Sets the parent display frame pointer for this object to the indicated display frame
      * \param par  The new display frame to be the parent object
      */
    virtual GLS_EXPORT void Parent( DisplayFrame* par );

    /** Gets the parent display frame pointer for this object
      * \return The parent display frame of this object
      */
    inline DisplayFrame* Parent( void ) const { return _parent; }

    /** Sets the parentGroup pointer for this object
      * \param group  The group to which this object belongs
      */
    virtual GLS_EXPORT void ParentGroup( Group* group );

    /** Gets the parentGroup pointer for this object
      * \return The group to which this object belongs
      */
    inline Group* ParentGroup( void ) const { return _parentGroup; }

    /** Attempts to pick an object in 3D and accounting for dynamic rotations and translations of this object or
      * parent objects. It also looks at the pickable status and attempts to return the "Best" pick if that is 
      * what is desired.
      *
      * Note: This method will pick objects in the scene based on a pick ray starting at winLoc and pointing into the screen.
      * It will not pick objects behind the depth specified by winLoc.z.  Typically winLoc.z should be set to 0 to ensure that
      * the pick ray starts at near clip plane.
      *
      * \param winLoc          Device coordinates for the mouse click.  Z value should be set to 0 to ensure pick ray starts at near clip plane.
      * \param logicalCoords   The start of the pick ray in logical coordinates.  Should be calculated from the winLoc using this->WindowToLogical(winLoc, logicalCoords, &directionVector).
      * \param scale           Current window scale. Affects picking radius of outlines.  Initial value should typically be 1.0.
      * \param directionVector The direction of the pick ray in logical coordinates.  Should be calculated from the winLoc using this->WindowToLogical(winLoc, logicalCoords, &directionVector).
      * \param collisionWinLoc  Returns where the pick vector intersects the object that is hit in device coordinates.
      * \param drawnMatrices   The matrices used to draw the object, including matrices set by parents that may have
      *                        dynamically rotated, translated or scaled this object.  Initial value should typically be a default OpenGLMatrices() object.
      *
      * \return  The object that was hit, or NULL if no object hit
      */
    virtual GLS_EXPORT DisplayObject* Pick3D( const Vector& winLoc,
        const Vector&                                       logicalCoords,
        float                                               scale,
        const Vector&                                       directionVector,
        Vector&                                             collisionWinLoc, /*Returned*/
        const OpenGLMatrices&                               drawnMatrices );

    /** Get the pickable state for this object
      * \return The pick mode
      * \sa PickableType_e
      */
    inline unsigned char Pickable() { return _pickable; }

    /** Set the pickable state for this object
      * \param pick The pick mode
      * \sa PickableType_e
      */
    virtual GLS_EXPORT void Pickable( unsigned char pick );

    /* Gets the polygon offset (Z buffer offset) for this object
      * \return mode The new polygon offset for this object
      * Currently unused.
      */
    virtual GLS_EXPORT int PolygonOffset( void ) const;

    /* Sets the polygon offset (Z buffer offset) for this object
      * \param mode The new polygon offset for this object
      * Currently unused.
      */
    virtual GLS_EXPORT void PolygonOffset( const int offset );

    /** Gets the polygon end mode (Open or Closed) for the polygon
      * \return Enumeration indicating open or closed mode
      * \sa PolygonClose_e
      */
    virtual GLS_EXPORT int PolygonEnd( void );

    /** Sets the polygon end mode (Open or Closed) for the polygon
      * \param end  Enumeration indicating open or closed mode
      * \sa PolygonClose_e
      */
    virtual GLS_EXPORT void PolygonEnd( const int end );

    /** Gets the polygon drawing mode for this object
      * \return The polygon drawing mode for this object
      * \sa PolygonMode_e
      */
    virtual GLS_EXPORT int PolygonMode( void );

    /** Sets the polygon drawing mode for this object
      * \param mode The new polygon drawing mode for this object
      * \sa PolygonMode_e
      */
    virtual GLS_EXPORT void PolygonMode( int mode );

    /** Traverses the hierarchy calculating the 
      * _modelMatrix, _projMatrix, _viewMatrix as needed.
      * \param current  Current matrices inherited from parent
      * \param culler   Object that possibly marks this object for culling
      */
    virtual GLS_EXPORT void PreDraw( const OpenGLMatrices& current, Culler& culler );

    /** \return The saved Projection matrix, if any. Normally not used by the user.
      */
    GLS_EXPORT GlsMatrixType* ProjMatrix();

    /** Reallocates the vertex and texture coordinate and normal arrays.  Existing vertices are 
      * copied .  If the new size is less than the old size, the first numVertices vertices are 
      * copied.  If the new size is larger, all vertices are copied and the new vertices are 
      * initialized to zero.
      * \param numVertices    The new number of vertices for the object
      * \param initializeNew  Whether or not to initialize the new vertices
      * \param copyOld        Whether or not to copy the old data
      */
    virtual GLS_EXPORT void ReallocateVertices( unsigned int numVertices, bool initializeNew, bool copyOld );

    /** Return the relative angle of an line constructed from the given point
      * to the _location of the object, (in the xy plane)
      * \param x X coordinate of endpoint
      * \param y Y coordinate of endpoint
      * \return Relative angle in degrees
      */
    virtual GLS_EXPORT float RelativeAngle( const float x, const float y );

    /** Gets a reference to the specified attribute for reading and writing.
      * This reference can be streamed into and out of variables.
      * For Example: someObject->Resource("Visible") >> someBool;
      *              someBool << someObject->Resource("Visible");
      */
    virtual GLS_EXPORT DistiAttributeBase& Resource( const char* name );

    /** Writes the resources (attributes) of this object to the specified stream.
      * The output of this method can be controlled by the GlsResourceFilter.
      * Note that if filter->NamesOnly() is false (the default), then only resources
      * that can return a value will appear in the list.
      *
      * \sa GlsResourceFilter
      * \sa DistiAttributeProperty
      * \param outstr The stream to write to
      * \param filter The filter to determine what to write
      */
    virtual GLS_EXPORT void GetResources( std::ostream& outstr, GlsResourceFilter* filter = NULL );

#ifndef GLES
    /** Restores the alpha test/blend settings if they were changed from default 
      * \sa SetupAlpha
      */
    GLS_EXPORT void RestoreAlpha( void );

    /** Restores the antialias settings if they were changed from default
      * \sa SetupAntiAlias
      */
    GLS_EXPORT void RestoreAntiAlias( void );

    /** Restores the lighting state 
      * \sa SetupLighting
      */
    GLS_EXPORT void RestoreLighting( void );

    /** Sets the line style settings to their defaults
      * \sa SetupLineStyle
      */
    GLS_EXPORT void RestoreLineStyle( void );
#endif

    /** \return The rotation point for the object. 
      * Lifetime is guaranteed to coincide with the DisplayObject's lifetime.
      */
    const Vertex& RotationPoint() { return _rotationPoint; }

    /** Sets the location of the rotation point for the object. Dynamic
      * rotation of the object will cause the object to be rotated around this
      * point.
      * \param  v The new rotation point
      */
    virtual GLS_EXPORT void RotationPoint( const Vertex& v );

    /** Sets the location of the rotation point for the object. Dynamic
      * rotation of the object will cause the object to be rotated around this
      * point.
      * \param x X Coordinate of the new rotation point
      * \param y Y Coordinate of the new rotation point
      * \param z Z Coordinate of the new rotation point
      */
    virtual GLS_EXPORT void RotationPoint( float x, float y, float z );

    /** Gets the location of the rotation point for the object.
      * \param v   Will be filled in with the current rotation point
      */
    virtual GLS_EXPORT void GetRotationPoint( Vertex& v );

    /** Rotates the object (around the specified axis) by the angle
      * indicated, at the object's rotation point. Recalculates the
      * vertex data.
      * \param angle  The angle to rotate by, in degrees
      * \param axis   The axis to rotate the object around.
      */
    virtual GLS_EXPORT void Rotate( float angle, int axis = Z_AXIS );

    /** Rotates the object (around the specified axis) by the angle indicated,
      * at the point specified. Recalculates the vertex data. 
      * \param origin   The point to rotate around
      * \param angle  The angle to rotate by, in degrees
      * \param axis   The axis to rotate the object around
      */
    virtual GLS_EXPORT void Rotate( const Vector& origin, float angle, int axis = Z_AXIS );

    /** Rotates the object (around the specified axis) by the angle indicated,
      * at the point specified. Recalculates the vertex data. 
      * \param orig   The point to rotate around
      * \param angle  The angle to rotate by, in degrees
      * \param axis   The arbitrary axis to rotate the object around
      */
    virtual GLS_EXPORT void Rotate( const Vector& orig, float angle, const Vector& axis );

    /** Causes the Projection, Model and View matrix for this object to be saved.  Used by the 3D 
      * picking algorithm.  Normally not used by the user.
      */
    GLS_EXPORT void SaveMatrices();

    /** 2D version of Scale for gls 2.1 compatibility.
      * This method is deprecated.
      * New code should call the 3D version of scale.
      */
    inline void Scale( int handleBar, float px, float py, Vertex* anchor = NULL )
    {
        Scale( px, py, 1.0f, anchor, handleBar );
    }

    /** Scales the object, either the handleBar, or the Anchor is
      * used to translate the object, not both.  Anchor takes 
      * presidence, if it is set HandleBar is ignored.
      * The footprint is different from the 2D scale so the compiler can destinguish the two.
      * \param px Value of the percentage of scale in x-axis
      * \param py Value of the percentage of scale in y-axis
      * \param pz Value of the percentage of scale in z-axis
      * \param anchor Anchor from which to scale object relative to
      * \param handleBar Vertex that is being dragged
      */
    virtual GLS_EXPORT void Scale( float px, float py, float pz, Vertex* anchor, int handleBar = 0 );

    /** Set attributes of the object using VarArgs style interface
      * Object attributes are defined with an enumeration.  This
      * routine is designed to make generated code very clean and readable.
      * \sa GLS_Initializers
      */
    GLS_EXPORT void Set( int spec, ... );

    /** Sets the alpha test/blend settings based on object settings
      * \sa RestoreAlpha
      */
    GLS_EXPORT bool SetupAlpha( void );

#ifndef GLES
    /** Sets the antialias settings based on object settings
      * \sa RestoreAntiAlias
      */
    GLS_EXPORT bool SetupAntiAlias( void );
#endif

    /** Sets the depth test settings based on object settings */
    GLS_EXPORT void SetupDepthTest( void );

    /** Sets the lighting state
      * \sa RestoreLighting
      */
    GLS_EXPORT void SetupLighting( void );

    /** Sets the line style settings based on object settings
      * \return True if the line style was set.  If this method returns true
      * then the object must call RestoreLineStyle to cleanup
      * \sa RestoreLineStyle
      */
    GLS_EXPORT bool SetupLineStyle( void );

#if !defined( GLES )
    /** Sets the polygon draw style based on object settings */
    GLS_EXPORT void SetupPolyDrawStyle( void );

    /** Sets the shading settings based on object settings */
    GLS_EXPORT void SetupShading( void );
#endif

    /** First half of texture setup for the object.
      * \return True if the object will be textured  False otherwise.
      *  If this method returns true, then the caller needs to do
      *  a glDisable(GL_TEXTURE_2D) afterwards to cleanup
      */
    GLS_EXPORT bool SetupTexture( void );

    /** Gets the polygon shading mode (Flat or gouraud) for the polygon
      * \return Enumeration indicating shading mode
      * \sa ShadingType_e
      */
    virtual GLS_EXPORT int Shading( void );

    /** Sets the polygon shading mode (Flat or gouraud) for the polygon
      * \param shading  Enumeration indicating shading mode
      * \sa ShadingType_e
      */
    virtual GLS_EXPORT void Shading( const int shading );

    /** Determines the static extents of the geometry projected to the XY plane of an arbirary coordinate system.
      * \param min Returns the minimum values found in the traversal
      * \param max Returns the maximum values found in the traversal
      * \param matrix Transformation matrix from logical coordinates to the coordinate system to determine the extents in. 
      * \param resetMinMax Normally not specified by user. Should be true for the initial call.  
      */
    virtual GLS_EXPORT void GetTransformedExtents( Vector& min, Vector& max, const GlsMatrixType& matrix, bool resetMinMax = true );

    /** Sets the texture coordinate data for this object
      * \param nPoints  The number of texture vertices in the object
      * \param new_tex_coord  The texture coordinates for the object
      * \param isVectorArray  true if array points to a Vector array, false if it
      *                       points to a Vertex array
      * \sa TextureCoordinates()
      * \sa VaSetTexCoords()
      * \sa SetTexCoords()
      */
    virtual GLS_EXPORT void SetTexCoords( unsigned int nPoints, Vector* new_tex_coord, bool isVectorArray = true );

    /** Vertex version of SetTexCoords 
      * \sa VaSetTexCoords()
      * \sa TextureCoordinates()
      */
    void SetTexCoords( unsigned int nPoints, Vertex* new_tex_coord )
    {
        SetTexCoords( nPoints, new_tex_coord, false );
    }

    /** Sets the texture coordinate data for this object
      * \param nPoints  The number of texture vertices in the object
      * \param ...  X,Y,Z for each vertex
      * \sa TextureCoordinates()
      * \sa GetTextureCoordinates()
      */
    GLS_EXPORT void VaSetTexCoords( unsigned int nPoints, ... );

    /** Gets the object's texture coordinates
      * \note Texture Coordinates are vertex attributes. They can be two-dimensional 
      *       (UV-coordinates) or three-dimensional (UVW-coordinates). The texture coordinates at each
      *       vertex are interpolated across the triangle generated from those vertices to determine 
      *       where to sample the texture applied to the object.
      * \note Some shaders use UVW coordinates as an input, but use them for some other purpose than texturing.
      * \return  Pointer to the object's texture coordinate array.  NULL if the object is not textured.
      * \sa GetTextureCoordinates()
      * \sa VaSetTexCoords()
      * \sa SetTexCoords()
      * \sa GetTexturePoints()
      */
    Vector* TextureCoordinates( void ) { return _texCoord; }

    /** Gets the object's texture coordinates
      * \return  Pointer to the object's texture coordinate array.  NULL if the object is not textured.
      * \sa TextureCoordinates()
      * \sa GetTexturePoints()
      */
    Vector* GetTextureCoordinates( void ) { return _texCoord; }

    /** Get the texture index for this object
      * \return The texture index for this object
      */
    virtual GLS_EXPORT int TextureIndex( void );

    /** Sets the texture index to be used when drawing the object.
      * \param textureIndex The texture index to use.
      *  -1 indicates that no texture will be drawn.
      */
    virtual GLS_EXPORT void TextureIndex( int textureIndex );

    /** Gets the object's texture points
      * \return  Pointer to the object's texture point array.
      * \note For most DisplayObjects, the Texture Points are used to compute the texture coordinates.
      *       The TexturePoints are four vertices that describe where the "corners" of the texture is in 
      *       Vertex Coordinates (i.e., the object's parent's logical coordinate space translated to
      *       the object location). The DisplayObject then uses a projection to compute the texture
      *       coordinates from these points. The most common is a Planar mapping, but a few objects 
      *       use other mappings (e.g. Spherical or Cylindrical).
      * \sa TextureCoordinates()
      * \sa GetTextureCoordinates()
      */
    virtual GLS_EXPORT Vector* GetTexturePoints( void );

    /** Gets the texturing repeat mode for this object
      * \return The texture repeat mode for this object 
      */
    virtual GLS_EXPORT bool TextureRepeat( void );

    /** Sets the texturing repeat mode for this object
      * \param rep The new texture repeat mode for this object (boolean)
      */
    virtual GLS_EXPORT void TextureRepeat( const int rep );

    /** Gets the texturing mapping mode for this object
      * \return The texture mapping mode for this object
      * \sa TextureMap_e
      */
    virtual GLS_EXPORT int TextureMappingTechnique( void );

    /** Sets the texturing mapping mode for this object
      * \param map The new texture mapping mode for this object
      * \sa TextureMap_e
      */
    virtual GLS_EXPORT void TextureMappingTechnique( const int map );

    /** Gets the texture magnification filter for this object
      * \return The texture magnification filter for this object
      * \sa TextureFilter_e
      */
    virtual GLS_EXPORT int TextureMagnificationFilter( void );

    /** Sets the texture magnification filter for this object
      * \param filter The new texture magnification filter for this object
      * \sa TextureFilter_e
      */
    virtual GLS_EXPORT void TextureMagnificationFilter( const int filter );

    /** Gets the texture minification filter for this object
      * \return The texture minification filter for this object
      * \sa TextureFilter_e
      */
    virtual GLS_EXPORT int TextureMinificationFilter( void );

    /** Sets the texture minification filter for this object
      * \param filter The new texture minification filter for this object
      * \sa TextureFilter_e
      */
    virtual GLS_EXPORT void TextureMinificationFilter( const int filter );

    /** Moves the object by the amount indicated.
      * \param tr  Float[3] array containing the x,y,z amounts to translate by
      */
    virtual GLS_EXPORT void Translate( float tr[] );

    /** Moves the object by the amount indicated.
      * \param x  X amount to translate by
      * \param y  Y amount to translate by
      * \param z  Z amount to translate by
      */
    virtual GLS_EXPORT void Translate( float x, float y, float z );

    /** Moves the object's vertices by the amount indicated.  Does not change _location.
      * \param x  X amount to translate by
      * \param y  Y amount to translate by
      * \param z  Z amount to translate by
      */
    virtual GLS_EXPORT void TranslateVertices( float x, float y, float z );

    /** Updates the bounding volume of this object 
      * This method should be called if the vertices change for picking and
      * culling to work correctly.
      * This will only update this object.  If PerformGroupCullCheck is enabled
      * for one of the objects parents, you may also need to call
      * CalculateParentBoundingBox() to update all of the objects parents.
      */
    virtual void GLS_EXPORT UpdateBoundingVolume( void );

    /** Gets the current UserData pointer.  UserData is a pointer the user can
      * use to attach user defined data to a GL Studio object.
      * \return The current UserData pointer
      */
    void* UserData( void ) const { return _userData; }

    /** Sets the current UserData pointer 
      * \param data The new UserData pointer
      */
    void UserData( void* data ) { _userData = data; }

    /** Changes the color of a vertex
      * \param vertex  1 based index of the vertex to the change color for
      * \param CurrentFillColor The new RGBA (0-255 range) color for the vertex
      */
    virtual GLS_EXPORT void SetVertexColor( unsigned int vertex, unsigned char CurrentFillColor[] );

    /** Gets the object's vertices.
      * You should call UpdateBoundingVolume after changing an objects extents.
      * \sa UpdateBoundingVolume
      * \return  Pointer to the object's vertex array
      */
    virtual GLS_EXPORT Vertex* Vertices();

    /** Sets the vertex data for this polygon
      * You should call UpdateBoundingVolume after changing an objects extents.
      * \sa UpdateBoundingVolume
      * \param nPoints  The number of vertices in the object
      * \param vertices  The vertex data for the object
      */
    virtual GLS_EXPORT void SetVertices( unsigned int nPoints, Vertex* vertices );

    /** Sets the vertex data for this object
      * You should call UpdateBoundingVolume after changing an objects extents.
      * \sa UpdateBoundingVolume
      * \param nPoints  The number of vertices in the object
      * \param ...      r,g,b,a,x,y,z for each vertex  
      */
    GLS_EXPORT void VaSetVertices( unsigned int nPoints, ... );

protected:
    /** Sets the vertex data for this object
      * You should call UpdateBoundingVolume after changing an objects extents.
      * \sa UpdateBoundingVolume
      * \param nPoints  The number of vertices in the object
      * \param args     va_list in the form r,g,b,a,x,y,z for each vertex  
      */
    virtual GLS_EXPORT void VaListSetVertices( unsigned int nPoints, va_list args );

    /** Sets the normal data for this object
      * This function is called as part of VaSetNormals( unsigned int, ... )
      * \param nPoints  The number of normals in the object
      * \param args     va_list in the form x,y,z for each normal
      */
    virtual GLS_EXPORT void VaListSetNormals( unsigned int nPoints, va_list args );

    /** Sets the texture coordinate data for this object
      * This function is called as part of VaTexCoords( unsigned int, ... )
      * \param nPoints  The number of texture coordinates in the object
      * \param args     va_list in the form x,y,z for each texture coordinate
      */
    virtual GLS_EXPORT void VaListSetTexCoords( unsigned int nPoints, va_list args );

public:
    /** \return The saved View matrix, if any. Normally not used by the user.*/
    GLS_EXPORT int* ViewMatrix();

    /** Get the visibility state this object
      * \return Whether or not this object is enabled for drawing
      */
    inline bool Visible( void ) const { return _visible; }

    /** Get the visibility state this object
      * \return Whether or not this object is enabled for drawing
      */
    inline bool Visibility( void ) const { return _visible; }

    /** Set the visiblity state for this object
      * \param vis  Whether or not enable this object for drawing
      */
    virtual GLS_EXPORT void Visibility( const bool vis );

    /** Gets the rotation point for the object in world coordinates
      * \return The rotation point for the object in world coordinates
      */
    virtual GLS_EXPORT Vector WorldRotationPoint( void );

    /** Sets the rotation point for the object in world coordinates
      * \param vert The rotation point for the object in world coordinates
      */
    virtual GLS_EXPORT void WorldRotationPoint( const Vector& vert );

    /** Gets a vertex from the object, in World coordinates (i.e. not relative to the location 
      * as is the case with the Vertices() API call).  
      * \param i  Index of the vertex to get
      * \return The vertex
      */
    virtual GLS_EXPORT Vertex WorldVertex( unsigned int i );

    /** Sets a vertex of the object, in World coordinates (i.e. not relative to the location 
      * as is the case with the Vertices() API call. ) 
      * \param i     The 0 based index of the vertex to get
      * \param vert  The new vertex value
      */
    virtual GLS_EXPORT void WorldVertex( unsigned int i, const Vertex& vert );

    /** Convert a point from logical coordinates to window coordinates 
      * \param logical The point in logical coordinates
      * \param winLoc The returned value in window coordinates. Z Ranges from 0.0 to 1.0.  0.0 is near clip, 1.0 is far clip.
      * \param alternateMatrices When supplied it is used instead of self determined matrices.
      */
    GLS_EXPORT bool LogicalToWindow( const Vector& logical,
        Vector&                                    winLoc, /* .z is 0.0 -> 1.0 */
        const OpenGLMatrices&                      alternateMatrices = OpenGLMatrices() );

    /** Convert a point in window coordinates to logical coordinates
      * \param winLoc Coordinate in window coordinates.  X and Y are in pixels. Z Ranges from 0.0 to 1.0.  0.0 is near clip, 1.0 is far clip.
      * \param logical  Coordinate in logical coordinates (returned)
      * \param directionVector  normal into the screen at the point (returned)
      * \param alternateMatrices  A Set of matrices that if supplied, will alter the point
      */
    GLS_EXPORT bool WindowToLogical(
        const Vector&         winLoc,
        Vector&               logical,                  /* returned */
        Vector*               directionVector   = NULL, /* returned if not NULL */
        const OpenGLMatrices& alternateMatrices = OpenGLMatrices() );

    /** PROJECT a point from logical coordinates to the object's DCS's XY plane
      * \param logicalPoint The original point in logical coordinates
      * \param objectLocal The returned point in the objects DCS coordinate system on the XY plane.
      * \param directionVector The direction vector to use when projecting the point.  If NULL, the point will be converted but not projected.
      * \param planeNormal
      * \param planePoint
      * \param dcsMatrix An alternate DCS matrix to convert to.
      */
    GLS_EXPORT void LogicalToDCS(
        Vector               logicalPoint,
        Vector&              objectLocal, /* returned */
        const Vector*        directionVector,
        const Vector&        planeNormal = Vector( 0, 0, 1 ), /* X/Y plane */
        const Vector&        planePoint  = Vector(),
        const GlsMatrixType* dcsMatrix   = NULL );

    /** Transform a point from the object's DCS coordinate system to the logical coordinate system.
      * \param dcsPoint The original point in dcs coordinates
      * \param logicalPoint The returned point in the objects DCS coordinate system on the XY plane.
      * \param dcsMatrix An alternate DCS matrix to convert from.
      */
    GLS_EXPORT void DCSToLogical(
        Vector               dcsPoint,
        Vector&              logicalPoint, /* returned */
        const GlsMatrixType* dcsMatrix = NULL );

#ifdef GLES
    /** Create a new DisplayObject, reading the properties in order from our GLO.
      * \param dataStream The GLO data stream we are getting our properties from.
      * \param parent The Group that will be this object's parent.
      */
    GLS_EXPORT bool Create( GlsGloFile& dataStream, Group* parent );

    void GeometryRefresh() { _geometryRefresh = true; }
#endif

protected:
#ifdef GLES
    bool _geometryRefresh; /**< Whether or not the geometry needs to be refreshed to the hardware */

    GLS_EXPORT void ApplyTextureMinMagSettings();
    GLS_EXPORT void ApplyTextureEnvModeSettings();
    GLS_EXPORT bool SetupTextureIsNeeded();

#endif

    int _alphaMode; /**< Whether or not to perform alpha testing while drawing. */

    bool _antiAlias; /**< Whether or not to perform anti-aliasing while drawing. */

    bool _attributesAdded; /**< True if SetAvailableAttributes has been called. Users should not change this. */

    bool _blinking; /**< Whether or not the blinking mode is turned on */

    float _blinkRate; /**< Number of times per second the object will blink */

    GlsColor _color; /**< The RGBA color for drawing the outline of the object. */

    bool _cullBackFace; /**< Whether or not to remove backfaces */

    GlsMatrixType _dcsMatrix; /**< The dynamic coordinate system.  The Dynamic changes to rotation, scale, and translate will 
                                      * be modified by this and applied to the _drawMatrix. */

    unsigned char _depthTest; /**< What kind of depth testing while drawing. See DepthBuffer_e*/

    GlsMatrixType* _drawMatrix; /**< The objects current contribution to the draw matrix.  
                                      * This will be multiplied by the current matrix at draw time. 
                                      * If NULL, this object has no contribution (it is not dynamic)
                                      * See CalcDrawMatrix() for more */

    bool _needCalcDrawMatrix; /** True if CalcDrawMatrix() needs to be called on this object */

    unsigned char _lineStippleMultiplier; /**< The multiplier used when applying a line stipple pattern to a line. */

    unsigned short _lineStipplePattern; /**< A bit pattern indicating which pixels in a line should be drawn and which pixels should not. */

    float _lineWidth; /**< The current width of lines rendered in the object, in logical units */

    Vertex _location; /**< The location of the origin point for this object, in the world coordinate system. */

    DynamicArray<int> _materialIndices;

    GlsMatrixType* _modelMatrix; /**< Stores the Model matrix for this object, if needed.  Used by Draw() and 3D picking. */

    Vector* _normals; /**< The array of vertex normals for this object.
                          * The size of this array is based on _nVertices */

    unsigned int _nTex_vertices; /**< The number of Texture Coordinate Vertices in this object */

    unsigned int _nVertices; /**< The number of vertices in this object */

    unsigned char _polygonEnd; /**< Whether or not this is a CLOSED or OPEN polygon */

    unsigned char _polygonMode; /**< The mode for drawing the object. */

    int _polygonOffset; /**< The depth buffer offset for this object */

    GlsMatrixType* _projMatrix; /**< Stores the Projection matrix for this object, if needed.  Used by Draw() and 3D picking. */

    unsigned char _shading; /**< The shading mode for this object */

    Vector* _texCoord; /**< The array of texture coordinates for this object.  If an object is untextured,
                          * this value is NULL.  The size of this array is based on _nTex_vertices */

    GlsColor _textureBlendColor; /**< The current texture blend color (used if TextureMapMode is TEXTURE_MAP_BLEND mode only) */

    int _textureIndex; /**< The index into the texture palette array of the texture used to
                          * to texture this object. A texture index of -1 indicates that no
                          * texture is assigned to the object. */

    unsigned char _textureMagFilter; /**< The current texturing magnification filter mode for the object */

    unsigned char _textureMinFilter; /**< The current texturing minification filter mode for the object */

    unsigned char _textureMap; /**< The current texturing map mode for the object. */

    Vector _texturePoints[ NUM_TEXTURE_POINTS ]; /**< Used to store the relative placement and rotation of a texture on
                                                  * the object.  Texture coordinates are calculated from the texture points.
                                                  * The _texturePoints are relative to the _location, which makes
                                                  * them in the objects coordinate system.
                                                  */

    unsigned char _textureRepeat; /**< The current texturing repeat mode for the object. */

    void* _userData; /**< Data pointer for the user to assign as needed */

    Vertex* _vertices; /**< The array of vertices for this object.  The vertices are in the object's
                          * coordinate system.  That is, they are relative to the _location field.
                          * This array always has a size based on _nVertices */

    int* _viewMatrix; /**< Stores the View matrix for this object, if needed.  Used by Draw() and 3D picking. */

    bool _visible; /**< Whether or not the object is enabled for drawing */

    virtual GLS_EXPORT int ColorMaterialMode( void );

    /** Allocate the model matrix, if needed */
    GLS_EXPORT void AllocateModelMatrix();

    /** Applies dynamic rotation to object, saving the matrix stack
      * so that dynamic picking can occur
      * \return True if a rotation was performed.  False otherwise.
      *  If this method returns true, then the caller needs to do
      *  a glPopMatrix to restore the stack after drawing
      */
    GLS_EXPORT bool ApplyDynamicRotation( void );

    /** Creates and recalculates the _drawMatrix
      * If _rotation, _dynamicScale, or _dynamicTranslate change you must call CalcDrawMatrix()
      * If _dcsMatrix, _location, or _rotationPoint change you need to call CalcDrawMatrixIfExists()
      * These are normally called automatically for you by the API Methods that affect those values.
      * Sub-classes may override CalcDrawMatrix() to include additional transformations in the _drawMatrix.
      */
    virtual GLS_EXPORT void CalcDrawMatrix();

    /** Recalculates the _drawMatrix if it exists.
      * See CalcDrawMatrix() for more info. */
    inline void CalcDrawMatrixIfExists()
    {
        if( _drawMatrix )
        {
            CalcDrawMatrix();
        }
    }

    /** Applies the _drawMatrix to the modelMatrix.  
      * If necessary derived classes can save other matrices.
      * \param  newMatrices  A set of matrices passed down to this object from its parent.
      */
    virtual GLS_EXPORT void CalculateMatrices( const OpenGLMatrices& newMatrices );

    /** Returns true if the point is inside the 2D extents of the given vertices
      * \param x X coordinate of pick point
      * \param y Y coordinate of pick point
      * \param nVerts Number of vertices to try
      * \param verts  Vertex array to try
      * \param tolerance  Picking tolerance
      */
    GLS_EXPORT bool InsideVertexExtents( float x, float y, unsigned int nVerts, Vertex* verts, float tolerance );

    /* Used internally to determine if the user has modified the location */
    inline void LastDrawMatrixLocation( const Vertex& loc ) { _lastDrawMatrixLocation = loc; }

    /* Used internally to determine if the user has modified the location */
    inline const Vertex& LastDrawMatrixLocation() { return _lastDrawMatrixLocation; }

    /** Set the value of _needCalculate */
    inline void NeedCalculate( bool val ) { _needCalculate = val; }

    /** Sets up the object for picking by dynamically rotating vertices
      * \param x X coordinate of pick point
      * \param y Y coordinate of pick point
      * \param z Z coordinate of pick point
      * \param vertices Vertex array to setup
      * \param vertex_cnt Number of vertices to setup
      * \param directionVector dynamic rotation vector
      */
    GLS_EXPORT void PickSetup( float x, float y, float z, Vertex* vertices, unsigned int vertex_cnt, const Vector& directionVector );

    /** Restores the temporarily rotated vertices
      * \param vertices Vertex array to restore
      * \param vertex_cnt Number of vertices to restore
      */
    GLS_EXPORT void PickCleanup( Vertex* vertices, unsigned int vertex_cnt );

#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 );
#endif

    /** Finds three coplanar points and the surface normal, if possible.  This calculation is performed using the
      * Vertices() of this object.  Used in the editor to determine how to map a texture onto an object.
      * \param p1  Returns a point on the plane
      * \param p2  Returns a point on the plane
      * \param p3  Returns a point on the plane
      * \param planeVector Returns the surface normal of the plane
      * \return  True if 3 coplanar points were found
      */
public:
    virtual GLS_EXPORT bool GetPlaneVectorPoints( Vertex& p1, Vertex& p2, Vertex& p3, Vertex& planeVector );

    /** Implements AttributeChangedNotifier::NotifyAttributeChanged.
      * Notify the class that the attribute has changed.  Observers of the attribute will have their callbacks called 
      * \param name the name of the attribute
      */
    GLS_EXPORT void NotifyAttributeChanged( const AttributeName& name ) DISTI_METHOD_OVERRIDE;

protected:
    /** Sets an attribute of this object using variable arguments
      * \param spec  A GLS_Initializer tag
      * \param args  A variable argument list
      */
    GLS_EXPORT virtual void SetValue( int spec, va_list& args );

private:
    void CopyGeometryInternal( const DisplayObject* src );
    void CopyPropertiesInternal( const DisplayObject* src );
    void CopyHierarchyPropertiesInternal( const DisplayObject* src, bool copyName );

    DistiAttribDict* _attribDict; /**< Stores all of this object's metadata attributes */

    Vector _boundingVolumeCenter; /**< Center of the bounding volume (relative to Location())*/

    float _boundingVolumeRadius; /**< Radius of the bounding sphere */

    CallbackMethodCallerBase* _callbackCaller; /**< The pointer to the callback caller for this object. 
                                                * This is currently unrelated to the InputDevice callback */

    bool _culled; /**< Whether or not this object is currently culled */

    float _dynamicTranslate[ 3 ]; /* The current (dynamic) translation of the object, in logical units and relative to the object's DCS.
                                 * _dynamicTranslate[0] = x traslation
                                 * _dynamicTranslate[1] = y traslation
                                 * _dynamicTranslate[2] = z traslation */

    float _dynamicScale[ 3 ]; /* The current (dynamic) scale of the object */

    EditorObjectBase* _editorObject; /* Used in the editor to access editor functionality */

    char* _instanceName; /**< A unique character string used to identify the object. This name
                             * will correspond to the name of the C++ member variable generated for
                             * this object in the output code. */

    Vertex _lastDrawMatrixLocation; /**< The value of _location the last time CalcDrawMatrix() was called */

    bool _lightingEnabled; /**< Stores the lighting enabled state */

    bool _needCalculate; /* true if Calculate() needs be called on this object.
                             * Defaults to true.
                             * Calculate() may still be called in some situations */

    DisplayFrame* _parent; /**< The display frame or component that contains this object */

    Group* _parentGroup; /**< The group of which this object is a member */

    unsigned char _pickable; /**< The type of picking that is enabled for this object */

    float _rotation[ 3 ]; /* The current (dynamic) rotation of the object, in degrees and relative to 
                         * the object's rotation point. Order of rotation is x, then y, then z
                         * _rotation[0] = x rotation angle
                         * _rotation[1] = y rotation angle
                         * _rotation[2] = z rotation angle */

    Vertex _rotationPoint; /* The location, in the object coordinate system, of the point to rotate
                             * this object around when the object is dynamically rotated.
                             * So when we want to rotate this object (not just rotate the view), this
                             * is the point to rotate about.  This point is relative to the _location,
                             * which makes in in the objects coordinate system. */

    GLS_EXPORT void DisplayColorMaterialModeError( const int mode );
    GLS_EXPORT int  DisplayColorMaterialModeError();

    void CommonConstructorInit( float x, float y, float z );

    /** Assignment operator not implemented. Use CloneObject() or the copy constructor instead. */
    DisplayObject& operator=( const DisplayObject& that ); // = delete

protected:
    /** Returns the local setting for _textureIndex if not -1,
      * otherwise returns the group texture index.
      */
    GLS_EXPORT int GetApplicableTextureIndex();
    /** Returns the local setting for _textureRepeat if
      * _textureIndex is not -1,
      * otherwise returns the group texture repeat setting.
      */
    GLS_EXPORT int GetApplicableTextureRepeat();

#ifdef GLES
    IGlsStateManager* _stateManager;
#endif

#ifdef GLES20
    IGlsStateManagerES20* _stateManagerES20;
#endif
};

} // namespace disti

#endif