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 placent.  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 );

/** Gets the default value for absolute placent. 
  */
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;
    typedef Group BaseClass;
    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  
      */
    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;

    /** Gets 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; }

    virtual GLS_EXPORT void ChangedAbsolutePlacement( bool val );

    /** Sets the value for Absolute Placement.  This affects what happens
      * durring the call to CreateObjects().  
      * 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 );

    /* See base class */
    virtual GLS_EXPORT void CalculateBoundingBox( void ) 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;

    /* See base class */
    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;

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

#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

    /** 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.
      */
    LiveComponentAccessor* LiveAccessor() { return _liveAccessor; }

    using Group::Location;
    virtual GLS_EXPORT const Vertex& Location( void ) const DISTI_METHOD_OVERRIDE { return Group::Location(); }

    /* See base class */
    virtual GLS_EXPORT void Location( const Vertex& v ) DISTI_METHOD_OVERRIDE;

    /* See base class */
    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; }

    /* 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;

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

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

    /* See base class */
    virtual GLS_EXPORT DistiAttributeBase& Resource( const char* name ) DISTI_METHOD_OVERRIDE;

    /* Unhides base class implementation. */
    using Group::Rotate;
    using Group::Scale;

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

    /* See base class */
    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( void ) DISTI_METHOD_OVERRIDE;

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

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

    /** If UseParentsLighting is true, the component will add 
     *  it's lights to those already set by it's parent.
     *  If false, the component will only use it's own lights.
     */
    virtual GLS_EXPORT void UseParentsLighting( const bool& );

    /** If UseParentsLighting is true, the component will add 
     *  it's lights to those already set by it's parent.
     *  If false, the component will only use it's own lights.
     */
    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. 
      */
    virtual GLS_EXPORT int  TextureIndex() DISTI_METHOD_OVERRIDE;
    virtual GLS_EXPORT void TextureIndex( int index ) DISTI_METHOD_OVERRIDE
    {
        BaseClass::TextureIndex( index );
    }

    /* See base class */
    GLS_EXPORT void SetValue( int spec, va_list& args ) DISTI_METHOD_OVERRIDE;

    /** \see DisplayFrame 
      * Returns the parents input handler if a parent exists, else returns this component's input handler 
      */
    virtual GLS_EXPORT InputHandler* GetInputHandler() DISTI_METHOD_OVERRIDE;

    /** overrides DisplayObject::NotifyAttributeChanged */
    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 placemnt */
    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;
    GLS_EXPORT void         EditorTransformMatrix( const GlsMatrixType& 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 );
};

typedef ComponentBase* ( *ComponentBaseCreateFunc )();
/** Returns the directory of the .dll or .so that calls this function. */
#ifdef WIN32
GLS_EXPORT std::string GetComponentDirectory( HINSTANCE module );
#else
GLS_EXPORT std::string GetComponentDirectory( void* module );
#endif
} // namespace disti

#endif