gls_rso_loader.h

Go to the documentation of this file.

/*! \file gls_rso_loader.h
\brief  The main class for loading an RSO.

\par Copyright Information

    Copyright (c) 2013 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 GLS_RSO_LOADER_H_INCLUDED
#define GLS_RSO_LOADER_H_INCLUDED

#include "rso_interface_4.h"

#include <string>
#include <vector>

/** \brief Namespace for loading RSOs. */
namespace GlsRSOLoader
{
class LiveComponentLibRef;

/** RSOReference class. Main interface for GlsRSOLoader */
class RSOReference
{
    disti::RSOInterface1* _rso;
    unsigned int          _rsoVersion;
    LiveComponentLibRef*  _liveComponentLibRef;

    RSOReference( const RSOReference& );
    RSOReference& operator=( const RSOReference& );

public:
    /** Constructor */
    RSOReference( disti::RSOInterface1*, LiveComponentLibRef*, unsigned int );

    /** Destructor */
    ~RSOReference();

    /** Accessor for RSOInterface contained within this RSO Reference
        * \return Pointer to RSOInterface instance
        */
    inline disti::RSOInterface1* GetRSOInterface1() { return _rso; }

    /** Gets the version number for the RSO
        *  \return The RSO version number
        */
    inline unsigned int GetRSOVersion() { return _rsoVersion; }

    /** Sets a resource contained within the RSO
        * \param resourceName  Resource name
        * \param resourceVal  Resource value
        */
    inline void SetResource( const char* resourceName, const char* resourceVal ) { _rso->SetResource( resourceName, resourceVal ); }

    /** CRT Insensitive version of SetResources()
        * Parse a buffer of resource value pairs.
        * \param buf String containing resource data
        */
    void SetResources( const char* buf );

    /** Gets a resource value by name
        * \param resourceName Resource name
        * \return Value of given resource
        */
    inline const char* GetResource( const char* resourceName ) { return _rso->GetResource( resourceName ); }

    /** Calculate method. Should be called every frame for normal operation.
        * \param time  Elapsed time, in seconds
        */
    inline void Calculate( double time ) { _rso->Calculate( time ); }

    /** Calculate transformations and perform culling. Call this before Draw()
        * \param current  Transformation matrices (Projection and Modelview) to apply
        * \param culler  Culler operation to apply on this RSO
        */
    inline void PreDraw( const disti::RSOInterface1::OpenGLMatrices& current, disti::RSOInterface1::Culler& culler ) { _rso->PreDraw( current, culler ); }

    /** Draw the object via OpenGL. Call this after PreDraw() */
    inline void Draw() { _rso->Draw(); }

    /** Allow the object to handle an event.
        * \param ev Event to be handled by the RSO
        * \return true if the event was handled by the RSO
        */
    inline bool HandleInput( disti::RSOInterface1::Event* ev ) { return _rso->HandleInput( ev ); }

    /** 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.
        */
    inline bool SetEmittedEventHandler( disti::RSOInterface1::EmittedEventHandler* handler ) { return _rso->SetEmittedEventHandler( handler ); }

    /** Sets the "AbsolutePlacement" property on the RSO
        * \param value true to enable AbsolutePlacement property, false to disable it
        */
    void AbsolutePlacement( bool value );

    /** Gets the background color of the RSO's display frame
        * \param r Red color component (0-255)
        * \param g Green color component (0-255)
        * \param b Blue color component (0-255)
        * \param a Alpha color component (0-255)
        */
    void GetBackgroundColor( unsigned char& r, unsigned char& g, unsigned char& b, unsigned char& a );

    /** Get the extents of the RSO 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)
        * \return true if the extents were calculated, false if the extents could not be calculated.
        */
    bool GetBoundingBox( disti::RSOInterface1::Vector* min, disti::RSOInterface1::Vector* max, disti::RSOInterface1::MatrixD* transform = 0 );

    /** Sets the projection of the RSO using glOrtho or gluSetPerspective. Sets the application's projection globally.
        * \param controlWidth Width of the RSO (in pixels)
        * \param controlHeight Height of the RSO (in pixels)
        * \param depthFactor depth factor of the projection
        * \param fov field of view (in degrees)
        * \param perspective Whether the projection is perspective or orthographic
        */
    void SetProjection( int controlWidth, int controlHeight, float depthFactor = 4.0f, float fov = 90.0f, bool perspective = false );

    /** Mouse button down event handler
        * \param x X screen coordinate of mouse cursor's current location
        * \param y Y screen coordinate of mouse cursor's current location
        * \param button Mouse button pressed (see RSOInterface1::MouseEvent::MouseButtonType)
        * \return true if event handled successfully, false otherwise
        */
    bool HandleMouseDown( int x, int y, int button );

