gls_display_frame.h

Go to the documentation of this file.

/*! \file
  \brief  disti::glsDisplayFrame class.  The class for creating standalone executables.

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

// This is just here to have somewhere to put it that will get documented by doxygen.
/** \class Fl_Gl_Window
  * \htmlonly <dt><a href="fltk/Fl_Gl_Window.html">Fl_Gl_Window reference</a></dt> \endhtmlonly
  * \htmlonly <dt><a href="fltk/index.html">Complete Fltk documentation</a></dt> \endhtmlonly
  */

#ifdef GLES

#    ifdef __APPLE__
#        include "ios_display_frame.h"
#    elif defined( ANDROID )
#        include "android_display_frame.h"
#    elif defined( EMSCRIPTEN )
#        include "events.h"
#        include "gls_gl.h"
#        include "gls_include.h"
#        include "timer.h"
#    else
#        include "embedded_display_frame.h"
namespace disti
{
typedef EmbeddedDisplayFrame glsDisplayFrame;
}
#    endif

#else

#    include "gls_include.h"

#    ifdef WIN32
#        pragma warning( push )
#        pragma warning( disable : 4244 )
#    endif
#    include <FL/Fl.H>
#    include <FL/Fl_Box.H>
#    include <FL/Fl_Gl_Window.H>
#    include <FL/Fl_Window.H>
#    ifdef WIN32
#        pragma warning( pop )
#    endif

#    include "events.h"
#    include "runtime_display_frame.h"
#    include "timer.h"

class Fl_Gl_Window;

namespace disti
{
class SplashDisplay;
class glsDisplayFrame;

/** \class OpenGLWindow
  * OpenGLWindow is a GL Studio specific implementation of the Fltk Fl_Gl_Window
  */
class OpenGLWindow : public Fl_Gl_Window
{
    glsDisplayFrame* frame; /**< The DisplayFrame associated with this window */
    MouseEvent       ev;    /**< Last mouse event received */
    KeyboardEvent    kev;   /**< Last keyboard event received */

    /** Overload of FLTK draw routine */
    GLS_EXPORT void draw();

public:
    /** Overload of FLTK make_current() method.  Sets this window as the current OpenGL context */
    GLS_EXPORT void make_current();

    /** Overload of FLTK end() method.  Used to signal FLTK to not make this the "current" window to add widgets to */
    GLS_EXPORT void end();

    /** Overload of FLTK resizable() method. */
    GLS_EXPORT void resizable( OpenGLWindow* win );

    /** Overload of FLTK resize() method. Resizes the window.
      * \param x  New x coordinate of window on screen
      * \param y  New y coordinate of window on screen
      * \param w  New width of window in pixels
      * \param h  New height of window in pixels
      */
    GLS_EXPORT void resize( int x, int y, int w, int h );

    /** Overload of FLTK show() method. Sets the visible flag for this window, causing it to be shown the next time
      * the FLTK event loop is checked.
      */
    GLS_EXPORT void show();

    /** Overload of FLTK event handle routine.  This is how mouse and keyboard events get passed in */
    GLS_EXPORT int handle( int );

    /** Constructor for window
      * \param x Initial x loc of window
      * \param y Initial y loc of window
      * \param w Initial width of window
      * \param h Initial height of window
      * \param l Window title
      * \param frame_  Display to associate with window */
    GLS_EXPORT OpenGLWindow( int x, int y, int w, int h, const char* l, glsDisplayFrame* frame_ );

    /** Grabs the window contents and saves them to an uncompressed 24 bit BMP file
      * \param filename  Name of the file to write a BMP to
      */
    GLS_EXPORT void GrabWindow( char* filename );

    /** Converts mouse window coordinates to logical simulation coordinates.
      * \param frame DisplayFrame to convert for
      * \param x Mouse Device coordinate
      * \param y Mouse Device coordinate
      * \param lx Filled in with logical X coordinate
      * \param ly Filled in with logical Y coordinate
      */
    GLS_EXPORT void WindowToLogical( glsDisplayFrame* frame, float x, float y, float& lx, float& ly );
};

typedef void ( *GlsDrawCallback )( glsDisplayFrame* );

/** GL Studio standalone application class.
  * Creates one window and draws all contents in it.
  */
class glsDisplayFrame : public RuntimeDisplayFrame
{
protected:
    Timer frameTimer;          /**< Timer used for scheduling */
    float _smoothedFrameDelay; /**< Frame interval, smoothed based on actual draw performance */
    bool  _redraw;             /**< Flag indicating if the window should be redrawn */

    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;

    GlsDrawCallback _preDrawCallback;  /**< A function pointer that will be called prior to the Draw method being called */
    GlsDrawCallback _postDrawCallback; /**< A function pointer that will be called after the Draw method is called */

