root/tags/Release_0_1/DerelictGL/README

================================================================================
DerelictGL
================================================================================
DerelictGL is a D package which allows you to use OpenGL in your D programs
without the need to link to an import library. This gives you control over how
to handle the case where the OpenGL shared library is not available on the
user's machine. DerelictGL also exposes all avaialable core OpenGL functions
and extensions up to version 1.5 through Joel Anderson's port of Ben Woodhouse's
GL Easy Extensions (GLee) library.

Please note that the Linux version is not yet implemented. Anyone who would like
to do so please let me know in the forum!

--------------------------------------------------------------------------------
USING
--------------------------------------------------------------------------------
You can use DerelictGL in your project by first adding the Derelict source path
to your compile command line with the -I switch (-I<derelict_dir>/DerelictGL) and
either by adding all the source/obj files to your makefile, or by building and
linking with derelictGL.lib (see the section entitled 'BUILDING' below for build
instructions).

If you link to derelictGL.lib or the glee.d object file (one of which you must
do to make use of extensions), then you need to also use the supplied go.bat
file to build glee.lib with DMC and link with it as well. If you do not need
OpenGL functionality beyond version 1.1 *and* have no need for extensions, then
simply compile and link gl.d as part of your project and ignore glee.d and
the lib files. 

In your code, you need to import the derelict.opengl.gl module. To make use
of extensions, import glee;

++++++++++++++++++++++++++   CODE  +++++++++++++++++++++++++++++++++++++++++++++

import derelict.opengl.gl;      // core GL 1.1 functions
import glee;                    // Core GL functions up to 1.5 plus extensions

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

During initialization of your application, you need to make a call to
dglLoad. This will load the shared library, platform-specific core gl functions
(such as the wgl* functions on Windows), and all core GL 1.1 functions. If
you only require OpenGL 1.1, then you are finished initializing DerelictGL and
can go on about your business.

If you require the functionality of OpenGL 1.2+ or any extensions, then you'll
need to make a call to GLeeInit. The catch is that you must first create
and activate an OpenGL context (if you aren't sure what I'm talking about, take
a gander at the nehe.gamedev.net OpenGL tutorials). OpenGL requires that a GL
context be active before querying for extensions. This is why dglLoad only loads
the core 1.1 functions. Once your context is activated, calling GLeeInit
will load all available core OpenGL 1.5 functions as well as all available
extensions.

++++++++++++++++++++++++++   CODE  +++++++++++++++++++++++++++++++++++++++++++++

// load the shared library and Core 1.1 functions via DerelictGL
dglLoad();

// app-specific code to init an OpenGL context goes here
...

// load extensions via GLee
GLeeInit();


++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Once the extensions are loaded, you can query for the availability of those
you need via GLee's extension flags. These take the same form as the extension
names, except that the 'GL_' in the names is replaced with 'GLEE_'. So, for
example, GL_ARB_vertex_program becomes GLEE_ARB_vertex_program. 

Platform-specific extensions, such as the 'WGL_' extensions, follow a different 
naming convention in that 'GLEE_' is prefixed to the extension name such that 
WGL_ARB_buffer_region becomes GLEE_WGL_ARB_buffer_region.

And finally, variables for querying the version of OpenGL available beyond 1.1
take the form of 'GLEE_VERSION_(major)_(minor)', such as 'GLEE_VERSION_1_2'.

The query variables will be set to 0 if the extension or version is unavailable.

++++++++++++++++++++++++++   CODE  +++++++++++++++++++++++++++++++++++++++++++++

// querying for specific GL versions
if(GLEE_VERSION_1_5)
    // do GL 1.5 stuff
else if(GLEE_VERSION_1_4)
    // do GL 1.4 stuff

// querying for specific extensions
if(GLEE_ARB_vertex_program)
    ...

if(GLEE_EXT_abgr)
    ...

if(GLEE_WGL_ARB_pbuffer)
    ...
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

If you need to get the actual version/extension strings (or any other gl strings,
such as the vendor string) you can use glGetString as normal. Note, however, that
GLee provides some convenience functions which can be used to get standard and
platform-specific extension, as well as error, strings:

GLeeGetExtStrGL();
GLeeGetExtStrWGL(); // windows
GLeeGetExtStrGLX(); // linux
GLeeGetErrorString()


--------------------------------------------------------------------------------
BUILDING
--------------------------------------------------------------------------------

To build DerelictGL on Windows:

1) ensure that both dmd\bin and dm\bin are on your path
2) from a command prompt, cd to <derelict_dir>\src\derelict\opengl
3) type 'make' or 'make lib' to build derelictGL.lib    
4) optionally type 'make clean' to delete all object files OR
   optionally type 'make cleanall' to delete all object, lib and bak files
5) run go.bat to build the C library glee.lib - this only need be done once but
   is required to make use of GLee.