component_base.h

Go to the documentation of this file.

/*! \file
  \brief  The disti::ComponentBase class.
 
  \par Copyright Information
 
  Copyright (c) 2017 by The DiSTI Corporation.<br>
  11301 Corporate Blvd; Suite 100<br>
  Orlando, Florida 32817<br>
  USA<br>
  <br>
  All rights reserved.<br>
 
  This Software contains proprietary trade secrets of DiSTI and may not be
reproduced, in whole or part, in any form, or by any means of electronic,
mechanical, or otherwise, without the written permission of DiSTI.  Said
permission may be derived through the purchase of applicable DiSTI product
licenses which detail the distribution rights of this content and any
Derivative Works based on this or other copyrighted DiSTI Software.
 
  NO WARRANTY. THE SOFTWARE IS PROVIDED "AS-IS," WITHOUT WARRANTY OF ANY KIND,
AND ANY USE OF THIS SOFTWARE PRODUCT IS AT YOUR OWN RISK. TO THE MAXIMUM EXTENT
PERMITTED BY APPLICABLE LAW, DISTI AND ITS SUPPLIERS DISCLAIM ALL WARRANTIES
AND CONDITIONS, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY AND/OR FITNESS FOR A
PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT, WITH REGARD TO THE SOFTWARE.
 
  LIMITATION OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW,
IN NO EVENT SHALL DISTI OR ITS SUPPLIERS BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION,
DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS
INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR
INABILITY TO USE THE SOFTWARE, EVEN IF DISTI HAS BEEN ADVISED OF THE POSSIBILITY
OF SUCH DAMAGES.  DISTI'S ENTIRE LIABILITY AND YOUR EXCLUSIVE REMEDY SHALL NOT
EXCEED FIVE DOLLARS (US$5.00).
 
  The aforementioned terms and restrictions are governed by the laws of the
State of Florida and the United States of America.
 
*/
#ifndef _COMPONENT_BASE_H
#define _COMPONENT_BASE_H
 
#include "display_frame.h"
#include "gls_include.h"
#include "gls_version.h"
#include "group.h"
 
