gls_multi_view.h

Go to the documentation of this file.

/*! \file
  \brief  The disti::GlsMultiView 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_GLS_MULTI_VIEW_H
#define INCLUDED_DISTI_GLS_MULTI_VIEW_H
 
#include "display_types.h"
#include "gls_eyepoint.h"
#include "group.h"
 
/// Automatically link the runtime library plugin (on Windows).
#define LIB_BASE_NAME "gls_multi_view"
#include "gls_auto_lib.h"
#undef LIB_BASE_NAME
 
/// Provides support for creating DLLs.
#if( defined( GLSGEN_EXPORT_GlsMultiView ) || defined( GLSGEN_IMPORT_GlsMultiView ) || defined( GLS_EXPORT_GENERATED ) || defined( GLS_IMPORT_GENERATED ) ) \
    && defined( _MSC_VER )
#    if defined( GLSGEN_EXPORT_GlsMultiView ) || defined( GLS_EXPORT_GENERATED )
#        define GLSGEN_GlsMultiView_EXPORT __declspec( dllexport )
#    else
#        define GLSGEN_GlsMultiView_EXPORT __declspec( dllimport )
#    endif
#else
#    define GLSGEN_GlsMultiView_EXPORT
#endif
///////////////////////////////////////////////////////////////////////////////
 
namespace disti
{
// SetValue enumerations
enum
{
    GLS_GLSMULTIVIEW_FIRST_VALUE = GLS_LAST_INITIALIZER + 1,
    GLS_GLSMULTIVIEW_VIEW_DATA,
    GLS_GLSMULTIVIEW_VIEW_DRAWING_STATE
};
class ComponentLightMgr;
 
/** Runtime implementation of GlsMultiView */
class GlsMultiView : public Group
{
    friend class GlsMultiViewEditor;
 
public:
    DISTI_DEPRECATED( "This identifier is forbidden by the C++ standard. Use BaseClass instead." )
    typedef Group _BaseClass; ///< Deprecated typedef for the base class.
    typedef Group BaseClass;  ///< Typedef for the base class.
 
    /** Create a new GlsMultiView.
      * \param generateInstance  Whether or not to generate an instance name
      * for this inputdevice */
    GLSGEN_GlsMultiView_EXPORT GlsMultiView( int generateInstance = FALSE );
 
    /// Copy constructor
    /// \param that The object to copy from.
    /// \param generateNames Whether or not to generate an instance name.
    GLSGEN_GlsMultiView_EXPORT GlsMultiView( const GlsMultiView& that, const bool generateNames );
 
    /** GlsMultiView deconstructor */
    virtual GLSGEN_GlsMultiView_EXPORT ~GlsMultiView();
 
    /// \return A pointer to a new GlsMultiView object.
    static GLSGEN_GlsMultiView_EXPORT DisplayObject* CreateInstance();
 
    virtual GLSGEN_GlsMultiView_EXPORT void SetAvailableAttributes( unsigned int value ) DISTI_METHOD_OVERRIDE;
    virtual GLSGEN_GlsMultiView_EXPORT DisplayObject* CloneObject( bool generateNames = FALSE ) DISTI_METHOD_OVERRIDE;
    virtual GLSGEN_GlsMultiView_EXPORT void           PreDraw( const OpenGLMatrices& parentMatrices, Culler& culler ) DISTI_METHOD_OVERRIDE;
    virtual GLSGEN_GlsMultiView_EXPORT void           Draw() DISTI_METHOD_OVERRIDE;
    virtual GLSGEN_GlsMultiView_EXPORT void           CopyProperties( DisplayObject* src ) DISTI_METHOD_OVERRIDE;
 
#ifndef GLES
    virtual GLSGEN_GlsMultiView_EXPORT InterfaceListType* GetCppInterfaceDescription( InterfaceListType* addToThisList = NULL ) DISTI_METHOD_OVERRIDE;
    virtual GLSGEN_GlsMultiView_EXPORT void               GetCppInterfaceDescriptionFree( InterfaceListType* array ) DISTI_METHOD_OVERRIDE;
#endif
 
    virtual GLSGEN_GlsMultiView_EXPORT DisplayObject* Pick3D( const Vector& winLoc,
        const Vector&                                                       logicalCoords,
        float                                                               scale,
        const Vector&                                                       directionVector,
        Vector&                                                             collisionWinLoc, /*Returned*/
        const OpenGLMatrices&                                               drawnMatrices ) DISTI_METHOD_OVERRIDE;
 
