[Rbgl-discussion] RBGL starting manual

[John P. <cap...@ya...>]

Ok, here's a really rough start on that manual.  It was really
structured when I started it but things sorta fell appart as the day
went on.  Anyway it's a start.


RBGLSpace			This is the base control where all the graphics are
rendered.  This is basically our version of the RB3DSpace control.

Properties
	ClearBackground		Boolean		If true, clear the bounds of the RBGLSpace
when display is updated.
	BackgroundColor		Color		Color to clear to if ClearBackground is set to
true.  Same as SkyColor in RB3D.
	BackgroungObject	RBGLObject	Background graphics, same as Background in
RB3D except uses RBGLObject.
	FieldOfView			Integer		Field of view in degrees.
	Hither				Integer		Distance cut off point.
	Yon					Integer		Proximity cut off point.
	FogStart			Integer		Starting point for fog.
	FogVisible			Boolean		Render fog is true.
	Objects				RBGLGroup	Same as in RB3D except uses an RBGLGroup.
	

Methods
	Update							Causes the area to update all graphics.
	FrustumCull(RBGLGroup)	 		Culls objects based on the frustum routine
(objects that are not within the camera's field of view are not
rendered).  Later there aught to be several culling routines available
for the developer to choose between fro custom culling.
	
	The following are identical to the same routines in RB3D except they
use the RBGLLight object.  Beyond this I'm still having trouble
deciding on how to actually handle lighting procedures, so I haven't
gone any further.
	AddLight(RBGLLight)
	Light(Integer)
	LightCount() As Integer
	RemoveLight(Integer/RBGLLight)
	

Events
	CullObjects(RBGLGroup)			Here is where the developer can opt to cull
out objects that don't need rendering.  I plan to implement several
culling routines that they can choose from based on what is necessary
depending on the program they are writing.  This routine must return
true to acknolege that something was done, otherwise RBGL will default
with the Frustum cull alone.



RBGLObject			This is the base object class.  Specific types of geometry
objects will be based on this class.

Properties
	DisplayListHandle	Integer		Display lists are a way to kind of pre-load
rendering instructions for a set of geometry.  It's much faster this
way.  Display lists are ideal for geometry that won't be changing
shape, which is easily a majority of the objects that will be rendered.
 This is the handle to the object's display list if the developer
actually wants to access it.
	UseDisplayList		Boolean		In some cases you won't want to use a display
list (like the player's character which would be constantly changing
shape as they move).
	MaterialColor		Color		Before an object is rendered you can set its
overall color tone.
	UseMaterialColor	Boolean		Things like this one could question the
usefullness of, but it's an option in OpenGL so by all means I'm
including it.
	Translucency		Double		Generally this would be something that is a part
of an object's actual geometry, but I know a lot of people out there
will want this option on a nice broad level like this, so we'll try to
implement it.

**There are unique issues when handling translucency.  Except it rare
cases, OpenGL will be set to not bother rendering objects in back of
others (this is different from culling), and as such objects behind a
translucent object won't be drawn.  How this is handled is you first
draw all solid objects, THEN draw translucent objects in back to front
order.  Heh, yeah, we'll worry about actually implementing this feature
when the time comes.**

	Scale				Double		These both work just like in RB3D
	Visible				Boolean
		
The following work just like the equivalent properties in RB3D except
they use RBGL objects.  There should also be a way to pass and use the
RB3D classes (more on this later)
	Bounds				RBGLBounds
	Orientation			RBGLQuaternion
	Position			RBGLVector
	
Methods
	Update				This will tell the object to commence the OpenGL rendering
procedure.  This really will only be used by the RBGLGroup class, or
when updating the display list (it's not really for the actual
developer)
	UpdateBounds		Simply updates the Bounds property.
	UpdateDisplayList	Should the geometry change you may need to update
the display list.  This routine simply tells OpenGL that a DisplayList
is about to be rendered, calls the Update method, then tells OpenGL
that we're done.

Events
	CalculateBounds		Since doing this calculation depends on how the
actual data is stored, it has to be handled by the subclass.
	Render				This is where the drawing routines are actually done, since
they depend on the specific object and how the data is stored.



RBGLGroup		This is our version of the Group3D.  It is subclassed from
the RBGLObject class, so it will also have position, orientation, etc.

Methods			These all behave identically to their equivalent methods in a
Group3D.
	Append
	Count
	Item
	Remove



General design philosophy

	Perhaps it comes from my lack of decisiveness, but I want provide the
