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"

namespace disti
{
class Statistics;
class GlsEyePoint;

/** Provides basic support for runtime display frames */
class RuntimeDisplayFrame : public DisplayFrame
{
private:
    Statistics* _stats; /**< Keeps track of draw/predraw/calculate timing statistics */
protected:
    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 */

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

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

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

} // namespace disti

#endif