    virtual GLSGEN_GlsMultiView_EXPORT DisplayObject* handle( DisplayEvent* ev ) DISTI_METHOD_OVERRIDE;
    virtual GLSGEN_GlsMultiView_EXPORT DistiAttributeBase& Resource( const char* name ) DISTI_METHOD_OVERRIDE;
    virtual GLSGEN_GlsMultiView_EXPORT void                GetResources( std::ostream& outstr, GlsResourceFilter* filter = NULL ) DISTI_METHOD_OVERRIDE;
    virtual GLSGEN_GlsMultiView_EXPORT void                SetValue( int spec, va_list& args ) DISTI_METHOD_OVERRIDE;
 
    //////////////////////////////////////////////////
    // Object specific operations
    //////////////////////////////////////////////////
 
    /// \details The ClearBackgroundEnum enumeration. Describes how the background for a given view will be cleared.
    enum
    {
        CLEAR_BG_OFF             = 0,
        CLEAR_BG_DEPTH_AND_COLOR = 1,
        CLEAR_BG_DEPTH           = 2,
        CLEAR_BG_COLOR           = 3
    } ClearBackgroundEnum;
 
    /// \details The ViewData class. Describes a single view within GlsMultiView.
    class ViewData : virtual public AttributeChangedNotifier
    {
        friend class GlsMultiView;
        friend class GlsMultiViewEditor;
 
        float        _bottom;          ///< The bottom edge of the view from 0.0 to 1.0, or in pixels if _absolutePixels is true.
        float        _left;            ///< The left edge of the view from 0.0 to 1.0, or in pixels if _absolutePixels is true.
        float        _top;             ///< The top edge of the view from 0.0 to 1.0, or in pixels if _absolutePixels is true.
        float        _right;           ///< The right edge of the view from 0.0 to 1.0, or in pixels if _absolutePixels is true.
        bool         _absolutePixels;  ///< If true, the corners are defined in screen space pixels, otherwise is the portion of the screen from 0.0 to 1.0.
        GlsEyePoint* _eyepoint;        ///< The associated eyepoint for this view, can be NULL. In this case the parent's view is used.
        std::string  _desiredEyePoint; ///< The optional name of the eyepoint to associate to this view.
        int          _clearBackground; ///< Defines the clear behavior for this view, \see ClearBackgroundEnum.
        bool         _pickGeometry;    ///< If true, allows the view itself to be picked.
        bool         _visible;         ///< If true, this view will be drawn.
        bool         _pickable;        ///< If true, geometry within the view can be picked.
 
        DistiAttribDict _attribDict;  ///< The attribute dictionary holding the members of this class.
        GlsMatrixType*  _modelMatrix; ///< The modelview matrix associated with this view.
        GlsMatrixType*  _projMatrix;  ///< The projection matrix associated with this view.
        int*            _viewPort;    ///< The viewport associated with this view.
        bool            _cullerVal;   ///< The state of the incoming Culler object, used in PreDraw.
 
        GlsMultiView* _multiView; ///< Parent pointer, back to the associated GlsMultiView object.
 
        /// \note For public access, use GetEyePoint(). It requires an object pointer.
        /// \return The pointer to the eyepoint for this view.
        GlsEyePoint* EyePoint();
 
        /// Set the associated parent GlsMultiView for this view.
        /// \param view The new parent object to set.
        void SetMultiview( GlsMultiView* view );
 
        /// Initializes the attribute dictionary for this object, associating member variables.
        void InitAttributes();
 
    public:
        GLSGEN_GlsMultiView_EXPORT ViewData();
 
        /// Copy constructor
        GLSGEN_GlsMultiView_EXPORT ViewData( const ViewData& );
 
        GLSGEN_GlsMultiView_EXPORT ~ViewData();
 
        /// Assignment operator
        /// \return The resulting object (this).
        GLSGEN_GlsMultiView_EXPORT const ViewData& operator=( const ViewData& );
 
        /// Copies the baseline data from the other view object.
        /// This does not include derived or cached values (like matrices / object pointers).
        /// \param other The object to copy from.
        GLSGEN_GlsMultiView_EXPORT void CopyBaseData( const ViewData& other );
 
        /// \return The attribute dictionary for this view.
        DistiAttribDict& Attributes() { return _attribDict; };
 
        virtual GLSGEN_GlsMultiView_EXPORT void NotifyAttributeChanged( const AttributeName& name ) DISTI_METHOD_OVERRIDE;
 
