DDD_RSOAsset.h

Go to the documentation of this file.

/*! \file DDD_RSOAsset.h
  
  \par Copyright Information

  Copyright (c) 2012 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 POSSIBLITY
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 _DDD_RSOAsset_h_
#define _DDD_RSOAsset_h_


#include "DDD_Include.h"
#include "DDD_AssetBase.h"
#include "DDD_AttributeString.h"
#include "DDD_AttributeInt.h"
#include "DDD_AttributeDouble.h"
#include "DDD_AttributeBool.h"
#include "DDD_ObjectEvent.h"
#include "DDD_ObjectEventSubscriber.h"

#include "rso_interface_1.h"
#include "component_base.h"
#include "display_frame.h"
#include "gls_eyepoint.h"
#include <string>

///////////////////////////////////////////////////////////
// Some macro definitions
///////////////////////////////////////////////////////////
#define RSO_ASSET_CLASS      "DDD_RSOAsset"  /**< Hard-coded identifier for this asset class. */
#define RSO_PARAM_DLL_PATH   "dllPath"       /**< Hard-coded param name for RSO DLL path */
#define RSO_PARAM_CLASS_NAME "className"     /**< Hard-coded param name for className */
#define RSO_PARAM_EYEPOINT   "eyepoint"      /**< Hard-coded param name for RSO Eyepoint */
#define RSO_PARAM_LOC_X      "locX"          /**< Hard-coded param name for RSO Location X value */
#define RSO_PARAM_LOC_Y      "locY"          /**< Hard-coded param name for RSO Location Y value */
#define RSO_PARAM_LOC_Z      "locZ"          /**< Hard-coded param name for RSO Location Z value */
#define RSO_PARAM_SCALE_X    "scaleX"        /**< Hard-coded param name for RSO Scale X value */
#define RSO_PARAM_SCALE_Y    "scaleY"        /**< Hard-coded param name for RSO Scale Y value */
#define RSO_PARAM_SCALE_Z    "scaleZ"        /**< Hard-coded param name for RSO Scale Z value */
#define RSO_INJECTED_EVENT_HANDLER "InjectedEventHandler" /**< Hard-coded param name for the RSOs EventPipe */
#define RSO_EVENT_SUBSCRIBER "EventSubscriber" /**< Hard-coded param name for Event Subscriber flag */

