Re: [Plib-devel] Work outstanding.

[Gil C. <g.c...@ca...>]

>   * Dave has shelved his Blender-VRML loader for a while and asks for 
> help with
>     continued development.  If this 'Blender-VRML' subset is the best 
> interchange
>     format between Blender and PLIB then we'd better write an exporter 
> too so that
>     Blender and PrettyPoly can exchange files too.

That sounds like me...  I'll have a look at where Dave's up to with this 
loader tonight.  I assume it's somewhere in the CVS repository?

I might as well throw a couple of my future ideas into the ring before they 
even make it to the design stage (true vapourware!) to see if they're of 
interest to others.  (These ideas come _after_ the VRML loader, I promise!)

puTrace
~~~~~~~

Basically a benchmarking and information library which developers can link 
against during development for timing and rendering stats.  I'm influenced 
by Performer's perfly program here, so the kinds of things I'm thinking of are:

* app/cull/draw times
* frames per second - peak and averaged
* number of tris in view frustum
* tri strip lengths
* textures loaded
* state information
* toggle rendering between different modes - flat, shaded, wireframe etc
* lighting on/off
* lots of other things too!

puTrace would be a library in addition to the main PLIB core, and would 
look after measurement and display of all of these parameters.  Using the 
right #if directives, the trace can be left in the source, but compiled out 
for release versions of software.

As a possible extension, the display of puTrace information might be 
available on a networked machine - in other words, the main app links in 
puTrace to do the measurements, and the results are sent over a TCP/IP 
connection to another machine which then displays them.

The secondary display application will also be a PLIB app, set up to 
receive and display the stats.  This way, the main machine's rendering is 
"untouched" by puTrace, and the second machine can do much more in terms of 
logging results without affecting the main app under test.  Since puTrace 
will already have the HUD code built into it for local hosting of debug 
info, writing a remote version is almost a no-brainer.

puFly
~~~~~

*Very* similar to perfly - IOW, a program which can load and display any 
type of PLIB compatible model, but allows interactive display of rendering 
stats and a graphical display of the scene graph.  Obviously, this package 
will link puTrace in, and make heavy use of it.  In fact, my plan for 
testing puTrace is to write puFly anyhow, so it's almost going to fall out 
as by-product.  (Gee, is the phonetic pronounciation for puFly "POO-fly"?)

puFly would be a possible replacement for the current "tux on a box with 
panning camera" demo, and would allow a showcase of the features of PLIB. 
Hopefully.

For a rough idea of what perfly can do, have a look at this page which I've 
quickly cobbled together.

http://www.powerup.com.au/~gcarter/plib/perfly.html

It shows a couple of screenshots from perfly running on my O2 and 
displaying a simple model.  Perfly also runs on the Linux distribution of 
Performer if you've got it installed.

>   * Documentation - this is especially problematic for SSG which has 
> undergone
>     a TON of changes since 1.0.5-ish (which is the last time I did a serious
>     sync-up between the code and the manual).  The other libraries aren't
>     too far out of date - but they could probably be read against the header
>     files to be sure that every public function is explained for every class.
>     (as a minimum).

I'd *really* like to help with this.  Documentation is a pretty vital part 
of getting newbies running, so I'll see what I can do in this regard.  I'm 
thinking of HTML page per class, with member variables and methods 
documented.  Ideally, a code fragment also, but that relies on having a lot 
of little code fragments!

The Java guys use a neat system called Javadoc, which allows comments 
embedded in code to be cross-compiled into documentation.  You need to use 
some special tags in the comments for the parser to find, but it works 
really nicely if people do it as they go.  Assuming that the comments are 
up to date, a documentation update is as simple as running the Javadoc 
parser through the source.  http://java.sun.com/products/jdk/javadoc/ if 
you're interested.

There are a number of packages which do the same thing for C++, and I was 
going to have a look at Doxygen, which seems to be quite popular - 
http://www.stack.nl/~dimitri/doxygen/  I'll post some findings about this; 
the last thing I want is to suggest other developers use some weird 
commenting system which most people will just ignore.  It has to be easy 
enough to use that it's almost no effort.

As some more general reference material, I'd also like to reference some 
other papers - mostly from SGI - about real time rendering issues.  Eric 
Haines' website at http://www.realtimerendering.com also has a treasure 
trove of good information.  These links plus other local docs would form 
some basic self help for people who land at the PLIB project without enough 
background in realtime 3D to be able to just jump in and start using PLIB.

Comments?

Gil