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

Re: LibGGI2D, LibGGI3D and targets

Jon M. Taylor wrote:
> 
> On Fri, 28 Aug 1998, Marcus Sundberg wrote:
> > and in order to accomplish
> > this task it may load other libraries - HELPER libraries like
> > vgagl.so,
> 
>         Which overload a subset of the API in order to reimplement API
> functionality in a non-device-specific way.  vgagl overloads hline
> drawing, but it is not like a hardware driver - the new hline is still
> hardware-independent, just done differently. 

No, vgagl.so is hardware-dependent. In fact vgagl.so will fail
to load if it's not loaded from the SVGAlib target (or another
library pretending to be the SVGAlib target, but that would be
a mean thing to to ;-)

The functions in vgagl.so could very well have been in the
SVGAlib target (svgalib.so) itself, but were put in a separate
library because:
a) They are only used for banked SVGAlib modes, so we save
   memory by only loading them when they are needed.
b) They need to be linked to libvgagl.so, which the rest of
   the SVGAlib target does not. By putting them in a separate
   library we don't need to link svgalib.so to libvgagl.so.

> > 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.

> > and
> > DRIVER libraries like mystique-8-15-16-32.so.
> 
>         Which, like helper libs, overload a subset of the API functions
> but do so in a device-dependent way, usually for accelerated drawing.
> Correct?

Correct.

> > I hereby define an EXTENSIONTARGET as "the first .so library that
> > gets loaded when you attach an extension to a visual"
> > An extensiontarget is responsible for providing the full
> > API of the extension to applications that attach the extension
> > to a visual. The extension-API is only available to visuals on
> > which the extension has been attach.
> 
>         Damn.  I've been thinking about the relationship between visuals
> and APIs incorrectly.  I envisioned LibGGI3D having its own (3D) visuals
> and then rendering from those visuals to a LibGGI2D target which would
> have its own, separate (2D) visuals.  Instead, it seems like I would want
> to:
> 
> * Open a visual
> * Set GGI3D_TARGET=libggi2d
> * Attach the LibGGI3D API to the visual
> * The LibGGI2D driver library's init code would attach the LibGGI2D API
>   to the visual and overload some or all of the LibGGI3D drawing functions
>   such that they would call out to LibGGI2D drawing functions
> * If the LibGGI3D API is unloaded from the visual, its LibGGI2D target will
>   also detatch the LibGGI2D API from the visual.
> 
>         Sound about right?

Yes, just two minor things:
1. In most cases setting GGI3D_TARGET=libggi2d shouldn't be 
   neccesary. If there isn't a native libggi3d extensiontarget
   for the visual libggi3d should automagically fall back to
   using libggi2d as the extensiontarget.
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.

   Also this reminds me that we need to add a usagecount to 
   ggiExtensionAttach() - imagine if an app first attaches the
   libggi2d API and then the libggi3d API with the libggi2d
   extensiontarget as you describe above. Then when libggi3d is
   detached it will take libggi2d with it if we don't have a
   counter.

//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