        /// Sets the Screen Rectangle
        /// The screen rect is specified in 0.0-1.0 as a ratio of the available viewport
        /// e.g. 0.0, 0.0, 1.0, 1.0 uses the full screen.
        /// \param bottom The bottom corner of the view rectangle.
        /// \param left The left corner of the view rectangle.
        /// \param top The top corner of the view rectangle.
        /// \param right The right corner of the view rectangle.
        GLSGEN_GlsMultiView_EXPORT void SetScreenRect( float bottom, float left, float top, float right );
 
        /// Returns the current screen rectangle.
        /// \param bottom The returned bottom corner of the view rectangle.
        /// \param left The returned left corner of the view rectangle.
        /// \param top The returned top corner of the view rectangle.
        /// \param right The returned right corner of the view rectangle.
        GLSGEN_GlsMultiView_EXPORT void GetScreenRect( float* bottom, float* left, float* top, float* right ) const;
 
        /// Set the bottom value.
        GLSGEN_GlsMultiView_EXPORT void Bottom( const float& );
 
        /// \return The bottom value.
        GLSGEN_GlsMultiView_EXPORT float Bottom() const;
 
        /// Set the left value.
        GLSGEN_GlsMultiView_EXPORT void Left( const float& );
 
        /// \return The left value.
        GLSGEN_GlsMultiView_EXPORT float Left() const;
 
        /// Set the top value.
        GLSGEN_GlsMultiView_EXPORT void Top( const float& );
 
        /// \return The top value.
        GLSGEN_GlsMultiView_EXPORT float Top() const;
 
        /// Set the right value.
        GLSGEN_GlsMultiView_EXPORT void Right( const float& );
 
        /// \return The right value.
        GLSGEN_GlsMultiView_EXPORT float Right() const;
 
        /// Set the absolute pixels flag.
        /// When true, the Left-Right-Top-Bottom values are interpreted
        /// as pixel coordinates, otherwise they are percentage of screen space.
        GLSGEN_GlsMultiView_EXPORT void AbsolutePixels( const bool& );
 
        /// Get the absolute pixels flag.
        /// When true, the Left-Right-Top-Bottom values are interpreted
        /// as pixel coordinates, otherwise they are percentage of screen space.
        /// \return the current absolute pixels flag
        GLSGEN_GlsMultiView_EXPORT bool AbsolutePixels() const;
 
        /// Sets the eyepoint to view from. When NULL, the parent view is used.
        GLSGEN_GlsMultiView_EXPORT void EyePoint( GlsEyePoint* );
 
        /// Sets the clear background mode
        /// 0 == Don't Clear; 1 == Clear both; 2 == Depth only; 3 == Color only
        /// \sa ClearBackgroundEnum
        GLSGEN_GlsMultiView_EXPORT void ClearBackground( const int& );
 
        /// \return The clear background mode.
        GLSGEN_GlsMultiView_EXPORT int ClearBackground() const;
 
        /// Sets the pick geometry flag
        /// When true, the geometry will be traversed with Pick3D in this view.
        GLSGEN_GlsMultiView_EXPORT void PickGeometry( const bool& );
 
        /// \return The pick geometry flag.
        GLSGEN_GlsMultiView_EXPORT bool PickGeometry() const;
 
        /// Set the visibility of this view .
        GLSGEN_GlsMultiView_EXPORT void Visible( bool );
 
        /// \return The visibility of this view.
        GLSGEN_GlsMultiView_EXPORT bool Visible() const;
 
        /// Set if this view is pickable.
        /// If true, and PickGeometry() is false, the view area will be picked.
        GLSGEN_GlsMultiView_EXPORT void Pickable( bool );
 
        /// \return The pickability of this view.
        GLSGEN_GlsMultiView_EXPORT bool Pickable() const;
 
        /// Set the name of the view's eyepoint.
        GLSGEN_GlsMultiView_EXPORT void DesiredEyePoint( const GlsPropString& );
 
        /// \return The name of the view's eyepoint.
        GLSGEN_GlsMultiView_EXPORT GlsPropString DesiredEyePoint() const;
 
        /// Finds the eyepoint or returns a previously found one.
        /// It will be based on the _desiredEyePoint.
        /// \param heirarchiedObject The point in the hierarchy to start searching for the eyepoint.
        /// \return A pointer to the found eyepoint, else NULL.
        GLSGEN_GlsMultiView_EXPORT GlsEyePoint* GetEyePoint( const DisplayObject* heirarchiedObject );
 
