gls_mimic_group.h

Go to the documentation of this file.

/*! \file
  \brief

  \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_GLS_MIMIC_GROUP_H
#define INCLUDED_GLS_MIMIC_GROUP_H

#include "frame_buffer_utility.h"

#include "gls_cpp_lang_support.h"
#include "group.h"
#include "image.h"

//////////////////// Provides support for creating DLLs ////////////////////////
#if( defined( GLSGEN_EXPORT_GLSMIMICGROUP ) || defined( GLSGEN_IMPORT_GLSMIMICGROUP ) || defined( GLS_EXPORT_GENERATED ) || defined( GLS_IMPORT_GENERATED ) ) \
    && defined( _MSC_VER )
#    if defined( GLSGEN_EXPORT_GLSMIMICGROUP ) || defined( GLS_EXPORT_GENERATED )
#        define GLSGEN_GLSMIMICGROUP_EXPORT __declspec( dllexport )
#    else
#        define GLSGEN_GLSMIMICGROUP_EXPORT __declspec( dllimport )
#    endif
#else
#    define GLSGEN_GLSMIMICGROUP_EXPORT
#endif
///////////////////////////////////////////////////////////////////////////////

#define LIB_BASE_NAME "gls_mimic_group"
#include "gls_auto_lib.h"
#undef LIB_BASE_NAME

namespace disti
{
#ifdef GLES
class GlsGloFile;
#endif

// SetValue enumerations
enum
{
    GLS_MIMIC_GROUP_STATE = GLS_LAST_INITIALIZER + 1,
    GLS_MIMIC_GROUP_MIMIC_ACTIVE,
    GLS_MIMIC_GROUP_BOTTOM_LEFT_CORNER,
    GLS_MIMIC_GROUP_TOP_RIGHT_CORNER,
    GLS_MIMIC_GROUP_SHOW_OUTLINE,
    GLS_MIMIC_GROUP_TEXTURE_HEIGHT,
    GLS_MIMIC_GROUP_TEXTURE_WIDTH,
    GLS_MIMIC_GROUP_HAS_DEPTH_BUFFER,
    GLS_MIMIC_GROUP_DEPTH_TEST,
    GLS_MIMIC_GROUP_GENERATE_MIPMAPS,
    GLS_MIMIC_GROUP_DRAW_MIMIC_POLYGON,
    GLS_MIMIC_GROUP_ATTACHED_TEXTURE_INDEX,
    GLS_MIMIC_GROUP_CLEAR_COLOR,
    GLS_MIMIC_GROUP_USE_OPAQUE_TEXTURE,
    GLS_MIMIC_GROUP_MIMIC_AUTO_REDRAW
};

/**
* The GlsMimicGroup class provides a way to group objects that change
* infrequently into a single textured polygon such that performance is increased due
* to not having to render the objects every frame. Instead, since all of the objects
* in the group are replaced with a single texture, performance is saved by updating the texture
* ONLY through handling a display event of name "MimicGroupUpdate". Whenever an object
* placed in this group is modified, you must write code to emit a "MimicGroupUpdate" ObjectEvent
* so that any changes made to its appearance will be reflected in the rendered texture.
*
* For example:
* EmitObjectEvent( objectThatChanged, "MimicGroupUpdate" );
*
* Picking and event handling for objects within the GlsMimicGroup work the same as
* for a regular Group, so it can contain interactive objects such as buttons, switches, etc.
* The GlsMimicGroup will only redraw the texture when it receives a "MimicGroupUpdate"
* ObjectEvent so you must write code to emit these events whenever a
* press, toggle, etc. affect the appearance of the object.
*
* The GlsMimicGroup can contain 2D or 3D objects.  All of these objects will be replaced
* with a 2D texture polygon so the GlsMimicGroup is best suited for use with panels that are mostly 2D.
* The GlsMimicGroup can also be useful with a collection of 3D objects as long as the
* GlsMimicGroup remains screen-aligned.
*
* On older hardware that does not support the render-to-texture capabilities required by the
* GlsMimicGroup, the GlsMimicGroup will fall-back to rendering like a regular Group.
*/
class GlsMimicGroup : public Group
    , virtual public GlsPainter
{
private:
    GlsMimicGroup& operator=( const GlsMimicGroup& ) DISTI_SPECIAL_MEM_FUN_DELETE;
    GlsMimicGroup( const GlsMimicGroup& ) DISTI_SPECIAL_MEM_FUN_DELETE;

public:
    friend class GlsMimicGroupEditor;
    DISTI_DEPRECATED( "This identifier is forbidden by the C++ standard. Use BaseClass instead." )
    typedef Group _BaseClass;
    typedef Group BaseClass;

    /**
    * Constructor.
    *
    * \param generateInstance  Whether or not to generate an instance name
    *                          for this mimic group
    */
    GLSGEN_GLSMIMICGROUP_EXPORT GlsMimicGroup( bool generateInstance = false );

    GLSGEN_GLSMIMICGROUP_EXPORT GlsMimicGroup( const GlsMimicGroup& that, const bool generateNames );

    /**
    * Destructs a GlsMimicGroup object
    */
    virtual GLSGEN_GLSMIMICGROUP_EXPORT ~GlsMimicGroup();

    /**
    * Provides a way to statically create an instance of the GlsMimicGroup
    *
    * \return an instance of a GlsMimicGroup
    */
    static GLSGEN_GLSMIMICGROUP_EXPORT DisplayObject* CreateInstance();

    /**
    * \see DisplayObject
    */
    virtual GLSGEN_GLSMIMICGROUP_EXPORT void SetAvailableAttributes( unsigned int value ) DISTI_METHOD_OVERRIDE;

    /**
    * \see DisplayObject
    */
    virtual GLSGEN_GLSMIMICGROUP_EXPORT DisplayObject* CloneObject( bool generateNames = false ) DISTI_METHOD_OVERRIDE;

    /**
    * \see DisplayObject
    */
    virtual GLSGEN_GLSMIMICGROUP_EXPORT void CopyProperties( DisplayObject* src ) DISTI_METHOD_OVERRIDE;

#ifndef GLES
    /**
    * \see DisplayObject
    */
    virtual GLSGEN_GLSMIMICGROUP_EXPORT InterfaceListType* GetCppInterfaceDescription( InterfaceListType* addToThisList = NULL ) DISTI_METHOD_OVERRIDE;

    /**
    * \see DisplayObject
    */
    virtual GLSGEN_GLSMIMICGROUP_EXPORT void GetCppInterfaceDescriptionFree( InterfaceListType* array ) DISTI_METHOD_OVERRIDE;
#endif

    /**
    * \see DisplayObject
    */
    virtual GLSGEN_GLSMIMICGROUP_EXPORT void Draw( void ) DISTI_METHOD_OVERRIDE;

    /**
    * \see DisplayObject
    */
    virtual GLSGEN_GLSMIMICGROUP_EXPORT void SetValue( int spec, va_list& args ) DISTI_METHOD_OVERRIDE;

    //////////////////////////////////////////////////
    // GlsMimicGroup specific operations
    //////////////////////////////////////////////////

    /**
    * Accessor for the mimic texture width.
    *
    * \return the width, in pixels, of the mimic texture.
    */
    virtual GLSGEN_GLSMIMICGROUP_EXPORT unsigned int TextureWidth() const { return _textureWidth; }

    /**
    * Set the mimic texture width.
    *
    * \param textureWidth the width, in pixels, of the mimic texture.
    */
    virtual GLSGEN_GLSMIMICGROUP_EXPORT void TextureWidth( unsigned int textureWidth );

    /**
    * Accessor for the mimic texture height.
    *
    * \return the height, in pixels, of the mimic texture.
    */
    virtual GLSGEN_GLSMIMICGROUP_EXPORT unsigned int TextureHeight() const { return _textureHeight; }

    /**
    * Set the mimic texture height.
    *
    * \param textureHeight the height, in pixels, of the mimic texture.
    */
    virtual GLSGEN_GLSMIMICGROUP_EXPORT void TextureHeight( unsigned int textureHeight );

    /**
    * Whether or not the mimic will render a depth buffer.
    *
    * \return true if the mimic will render a depth buffer.
    */
    virtual GLSGEN_GLSMIMICGROUP_EXPORT bool HasDepthBuffer() const { return _hasDepthBuffer; }

    /**
    * Set whether or not the mimic will render a depth buffer.
    *
    * \param hasDepthBuffer true if the mimic will render a depth buffer.
    */
    virtual GLSGEN_GLSMIMICGROUP_EXPORT void HasDepthBuffer( bool hasDepthBuffer );

    /**
    * Whether or not the mimic will generate mip maps.
    *
    * \return true if the mimic will generate mip maps.
    */
    virtual GLSGEN_GLSMIMICGROUP_EXPORT bool GenerateMipMaps() const { return _generateMipMaps; }

    /**
    * Set whether or not the mimic will generate mip maps.
    *
    * \param generate true if the mimic will generate mip maps.
    */
    virtual GLSGEN_GLSMIMICGROUP_EXPORT void GenerateMipMaps( bool generate );

    /**
    * Whether or not a mimic polygon will be drawn.
    *
    * \return true if a mimic polygon will be drawn.
    */
    virtual GLSGEN_GLSMIMICGROUP_EXPORT bool DrawMimicGroupPolygon() const { return _drawMimicGroupPolygon; }

    /**
    * Set whether or not a mimic polygon will be drawn.
    *
    * \param draw true if a mimic polygon will be drawn.
    */
    virtual GLSGEN_GLSMIMICGROUP_EXPORT void DrawMimicGroupPolygon( bool draw );

    /**
    * Accessor for the mimic depth test settings.
    *
    * \return the depth settings
    */
    virtual GLSGEN_GLSMIMICGROUP_EXPORT unsigned char MimicGroupDepthTest() const { return _mimicGroupDepthTest; }

    /**
    * Set the mimic depth test settings.
    *
    * \param depthSettings the depth settings
    */
    virtual GLSGEN_GLSMIMICGROUP_EXPORT void MimicGroupDepthTest( unsigned char depthSettings );

    /**
    * Accessor for the mimic auto-redraw for conditional rendering settings.
    *
    * \return the depth settings
    */
    virtual GLSGEN_GLSMIMICGROUP_EXPORT bool AutoRedraw() const { return _autoRedraw; }

    /**
    * Set the mimic auto-redraw for conditional rendering.
    *
    * \param autoRedrawSetting the enable to automatically update.
    */
    virtual GLSGEN_GLSMIMICGROUP_EXPORT void AutoRedraw( bool autoRedrawSetting );

    /**
    * Accessor for the mimic scene background clear color.
    *
    * \return the RGBA color that the mimic will use to clear mimic scene background with
    */
    virtual GLSGEN_GLSMIMICGROUP_EXPORT GlsColor ClearColor() const { return _clearColor; }

    /**
    * Set the mimic scene background clear color.
    *
    * \param color the RGBA color that the mimic will use to clear mimic scene background with
    */
    virtual GLSGEN_GLSMIMICGROUP_EXPORT void ClearColor( const GlsColor& color );

    /**
    * Accessor for the GL Studio texture index the mimic will generate into.
    *
    * \return the GL Studio texture index the mimic will generate into.  If -1, then mimic will generate its own texture.
    */
    virtual GLSGEN_GLSMIMICGROUP_EXPORT int AttachedTextureIndex() const { return _attachedTextureIndex; }

    /**
    * Set the GL Studio texture index the mimic will generate into.
    *
    * \param textureIndex the GL Studio texture index to generate mimic into.  If -1, then mimic will generate its own texture.
    */
    virtual GLSGEN_GLSMIMICGROUP_EXPORT void AttachedTextureIndex( int textureIndex );

    /**
    * Whether or not the mimic is active for this group.
    * If not active, mimic group behaves as a normal group
    *
    * \return true if mimic is active for this group
    */
    GLSGEN_GLSMIMICGROUP_EXPORT bool MimicGroupActive( void ) { return _mimicGroupActive; }

    /**
    * Sets if mimic is active for this group
    * If not active, mimic group behaves as a normal group
    *
    * \param activate whether or not to activate the mimic
    */
    GLSGEN_GLSMIMICGROUP_EXPORT void MimicGroupActive( bool activate );

    /**
    * Set the bottom left corner of mimic scene region
    *
    * \param bottomLeftCorner (in object coordinates)
    */
    GLSGEN_GLSMIMICGROUP_EXPORT void BottomLeftCorner( const Vector& bottomLeftCorner );

    /**
    * Accessor for the bottom left corner coordinate of the mimic scene region.
    *
    * \return the bottom left corner of mimic scene region  (in object coordinates)
    */
    GLSGEN_GLSMIMICGROUP_EXPORT Vector BottomLeftCorner( void ) { return _bottomLeftCorner; }

    /**
    * Set the top right corner of mimic scene region
    *
    * \param topRightCorner (in object coordinates)
    */
    GLSGEN_GLSMIMICGROUP_EXPORT void TopRightCorner( const Vector& topRightCorner );

    /**
    * Accessor for the top right corner coordinate of the mimic scene region.
    *
    * \return the top right corner of mimic scene region (in object coordinates)
    */
    GLSGEN_GLSMIMICGROUP_EXPORT Vector TopRightCorner( void ) const { return _topRightCorner; }

    /**
    * Whether or not the outline of the mimic polygon region should be shown in the editor.
    *
    * \return true if region should always be drawn in the editor
    */
    GLSGEN_GLSMIMICGROUP_EXPORT bool ShowOutline( void ) const { return _showOutline; }

    /**
    * Set whether or not the mimic polygon region should always be drawn in the editor.
    *
    * \param showOutline  true if outline should always be drawn in editor
    */
    GLSGEN_GLSMIMICGROUP_EXPORT void ShowOutline( bool showOutline );

    /**
    * Whether or not the mimic group needs to redraw.
    *
    * \return true if the mimic group needs to redraw.
    */
    GLSGEN_GLSMIMICGROUP_EXPORT bool Redraw( void ) const { return _redraw; }

    /**
    * Set whether or not the mimic group needs to redraw
    *
    * \param redraw the new redraw value
    */
    GLSGEN_GLSMIMICGROUP_EXPORT void Redraw( bool redraw );

    /**
    * Whether or not the mimic group texture is RGB.
    *
    * \return true if the mimic group texture is RGB.
    */
    GLSGEN_GLSMIMICGROUP_EXPORT bool UseOpaqueTexture( void ) const { return _useOpaqueTexture; }

    /**
    * Set whether the mimic group texture is RGB or RGBA
    *
    * \param opaque true for RGB, false for RGBA
    */
    GLSGEN_GLSMIMICGROUP_EXPORT void UseOpaqueTexture( bool opaque );

    /**
    * \see DisplayObject
    */
    GLSGEN_GLSMIMICGROUP_EXPORT void SetPainter( GlsPainter* painter ) DISTI_METHOD_OVERRIDE;

    /**
    * \see Group
    */
    virtual GLSGEN_GLSMIMICGROUP_EXPORT void InsertObject( DisplayObject* obj, bool reparent = true, bool recalculateBoundingbox = true, int loc = -1 ) DISTI_METHOD_OVERRIDE;

    /**
    * \see Group
    */
    virtual GLSGEN_GLSMIMICGROUP_EXPORT void PushObject( DisplayObject* obj ) DISTI_METHOD_OVERRIDE;

    /**
    * \see GlsPainter
    */
    GLSGEN_GLSMIMICGROUP_EXPORT void Invalidate() DISTI_METHOD_OVERRIDE;

    /**
    * \see GlsPainter
    */
    GLSGEN_GLSMIMICGROUP_EXPORT bool IsInvalidated() const DISTI_METHOD_OVERRIDE;

protected:
    /**
    * Set up the matrices for the root of the mimic scene. The mimic scene is drawn without regard to any
    * parent matrices of the mimic group.
    */
    virtual GLSGEN_GLSMIMICGROUP_EXPORT void SetMatrices();

    /**
    * Predraw case for when the mimic scene redraws
    */
    virtual GLSGEN_GLSMIMICGROUP_EXPORT void PreDrawMimicGroupChildren( const OpenGLMatrices& parentMatrices, Culler& culler );

    /**
    * Set depth buffer settings when rendering the mimic polygon
    */
    GLSGEN_GLSMIMICGROUP_EXPORT void SetupMimicGroupDepthTest();

    /**
    * Get the four corners of the region transformed by the current DCS and offset by the group's location
    *
    * \param topLeftCorner [out] receives top left corner
    * \param topRightCorner [out] receives top right corner
    * \param bottomRightCorner [out] receives bottom right corner
    * \param bottomLeftCorner [out] receives bottom left corner
    */
    GLSGEN_GLSMIMICGROUP_EXPORT void GetRegionCorners( Vector& topLeftCorner, Vector& topRightCorner, Vector& bottomRightCorner, Vector& bottomLeftCorner );

    /**
    * Apply texture settings for mimic polygon
    */
    GLSGEN_GLSMIMICGROUP_EXPORT void ApplyMimicGroupTextureSettings();

    /**
    * Allocate and create the diffuse texture map
    */
    GLSGEN_GLSMIMICGROUP_EXPORT void CreateDiffuseTexture();

    /**
    * Allocate and create the depth texture map
    */
    GLSGEN_GLSMIMICGROUP_EXPORT void CreateDepthTexture();

    /**
    * Allocate and create the mimic quad
    */
    GLSGEN_GLSMIMICGROUP_EXPORT void CreateMimicGroupQuad();

    /**
    * Allocate and create the frame buffer
    */
    GLSGEN_GLSMIMICGROUP_EXPORT void CreateFrameBuffer();

    /**
    * Delete the frame buffer (if it has been bound)
    */
    GLSGEN_GLSMIMICGROUP_EXPORT void DeleteFrameBuffer();

    /**
    * Redraw the scene
    */
    GLSGEN_GLSMIMICGROUP_EXPORT void RedrawScene();

    /**
    * Draw the polygon for the mimic
    */
    GLSGEN_GLSMIMICGROUP_EXPORT void DrawPolygon();

    /**
    * Regenerate the mip maps
    */
    GLSGEN_GLSMIMICGROUP_EXPORT void RegenerateMipMaps();

    /**
    * \see DisplayObject
    */
    GLSGEN_GLSMIMICGROUP_EXPORT DisplayObject* handle( DisplayEvent* displayEvent ) DISTI_METHOD_OVERRIDE;

    /**
     * The GlsMimicGroup requres specific extensions of OpenGL which are not required
     * elsewhere in GL Studio. This method will check that those features are supported.
     *
     * \return True if the required features are supported.
     */
    GLSGEN_GLSMIMICGROUP_EXPORT bool RequiredGlFeaturesSupported();

    /**
     * Logs the unsupported features that the GlsMimicGroup class requires to function properly.
     */
    GLSGEN_GLSMIMICGROUP_EXPORT void LogUnsupportedFeatures();

    /**
     * Determines if vertex buffer objects are supported on this platform.
     *
     * \return True if vertex buffer objects are supported on this platform.
     */
    GLSGEN_GLSMIMICGROUP_EXPORT bool VertexBuffersAreSupported();

    /**
     * Draw the mimic group. Care should be taken to call this method only when it is safe to draw
     * the mimic group. The Draw() has the conditional structure necessary to
     * make this decision.
     *
     */
    GLSGEN_GLSMIMICGROUP_EXPORT void DrawMimicGroup();

#ifdef GLES
    /**
    * Set a single attribute from the GLO file.
    *
    * \param data The attribute to set and its associated data.
    */
    virtual GLSGEN_GLSMIMICGROUP_EXPORT void SetFromGloData( GlsGloFileAttribute& data ) DISTI_METHOD_OVERRIDE;
#endif

    bool          _mimicGroupActive;      /*< Whether or not the mimic is active.  If not active, mimic group behaves as a normal group */
    bool          _autoRedraw;            /*< Whether or not the mimic group should automatically update via conditional rendering */
    bool          _redraw;                /*< Whether or not the mimic scene needs to redraw */
    bool          _hasDepthBuffer;        /*< Whether or not the mimic will render a depth buffer */
    bool          _generateMipMaps;       /*< Whether or not the mimic will generate mip maps */
    bool          _showOutline;           /*< Outline is only visible in editor */
    bool          _drawMimicGroupPolygon; /*< Whether or not a mimic polygon will be drawn.  */
    unsigned char _mimicGroupDepthTest;   /*< Mimic depth test settings (affects whether or not the mimic polygon is depth tested) */
    bool          _textureIndexChanged;
    GlsColor      _clearColor;                     /*< RGBA color to clear mimic scene background with */
    Vector        _bottomLeftCorner;               /*< Bottom Left Corner of the mimic scene region */
    Vector        _topRightCorner;                 /*< Top Right Corner of the mimic scene region */
    int           _attachedTextureIndex;           /*< GL Studio texture index to generate mimic into.  If -1, then mimic will generate its own texture. */
    unsigned int  _textureWidth;                   /*< Width of the mimic texture in pixels (MUST BE power of two) */
    unsigned int  _textureHeight;                  /*< Height of the mimic texture in pixels (MUST BE power of two) */
    unsigned int  _frameBufferHandle;              /*< Handle for frame buffer object */
    unsigned int  _depthBufferHandle;              /*< Handle for depth buffer object */
    Image*        _mimicGroupTexture;              /*< Image object for texture */
    unsigned int  _vertexBufferHandle;             /*< Vertex buffer handle for mimic quad */
    bool          _frameBuffersEnabledAndAttached; /**< True when frame buffer support is detected and frame buffers were attached successfully */
    bool          _overrideMimicGroupActive;       /**< True if the mimic group is not allowed to be activated due to platform restrictions. */
    bool          _useOpaqueTexture;               /*< True if the atached frame buffer texture should be crated as GL_RGB, False will create the texture as GL_RGBA  */

    static bool _unsupportedLogged; /**< True if a warning has been logged to users that the mimic group feature is not supported. This keeps us from spamming the user about not being supported. */
};

} // namespace disti

#endif