README

# Copyright (C) 1998 Tuomas J. Lukka
# DISTRIBUTED WITH NO WARRANTY, EXPRESS OR IMPLIED.
# See the GNU Library General Public License (file COPYING in the distribution)
# for conditions of use and redistribution, EXCEPT on the files 
# which belong under the mozilla public license.

Welcome to a developer-alpha release of VRML::Browser.
See below for what has changed.

For updates, see the FreeWRL homepage, currently at 
http://www.fas.harvard.edu/~lukka/freewrl

DO NOT EXPECT YOUR COMPLICATED WORLD TO WORK!
If your world doesn't expect *much* more than the browser provides
right now, please send me a copy -- I'll make it work in the next
version. 

Textures are probably the last thing I'm going to make really well --
if you want to change that, buy me a computer with Linux-supported
3D acceleration for textures and you'll find them working in the next
release (even lending a machine for some months would do) ;) ;) 
-- or just fix the implementation yourself. Same applies to a multi-threaded 
version and multi-CPU machines ;)

See the file INSTALL for how to compile this program.

After installation, try

	./freewrl tests/1.wrl

(the file browse is the perl script which starts the browser -- if
there is a problem ("file not found"), try

	perl browse tests/1.wrl

or change the first line of "browse" to find your perl binary).

This should open a new window with a view of the VRML world in question.

Use the first and third button of your mouse (while moving your mouse)
to move around.

To change viewers between walk and examine, press 'w' or 'e' or 'd' in 
the browser window ('d' only works with the keyboard currently).

There are more tests in the bt/ and jt/ and pt/ directories, which
are, respectively, the browser API tests, java/javascript tests and
perl API tests.

E-mail any comments, questions & patches to me at lukka@fas.harvard.edu

	Tuomas J. Lukka

P.s. I am available for employment after july 1999 - email me if your
university or company is interested. I would like to be able 
at the same time to continue free software development and research.

-----------------
V0.14 DOCUMENTATION!!!!!!!!!
 - manual pages, at last! Halleluyah!
 - more extrusion fixes from Bernhard Reiter
 - Viewer&Navigationinfo fixes from John Breen
 - added "-lz" into vrml.conf for PNG
 - new command line interface
   NOTE NOTE NOTE!!!!!!!!!!!
   YOU HAVE TO CHANGE YOUR XSWALLOW SETTINGS FOR THIS RELEASE
 - warn if file doesn't start with the proper header
 - moved many optional behaviours from environment variables
   to command-line options.
 - more verbosity cleanup
 - added warning for missing proper header, corrected headers of 
   example files
 - other, tiny things

V0.13 Java EAI, other tiny things. 
AS OF THIS RELEASE, ALL "MAJOR" COMPONENTS HAVE FRAMEWORKS IN PLACE.
AFTER THIS, ENHANCING FREEWRL WILL CONSIST OF FILLING OUT 
UNIMPLEMENTED BITS IN THE FRAMEWORK. I NEED HELP IN THIS; IF YOU
WANT TO GET TO FILL IN YOUR PIECE (and get mentioned in the CREDITS
file, the coolest place on the web ;), EMAIL ME!
 - better way of doing trig stuff from Robin Williams
 - make the 'v' and 'b' keys really *WORK* for changing viewpoints on fly
 - make viewpoint orientation finally work (Thanks to John Breen
   for telling me about it)
 - make MFFloat and MFInt32 parsing handle the case "5 , 3 , 2"
   correctly - thanks to Etienne Grossmann for noticing the bug
 - new Extrusion code by Bernhard Reiter
 - new option zpl=xx to set the farther z-buffer plane in case you 
   want to view extremely large worlds
 - first shot at Java EAI!
   Most things still do not work but it's a start. We are communicating.
   See java/eai/test.java for an example (it uses the VRML in eai/test2.wrl).
   This is my second Java program, and the first one that
   uses threads (the first java program was the Script interface ;).
   Please comment if I'm doing anything wrong.
   The second example (java/eai/test2.java, eai/test3.wrl) demonstrates
   how to both receive & send events.
 - Inlines should work again (oops ;)
 - complain if url is bad
 - PNG/PNG.xs *should* now work with perlapio as well....
 - first shot at working navigationinfo, but I didn't have time to
   test it yet...
Continuing compliance tests:
 - fixed lineset & pointset coloring behaviour
 - fixed unlit behaviour when no Material node present
 - fixed SFNode, MFNode PROTO fields (we need lots of really devious tests!)

V0.12 
 - EAI first attempt
   - protocol only, no Java classes yet
   - try it with "perl eai/t1.pl", which starts freewrl
     and uses sockets to communicate the color change event.
   - it works by giving a command-line argument "eai=host:port"
     to connect into.
   - sometimes the processes live after they should die - 
     kill them explicitly if this happens
 - clean up the JS verbosity a little..
 - allow "url=..." command-line argument to freewrl for setting
  the base url separate from file name (to allow use of inlines
  from inside Netscape).
 - fix sensors so that transformations won't affect dragging 
  (NIST PlaneSensor test 2)
 - fix examine viewer to take position given to it seriously
 - make top-level sensors work
 - fix x_changed and set_x names to work
 - let images be scaled
 - PNG support
 - cache URLs when loading - same texture several times
 - set next/previous viewpoint (use keys 'v', 'b')
 - fixed texture mapping a bit