    /** Mouse button up event handler
        * \param x X screen coordinate of mouse cursor's current location
        * \param y Y screen coordinate of mouse cursor's current location
        * \param button Mouse button released (see RSOInterface1::MouseEvent::MouseButtonType)
        */
    bool HandleMouseUp( int x, int y, int button );

    /** Mouse wheel plus event handler
        * \param x X screen coordinate of mouse cursor's current location
        * \param y Y screen coordinate of mouse cursor's current location
        * \param buttonMask bitfield of which mouse buttons are currently held down (see RSOInterface1::MouseEvent::MouseButtonType)
        * \return true if event handled successfully, false otherwise
        */
    bool HandleMouseWheelPlus( int x, int y, int buttonMask );

    /** Mouse wheel minus event handler
        * \param x X screen coordinate of mouse cursor's current location
        * \param y Y screen coordinate of mouse cursor's current location
        * \param buttonMask bitfield of which mouse buttons are currently held down (see RSOInterface1::MouseEvent::MouseButtonType)
        * \return true if event handled successfully, false otherwise
        */
    bool HandleMouseWheelMinus( int x, int y, int buttonMask );

    /** Mouse button up event handler
        * \param x X screen coordinate of mouse cursor's current location
        * \param y Y screen coordinate of mouse cursor's current location
        * \param buttonMask bitfield of which mouse buttons are currently held down (see RSOInterface1::MouseEvent::MouseButtonType)
        * \return true if event handled successfully, false otherwise
        */
    bool HandleMouseMove( int x, int y, int buttonMask );

    /** Keyboard key down event handler
        * \param key Key code pressed. Either ascii value or RSOInterface1::KeyboardEvent::KeySymCodeEnum (for any non-ascii key).
        * \param x X screen coordinate of mouse cursor's current location
        * \param y Y screen coordinate of mouse cursor's current location
        * \return true if event handled successfully, false otherwise
        */
    bool HandleKeyDown( int key, int x, int y );

    /** Keyboard key up event handler
        * \param key Key code released. Either ascii value or RSOInterface1::KeyboardEvent::KeySymCodeEnum (for any non-ascii key).
        * \param x X screen coordinate of mouse cursor's current location
        * \param y Y screen coordinate of mouse cursor's current location
        * \return true if event handled successfully, false otherwise
        */
    bool HandleKeyUp( int key, int x, int y );

    // Additions for RSO version 2

    /** Constructs a resource handle for rapid access to the named resource (RSO v2)
        *  \param resourceName         resource name
        *  \param[out] resourceHandle  reference to resource handle output location
        *  \return                     true if successful
        */
    bool CreateResourceHandle( const char* resourceName, disti::RSOInterface2::ResourceHandle& resourceHandle );

    /** Frees the given resource handle (RSO v2)
        *  \param resourceHandle  resource handle
        *  \return                true if successful
        */
    bool ReleaseResourceHandle( disti::RSOInterface2::ResourceHandle resourceHandle );

    /** Checks the given resource handle for validity (RSO v2)
        *  \param resourceHandle  resource handle
        *  \return                true if the given resource handle is connected to a valid resource
        */
    bool IsResourceHandleValid( disti::RSOInterface2::ResourceHandle resourceHandle );

    /** Sets a string resource by handle (RSO v2)
        *  \param resourceHandle  resource handle
        *  \param resourceVal     resource value
        *  \return                true if successful
        */
    bool SetResource( disti::RSOInterface2::ResourceHandle resourceHandle, const char* resourceVal );

    /** Gets a string resource by handle (RSO v2)
        *  \param resourceHandle      resource handle
        *  \param[out] resourceValue  reference to resource value output location
        *  \return                    true if successful
        */
    bool GetResource( disti::RSOInterface2::ResourceHandle resourceHandle, const char*& resourceValue );

    /** Sets an integer resource by name (RSO v2)
        *  \param resourceName  resource name
        *  \param resourceVal   resource value
        *  \return              true if successful
        */
    bool SetIntResource( const char* resourceName, long resourceVal );
    /** Sets an integer resource by handle (RSO v2)
        *  \param resourceHandle  resource handle
        *  \param resourceVal     resource value
        *  \return                true if successful
        */
    bool SetIntResource( disti::RSOInterface2::ResourceHandle resourceHandle, long resourceVal );

