glut.h

Go to the documentation of this file.
00001 /*
00002  * glut.h
00003  *
00004  * Copyright (C) 2008-2010  Thomas A. Vaughan
00005  * All rights reserved.
00006  *
00007  *
00008  * Redistribution and use in source and binary forms, with or without
00009  * modification, are permitted provided that the following conditions are met:
00010  *     * Redistributions of source code must retain the above copyright
00011  *       notice, this list of conditions and the following disclaimer.
00012  *     * Redistributions in binary form must reproduce the above copyright
00013  *       notice, this list of conditions and the following disclaimer in the
00014  *       documentation and/or other materials provided with the distribution.
00015  *     * Neither the name of the <organization> nor the
00016  *       names of its contributors may be used to endorse or promote products
00017  *       derived from this software without specific prior written permission.
00018  *
00019  * THIS SOFTWARE IS PROVIDED BY THOMAS A. VAUGHAN ''AS IS'' AND ANY
00020  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
00021  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00022  * DISCLAIMED. IN NO EVENT SHALL THOMAS A. VAUGHAN BE LIABLE FOR ANY
00023  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
00024  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00025  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
00026  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
00027  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00028  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00029  *
00030  *
00031  * This "library" (my own glut library) is just a thin shell on top of the
00032  * actual freeglut libraries.  This is here only to make it easy for other
00033  * programs that use glut to find headers, link correctly, etc.
00034  */
00035 
00036 #ifndef WAVE_GLUT_GLUT_H__
00037 #define WAVE_GLUT_GLUT_H__
00038 
00039 
00040 // includes --------------------------------------------------------------------
00041 #include "color/color.h"
00042 #include "geometry/geometry_3d.h"
00043 #include "geometry/matrix_4.h"
00044 #include "threadsafe/smart_ptr.h"
00045 
00046 #include "GL/glew.h"
00047 #include "GL/glxew.h"
00048 #include "GL/freeglut.h"
00049 
00050 
00051 namespace glut {
00052 
00053 
00054 ////////////////////////////////////////////////////////////////////////////////
00055 ///
00056 /// \ingroup wave_glut
00057 /// \defgroup glut Wavepacket Glut Library Wrapper
00058 ///
00059 /// \n
00060 /// Mostly this library
00061 /// is here only as a convenient placeholder.  Code with
00062 /// glut dependencies can refer to this module in the build, and then the
00063 /// right directories will be searched for include files, the right libraries
00064 /// linked, etc.
00065 ///
00066 /// This library does provide a few helper objects and methods to make using
00067 /// glut easier, and to abstract away common setup code.
00068 ///
00069 ////////////////////////////////////////////////////////////////////////////////
00070 /*@{*/
00071 
00072 
00073 /// base floating point color object
00074 struct fcolor_t {
00075         // constructor, manipulators
00076         fcolor_t(void) throw() { this->clear(); }
00077         void clear(void) throw() {
00078                         red = green = blue = 0.0;
00079                         alpha = 1.0;
00080                 }
00081         bool isValid(void) const throw() {
00082                         return (red >= 0.0 && red <= 1.0 &&
00083                                 green >= 0.0 && green <= 1.0 &&
00084                                 blue >= 0.0 && blue <= 1.0 &&
00085                                 alpha >= 0.0 && alpha <= 1.0);
00086                 }
00087         operator float * (void) throw() {
00088                         return &red;
00089                 }
00090         operator const float * (void) const throw() {
00091                         return &red;
00092                 }
00093 
00094         // data fields
00095         float           red;
00096         float           green;
00097         float           blue;
00098         float           alpha;
00099 };
00100 
00101 
00102 
00103 /// If a client wants to use this library's glut helper entry point, it needs
00104 /// to supply an object that supports this interface.
00105 class Host {
00106 public:
00107         // public typedefs -----------------------------------------------------
00108         enum eBehavior {
00109                 eContinue       = 1,    ///< continue in glut loop
00110                 eExit           = 2,    ///< exit program immediately
00111 
00112                 // must be last!
00113                 eInvalid        = 0
00114         };
00115 
00116         // virtual destructor --------------------------------------------------
00117         virtual ~Host(void) throw();
00118 
00119         // glut::Host class interface methods ----------------------------------
00120 
00121         /// Called once, at initialization (just before main glut loop)
00122         virtual void init(void) { }
00123 
00124         /// Called on every glut idle event.
00125         virtual eBehavior tick(void) { return eContinue; }
00126 
00127         /// Called for every display frame.
00128         virtual void display(IN int w, IN int h) { }
00129 
00130         /// Called on mouse motion (see glutPassiveMotionFunc()).
00131         virtual eBehavior mouseMove(IN int x, IN int y) { return eContinue; }
00132 
00133         /// Called on mouse button events (see glutMouseFunc()).
00134         virtual eBehavior mouseButton(IN int button, IN int state,
00135                                 IN int x, IN int y)
00136                                 { return eContinue; }
00137 
00138         /// Called on keyboard events.
00139         virtual eBehavior keyboard(IN int key, IN int mods)
00140                                 { return eContinue; }
00141 
00142         /// Called when a special key is pressed (see glutSpecialFunc())
00143         virtual eBehavior specialKey(IN int key, IN int mods)
00144                                 { return eContinue; }
00145 
00146         /// Called only once, at glut shutdown.  Host can provide program
00147         ///     return value (typically zero if no errors).
00148         virtual int shutdown(void) { return 0; }
00149 };
00150 
00151 
00152 
00153 /// clients can call this to get common glut setup
00154 void start(IN int argc,
00155                         IN const char * argv[],
00156                         IN int width,           ///< window width, pixels
00157                         IN int height,          ///< window height, pixels
00158                         IN const char * title,  ///< window title
00159                         IN const char * gameModeString, ///< optional
00160                         IN smart_ptr<Host>& host);
00161 
00162 
00163 
00164 /// \ingroup glut
00165 /// \defgroup glut_threading Wavepacket OpenGL Threading
00166 ///
00167 /// \n
00168 /// Threading in OpenGL is non-trivial!  Just do some internet searches for
00169 /// "OpenGL multithreading context" and you'll see what I mean.
00170 ///
00171 /// \n
00172 /// In general, OpenGL isn't easy to use in a multithreaded way.  It can be
00173 /// done, but for most purposes, diving into OpenGL contexts is probably overkill.
00174 /// However, by default OpenGL isn't thread-friendly, so some sort of
00175 /// synchronization is required.
00176 ///
00177 /// \n
00178 /// This library uses multithreading in OpenGL in a very basic way: a single thread
00179 /// is doing all of the rendering, but background threads occasionally kick in
00180 /// and need to load and set up textures, etc.
00181 ///
00182 /// When a thread needs to do some open-GL specific work (that is, any time
00183 /// it needs to call OpenGL or glut APIs!) it should request that as a task.
00184 /// If the calling thread is not the OpenGL thread, the call (requestTask())
00185 /// will block until the OpenGL thread gets to it.  If the thread is the
00186 /// OpenGL thread, then the task executes right away.
00187 /*@{*/
00188 
00189 
00190 /// Create one of these (you'll have to inherit) if you have openGL work you
00191 /// need to submit to requestTask().
00192 class Task {
00193 public:
00194         // virtual destructor --------------------------------------------------
00195         virtual ~Task(void) throw();
00196 
00197         // glut::Task class interface methods ----------------------------------
00198 
00199         /// here is where the implementer can do any OpenGL-specific work
00200         virtual void doTask(void) = 0;
00201 };
00202 
00203 
00204 
00205 /// Here a thread can request that a task be handled by the open GL thread.
00206 /// Blocks until task is completed!  If task throws an exception, the
00207 /// exception will also be thrown back to the caller.
00208 void requestTask(IO Task * task);
00209 
00210 
00211 /// draw the outline of a 3D rectangle
00212 void drawRectLines(IN const rect3d_t& r,
00213                                 IN const glut_color_t& c) throw();
00214 
00215 /// get a 4x4 matrix from the given OpenGL matrix
00216 void getModelViewMatrix(OUT matrix4_t& T) throw();
00217 
00218 
00219 };      // glut namespace
00220 
00221 
00222 #endif  //WAVE_GLUT_GLUT_H__
00223