NOTE: v0.11 is NOT PUBLICALLY ANNOUNCED and contains a lot of
unstable new stuff. Be careful with it. I'll follow with 0.12 soon.


V0.11 - Onset of promiscuity -- we can plugin to netscape!!!
      - lots of new, not-thoroughly-tested features
 - set window name to FreeWRL
 - final changes to make it possible to run freewrl from another
   directory - e.g. fonts so that we specify the font at startup and
   "use blib" conditionalized. Including
    FREEWRL_FONTS=... perl -Mblib=... freewrl "$1"
   into xswallow's dispatch-vrml did it! Yow! (remember to redirect
   stdout and stderr to some file (e.g. /tmp/VRMLlog) to see what went
   wrong - it's by no means foolproof and doesn't load even nearly all
   files)
   However, this is probably worth a screenshot!
   If you try it, remember to Edit/Preferences/Netscape/Applications
   in netscape to inform it that x-world/x-vrml is handled by the plugin.
   (if you have problems, email me)
 - plugging into netscape made me fix a variety of bugs because
   I can browse worlds easier.
 - rest of the Light nodes
 - VisibilitySensor (very dumb but compliant - always visible)
 - environment variable (I know, I should document them all in one place ;)
   FREEWRL_SAVE to specify a directory to save all the files/urls in the
   world (not the whole world, just the world you're looking at ;)
 - fixed CoordinateInterpolator initial value
 - fixed Interpolators initial state - no event to be sent.
 - first try at ProximitySensor
 - fixed SFInt32 parsing (oops)
 - ElevationGrid: colors!
 - TextureTransform (but not yet tested)
 - render sky correctly when only one skycolor given
 - Inlines work again

There is one big problem with the URLs: relative URLs don't work
from the 

V0.10 - Yea!
 - fixed YEQ, ZEQ tests for raycasting - sensors should be more
   reliable now when the ray is parallel to some axis. Oops.
   Thanks for Bernhard Reiter for the report.
 - VRML::Field::Multi ISA VRML::Field -> MF* things in PROTOs now
   work. Thanks to John Breen for the bug report and fix.
 - actually included tests/10.wrl (oops ;) 
 - viewpoint fixes galore - jump=TRUE viewpoints should now work
   completely. jump=FALSE is more difficult but luckily less used.
   Thanks to several people for bugging me about it ;)
 - box touchsensor now works properly even when looking on the xz plane
 - make an environment variable FREEWRL_NO_COLORMAP to prevent
   creation of window's own colormap - thanks to William R. Ward
 - more documentations / organizations in the source
 - new Walk viewer from John Breen
 - Events.pm: ToQueue so you can send events TO a node instead of just
   from

V0.09 - bugs & docs
 - fixed a bad parser bug, reported by Bernhard Reiter.
   now [1 1 1,2 2 2,3 3 3] works as it is supposed to.
 - commented VRMLC.pm and VRMLRend.pm
 - fixed prototypes & events -- now they should finally work
   closer to the spec
 - new demo: tests/10.wrl which was my challenge to myself to
   improve the javascript api to include SFVec3f and SFRotation
   functions.
 - as a result, JavaScript api now has SFVec3f and SFRotation
   methods ;)
 - now viewers should get the shift / control status as extra
   arguments - so the Descent mode is possible to do with mouse
   (as requested by John Breen).
   Didn't have time to improve the descent mode yet, though.

