From: Jon M. Taylor <taylorj@ecs.csus.edu>
  To  : ggi-develop@eskimo.com
  Date: Fri, 28 Aug 1998 23:30:38 -0700 (PDT)

Re: LibGGI2D, LibGGI3D and targets

On Fri, 28 Aug 1998, Marcus Sundberg wrote:

> Jon M. Taylor wrote:
> >         But the problem is that the targets implement an API with those
> > stubs, and the LibGGI2D API is different from the LibGGI3D and LibGWT
> > APIs.  Either you'd have to merge all LibGGIxx APIs into one for these
> > mega-targets, or have some way of implementing multiple versions of the
> > same target for the different LibGGIxx libraries, and if you are going to
> > do that last then why not separate the different targets and put them in
> > their LibGGIxx subdirectories?
> 
> Sigh, what am I doing wrong here? Let's try yet another way to
> explain, and lets make some definitions. ;)

	Thanks a lot.  I *think* I have a handle on this now. 

> To avoid further confusion I hereby define a TARGET as
> "the first .so library that get's loaded when you call ggiOpen()"
> A target is responsible for providing the full libggi API
> to applications that open the target, 

	Ok, so a target is a rendering pipeline composed of a set of .dls
which implement the API function set and overload each other in whole or
in part according to some ruleset.  Sound about right?

> 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.  It sounds like this is how I
would want to implement z-buffer renderthrough or caching in a target or
suchlike.  Am I correct?

> STUB libraries like stub.so and linear_16.so, 

	Which implement the whole API, correct?

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

> The target does
> not provide any API other than the libggi one.

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

> To accomplish this task
> the extensiontarget may also load other libraries - 
> EXTENSIONHELPER, EXTENSIONSTUB and EXTENSIONDRIVER libraries.

	Got it.
 
> An EXTENSIONLIBRARY is the library the application wishing to
> use the extension links to at compiletime - like libggimisc.so.
> The extensionlibrary is responsible for registrering the extension
> with libggi, and provide a function that will
> a) attach the extension to a visual
> b) load the extensiontarget

	Got it.
 
> Normally each extension will have an extensiontarget for each 
> libggi target, to provide target-specific accelerations, but
> it doesn't have to have that.
> 
> Now does this answer your questions?

	Yes.  I think I understand now.  Please keep correcting me if I am
still wrong about something.

Jon

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