group.h

Go to the documentation of this file.

/*! \file
  \brief  The disti::Group class.  Implements groups of objects.

  \par Copyright Information

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

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

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

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

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

*/
#ifndef INCLUDED_DISTI_GROUP_H
#define INCLUDED_DISTI_GROUP_H

#include "display.h"
#include "dynamic_array.h"
#include "gls_cpp_lang_support.h"

namespace disti
{
/**
  * The Group class.  Implements groups of objects
  */
class Group : public DisplayObject
{
public:
    DISTI_DEPRECATED( "This identifier is forbidden by the C++ standard. Use BaseClass instead." )
    typedef DisplayObject _BaseClass;
    typedef DisplayObject BaseClass;

private:
    /** If true, this object will be eligible for culling based on its static extents.
      * IMPORTANT: The cull will only be acturate within the STATIC extents of the group
      * If any child moves outside the static extents using Dynamic operations, it will
      * be over-culled.
      * The default is false, and only leaf nodes (non-groups) will cull.
      */
    bool _performGroupCullCheck;

    /** If true, cull checking will pass on to children of this group.
      * If false, children will not be culled (if this group is not culled) */
    bool _cullTestChildren;

    DisplayObject* BestPick( const Vector& winLoc, const Vector& logicalCoords, float scale, const Vector& directionVector, Vector& collisionWinLoc /*Returned*/, const OpenGLMatrices& drawnMatrices );
    DisplayObject* FirstPick( const Vector& winLoc, const Vector& logicalCoords, float scale, const Vector& directionVector, Vector& collisionWinLoc /*Returned*/, const OpenGLMatrices& drawnMatrices );

    virtual GLS_EXPORT void onVertexchanged( void );

    // GLS-8709 - There should be an attribute type that doesn't require a dummy setter and also does not write the GLS file.
    void   DummySetUnsignedInt( const unsigned int& ) {} // Used for making a read only property
    Group& operator=( const Group& ) DISTI_SPECIAL_MEM_FUN_DELETE;
    Group( const Group& that ) DISTI_SPECIAL_MEM_FUN_DELETE;

protected:
    DisplayObjectArray _objects; /** The objects contained in this group */

    /** Helper method for child classes of group that don't want to call Group::SetAvailableAttributes */
    virtual GLS_EXPORT void AddAvailableAttributes( unsigned int availableAttributes );

    /** Grow bounding box to accomodate new object
      * \param obj The new object in the group
      * \pre   obj Must already be added to the group
      */
    virtual GLS_EXPORT void GrowBoundingBox( DisplayObject* obj );

public:
    friend class GroupEditor;

#ifndef GLES
    /* See base class */
    virtual GLS_EXPORT InterfaceListType* GetCppInterfaceDescription( InterfaceListType* addToThisList = NULL ) DISTI_METHOD_OVERRIDE;

    /* See base class */
    virtual GLS_EXPORT void GetCppInterfaceDescriptionFree( InterfaceListType* array ) DISTI_METHOD_OVERRIDE;
#endif

    /** Finds a pointer to the display object in the group, using the object's
      * instance name as a key.
      * \note If there are multiple DisplayObjects within the group with the same name, 
      *       only the first instance will be found.  This can be an issue if a sub-component
      *       contains objects with the same name as the object you are searching for.
      * \param name  Instance name of the object to find
      * \return A pointer to the object if it is in the group, otherwise NULL
      */
    GLS_EXPORT DisplayObject* FindByName( const char* name );

    /** Finds a pointer to the display object in the group, using the object's
      * instance name as a key.
      * This does not desend into components, as they are different frames
      * with possibility for duplicate names as the current frame.
      * \param name  Instance name of the object to find
      * \return A pointer to the object if it is in the group, otherwise NULL
      */
    virtual GLS_EXPORT DisplayObject* FindByNameSameFrame( const char* name );

    /** Finds a pointer to the display object in the group, using the object's
      * instance name as a key.
      * \param obj  Pointer to the object to find
      * \return A pointer to the object if it is in the group, otherwise NULL
      */
    DisplayObject* FindByName( DisplayObject* obj ) { return FindByName( obj->InstanceName() ); }