namespace disti
{
class GlsMultiView;

/** \brief The DDD_RSOAsset class. DataDirector asset class that controls GL Studio RSOs.
  */
class DDD_EXPORT DDD_RSOAsset : public DDD_AssetBase, 
                                public DDD_AttributeObserver,                               
                                public RSOInterface1::EmittedEventHandler,
                                public DDD_ObjectEventSubscriber
{
public:
    typedef DynamicPtrArray<DDD_RSOAsset *> RSOAssetList;

    static const char* const DDD_RSO_ASSET_CLASSNAME; /**< Classname string constant.  Needed by the AssetFactory */

protected:
    static RSOAssetList _rsoAssetList; /**< List of all loaded RSO assets */
    
    /*  Function that returns the currently loaded component
     * \return a pointer to the currently loaded component
     */
    disti::ComponentBase* GetLoadedComponent(const std::string &rsoLibName,const std::string &className);

    /*  Helper function that reads the data for connected attributes within a component
     *
     */
    void ReadDataFromDictionary();
public:

    /* Default constructor
     *
     */
    DDD_RSOAsset(DDD_AssetContainer *container);

    /* Default destructor
     *
     */
    virtual ~DDD_RSOAsset();

    /* Helper function that returns a string with a description for the 
     * RSOAsset class
     * \return  String with a description for the RSOAsset class
     */
    virtual const char *Description(){ return "Wrapper Asset class for RSO Components.";    }

    /* Function used to determine of the component is currently live
     * \return True if the component is live and False if it is not
     */
    virtual bool Live() { return (_component != NULL); }

    /* Helper function used to retrieve the list of attributes supported 
     * by the loaded component
     */
    virtual void PopulateAttributeList();

    /* Function used to retrieve the class name for this asset   
     * \return The RSO Asset class name
     */
    virtual const char* ClassName() { return RSO_ASSET_CLASS; }

    /* Function used to set the name of the current compoent instance
     * \param name String identifying the current component
     */
    virtual void SetInstanceName(const char *name);

    /* Helper function used to start and initialize the current component
     *
     */
    virtual void Start();

    /* Function used to pump the current asset
     * \param time  Time slice since the last pump
     */
    virtual void Calculate(double time);

    /** Resume asset.  Do allocations, initializations that should happen when the asset is resumed */
    virtual void Resume();

    /* Helper function used to generate the initial instance name. 
     * Overridden from DDD_AssetBase to use RSO Classname instead of DDD_RSOAsset
     * \param assetList  List of assets used to check uniqueness
     * \post _instanceName will have a unique identifier string
     */
    virtual void GenerateInstanceName(const DDD_AssetList& assetList);

    /* Function that implements the  DDD_AttributeObserver interface
     * \param attribute  Pointer to the attribute whose value just 
     * changed
     */
    virtual void OnAttributeChanged(DDD_AttributeBase *attribute);

    /* Returns _displayObject member
     * \return a pointer to the current displayOjbect
     */
    disti::ComponentBase* GetComponent();

    /** Sets the _topLevelDisplayFrame member, which is only used when the 
      * DataDirector is being embedded into a GlsDisplayFrame via the GlsDisplayFrame adapter
      */
    void SetTopLevelDisplayFrame(disti::DisplayFrame *frame);

    /* Sets the _component member.   
     * \param component  Pointer to the component to use for this asset
     */
    void SetComponent(disti::ComponentBase *component);

    /* Sets the width
     * \param width  Value to use for width
     */
    void SetWidth(float width) { _width = width; }
    
    /* Returns the current width
     * \return current width
     */
    float GetWidth() { return _width; }
    
    /* Sets the current height
     * \param height Value to use for height
     */
    void SetHeight(float height) { _height = height; }
    
    /* Returns the current height
     * \return current height
     */
    float GetHeight() { return _height; }

    /* Returns the unscaled original width
     * \return Unscaled Width value
     */
    float GetUnscaledWidth() { return _unscaledWidth; }

    /* Returns the unscaled original height
     * \return Unscaled height value
     */
    float GetUnscaledHeight() { return _unscaledHeight; }

    /* Returns the current scale
     * \param scale  reference to a vetor that will be populated with the current scale
     */
    void GetScale(disti::Vector& scale);

    /* Sets the current scale
     * \param scaleX  Scale value to use for X
     * \param scaleY  Scale value to use for Y
     * \param scaleZ  Scale value to use for Z
     */ 
    void Scale(float scaleX, float scaleY, float scaleZ);

    /* Helper function used to compute the scale 
     * Matric
     */
    void ComputeScaleMatrix();

    /* Returns the current origin
     * \return a vector describing the current origin
     */
    disti::Vector GetOrigin();

    /* Sets the current origin
     * \param origin  Vector describing the current origin
     */
    void SetOrigin(disti::Vector origin);

    /* Restricts the maximum/minimum size of components on initial 
     * creation- only changes scale
     */
    void NormalizeComponentSize();

    /* Returns the name of the eyepoint that is currently in use
     * \return  std::string containing the name of the current eyepoint
     */
    std::string GetEyepointName() { return _eyepointName; }

    /* Return the current multiview
     * \return  Pointer to a GlsMultiView instance used by the current asst
     */
    GlsMultiView* GetMultiView() { return _multiView; }

    /*  Helper function used to determine if the asset uses an eyepoint
     * \return  True if the asset uses an eyepoint and False if it doesn't
     */
    bool UsesEyepoint()  { return _usesEyepoint; }

    /*  Sets the multivew position for the current asset
     * \param bottom  Value to use for bottom 
     * \param left  Value to use for left
     * \param top  Value to use for top
     * \param right  Value to use for right
     */
    void SetMultiViewPos(float bottom, float left, float top, float right);

    /* Implementation for the  RSOInterface1::EmittedEventHandler interface
     * \param ev  Event emited by the RSO interface
     */
    virtual int HandleEvent(RSOInterface1::Event *ev);

    /** Event handler for direct connection to a component, not via the RSO interface
      * This is used when Data Director is embedded into an RSO or glsDisplayFrame
      * \param self  The component producing the event
      * \param ev   The event to handle
      * \return 1 If this method handled the event 
      */
    int HandleComponentEvent(ComponentBase *self,DisplayEvent *ev);

    // From DDD_ObjectEventSubscriber
    /** Posts an event to the ObjectEvent subscriber
      * \param newEvent  The event to post to the subscriber.  The subscriber 
      *                  must make a local copy of this event
      */
    virtual void PostEvent(DDD_ObjectEvent *newEvent);

protected:
    /** If this flag is true, then Data Director is controlling the Calculate clock.  If it's false
      * then the component is doing Calculate on its own and Data Director won't call calculate on it
      */
    bool _DDD_ControlsClock;

public:
    /** Sets the DDD_ControlsClock flag, which determines whether DataDirector should call Calculate on this component
      * \param val  If true, Data Director will call Calculate on this component during the Data Director Calculate traversal
      */
    void SetDDDControlsClock(bool val)
    {
        _DDD_ControlsClock = val;
    }

protected:
    /*  Helper function used to find an attribute object by name
     * \param attributeName  Name of the attribute we are looking for
     */
    virtual disti::DDD_AttributeBase* GetDictionaryAttribute(const char *attributeName);

    /* Sets the unscaled width. This should only be called once when the component
     * is instantiated.
     * \param width  Value to set as the unscaled width
     */
    void SetUnscaledWidth(float width) { _unscaledWidth = width; }
    
    /* Sets the unscaled height. This should only be called once when the component
     * is instantiated.
     * \param height  Value to set as the unscaled height
     */
    void SetUnscaledHeight(float height) { _unscaledHeight = height; }

    /* Updates scale and location of component from _loc and _scale variables
     *
     */
    void UpdateScaleAndLocation();  

private:
    /* Calls CreateLiveComponent and stores the returned value in _displayObject
     * \return True is succesful False otherwise
     */
    bool LoadLiveComponent();

    /*  Used to parse the getPropertiesMetadata resource in the current component
     *  NOTE: the _component variable needs to point to a valid rso instance
     */
    void ParseMetadata();

    /* Helper function used to determine if a particula attribute
     * exists within the attribute list with the provided name
     * \param attribName  Name of the attribute we are looking for
     * \return True if the attribute is found and False otherwise
     */
    bool IsAttributeInList(const std::string& attribName);

    /* uses _eyepointName to construct new eyepoint with attributes from given component
     * if _eyepointName isn't found within component, it returns false
     * returns false is component or eyepoint pointers are invalid as well
     * \param component  Component to use for setting the eyepoint
     * \param eyepoint  Eyepoint to set
     * \return True if sucesfull False otherwise
     */
    bool GetEyepointFromRSO(disti::ComponentBase *component, disti::GlsEyePoint *eyepoint);

    /** Get the list of resources and resource values from the RSO and store them into resourceList
      * \param resourceList A list of resource name/value pairs
      */
    void GetResourcesFromRSO(DDD_AttributeList &resourceList);

    /**  Add the exposed params to the attribute list
      */
    void AddExposedParamsAsAttributes();

private:

    disti::DisplayFrame *_topLevelDisplayFrame; /**< Pointer to the GlsDisplayFrame that contains this asset.  Only used when the GlsDisplayFrameAdapter is used */

    disti::ComponentBase *_component; /**< Points to the instance of the component for this asset */
    disti::ComponentBase *_rso;       /**< Points to the instance of the RSO for this asset.  NOTE: _rso and _component are genarly the same except for when
                                            an eyepoint is being used then the _rso is a part of the group inside the _component instance.  Use _rso to push/pull data */

    disti::CallbackMethodCallerBase *_oldCallback; /**< Container for any previously assigned callback to the associated RSO. */

    float _width;  /**< Current width of the component */
    float _height; /**< Current height of the component */


    float _unscaledWidth;   /**< Unscaled original width loaded from the component */
    float _unscaledHeight;  /**< Unscaled original height loaded from the component */

    float _unscaledOffsetX; /**< Unscaled original origin X */
    float _unscaledOffsetY; /**< Unscaled original origin Y */
    
    Vector _origin;         /**< Lower left corner */

    
    std::string _eyepointName;  /**< Contains the name of the eyepoint for _displayObject.  It has a length()
                                  * of 0 if it does not contain one. */

    bool _usesEyepoint;         /**< True if the RSO uses an eyepoint */

    GlsMultiView *_multiView;   /**< GlsMultiView used for viewing the component through its eyepoint */

    int _supportsAttEvents;     /**< True if this RSO supports the more efficient event interface */

    DDD_ObjectEventList  _objectEventQueue;    /**< Queue of incoming object events from ALL RSOs, including this one.  Populated by DataDirector */
    DDD_AttributeString     *_rsoLibFilename;  /**< The name of the RSO DLL to load */
    DDD_AttributeString     *_rsoClassName;    /**< The name of the RSO classname within the DLL */
    DDD_AttributeString     *_rsoEyepoint;     /**< The name of the RSO eyepoint within the DLL */
    DDD_AttributeDouble     *_locX;            /**< The Location of the RSO relative to the window origin (X) */
    DDD_AttributeDouble     *_locY;            /**< The Location of the RSO relative to the window origin (Y) */ 
    DDD_AttributeDouble     *_locZ;            /**< The Location of the RSO relative to the window origin (Z) */
    DDD_AttributeDouble     *_scaleX;          /**< The Scale of the RSO relative to its original size (X) */
    DDD_AttributeDouble     *_scaleY;          /**< The Scale of the RSO relative to its original size (Y) */ 
    DDD_AttributeDouble     *_scaleZ;          /**< The Scale of the RSO relative to its original size (Z) */
    DDD_AttributeBool       *_eventSubscriber; /**< Flag indicating if this RSO wants to receive events */

    DDD_AttributeDouble     *_AttLocX;            /**< Attribute for the Location of the RSO relative to the window origin (X) */
    DDD_AttributeDouble     *_AttLocY;            /**< Attribute for the Location of the RSO relative to the window origin (Y) */ 
    DDD_AttributeDouble     *_AttLocZ;            /**< Attribute for the Location of the RSO relative to the window origin (Z) */
    DDD_AttributeDouble     *_AttScaleX;          /**< Attribute for the Scale of the RSO relative to its original size (X) */
    DDD_AttributeDouble     *_AttScaleY;          /**< Attribute for the Scale of the RSO relative to its original size (Y) */ 
    DDD_AttributeDouble     *_AttScaleZ;          /**< Attribute for the Scale of the RSO relative to its original size (Z) */

    bool _reloadRSO;    /**< Flag for notifying asset to reload or load a new component */
};

}   // end namespace disti

#endif