From: Marcus Sundberg <mackan@stacken.kth.se>
  To  : ggi-develop@eskimo.com
  Date: Sat, 29 Aug 1998 21:52:18 +0000

Re: LibGGI2D, LibGGI3D and targets

Jon M. Taylor wrote:
> 
> On Sat, 29 Aug 1998, Marcus Sundberg wrote:
> If the vgagl target is
> always meant to be used with the SVGALib target, why not put it as a
> subdirectory under display/svgalib?

Good idea. I should have thought of that earlier, moving directories in
CVS is a real PITA...

> > > > STUB libraries like stub.so and linear_16.so,
> > >
> > >         Which implement the whole API, correct?
> >
> > Hmm, I think I'll change this definition:
> > stub.so are a STUB library, while linear_16.so are a GENERIC
> > library.
> > A stub library provides fallback implementations for all
> > functions that can be emulated using a more simple function.
> > For example all drawing-functions can be emulated by calling
> > _ggiPutPixelNC() (NC = No Clipping)
> > It is strongly recommended
> > that targets implement functions in a STUB library themselves,
> > as the stub functions are much slower.
> > A GENERIC library implements all the functions that are common
> > to a certain type of visual - for example a visual with
> > a linear framebuffer and a physical pixel-size of 16 bits.
> 
>         So STUB libraries are generics for a type of _target_,

Well, I'm making this terminology up as I write, just so we'll
have a clearly defined one in the future ;-) But I'd say that
there is exactly one stub library per library (libggi/libggi2d etc),
and for libggi that is stub.so

> and GENERIC libraries are generics for a type of _visual_. 

> STUB libraries are
> "generic generics" to be used when you know nothing about the nature of
> your target hardware or visual layout.

The STUB libraries should always be loaded first by a target:
Let's say that you have a binary-only target from libggi 2.0,
that implements all libggi functions natively, and you upgrade
to libggi 4.0, in which we for some reason decided that a
ggiDrawParallelogram() function was badly needed.

Now, the beauty of libggi is that as this target loads the
stub.so library, you can use the new ggiDrawParallelogram() function
even though the target doesn't even know it exists!

> If you know your visual layout, you load a GENERIC library.

Well, targets always know their visual layout, or else they
couldn't know how to use the visual. ;)
I'd rather say that if the visual layout has an apropriate GENERIC
library and the target can't hardware accelerate all the
functions it will load the GENERIC library.

> If you know your target "hardware", you load
> a DRIVER library (for drawing accelerations) and/or a HELPER library (for
> other type of "accelerations" like what vgagl does or rendering through a
> z-buffer or whatever).  Correct?

Right.

> > 2. It is true that from a technical point of view the libggi2d API
> >    will be attached to the visual at point 4 and removed at point 5,
> >    but from an application's point of view this doesn't happen -
> >    if it want to use the libggi2d API it should attach it by itself.
> 
>         Of course, but I was assuming that the application just wanted to
> do LibGGI3D stuff and render to a 2D visual.  If the app also wanted to do
> 2D drawing, it would load LibGGI2D itself, correct?

Yes, that's correct. Just wanted to be sure you knew that.

//Marcus-- 
-------------------------------+------------------------------------
        Marcus Sundberg        | http://www.stacken.kth.se/~mackan/
 Royal Institute of Technology |       Phone: +46 707 295404
       Stockholm, Sweden       |   E-Mail: mackan@stacken.kth.se