    /** Finds a pointer to the DisplayObject in the group using a qualified instance name.
      * This allows precise searches for an object contained within a sub-component.
      * (e.g. "cockpit.altimeter.needle").  To find an object in the same DisplayFrame
      * use just the instance name. (e.g. "cockpit")
      * The dot denotes crossing of DisplayFrame boundaries.
      * \sa GetQualifiedInstanceName
      * \param name  Qualified instance name of the object to find
      * \returns A pointer to the object if it is in the group, otherwise NULL
      */
    GLS_EXPORT DisplayObject* FindByQualifiedName( const char* name );

    /** Finds a pointer to the display object in the group, using the object's address as a key
      * \param obj  Pointer to the object to find
      * \return A pointer to the object if it is in the group, otherwise NULL
      */
    GLS_EXPORT DisplayObject* FindNonRecursive( DisplayObject* obj );

    /** Returns a reference to the object array for this group */
    DisplayObjectArray& Objects() { return _objects; }

    /** Returns a const reference to the object array for this const group */
    const DisplayObjectArray& Objects() const { return _objects; }

    /** Returns the DisplayObject at the given group index
      * \param index The index of the object to find
      * \return A pointer to the object if it is in the group, otherwise NULL
      */
    GLS_EXPORT DisplayObject* Item( unsigned int index );

    /** Returns whether or not this group should be considered for culling */
    bool PerformGroupCullCheck( void ) const { return _performGroupCullCheck; }

    /** Sets whether or not this group should be considered for culling */
    GLS_EXPORT void PerformGroupCullCheck( bool mode );

    /** Returns whether or not this group's children should be considered for culling */
    bool CullTestChildren( void ) const { return _cullTestChildren; }

    /** Sets whether or not this group's children should be considered for culling */
    GLS_EXPORT void CullTestChildren( bool mode );

    /** \return The number of objects in this group. (Non recursive count) */
    unsigned int Count( void ) const { return _objects.Count(); }

    /** Overload of the array index operator to allow you to treat this Group as an array of objects */
    DisplayObjectPtr operator[]( unsigned int index ) { return _objects[ index ]; }

    /** Overload of the array index operator to allow you to treat this const Group as an array of const objects */
    const DisplayObject* operator[]( unsigned int index ) const { return _objects[ index ]; }

    /** \return pointer to the first element in the group, or NULL if it doesn't exist */
    GLS_EXPORT DisplayObject* FirstObject();

    /** \return pointer to the last element in the group, or NULL if it doesn't exist */
    GLS_EXPORT DisplayObject* LastObject( void );

    /** \return True if this group is empty */
    bool IsEmpty() const { return ( Count() == 0 ); }

    /** Get the index position of the specified object in the list
      * \param obj   The object to find
      * \return The index of the object in the list, -1 if it isn't in the list
      */
    GLS_EXPORT int Position( const DisplayObject* obj ) const;

    /** Construct a new group.
      * \param generateInstance  Whether or not to generate an instance name for this group
      */
    GLS_EXPORT explicit Group( int generateInstance = FALSE );

    /** Copy construct a new group, performing a "deep copy" by cloning objects in the group.
      * \param group The group to clone.
      * \param generateNames Whether or not to generate a new instance name for this group and its children.
      */
    GLS_EXPORT Group( const Group& group, bool generateNames );

    /** Sets the initial number of entries in a group 
      * \param cnt  The initial number of entries
      */
    GLS_EXPORT void InitialGroupCount( unsigned int cnt );

    static GLS_EXPORT DisplayObject* CreateInstance();

    /** Destroy a group object */
    virtual GLS_EXPORT ~Group();

    /** Actually delete all the children of the group.
      * This does a recursive "delete" on all the children.
      * This does NOT just remove them from the group.
      */
    virtual GLS_EXPORT void DeleteAllChildren();

    virtual GLS_EXPORT void SetAvailableAttributes( unsigned int value ) DISTI_METHOD_OVERRIDE;

    /* See base class */
    virtual GLS_EXPORT DisplayObject* CloneObject( bool generateNames = false ) DISTI_METHOD_OVERRIDE;