        /// Forces eyepoint reload, causes the multi view to trigger a redraw.
        GLSGEN_GlsMultiView_EXPORT void ForceEyePointReload();
 
        /// \return the cached OpenGL matrices from the previous frame's draw
        GLSGEN_GlsMultiView_EXPORT OpenGLMatrices SavedMatrices() const;
    };
 
    typedef DynamicArray<ViewData> ViewDataArray; ///< Shorthand typedef for a list of views.
 
    /// \details The ViewDrawStateEnum enumeration. Describes the drawing behavior for the multi view.
    typedef enum
    {
        GEOMETRY_ONLY = 0,
        GEOMETRY_AND_VIEWS,
        VIEWS_ONLY
    } ViewDrawStateEnum;
 
    /// Set the ViewDrawingState.
    GLSGEN_GlsMultiView_EXPORT void ViewDrawingState( ViewDrawStateEnum );
 
    /// \return the ViewDrawingState
    GLSGEN_GlsMultiView_EXPORT ViewDrawStateEnum ViewDrawingState();
 
    /** Returns the number of views 
      * \return The view count 
      */
    GLSGEN_GlsMultiView_EXPORT unsigned int ViewCount() const;
 
    /// Returns a reference to the specified View object
    /// Creates it (and all views with a lower id) if it doesn't exist
    /// \param viewNumber The index of the view to return.
    /// \return The associated view.
    GLSGEN_GlsMultiView_EXPORT ViewData& View( unsigned int viewNumber );
 
    /// \return A reference to the array containing the Views.
    GLSGEN_GlsMultiView_EXPORT ViewDataArray& ViewArray();
 
    /// Return the integer id of the last view that was picked or
    /// -1 if no view has been picked yet or if the GlsMultiview
    /// was picked because it is set to PICK_ALWAYS.
    /// \return The id of the last view that was picked.
    GLSGEN_GlsMultiView_EXPORT int LastViewPicked() const;
 
    /** Set the value for _emitViewDrawEvents
      * When true, an object event is emitted at the start and
      * end the draw of each view.
      * VIEW_DRAW_BEGIN and VIEW_DRAW_END
      * The data of the event is the view index.
      *
      * These events are currently EXPERIMENTAL and may be removed or
      * changed in a future release. They are not accessable from the 
      * plugin GUI for this reason.
      */
    GLSGEN_GlsMultiView_EXPORT void EmitViewDrawEvents( const bool& );
 
    /// \return The value for _emitViewDrawEvents.
    GLSGEN_GlsMultiView_EXPORT bool EmitViewDrawEvents() const;
 
    /// Draws the given view.
    /// \note Not normally called by users.
    /// \param viewNumber The index of the view to draw.
    /// \param view The view data of the view to draw.
    GLSGEN_GlsMultiView_EXPORT void DrawView( unsigned int viewNumber, ViewData* view );
 
protected:
    /// Calculate the matrices that are used for drawing the given view.
    /// This method is called during the PreDraw, then the matrices
    /// are used to setup the geometry for the Draw and Pick3D later.
    /// \note Not normally called by users.
    /// \param parentMatrices The initial matrix state at the parent view.
    /// \param culler The intial culler state at the parent view.
    /// \param view The view to calculate matrices for.
    GLSGEN_GlsMultiView_EXPORT void CalculateViewMatrices( const OpenGLMatrices& parentMatrices, Culler& culler, GlsMultiView::ViewData* view ) const;
 
    /// Applies the matrices for the given view to the geometry in preparation for a pick or draw.
    /// \note Not normally called by users.
    /// \param viewNumber The number of the last view predraw or -1 if predraw used parent's view.
    /// \param view The view data to predraw for.
    /// \return True if the predraw was successful (view data is valid).
    GLSGEN_GlsMultiView_EXPORT bool PreDrawGeometryForView( int viewNumber, ViewData* view );
 
    /// Forces a recalculation of parent lighting based on the current view.
    /// \note Not normally called by users.
    /// \param view The view to be used when calling ComponentLightMgr::ReapplyLightsForEyePoint().
    GLSGEN_GlsMultiView_EXPORT void ReapplyGlobalLightsForView( ViewData* view );
 
#ifdef GLES
    /** Set a single attribute from the GLO file.
     * \param data The attribute to set and its associated data.
     */
    GLSGEN_GlsMultiView_EXPORT virtual void SetFromGloData( GlsGloFileAttribute& data ) DISTI_METHOD_OVERRIDE;
#endif
 
