display_frame.h

Go to the documentation of this file.

/*! \file
  \brief  The disti::DisplayFrame 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 INCLUDED_DISTI_DISPLAY_FRAME_H
#define INCLUDED_DISTI_DISPLAY_FRAME_H

#include "display.h"
#include "gls_include.h"
#include "gls_painter.h"
#include "image.h"
#include "texture_palette.h"
#include "util.h"
#include "vertex.h"
#include <string.h>
#ifndef GLS_EDITOR_CODE
#    include "message.h"
#endif

#include "disti_metadata.h"
#include "dynamic_array.h"
#include "input_handler.h"
#include "material.h"
#include "scoped_ptr.h"
#include "sound.h"
#include "weak_referenceable_mixin.h"

struct DragObjectMap;

namespace disti
{
static const int MAX_PLAYABLE = 20; /**< Max. Number of sound files that can be played */

const char META_COMPONENT_HEADER_FILE_NAME[] = "ComponentHeaderFile";

typedef DynamicArray<Material> DynamicMaterialArray; /**< Typedef for dynamic array of materials */

class Group;
class ComponentLightMgr;

template<class>
class EventCompressor;

/** The base class for associating a display device with an object list.
  *
  * DisplayFrame contains all of the display objects, texture, and fonts for
  * an application.
  *
  */