    /* See base class */
    virtual GLS_EXPORT void CopyGeometry( DisplayObject* src ) DISTI_METHOD_OVERRIDE;

    /* See base class */
    virtual GLS_EXPORT void CopyProperties( DisplayObject* src ) DISTI_METHOD_OVERRIDE;

    /* See base class */
    virtual GLS_EXPORT void Draw( void ) DISTI_METHOD_OVERRIDE;

    /* See base class */
    virtual GLS_EXPORT void PreDraw( const OpenGLMatrices& current, Culler& culler ) DISTI_METHOD_OVERRIDE;

    /* See base class */
    virtual GLS_EXPORT bool Hit( float x, float y, float z, float scale, const Vector& directionVector, Vector* collisionPoint ) DISTI_METHOD_OVERRIDE;

    /* See base class */
    virtual GLS_EXPORT DisplayObject* Pick3D( const Vector& winLoc,
        const Vector&                                       logicalCoords,
        float                                               scale,
        const Vector&                                       directionVector,
        Vector&                                             collisionWinLoc /*Returned*/,
        const OpenGLMatrices&                               drawnMatrices ) DISTI_METHOD_OVERRIDE;

    using BaseClass::Parent;

    /* See base class */
    virtual GLS_EXPORT void Parent( DisplayFrame* par ) DISTI_METHOD_OVERRIDE;

    /* See base class */
    GLS_EXPORT void SetPainter( GlsPainter* painter ) DISTI_METHOD_OVERRIDE;

    /* See base class */
    virtual GLS_EXPORT void CalculateBoundingBox( void );

    /* Unhides base class implementation. */
    using BaseClass::Location;

    /* See base class */
    virtual GLS_EXPORT void Location( const Vertex& v ) DISTI_METHOD_OVERRIDE;
    virtual GLS_EXPORT void Location( float x, float y, float z ) DISTI_METHOD_OVERRIDE;

    /* See base class */
    virtual GLS_EXPORT void Translate( float x, float y, float z ) DISTI_METHOD_OVERRIDE;

    /* See base class */
    virtual GLS_EXPORT void Translate( float transAmount[] ) DISTI_METHOD_OVERRIDE;

    /* See base class */
    virtual GLS_EXPORT void TranslateVertices( float x, float y, float z ) DISTI_METHOD_OVERRIDE;

    /* See base class */
    virtual GLS_EXPORT void TranslateVertices( float transAmount[] );

    /* See base class */
    virtual GLS_EXPORT void GetExtents( float& x, float& y, float& z, float& x1, float& y1, float& z1 ) DISTI_METHOD_OVERRIDE;

    /* See base class */
    virtual GLS_EXPORT void GetTransformedExtents( Vector& min, Vector& max, const GlsMatrixType& matrix, bool resetMinMax = true ) DISTI_METHOD_OVERRIDE;

    /* Unhides base class implementation. */
    using BaseClass::Rotate;

    /* See base class */
    virtual GLS_EXPORT void Rotate( const Vector& orig, float angle, const Vector& axis ) DISTI_METHOD_OVERRIDE;

    /* Scale in X-Y plane using the center of the group as the anchor. */
    virtual GLS_EXPORT void Scale( float scale_x, float scale_y );

    /* See base class */
    GLS_EXPORT void Scale( float scale_x, float scale_y, float scale_z, Vertex* anchor = NULL, int handle = 0 ) DISTI_METHOD_OVERRIDE;

    /** Adds the specified object into the group, at the end of the list
      * \param obj A pointer to the object to add
      * \param reparent Whether or not the object parent should be set to this group
      * \param recalculateBoundingbox Whether or not to recalculate the bounding box
      * \param loc Where to insert it (defaults to -1 which means at the end of the list)
      */
    virtual GLS_EXPORT void InsertObject( DisplayObject* obj, bool reparent = true, bool recalculateBoundingbox = true, int loc = -1 );