    /** Gets an integer resource by name (RSO v2)
        *  \param resourceName      resource name
        *  \param[out] resourceVal  reference to resource value output location
        *  \return                  true if successful
        */
    bool GetIntResource( const char* resourceName, long& resourceVal );
    /** Gets an integer resource by handle (RSO v2)
        *  \param resourceHandle      resource handle
        *  \param[out] resourceVal    reference to resource value output location
        *  \return                    true if successful
        */
    bool GetIntResource( disti::RSOInterface2::ResourceHandle resourceHandle, long& resourceVal );

    /** Sets a float resource by name (RSO v2)
        *  \param resourceName  resource name
        *  \param resourceVal   resource value
        *  \return              true if successful
        */
    bool SetFloatResource( const char* resourceName, double resourceVal );
    /** Sets a float resource by handle (RSO v2)
        *  \param resourceHandle  resource handle
        *  \param resourceVal     resource value
        *  \return                true if successful
        */
    bool SetFloatResource( disti::RSOInterface2::ResourceHandle resourceHandle, double resourceVal );

    /** Gets a float resource by name (RSO v2)
        *  \param resourceName      resource name
        *  \param[out] resourceVal  reference to resource value output location
        *  \return                  true if successful
        */
    bool GetFloatResource( const char* resourceName, double& resourceVal );
    /** Gets a float resource by handle (RSO v2)
        *  \param resourceHandle      resource name
        *  \param[out] resourceVal    reference to resource value output location
        *  \return                    true if successful
        */
    bool GetFloatResource( disti::RSOInterface2::ResourceHandle resourceHandle, double& resourceVal );

    /** Register a resource observer to be notified when a resource changes *
        * \param resourceHandle the resource handle
        * \param obs the observer to be notified
        * \param[out] id the id used to unregister the observer
        * \return true if successful
        */
    bool RegisterResourceObserver( disti::RSOInterface2::ResourceHandle resourceHandle, disti::RSOInterface4::ResourceObserver* obs, disti::RSOInterface4::CallbackID& id );

    /** Unregister a resource observer
        * \param resourceHandle the resource handle
        * \param id the id used to register the resource observer
        * \return true if successful
        */
    bool UnregisterResourceObserver( disti::RSOInterface2::ResourceHandle resourceHandle, disti::RSOInterface4::CallbackID id );
};

/** Create RSO static
    * This will load the specified DLL and try to create the specified class.
    * It will return the RSO1Reference* on success, and NULL on failure.
    * \param fileName The name of the DLL
    * \param className The class name to create.  If NULL, the default class will be created.
    * \param absolutePlacement Initial value of AbsolutePlacement
    * \return NULL on failure.*/
RSOReference* LoadRSO( const char* fileName, const char* className = 0, bool absolutePlacement = true );

/** Delete an RSO reference */
void DestroyRSO( RSOReference* );

/** Sets up the OpenGL Pipeline to the state expected by RSO drawing.
    * \param pushState Whether or not to save values. If true, this will call
    *                 glPushClientAttrib(GL_CLIENT_ALL_ATTRIB_BITS) and glPushAttrib(GL_ALL_ATTRIB_BITS). You should call
    *                 RestoreOpenGLState() after drawing to pop the attributes.
    */
void SetOpenGLDefaultState( bool pushState );

/** Call this after calling SetOpenGLDefaultState with saveVal == true.
    * DO NOT call this after calling SetOpenGLDefaultState with saveVal == false
    * because this will pop the attribute stack.
    */
void RestoreOpenGLState();

/** OpenGLMatrices is used to pass the current OpenGL matrices to PreDraw */
class OpenGLMatrices : public disti::RSOInterface1::OpenGLMatrices
{
protected:
    bool _needsDelete;

public:
    /** Constructor */
    OpenGLMatrices();
    /** Destructor */
    ~OpenGLMatrices();

    /** Retrieves the current OpenGL Matrices from the
        * OpenGL Subsystem */
    void GetCurrent();
};

/** Defines culling parameters (ie- clipping planes for frustum culling) for PreDraw */
class Culler : public disti::RSOInterface1::Culler
{
public:
    /** Culler constructor
        * \param enabled  Whether or not to actually do the culling test
        */
    Culler( bool enabled = true );

    /** Reads the current OpenGL projection matrices and determines the six frustum planes.
        * \param currentMatrices Transformation matrices to apply to culling planes
        */
    void ExtractFrustum( disti::RSOInterface1::OpenGLMatrices& currentMatrices );
};

/** Used for specifiying a filter for accessing resources
    */
class GlsResourceFilter : public disti::RSOInterface1::ResourceFilter
{
public:
    int                      _levelsUp;
    int                      _groupLevelsDown;
    std::vector<std::string> _excludeList;
    std::vector<std::string> _includeList;
    bool                     _namesOnly;

public:
    GlsResourceFilter();
    /// Copy constructor
    GlsResourceFilter( GlsResourceFilter& source );

