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