developer with numberous options for various aspects of the
environment, meanwhile leaving a solid default.  How I want to handle
culling procedures is a good example of this.

	I don't know how familiar you are with culling routines or what they
do, so I'll give a brief explaination.  Basically every piece of
geometry you tell OpenGL to render will be attempted, even if it won't
be displayed.  So if an object is behind another, or isn't even on the
screen, OpenGL will still consider it while calculating what to draw. 
It's usually way more efficient to figure out if something isn't
necessary to attempt than to tell OpenGL to draw it anyway.
	This, I figure, should all optional because it's possible that the
developer won't even need a culling routine at all; and the specific
routine needed may change from project to project.  Thus I want to have
plenty of premade options available, to minimize development time, and
just set frustum culling as the default.

	Along with a wealth of options (for many things), I really want the
developer to be able get inside RBGL instead of working outside/around
it.  I find that with RBGL the developer would have to work around it
and, in a sense, translate to work with the interface.  A good example
here would be how objects are stored and rendered in RB3D, versus how I
would like to handle it.  In RB3D you are limited to using the
QD3D/Quesa 3D object format.  RB3D only loads 3DMF files, so if you
want to use anything else (an industry standard file perhaps?) you not
only have to translate, but use Quesa declares to load it.  And then it
can be a pain to work with the data for certain uses, like level of
detail routines (where the geometry is manipulated for detail based on
distance).  With RBGL I don't want to have a standard data format that
the developer is forced to use.  A RBGLObject is simply a base class
that serves as a basic structure.  It is up to subclasses to load,
store, and render the data.  This leaves things wide open for the
developer to easily create their own data formats and still be working
with the RBGL interface, not around it.

	I'm not sure how well I'm describing all this(concepts are hard to get
across), so don't worry if you're confused.

	When passing information like verticies to OpenGL you can pass 3
seperate numbers, or a pointer to an array that contains the data. 
Passing this data in a single MemoryBlock would be much more efficient
(not just for the developer, but also in terms of speed) than accessing
the X, Y, and Z properties of a Vector3D object.  Where possible I
would like to allow this option to the developer.  As such, it would
make sence to create a parallel set of classes that behave just like a
Vector3D, Quaternion, Bounds3D, or whatever, except it would be a
subclass of a MemoryBlock so that it can be passed directly to OpenGL. 
However I would like to maintain an interoperability with those classes
that are already a part of RB3D.  This would be simple enough, and give
the developer even more options.
	In general it can actually be a lot more efficient to use MemoryBlocks
anyway.  I'm not certain but it might actually be faster than an array
(I should probably contact Real Software to find out for sure).  Anyway
wherever it makes sense (and we're able to keep it from getting
awkward) I think we aught to use MemoryBlocks to store large amounts of
data (like loaded 3D objects) while providing accessors for those who
don't want to muck around with the data on that level.

	A special consideration we might make at some point is for 2D
graphics, since OpenGL isn't at all designed for 3D alone.  I'm not
certain if we should bother or not really, considering what trouble it
might be to implement both 2D and 3D capabilities into the same
control.  However for the sake of completeness I feel almost
responsible to do so.  Perhaps we can work on it later, or even create
a parallel control to handle this.  I'm not sure, what's your take on
the matter?


	I think my brain just fried.  I know this is all pretty incomplete,
especially for a manual, but pretty much anything that's missing is
identical to how it is done in RB3D.  I'd work on this a bit more but
right now I just want to get it to you as a starting point and it can
be tuned/fixed later.  Forgive me if everything here jumps around a
lot, I give myself much direction (figuring this as a jumping off point
anyway).

	Any way while writing all this I cracked open the old project that I
started months ago, and it looks a lot better than I remember it.  I
based much of what's here on that project.  I tweaked a few things in
it and tossed in some Windows code so it might work, but I have no way
of testing it.  I'm going to send it to you as an attachment in a
seperate email.  The only querk I'm certain there will be is it will
probably render to the whole window, or do something funny like that
(can't be sure, since I can't test it).  At least it will give you
something to tweak and start with.  Even if you can't get it to work,
give it a look.  Actually running through the code should give you an
idea of the overall structure I'm going for (since I'm pretty certain
that my descriptions above are unclear- I'm not thinking too straight
today it seems).

Ok I need sleep.  I think there were other things I ment to say to you
but there long gone by now.  I've been working on this all day off an
on so I'm sorry if it's a bit unstructured.  I think I said that.. Yeah
I need sleep right now.

Enjoy,
    - John


		
____________________________________________________
Start your day with Yahoo! - make it your home page 
http://www.yahoo.com/r/hs