V0.08 - important details
 - using libwww-perl for getting documents from over the web.
   we can use general URLS, hurray!
   Because of this, perl scripts are now disabled by default
   because of security -- the code is completely trusted and
   we don't want you to get http://evil.foo/rm-rf.wrl containing
   a Perl script doing "system('rm -rf /'')".
 - use gunzip to decompress gzipped content
 - general ray code -- now IndexedFaceSet, ElevationGrid and even
   Extrusions should work with TouchSensors
 - "install" should now at least partially work. 
   Changed all "require 'foo.pm'" to "require VRML/foo.pm"
 - get_scene for the browser object -- now it is possible to
   create scenes in Perl scripts:
    "
    	use VRML::Browser;
	$b = new VRML::Browser;
	$s = $b->get_scene;
	$nod1 = $b->new_node(Shape, {
		geometry => $b->new_node(Box, { ... } ),
		...
	});
	...
	$s->topnodes([$nod1,$nod2,...]);
	$b->eventloop;
    "
   so you can use scripts to generate scenes.
 - then, use $scene->as_string to actually generate the VRML code
   in ASCII.
 - $backend->snapshot. See pt/* for samples
 - Documentation
 - Make the browser accept some faulty VRML (commas after field values)
 - Some portability fixes from John Breen and Lupe Christoph
 - fix IndexedFaceSet core dump if coordIndex doesn't end in -1
 - some event fixes. 

V0.07 - quick bug fixes
 - parse: make the optimization for MFFloat and MFTime correct when
   there are commas :(
 - fix FontStyle defaults
 - stabler quadratic solution from Robin Williams
 - background works again -- we can't displaylist something that moves ;)
 - better viewpoint implementation -- it still doesn't quite work
   like the spec. 

V0.06 - solidification:
 - input of SFColor etc. to javascript
 - output of floats etc. from javascript
 - numerous other bugfixes for javascript...
 - beginnings of the browser object in Perl
 - add OpenGL includes/defines for other makefiles as well..
 - Text should possibly be compatible with FreeType-1.1 now...
 - Fly mode, with key controls a la Descent(TM)!! Press 'D'
   when browsing and then use a,z and 789uiojklp; (the keys
   that are the numpad on my laptop ;) to move. If someone
   wants to send a patch to make the keys configurable, I'd be 
   delighted ( I don't want to spend time on that right now, I 
   have more important matters in this to do.. )
 - much faster MFFloat parsing -- similar speedups for other fields
   are just a matter of doing it..
 - various speed improvements
 - fixed use of display lists to actually work (blush)..

V0.05 - details...
 - Switch
 - LOD
 - face culling -> double speedup sometimes
 - DirectionalLight
 - PlaneSensor
 - SphereSensor
 - better support for bindable nodes
 - dummy Anchor ( == group )
 - add many missing fields (as dummies) to nodes

V0.04
Quick release, due to notification from Thomas Dudziak that
I had missed important files from the .tar.gz file. Oops...
 - Text!!!!!!! With FreeType library
 - Background basics (skyColor, skyAngle)
 - VRMLC -> VRMLC+VRMLRend - split to smaller files
 - Bindable nodes -- see nodes/Background2.wrl for what works now

V0.03 "filling in some blanks"
 - MFColor and other field types for javascript -- now able
   to run VRML97 spec example D.14!!


V0.02 "some things about *most* features work"
THIS RELEASE IS ESPECIALLY UNSTABLE - LOTS OF CODE HAS BEEN ADDED 
AND LOTS OF NEW FEATURES ARE SEMI-IMPLEMENTED. THERE ARE PROOF-OF-PRINCIPLE
JAVA AND JAVASCRIPT SCRIPTS BUT MOST OF THOSE SCRIPTING INTERFACES
ARE STILL UNIMPLEMENTED. THE PROOF-OF-PRINCIPLE SCRIPTS CAN BE FOUND
IN THE DIRECTORY jt/.

THE BROWSER IS STILL FAR FROM SPEC COMPLIANCE -- A LOT NEEDS TO BE DONE.
IF YOU ARE NOT ABLE TO PROGRAM, DO NOT EXPECT TO BE ABLE TO USE THIS
BROWSER YET. THIS RELEASE IS PRIMARILY MADE TO ATTRACT POTENTIAL
DEVELOPERS TO HACK ON THE CODE.

 WHAT EXTRA IS SUPPOSED TO WORK NOW
  - simple scripting in complex languages (java,javascript)
    (warning: this is very immature so far - it's my first ever java
    program and I've only been at it for a couple of days. You have to
    make a named pipes in the current directory with the name '.javapipep'
    and '.javapipej', with the command "mknod .javapipep p" or the equivalent
    on your system).
    For javascript, you'll need to hack it to compile yourself - I'll
    try to provide a better make system later.
  - simple complex uses of simple sensor (touchsensor hitpoint,
    although only for primitives yet (no indexedfaceset :(...))
    This is by raycasting now, see VRMLC.pm
  - simple textures: jpg only, and only 2**n * 2**n.
    also, most texture mappings of nodes are not yet correct
  - Extrusion, ElevationGrid
  - Billboard
  - Browser: die if file not openable
  - Parser: accept ROUTE et al in more contexts 
  - CoordinateInterpolator
  - IndexedLineSet and PointSet
  - Shape with appearance==NULL
  - Color, Normal
  - more fields for supported nodes
  - Inline (preliminary)
  - beautify tests/ a little
 WHAT STILL DOES NOT WORK
  - more complicated things of any particular kind:
    - sensors
    - extrusions which are collinear
    - ...

SPECIFICALLY: FOR SCRIPTS IN JAVA/JAVASCRIPT:
 Eventin floats work and eventout colors work, not much else.
 Of course, this will be very easy to expand later (next version I hope
 to have MFthings and everything except Nodes.

 These scripting implementations are to be considered very preliminary and 
 just proof-of-principles.

 Especially the javascript interface is VERY UGLY. And contains
 unfinished code.

V0.01 "some things work"
 WHAT IS SUPPOSED TO WORK
  - simple primitives (box, cone, cylinder, sphere, indexedfaceset*)
  - simple sensors (touchsensor, timesensor)
  - simple languages (perl)
  - simple nodes (scalarinterpolator,...)
  - simple structures (PROTO, USE/DEF)
 WHAT IS NOT YET IMPLEMENTED
  - complex geometries (elevationgrid, extrusion)
  - complex sensors (cylindersensor etc)
  - complex languages (java, javascript)
  - complex nodes (switch, lod...)
  - complex structures (anchor, externproto...)

(* indexedfaceset only partly implemented)