rso_interface_1.h

Go to the documentation of this file.

/*! \file
  \brief  Defines the RSO interface, which provides a generic way of accessing RSOs and other content, disti::RSOInterface1.

  \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 _RSO_INTERFACE_1_H
#define _RSO_INTERFACE_1_H

// !!! NOTICE !!!
// To maintain compatibility with existing RSOs this header cannot be changed.

namespace disti
{
////////////////////////////////////////////////////////////////////////////////
// In order for the RSO to be discovered in a .DLL or .so file,
// The following "C" funtions need to be defined.
// They are only comments here.
////////////////////////////////////////////////////////////////////////////////
// RSOInterface1* GetRSOInterface1_ClassNameHere()
// Optionally:
// const char* GlsDefaultClassName()
////////////////////////////////////////////////////////////////////////////////

/** The RSOInterface1 class defines an abstract interface to an RSO instance. 
  */
class RSOInterface1
{
public:
    ////////////////////////////////////////////////////////////////////////////////
    // Forward declaration of support classes
    ////////////////////////////////////////////////////////////////////////////////
    class Vector;
    class MatrixD;
    class OpenGLMatrices;
    class PlaneClass;
    class Culler;
    class Event;
    class LocationEvent;
    class MouseEvent;
    class KeyboardEvent;
    class ObjectEvent;
    class EmittedEventHandler;
    class ResourceFilter;

public:
    ////////////////////////////////////////////////////////////////////////////////
    /// The RSO Interface methods
    ////////////////////////////////////////////////////////////////////////////////

    ////////////////////////////////////////////////////////////////////////////////
    /// Perform component simulation.
    /// Any non-drawing activities can be performed here.
    /// Call this before PreDraw()
    ////////////////////////////////////////////////////////////////////////////////
    virtual void Calculate( double time ) = 0;

    ////////////////////////////////////////////////////////////////////////////////
    /// Calculate transformations and perform culling
    /// Call this before Draw()
    ////////////////////////////////////////////////////////////////////////////////
    virtual void PreDraw( const OpenGLMatrices& current, Culler& culler ) = 0;

    ////////////////////////////////////////////////////////////////////////////////
    /// Draw the object via OpenGL
    /// Call this after PreDraw()
    ////////////////////////////////////////////////////////////////////////////////
    virtual void Draw() = 0;

    ////////////////////////////////////////////////////////////////////////////////
    /// Set the string value for a given named resource
    ////////////////////////////////////////////////////////////////////////////////
    virtual void SetResource( const char* resourceName, const char* resourceVal ) = 0;

    ////////////////////////////////////////////////////////////////////////////////
    /// Get the string value for the given resource
    ////////////////////////////////////////////////////////////////////////////////
    virtual const char* GetResource( const char* resourceName ) = 0;

    ////////////////////////////////////////////////////////////////////////////////
    /// Get a list of the resources for the component.
    /// Each resource is separated by a newline ('\n') with the output controlled by filter.
    /// filter may be NULL in which case the default values are used.
    ////////////////////////////////////////////////////////////////////////////////
    virtual const char* GetResources( ResourceFilter* filter = 0 ) = 0;

    ////////////////////////////////////////////////////////////////////////////////
    /// Allow the object to handle an event
    /// Returns true if the event was handled by the component
    ////////////////////////////////////////////////////////////////////////////////
    virtual bool HandleInput( Event* ev ) = 0;

    ////////////////////////////////////////////////////////////////////////////////
    /// Allow for handling events from inside the object.
    /// The emitted event handler will be passed events that are from inside the component
    /// \param handler pointer to the EmittedEventHandler object to use or NULL to remove the current event handler.
    /// \return true if this component may emit events, false if this component will never emit events.
    ////////////////////////////////////////////////////////////////////////////////
    virtual bool SetEmittedEventHandler( EmittedEventHandler* handler ) = 0;

    ////////////////////////////////////////////////////////////////////////////////
    /// Pick3D returns true if the RSO was picked.
    ////////////////////////////////////////////////////////////////////////////////
    virtual bool Pick3D( const Vector& winLoc,
        const Vector&                  logicalCoords,
        float                          scale,
        const Vector&                  directionVector,
        Vector&                        collisionWinLoc,
        const OpenGLMatrices&          drawnMatrices )
        = 0;

