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; ///< Deprecated typedef for the base class.
    typedef DisplayObject BaseClass;  ///< Typedef for the base class.
 
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();
 
    // 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.
    /// \param availableAttributes Bit field for attribute types to create.
    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
    virtual GLS_EXPORT InterfaceListType* GetCppInterfaceDescription( InterfaceListType* addToThisList = NULL ) DISTI_METHOD_OVERRIDE;
    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 );
 
    /// \return A reference to the object array for this group.
    DisplayObjectArray& Objects() { return _objects; }
 
    /// \return 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 );
 
    /// \return Whether or not this group should be considered for culling.
    bool PerformGroupCullCheck() const { return _performGroupCullCheck; }
 
    /// Sets whether or not this group should be considered for culling.
    /// \param mode The new cull mode for the group.
    GLS_EXPORT void PerformGroupCullCheck( bool mode );
 
    /// \return Whether or not this group's children should be considered for culling.
    bool CullTestChildren() const { return _cullTestChildren; }
 
    /// Sets whether or not this group's children should be considered for culling.
    /// \param mode The new cull mode to set.
    GLS_EXPORT void CullTestChildren( bool mode );
 
    /** \return The number of objects in this group. (Non recursive count) */
    unsigned int Count() const { return _objects.Count(); }
 
    /// Overload of the array index operator to allow you to treat this Group as an array of objects.
    /// \param index The object index to be returned.
    /// \return A pointer to the requested object.
    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.
    /// \param index The object index to be returned.
    /// \return A pointer to the requested object.
    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();
 
    /** \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 );
 
    /// \return A pointer to a new Group object.
    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;
 
    virtual GLS_EXPORT DisplayObject* CloneObject( bool generateNames = false ) DISTI_METHOD_OVERRIDE;
    virtual GLS_EXPORT void           CopyGeometry( DisplayObject* src ) DISTI_METHOD_OVERRIDE;
    virtual GLS_EXPORT void           CopyProperties( DisplayObject* src ) DISTI_METHOD_OVERRIDE;
    virtual GLS_EXPORT void           Draw() DISTI_METHOD_OVERRIDE;
    virtual GLS_EXPORT void           PreDraw( const OpenGLMatrices& current, Culler& culler ) DISTI_METHOD_OVERRIDE;
    virtual GLS_EXPORT bool           Hit( float x, float y, float z, float scale, const Vector& directionVector, Vector* collisionPoint ) DISTI_METHOD_OVERRIDE;
 
    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;
    virtual GLS_EXPORT void Parent( DisplayFrame* par ) DISTI_METHOD_OVERRIDE;
 
    GLS_EXPORT void SetPainter( GlsPainter* painter ) DISTI_METHOD_OVERRIDE;
 
    /// Recalculates the 3D bounding volume of the object, setting the Group's vertices.
    /// Affects the results of GetExtents().
    /// This should be called when a Group's children are modified.
    virtual GLS_EXPORT void CalculateBoundingBox();
 
    /* Unhides base class implementation. */
    using BaseClass::Location;
    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;
    virtual GLS_EXPORT void Translate( float x, float y, float z ) DISTI_METHOD_OVERRIDE;
    virtual GLS_EXPORT void Translate( float transAmount[] ) DISTI_METHOD_OVERRIDE;
    virtual GLS_EXPORT void TranslateVertices( float x, float y, float z ) DISTI_METHOD_OVERRIDE;
 
    /// Translates the group by the specified amount my changing the
    /// vertices instead of changing the _location value, moving all subobjects.
    /// \param transAmount A pointer to an array of floats representing X, Y, and Z to translate.
    virtual GLS_EXPORT void TranslateVertices( float transAmount[] );
 
    virtual GLS_EXPORT void GetExtents( float& x, float& y, float& z, float& x1, float& y1, float& z1 ) DISTI_METHOD_OVERRIDE;
    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;
    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.
    /// \param scale_x The X factor to scale by.
    /// \param scale_y The Y factor to scale by.
    virtual GLS_EXPORT void Scale( float scale_x, float scale_y );
    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 );
 
    virtual GLS_EXPORT void GetResources( std::ostream& outstr, GlsResourceFilter* filter = NULL ) DISTI_METHOD_OVERRIDE;
 
    virtual GLS_EXPORT void CalculateTextureCoordinates() DISTI_METHOD_OVERRIDE;
 
    virtual GLS_EXPORT void  LineWidth( float width ) DISTI_METHOD_OVERRIDE;
    virtual GLS_EXPORT float LineWidth() DISTI_METHOD_OVERRIDE;
 
    virtual GLS_EXPORT void LineStipplePattern( int pattern ) DISTI_METHOD_OVERRIDE;
    virtual GLS_EXPORT int  LineStipplePattern() DISTI_METHOD_OVERRIDE;
 
    virtual GLS_EXPORT void LineStippleMultiplier( int mult ) DISTI_METHOD_OVERRIDE;
    virtual GLS_EXPORT int  LineStippleMultiplier() DISTI_METHOD_OVERRIDE;
 
    virtual GLS_EXPORT int  PolygonMode() 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() DISTI_METHOD_OVERRIDE;
 
    virtual GLS_EXPORT void Shading( const int mode ) DISTI_METHOD_OVERRIDE;
    virtual GLS_EXPORT int  Shading() DISTI_METHOD_OVERRIDE;
 
    virtual GLS_EXPORT void DepthTest( unsigned char mode ) DISTI_METHOD_OVERRIDE;
    virtual GLS_EXPORT int  DepthTest() DISTI_METHOD_OVERRIDE;
 
    virtual GLS_EXPORT void AntiAlias( bool mode ) DISTI_METHOD_OVERRIDE;
    virtual GLS_EXPORT bool AntiAlias() DISTI_METHOD_OVERRIDE;
 
    virtual GLS_EXPORT void AlphaMode( int mode ) DISTI_METHOD_OVERRIDE;
    virtual GLS_EXPORT int  AlphaMode() DISTI_METHOD_OVERRIDE;
 
    virtual GLS_EXPORT void CullBackFace( const bool mode ) DISTI_METHOD_OVERRIDE;
    virtual GLS_EXPORT bool CullBackFace() 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() 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() 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() 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() DISTI_METHOD_OVERRIDE;
 
    virtual GLS_EXPORT void TextureMinificationFilter( const int filter ) DISTI_METHOD_OVERRIDE;
    virtual GLS_EXPORT int  TextureMinificationFilter() DISTI_METHOD_OVERRIDE;
 
    virtual GLS_EXPORT void TextureMagnificationFilter( const int filter ) DISTI_METHOD_OVERRIDE;
    virtual GLS_EXPORT int  TextureMagnificationFilter() 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;       ///< The underlying index of this child object.
        Group*       _parentGroup; ///< This group's parent group.
 
    public:
        GLS_EXPORT CompatabilityListItem();
 
        /// \return A pointer to the next item in the list.
        GLS_EXPORT CompatabilityListItem* Next();
 
        /// \return A pointer to the previous item in the list.
        GLS_EXPORT CompatabilityListItem* Prev();
 
        /// \return The underlying object for this list item.
        GLS_EXPORT DisplayObject* DataPtr();
 
        /// Configure the list for the specified Group.
        /// \param whichGroup The Group whose compatibility list is to be configured.
        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; ///< Used for GL Studio 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.
/// \param group The group whose first element is to be returned.
/// \return A pointer to the first element.
inline DisplayObjectPtr* begin( Group& group )
{
    return begin( group.Objects() );
}
 
/// Overload begin() so that range-for loops and other constructs work with Group.
/// \param group The group whose first element is to be returned.
/// \return A pointer to the first element.
inline const DisplayObjectPtr* begin( const Group& group )
{
    return begin( group.Objects() );
}
 
/// Overload end() so that range-for loops and other constructs work with Group.
/// \param group The group whose last element is to be returned.
/// \return A pointer to the last element.
inline DisplayObjectPtr* end( Group& group )
{
    return end( group.Objects() );
}
 
/// Overload end() so that range-for loops and other constructs work with Group.
/// \param group The group whose last element is to be returned.
/// \return A pointer to the last element.
inline const DisplayObjectPtr* end( const Group& group )
{
    return end( group.Objects() );
}
 
} // namespace disti
 
#endif