Version 0.3

1) Definitions:
---------------

http://www.opengl.org/developers/documentation/

  - OpenGL: OpenGL is a software interface to graphics hardware, which 
provides the ability to render images onto OpenGL drawables via so called 
OpenGL rendering contexts.
  - OpenGL rendering context: OpenGL commands are sent via the rendering
context bound to the calling thread (ie: the "current" context). An OpenGL 
context can be configured to use direct (the OpenGL client directly accesses
the hardware rendering pipeline) or indirect (the OpenGL client must go through
the windowing system to access the hardware rendering pipeline) rendering.
  - OpenGL drawable: an OpenGL drawable represents the medium where the 
scene is rendered.
  - OpenGL frame buffer: this is the memory underlying a drawable. It
can be configured to use several different attributes (e.g. double-buffering, 
stereo rendering, several types of ancillary buffers, pixel depth, ...)

  - GLX: GLX is a full-fledged extension to the X Windows System which can
be used to configure OpenGL frame buffers and create OpenGL drawables and 
OpenGL Contexts. GLX can create different types of OpenGL drawables:
     1. X window or GLXWindow (in GLX 1.3): an X window can be an
        OpenGL drawable.
     2. GLXPixmap: an X pixmap can also be an OpenGL drawable.
     3. GLXPbuffer: a Pbuffer (pixel buffer) is an off-screen
        OpenGL drawable. It is an area of the frame buffer memory of
        graphics hardware. X cannot draw on Pbuffer.
The GLX specification is available here: 
ftp://ftp.sgi.com/opengl/doc/opengl1.2/glx1.3.pdf.

  - WGL: this is the win32 equivalent of GLX. Its API was closely
modeled after the GLX API. A comparison is available here:
http://msdn.microsoft.com/library/en-us/opengl/ntopnglo_4v3m.asp?frame=true

  - GLUT: http://www.opengl.org/developers/documentation/glut/index.html
GLUT is basically a 3D toolkit built on top of OpenGL/GLX/WGL.

2) Goal
-------

Our goal is to provide a platform-independent API integrated in GTK+ (and/or GDK) 
to:
  - Choose buffer configuration (format, type and size for the color and
    ancillary buffers for drawables)
  - Create an OpenGL rendering context and control it (bind to the current
    calling thread, copy context's state, etc.).
  - Create an OpenGL drawable for on-screen rendering
  - Swap opengl buffers
  - Synchronize the opengl and windowing-system rendering pipelines (functions 
    such as glXWaitX for example)
  - Maybe provide a specialized widget which provides a trivial interface to
    these functions.
  - Maybe create an OpenGL drawable for off-screen rendering (into a pixmap)

Owen and a few others seem to agree on these goals and what we need to discuss
and agree upon is how we will achieve these goals.


3) What are the issues ?
------------------------

3.1) link-time dependency
-------------------------

Adding this feature into GTK/GDK means that, somehow, we need to drag yet another
dependency to the build. Namely, we need to drag in a dependency on the OpenGL
library used on the user's system which contains either the glX or the WGL layer.
During the previous thread on this topic, owen identified five possible solutions:
  1- add this support directly into the gdk/gtk libraries: this means adding another
    library during the link for all applications (even those which do not use openGL)
    QT does this.
  2- add only the API into the gdk/gtk libraries. Implement them with empty stubs if you
    do not want openGL support.
  3- add this support into a separate library shipped with gdk/gtk.
  4- add this support into a separate library not shipped with gdk/gtk but officialy 
    "blessed".
  5- add this support into a separate library not shipped with gdk/gtk and do not 
    "bless" it.

2- is probably the worst solution because it would make it really painful for application
to behave correctly if they want to use OpenGL and the GTK+ library they are run against
does not support it.
5- is not really an option since we want to add OpenGL support in a way or another.
4- In our experience, users are very wary of external libraries (in terms of portability,
maintainance and documentation). They don't like having to install multiple libraries.
1- The main issue here seems to be the reluctance by many (a lot of embedded developers
and some users of legacy systems) to see GTK+ drag another dependency when the current 
dependency list is already pretty big. Some probably believe the "easy" solution is to 
add a compile-time compilation option to the system but this drags in a lot of problems 
related to application-side detection of the compilation options of the GTK+ library 
they are compiled and run against.
A solution might be to re-use an entirely different configuration system (something 
similar to the linux kernel's configuration UI or to the configuration tool of eCos)
for embedded/specialized builds and leave the UNIX/win32 builds with the current 
non-configuration approach.
3- does not really change the problems of -1 for embedded developers. It might make the
legacy systems people be happier though.

3.2) API issues
---------------

