lib/wave-glut/wave-glut.h

Go to the documentation of this file.

/*
 * wave-glut.h
 *
 * Copyright (C) 2008-2010  Thomas A. Vaughan
 * All rights reserved.
 *
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *     * Neither the name of the <organization> nor the
 *       names of its contributors may be used to endorse or promote products
 *       derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THOMAS A. VAUGHAN ''AS IS'' AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THOMAS A. VAUGHAN BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 *
 * This "library" (my own glut library) is just a thin shell on top of the
 * actual freeglut libraries.  This is here only to make it easy for other
 * programs that use glut to find headers, link correctly, etc.
 */

#ifndef WAVE_GLUT_WAVE_GLUT_H__
#define WAVE_GLUT_WAVE_GLUT_H__


// includes --------------------------------------------------------------------
#include "color/color.h"
#include "geometry/geometry_3d.h"
#include "geometry/matrix_4.h"
#include "threadsafe/smart_ptr.h"

// need to define these to force static linking
#define FREEGLUT_STATIC
#define GLUT_STATIC_LIB
#define GLEW_STATIC

#include "GL/glew.h"
#ifdef WIN32
#include "GL/wglew.h"
#else   // WIN32
#include "GL/glxew.h"
#endif  // WIN32
#include "GL/freeglut.h"

namespace glut {


////////////////////////////////////////////////////////////////////////////////
///
/// \ingroup wave_glut
/// \defgroup glut Wavepacket Glut Library Wrapper
///
/// \n
/// Mostly this library
/// is here only as a convenient placeholder.  Code with
/// glut dependencies can refer to this module in the build, and then the
/// right directories will be searched for include files, the right libraries
/// linked, etc.
///
/// This library does provide a few helper objects and methods to make using
/// glut easier, and to abstract away common setup code.
///
////////////////////////////////////////////////////////////////////////////////
/*@{*/


/// base floating point color object
struct fcolor_t {
        // constructor, manipulators
        fcolor_t(void) throw() { this->clear(); }
        void clear(void) throw() {
                        red = green = blue = 0.0;
                        alpha = 1.0;
                }
        bool isValid(void) const throw() {
                        return (red >= 0.0 && red <= 1.0 &&
                                green >= 0.0 && green <= 1.0 &&
                                blue >= 0.0 && blue <= 1.0 &&
                                alpha >= 0.0 && alpha <= 1.0);
                }
        operator float * (void) throw() {
                        return &red;
                }
        operator const float * (void) const throw() {
                        return &red;
                }

        // data fields
        float           red;
        float           green;
        float           blue;
        float           alpha;
};



/// If a client wants to use this library's glut helper entry point, it needs
/// to supply an object that supports this interface.
class Host {
public:
        // public typedefs -----------------------------------------------------
        enum eBehavior {
                eContinue       = 1,    ///< continue in glut loop
                eExit           = 2,    ///< exit program immediately

                // must be last!
                eInvalid        = 0
        };

        // virtual destructor --------------------------------------------------
        virtual ~Host(void) throw();

        // glut::Host class interface methods ----------------------------------

        /// Called once, at initialization (just before main glut loop)
        virtual void init(void) { }

        /// Called on every glut idle event, with elapsed seconds since last
        virtual eBehavior tick(IN float dt) { return eContinue; }

        /// Called for every display frame.
        virtual void display(IN int w, IN int h) { }

        /// Called on mouse motion (see glutPassiveMotionFunc()).
        virtual eBehavior mouseMove(IN int x, IN int y) { return eContinue; }

        /// Called on mouse button events (see glutMouseFunc()).
        virtual eBehavior mouseButton(IN int button, IN int state,
                                IN int x, IN int y)
                                { return eContinue; }

        /// Called on keyboard events.
        virtual eBehavior keyboard(IN int key, IN int mods)
                                { return eContinue; }

        /// Called when a special key is pressed (see glutSpecialFunc())
        virtual eBehavior specialKey(IN int key, IN int mods)
                                { return eContinue; }

        /// Called only once, at glut shutdown.  Host can provide program
        ///     return value (typically zero if no errors).
        virtual int shutdown(void) { return 0; }
};



/// clients can call this to get common glut setup
void start(IN int argc,
                        IN const char * argv[],
                        IN int width,           ///< window width, pixels
                        IN int height,          ///< window height, pixels
                        IN const char * title,  ///< window title
                        IN const char * gameModeString, ///< optional
                        IN smart_ptr<Host>& host);



/// \ingroup glut
/// \defgroup glut_threading Wavepacket OpenGL Threading
///
/// \n
/// Threading in OpenGL is non-trivial!  Just do some internet searches for
/// "OpenGL multithreading context" and you'll see what I mean.
///
/// \n
/// In general, OpenGL isn't easy to use in a multithreaded way.  It can be
/// done, but for most purposes, diving into OpenGL contexts is probably overkill.
/// However, by default OpenGL isn't thread-friendly, so some sort of
/// synchronization is required.
///
/// \n
/// This library uses multithreading in OpenGL in a very basic way: a single thread
/// is doing all of the rendering, but background threads occasionally kick in
/// and need to load and set up textures, etc.
///
/// When a thread needs to do some open-GL specific work (that is, any time
/// it needs to call OpenGL or glut APIs!) it should request that as a task.
/// If the calling thread is not the OpenGL thread, the call (requestTask())
/// will block until the OpenGL thread gets to it.  If the thread is the
/// OpenGL thread, then the task executes right away.
/*@{*/


/// Create one of these (you'll have to inherit) if you have openGL work you
/// need to submit to requestTask().
class Task {
public:
        // virtual destructor --------------------------------------------------
        virtual ~Task(void) throw();

        // glut::Task class interface methods ----------------------------------

        /// here is where the implementer can do any OpenGL-specific work
        virtual void doTask(void) = 0;
};



/// Here a thread can request that a task be handled by the open GL thread.
/// Blocks until task is completed!  If task throws an exception, the
/// exception will also be thrown back to the caller.
void requestTask(IO Task * task);


/// draw the outline of a 3D rectangle
void drawRectLines(IN const rect3d_t& r,
                                IN const glut_color_t& c) throw();

/// get a 4x4 matrix from the given OpenGL matrix
void getModelViewMatrix(OUT matrix4_t& T) throw();


};      // glut namespace


#endif  //WAVE_GLUT_WAVE_GLUT_H__