ruby-opengl 0.50.0 → 0.60.0

data/doc/history.txt

@@ -60,3 +60,7 @@ of unit tests, creating near-complete support for OpenGL 2.1.
 Support for MS Windows was also added during this time.
 
 Version 0.40 was released in July 2007.
+
+Version 0.50 was released in October 2007.
+
+Version 0.60 was released in December 2007.

data/doc/roadmap.txt

@@ -1,21 +1,19 @@
 Roadmap
 =======
 
-* Add ARB and other core OpenGL extensions
-* Write better getting started tutorial
 * Write comprehensive API documentation
 * Create more example code
+* Add RMagick(ImageMagick) integration for easy image handling (textures,screenshots)
 * Support all pixelstore modes (currently forced to default values by
   any function getting/setting data affected by it)
-* Add direct mapping on ruby types for vertex arrays, buffers and image data to allow
-  high performance data operations from within ruby (currently data has to be converted to/from string when being passed to OpenGL and so does not allow fast in-place modifications)
-	- this should be modeled after Perl's OpenGL::Array
 
 Possible Features
 ========
 * Add **all** OpenGL extensions (some are obsolete or not really used or useful at all)
+* Add direct mapping on ruby types for vertex arrays, buffers and image data to allow high performance data operations from within ruby
+	- this should be modeled after Perl's OpenGL::Array
+	- Update: preliminary tests shows that performance-wise there is no need for it, as the Ruby interpreter overhead is currently larger than immediate-mode calls overhead, so any potential speed gains are in domain of 1-5%. It still may be good idea from usability perspective, although that would require more comprehensive design, not just simple wrapper.
 * Support for r/w VBO buffer mapping - gl(Un)MapBuffer (is it needed?)
-* Add image handling wrapper for easy image handling (textures,screenshots) using RMagick (ImageMagick) - this may not be needed as API as using RMagick to do this stuff is trivial, maybe writing usage guide as part of tutorial is better alternative
 
 <br/>
 <br/>

data/doc/scientific_use.txt

@@ -26,3 +26,10 @@ Links
 * <http://narray.rubyforge.org/> -- Numerical n-dimensional Array class.
 * <http://www.kitp.ucsb.edu/~paxton/tioga.html> -- Tioga. Create plots using
   Ruby and TeX.
+
+<br/>
+<br/>
+<br/>
+<br/>
+<br/>
+<br/>

data/doc/supplies/page_template.html

@@ -24,10 +24,11 @@
 	</ul>
 	
 	<div id="sidebar">
+    <img src="./images/ogl.jpg">
 		<h3>Contact</h3>
 		<ul>
 			<li><a href="http://rubyforge.org/mail/?group_id=2103">Mailing list</a></li>
-			<li><a href="http://rubyforge.org/tracker/?atid=8185&group_id=2103&func=browse">Bug tracker</a></li>
+			<li><a href="http://rubyforge.org/tracker/?atid=8185&amp;group_id=2103&amp;func=browse">Bug tracker</a></li>
 			<li><a href="http://rubyforge.org/projects/ruby-opengl">Project page</a></li>
 		</ul>
 		<h3>Download</h3>

data/doc/thanks.txt

@@ -22,3 +22,8 @@ Aside from big thank-you's to the core devs, special thanks also goes to:
 <br/>
 <br/>
 <br/>
+<br/>
+<br/>
+<br/>
+<br/>
+<br/>

data/doc/tutorial.txt

@@ -1,105 +1,456 @@
-Usage tutorial
+Usage Tutorial
 ==============
+This page should serve as tutorial and also as reference to Ruby bindings for OpenGL
+language. It is assumed that you have basic understanding of both OpenGL and Ruby.
 