    ////////////////////////////////////////////////////////////////////////////////
    /// Get the bounding sphere for the component in the components coordinate system
    /// \param center If the method returns true, contains the center point of the sphere. If the method returns false, value is undefined.
    /// \param radius If the method returns true, contains the radius of the sphere. If the method returns false, value is undefined.
    /// \returns true if the bounding sphere was returned, false if the bounding sphere is not available.
    ////////////////////////////////////////////////////////////////////////////////
    virtual bool GetBoundingSphere( Vector* center, float* radius ) = 0;

    ////////////////////////////////////////////////////////////////////////////////
    /// Get the extents of the component when drawn with the given transformation matrix, as a coordinate system-aligned box
    /// \param min If the method returns true, contains the point corresponding with the 1st corner of the box.  If the method returns false, value is undefined.
    /// \param max If the method returns true, contains the point corresponding with the 2nd corner of the box.  If the method returns false, value is undefined.
    /// \param transform Transformation matrix from A to B where A is the component's coordinate system and B is the coordinate system to compute the bounding box in. (If NULL then identity matrix is assumed)
    /// \returns true if the extents were calculated, false if the extents could not be calculated.
    ////////////////////////////////////////////////////////////////////////////////
    virtual bool GetBoundingBox( Vector* min, Vector* max, const MatrixD* transform = 0 ) = 0;

    ////////////////////////////////////////////////////////////////////////////////
    /// Returns a new instance of the RSO
    /// that is a clone of this object or NULL if not possible.
    ////////////////////////////////////////////////////////////////////////////////
    virtual RSOInterface1* CloneObject() = 0;

    ////////////////////////////////////////////////////////////////////////////////
    /// Safely delete the object.
    ////////////////////////////////////////////////////////////////////////////////
    virtual void DeleteInstance() = 0;

protected:
    ////////////////////////////////////////////////////////////////////////////////
    /// Protected destructor so it can't be deleted directly.
    ////////////////////////////////////////////////////////////////////////////////
    virtual ~RSOInterface1() {}

public:
    ////////////////////////////////////////////////////////////////////////////////
    // Supporting classes
    ////////////////////////////////////////////////////////////////////////////////

    /** Vector */
    class Vector
    {
    public:
        float _x, _y, _z;

        Vector()
            : _x( 0 )
            , _y( 0 )
            , _z( 0 )
        {}

        inline void Set( float x, float y, float z )
        {
            _x = x;
            _y = y;
            _z = z;
        }

        inline float X() { return _x; }
        inline float Y() { return _y; }
        inline float Z() { return _z; }
    };

    /** MatrixD contains the data for a 4x4 matrix */
    class MatrixD
    {
    public:
        /// raw column-major matrix data
        double _data[ 4 * 4 ];

        /// Uninitialized data
        MatrixD()
        {}

        /// Copy from data
        MatrixD( double* data )
        {
            _data[ 0 ]  = data[ 0 ];
            _data[ 1 ]  = data[ 1 ];
            _data[ 2 ]  = data[ 2 ];
            _data[ 3 ]  = data[ 3 ];
            _data[ 4 ]  = data[ 4 ];
            _data[ 5 ]  = data[ 5 ];
            _data[ 6 ]  = data[ 6 ];
            _data[ 7 ]  = data[ 7 ];
            _data[ 8 ]  = data[ 8 ];
            _data[ 9 ]  = data[ 9 ];
            _data[ 10 ] = data[ 10 ];
            _data[ 11 ] = data[ 11 ];
            _data[ 12 ] = data[ 12 ];
            _data[ 13 ] = data[ 13 ];
            _data[ 14 ] = data[ 14 ];
            _data[ 15 ] = data[ 15 ];
        }
    };

    /** OpenGLMatrices is used to pass the current OpenGL matrices to PreDraw */
    class OpenGLMatrices
    {
    public:
        int*     _viewPort; /**< pointer to array size 4 */
        MatrixD* _projMatrix;
        MatrixD* _modelMatrix;

        OpenGLMatrices()
            : _viewPort( 0 )
            , _projMatrix( 0 )
            , _modelMatrix( 0 )
        {}