    virtual ~GlsResourceFilter();

    /** How many levels of qualification above the starting point to show in the attribute names.
        * This is based on the component heirarchy, not the draw hierarchy.
        * For example if you call Altimeter->GetResources() with:
        *  LevelsUp = 0, expect:
        *    Altitude: 1000
        *  LevelsUp = 1, expect:
        *    Altimeter.Altitude:
        *  LevelsUp = 2, expect:
        *    Cockpit.Altimeter.Altitude:
        * -1 means full qualification.
        */
    inline int  LevelsUp() const { return _levelsUp; }
    inline void LevelsUp( int value ) { _levelsUp = value; }

    /** How many levels of children to show.
        * This is different from LevelsUp because this is based on the draw
        * heirarchy (Groups rather than components).
        * For example with:
        *  GroupLevelsDown = 0, only the specified object's resources will be shown.
        *  GroupLevelsDown = 1, only the immeadiate children of the object's resources will be shown.
        *  GroupLevelsDown = -1, means all children will be shown.
        * Note that the name stays fully qualified for the children.  For example:
        * if GroupLevelsDown == 1 the results would include:
        *    Altimeter.Visible: 1
        *    Altimeter.Group1.Visible: 1
        * but NOT:
        *    Altimeter.Group1.Poly.Visible: 1
        */
    inline int  GroupLevelsDown() const { return _groupLevelsDown; }
    inline void GroupLevelsDown( int value ) { _groupLevelsDown = value; }

    /** If true, only a list of names will be returned.
        * Values will not be returned.
        * The format changes to not include the ":".
        */
    inline bool NamesOnly() const { return _namesOnly; }
    inline void NamesOnly( bool value ) { _namesOnly = value; }

    /** Add a resource name to the exclude filter
        * Resources on the exclude list will not pass the filter.
        * Excludes take precedence over includes
        */
    void AddExclude( const char* name );

    /// Returns the number of exclude entries in the filter
    int ExcludeCount() const;

    /** Returns the resource name for the given exclude list entry
        * \pre index < ExcludeCount()
        */
    const char* GetExclude( int index ) const;

    /** Removes a entry from the exclude list
        * This will reduce the ExcludeCount()
        * \pre index < ExcludeCount()
        */
    void RemoveExclude( unsigned int index );

    /// Removes all entries from the exclude list
    void ClearExcludes();

    /** Add a resource name to the include filter
        * If there are no includes specified, all resources
        * will pass the filter by default.
        * If IncludeCount() > 0, then only resources that
        * are included will pass the filter.
        */
    void AddInclude( const char* name );

    /// Returns the number of includes in the filter
    int IncludeCount() const;

    /** Returns the resource name for the given include list entry
        * \pre index < IncludeCount()
        */
    const char* GetInclude( int index ) const;

    /** Removes a entry from the include list
        * This will reduce the IncludeCount()
        * \pre index < IncludeCount()
        */
    void RemoveInclude( unsigned int index );

    /// Removes all entries from the include list
    void ClearIncludes();

    /// Test a resource name against the filter
    virtual bool PassFilter( const char* name ) const;

    /// assignment operator
    GlsResourceFilter& operator=( const GlsResourceFilter& rhs );
};

/** Template for a ResourceObserver that will call a class method whenever the attribute changes. 
    * Don't use this directly, use GlsRSOLoader::CreateResourceMethodCallback instead.
    */
template<class T>
class ResourceMethodCallback : public disti::RSOInterface4::ResourceObserver
{
public:
    typedef void ( T::*Callback )( disti::RSOInterface2::ResourceHandle );

    ResourceMethodCallback( T* object, Callback method )
        : _method( method )
        , _object( object )
    {
    }

    virtual void Call( disti::RSOInterface2::ResourceHandle handle )
    {
        ( _object->*( _method ) )( handle );
    }

    virtual void Destroy()
    {
        delete this;
    }

protected:
    Callback _method;
    T*       _object;
};

/** Create an ResourceObserver that will call a class method whenever the attribute changes.
    * \param obj the object to call the method on
    * \param method a class method pointer
    */
template<class Class>
disti::RSOInterface4::ResourceObserver* CreateResourceMethodCallback(
    Class* const                                           obj,
    const typename ResourceMethodCallback<Class>::Callback method )
{
    return new ResourceMethodCallback<Class>( obj, method );
}

} // end namespace GlsRSOLoader

#endif