    SplashDisplay* splashDisplay; /**< The Spash screen image */

    int _current_view; /**< Current view of the canvas (e.g., ortho, perspective, eyepoint) */

    /** For better control over clipping and field of view, use a GlsEyePoint, but some limited functionality is available here */

    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. */

    bool _sKeyTogglesStatistics; /**< When true, the [s] key toggles statistics */
    bool _escKeyExits;           /**< When true, the [Esc] key exits the application */

    /* \see DisplayFrame */
    virtual GLS_EXPORT EventCompressor<DisplayFrame>* GetEventCompressor() { return &eventCompressor; }

public:
    OpenGLWindow* theWindow; /**< The window associated with this DisplayFrame */

    /** Used for event compression.  Not for general use by users. */
    EventCompressor<DisplayFrame> eventCompressor;

    /** Creates this glsDisplayFrame
      * \param name  Window Title
      * \param width Width of Dsplay Frame in pixels
      * \param height Width of Dsplay Frame in pixels
      */
    GLS_EXPORT glsDisplayFrame( const char* name, int width, int height );

    virtual GLS_EXPORT ~glsDisplayFrame();

    /** Removes (hides) the spash screen */
    virtual GLS_EXPORT void RemoveSplash();

    /** Creates the spash screen */
    virtual GLS_EXPORT void CreateSplash();

    /** Creates this display frame.  Called after the constructor so that things that need to
      * access the OpenGL context can safely do so */
    virtual GLS_EXPORT void Create( void );

    /** Sets up the default Orthographic projection (which supports things like pan and zoom) */
    virtual GLS_EXPORT void SetProjection( void );

    /** 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.
      */
    virtual GLS_EXPORT bool FrameAnimate( void );

    /** Redraw the window now.  
      * This actually calls the OpenGL Drawing routines. 
      */
    virtual GLS_EXPORT void Redraw( void );

    /** Set a flag that UpdateAnimate can test to see if the window needs redrawing. 
      */
    virtual GLS_EXPORT void SetRedraw( void );

    /** Only draw on events or if SetRedraw has been called.
      * If this is called in a main loop, updates can occur very frequently if SetRedraw is
      * continuously being called.
      */
    virtual GLS_EXPORT bool UpdateAnimate( void );

    /** Set the dimensions for the display frame window
      * \param X  New X coordinate of window
      * \param Y  New Y coordinate of window
      * \param W  New width of window
      * \param H  New height of window
      */
    virtual GLS_EXPORT void SetWindowDimensions( int X, int Y, int W, int H );

    /** Get the dimensions for the display frame window
      * \param X Gets X coordinate of window
      * \param Y Gets Y coordinate of window
      * \param W Gets width of window
      * \param H Gets height of window
      */
    virtual GLS_EXPORT void GetWindowDimensions( int& X, int& Y, int& W, int& H );

    /** Sets the post draw callback to the function pointer passed in */
    virtual GLS_EXPORT void PostDrawCallback( GlsDrawCallback cb );

    /** Sets the pre draw callback to the function pointer passed in */
    virtual GLS_EXPORT void PreDrawCallback( GlsDrawCallback cb );

    /** Sets the mode flags for the window
      * \param flags  The mode flags
      */
    virtual GLS_EXPORT void WindowFlags( unsigned long flags );

    /** 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 );

    /** Called after calling handle.  
      * \param handled True when the event has already been handled
      * \param ev the pointer to the the event
      * \return True If PostHandle has handled the event.
      * Checks for statistics toggle [s] key, and [ESC] key press.
      * The user can override this to turn off these behaviors.
      */
    virtual GLS_EXPORT bool PostHandle( bool handled, DisplayEvent* ev );

    /** Causes the window to center the view on the specified logical coordinate.  
      * It takes into account the possible rotation of the top group. 
      * \param lx  Logical X Coordinate
      * \param ly  Logical Y Coordinate
      */
    virtual GLS_EXPORT void CenterOnLogical( float lx, float ly );

    /** 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; }

    /** \return Whether or not the 'S' key is enabled for controlling statistics 
      */
    virtual GLS_EXPORT bool SKeyTogglesStatistics();

    /** Enable/disable s key for toggling statistics
      * \param flag  Whether or not S key will toggle statistics
      */
    virtual GLS_EXPORT void SKeyTogglesStatistics( bool flag );

    /** \return Whether or not the ESC key exits application
      */
    virtual GLS_EXPORT bool EscKeyExits();

    /** Enable/disable ESC key for exiting application
      * \param flag  Whether or not ESC key exits application
      */
    virtual GLS_EXPORT void EscKeyExits( bool flag );
};

} // namespace disti

#endif
#endif