        OpenGLMatrices( int* viewPort, MatrixD* projMatrix, MatrixD* modelMatrix )
            : _viewPort( viewPort )
            , _projMatrix( projMatrix )
            , _modelMatrix( modelMatrix )
        {}
    };

    /** The PlaneClass is used to define the clipping planes for culling */
    class PlaneClass
    {
    public:
        //@{
        float _a, _b, _c, _d; /**< Coefficients to describe a 3D plane:  aX + bY + cZ + d = 0 */
        //@}

        PlaneClass()
            : _a( 0 )
            , _b( 0 )
            , _c( 0 )
            , _d( 0 )
        {}

        inline void Set( float a, float b, float c, float d )
        {
            _a = a;
            _b = b;
            _c = c;
            _d = d;
        }

        inline float A() { return _a; }
        inline float B() { return _b; }
        inline float C() { return _c; }
        inline float D() { return _d; }
    };

    /** Defines culling parameters for PreDraw */
    class Culler
    {
    public:
        bool       _enabled;     /**< Whether or not culling is enabled */
        PlaneClass _planes[ 6 ]; /**< Array of six clipping planes to define the frustum */

        Culler()
            : _enabled( false )
        {}
    };

    /** Base class for events */
    class Event
    {
    public:
        /** Event Type Enum */
        typedef enum
        {
            EVENT_MOUSE = 0,  /**< A Mouse (or touch screen) event */
            EVENT_KEYBOARD,   /**< A Keyboard event */
            EVENT_TIMER,      /**< Unused */
            EVENT_OBJECT,     /**< An event emitted by an object */
            EVENT_KEYBOARD_UP /**< A Keyboard up event (uses KeyboardEvent class) */
        } EventTypeEnum;

        /** Event Subtype Enum */
        typedef enum
        {
            MOUSE_DOWN = 0,    /**< A Mouse button was pushed down */
            MOUSE_UP,          /**< A Mouse button was released */
            MOUSE_MOVE,        /**< The mouse moved */
            MOUSE_DRAG,        /**< The mouse moved while a button was held down */
            MOUSE_LEAVE,       /**< The mouse exited the object */
            MOUSE_ENTER,       /**< The mouse entered the object */
            MOUSE_WHEEL_MINUS, /**< The mouse wheel was turned in the negative direction */
            MOUSE_WHEEL_PLUS   /**< The mouse wheel was turned in the positive direction */
        } EventSubtypeEnum;

        unsigned short _eventType;    /**< Major event code. see EventTypeEnum */
        unsigned short _eventSubtype; /**< Minor event code. see EventSubtypeEnum */

        /**
            Special Key State
        */
        typedef enum
        {
            NONE_STATE        = 0,
            SHIFT_STATE       = 0x00010000,
            CAPS_LOCK_STATE   = 0x00020000,
            CTRL_STATE        = 0x00040000,
            ALT_STATE         = 0x00080000,
            NUM_LOCK_STATE    = 0x00100000,
            META_STATE        = 0x00400000,
            SCROLL_LOCK_STATE = 0x00800000,
            BUTTON1_STATE     = 0x01000000,
            BUTTON2_STATE     = 0x02000000,
            BUTTON3_STATE     = 0x04000000
        } SpecialKeyState;

        Event()
            : _eventType( 0 )
            , // Derived classes MUST set the appropriate event type
            _eventSubtype( MOUSE_DOWN )
        {}

        virtual ~Event() {}

        inline unsigned short EventType() { return _eventType; }
        inline void           EventType( unsigned short value ) { _eventType = value; }

        inline unsigned short EventSubType() { return _eventSubtype; }
        inline void           EventSubType( unsigned short value ) { _eventSubtype = value; }
    };

    /** An event associated with a specific location in the application window.
      * Base class for MouseEvent and KeyboardEvent.
      */
    class LocationEvent : public Event
    {
    public:
        Vector _winLoc; /**< Location of the event in window coordinates
                                * x and y window coordinates in pixels.  
                                * z is from 0.0 -> 1.0 and represents the depth.  
                                * z == 0 is at the near cliping plane.
                                * z == 0.5 represents half way between near
                                * and far cliping planes. 
                                */
        LocationEvent()
        {}

        inline Vector WinLoc() { return _winLoc; }
        inline void   WinLoc( Vector value ) { _winLoc = value; }
    };