    /** Removes the specified object from this group. Does not delete it.
      * \param obj  The display object to removed
      * \param recalculateBoundingbox
      * \return  True if the object was found and removed from this group
      */
    virtual GLS_EXPORT bool DeleteObject( DisplayObject* obj, bool recalculateBoundingbox = true );

    /** Change the draw order of a child object within this group
      * \param oldIndex  The old index of the object
      * \param newIndex  The new index of the object
      * \pre  oldIndex and newIndex must be valid indices
      */
    virtual GLS_EXPORT void ReorderObject( unsigned int oldIndex, unsigned int newIndex );

    /** Adds the specified object into the group, at the head of the list
      * Treats the list like a stack, hence the name Push
      * \param obj A pointer to the object to add
      */
    virtual GLS_EXPORT void PushObject( DisplayObject* obj );

    /** It is not possible to modify a Group's Vertices. Overriden to disable. */
    GLS_EXPORT void DeleteVertexAt( unsigned ) DISTI_METHOD_OVERRIDE {}

    /** It is not possible to modify a Group's Vertices. Overriden to disable. */
    GLS_EXPORT void InsertVertexAt( unsigned ) DISTI_METHOD_OVERRIDE {}

    /** Copies the given vertex data into the group's location vertex
      * thereby moving the group's location member without affecting
      * its child objects.
      * \param v - Given vertex
      */
    virtual GLS_EXPORT void SetGroupLocation( const Vertex& v );

    /* See base class */
    virtual GLS_EXPORT void GetResources( std::ostream& outstr, GlsResourceFilter* filter = NULL ) DISTI_METHOD_OVERRIDE;

    /* See base class */
    virtual GLS_EXPORT void CalculateTextureCoordinates( void ) DISTI_METHOD_OVERRIDE;

    virtual GLS_EXPORT void  LineWidth( float width ) DISTI_METHOD_OVERRIDE;
    virtual GLS_EXPORT float LineWidth( void ) DISTI_METHOD_OVERRIDE;

    virtual GLS_EXPORT void LineStipplePattern( int pattern ) DISTI_METHOD_OVERRIDE;
    virtual GLS_EXPORT int  LineStipplePattern( void ) DISTI_METHOD_OVERRIDE;

    virtual GLS_EXPORT void LineStippleMultiplier( int mult ) DISTI_METHOD_OVERRIDE;
    virtual GLS_EXPORT int  LineStippleMultiplier( void ) DISTI_METHOD_OVERRIDE;

    virtual GLS_EXPORT int  PolygonMode( void ) DISTI_METHOD_OVERRIDE;
    virtual GLS_EXPORT void PolygonMode( int mode ) DISTI_METHOD_OVERRIDE;

    virtual GLS_EXPORT void PolygonEnd( const int mode ) DISTI_METHOD_OVERRIDE;
    virtual GLS_EXPORT int  PolygonEnd( void ) DISTI_METHOD_OVERRIDE;

    virtual GLS_EXPORT void Shading( const int mode ) DISTI_METHOD_OVERRIDE;
    virtual GLS_EXPORT int  Shading( void ) DISTI_METHOD_OVERRIDE;

    virtual GLS_EXPORT void DepthTest( unsigned char mode ) DISTI_METHOD_OVERRIDE;
    virtual GLS_EXPORT int  DepthTest( void ) DISTI_METHOD_OVERRIDE;

    virtual GLS_EXPORT void AntiAlias( bool mode ) DISTI_METHOD_OVERRIDE;
    virtual GLS_EXPORT bool AntiAlias( void ) DISTI_METHOD_OVERRIDE;

    virtual GLS_EXPORT void AlphaMode( int mode ) DISTI_METHOD_OVERRIDE;
    virtual GLS_EXPORT int  AlphaMode( void ) DISTI_METHOD_OVERRIDE;

    virtual GLS_EXPORT void CullBackFace( const bool mode ) DISTI_METHOD_OVERRIDE;
    virtual GLS_EXPORT bool CullBackFace( void ) DISTI_METHOD_OVERRIDE;

    virtual GLS_EXPORT bool LightingEnabled() DISTI_METHOD_OVERRIDE;
    virtual GLS_EXPORT void LightingEnabled( bool lighting ) DISTI_METHOD_OVERRIDE;

