ruby-opengl 0.33.0

data/Rakefile

@@ -0,0 +1,129 @@
+#-*-ruby-*-
+#
+# Copyright (C) 2006 John M. Gabriele <jmg3000@gmail.com>
+#
+# This program is distributed under the terms of the MIT license.
+# See the included MIT-LICENSE file for the terms of this license.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+# OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+# IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+# CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+# TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+# This Rakefile currently only deals with generating docs and uploading
+# the web site. The actual modules are build using mkrf and, for now,
+# the top-level build.sh script.
+
+#====================================================================
+# Generate html docs from the markdown source and upload to the site.
+# All doc files that are destined for the website have filenames that
+# end in .txt.
+
+begin
+    require 'rubygems'
+rescue LoadError
+    nil
+end
+
+require 'rake'
+require 'rake/clean'
+require 'rake/gempackagetask'
+require 'mkrf/rakehelper'
+
+WEBSITE_MKDN = FileList['./doc/*.txt'] << 'README.txt'
+NICE_HTML_DOCS = WEBSITE_MKDN.ext('html')
+
+CLEAN.include("ext/gl*/Rakefile", "ext/*/mkrf.log", "ext/*/*.so", 
+              "lib/*.so", "ext/*/*.o", "pkg")
+CLOBBER.include("*.plain", "doc/*.plain", "doc/*.snip", "*.html",
+                "doc/*.html", "website/*.html")
+
+setup_extension('gl', 'gl')
+setup_extension('glu', 'glu')
+setup_extension('glut', 'glut')
+
+desc 'Does a full compile'
+task :default => [:build_rbogl, :gl, :glu, :glut]
+
+task :extension => :default
+
+desc 'Builds common OpenGL object file.  Necessary for building GL bindings'
+task :build_rbogl do
+    puts "Building common rbogl object file"
+    sh "cd ext/common && rake"
+end
+
+desc 'Show contents of some variables related to website doc generation.'
+task :explain_website do
+    puts "WEBSITE_MKDN:"
+    WEBSITE_MKDN.each do |doc|
+        puts "\t#{doc}"
+    end
+    puts "NICE_HTML_DOCS:"
+    NICE_HTML_DOCS.each do |doc|
+        puts "\t#{doc}"
+    end
+end
+
+desc 'Generate website html.'
+task :gen_website => NICE_HTML_DOCS do
+    # Now that the website docs have been generated, copy them to ./website.
+    puts
+    sh "cp README.html website/index.html"
+    sh "cp doc/*.html website"
+end
+
+# You'll see some intermediate .plain files get generated. These are html,
+# but don't yet have their code snippets syntax highlighted.
+rule '.html' => '.plain' do |t|
+    puts "Turning #{t.source} into #{t.name} ..."
+    sh "./utils/post-mkdn2html.rb #{t.source} #{t.name}"
+end
+
+# Process the markdown docs into plain html.
+rule '.plain' => '.txt' do |t|
+    puts
+    puts "Turning #{t.source} into #{t.name} ..."
+    sh "./utils/mkdn2html.rb #{t.source} #{t.name}"
+end
+
+desc 'Upload the newly-built site to RubyForge.'
+task :upload_website => [:gen_website] do
+    sh "scp website/*.html hoanga@rubyforge.org:/var/www/gforge-projects/ruby-opengl"
+end
+
+desc 'Upload entire site, including stylesheet and the images directory.'
+task :upload_entire_website => [:gen_website] do
+    sh "scp website/*.html hoanga@rubyforge.org:/var/www/gforge-projects/ruby-opengl"
+    sh "scp website/*.css hoanga@rubyforge.org:/var/www/gforge-projects/ruby-opengl"
+    sh "scp -r website/images hoanga@rubyforge.org:/var/www/gforge-projects/ruby-opengl"
+end
+
+# Define the files that will go into the gem
+gem_files = FileList["{lib,ext,doc,examples,test}/**/*"]
+gem_files = gem_files.exclude("**/*.so", "**/*.o", "ext/**/*.log", "ext/gl*/Rakefile")
+
+spec = Gem::Specification.new do |s|
+    s.name              = "ruby-opengl"
+    s.version           = "0.33.0"
+    s.authors           = [ "John Gabriele", "Minh Thu Vo" ]
+    s.homepage          = "http://opengl-ruby.rubyforge.org"
+    s.platform          = Gem::Platform::RUBY
+    s.summary           = "OpenGL Interface for Ruby"
+    s.files             = gem_files
+    s.extensions        << 'Rakefile'
+#    s.extensions        << 'ext/common/Rakefile', 'ext/gl/mkrf_conf.rb', 
+#                           'ext/glu/mkrf_conf.rb', 'ext/glut/mkrf_conf.rb']
+    s.require_path      = "lib"
+    s.autorequire       = "gl"
+    s.has_rdoc          = false
+    s.add_dependency("mkrf", ">=0.2.0")
+end
+
+# Create a task for creating a ruby gem
+Rake::GemPackageTask.new(spec) do |pkg|
+    pkg.need_tar = true
+end