    /** An event containing mouse input. */
    class MouseEvent : public LocationEvent
    {
    public:
        /** Mouse Button Type */
        typedef enum
        {
            MOUSE_LBUTTON    = 1, /**< Mask that matches only left mouse button */
            MOUSE_MBUTTON    = 2, /**< Mask that matches only middle mouse button */
            MOUSE_RBUTTON    = 4, /**< Mask that matches only right mouse button */
            MOUSE_BUTTON_ANY = 7  /**< Mask that matches any mouse button */
        } MouseButtonType;

        unsigned char _buttonMask; /**< bitfield: which button was pressed for this event ( MouseButtonType )*/
        unsigned char _clicks;     /**< # of times a button was pressed */
        int           _modifiers;  /**< bitfield: which buttons or modifiers were depressed before event ( \sa SpecialKeyState) */

        MouseEvent()
            : _buttonMask( 0 )
            , _clicks( 0 )
            , _modifiers( NONE_STATE )
        {
            _eventType = EVENT_MOUSE;
        }

        inline unsigned char ButtonMask() { return _buttonMask; }
        inline void          ButtonMask( unsigned char value ) { _buttonMask = value; }

        inline unsigned char Clicks() { return _clicks; }
        inline void          Clicks( unsigned char value ) { _clicks = value; }

        inline int  Modifiers() { return _modifiers; }
        inline void Modifiers( int value ) { _modifiers = value; }
    };

    /** An event containing keyboard input */
    class KeyboardEvent : public LocationEvent
    {
    public:
        /// Keyboard key enum used by keysym (use ascii letters for all other keys):
        enum
        {
            KEY_Button      = 0xfee8,
            KEY_BackSpace   = 0xff08,
            KEY_Tab         = 0xff09,
            KEY_Enter       = 0xff0d,
            KEY_Pause       = 0xff13,
            KEY_Scroll_Lock = 0xff14,
            KEY_Escape      = 0xff1b,
            KEY_Home        = 0xff50,
            KEY_Left        = 0xff51,
            KEY_Up          = 0xff52,
            KEY_Right       = 0xff53,
            KEY_Down        = 0xff54,
            KEY_Page_Up     = 0xff55,
            KEY_Page_Down   = 0xff56,
            KEY_End         = 0xff57,
            KEY_Print       = 0xff61,
            KEY_Insert      = 0xff63,
            KEY_Menu        = 0xff67,
            KEY_Num_Lock    = 0xff7f,
            KEY_KP          = 0xff80,
            KEY_KP_Enter    = 0xff8d,
            KEY_KP_Last     = 0xffbd,
            KEY_F           = 0xffbd,
            KEY_F_Last      = 0xffe0,
            KEY_Shift_L     = 0xffe1,
            KEY_Shift_R     = 0xffe2,
            KEY_Control_L   = 0xffe3,
            KEY_Control_R   = 0xffe4,
            KEY_Caps_Lock   = 0xffe5,
            KEY_Meta_L      = 0xffe7,
            KEY_Meta_R      = 0xffe8,
            KEY_Alt_L       = 0xffe9,
            KEY_Alt_R       = 0xffea,
            KEY_Delete      = 0xffff
        } KeySymCodeEnum;

        int _keysym;    /**< Code for key that was pressed \sa KeySymCodeEnum */
        int _modifiers; /**< bitfield: which modifiers or buttons were pressed \sa SpecialKeyState */

        KeyboardEvent()
            : _keysym( 0 )
            , _modifiers( 0 )
        {
            _eventType = EVENT_KEYBOARD;
        }

        inline int  KeySym() { return _keysym; }
        inline void KeySym( int value ) { _keysym = value; }

        inline int  Modifiers() { return _modifiers; }
        inline void Modifiers( int value ) { _modifiers = value; }
    };

    /** An event that is emitted from a simulation object */
    class ObjectEvent : public Event
    {
    public:
        char* _initiator; /**< The qualified name of the object that initiated the event */
        char* _eventName; /**< String event name */
        char* _eventData; /**< Any additional data for this event.  A NULL terminated string */

        ObjectEvent()
            : _initiator( 0 )
            , _eventName( 0 )
            , _eventData( 0 )
        {
            _eventType = EVENT_OBJECT;
        }

