[Glsdk-devel] The purpose of the GL SDK

[Jason M. <ko...@gm...>]

Personally, whenever I begin a project of any particular size, the first 
question I ask is what it should do. What is the purpose in creating it. 
I find this useful, as any debate about what should or should not be 
included in the project can usually be cleared up by looking at its 
purpose. Or, at the very least, it is easier to see which alternative 
fills the purpose better than the other.

Normally, I would do this by making a (prioritized) list of goals. 
However for this project, I think it would be easier to list who should 
want to use the GL SDK and for what reasons. The audience for the SDK 
should drive all aspects of the design of the project.

I would say that our audience is two-fold. One section of our audience 
is the "new to OpenGL/graphics" programmer: the neophyte. This is 
someone who decided to do some graphics work, heard about OpenGL, and 
wants to have a go at it. This person cares about seeing something 
working and learning about how and why it is working. This person wants 
detailed examples, a clear, well-documented codebase, and above all, for 
it to work with as little fuss as possible.

The other section of our audience is the hobbiest GL programmer. This is 
someone who may probably has some GL experience. This programmer has 
some understanding of graphics, and may be interested in getting a 
greater understanding. However, the hobbiest differs from the neophyte 
in a very specific way: the hobbiest wants to code something specific. 
The neophyte just wants to learn; the hobbiest wants to implement some 
form of shadow mapping. He is not interested (at the moment) in building 
a large, complicated engine for doing it. He is more interested in 
getting a specific result, interfacing with OpenGL and getting it to do 
that cool think he heard about. The hobbiest wants to make little demo 
programs that do cool-looking things.

The neophyte is interested in examples, tutorials, documentation, and a 
simple, easy-to-use codebase. The hobbiest is interested in 
comprehensive documentation and the functionality of the codebase. Both 
of them are interested in playing with graphics, but the hobbiest knows 
more about graphics and is mostly interested in how to translate some 
idea into an on-screen result.

So the first thing I would put forward is that the GL SDK should serve 
the needs of both of these groups. There's enough overlap, particularly 
in the general code department, that serving both of their needs should 
be doable without much additional effort.

So, given the needs of the above, I would put forth the following as a 
prioritized list of design goals:

   1. Cross-platform. That's a given, as it is OpenGL's primary strength.
   2. Simple. The code design should be written in a style that can be
      understood.
   3. Comprehensive. We should provide full coverage over OpenGL's
      functionality. This means tutorials on lots of different aspects
      of GL, appropriate base code support, etc.
   4. Well Documented. All code needs to have clear documentation about
      every function, object, etc.
   5. Easy-to-"Install". I'm not necessarily suggesting a packaged
      installer (though I wouldn't be against it), but the library
      should be something that can be easily installed onto a system.
      And, most importantly, /compiled/. Generally, that means no
      /external/ dependencies; that means we ship the library with any
      actual dependencies (if we use libpng, we ship our lib with a
      version of libpng, etc).
   6. Functionality. To the extent that the prior goals are followed, we
      should provide a base code that gives reasonably comprehensive
      functionality to the user.

So, what do you think?