From: Jon M. Taylor <taylorj@ecs.csus.edu>
  To  : ggi-develop@eskimo.com
  Date: Sat, 29 Aug 1998 14:07:19 -0700 (PDT)

Re: LibGGI2D, LibGGI3D and targets

On Sat, 29 Aug 1998, Marcus Sundberg wrote:

> 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 ;-)

	Sounds like it is target-dependent.  SVGALib could be running on
any number of video cards.  But I take your point.  If the vgagl target is
always meant to be used with the SVGALib target, why not put it as a
subdirectory under display/svgalib?

> > > 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_, 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.  If you know your visual layout,
you load a 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?
 
> > > 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.

	So the visual type is tied to the target type?  Make sense.

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

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

	Ooops |->.  Yes, a useagecount is needed.  COM objects in Windows
need the same thing. 

Jon 

---
'Cloning and the reprogramming of DNA is the first serious step in 
becoming one with God.'
	- Scientist G. Richard Seed