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

Re: LibGGI2D, LibGGI3D and targets

On Sat, 29 Aug 1998, Marcus Sundberg wrote:

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

	Everything in CVS is a mess right now.  I suggest that we keep
working until we all agree that a suitable stable state has been reached,
and then we have Emmanuel blow away the whole CVS tree and reinstall
everything without kgi/, os/, lib/libggi/extensions/libggi2d, etc and with
any directory moves that we want done, done.  That will cost us our
revision control, but we can archive the old tree if necessary and the
cleanups will be worth it.  

	We don't want to be doing this too often though, so we should make
sure that we do every pending directory reorganization we can think of
that we need all at once.  The issues that were discussed a while back
about the new directory structure for kgicon and the new makefile system
should be handled at this point as well, if at all possible.  Plus there
is the issue of James' new kernel makefile system. 

	We *could* wait to do this until after (or immediately before)
Degas is released, but IMHO that would be a bad idea.  At the rate that
stuff is meaing added, deleted and changed in the tree lately, we will
have a huge mess by the time December rolls around.  The sooner we bite
the bullet and do a reorg-and-cleanup, the better off we will all be. 
IMHO of course.
 
> > > > > 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

	I mistyped, that is what I was thinking of.  Stubs libraries are
per-extension-library.
 
> > 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!

	I see.  But what if the API changes between versions?  Will the
old 2.0 DrawBox() be ignored, for example? 

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

	Right.  Even if the stub code draws everything using PutPixel(),
PutPixel() still has to know about the visual layout to know what a pixel
*is* and how to draw it.  I assume this means that all targets must
implement PutPixel() for all mode types in the stubs?

Jon

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