data/doc/build_install.txt

@@ -0,0 +1,53 @@
+Building ruby-opengl
+====================
+
+
+Pre-requisites
+--------------
+
+On Ubuntu, aside from Ruby and the Rake gem, you'll need the following
+packages:
+
+* `libgl1-mesa libgl1-mesa-dri libglu1-mesa freeglut3`
+* `libgl1-mesa-dev libglu1-mesa-dev freeglut3-dev`
+
+
+Build instructions
+------------------
+
+The current build setup is still under construction. When last looked at
+(late November 2006), we were waiting for
+the next mkrf release (we've patched what they have in svn, so it works,
+but their maintainer seems to have moved on and not made a release
+containing our fix). Building our ruby-opengl works, but you'll need
+the version of mkrf still in svn.
+
+Once you have a mkrf in place, on unixy platforms, just run
+
+    ./build.sh
+
+to build.
+
+After building, the extension modules are automatically copied to the
+project's `./lib` directory.
+
+
+Installing
+----------
+
+For now, if you want to install ruby-opengl on your system, you can
+do so manually (there is no gem, nor even a release, for it yet).
+Just copy the contents of `./lib` into your
+`.../lib/ruby/site_ruby/1.8` directory (or anywhere else `ruby`
+searches for modules).
+
+
+Testing / Running
+-----------------
+
+To run a sample file:
+
+    $ cd examples
+    $ ruby plane.rb
+
+Hit ESC to exit.

data/doc/history.txt

