From: Marcus Sundberg <e94_msu@elixir.e.kth.se>
  To  : ggi-develop@eskimo.com
  Date: Thu, 20 Aug 1998 23:49:38 +0200

libggi internals (Re: LibGGI3D RFC)

> The extension mechanism of libggi provides a mean to add _new_ functions
> to the GGI API, available for a given ggi_visual_t.
> This means that you can add a function ggi3dDrawTriangle(x,y,z) easily
> (NB: The x,y,z parms are here just because I _need_ parms for the following,
> I don't mind if this is realistic.)
> This is the purpose of extension libraries.
> 
> A display target allows you to _specialize_ the functions (ie: to adapt
> them to a specific environment). E.g. you can provide a
> ggi3dDrawTriangleDamnFastOn16Bpp(x,y,z) function in a display-damnfast-16bpp
> display target. And the user will not call it directly, it will simply
> use the normal ggi3dDrawTriangle(x,y,z).
> This is the purpose of display target and dynamic loading of specialized
> lib. (As you guessed, the "stub" lib is the generic lib that gets loaded
> anyway if there is nothing specialized for the running environment.)

Seems some things needs to be cleared out here.

An extension library is a library that needs to do one of the
following things:
* Access data that is internal to libggi.
* Change the behaviour of existing libggi API functions.
To achieve those things it needs to use the libggi extension
mechanism, and therefore by definition is an extension.
One reason it may want to the first thing may be that the
extension library wants to add functions that are not wrappers
for existing libggi API functions. Such as functions dealing
with accelerated 3D for example.

A non-extension library is a library that uses the libggi
API just like any normal application. An example of this is
the SVGAlib wrapper.

A display target is the name for both a certain subsystem
that libggi is able to draw on (such as X, fbdev, SVGAlib,
KGI, memory and glide), and the .so library that is responsible
of providing access to this subsystem. The display target may
load other libs to aid it in providing this. For example a target
that has a linear framebuffer just need to set up it's framebuffer
address, virtual size of the fb and the stride, and then load
the generic-linear-16 library which will provide all drawing
functions for a 16bpp framebuffer.

Now, you want kernel-drivers for 3D accelerated cards, and a 
libggi3d to interface the drivers.

This gives you three options:
1. Extend the KGI API with 3D functions and use the same
   driver for 2D and 3D.
2. Design a new kernel-driver API for your 3D drivers, which
   also contains 2D functions.
3. Design a new kernel-driver API for your 3D drivers, which
   only deals with 3D.

The third option would cause problems for cards that integrate
2D and 3D as you would have two drivers access the card. In any
case you do not have any reason to interface to libggi if you
choose this option.

The seccond option would be pretty braindead as KGI is already
about to be a standard. (Thinking of Alan Cox removing the
MediaGX driver and recommending kgicon instead).
If you were to choose this option you would use the same
display-new-kernel-driver-API display target regardless of
which kernel-driver you were using.

The first option is what I'd prefer. In this case the display target
would be KGI.

In any case there will never be a display-damnfast-16bpp display
target. If we assume that you use the first option for the kernel-
drivers here's how it will work:

The application will first call ggi3dInit(), which will initiate
libggi if that's not done and then register the ggi3d extension
with libggi.
Then the application uses ggiOpen() to open the display it want's
to use. Now the application can use all the normal libggi functions
to draw on the display (even if it's a "3D only" card you can
always do 2D in some way - access the framebuffer directly, or
emulate putpixel with 1x1 triangles/textures/whatever).
But as the application wants to do 3D it calls ggi3dAttach(vis)
where vis is the visual that ggiOpen() returned.
Now the application can use all the libggi3d functions to draw onto
the visual vis.

For an example of how this works internally, pleae look at the
misc-extension.

Btw, libggi3d may very well have a ggi3d-damnfast-16bpp library,
but it will not be a display target, it will just be a library
that provides a visual with some of the functions found in
libggi3d.

//Marcus