namespace disti
{
class LiveComponentAccessor;
 
/** Sets the default value for absolute placement. If not set, the default will be true.
  * Typically only used for backwards compatibility with previous versions of GL Studio
  * \param value true if the absolute placement default should be true, false otherwise.
  */
GLS_EXPORT void SetAbsolutePlacementDefault( bool value );
 
/// \return The default value for absolute placement.
GLS_EXPORT bool GetAbsolutePlacementDefault();
 
/** The ComponentBase class is derived from Group and DisplayFrame.
  It is capable of containing objects as well as drawing them.
  It is used for encapsulating object geometry and behavior.
  The behavior is defined when this object is derived.
  */
class ComponentBase : public Group
    , public DisplayFrame
{
public:
    DISTI_DEPRECATED( "This identifier is forbidden by the C++ standard. Use BaseClass instead." )
    typedef Group _BaseClass; ///< Deprecated typedef for the base class.
    typedef Group BaseClass;  ///< Typedef for the base class.
    friend class disti::LiveComponentAccessor;
 
    /** Constructor
      * \param generateInstance If true generates a new unique instance name 
      */
    GLS_EXPORT ComponentBase( int generateInstance = FALSE );
 
    /** Cleans up the object and destructs it.
      * Don't call "delete yourComponent", instead call yourComponent->Destroy().
      * If this is an RSO, it will be completely destroyed, including the DLL.
      */
    virtual GLS_EXPORT ~ComponentBase();
 
    /** Create RSO static
      * This will load the specified DLL and try to create the specified class.
      * It will return the ComponentBase* on success, and NULL on failure.
      * Internally, this uses a LiveComponentAccessor.  If more control is needed,
      * it is recommended to create a LiveComponentAccessor.
      * \param fileName The name of the DLL
      * \param className The class name to create.  If NULL, the default class will be created.
      * \param performCreate If true, CreateObjects() will be called, otherwise it will not.
      * \param callingVersion 
      * \return NULL on failure.*/
    static GLS_EXPORT ComponentBase* CreateLiveComponent( const char* fileName = NULL, const char* className = NULL, bool performCreate = true, const GlsBuiltVersionInfo& callingVersion = GlsBuiltVersionInfo() );
 
    /** Returns true if version checks ok, false if there MIGHT be a problem.
      * The consequences of version mismatches depend on the methods that will be
      * called on the object.  This will emit warnings to stdout.
      * \param comp RSO
      * \param callingVersion Leave this as the default and it will use the calling function's version information.
      * \return true If version is considered OK.
      */
    static GLS_EXPORT bool CheckLiveVersion( ComponentBase* comp, const GlsBuiltVersionInfo& callingVersion = GlsBuiltVersionInfo() );
 
    /// Creates a new component of the templated type
    /// \param availableAttributes The value to call SetAvailableAttributes() with.
    /// \return A pointer to the newly created component instance.
    template<class T>
    static T* CreateComponent( DisplayObject::AvailableAttributesEnum availableAttributes = DisplayObject::GLS_ATTRIBUTES_ALL )
    {
        T* comp = new T();
        comp->SetAvailableAttributes( availableAttributes );
        comp->CreateObjects();
        return comp;
    }
 
    virtual GLS_EXPORT void SetAvailableAttributes( unsigned int value ) DISTI_METHOD_OVERRIDE;
 
    /// \return The value for Absolute Placement.
    /// If true, the component will be left in the generated location.
    /// Otherwise it will be moved based on its extents.
    bool AbsolutePlacement() const { return _absolutePlacement; }
 
    /// Sets the value for absolute placement.
    /// \param val The new value for absolute placement.
    /// \see AbsolutePlacement
    virtual GLS_EXPORT void ChangedAbsolutePlacement( bool val );
 
    /// Sets the value for Absolute Placement. This affects what happens during the call to CreateObjects().
    /// \param val If true, the component will be left in the generated location, otherwise it will be moved based on its extents.
    virtual GLS_EXPORT void AbsolutePlacement( bool val );
 
    virtual GLS_EXPORT void CalculateBoundingBox() DISTI_METHOD_OVERRIDE;
 
    /** Call this before deleting objects which may be being kept
      * by the drag or focus objects. */
    virtual GLS_EXPORT void ClearDragAndFocus() DISTI_METHOD_OVERRIDE;
 
    virtual GLS_EXPORT DisplayObject* CloneObject( bool generateNames = false ) DISTI_METHOD_OVERRIDE;
 
    /* Copies the geometry information from one object to another. 
      * In a ComponentBase, this does nothing.
      * \param src   The object to copy geometry from.
      */
    virtual GLS_EXPORT void CopyGeometry( DisplayObject* src ) DISTI_METHOD_OVERRIDE;
 
    virtual GLS_EXPORT void CopyProperties( DisplayObject* src ) DISTI_METHOD_OVERRIDE;
 
#ifndef GLES
 
    virtual GLS_EXPORT InterfaceListType* GetCppInterfaceDescription( InterfaceListType* addToThisList = NULL ) DISTI_METHOD_OVERRIDE;
    virtual GLS_EXPORT void               GetCppInterfaceDescriptionFree( InterfaceListType* array ) DISTI_METHOD_OVERRIDE;
#endif
 
    /** In derived classes this creates all the geometry for the component */
    virtual GLS_EXPORT void CreateObjects();
 
    /** Overriden to avoid children getting deleted until object deletion. */
    virtual GLS_EXPORT void DeleteAllChildren() DISTI_METHOD_OVERRIDE;
 
    /** Draws this object and all its contained objects in the current OpenGL pipeline.
        This can be overloaded to perform any special effects.
        If PreDraw and Draw are needed, call DisplayFrame::Draw() */
    virtual GLS_EXPORT void Draw() DISTI_METHOD_OVERRIDE;
 
    /** Finds a pointer to the display object in the group, using the object's
    * instance name as a key.
    * Because this is a component, it will always return NULL.
    * \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 ) DISTI_METHOD_OVERRIDE;
 
    /* Figure out the min and max x&y extents for the object.
      * Modify results by _scale
      * \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 ) DISTI_METHOD_OVERRIDE;
 
    /** Determines the extents of 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 world coordinates to the desired coordinate system. 
      * \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 ) DISTI_METHOD_OVERRIDE;
 
    /** Handles input events.  
      * It traverses the hierarchy with Pick3D.  
      * Then THE picked object is given the handle() call.
      * \param ev The event data.
      * \returns The object that handled the input.
      */
    virtual GLS_EXPORT DisplayObject* HandleInput( DisplayEvent* ev );
 
    /** Peforms post creation tasks including reparenting all objects.
      * and adjusting their position.
      * It checks the value of _absolutePlacement to determine if movement of the
      * generated objects is necessary 
      * /see AbsolutePlacement
      */
    virtual GLS_EXPORT void Init();
 
    /** The GL Studio code generator allways derives a new Initialize method for the user 
        This is called after all the objects are created.
    */
    virtual GLS_EXPORT void Initialize();
 
    /// If this component was loaded from an RSO library,
    /// this method returns the object's library reference.
    /// The library reference should be deleted AFTER the component is deleted.
    /// If the component was not loaded from an RSO library,
    /// this method returns NULL.
    /// \return A pointer to component's library reference, if it was loaded from an RSO, else NULL.
    LiveComponentAccessor* LiveAccessor() { return _liveAccessor; }
 
    using Group::Location;
    virtual GLS_EXPORT const Vertex& Location() const DISTI_METHOD_OVERRIDE { return Group::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;
 
    /* Unhides base class implementation. */
    // force inheritance
    using Group::Parent;
 
    /** Sets the DisplayFrame for this object.
      * It does not set the specified parent for all the children.
      * Instead, it sets all the children's parent to 'this'.  And
      * saves the argument 'par' in _parentDisplayFrame.  This
      * allows special traversals, which traverse out of the ComponentBase
      * to the ComponentBase's parent.
      * \param par The parent which will be saved in _parentDisplayFrame 
      * \see ParentDisplayFrame
      */
    virtual GLS_EXPORT void Parent( DisplayFrame* par ) DISTI_METHOD_OVERRIDE;
 
    /** Gets the value of the DisplayFrame containing this component 
      * \return the value of the DisplayFrame containing this component. 
      * Returns NULL if there is no parent DisplayFrame 
      */
    inline DisplayFrame* ParentDisplayFrame() const { return _parentDisplayFrame; }
 
    /** Sets the parent DisplayFrame for this object.  This is normally only set by a
      * call to Parent().
      * \param val The new val for _parentDisplayFrame
      * \see ComponentBase::Parent()
      */
    inline void ParentDisplayFrame( DisplayFrame* val ) { _parentDisplayFrame = val; }
 
    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;
 
    virtual GLS_EXPORT void PreDraw( const OpenGLMatrices& current, Culler& culler ) DISTI_METHOD_OVERRIDE;
    virtual GLS_EXPORT void GetResources( std::ostream& outstr, GlsResourceFilter* filter = NULL ) DISTI_METHOD_OVERRIDE;
    virtual GLS_EXPORT DistiAttributeBase& Resource( const char* name ) DISTI_METHOD_OVERRIDE;
 
    using Group::Rotate;
    using Group::Scale;
 
    virtual GLS_EXPORT void Rotate( const Vector& orig, float angle, const Vector& axis ) DISTI_METHOD_OVERRIDE;
    virtual GLS_EXPORT void Scale( float px, float py, float pz, Vertex* parentAnchor, int handleBar = 0 ) DISTI_METHOD_OVERRIDE;
 
    /** This will call our parent display frame's SetRedraw() causing
        this component to be redrawn in the future.
      */
    virtual GLS_EXPORT void SetRedraw() DISTI_METHOD_OVERRIDE;
 
    virtual GLS_EXPORT void Translate( float tr[] ) DISTI_METHOD_OVERRIDE;
    virtual GLS_EXPORT void Translate( float x, float y, float z ) DISTI_METHOD_OVERRIDE;
 
    /** If UseParentsLighting is true, the component will add 
     *  its lights to those already set by its parent.
     *  If false, the component will only use its own lights.
     */
    virtual GLS_EXPORT void UseParentsLighting( const bool& );
 
    /// If UseParentsLighting is true, the component will add
    /// its lights to those already set by its parent.
    /// If false, the component will only use its own lights.
    /// \return The current use parent's lighting value.
    virtual GLS_EXPORT bool UseParentsLighting();
 
    /// Overridden so we will always get -1 for our texture index.
    /// This keeps our children from trying to draw with our texture
    /// index which would be for the wrong palette.
    /// \return -1
    virtual GLS_EXPORT int  TextureIndex() DISTI_METHOD_OVERRIDE;
    virtual GLS_EXPORT void TextureIndex( int index ) DISTI_METHOD_OVERRIDE
    {
        BaseClass::TextureIndex( index );
    }
 
    GLS_EXPORT void SetValue( int spec, va_list& args ) DISTI_METHOD_OVERRIDE;
 
    /// \see DisplayFrame
    /// \return the parents input handler if a parent exists, else returns this component's input handler
    virtual GLS_EXPORT InputHandler* GetInputHandler() DISTI_METHOD_OVERRIDE;
 
    GLS_EXPORT void NotifyAttributeChanged( const AttributeName& name ) DISTI_METHOD_OVERRIDE;
 
protected:
    LiveComponentAccessor* _liveAccessor;           /**< /see ComponentBase::LiveAccessor */
    bool                   _absolutePlacement;      /**< /see ComponentBase::AbsolutePlacement */
    Vertex                 _absolutePlacementDelta; ///< The delta vector used when using relative placement.
    DisplayFrame*          _parentDisplayFrame;     /**< /see ComponentBase::ParentDisplayFrame */
    GlsMatrixType          _editorTransformMatrix;  /**< The static transformation from the internal component coordinates to the parent's coordinate system */
 
    /** Overridden from base class 
      * This adds the _editorTransformMatrix to the DCS.  You will need to call CalcDrawMatrix whenever the _editorTransformMatrix changes.*/
    virtual GLS_EXPORT void CalcDrawMatrix() DISTI_METHOD_OVERRIDE;
 
    /* Overridden from base class */
    virtual GLS_EXPORT void CalculateMatrices( const OpenGLMatrices& newMatrices ) DISTI_METHOD_OVERRIDE;
 
    /// EditorTransformMatrix is an extra transformation added in addition to the DCS matrix.
    /// This is used for scaling, rotation, and placement of component instances in the editor and at runtime.
    /// \param matrix The new transform matrix value to use.
    GLS_EXPORT void EditorTransformMatrix( const GlsMatrixType& matrix );
 
    /// \return A const reference to the the current editor transform matrix.
    GLS_EXPORT const GlsMatrixType& EditorTransformMatrix() const;
 
#ifdef GLES
    /** Set a single attribute from the GLO file.
     * \param data The attribute to set and its associated data.
     */
    virtual GLS_EXPORT void SetFromGloData( GlsGloFileAttribute& data ) DISTI_METHOD_OVERRIDE;
#endif
 
private:
    DisplayObject* PickFirst( const Vector& winLoc, const Vector& logicalCoords, float scale, const Vector& directionVector, Vector& collisionWinLoc /*Returned*/, const OpenGLMatrices& drawnMatrices );
    DisplayObject* PickBest( const Vector& winLoc, const Vector& logicalCoords, float scale, const Vector& directionVector, Vector& collisionWinLoc /*Returned*/, const OpenGLMatrices& drawnMatrices );
};
 
/// \return The directory of the shared library that calls this function.
/// \param module The pointer to the shared library in question.
#ifdef WIN32
GLS_EXPORT std::string GetComponentDirectory( HINSTANCE module );
#else
GLS_EXPORT std::string GetComponentDirectory( void* module );
#endif
} // namespace disti
 
#endif