@@ -0,0 +1,48 @@
+Project history
+===============
+
+The [original ruby-opengl](http://www2.giganet.net/~yoshi/) was written
+by Yoshi.
+
+John G. then wanted to clean it up and add some docs to it, and so started
+tweaking and put up a new site and made his changes available.
+
+Then Peter M. came along and decided to try updating ruby-opengl using SWIG,
+as it seemed easier than doing everything by hand. Peter wrote the new code,
+John started the actual RubyForge project, put up a new site, and Peter
+committed the code.
+
+Thu M. V. joined the project with a lot of energy, and the mailing list
+was showing a good bit of activity.
+
+After some experience, we began to question whether SWIG was necessary/helpful
+for a project of this nature.  The leaning was that people want to abandon
+SWIG and go back to maintaining the binding files by hand. Thu even provided
+a script to help with the manual coding that would be required without using
+SWIG.
+
+The reasoning at the time was:
+
+Pro-SWIG:
+
+* Could use the .i files for another project, perhaps (OTOH, we couldn't
+  use previous .i files on this project...)
+
+* It's supposed to require less manual coding.
+
+Con-SWIG:
+
+* yet another tool to learn
+
+* OpenGL isn't really all that big
+
+* OpenGL doesn't change a lot
+
+* A lot of boilerplate and overhead in the generated files because SWIG is
+  a general tool.
+
+
+In September 2006, we stopped using SWIG. Thu and Peter began fine tuning
+Thu's original `utils/mkwrap.rb` script.
+
+Development stalled in October 2006.

data/doc/requirements_and_design.txt

@@ -0,0 +1,131 @@
+Design
+======
+
+This document records the requirements, high-level design, and the
+specifications for the ruby-opengl project.
+
+The content of this document was gleaned from the postings on the
+ruby-opengl-dev list and internal notes from John G., Peter M., Vo Minh Thu,
+and Robert K.
+
+
+Requirements
+------------
+
+* ruby-opengl is a Ruby extension library which wraps the OpenGL, GLU,
+  and GLUT libraries.
+
+* ruby-opengl shall provide three base modules: *BaseGL*, *BaseGLU*, and
+  *BaseGLUT* (the "Base Modules").
+
+  Note: "BaseGL" etc. are not the names that appear in the code -- they are
+  just handles so we can write about them in documents like this one.
+
+* The Base Modules shall be separately loadable.
+
+* BaseGL shall not depend on any of the other Ruby modules.
+
+* BaseGLU shall depend on, at most, BaseGL.
+
+* BaseGLUT shall depend on, at most, BaseGLU and BaseGL.
+
+* Base Module syntax shall closely follow the standard C-syntax.
+
+  The syntax for a Ruby program that uses the base modules, shall closely
+  follow the standard C-like syntax that OpenGL programmers are used to,
+  and that most OpenGL examples are published in:
+
+        {{ruby}}
+        require 'gl'
+        Gl.glBegin( Gl::GL_POLYGON )
+          Gl.glVertex2d( 0, 0 )
+          Gl.glVertex2d( 0, 1 )
+          Gl.glVertex2d( 1, 1 )
+          Gl.glVertex2d( 1, 0 )
+        Gl.glEnd
+
+  Or:
+
+        {{ruby}}
+        require 'gl'
+        include Gl
+        glBegin( GL_POLYGON )
+          glVertex2d( 0, 0 )
+          glVertex2d( 0, 1 )
+          glVertex2d( 1, 1 )
+          glVertex2d( 1, 0 )
+        glEnd
+
+  The rationale for adopting the C-like syntax is:
+    * Makes it familiar to OpenGL programmers.
+    * Removes the burden of learning OpenGL plus some Ruby-isms, just to
+      get started.
+    * Makes it easier to port OpenGL programs to/from ruby-opengl.
+    * The current OpenGL documentation more naturally fits ruby-opengl.
+    * Putting "gl", "glu" and "glut" in front of all the names (i.e.,
+      following the C-like syntax) leaves common variable names open for
+      the programmers (e.g., "vertex", "color" etc. are popular topics in
+      3D programming, so not robbing the ruby namespace of such valuable
+      real-estate seems nice).
+
+
+* It shall be possible to check out the project from svn, compile and test
+  on the following platforms: Mac OS X, GNU/Linux. MS Windows operating
+  systems may also be supported in the future.
+
+* Provide backwards compatiblity for the older ruby-opengl function and
+  constant naming style (possibly in a layer built on top of the Base layers).
+  The support should be as minimally invasive as possible, perhaps via:
+  `require 'gl_prev'`, `require 'glu_prev'`, and `require 'glut_prev'`.
+
+* The project will make a number of pre-compiled extensions available as gems.
+
+* The project will supply source code and build scripts (via svn checkout)
+  conducive to straightforward porting to other platforms.
+
+* There shall be a test suite that exercises each call in each of the Base
+  modules.
+
+* There shall be tools supplied which can:
+
+    * generate source code from existing OpenGL/GLUT header files which,
+      probably with some fine-tuning, can be used to update the module.
+
+    * show differences in coverage between ruby-opengl and a given set
+      of OpenGL/GLUT header files.
+
+* All project documentation will be in Markdown format in files that end in
+  `.txt`.
+
+* The project will make some efforts to track versions of OpenGL.
+
+
+### Things in the future
+
+Once the base modules are implemented, there are several ideas on things to
+do next.  This list is not really requirements, but a list of nice ideas to
+try:
+
+* Provide wrappers for glBegin/glEnd, eg: polygon()...translates to
+  glBegin(GL_POLYGON)....glEnd
+
+* Untyped versions of the multi-typed gl functions:  e.g., a single
+  glVertex that examines its arguments and calls the appropriate
+  glVertex{234}{fisdv} call in BaseGL.
+
+
+
+Implementation
+--------------
+
+Our plan is to continue on with Yoshi's original code, modified
+to use standard OpenGL-style constant and function names.
+
+
+### Build environment ###
+
+The build environment will:
+
+* use rake and mkrf. (note -- development of mkrf seems to have
+  stalled)
+* minimize the number of additional tools required

data/doc/roadmap.txt

@@ -0,0 +1,19 @@
+Roadmap
+=======
+
+* Get BaseGL updated.
+* Get BaseGLU updated.
+* Get BaseGLUT updated.
+* Add the ESC keyboard handler to smooth.rb
+
+<br/>
+<br/>
+<br/>
+<br/>
+<br/>
+<br/>
+<br/>
+<br/>
+<br/>
+<br/>
+<br/>

data/doc/scientific_use.txt

@@ -0,0 +1,28 @@
+Scientific Use
+--------------
+
+Though not directly related to ruby-opengl, this page contains a
+few tidbits of general info that might possibly be of interest to
+a number of users.
+
+There are currently two bindings to the [GNU Scientific Library][1] (GSL):
+
+* Yoshiki's Ruby/GSL (<http://rb-gsl.rubyforge.org/>) --
+  Comes with an API reference. Also, I've been told that the API has been
+  worked a bit to be more comfortable for Ruby programmers.
+* Arno's ruby-gsl (<http://ruby-gsl.sourceforge.net/>) --
+  more of a straight wrapper around the C API.
+
+[1]: http://www.gnu.org/software/gsl/
+
+<a href="http://rubyforge.org/softwaremap/trove_list.php?form_cat=97">Browse Rubyforge</a>
+for more.
+
+
+Links
+-----
+
+* <http://sciruby.codeforpeople.com/sr.cgi/FrontPage> -- SciRuby wiki.
+* <http://narray.rubyforge.org/> -- Numerical n-dimensional Array class.
+* <http://www.kitp.ucsb.edu/~paxton/tioga.html> -- Tioga. Create plots using
+  Ruby and TeX.

data/doc/supplies/page_template.html

@@ -0,0 +1,63 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
+<link type="text/css" media="screen" rel="stylesheet" href="style.css" />
+<title>ruby-opengl -- {{title}}</title>
+</head>
+
+<body>
+
+<div id="container">
+
+	<div id="header">
+		<em>ruby-opengl</em>
+	</div>
+
+	<ul id="tabnav">
+		<li><a href="./index.html">Home</a></li>
+		<li><a href="./tutorial.html">Tutorial</a></li>
+		<li><a href="./requirements_and_design.html">Req's doc</a></li>
+		<li><a href="./build_install.html">Build/Install</a></li>
+		<li><a href="./history.html">History</a></li>
+		<li><a href="./roadmap.html">Roadmap</a></li>
+	</ul>
+	
+	<div id="sidebar">
+		<h3>Contact</h3>
+		<ul>
+			<li><a href="http://rubyforge.org/mail/?group_id=2103">Mailing list</a></li>
+		</ul>
+
+        <h3>Other docs</h3>
+        <ul>
+            <li><a href="./thanks.html">Thanks</a></li>
+            <li><a href="./scientific_use.html">Scientific use</a></li>
+        </ul>
+
+		<h3>Links</h3>
+		<ul>
+			<li><a href="http://www.opengl.org/">OpenGL</a></li>
+			<li><a href="http://www.mesa3d.org/">Mesa</a></li>
+			<li><a href="http://freeglut.sourceforge.net/">freeglut</a></li>
+			<li><a href="http://rubyforge.org/projects/ruby-ftgl/">ruby-ftgl</a></li>
+			<li><a href="http://www.rubygarden.org/ruby?OpenGL">Ruby wiki GL page</a></li>
+			<li><a href="http://rubygame.seul.org/">RubyGame</a></li>
+		</ul>
+	</div>	
+	
+	<div id="content">
+
+    {{content}}
+
+	</div>
+	<div id="footer">
+	<p><a href="http://validator.w3.org/check?uri=referer">Valid XHTML 1.0</a> |
+    Copyright &copy; <a href="#">John M. Gabriele</a> |
+    Design by <a href="http://www.jdavidmacor.com">super j man</a></p>
+	</div>
+	
+</div>
+
+</body>
+</html>

data/doc/thanks.txt

@@ -0,0 +1,23 @@
+Thank you
+---------
+
+Aside from big thank-you's to the core devs, special thanks (alphabetical
+by first name) also goes to:
+
+* Bill Kelly -- provided some pilot code changing how users can call method and constant names.
+* Ilmari Heikkinen -- provided code for changing how users can call method and constant names.
+* James Adam -- Mac OS X fixes
+* Tony Hursh -- Mac OS X glut build tweak
+* **Yoshi** -- providing ruby-opengl-0.32g from which to work off of.
+
+
+<br/>
+<br/>
+<br/>
+<br/>
+<br/>
+<br/>
+<br/>
+<br/>
+<br/>
+<br/>