Here are the API issues:
  1) GDK-level: we need to provide a set of wrapper functions which provide the GLX/WGL
     functionality and which act on a GdkWindow/GdkPixmap. These functions must:
	- provide buffer configuration
	- provide context creation
	- provide context manipulation
	- provide misc buffer swapping, synchronization primitives
  2) GTK+-level: we might need to provide helper functions at the GTK+ level using the 
     gdk-level functions as well as a potential GTK+ specialized widget for OpenGL rendering.

2) should be implemented on top of 1) so I think the discussion should focus on 1) first.
Current alternatives to 1):
	- gtkglext: provides functions to create a GdkGLDrawable on a given GdkWindow or GdkPixmap
	  after it was created. It is then possible to:
		* create and manipulate the GL context
		* swap buffers
		* synchronize the rendering pipelines
	  with this object.

	- gtkglarea: provides functions to create an abstract type (GdkGLContext) which 
	  represents the OpenGL Rendering context. It is possible to manipulate it, swap buffers.
	  There is no synchronization primitive.

	- "Owen": he suggested informally on IRC the creation of a subclass of GdkWindow and a 
	  subclass of GdkPixmap which would both implement a GdkGLInterface.

3.3) Existing APIs
------------------

 3.3.1) Traditional OpenGL drawing area widget for X11
 -----------------------------------------------------

   GLwDrawingArea - for Xt
   GLwMDrawingArea - for Motif

    http://www.xfree86.org/current/GLwDrawingArea.3

   - They don't have GLX abstraction layer. You need to use GLX
     functions to create a GLXContext.
   - Example program with Mesa.
      http://cvs.sourceforge.net/viewcvs.py/mesa3d/Mesa/widgets-sgi/boilerplate.c?rev=1.1.1.1&view=auto

 3.3.2) Qt OpenGL module
 -----------------------
 
   QGLWidget: An easy-to-use Qt widget for rendering OpenGL scenes.
   QGLContext: Encapsulates an OpenGL rendering context.
   QGLFormat: Specifies the display format of a rendering context.
   QGLColormap: Handles indexed colormaps in GL-index mode.

    http://doc.trolltech.com/3.2/opengl.html

   - OpenGL programming using QGLWidget is very simple. Binding
     context to current calling thread, swapping front and back
     buffers, etc. can be done automatically by QGLWidget. (But it
     means that QGLWidget approach would reduce GLX's frexibility.)
   - Not well structured, I think. Off-screen pixmap rendering is
     mixed into QGLWidget API (QGLWidget::renderPixmap).
   - Overlay is supported.

 3.3.3) GtkGLArea
 ----------------

    http://cvs.gnome.org/lxr/source/gtkglarea/docs/HOWTO.txt

   - It looks like GLwDrawingArea.
   - Derives from GtkDrawingArea.
   - Example program.
      http://cvs.gnome.org/lxr/source/gtkglarea/examples/simple.c

 3.3.4) GtkGLExt
 ---------------

   http://gtkglext.sourceforge.net/reference/gtkglext/

  - Composed of two libraries.
    libgdkglext - OpenGL extension to GDK.
    libgtkglext - Support library for using OpenGL on GtkDrawingArea.
  - GdkGLConfig looks like QGLFormat.
  - Currently, it doesn't provide OpenGL-specific widget.
  - Example programs.
     http://cvs.sourceforge.net/viewcvs.py/gtkglext/gtkglext/examples/simple.c?view=markup
    low-level libgdkglext only example
     http://cvs.sourceforge.net/viewcvs.py/gtkglext/gtkglext/examples/low-level.c?view=markup


4) Changes:
-----------

  Since 0.3:
	- make the API issues section hopefully more clear. Include a few details on owen's ideas.
  Since 0.2:
	- add more details to the link-time issue
	- add GLwDrawingArea to library list.
  Since 0.1:
	- add frame buffer to definitions, update the other definitions to use this term
	- update the goal list	
  Since pre-0.1:
	- add short blurb/pointers+comparison for most toolkit-integration libraries
	- add GLUT description
	- add version number
	- add section numbering
	- update OpenGL/GLX descriptions
	- add discussion on library dependency issues
