runtime_display_frame.h

Go to the documentation of this file.

/*! \file
  \brief  The disti::RuntimeDisplayFrame class, parent class of all DisplayFrames used in runtime code.

  \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 _RUNTIME_DISPLAY_FRAME_H
#define _RUNTIME_DISPLAY_FRAME_H

#include "display_frame.h"
#include "gls_include.h"
#include "timer.h"

namespace disti
{
class Statistics;
class GlsEyePoint;

/** Provides basic support for runtime display frames */
class RuntimeDisplayFrame : public DisplayFrame
    , virtual public GlsPainter
{
private:
    Statistics* _stats; /**< Keeps track of draw/predraw/calculate timing statistics */
protected:
    Timer  _frameTimer;         /**< Timer used for scheduling */
    Timer& frameTimer;          /** for backwards compatibility */
    float  _smoothedFrameDelay; /**< Frame interval, smoothed based on actual draw performance */

    /** For better control over clipping and field of view, use a GlsEyePoint, but some limited functionality is available here */
    float  _width_offset;  /**< Current "width" offset of window.  Used for panning of display horizontally in ortho mode. */
    float  _height_offset; /**< Current "height" offset of window.  Used for panning of display vertically in ortho mode.  */
    Vector _viewOffset;
    float  _depthFactor;   /**< Used for auto calculations */
    double _fov;           /**< Field Of View.  If 0.0 (the default), fov will be auto calculated. */
    double _nearZ;         /**< Near clipping plane.  Only meaningful if _autoCalcNearZ is false */
    bool   _autoCalcNearZ; /**< When true a _nearZ is automatically calculated. */
    double _farZ;          /**< Far clipping plane.  Only meaningfull if _autoCalcVarZ is false */
    bool   _autoCalcFarZ;  /**< When true a _farZ is automatically calculated. */
    int    _current_view;  /**< Current view of the canvas (e.g., ortho, perspective, eyepoint) */

    std::string  _name;            /**< The title of this display frame's window, if applicable */
    float        _scale;           /**< Scale of the window */
    unsigned int frameInterval;    /**< The frame interval in microSeconds (inverse of frame rate) */
    GlsEyePoint* _currentEyePoint; /**< The current eyepoint for viewing the scene */
    bool         _redraw;          /**< Flag indicating if the window should be redrawn */

public:
    /** Ctor for RuntimeDisplayFrame
      * \param name  The title of the display frame. Shown in the window title bar.
      * \param width  The width of the display frame window, in pixels.
      * \param height  The height of the display frame window, in pixels.
      */
    GLS_EXPORT RuntimeDisplayFrame( const char* name, int width, int height );

    /** Dtor for RuntimeDisplayFrame */
    virtual GLS_EXPORT ~RuntimeDisplayFrame();

    /** Clears the window associated with the display frame.
      * The current _clearBitfield is used */
    virtual GLS_EXPORT void Clear( void );

    /** \return The current eyepoint for the display frame */
    virtual GLS_EXPORT GlsEyePoint* CurrentEyePoint();

    /** Sets the current eyepoint for the display frame.
      * \param eye  The eyepoint to use for the display frame.
      */
    virtual GLS_EXPORT void CurrentEyePoint( GlsEyePoint* eye );

    /** Set the scale for the display frame.
      * \param scale  The new scale factor.  Must be non-zero.  A value of zero will be ignored.
      */
    virtual GLS_EXPORT void Scale( float scale );

    /** \return The current scale for the display frame */
    virtual GLS_EXPORT float Scale( void ) DISTI_METHOD_OVERRIDE;

    /** Handles keyboard and mouse events and dispatches them to the display objects.
      * \param ev  A display event
      * \return Pointer to the object that handled the event or NULL if no object handled it.
      */
    virtual GLS_EXPORT DisplayObject* handle( DisplayEvent* ev );

    /** Sets the background color of the window to the given value
      * \param r New red color (0-255 range)
      * \param g New green color (0-255 range)
      * \param b New blue color (0-255 range)
      * \param a New alpha color (0-255 range)
      */
    virtual GLS_EXPORT void BackgroundColor( unsigned char r, unsigned char g, unsigned char b, unsigned char a );

    /** Gets the background color of the window to the given value
      * \param r Gets red color (0-255 range)
      * \param g Gets green color (0-255 range)
      * \param b Gets blue color (0-255 range)
      * \param a Gets alpha color (0-255 range)
      */
    virtual GLS_EXPORT void GetBackgroundColor( unsigned char& r, unsigned char& g, unsigned char& b, unsigned char& a );

    /** Sets the background color of the window to the given value
      * \param color The new color
      */
    virtual GLS_EXPORT void BackgroundColor( const GlsColor& color );

    /** Gets the title(name) of this display frame
      * \return  The name of this display frame
      */
    GLS_EXPORT const char* Name( void );

    /** Sets the name(title) for this display frame
      * \param name  The new title for the display frame
      */
    GLS_EXPORT void Name( char* name );

    /** Gets the background color of the window to the given value
      * \return The background color
      */
    virtual GLS_EXPORT GlsColor BackgroundColor( void );

    /** Returns the Frame Interval in microseconds
      * \return The Frame Interval in microseconds
      */
    virtual GLS_EXPORT int FrameInterval( void );

    /** Sets the target Frame Interval in microseconds 
      * \param interval  The frame interval in microseconds
      */
    virtual GLS_EXPORT void FrameInterval( int interval );

    /** Creates and returns a pointer to a statistics object
      * \return A pointer to the statistics object
      */
    virtual GLS_EXPORT Statistics* Stats();

    /** Part of display frame statistics, for recording time used in Calculate() */
    virtual GLS_EXPORT void RecordCalculateStart( void );

    /** Part of display frame statistics, for recording time used in Calculate() */
    virtual GLS_EXPORT void RecordCalculateEnd( void );

    /** Call this before deleting objects which may be being kept
      * by the drag or focus objects */
    virtual GLS_EXPORT void ClearDragAndFocus() DISTI_METHOD_OVERRIDE;

    /** Redraws the scene if the scene has changed since the last frame, and also calls WaitForNextFrame to ensure we are not drawing 
     * faster than the set frame interval allows.
     * \returns true if we the scene was redrawn.  Generally used to determine if the buffers need to be swapped
     */
    virtual GLS_EXPORT bool UpdateAnimate();

    /** Redraw the window at the Hz rate set for the DisplayFrame, or at least
     * try to.  We might be slower if the hardware can't keep up.
     * \return on desktop runtimes, returns true if any window is still open.  On ES runtimes always returns true.
     */
    virtual GLS_EXPORT bool FrameAnimate();

    /** Sleeps based on the Hz rate set for the DisplayFrame. */
    virtual GLS_EXPORT void WaitForNextFrame();

    /** Redraws the window, using the platform specific mechanism. Place holder for base class implementations.  Simple implementations may draw directly, while
      * implementations that use a window manager may tell the window manager to redraw.
     */
    virtual GLS_EXPORT void Paint(){};

    /** Pans the display horizontally
     * \param offset  The new X position at the center of the window 
     */
    virtual GLS_EXPORT void WidthOffset( float offset );

    /** Gets the horizontal position of the display at the center of the window
     * \return  The X position at the center of the window
     */
    virtual GLS_EXPORT float WidthOffset( void );

    /** Pans the display vertically
     * \param offset  The new Y position of the center of the window
     */
    virtual GLS_EXPORT void HeightOffset( float offset );

    /** Gets the vertical position of the display at the center of the window
     * \return  The Y position at the center of the window
     */
    virtual GLS_EXPORT float HeightOffset( void );

    /** Sets the Depth Factor for the window
     * \param factor  The depth factor.  Used for autocalculating clipping planes */
    virtual GLS_EXPORT void DepthFactor( float factor );

    /** Gets the Depth Factor for the window
     * \return  The current depth factor 
     */
    virtual GLS_EXPORT float DepthFactor();

    /** Sets the FOV (Field of View) for the window.   If fov is set to 0.0, a reasonable FOV
     * will be calculated based on width and height.
     * \param fov  New field of view in degrees 
     */
    virtual GLS_EXPORT void FOV( double fov );

    /** Gets the FOV (Field of View) for the window.
     * \return  The current field of view in degrees
     */
    virtual GLS_EXPORT double FOV();

    /** Sets the current view mode for the window
     * \param view  The new view mode for the window.  
     * Acceptable view types are:
     * [VIEW_EYEPOINT    - The application will be viewed through an eyepoint]
     * [VIEW_XY          - The application will be viewed through a 2D orthographic view of the XY plane]
     * [VIEW_PERSPECTIVE - The application will be viewed through a perspective projection]
     */
    virtual GLS_EXPORT void CurrentView( const int view ) { _current_view = view; }

    /** Gets the current view mode for the window.
     * \return The current viewmode for the window (VIEW_EYEPOINT, VIEW_XY, VIEW_PERSPECTIVE)
     */
    virtual GLS_EXPORT int CurrentView( void ) const { return _current_view; }

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

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

    /** The background clear color */
    GlsColor _backgroundColor; // DDH:   This is public yet has an accessor method....should it be protected?
};

} // namespace disti

#endif