-Naming conventions
-------------------
-
-There are two ways to use ruby-opengl. Firstly, you can use customary
-C-style method names and constant names like so:
-
-    {{ruby}}
-    require 'gl'
-    require 'glu'
-    require 'glut'
-    
-    include Gl
-    include Glu
-    include Glut
+If you are new to OpenGL, you can start by visiting [OpenGL homepage](http://www.opengl.org)
+, reading the [OpenGL Programming Guide](http://opengl.org/documentation/books/#the_opengl_programming_guide_the_official_guide_to_learning_opengl_version) (also known as Red Book) or going to [NeHe's tutorials page](http://nehe.gamedev.net/).
 
-    glFooBar( GL_FOO_BAR )
-    gluFooBar( GLU_FOO_BAR )
-    glutFooBar( GLUT_FOO_BAR )
+If you are new to Ruby, [the ruby-lang website](http://www.ruby-lang.org/en/documentation/) contains lots of
+documentation and manuals for Ruby.
 
-You don't have to `include` Gl, Glu, and Glut, but if you don't, then
-you'll have to prefix each of those method and constant names like so:
-
-    {{ruby}}
-    require 'gl'
-    require 'glu'
-    require 'glut'
+Table of Contents
+==============
+Basics:
+* [Naming Conventions](#naming_conventions)<br/>
+* [Function parameters](#function_parameters)<br/>
+* [Return values](#return_values)<br/>
+* [Matrices](#matrices)<br/>
+* [Textures and other raw data](#textures)<br/>
+* [Error Checking](#error_checking)<br/>
+* [Examples](#examples)<br/>
+
+Advanced stuff:
+* [OpenGL version and Extensions](#extensions)<br/>
+* [Selection and Feedback queries](#selection_feedback)<br/>
+* [Vertex Arrays](#vertex_arrays)<br/>
+* [Buffer Objects](#buffer_objects)<br/>
+* [GLUT, SDL, GLFW..](#glut_sdl)<br/>
+* [GLUT callbacks](#glut_callbacks)<br/>
+* [Internals](#internals)<br/>
+
+API reference:
+* TODO
+
+<a name="naming_conventions"></a>
+Naming conventions
+------------------
 
-    Gl.glFooBar( Gl::GL_FOO_BAR )
-    Glu.gluFooBar( Glu::GLU_FOO_BAR )
-    Glut.glutFooBar( Glut::GLUT_FOO_BAR )
+The bindings contains three modules:
+* 'Gl' - OpenGL functions itself
+* 'Glu' - OpenGL Utility Library API - higher-level drawing routines, NURBS etc.
+* 'Glut' - OpenGL Utility Toolkit - low level functions such as creating OpenGL
+  context, opening window or handling user input
+
+You can import all three modules by calling
+
+	{{ruby}}
+	require 'opengl'
+
+You can also load the modules separately by using:
+
+	{{ruby}}
+	require 'gl'
+	require 'glu'
+	require 'glut'
+
+The functions and constants are named the same as their C counterparts:
+
+	{{ruby}}
+	require 'opengl'
+	...
+	Gl.glFooBar( Gl::GL_FOO_BAR )
+	Glu.gluFooBar( Glu::GLU_FOO_BAR )
+	Glut.glutFooBar( Glut::GLUT_FOO_BAR )
+
+This is the 'full' syntax, usefull when you are expecting name clashes
+with other modules, or just want to be formal ;) More often, you will
+want to use the 'C-style' syntax, which you can accomplish by using 'include'
+to export the module functions and constants to global namespace:
+
+	{{ruby}}
+	require 'opengl'
+	include Gl,Glu,Glut
+	...
+	glFooBar( GL_FOO_BAR )
+	gluFooBar( GLU_FOO_BAR )
+	glutFooBar( GLUT_FOO_BAR )
+
+Finally, you can use the 'old' syntax:
+
+	{{ruby}}
+	require 'opengl'
+	...
+	# Note the missing prefixes in functions and constants
+	# and also capitalization of module names
+	GL.FooBar( GL::FOO_BAR )
+	GLU.FooBar( GLU::FOO_BAR )
+	GLUT.FooBar( GLUT::FOO_BAR )
+
+This syntax was used by previous ruby-opengl versions; some people also
+consider it as being more in the spirit of OO programming. It has one
+downside though - due to Ruby's naming scheme, you cannot use constants
+which begins with number, e.g. GL_2D would under this syntax be (GL::)2D
+which is illegal.
+
+All three variants of syntax will continue to be supported in future,
+so it's up to you which one you choose to use.
+
+The rest of this tutorial will use the C syntax.
+
+Calling syntax
+--------------
+<a name="function_parameters"></a>
+Function parameters
+--------------
+For most types the ruby syntax follows the C API. If needed, ruby will do
+automatic parameter conversion to required type if possible. Example:
+
+	{{ruby}}
+	glVertex3f( 1.0, 1.0, 1.0 )  # matches C syntax
+	glVertex3f( 1, 1, 1 )        # equivalent to the above
+	glVertex3f( "string", 1, 1 ) # raises TypeError exception
+		
+Arrays are passed/received as Ruby arrays:
+
+	{{ruby}}
+	vertex = [ 1, 1, 1 ]
+	glVertex3fv( vertex )
+
+For functions with multiple parameter-number variations (glVertex,glColor,...)
+we define 'overloaded' functions, as in:
+
+	{{ruby}}
+	glVertexf( 1, 1 )       # will call glVertex2f()
+	glVertexf( 1, 1, 1 )    # will call glVertex3f()
+	glVertexf( 1, 1, 1, 1 ) # will call glVertex4f()
+	glVertexi( 1, 1 )       # will call glVertex2i()
+	...
+	# and so on
+
+<a name="return_values"></a>
+Return values
+-------------
+In C, OpenGL functions rarely return values directly, instead you pass in pointer to
+preallocated buffer and they will fill it with values; sometimes you have to even query
+how big buffer you'll need to allocate. Ruby does this all for you, returning either single
+value or array:
+
+	{{ruby}}
+	glColor4f( 1.0, 1.0, 1.0, 1.0 )
+	...
+	color =	glGetDoublev(GL_CURRENT_COLOR)
+	p color # will be [1.0,1.0,1.0,1.0]
+
+<a name="matrices"></a>
+Matrices
+-------------
+Matrices are passed and received as ruby array, or as ruby Matrix objects:
+
+	{{ruby}}
+	matrix_a = [0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15]
+	matrix_b = [ [  0, 1, 2, 3 ],
+	             [  4, 5, 6, 7 ],
+	             [  8, 9,10,11 ],
+	             [ 12,13,14,15 ] ]
+	matrix_c = Matrix.rows( [ [  0, 1, 2, 3 ],
+	                          [  4, 5, 6, 7 ],
+	                          [  8, 9,10,11 ],
+	                          [ 12,13,14,15 ] ] )
+	...
+	glLoadMatrixf(matrix_a)
+	glLoadMatrixf(matrix_b) 
+	glLoadMatrixf(matrix_c) # same result
+
+You may also create your own matrix class and pass it this way, provided that it
+is convertible to array (has 'to_a' method).
+
+Note that as OpenGL uses column-major
+notation for matrices, you may need to call transpose() when working with
+row-major matrices or arrays in ruby.
+
+<a name="textures"></a>
+Textures and other raw data
+-------------
+Data for textures, arrays, buffers etc. can be specified either as ruby arrays or directly as raw packed strings -
+strings that contains their direct memory representation (just like C arrays). If you need to convert between
+ruby arrays and these strings, use ruby Array#pack() and String#unpack() functions.
+Example:
+
+	{{ruby}}
+	# create texture, 2x2 pixels,
+	# 3 components (R,G,B) for each pixel as floats
+	texture = [
+	           1.0, 0.0, 0.0, # 1st pixel, red
+	           0.0, 1.0, 0.0, # 2nd pixel, green
+	           0.0, 0.0, 1.0, # 3rd pixel, blue
+	           1.0, 1.0, 1.0  # 4th pixel, white
+	          ]
+	# convert it to string
+	# f = native float representation
+	# * = convert all values in the array the same way
+	data = texture.pack("f*")
+	...
+	glTexImage2D(
+	  GL_TEXTURE_2D, # target
+	  0,             # mipmap level,
+	  GL_RGB8,       # internal format
+	  2, 2,          # width, height
+	  0,             # border = no
+	  GL_RGB,        # components per each pixel
+	  GL_FLOAT,      # component type - floats
+	  data           # the packed data
+	)
+
+Reverse works just the same:
+
+	{{ruby}}
+	...
+	data = glGetTexImage( # returns the packed data as string
+	  GL_TEXTURE_2D, # target
+	  0,             # mipmap level
+	  GL_RGB,        # components per pixel
+	  GL_FLOAT       # component type
+	)
+	# now convert it to ruby array
+	texture = data.unpack("f*")
+	...
+
+For storage, packed strings are more memory efficient than ruby arrays, but
+cannot be easily changed or manipulated.
+
+<a name="error_checking"></a>
+Error Checking
+--------------
+Starting with version 0.60.0, ruby-opengl performs automatic checking of OpenGL and GLU errors.
+Functions:
+
+	{{ruby}}
+	Gl.enable_error_checking
+	Gl.disable_error_checking
+	Gl.is_error_checking_enabled? # true/false
+
+When the checking is enabled (default), glGetError() is executed after each OpenGL call, and should error
+occur, Gl::Error exception is raised:
+
+	{{ruby}}
+	Gl.enable_error_checking
+	...
+	begin 
+	  ...
+	  glEnable(GL_TRUE) # will raise exception
+	  ...
+	rescue Gl::Error => err
+		# err.id contains the OpenGL error ID
+		if (err.id == GL_INVALID_ENUM)
+			puts "Oh noes! You used invalid enum!"
+			...
+		end
+		...
+	end
+
+Some GLU functions may also throw Glu::Error - the handling is the same as above.
+
+It is usually good idea to leave error checking on for all your code, as OpenGL errors have habit to pop-up in
+unexpected places. For now there is no measurable performance hit for error checking, although this may depend
+on your graphic drivers implementation.
+
+<a name="examples"></a>
+The Examples
+-----------
 
-The other way you might use ruby-opengl is to employ the notation that
-users of previous versions of ruby-opengl have used:
+Various examples are in 'examples' directory of the bindings. To run them, manually pass them to `ruby` like:
 
-    {{ruby}}
-    require 'opengl'
-    
-    GL.FooBar( GL::FOO_BAR )
-    GLU.FooBar( GLU::FOO_BAR )
-    GLUT.FooBar( GLUT::FOO_BAR )
+    ruby some_sample.rb
 
-There are many fine OpenGL and GLUT tutorials all over the 'Net, so we
-don't plan on trying to duplicate them here at the moment. Most of
-these tutorials presume you are writing your code in C or C++, but
-they should still be almost directly usable with ruby-opengl as long
-as you use the C-style names (and, of course, as long as you change
-the rest of the C code you find from C (or C++) to Ruby). If you opt
-for using the legacy ruby-opengl style names, you'll have to take the
-additional step of converting the calls from `glFooBar( GL_FOO_BAR )`
-to `GL.FooBar( GL::FOO_BAR )`.
+On windows, you may want to use 'rubyw' instead, which displays the standard output window
+as some examples use the console for usage info etc.
 
-Personally, I prefer the current C-style names because:
+If you get 'opengl not found' error, and you installed ruby-opengl from gems, your
+shell or ruby installation is probably not configured to use the gems; in that case type:
 
-1. It's somewhat easier to follow along with the many online tutorials
-   and written OpenGL/GLUT books (i.e. the RedBook, BlueBook, SuperBible,
-   etc.).
+    ruby -rubygems some_sample.rb
 
-2. Copying/pasting code between Ruby and C is easier (otherwise you'll
-   be doing a lot of search/replace).
+The `README` file in the `examples` directory contains some notes on the examples.
 
-3. My fingers are already used to typing the traditional C-style names
-   of all these identifiers.
+<a name="extensions"></a>
+OpenGL Version and Extensions 
+-----------
+To query for available OpenGL version or OpenGL extension, use Gl.is_available? function:
+
+	{{ruby}}
+	# true if OpenGL version is 2.0 or later is available
+	Gl.is_available?(2.0)
+	...
+	# returns true if GL_ARB_shadow is available on this system
+	Gl.is_available?("GL_ARB_shadow")
+	
+For list of what extensions are supported in ruby-opengl see this [page](extensions.html)
+
+The extensions' function names once again follows the C API. Some extensions were over time
+promoted to ARB or even to OpenGL core, retaining their function names just with suffix changed
+or removed. However sometimes the functions semantics was changed in the process, so to avoid
+confusion, ruby-opengl bindings will strictly adhere to the C naming, e.g. :
+
+	{{ruby}}
+	# will call the function from GL_ARB_transpose_matrix extension
+	glLoadTransposeMatrixfARB(matrix)
+	...
+	# will call the function from OpenGL 1.3
+	glLoadTransposeMatrixf(matrix)
+
+<b>Note:</b> ruby-opengl is compiled against OpenGL 1.1, and all functions and enums from later
+versions of OpenGL and from extensions are loaded dynamically at runtime. That means that all
+of OpenGL 2.1 and supported extensions are available even if the ruby-opengl bindings are
+compiled on platform which lacks proper libraries or headers (like for example Windows without
+installed graphic drivers). This should ease binary-only distribution and application packaging.
+
+
+<a name="selection_feedback"></a>
+Selection/Feedback queries
+-----------
+Querying selection and feedback is different from C. Example:
+
+	{{ruby}}
+	# this will create selection buffer 512*sizeof(GLuint) long
+	buf = glselectbuffer(512)
+	# enter feedback mode
+	glRenderMode(GL_SELECT) 
+	... # draw something here	
+	# return to render mode
+	count = glRenderMode(GL_RENDER)
+	# at this point the buf string is freezed and contains
+	# the selection data, which you can recover with unpack
+	# function
+	data = buf.unpack("I*") # I for unsigned integer
+	# also, next call to glRenderMode(GL_SELECT) will overwrite
+	# the 'buf' buffer with new data
+
+The feedback query follows the same pattern, only the data are stored
+as floats.
+
+<a name="vertex_arrays"></a>
+Vertex Arrays
+-----------
+In current state, vertex arrays are not very efficient in ruby-opengl, as it is not possible to change
+the array content once it is specified, and there is overhead for converting between ruby and C representation
+of numbers. Using display lists for static and immediate mode for dynamic objects is recommended instead.
 
-Also, I don't like the fact that, if you use the previous ruby-opengl
-style, you've got method names starting with a capital letter (which is
-not customary Ruby style).
+You can specify the data the same way as [texture data](#textures). Example:
 
-For the rest of this document, I'll use the current C-style names.
+	{{ruby}}
+	normals = [0,1,0, 1,0,0, 1,1,1]
+	glNormalPointer(GL_FLOAT,0,normals)
+	...
+	glEnable(GL_NORMAL_ARRAY)
+	glDrawArrays(...)
+	...
 
+This applies to all *pointer functions. glGetPointerv will return reference to the frozen string
+previously specified.
 
+<a name="buffer_objects"></a>
+Buffer Objects
+-----------
+Once again, in current state buffer objects (VBOs in particular) are not very efficient in ruby-opengl.
+Unlike textures and vertex arrays, the data for buffers *must* be prepacked by using .pack() function,
+as buffers does not retain information about the storage type. Mapping of the buffer afterwards is read-only. 
+
+Like in C, buffer binding affects some functions in way that if particular buffer is bound, the related
+functions (for example glTexImage) take integer offset in place of data string argument. This is also true
+for getter functions (e.g. glGetTexImage) - instead of returning the data string, they take offset as they're
+last argument (so in ruby they take one extra argument), and will write the data in the bound buffer as expected.
+
+VBO example:
+
+	{{ruby}}
+	# specify 3 vertices, 2*float each
+	data = [0,0, 0,1, 1,1].pack("f*")
+	...
+	# generate buffer name
+	buffers = glGenBuffers(1)
+	# bind to the name to ARRAY buffer for vertex array
+	glBindBuffer(GL_ARRAY_BUFFER,buffers[0])
+	# here the data is specified, size is n*sizeof(float)
+	# note that you don't get to specify type, as buffers
+	# operate on byte level
+	glBufferData(GL_ARRAY_BUFFER,6*4,data,GL_DYNAMIC_DRAW)
+	...
+	# here instead of specyfing the data, you pass '0' (or
+	# positive integer) as offset to the bound buffer
+	glVertexPointer(2,GL_FLOAT,0,0)
+	...
+	glEnableClientState(GL_VERTEX_ARRAY)
+	...
+
+<a name="glut_sdl"></a>
+GLUT, SDL, GLFW..
+---------
+When it comes to low-level task like GL window creation, input and event handling, the first choice is GLUT,
+as it is readilly available alongside OpenGL. However both GLUT itself and its implementations
+have their drawbacks, and for that and other reasons there are number of replacement libraries.
+You can use any of them with ruby-opengl (as long as there are ruby bindings for them).
+
+Here is example for [SDL](http://www.kmc.gr.jp/~ohai/index.en.html):
+
+	{{ruby}}
+	require 'opengl'
+	require 'sdl'
+	# init
+	SDL.init(SDL::INIT_VIDEO)
+	SDL.setGLAttr(SDL::GL_DOUBLEBUFFER,1)
+	SDL.setVideoMode(512,512,32,SDL::OPENGL)
+	...
+	Gl.glVertex3f(1.0,0.0,0.0)
+	...
+	SDL.GLSwapBuffers()
+	...
+
+and another example for [GLFW](http://ruby-glfw.rubyforge.org/):
+
+	{{ruby}}
+	require 'opengl'
+	require 'glfw'
+	# init
+	Glfw.glfwOpenWindow( 500,500, 0,0,0,0, 32,0, Glfw::GLFW_WINDOW )
+	...
+	Gl.glVertex3f(1.0,0.0,0.0)
+	...
+	Glfw.glfwSwapBuffers()
+	...
+
+<a name="glut_callbacks"></a>
 GLUT callbacks
 --------------
 
-The major difference from your GL code in C is in how glut callbacks are
-handled. Rather than define your callbacks as top-level functions,
-with ruby-opengl, it's done (for example) like so:
+The GLUT callback functions are specified as Proc objects, which you can
+either create with lambda as:
 
-    {{ruby}}
-    reshape = lambda do |w, h|
-        glViewport( ... )
-        glMatrixMode( GL_PROJECTION )
-        # etc.
-        glMatrixMode( GL_MODELVIEW )
-        glLoadIdentity
-    end
+	{{ruby}}
+	reshape = lambda do |w, h|
+	  ...
+	end
+	...
+	glutReshapeFunc( reshape )
 
-    # ...
-    
-    glutReshapeFunc( reshape )
+or by conversion from normal functions:
 
-An older notation you'll see instead of `lambda` is `proc`. The PickAxe
-v2 notes that `proc` is "mildly deprecated" in favor of `lambda`. You'll
-also sometimes see `Proc.new` used in place of either. Pages 359-360 of
+	{{ruby}}
+	def reshape(w,h)
+	  ...
+	end
+	...
+	glutReshapeFunc( method("reshape").to_proc )
+    
+Note: An older notation you'll see instead of `lambda` is `proc`. The
+PickAxe v2 notes that `proc` is "mildly deprecated" in favor of `lambda`.
+You'll also sometimes see `Proc.new` used in place of either. Pages 359-360 of
 PickAxe v2 describe the differences between using `lambda` and `Proc.new`,
 but for our purposes either will be fine.
 
-
-Source code layout
-------------------
+<a name="internals"></a>
+Internals
+---------
 
 The directory structure follows current Ruby standards, with a few
 extra directories added.
@@ -111,49 +462,8 @@ extra directories added.
   modules (gl, glu, glut). Herein are the files needed to compile the extension
   modules.
 * `lib/` -- Files that the user is meant to `require` in their own code.
-* `test/` -- Contains sample ruby files that make OpenGL and GLUT calls.
-* `utils` -- Some under-construction utility scripts used to help generate
-  extension module source from GL header files. Also contains some scripts
-  used to generate the ruby-opengl website.
+* `test/` -- Contains automatic testsuite for the bindings
+* `utils` -- Some utility scripts used to help generate code, documentation
+  and website.
 * `website` -- After running `rake gen_website` this directory will contain
   the ruby-opengl website.
-
-
-The Samples
------------
-
-To run the samples, manually pass them to `ruby` like so:
-
-    ruby some_sample.rb
-    ruby some_sample_prev.rb
-
-The names ending in `_prev.rb` have been "ported" to use the legacy method
-and constant names (and possibly have been neatened up a bit as well). The
-`README` file in the `samples` directory contains some notes on the samples.
-
-
-Mac OS X notes
---------------
-
-James Adam passed along some fixes to ruby-opengl in 2005 on ruby-talk.
-Some methods have been incorporated into ruby-opengl-0.33. Paraphrasing
-James a bit, he writes:
-
-> 1. `CheckLoop` was added to bring the GLUT module in line with the
->    same function in Apple's GLUT. GLUT's MainLoop is blocking and forces
->    you to perform additoinal processing using GLUT's IdleFunc system,
->    which can sometimes be very undesirable (particularly if you are using
->    Ruby as the glue between two libraries which both feature this type of
->    loop). CheckLoop allows you to cycle through a *single* GLUT processing
->    loop, and then returns control to the calling thread/process. Thus, by
->    periodically calling CheckLoop, you can get the scene to update without
->    having GLUT seize control of the whole application.
-> 
-> 2. `GameModeString(mode_string)` and `Glut.EnterGameMode()`. May allow you
->    to switch your application to fullscreen.
-> 
-> 3. `BitmapCharacterX(char)` for displaying characters, since there seems to
->    be a problem with the default `GLUT.BitmapCharacter` method.
-
-Any feedback on testing of these methods is welcome, and will likely
-be incorporated into the ruby-opengl docs.