Artur:
You are going to have a hard time convincing this group of this. I guess it
depends on what the target audience is for Java3d. If it is only for
experts of 3d graphics with experience specifically in OpenGL then perhaps
the documentation as it stands now is sufficient. Heres the issue... there
is a LOT of pages of documentation, yet often it is one line somewhere in
there that makes a huge difference to developers. For example somewhere in
the docs it says that Z in the java3d View system is toward the viewer. If
you miss that line it would never occur to you to translate the view
transform *backwards* in order to move your view *forwards*. In other words
you need to translate the view using a -z to move the camera into the
positive z direction (in terms of VR coordinates). Then there are the many
places where there is not enough information given to write efficient Java3d
code. Like knowing the impact to Morph nodes in supplying single frame with
a weight versus spreading it out over multiple frames, or that alpha blended
objects inside an ordered group are rendered in a different order than alpha
blended objects outside an ordered group. Or what blend modes are supported
in DecalGroup layers.. and what does it mean that the "geometry must be
coplanar but there is no guarentee that there will be no zbuffer
collisions"? Does that even make sense? So people spend countless hours
writing demo code just to figure this stuff out.
And heres the rub, you have arguably the four most experienced java3d
engineers on this list not counting the Sun engineers who have been asking
for better documentation. This is for several reasons. One is that we have
ourselves spent thousands of hours pouring over the documentation and
figuring out the little wierdnesses of Java3d. Then often a Sun engineer
drops by and answers the question with a single precise explanation, often
revealing a bit of how the engine is actually *using* the API to produce its
results. The second reason is that we spend a *lot* of time helping new
comers to Java3d through the same issues we ourselves went through long ago.
And the same questions over and over... "how do you make image plate aligned
geometry", "how come there is this canvas2d thing but when I use it the
frame rate drops to 1 frame every 5 seconds", or the ever popular "how do I
load a model into java3d?", or the even more popular question "how can I
save a scenegraph into a model?"
I think we see how great java3d is and widespread its use could be if the
learning curve was not so steep. Why is it that highschool students can
spend a few days at the www.opengl.org site and within a month they are
writing rendering engines in opengl... but the same people come to try
java3d and give up in disgust trying to do the simplest things? We want to
see Java3d become a pervasive standard in 3d graphics. While improving the
API and extending its functionality is important, the extensions will be
used by like 15 people at this point. Why isn't that number 5000 people?
Considering the pervasive nature of Java it would stand to reason that
Java3d would be a natural evolution for people wanting to do 3d programming.
yet I would hazard a guess that there are more people using the
java-to-opengl libraries to do 3d graphics than there are people using
java3d.
Dave Yazel
www.cosm-game.com
----- Original Message -----
From: Artur Biesiadowski <[EMAIL PROTECTED]>
To: <[EMAIL PROTECTED]>
Sent: Thursday, April 19, 2001 7:16 PM
Subject: Re: [JAVA3D] Documentation again
Justin Couch wrote:
> For example
> - tell me how WakeupOnSensorEntry works?
I think that Sensor class javadoc is quite enough to make sense out of
it.
Example of usage of WakeupOnSensorEntry class would be (my example after
reading docs for one minute) creating touch-and-expand menu (Johny
Mnemonic style) for virtual glove. View (head) would be in same place,
but hand (Sensor) would enter menu bounds and behaviour would fire up
(expanding menu with a lot of fx).
This is first time I've looked at Sensor/WakeupOnSensorEntry class. If
I'm right, then I think that docs are all right to person who never
touched a virtual glove and only by reading this very doc discovered
that hand position in this case has to be separate from view position.
As for the clockwise rule - yes I also agree it should be stressed very
clearly. But I don't think it should be mentioned in first chapter -
bold font note inside chapter about GeometryArrays and another one near
the PolygonAttributes CULL_* would be enough :) After all most people
are going to use externally created models anyway - and transforms,
branchgroups and appearances are a lot more important for them then raw
polygon creation rules.
I have nothing against good documention. I just do not think that
focusing at docs at cost of other things is a good idea - especially
given stability problems. Person can ask for help on net if he does not
understand a docs, but is helpless when app crashes on client machine.
Artur
===========================================================================
To unsubscribe, send email to [EMAIL PROTECTED] and include in the body
of the message "signoff JAVA3D-INTEREST". For general help, send email to
[EMAIL PROTECTED] and include in the body of the message "help".
===========================================================================
To unsubscribe, send email to [EMAIL PROTECTED] and include in the body
of the message "signoff JAVA3D-INTEREST". For general help, send email to
[EMAIL PROTECTED] and include in the body of the message "help".
