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