From: Jon M. Taylor <taylorj@ecs.csus.edu>
  To  : ggi-develop@eskimo.com
  Date: Thu, 20 Aug 1998 16:03:44 -0700 (PDT)

Re: libggi internals (Re: LibGGI3D RFC)

On Thu, 20 Aug 1998, Marcus Sundberg wrote:

> > The extension mechanism of libggi provides a mean to add _new_ functions
> > to the GGI API, available for a given ggi_visual_t.
> > This means that you can add a function ggi3dDrawTriangle(x,y,z) easily
> > (NB: The x,y,z parms are here just because I _need_ parms for the following,
> > I don't mind if this is realistic.)
> > This is the purpose of extension libraries.
> > 
> > A display target allows you to _specialize_ the functions (ie: to adapt
> > them to a specific environment). E.g. you can provide a
> > ggi3dDrawTriangleDamnFastOn16Bpp(x,y,z) function in a display-damnfast-16bpp
> > display target. And the user will not call it directly, it will simply
> > use the normal ggi3dDrawTriangle(x,y,z).
> > This is the purpose of display target and dynamic loading of specialized
> > lib. (As you guessed, the "stub" lib is the generic lib that gets loaded
> > anyway if there is nothing specialized for the running environment.)
> 
> Seems some things needs to be cleared out here.
> 
> An extension library is a library that needs to do one of the
> following things:
> * Access data that is internal to libggi.
> * Change the behaviour of existing libggi API functions.

	This is a strict overload, right?  The symbol table is patched,
and the new function's parameters and return value are the same as the old
function's? 

> To achieve those things it needs to use the libggi extension
> mechanism, and therefore by definition is an extension.
> One reason it may want to the first thing may be that the
> extension library wants to add functions that are not wrappers
> for existing libggi API functions. Such as functions dealing
> with accelerated 3D for example.
> 
> A non-extension library is a library that uses the libggi
> API just like any normal application. An example of this is
> the SVGAlib wrapper.

	I'm still not clear on the difference between a new function in an
extension and a new function in an application.  What makes the first one
"part of LibGGI"?  What does "part of LibGGI" mean?

> A display target is the name for both a certain subsystem
> that libggi is able to draw on (such as X, fbdev, SVGAlib,
> KGI, memory and glide), and the .so library that is responsible
> of providing access to this subsystem. The display target may
> load other libs to aid it in providing this. For example a target
> that has a linear framebuffer just need to set up it's framebuffer
> address, virtual size of the fb and the stride, and then load
> the generic-linear-16 library which will provide all drawing
> functions for a 16bpp framebuffer.

	Ah, so targets are not rendering methods, targets are... well,
targets |->.  The same target can have different rendering methods. 
 
> Now, you want kernel-drivers for 3D accelerated cards, and a 
> libggi3d to interface the drivers.
> 
> This gives you three options:
> 1. Extend the KGI API with 3D functions and use the same
>    driver for 2D and 3D.

	This is the way to go, IMHO.  Take your existing 2D KGI drivers
and add 3D drawing ioctls. 

> 2. Design a new kernel-driver API for your 3D drivers, which
>    also contains 2D functions.

	Why, when we already have KGI?  fbcon/fbdev *can* be used for 2D
and 3D acceleration (and the fbdev LibGGI target, too), but KGI is just
plain better designed. 

> 3. Design a new kernel-driver API for your 3D drivers, which
>    only deals with 3D.

	This might be necessary to flog the absolute most performance out
of 3D hardware (ioctls == slow sometimes), but if this is to be done it
should be saved for later, after we have something working first.

> The third option would cause problems for cards that integrate
> 2D and 3D as you would have two drivers access the card. 

	Either you would need to just toss out the 2D stuff and have a
3D-only specialized KGI driver, or KGI would have to multiplex the
hardware between two or more separate drivers.  This isn't a bad idea in
principle - imagine the accel driver as actually being a separate driver
module .o file.  It would allow for mix 'n match driver modularity, much
like we have now in userspace with LibGGI.  But this would be a VERY
complex system, and quite different from what we have right now.  I think
this needs to go on the to-do pile along with vblank syncing, etc.  Save
it for later. 

> In any
> case you do not have any reason to interface to libggi if you
> choose this option.
> 
> The seccond option would be pretty braindead as KGI is already
> about to be a standard. (Thinking of Alan Cox removing the
> MediaGX driver and recommending kgicon instead).

	Don't hold your breath |-<.  We may be using kgicon for a while. 
We'll need to get Degas-KGI working and show that it is clearly superior
and doesn't break things in the kernel before people will look at an
alternative to fbdev.  Especially if kgicon drivers can be accelerated. 

> If you were to choose this option you would use the same
> display-new-kernel-driver-API display target regardless of
> which kernel-driver you were using.

	Right.

> The first option is what I'd prefer. In this case the display target
> would be KGI.

	Me too.

> In any case there will never be a display-damnfast-16bpp display
> target. If we assume that you use the first option for the kernel-
> drivers here's how it will work:
> 
> The application will first call ggi3dInit(), which will initiate
> libggi if that's not done and then register the ggi3d extension
> with libggi.
> Then the application uses ggiOpen() to open the display it want's
> to use. 
> Now the application can use all the normal libggi functions
> to draw on the display (even if it's a "3D only" card you can
> always do 2D in some way - access the framebuffer directly, or
> emulate putpixel with 1x1 triangles/textures/whatever).

	The Glide target draws to a secondary buffer and dumps it to Glide
on a flush.

> But as the application wants to do 3D it calls ggi3dAttach(vis)
> where vis is the visual that ggiOpen() returned.
> Now the application can use all the libggi3d functions to draw onto
> the visual vis.

	Ah, I see.  Now would there be only one type of ggi3dAttach(vis)
for all possible permutations of 3D visuals (clipping, buffer layouts,
rendering/texturing settings, etc?  If I want to draw to a depth buffer
and then render from that to a 2D framebuffer, do I need a special
3D-but-really-2D framebuffer type or could I just use a LibGGI2D
framebuffer?  That is, are the existing 2D visual attributes preserved
with the 3D attributes "added on", or do you have to start from scratch? 

> For an example of how this works internally, pleae look at the
> misc-extension.
> 
> Btw, libggi3d may very well have a ggi3d-damnfast-16bpp library,
> but it will not be a display target, it will just be a library
> that provides a visual with some of the functions found in
> libggi3d.

	Right.  damnfast-16bpp for Glide may not be the same thing as
damnfast-16bpp for Virge or damnfast-16bpp for PowerVR, or.... 

Jon

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