    ViewDrawStateEnum _viewDrawingState; ///< The drawing behavior for the multi view, generally VIEWS_ONLY.
    ViewDataArray     _viewArray;        ///< The list of all views associated with this multi view.
    ViewData          _mainViewData;     ///< The main (parent) view used for drawing geometry based views.
    int               _lastViewPicked;   ///< The index of the last view picked, or -1 if the main view.
    int               _lastViewPredraw;  ///< The index of the last view predraw or -1 if predraw used parent's view.
 
    bool _showHighlights; ///< Used by the editor to turn on and off highlights.
    int  _highlightView;  ///< Used by the editor to highlight a specific view. -1 is none.
 
    bool _emitViewDrawEvents; ///< If true, will emit VIEW_DRAW_BEGIN / VIEW_DRAW_END object events on draw.
 
    ComponentLightMgr* _multiViewLightMgr;       ///< Our very own light manager.
    bool               _childLightsAffectGlobal; ///< Calculated internally based on if geometry is drawn.
 
    GlsMatrixType _savedProjectionMatrix; ///< Stores the projection matrix from PreDraw for restoring after DrawView
 
private:
    void OnViewDataChanged();
    void OnViewDrawingStateChanged();
    void OnViewArrayChange();
 
    void          DummySetInt( const int& ) {} // Used for making a read only property
    GlsMultiView& operator=( const GlsMultiView& ) DISTI_SPECIAL_MEM_FUN_DELETE;
    GlsMultiView( const GlsMultiView& ) DISTI_SPECIAL_MEM_FUN_DELETE;
};
 
/// \details The DistiAttributeViewDataArray class. Allows access to GlsMultiView::ViewData through the resource interface.
class DistiAttributeViewDataArray : public DistiAttributeBase
{
    GlsMultiView::ViewDataArray& _array; ///< Observing reference to underlying view data storage.
 
public:
    /// Constructor, uses existing storage
    /// \param caller The callback to call when this attribute changes.
    /// \param name The name of the attribute.
    /// \param array The existing view data storage.
    DistiAttributeViewDataArray( CallbackMethodCallerBase* caller, AttributeName name, GlsMultiView::ViewDataArray& array )
        : DistiAttributeBase( caller, name, false )
        , _array( array )
    {
    }
 
    /// Assignment operator
    /// \param oldClass The object to copy from.
    /// \return The resulting object (this).
    DistiAttributeBase& operator=( const DistiAttributeBase& oldClass ) DISTI_METHOD_OVERRIDE
    {
        const DistiAttributeViewDataArray* ptr;
        if( ( ptr = dynamic_cast<const DistiAttributeViewDataArray*>( &oldClass ) ) )
        {
            // Copy array contents directly
            _array = ptr->_array;
            CallCallback();
        }
        else
        {
            // Copy by string value
            return DistiAttributeBase::operator=( oldClass );
        }
        return *this;
    }
 
    std::istream& ReadValue( std::istream& instr ) DISTI_METHOD_OVERRIDE
    {
        // Scan through the token including the ':'
        std::string buf;
 
        // read through opening brace
        instr.ignore( 1024, '{' );
 
        // Clear the array before reading
        _array.Clear();
 
        while( DistiAttribDict::ScanToken( instr, buf ) )
        {
            if( buf.length() )
            {
                int index;
                index = atoi( buf.c_str() );
 
                // Eat the space between the : and the data
                instr.get();
                instr.ignore( 1024, '{' );
 
                // This eats the closing brace
                _array[ index ].Attributes().Read( instr );
            }
        }
        CallCallback();
 
        return instr;
    }
 
    std::ostream& WriteValue( std::ostream& outstr ) DISTI_METHOD_OVERRIDE
    {
        outstr << "\n"
               << DistiAttribDict::SpacingString() << "{"
               << "\n";
        DistiAttribDict::SpacingInc();
 
        for( unsigned int i = 0; i < _array.Count(); i++ )
        {
            outstr << DistiAttribDict::SpacingString() << i << ":\n";
            outstr << DistiAttribDict::SpacingString() << "{\n";
            DistiAttribDict::SpacingInc();
 
            _array[ i ].Attributes().Write( outstr );
 
            DistiAttribDict::SpacingDec();
            outstr << DistiAttribDict::SpacingString() << "}\n";
        }
        DistiAttribDict::SpacingDec();
        outstr << DistiAttribDict::SpacingString() << "}";
        return outstr;
    }
};
 
} // namespace disti
 
#endif