From: James A Simmons <jsimmons@acsu.buffalo.edu>
  To  : GGI mailing list <ggi-develop@eskimo.com>
  Date: Wed, 19 Aug 1998 08:42:04 -0400 (EDT)

Re: LibGGI3D RFC

> 	OpenGL is quite good, and for most purposes it gets the job done. 
> But not for every purpose.  For those who need a few simple 3D features,
> those who want to be able to develop a 3D KGI driver without having to
> deal with the whole OpenGL API, for those who just want to render a
> gouraud shaded, texture mapped triangle, we need a simpler API.  That API 
> is LibGGI3D.

I couldn't agree with you more.
 
> II. Overall design
> 
> 	So the keyword here is "simple".  If OpenGL is too complex, then
> let's look at what parts of OpenGL we *don't* need: 

yes, very simple. Support only high end function where if a card doesn't
support it (like old vga) tehn the software emulation must be only a few
lines of code. This could be done with gourand shading.

> 
> * 3D world modeling.  We don't need it, and it can be implemented on top
> of LibGGI3D if needed.  Our job is to do 3D drawing, not model worlds. 
> 
Yes. And are their any cards that do this in hardware? I don't think so.
Might be wrong.

> * Complex object representational schemes (polyhedra, surfaces,
> constructive solid geometry).  Again, this is a job for a higher-level
> API.  All of that stuff is tesselated down before rendering anyway, so
> LibGGI3D can be designed with the assumption that such tesellation has
> already been done.
Agree. Support only triangles. I seen your earlier post about triangles.
I have code to turn polygons into triangles. What is also nice about
triangles is we could use RAPID for collison detect. Its the fastest
method out their and it tells the exact place of intersect. Image a game
were you could blow holes threw people. 

> 
> * Lighting, shading, texture mapping, or any other such algorithms.  All
> of these are methods for determining the color of a pixel based on certain
> data.  If we give up world-building (see above), we no longer have the
> necessary information to shade pixels properly.  We need to provide a
> general way to shade pixels, but not make any assumptions about how that
> shading should be done.  That, again, is a job for higher API levels.
> 

I believe their is away around this. Yes we couldn't directly support this
but we could emulate this using something similar to pluggable shaders
idea. The use of color functions to map colors to the framebuffer.

> 
> 	So, what are we left with?  Essentially, we are left with two
> basic concepts: 3D drawing and 3D shading.  That is all we need in our
> API. But of course there are features we will need to have in order to 
> implement these primitives cleanly and with maximum flexibility.  So now 
> we get to the specifics of the LibGGI3D API design.

No problem. Plus this is all modern 3D cards do.

> 
> 	The first feature is the notion of a camera.  This is just two
> sets of 3D coordinates which specify a viewpoint and a direction.  This is
> necessary to map the 3D coordinate space onto the 2D coordinate space of
> the display.

Yes. The frame buffer becomes the finite 2D view plane in 3D space. 

> 	Next is the notion of triangle drawing.  LibGGI3D will have only
> one drawing function, DrawTriangle().  The triangle is the fundamental
> object of LibGGI3D.  All other 3D shapes can be tesellated into triangles,
> which are the prototypical polygon.

Yes. Also can use RAPID for collison detect. RAPID is fast but only works
with triangles

> 
> 	Next is the notion of pluggable shaders.  A triangle is drawn by
> setting a bunch of pixels.  What shade those pixels are can be determined
> in a huge number of different ways.  LibGGI cannot possibly avoid bloat if
> it has to know about all those ways to shade triangles.  Therefore,
> DrawTriangle can take a pointer to a shader table entry, which contains a
> pointer to a shader function.  Thus, the code using LibGGI3D can implement
> arbitrary shaders and LibGGI3D doesn't need to know about the gory
> details.  Both prebuilt shader functions (SHADE_PHONG,
> SHADE_GORAUD_TEXURED, SHADE_FLAT, etc) and user-defined shader functions
> go in this table.  The prebuilt shaders allow DrawTriangle() to use
> hardware shading if it is present, or fall back to software shading if it
> is not.

Great Idea. I will put together the idea of the color function to similate
shading, lighting, and texture mapping.

> 
> 	So, all LibGGI3D does is draw shaded triangles in a particular
> coordinate system.  End of story.  With these simple tools, almost any
> type of 3D hardware/software acceleration combo can be used and used
> fairly well.  Many common 3D video cards are based on triangles, and for
> those that are not (infinite planes, polygons) we can still use triangles
> or collections of triangles to represent polygons or polyhedra.

I couldn't agree more.

> 
> III. Design specifics.
> 
> * struct camera { float x1, y1, z1, x2, y2, z2 }. Every LibGGI3D display
> will have a camera struct attached to it.  A generic hook for arbitrary
> display data should also be present - the shaders might use it.  void
> *private_data. 
> 
> * int DrawTriangle (float x1, y1, x2, y2, x3, y3; shader_index shader; void
> *shader_data) is the core drawing function.

Should go into the kgi drivers accel.

> 
> * int DrawTriangleSet(triangle_set *triset; shader_index shader; void
> *shader_data) draws set of triangles, which can be used to draw polyhedra
> for hardware like infinite planes.  If future hardware can draw surfaces
> directly, triangle-based surface patches can be used with this function as
> well. 

Should kgi drivers support triangle sets? IMHO no.

> 
> * shader_index register_shader(shader_func *myshader) registers a custom
> shader function with the system and returns an index into the shader
> table.

No problem. KGI drivers can support that in accel. Also software emulation
can be small if you use my color funtion idea. One line of code for each color
component. 

> 
> * int unregister_shader(shader_index myshaderindex) unregisters a shader. 
> On GGI_exit(), all registered shaders are forcibly unregistered.
> 
> IV. Other stuff (FAQs)
> 
> Q: What about z-buffering?  You said you were going to make that part of 
> the API.

Think about that more in depth. No pun intented. Think about allocating
frames and labeling them as specific types.
 
> A: I changed my mind.  Once you start worrying about buffers, their
> dimensions, their layout, their coordinate system, etc etc you open up a
> whole can of worms.  If people want these features, they can either write
> a DirectBuffer equivalent or draw to a secondary depth buffer.  LibGGI3D
> is for drawing only.  Extra stuff should have its own API. 
> 
> Q: Why are coordinates floating point numbers?
> 
> A: Because it aloows for finer control of rasterization, perspective
> transforms and can easily be quantized into integer coordinate systems
> when needed.
> 
Yes and floating point on most platforms is alomost the same speed in
clock cycles as interger math.

> Q: Why do you use that shader table thing?  Why not just pass a pointer to
> a shader function directly to DrawTriangle()?
> 
> A: Because the drawing functions need to be able to know what type of
> shading is being used if they are to be able to use hardware shading.  So,
> you need a fixed set of shader types that are defined and come with the
> library.  Since the system has to know which shader functions go with
> which SHADER_* constants, it makes sense to use the constants as an index
> to a table.  And if you are treating the stock shaders this way, you might
> as well use the same system for the custom shaders.
> 
> Q: If I draw a triangle close to the camera and then draw another one much
> farther away such that the first, closer triangle should occlude the
> second, further one, the second one instead is drawn over the top of the
> first one!  Isn't that wrong behavior?
>

Possible Z buffer. Or could use culling for cheesy hidden surface
removal.
 
> A: Nope.  LibGGI3D does not concern itself with hidden surface removal. 
> None of the triangles are "aware" that the others exist.  Remember,
> there's no 3D world here.  If you want a 3D world, write LibGGI3Dworld or
> use OpenGL.