        virtual ~ObjectEvent()
        {
            if( _initiator )
            {
                delete _initiator;
                _initiator = 0;
            }
            if( _eventName )
            {
                delete _eventName;
                _eventName = 0;
            }
            if( _eventData )
            {
                delete _eventData;
                _eventData = 0;
            }
        }

        /// Get the initiator name
        inline const char* Initiator() const
        {
            return _initiator;
        }
        /// Set the initiator name
        virtual void Initiator( const char* value )
        {
            if( _initiator )
            {
                delete[] _initiator;
                _initiator = 0;
            }
            if( value )
            {
                _initiator = new char[ RSOInterface1::strlen( value ) + 1 ];
                RSOInterface1::strcpy( _initiator, value );
            }
        }

        /// Get the event name
        inline const char* EventName() const
        {
            return _eventName;
        }
        /// Set the event name
        virtual void EventName( const char* value )
        {
            if( _eventName )
            {
                delete[] _eventName;
                _eventName = 0;
            }
            if( value )
            {
                _eventName = new char[ RSOInterface1::strlen( value ) + 1 ];
                RSOInterface1::strcpy( _eventName, value );
            }
        }

        /// Get the event data
        inline const char* EventData() const
        {
            return _eventData;
        }
        /// Set the event data
        virtual void EventData( const char* value )
        {
            if( _eventData )
            {
                delete[] _eventData;
                _eventData = 0;
            }
            if( value )
            {
                _eventData = new char[ RSOInterface1::strlen( value ) + 1 ];
                RSOInterface1::strcpy( _eventData, value );
            }
        }
    };

    /** The emitted event handler is an object provided by the 
        container to handle events emitted from the component.
    */
    class EmittedEventHandler
    {
    protected:
        virtual ~EmittedEventHandler() {}

    public:
        /// Called by the component to pass an event
        /// to the container.  Most containers will only handle
        /// ObjectEvents.
        /// \returns int Reserved. Currently always -1.
        virtual int HandleEvent( Event* ev ) = 0;
    };

    /** The resource filter is a parameter to the GetResources method */
    class ResourceFilter
    {
    protected:
        virtual ~ResourceFilter() {}

    public:
        /// How many levels of qualification to show in the name.
        /// -1 means full qualification.
        /// Default: 0  // TODO: confirm this default
        virtual int  LevelsUp() const      = 0;
        virtual void LevelsUp( int value ) = 0;

        /// How many levels of children to show.
        ///  0 means don't show any children properties
        /// -1 means all the way down.
        /// Default: -1
        virtual int  GroupLevelsDown() const      = 0;
        virtual void GroupLevelsDown( int value ) = 0;

        /// If true, only a list of names will be returned.
        /// Values will not be returned.
        /// The format changes to not include the ":".
        /// Default: false
        virtual bool NamesOnly() const       = 0;
        virtual void NamesOnly( bool value ) = 0;

        /// Manage the list of excluded attributes
        virtual void AddExclude( const char* str ) = 0;
        /// Returns the number of entries in the exclude list.
        /// Default: 0
        virtual int ExcludeCount() const = 0;
        /// Returns NULL if index >= ExcludeCount() or index < -1
        virtual const char* GetExclude( int index ) const = 0;

        /// Manage the list of included attributes
        virtual void AddInclude( const char* str ) = 0;
        /// Returns the number of entries in the include list.
        /// Default: 0
        virtual int IncludeCount() const = 0;
        // Returns NULL if index >= IncludeCount() or index < -1
        virtual const char* GetInclude( int index ) const = 0;

        /// Check a name against the filters
        /// Exclude list takes precedence
        virtual bool PassFilter( const char* name ) const = 0;
    };

    ////////////////////////////////////////////////////////////////////////////////
    // Support class utility methods
    ////////////////////////////////////////////////////////////////////////////////

    static inline unsigned int strlen( const char* str )
    {
        unsigned int i = 0;
        while( str[ i ] != '\0' )
        {
            i++;
        }
        return i;
    }

    static inline char* strcpy( char* dest, const char* src )
    {
        unsigned int i = 0;
        while( ( dest[ i ] = src[ i ] ) != '\0' )
        {
            i++;
        }
        return dest;
    }
};

} // end namespace disti

#endif