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.
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.
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:
use rake and mkrf.
minimize the number of additional tools required
Generated with the Darkfish Rdoc Generator 2.