    /* Unhides base class implementation. */
    using BaseClass::SetBlendColor;

    virtual GLS_EXPORT void SetBlendColor( const GlsColor& color ) DISTI_METHOD_OVERRIDE;

    /* Unhides base class implementation. */
    using BaseClass::GetBlendColor;

    virtual GLS_EXPORT GlsColor GetBlendColor( void ) DISTI_METHOD_OVERRIDE;

    /* Unhides base class implementation. */
    using BaseClass::SetColor;

    virtual GLS_EXPORT void SetColor( const GlsColor& color ) DISTI_METHOD_OVERRIDE;

    /* Unhides base class implementation. */
    using BaseClass::GetColor;

    virtual GLS_EXPORT GlsColor GetColor( void ) DISTI_METHOD_OVERRIDE;

    /* Unhides base class implementation. */
    using BaseClass::SetFillColor;

    virtual GLS_EXPORT void SetFillColor( const GlsColor& color ) DISTI_METHOD_OVERRIDE;

    /* Unhides base class implementation. */
    using BaseClass::GetFillColor;

    virtual GLS_EXPORT GlsColor GetFillColor( void ) DISTI_METHOD_OVERRIDE;

    virtual GLS_EXPORT void TextureRepeat( const int rep ) DISTI_METHOD_OVERRIDE;
    using BaseClass::TextureRepeat;

    virtual GLS_EXPORT void TextureMappingTechnique( const int map ) DISTI_METHOD_OVERRIDE;
    virtual GLS_EXPORT int  TextureMappingTechnique( void ) DISTI_METHOD_OVERRIDE;

    virtual GLS_EXPORT void TextureMinificationFilter( const int filter ) DISTI_METHOD_OVERRIDE;
    virtual GLS_EXPORT int  TextureMinificationFilter( void ) DISTI_METHOD_OVERRIDE;

    virtual GLS_EXPORT void TextureMagnificationFilter( const int filter ) DISTI_METHOD_OVERRIDE;
    virtual GLS_EXPORT int  TextureMagnificationFilter( void ) DISTI_METHOD_OVERRIDE;

    /** Call the Calculate method for all children
      * \param time  The current time 
      */
    virtual GLS_EXPORT void Calculate( double time ) DISTI_METHOD_OVERRIDE;

    /** The following class is provided for GL Studio 2.1 backward compatibility.  
      * This interface is deprecated and should only be used to support legacy code.
      */
    class CompatabilityListItem
    {
    protected:
        unsigned int _index;
        Group*       _parentGroup;

    public:
        GLS_EXPORT CompatabilityListItem();

        GLS_EXPORT CompatabilityListItem* Next();

        GLS_EXPORT CompatabilityListItem* Prev();

        GLS_EXPORT DisplayObject* DataPtr();

        static GLS_EXPORT void RecalcCompatabilityList( Group* whichGroup );
    };

    /** \return The first object in this group
      */
    GLS_EXPORT CompatabilityListItem* First();

    /** \return The last object in this group
      */
    GLS_EXPORT CompatabilityListItem* Last();

    DynamicArray<CompatabilityListItem> _compatList; /** Use for 2.1 compatibility only */

private:
    /** Sets the texturing repeat mode for this object without affecting
      * the settings of its children.
      * \param rep The new texture repeat mode for this object (boolean)
      */
    virtual GLS_EXPORT void SetGroupTextureRepeat( const int mode );
};

/// Overload begin() so that range-for loops and other constructs work with Group
inline DisplayObjectPtr* begin( Group& group )
{
    return begin( group.Objects() );
}

/// Overload begin() so that range-for loops and other constructs work with Group
inline const DisplayObjectPtr* begin( const Group& group )
{
    return begin( group.Objects() );
}

/// Overload begin() so that range-for loops and other constructs work with Group
inline DisplayObjectPtr* end( Group& group )
{
    return end( group.Objects() );
}

/// Overload begin() so that range-for loops and other constructs work with Group
inline const DisplayObjectPtr* end( const Group& group )
{
    return end( group.Objects() );
}

} // namespace disti

#endif