data/doc/tutorial.txt

@@ -0,0 +1,160 @@
+Usage tutorial
+==============
+
+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
+
+    glFooBar( GL_FOO_BAR )
+    gluFooBar( GLU_FOO_BAR )
+    glutFooBar( GLUT_FOO_BAR )
+
+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}}
+    Gl.glFooBar( Gl::GL_FOO_BAR )
+    Glu.gluFooBar( Glu::GLU_FOO_BAR )
+    Glut.glutFooBar( Glut::GLUT_FOO_BAR )
+
+The other way you might use ruby-opengl is to employ the notation that
+users of previous versions of ruby-opengl have used:
+
+    {{ruby}}
+    require 'gl_prev'
+    require 'glu_prev'
+    require 'glut_prev'
+    
+    GL.FooBar( GL::FOO_BAR )
+    GLU.FooBar( GLU::FOO_BAR )
+    GLUT.FooBar( GLUT::FOO_BAR )
+
+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 )`.
+
+Personally, I prefer the current C-style names because:
+
+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.).
+
+2. Copying/pasting code between Ruby and C is easier (otherwise you'll
+   be doing a lot of search/replace).
+
+3. My fingers are already used to typing the traditional C-style names
+   of all these identifiers.
+
+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).
+
+For the rest of this document, I'll use the current C-style names.
+
+
+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:
+
+    {{ruby}}
+    reshape = lambda do |w, h|
+        glViewport( ... )
+        glMatrixMode( GL_PROJECTION )
+        # etc.
+        glMatrixMode( GL_MODELVIEW )
+        glLoadIdentity
+    end
+
+    # ...
+    
+    glutReshapeFunc( reshape )
+
+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
+------------------
+
+The directory structure follows current Ruby standards, with a few
+extra directories added.
+
+* `doc/` -- Contains documentation for the project (from which this
+  website is generated).
+* `examples` -- Some small sample programs. Mostly, these are being
+  copied from Yoshi's examples while being updated and neatened up.
+* `experimental` -- Pure Ruby modules that are intended to make ruby-opengl
+  usage more "Rubyish". These may eventually become part of ruby-opengl proper.
+* `ext/` -- Contains subdirectories, one for each of the three extension
+  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.
+* `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.