class DisplayFrame : virtual public AttributeChangedNotifier
    , virtual public WeakReferenceableMixin
{
private:
    DistiAttribDict*        _frameAttribDict; /**< Stores all of the attributes specific to the DisplayFrame */
    ScopedPtr<InputHandler> _inputHandler;

protected:
    bool                 _cullingEnabled;  /**< True if culling is enabled for this DisplayFrame */
    int                  _width;           /**< The width of the window for this display frame */
    int                  _height;          /**< The height of the window for this display frame */
    float                _lastPickedDepth; /**< Keeps previous picks depth for use when no pick is performed (dragging) */
    DynamicMaterialArray _materialPalette; /**< A Dynamic array for keeping the materials for this frame */
    ComponentLightMgr*   _lightMgr;        /**< The _lightMgr is used to setup lighting for the DisplayFrame */
    GLbitfield           _clearBitfield;   /**< The OpenGL bitfield to use when clearing.  /see glClear */

    std::string _componentHeaderFileName; /**< backing store for META_COMPONENT_HEADER_FILE_NAME attribute */

    DragObjectMap* _dragObjectMap;
    unsigned int   _currentCursor;     /**< the current cursor being processed */
    bool           _multitouchEnabled; /**< whether or not multitouch is enabled */
    unsigned int   _cursorsDown;       /**< The number of cursors (touches) that are currently down */

    /** Changes the current cursor to the specified cursor id.  Needed by multitouch, so that DragObject and FocusObject will return
      * the correct objects for the current cursor.
      * \param cursor_id the cursor id
      */
    virtual GLS_EXPORT void CurrentCursor( unsigned int cursor_id );

    /** Cleanup unused entries from the drag map */
    void CleanupDragMap();

    /** Get the drag object that corresponds to the curosr 
      * \param cursorID the cursor
      * \return the drag object or null if none exists
      */
    DisplayObject* GetDragObjectForCursor( unsigned int cursorID );

    /** Find a non-null drag object from the _dragObjectMap if on exists
      * \return a drag object, or null if there aren't any in the map 
      */
    DisplayObject* FindDragObject();

    /* Get the event compressor for this display frame, if it exists
    * \return the event compressor
    */
    virtual GLS_EXPORT EventCompressor<DisplayFrame>* GetEventCompressor() { return NULL; };

    /** \return The current scale for the display frame 
      */
    virtual GLS_EXPORT float Scale( void ) { return 1.0f; }

public:
    TexturePalette* texturePalette; /**< An array of textures allocated for display on objects */
    SoundSystem*    _sound_player;  /**< Sound file player for this DisplayFrame */
    Group*          objects;        /**< The object hierarchy for this display frame */

    /** Creates a new display frame
      * \param width  The width of this display frame in pixels
      * \param height The height of this display frame in pixels
      * \param allocateObjects
      */
    GLS_EXPORT DisplayFrame( int width, int height, bool allocateObjects = true );

    virtual GLS_EXPORT ~DisplayFrame( void );

    /** Sets the OpenGL clear bitmask that will be used when the window is cleared
      * \param bitField The OpenGL bitfield to use when clearing.  /see glClear
      */
    inline void ClearBitfield( GLbitfield bitField ) { _clearBitfield = bitField; }

    /** Gets the OpenGL clear bitmask that will be used when the window is cleared
      * \return The OpenGL bitfield to use when clearing.  /see glClear
      */
    inline GLbitfield ClearBitfield() { return _clearBitfield; }

    /** Sets the current "Drag" object for the current cursor
      * \param obj The new DragObject
      */
    virtual GLS_EXPORT void DragObject( DisplayObject* obj );

    /** Gets the current "Drag" object for the current cursor
      * \return The current DragObject
      */
    virtual GLS_EXPORT DisplayObject* DragObject( void );

    /** Clears the drag objects for all cursors.*/
    virtual GLS_EXPORT void ClearDrag();

    /** Sets the current focus object for the current cursor.*/
    virtual GLS_EXPORT void FocusObject( DisplayObject* obj );

    /** Gets the current "Focus" object for the current cursor
      * \return The current FocusObject
      */
    virtual GLS_EXPORT DisplayObject* FocusObject( void );

    /** Clears the focus objects for all cursors.*/
    virtual GLS_EXPORT void ClearFocus();

    /** Enables/Disables multitouch on the display frame.  Multitouch is enabled by default.  This function has no effect on platforms that
      * do not support multitouch */
    virtual GLS_EXPORT void MultitouchEnabled( bool enabled );

    /** Gets whether or not multitouch is enabled on the display frame. */
    virtual GLS_EXPORT bool MultitouchEnabled( void );

    /** Get the input handler */
    virtual GLS_EXPORT InputHandler* GetInputHandler();

    /** Handles a display event.  Picks an object and also tracks focus.
    */
    virtual GLS_EXPORT DisplayObject* HandleDisplayEvent( DisplayEvent* ev );

    /** Write the resources (attributes) of the objects in this display frame to the specified file
      * \param filename Name of the file to write to
      * \param filter   A filter to specify which attributes to write
      */
    virtual GLS_EXPORT void WriteResources( const char* filename, GlsResourceFilter* filter = NULL );

    /** Read the resources (attributes) of the objects in this display frame from the specified file
      * \param filename Name of the file to read from
      */
    virtual GLS_EXPORT void ReadResources( const char* filename );

    /** Gets a reference to the specified attribute for reading and writing.
      * This reference can be streamed into and out of variables.
      * This can access different levels of objects.
      * For example:
      * The DisplayFrame:  
      *         Resource("ComponentHeaderFile") >> someStdString;
      * An object in the DisplayFrame:
      *         Resource("SomeObject.Visible") << someBool;
      * An object in a Component in this DisplayFrame:
      *         Resource("SomeComponentObject.SomeObject.Visible") >> someBool;
      */
    virtual GLS_EXPORT DistiAttributeBase& Resource( const char* name );

    /** Get the resources for this display frame and all it's children acording to the filter
      * \param outstr The stream to write to
      * \param filter The filter to control what gets written.
      */
    virtual GLS_EXPORT void GetResources( std::ostream& outstr, GlsResourceFilter* filter = NULL );

    /** Parse a stream of resource value pairs.
      * \param instr Stream containing the resource data
      */
    virtual GLS_EXPORT void SetResources( std::istream& instr );

    /** Sets a DisplayFrame resource value. 
      * \param resourceName Name of the resource to set.
      * \param resourceVal Value of the resource to set
      */
    inline void SetResource( const std::string& resourceName, const std::string& resourceVal )
    {
        SetResource_CRTClean( resourceName.c_str(), resourceVal.c_str() );
    }
    inline void SetResource( const char* resourceName, const char* resourceVal )
    {
        SetResource_CRTClean( resourceName, resourceVal );
    }

    /** Gets a DisplayFrame resource value. 
      * \param resourceName Name of the resource to set
      */
    inline std::string GetResource( const std::string& resourceName )
    {
        char*       value     = GetResource_CRTClean( resourceName.c_str() );
        std::string stringVal = value;
        GetResourceFree_CRTClean( value );
        return stringVal;
    }
    inline std::string GetResource( const char* resourceName )
    {
        char*       value     = GetResource_CRTClean( resourceName );
        std::string stringVal = value;
        GetResourceFree_CRTClean( value );
        return stringVal;
    }

    /** CRT Insensitive version of GetResource()
      * Version with streams can not be called from differently compiled code.
      * \param name name of resource
      * \return The requested value allocated as a char array.
      * The user MUST call GetResourceFree() when finished using returned value.
      */
    virtual GLS_EXPORT char* GetResource_CRTClean( const char* name );

    /** Frees the memory allocated by a previous GetResource_CRTClean call
      * \param  memoryToFree Pointer to memory allocated by GetResource_CRTClean
      */
    virtual GLS_EXPORT void GetResourceFree_CRTClean( char* memoryToFree );

    /** CRT Insensitive version of GetResources()
      * \param filter The filter to control what gets written
      * \return A null terminated char* containing the requested resources
      * The user MUST call GetResourcesFree() on the returned value.
      */
    virtual GLS_EXPORT char* GetResources_CRTClean( GlsResourceFilter* filter );

    /** Frees the memory allocated by a previous GetResources_CRTClean call
      * \param  memoryToFree Pointer to memory allocated by GetResource_CRTClean
      */
    virtual GLS_EXPORT void GetResourcesFree_CRTClean( char* memoryToFree );

    /** CRT Insensitive version of SetResource()
      * Version with streams can not be called from differently compiled code.
      * \param name name of resource
      * \param value new value for resource
      */
    virtual GLS_EXPORT void SetResource_CRTClean( const char* name, const char* value );

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

    /** Implements AttributeChangedNotifier::NotifyAttributeChanged.
      * Notify the class that the attribute has changed.  Observers of the attribute will have their callbacks called 
      * \param name the name of the attribute
      */
    virtual GLS_EXPORT void NotifyAttributeChanged( const AttributeName& name ) DISTI_METHOD_OVERRIDE;

#ifndef GLES
    /** Get the details of the Cpp Interface
      * The actual interface is exposed in compiled code.
      * \param addToThisList A list to add to and then return.  Creates a new one if NULL.
      * \return A templated list.  
      * The caller must call the corresponding free method to
      * safely free the memory.
      */
    virtual GLS_EXPORT InterfaceListType* GetCppInterfaceDescription( InterfaceListType* addToThisList = NULL );

    /** Frees the memory allocated by a previous GetCppInterfaceDescription call
      * \param  array Pointer to memory allocated by GetCppInterfaceDescription
      */
    virtual GLS_EXPORT void GetCppInterfaceDescriptionFree( InterfaceListType* array );
#endif

    /** Sets the texture palette size for this display frame
      * \param cnt  The number of entries to have in the display frame
      */
    GLS_EXPORT void SetTexturePaletteSize( int cnt );

    /** Draw the objects contained in this display frame */
    GLS_EXPORT void Draw( void );

    /* Adds the specified object into this display frame 
      * \param  A pointer to the object to add
      * \param  Whether or not the object parent should be set to this group
      * \param  Whether or not to recalculate the bounding box
      * \param  Where to insert it (defaults to -1 which means at the end of the list)
      */
    GLS_EXPORT void InsertObject( DisplayObject* obj, bool reparent = true, bool recalculateBoundingbox = true, int loc = -1 );

    /** Inserts a display object into this display frame at the specified
      * index in the object list.
      * \param obj  The object to insert
      * \param loc  Where to insert the object
      */
    GLS_EXPORT void InsertObject( DisplayObject* obj, int loc );

    /** Inserts a display object into this display frame at the end
      * of the object list.
      * \param obj  The object to insert
      */
    GLS_EXPORT void PushObject( DisplayObject* obj );

    /** Gets the width in pixels of this display frame
      * \return  The width in pixels of this display frame
      */
    GLS_EXPORT int Width( void );

    /** Gets the height in pixels of this display frame
      * \return  The height in pixels of this display frame
      */
    GLS_EXPORT int Height( void );

    /** Sets the width in pixels of this display frame
      * \param w  The new width in pixels of this display frame
      */
    GLS_EXPORT void SetWidth( int w );

    /** Sets the height in pixels of this display frame
      * \param h  The new height in pixels of this display frame
      */
    GLS_EXPORT void SetHeight( int h );

    /** Does nothing here in the base class.  Allows other display
      * frames to add functionality.  
      * \deprecated Should not be called by new code.  
      */
    virtual GLS_EXPORT void SetRedraw( void ) {}

    /** Gets the whether or not culling is enabled for this display frame
      * \return  whether or not culling is enabled for this display frame
      */
    GLS_EXPORT bool CullingEnabled( void );

    /** Sets the whether or not culling is enabled for this display frame
      * \param enabled  whether or not culling is enabled for this display frame
      */
    GLS_EXPORT void CullingEnabled( const bool enabled );

    /** Sets up the OpenGL Pipeline to the state expected by GL Studio drawing.
      * resetTemplate is used to not reset certain catagories.  For example, it may
      * be desirable for a GL Studio object to receive lighting from it's VegaPrime scene.
      * \param saveVal  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.
      */
    static GLS_EXPORT void SetOpenGLDefaultState( bool saveVal );

    /** 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.
      */
    static GLS_EXPORT void RestoreOpenGLState( void );

    /** \return A reference to the Attribute dictionary for this display frame */
    inline DistiAttribDict& FrameAttribDict( void ) { return *_frameAttribDict; }

    /** \return A const reference to the Attribute dictionary for this display frame */
    inline const DistiAttribDict& FrameAttribDict( void ) const { return *_frameAttribDict; }

    /** \return A reference to the material palette for this display frame */
    inline DynamicMaterialArray& MaterialPalette( void ) { return _materialPalette; }

    /** \return A pointer to the light manager for this display frame */
    inline ComponentLightMgr* LightMgr( void ) { return _lightMgr; }

    /** Sets the light manager for this display frame.
      * This is used only for very special cases.
      * The current LightMgr is NOT deleted when the new one is set.
      * If this is used, it is recommended to restore the value to 
      * the original value.
      * \param val The pointer to the new light manger.
      */
    inline void LightMgr( ComponentLightMgr* val ) { _lightMgr = val; }

    /** Call this before deleting objects which may be being kept
      * by the drag or focus objects.
      * If an object is to be deleted.  The user must ensure that it is not
      * being used as the drag or focus object.  If it is, a leave event may 
      * be sent to it after it has been deleted, causing a crash.  
      * To avoid this the user can either ensure that the object never handles mouse events,
      * or call ClearDragAndFocus() imediatly before deleting them */
    virtual GLS_EXPORT void ClearDragAndFocus();
};

} // namespace disti

#endif