ruby-opengl 0.33.0

Sign up to get free protection for your applications and to get access to all the features.
data/Rakefile ADDED
@@ -0,0 +1,129 @@
1
+ #-*-ruby-*-
2
+ #
3
+ # Copyright (C) 2006 John M. Gabriele <jmg3000@gmail.com>
4
+ #
5
+ # This program is distributed under the terms of the MIT license.
6
+ # See the included MIT-LICENSE file for the terms of this license.
7
+ #
8
+ # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
9
+ # OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
10
+ # MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
11
+ # IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
12
+ # CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
13
+ # TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
14
+ # SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
15
+
16
+ # This Rakefile currently only deals with generating docs and uploading
17
+ # the web site. The actual modules are build using mkrf and, for now,
18
+ # the top-level build.sh script.
19
+
20
+ #====================================================================
21
+ # Generate html docs from the markdown source and upload to the site.
22
+ # All doc files that are destined for the website have filenames that
23
+ # end in .txt.
24
+
25
+ begin
26
+ require 'rubygems'
27
+ rescue LoadError
28
+ nil
29
+ end
30
+
31
+ require 'rake'
32
+ require 'rake/clean'
33
+ require 'rake/gempackagetask'
34
+ require 'mkrf/rakehelper'
35
+
36
+ WEBSITE_MKDN = FileList['./doc/*.txt'] << 'README.txt'
37
+ NICE_HTML_DOCS = WEBSITE_MKDN.ext('html')
38
+
39
+ CLEAN.include("ext/gl*/Rakefile", "ext/*/mkrf.log", "ext/*/*.so",
40
+ "lib/*.so", "ext/*/*.o", "pkg")
41
+ CLOBBER.include("*.plain", "doc/*.plain", "doc/*.snip", "*.html",
42
+ "doc/*.html", "website/*.html")
43
+
44
+ setup_extension('gl', 'gl')
45
+ setup_extension('glu', 'glu')
46
+ setup_extension('glut', 'glut')
47
+
48
+ desc 'Does a full compile'
49
+ task :default => [:build_rbogl, :gl, :glu, :glut]
50
+
51
+ task :extension => :default
52
+
53
+ desc 'Builds common OpenGL object file. Necessary for building GL bindings'
54
+ task :build_rbogl do
55
+ puts "Building common rbogl object file"
56
+ sh "cd ext/common && rake"
57
+ end
58
+
59
+ desc 'Show contents of some variables related to website doc generation.'
60
+ task :explain_website do
61
+ puts "WEBSITE_MKDN:"
62
+ WEBSITE_MKDN.each do |doc|
63
+ puts "\t#{doc}"
64
+ end
65
+ puts "NICE_HTML_DOCS:"
66
+ NICE_HTML_DOCS.each do |doc|
67
+ puts "\t#{doc}"
68
+ end
69
+ end
70
+
71
+ desc 'Generate website html.'
72
+ task :gen_website => NICE_HTML_DOCS do
73
+ # Now that the website docs have been generated, copy them to ./website.
74
+ puts
75
+ sh "cp README.html website/index.html"
76
+ sh "cp doc/*.html website"
77
+ end
78
+
79
+ # You'll see some intermediate .plain files get generated. These are html,
80
+ # but don't yet have their code snippets syntax highlighted.
81
+ rule '.html' => '.plain' do |t|
82
+ puts "Turning #{t.source} into #{t.name} ..."
83
+ sh "./utils/post-mkdn2html.rb #{t.source} #{t.name}"
84
+ end
85
+
86
+ # Process the markdown docs into plain html.
87
+ rule '.plain' => '.txt' do |t|
88
+ puts
89
+ puts "Turning #{t.source} into #{t.name} ..."
90
+ sh "./utils/mkdn2html.rb #{t.source} #{t.name}"
91
+ end
92
+
93
+ desc 'Upload the newly-built site to RubyForge.'
94
+ task :upload_website => [:gen_website] do
95
+ sh "scp website/*.html hoanga@rubyforge.org:/var/www/gforge-projects/ruby-opengl"
96
+ end
97
+
98
+ desc 'Upload entire site, including stylesheet and the images directory.'
99
+ task :upload_entire_website => [:gen_website] do
100
+ sh "scp website/*.html hoanga@rubyforge.org:/var/www/gforge-projects/ruby-opengl"
101
+ sh "scp website/*.css hoanga@rubyforge.org:/var/www/gforge-projects/ruby-opengl"
102
+ sh "scp -r website/images hoanga@rubyforge.org:/var/www/gforge-projects/ruby-opengl"
103
+ end
104
+
105
+ # Define the files that will go into the gem
106
+ gem_files = FileList["{lib,ext,doc,examples,test}/**/*"]
107
+ gem_files = gem_files.exclude("**/*.so", "**/*.o", "ext/**/*.log", "ext/gl*/Rakefile")
108
+
109
+ spec = Gem::Specification.new do |s|
110
+ s.name = "ruby-opengl"
111
+ s.version = "0.33.0"
112
+ s.authors = [ "John Gabriele", "Minh Thu Vo" ]
113
+ s.homepage = "http://opengl-ruby.rubyforge.org"
114
+ s.platform = Gem::Platform::RUBY
115
+ s.summary = "OpenGL Interface for Ruby"
116
+ s.files = gem_files
117
+ s.extensions << 'Rakefile'
118
+ # s.extensions << 'ext/common/Rakefile', 'ext/gl/mkrf_conf.rb',
119
+ # 'ext/glu/mkrf_conf.rb', 'ext/glut/mkrf_conf.rb']
120
+ s.require_path = "lib"
121
+ s.autorequire = "gl"
122
+ s.has_rdoc = false
123
+ s.add_dependency("mkrf", ">=0.2.0")
124
+ end
125
+
126
+ # Create a task for creating a ruby gem
127
+ Rake::GemPackageTask.new(spec) do |pkg|
128
+ pkg.need_tar = true
129
+ end
@@ -0,0 +1,53 @@
1
+ Building ruby-opengl
2
+ ====================
3
+
4
+
5
+ Pre-requisites
6
+ --------------
7
+
8
+ On Ubuntu, aside from Ruby and the Rake gem, you'll need the following
9
+ packages:
10
+
11
+ * `libgl1-mesa libgl1-mesa-dri libglu1-mesa freeglut3`
12
+ * `libgl1-mesa-dev libglu1-mesa-dev freeglut3-dev`
13
+
14
+
15
+ Build instructions
16
+ ------------------
17
+
18
+ The current build setup is still under construction. When last looked at
19
+ (late November 2006), we were waiting for
20
+ the next mkrf release (we've patched what they have in svn, so it works,
21
+ but their maintainer seems to have moved on and not made a release
22
+ containing our fix). Building our ruby-opengl works, but you'll need
23
+ the version of mkrf still in svn.
24
+
25
+ Once you have a mkrf in place, on unixy platforms, just run
26
+
27
+ ./build.sh
28
+
29
+ to build.
30
+
31
+ After building, the extension modules are automatically copied to the
32
+ project's `./lib` directory.
33
+
34
+
35
+ Installing
36
+ ----------
37
+
38
+ For now, if you want to install ruby-opengl on your system, you can
39
+ do so manually (there is no gem, nor even a release, for it yet).
40
+ Just copy the contents of `./lib` into your
41
+ `.../lib/ruby/site_ruby/1.8` directory (or anywhere else `ruby`
42
+ searches for modules).
43
+
44
+
45
+ Testing / Running
46
+ -----------------
47
+
48
+ To run a sample file:
49
+
50
+ $ cd examples
51
+ $ ruby plane.rb
52
+
53
+ Hit ESC to exit.
data/doc/history.txt ADDED
@@ -0,0 +1,48 @@
1
+ Project history
2
+ ===============
3
+
4
+ The [original ruby-opengl](http://www2.giganet.net/~yoshi/) was written
5
+ by Yoshi.
6
+
7
+ John G. then wanted to clean it up and add some docs to it, and so started
8
+ tweaking and put up a new site and made his changes available.
9
+
10
+ Then Peter M. came along and decided to try updating ruby-opengl using SWIG,
11
+ as it seemed easier than doing everything by hand. Peter wrote the new code,
12
+ John started the actual RubyForge project, put up a new site, and Peter
13
+ committed the code.
14
+
15
+ Thu M. V. joined the project with a lot of energy, and the mailing list
16
+ was showing a good bit of activity.
17
+
18
+ After some experience, we began to question whether SWIG was necessary/helpful
19
+ for a project of this nature. The leaning was that people want to abandon
20
+ SWIG and go back to maintaining the binding files by hand. Thu even provided
21
+ a script to help with the manual coding that would be required without using
22
+ SWIG.
23
+
24
+ The reasoning at the time was:
25
+
26
+ Pro-SWIG:
27
+
28
+ * Could use the .i files for another project, perhaps (OTOH, we couldn't
29
+ use previous .i files on this project...)
30
+
31
+ * It's supposed to require less manual coding.
32
+
33
+ Con-SWIG:
34
+
35
+ * yet another tool to learn
36
+
37
+ * OpenGL isn't really all that big
38
+
39
+ * OpenGL doesn't change a lot
40
+
41
+ * A lot of boilerplate and overhead in the generated files because SWIG is
42
+ a general tool.
43
+
44
+
45
+ In September 2006, we stopped using SWIG. Thu and Peter began fine tuning
46
+ Thu's original `utils/mkwrap.rb` script.
47
+
48
+ Development stalled in October 2006.
@@ -0,0 +1,131 @@
1
+ Design
2
+ ======
3
+
4
+ This document records the requirements, high-level design, and the
5
+ specifications for the ruby-opengl project.
6
+
7
+ The content of this document was gleaned from the postings on the
8
+ ruby-opengl-dev list and internal notes from John G., Peter M., Vo Minh Thu,
9
+ and Robert K.
10
+
11
+
12
+ Requirements
13
+ ------------
14
+
15
+ * ruby-opengl is a Ruby extension library which wraps the OpenGL, GLU,
16
+ and GLUT libraries.
17
+
18
+ * ruby-opengl shall provide three base modules: *BaseGL*, *BaseGLU*, and
19
+ *BaseGLUT* (the "Base Modules").
20
+
21
+ Note: "BaseGL" etc. are not the names that appear in the code -- they are
22
+ just handles so we can write about them in documents like this one.
23
+
24
+ * The Base Modules shall be separately loadable.
25
+
26
+ * BaseGL shall not depend on any of the other Ruby modules.
27
+
28
+ * BaseGLU shall depend on, at most, BaseGL.
29
+
30
+ * BaseGLUT shall depend on, at most, BaseGLU and BaseGL.
31
+
32
+ * Base Module syntax shall closely follow the standard C-syntax.
33
+
34
+ The syntax for a Ruby program that uses the base modules, shall closely
35
+ follow the standard C-like syntax that OpenGL programmers are used to,
36
+ and that most OpenGL examples are published in:
37
+
38
+ {{ruby}}
39
+ require 'gl'
40
+ Gl.glBegin( Gl::GL_POLYGON )
41
+ Gl.glVertex2d( 0, 0 )
42
+ Gl.glVertex2d( 0, 1 )
43
+ Gl.glVertex2d( 1, 1 )
44
+ Gl.glVertex2d( 1, 0 )
45
+ Gl.glEnd
46
+
47
+ Or:
48
+
49
+ {{ruby}}
50
+ require 'gl'
51
+ include Gl
52
+ glBegin( GL_POLYGON )
53
+ glVertex2d( 0, 0 )
54
+ glVertex2d( 0, 1 )
55
+ glVertex2d( 1, 1 )
56
+ glVertex2d( 1, 0 )
57
+ glEnd
58
+
59
+ The rationale for adopting the C-like syntax is:
60
+ * Makes it familiar to OpenGL programmers.
61
+ * Removes the burden of learning OpenGL plus some Ruby-isms, just to
62
+ get started.
63
+ * Makes it easier to port OpenGL programs to/from ruby-opengl.
64
+ * The current OpenGL documentation more naturally fits ruby-opengl.
65
+ * Putting "gl", "glu" and "glut" in front of all the names (i.e.,
66
+ following the C-like syntax) leaves common variable names open for
67
+ the programmers (e.g., "vertex", "color" etc. are popular topics in
68
+ 3D programming, so not robbing the ruby namespace of such valuable
69
+ real-estate seems nice).
70
+
71
+
72
+ * It shall be possible to check out the project from svn, compile and test
73
+ on the following platforms: Mac OS X, GNU/Linux. MS Windows operating
74
+ systems may also be supported in the future.
75
+
76
+ * Provide backwards compatiblity for the older ruby-opengl function and
77
+ constant naming style (possibly in a layer built on top of the Base layers).
78
+ The support should be as minimally invasive as possible, perhaps via:
79
+ `require 'gl_prev'`, `require 'glu_prev'`, and `require 'glut_prev'`.
80
+
81
+ * The project will make a number of pre-compiled extensions available as gems.
82
+
83
+ * The project will supply source code and build scripts (via svn checkout)
84
+ conducive to straightforward porting to other platforms.
85
+
86
+ * There shall be a test suite that exercises each call in each of the Base
87
+ modules.
88
+
89
+ * There shall be tools supplied which can:
90
+
91
+ * generate source code from existing OpenGL/GLUT header files which,
92
+ probably with some fine-tuning, can be used to update the module.
93
+
94
+ * show differences in coverage between ruby-opengl and a given set
95
+ of OpenGL/GLUT header files.
96
+
97
+ * All project documentation will be in Markdown format in files that end in
98
+ `.txt`.
99
+
100
+ * The project will make some efforts to track versions of OpenGL.
101
+
102
+
103
+ ### Things in the future
104
+
105
+ Once the base modules are implemented, there are several ideas on things to
106
+ do next. This list is not really requirements, but a list of nice ideas to
107
+ try:
108
+
109
+ * Provide wrappers for glBegin/glEnd, eg: polygon()...translates to
110
+ glBegin(GL_POLYGON)....glEnd
111
+
112
+ * Untyped versions of the multi-typed gl functions: e.g., a single
113
+ glVertex that examines its arguments and calls the appropriate
114
+ glVertex{234}{fisdv} call in BaseGL.
115
+
116
+
117
+
118
+ Implementation
119
+ --------------
120
+
121
+ Our plan is to continue on with Yoshi's original code, modified
122
+ to use standard OpenGL-style constant and function names.
123
+
124
+
125
+ ### Build environment ###
126
+
127
+ The build environment will:
128
+
129
+ * use rake and mkrf. (note -- development of mkrf seems to have
130
+ stalled)
131
+ * minimize the number of additional tools required
data/doc/roadmap.txt ADDED
@@ -0,0 +1,19 @@
1
+ Roadmap
2
+ =======
3
+
4
+ * Get BaseGL updated.
5
+ * Get BaseGLU updated.
6
+ * Get BaseGLUT updated.
7
+ * Add the ESC keyboard handler to smooth.rb
8
+
9
+ <br/>
10
+ <br/>
11
+ <br/>
12
+ <br/>
13
+ <br/>
14
+ <br/>
15
+ <br/>
16
+ <br/>
17
+ <br/>
18
+ <br/>
19
+ <br/>
@@ -0,0 +1,28 @@
1
+ Scientific Use
2
+ --------------
3
+
4
+ Though not directly related to ruby-opengl, this page contains a
5
+ few tidbits of general info that might possibly be of interest to
6
+ a number of users.
7
+
8
+ There are currently two bindings to the [GNU Scientific Library][1] (GSL):
9
+
10
+ * Yoshiki's Ruby/GSL (<http://rb-gsl.rubyforge.org/>) --
11
+ Comes with an API reference. Also, I've been told that the API has been
12
+ worked a bit to be more comfortable for Ruby programmers.
13
+ * Arno's ruby-gsl (<http://ruby-gsl.sourceforge.net/>) --
14
+ more of a straight wrapper around the C API.
15
+
16
+ [1]: http://www.gnu.org/software/gsl/
17
+
18
+ <a href="http://rubyforge.org/softwaremap/trove_list.php?form_cat=97">Browse Rubyforge</a>
19
+ for more.
20
+
21
+
22
+ Links
23
+ -----
24
+
25
+ * <http://sciruby.codeforpeople.com/sr.cgi/FrontPage> -- SciRuby wiki.
26
+ * <http://narray.rubyforge.org/> -- Numerical n-dimensional Array class.
27
+ * <http://www.kitp.ucsb.edu/~paxton/tioga.html> -- Tioga. Create plots using
28
+ Ruby and TeX.
@@ -0,0 +1,63 @@
1
+ <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2
+ <html xmlns="http://www.w3.org/1999/xhtml">
3
+ <head>
4
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
5
+ <link type="text/css" media="screen" rel="stylesheet" href="style.css" />
6
+ <title>ruby-opengl -- {{title}}</title>
7
+ </head>
8
+
9
+ <body>
10
+
11
+ <div id="container">
12
+
13
+ <div id="header">
14
+ <em>ruby-opengl</em>
15
+ </div>
16
+
17
+ <ul id="tabnav">
18
+ <li><a href="./index.html">Home</a></li>
19
+ <li><a href="./tutorial.html">Tutorial</a></li>
20
+ <li><a href="./requirements_and_design.html">Req's doc</a></li>
21
+ <li><a href="./build_install.html">Build/Install</a></li>
22
+ <li><a href="./history.html">History</a></li>
23
+ <li><a href="./roadmap.html">Roadmap</a></li>
24
+ </ul>
25
+
26
+ <div id="sidebar">
27
+ <h3>Contact</h3>
28
+ <ul>
29
+ <li><a href="http://rubyforge.org/mail/?group_id=2103">Mailing list</a></li>
30
+ </ul>
31
+
32
+ <h3>Other docs</h3>
33
+ <ul>
34
+ <li><a href="./thanks.html">Thanks</a></li>
35
+ <li><a href="./scientific_use.html">Scientific use</a></li>
36
+ </ul>
37
+
38
+ <h3>Links</h3>
39
+ <ul>
40
+ <li><a href="http://www.opengl.org/">OpenGL</a></li>
41
+ <li><a href="http://www.mesa3d.org/">Mesa</a></li>
42
+ <li><a href="http://freeglut.sourceforge.net/">freeglut</a></li>
43
+ <li><a href="http://rubyforge.org/projects/ruby-ftgl/">ruby-ftgl</a></li>
44
+ <li><a href="http://www.rubygarden.org/ruby?OpenGL">Ruby wiki GL page</a></li>
45
+ <li><a href="http://rubygame.seul.org/">RubyGame</a></li>
46
+ </ul>
47
+ </div>
48
+
49
+ <div id="content">
50
+
51
+ {{content}}
52
+
53
+ </div>
54
+ <div id="footer">
55
+ <p><a href="http://validator.w3.org/check?uri=referer">Valid XHTML 1.0</a> |
56
+ Copyright &copy; <a href="#">John M. Gabriele</a> |
57
+ Design by <a href="http://www.jdavidmacor.com">super j man</a></p>
58
+ </div>
59
+
60
+ </div>
61
+
62
+ </body>
63
+ </html>
data/doc/thanks.txt ADDED
@@ -0,0 +1,23 @@
1
+ Thank you
2
+ ---------
3
+
4
+ Aside from big thank-you's to the core devs, special thanks (alphabetical
5
+ by first name) also goes to:
6
+
7
+ * Bill Kelly -- provided some pilot code changing how users can call method and constant names.
8
+ * Ilmari Heikkinen -- provided code for changing how users can call method and constant names.
9
+ * James Adam -- Mac OS X fixes
10
+ * Tony Hursh -- Mac OS X glut build tweak
11
+ * **Yoshi** -- providing ruby-opengl-0.32g from which to work off of.
12
+
13
+
14
+ <br/>
15
+ <br/>
16
+ <br/>
17
+ <br/>
18
+ <br/>
19
+ <br/>
20
+ <br/>
21
+ <br/>
22
+ <br/>
23
+ <br/>
data/doc/tutorial.txt ADDED
@@ -0,0 +1,160 @@
1
+ Usage tutorial
2
+ ==============
3
+
4
+ Naming conventions
5
+ ------------------
6
+
7
+ There are two ways to use ruby-opengl. Firstly, you can use customary
8
+ C-style method names and constant names like so:
9
+
10
+ {{ruby}}
11
+ require 'gl'
12
+ require 'glu'
13
+ require 'glut'
14
+
15
+ include Gl
16
+ include Glu
17
+ include Glut
18
+
19
+ glFooBar( GL_FOO_BAR )
20
+ gluFooBar( GLU_FOO_BAR )
21
+ glutFooBar( GLUT_FOO_BAR )
22
+
23
+ You don't have to `include` Gl, Glu, and Glut, but if you don't, then
24
+ you'll have to prefix each of those method and constant names like so:
25
+
26
+ {{ruby}}
27
+ Gl.glFooBar( Gl::GL_FOO_BAR )
28
+ Glu.gluFooBar( Glu::GLU_FOO_BAR )
29
+ Glut.glutFooBar( Glut::GLUT_FOO_BAR )
30
+
31
+ The other way you might use ruby-opengl is to employ the notation that
32
+ users of previous versions of ruby-opengl have used:
33
+
34
+ {{ruby}}
35
+ require 'gl_prev'
36
+ require 'glu_prev'
37
+ require 'glut_prev'
38
+
39
+ GL.FooBar( GL::FOO_BAR )
40
+ GLU.FooBar( GLU::FOO_BAR )
41
+ GLUT.FooBar( GLUT::FOO_BAR )
42
+
43
+ There are many fine OpenGL and GLUT tutorials all over the 'Net, so we
44
+ don't plan on trying to duplicate them here at the moment. Most of
45
+ these tutorials presume you are writing your code in C or C++, but
46
+ they should still be almost directly usable with ruby-opengl as long
47
+ as you use the C-style names (and, of course, as long as you change
48
+ the rest of the C code you find from C (or C++) to Ruby). If you opt
49
+ for using the legacy ruby-opengl style names, you'll have to take the
50
+ additional step of converting the calls from `glFooBar( GL_FOO_BAR )`
51
+ to `GL.FooBar( GL::FOO_BAR )`.
52
+
53
+ Personally, I prefer the current C-style names because:
54
+
55
+ 1. It's somewhat easier to follow along with the many online tutorials
56
+ and written OpenGL/GLUT books (i.e. the RedBook, BlueBook, SuperBible,
57
+ etc.).
58
+
59
+ 2. Copying/pasting code between Ruby and C is easier (otherwise you'll
60
+ be doing a lot of search/replace).
61
+
62
+ 3. My fingers are already used to typing the traditional C-style names
63
+ of all these identifiers.
64
+
65
+ Also, I don't like the fact that, if you use the previous ruby-opengl
66
+ style, you've got method names starting with a capital letter (which is
67
+ not customary Ruby style).
68
+
69
+ For the rest of this document, I'll use the current C-style names.
70
+
71
+
72
+ GLUT callbacks
73
+ --------------
74
+
75
+ The major difference from your GL code in C is in how glut callbacks are
76
+ handled. Rather than define your callbacks as top-level functions,
77
+ with ruby-opengl, it's done (for example) like so:
78
+
79
+ {{ruby}}
80
+ reshape = lambda do |w, h|
81
+ glViewport( ... )
82
+ glMatrixMode( GL_PROJECTION )
83
+ # etc.
84
+ glMatrixMode( GL_MODELVIEW )
85
+ glLoadIdentity
86
+ end
87
+
88
+ # ...
89
+
90
+ glutReshapeFunc( reshape )
91
+
92
+ An older notation you'll see instead of `lambda` is `proc`. The PickAxe
93
+ v2 notes that `proc` is "mildly deprecated" in favor of `lambda`. You'll
94
+ also sometimes see `Proc.new` used in place of either. Pages 359-360 of
95
+ PickAxe v2 describe the differences between using `lambda` and `Proc.new`,
96
+ but for our purposes either will be fine.
97
+
98
+
99
+ Source code layout
100
+ ------------------
101
+
102
+ The directory structure follows current Ruby standards, with a few
103
+ extra directories added.
104
+
105
+ * `doc/` -- Contains documentation for the project (from which this
106
+ website is generated).
107
+ * `examples` -- Some small sample programs. Mostly, these are being
108
+ copied from Yoshi's examples while being updated and neatened up.
109
+ * `experimental` -- Pure Ruby modules that are intended to make ruby-opengl
110
+ usage more "Rubyish". These may eventually become part of ruby-opengl proper.
111
+ * `ext/` -- Contains subdirectories, one for each of the three extension
112
+ modules (gl, glu, glut). Herein are the files needed to compile the extension
113
+ modules.
114
+ * `lib/` -- Files that the user is meant to `require` in their own code.
115
+ * `test/` -- Contains sample ruby files that make OpenGL and GLUT calls.
116
+ * `utils` -- Some under-construction utility scripts used to help generate
117
+ extension module source from GL header files. Also contains some scripts
118
+ used to generate the ruby-opengl website.
119
+ * `website` -- After running `rake gen_website` this directory will contain
120
+ the ruby-opengl website.
121
+
122
+
123
+ The Samples
124
+ -----------
125
+
126
+ To run the samples, manually pass them to `ruby` like so:
127
+
128
+ ruby some_sample.rb
129
+ ruby some_sample_prev.rb
130
+
131
+ The names ending in `_prev.rb` have been "ported" to use the legacy method
132
+ and constant names (and possibly have been neatened up a bit as well). The
133
+ `README` file in the `samples` directory contains some notes on the samples.
134
+
135
+
136
+ Mac OS X notes
137
+ --------------
138
+
139
+ James Adam passed along some fixes to ruby-opengl in 2005 on ruby-talk.
140
+ Some methods have been incorporated into ruby-opengl-0.33. Paraphrasing
141
+ James a bit, he writes:
142
+
143
+ > 1. `CheckLoop` was added to bring the GLUT module in line with the
144
+ > same function in Apple's GLUT. GLUT's MainLoop is blocking and forces
145
+ > you to perform additoinal processing using GLUT's IdleFunc system,
146
+ > which can sometimes be very undesirable (particularly if you are using
147
+ > Ruby as the glue between two libraries which both feature this type of
148
+ > loop). CheckLoop allows you to cycle through a *single* GLUT processing
149
+ > loop, and then returns control to the calling thread/process. Thus, by
150
+ > periodically calling CheckLoop, you can get the scene to update without
151
+ > having GLUT seize control of the whole application.
152
+ >
153
+ > 2. `GameModeString(mode_string)` and `Glut.EnterGameMode()`. May allow you
154
+ > to switch your application to fullscreen.
155
+ >
156
+ > 3. `BitmapCharacterX(char)` for displaying characters, since there seems to
157
+ > be a problem with the default `GLUT.BitmapCharacter` method.
158
+
159
+ Any feedback on testing of these methods is welcome, and will likely
160
+ be incorporated into the ruby-opengl docs.