JVerge Version Beta 4 Copyright Justin Couch The Virtual Light Company 1996 justin@vlc.com.au A GNU production. See the file GNU.txt for licensing conditions as this code is released under the GNU Library Copyleft. JVerge is a set of Java classes that mimic the VRML node structure as closely as possible allowing you to abstract your design away from the browser interface and deal with getting things done. The source for this code can be found at ftp://ftp.vlc.com.au/JVerge/ Last updated 11:30 +10.00 22nd June 1997 http://www.vlc.com.au/JVerge/ --------------------------------------------- Introduction This beta release contains a much improved version of JVerge since the beta 3 release. Many things have been simplified, cleaned up and expanded and every node has undergone complete testing to ensure that they work in the correct fashion. JVerge is completely independent of the PAI that you wish to use. All you need to do to move the code from an applet to script or standalone is change the import line. Great care has been taken to ensure that the behaviour is identical between the three versions so that you don't need to re-code each time you change. This is the final beta before 1.0 release. Javadoc documentation is almost complete for all nodes, and a number of accessories have been added to the core JVerge classes. Courtesy of the IICM PW parser, you can now read in VRML files and generate the corresponding set of JVerge classes which allow you to add it directly to the scene. --------------------------------------------- Differences between beta 4 and beta 3 Entire package has now been tested. Barring bugs in the individual VRML browsers, all functionality is complete. Besides the usual round of bugs fixing these are the major improvements: - Script nodes now implemented. Some debugging may be necessary, but not anticipated. - ALL classes are now based on generic VrmlObject class. The external and internal VrmlObject classes are derived from the generic one. This adds amazing portability to your application as you now, no longer need to re-write the internal data passing mechanisms. Instead, youcan pass around generic.VrmlObject and then cast it to the internal or external version as required by the situation. Much stuff has been moved to this common base class/ There are variables to control the output and appearances. - writeToStream method has changed parameters. The PrintStream has been dropped in favour of a static variable in the generic VrmlObject which is used by all classes. The old method has been retained as a backwards compatibility issue, but do not expect to see it in the final release code. - node output has been completely rewritten from scratch. MFfields have protected methods in generic.VrmlObject to print the values out nicely. the wrapLevel field in VrmlObject can be set to specify how many values should be printed out per line. This applies to every node with MFFields in it except the SFImage and coordIndex of IFS and ILS. Check out the beautiful output now! - File reading capabilities introduced. Combining JVerge with the PW parser from IICM, the writers of the VRWave VRML browser, now allows you to read in a VRML 97 file and generate a set of JVerge classes to be added to the scene. All nodes are correctly handled, except PROTO/EXTERNPROTO, please see later for more details. - Full cloning support. If you clone a node, every single node underneath it is also cloned resulting in an entirely separate, yet identical copy of the scenegraph. --------------------------------------------- Differences between beta 3 and beta 2 Heaps! So much, that I can't list them all here, so these are the major changes. - Huge amounts of cleanup in internal coding. There where quite a number of cut and paste bugs for method names, and in particular the getEventIn/Out methods where stuff can sneak by undetected by the compiler. - There were some significant problems with people passing in null pointers to remove nodes. At times this was causing browsers like Cosmoplayer to crash. - The Switch and LOD nodes have had the add/remove methods removed. These were not VRML spec compliant so they were deleted (Switch does not have a addChoice eventIn for example). - Nodes that take MFNode eventIns - like Group, Transform etc now take proper node arrays. In previous versions the add/removeChildren methods only took a single ChildrenNode reference which is incorrect because the equivalent VRML eventIns were MFNodes node SFNodes. - The writeToFile method has been renamed to writeToStream to better reflect what it really is. The method writes to a generic Java stream which could be a file, but could just as equally be a Socket, string or for serialisation in Java 1.1 - All classes now implement cloneable. _However_, cloning is not properly supported. If you clone a grouping node, it will not recursive clone all its children to produce a replica of the scenegraph. This will be implemented in beta 4 - Beginnings of Javadoc documetation. This is not really official, All the file headers are done and some of the methods. There is no official javadoc distribution with beta 3, but if you wish to run it yourself over the packages, then soe semblence of reasonable output will be generated. - Automatic DEF/USE. If you pass the same reference through to a number of different nodes in the scenegraph it will automatically apply DEF/USE constructs to the string output. The only minor cost of this is that you need to call a reset method before writing out the scenegraph. - Internal version has changed the getEventIn methods to getExposedField calls when dealing with exposedFields. A number of browsers were known to be unable to handle getEventIn calls to exposedFields. --------------------------------------------- Differences between beta 1a and beta 2 - To make way for the internal scripted code, I have had to move the external code down a level in the package hierarchy. Any code that used the original libraries will need to change the import line to import vlc.vrml.external.geometry; The internal code is in vlc.vrml.internal.geometry; The generic code is in vlc.vrml.generic.geometry; - There are also a set of implementations of the Scripting exception classes in vlc.vrml.internal.exception if you require them (usually they should come with the browser). - Collision Proxy is now supported. Unfortunately due to the limits of the specification, A full implementation compliant with the spec cannot be done within the framework of the JVerge programming model. However, I think you will find the tradeoff more than acceptable. To accomodate the use of proxy children the complete node constructor (not the default one) offers you a boolean to say whether you want proxy children or not. If this is set to true then the code will produce a group node as the proxy field. In this group you can then add any children that you like, courtesy of the addProxyChildren, removeProxyChildren, set_proxyChildren and get_proxyChildren methods. This roughly is equivalent to what you would be doing in a text file anyway, so I believe this is an acceptable solution. The printed out code also includes this extra Group node. - Lots of big fixes. One that stands out is the set_ methods of any node that contains an SF/MFNode field. If you passed it a null (ie to remove the node in the field) it was silently exiting the method when I tried to access child.node. Blame Netscape's VM implementation for this one. This error should be generating a NullPointerException but does not in NS 3.x. - RemoveChildren eventIn methods of the grouping nodes suffered from a cut and paste bug. I was passing the nodes to the _addChildren field, rather than the _removeChildren field DOH! --------------------------------------------- Installation Simply unpack the files into any directory and add that directory to your CLASSPATH. For simplicity I recommend that you put the files into a directory that is already part of your CLASSPATH like c:\java\classes\ for PC users and /usr/local/java for UNIX geeks. Note that for these files to run then you MUST already have the External Application Interface and/or java scripting libraries installed. The browser does not need to be operational for the class files to be used, but the files must be available. If you want to run using just the standalone version (vlc.vrml.generic.*) then neither of these classes are needed. After that, start using them by importing them in the usual way - import vlc.vrml.external.geometry.*; I have included a sample file (VrmlRoot.java) in the root package of each version so that know how to create a root node for your scene graph given a basic grouping node at the root of the VRML world. --------------------------------------------- Features: o Complete implementation of all VRML 2.0 nodes including Script nodes. PROTO and EXTERNPROTO structures are not supported. The libraries are independent of the browser used and it's implementation of the EAI or JSAI. If you wish to have them display in the browser then you must supply an instance of the browser reference. o Complete faithfullness to the VRML 2.0 specification (with the noted exception for Collision node proxy fields). Nodes can only have field access during construction. ExposedField and EventOut values can be queried for their current value - direct from the browser. For the generic interface, you cannot get the current eventOut values - becuase they don't exist! No methods for these exist. I should probably implement dummy methods here than return default values for a complete coverage. o Complete Scene graph output capability to whatever stream you want. One call to the writeToFile method with your required PrintStream and the output is dumped for the scene graph under that node. Very handy for debugging and also creating VRML editors. For example you could open a streamed source like a TCP Socket to a remote host and directly dump your VRML output. o Enforces the scoping rules applied by the VRML node structure. You cannot add the wrong childtype node to another node. It follows the VRML 2.0 spec to the letter. You can for example add a WorldInfo node as a child of a Transform. o Automatic DEF/USE in the output stream saving lots of file size. --------------------------------------------- Bugs and Notes: - While my code has been debugged, that does not necessarily imply that you will end up getting the correct behaviour from the Browser. I've been running the code on both Live3D and CosmoPlayer PC and the differences are huge. - Your mileage with the internal variant may vary. From early alpha testers of this code I know that CommunityPlace does not implement the getEventIn method correctly. For normal eventIns it has no problem, but for exposedFields it barfs and causes an exception. - There is no protection on a lot of the methods if you try to read a value from an eventOut field and do not have the applet/application talking to a VRML browser. The idea is that the libraries are designed for speed. Adding all the extra overheads of copying or cloning fields is a really big killer for speed. It will either cause a NullPointerException or just crash. You have been warned... Send bug reports to: jverge_bugs@vlc.com.au ---------------------------------------------- About PROTO/EXTERNPROTO Support JVerge does _not_ support PROTO/EXTERNPROTO directly. There are many reasons for this. Firstly, JVerge uses the java class mechanism to enforce correctness on the programmer. PROTOs can exist that replicate any node in VRML which makes life exceedingly difficult when it comes to making a single PROTO class to handle all prototyped nodes. While it is possible to write one, it also means reducing compiled time checks to an unacceptable level and increasing runtime checks meaning more overheads and slower code for you. If you want to see what sort of a mess it can make - check out the internal or external implementations of the Script node. I thought I could write horrible looking C code, just wait until you see that stuff! Secondly, JVerge is a philosophy of doing things. Each class represents a node. A PROTO is not a node per se, but a way of constructing new nodes. When you declare a PROTO in a file, you are creating a template, but not actually creating a node instance. This is the same with the Java classes. A PROTO can be thought of as the .class file sitting on the harddrive, while the nodes are real instances of that file. With this in mind you should see that I am saying, if you have custom nodes that would exist as PROTOs, then you should be deriving the appropriate class to build the PROTO. This then allows you to do your own rules checking at compile time against the standard classes. I assume that this is what most people are going to be using the classes for, rather than reading in a VRML file to place into a scene. Having said all this, generic proto support may appear in a post 1.0 version of JVerge. ------------------------------------------------- About the File Reader Included in this release of JVerge is a complete file reader -> JVerge class parser. The basis of this is the GNU LGPL PW parser from the guys at VRWave. The code will be included in a separate download, but please make sure that you use the code that comes with this distribution. I've had to make a number of major changes to the parser to get things to work correctly. The VRWave team have promised to roll these changes into thier release code, but that won't happen for a while yet. Please keep checking the website for updates, and updated code. The file reader is in its first beta form, having previously gone through a number of small scale alpha tests. I'm very confident in its stability and correctness at this very early stage, but it needs more testing before I am 100% happy. The code exists in the various util directories under vlc.vrml.external/internal/generic. You will also need a file to start the parsers. I have written a test application that is placed in the VermelGen directory directly under where you unpacked the JVerge class files. (that is JVerge is in the /vlc directory and the parser test file is in /VermelGen). Change to that directory and unse the command line java ParserTest vrml_file.wrl to see it print out the contents of the file in a nicely formatted way. If you see any bugs in the output please notify me. Of course, if you complain that PROTO nodes don't appear, your mail message will find my trash folder very quickly. To see what I have been testing against, there are a number of VRML source files in that same directory. The torture test is called test2.wrl. This contains every single VRML node in various guises. Loading it into a web browser probably wouldn't be a good idea, as the nodes are designed to test the capabilities of JVerge, and not the browser! ------------------------------------------------ As usual insert the usual legal crap in here about use of the product and no warranty yadda, yadda, yadda. Hey, you take, you try, you tell me if you like or not and any bugs. Justin Couch 22nd July 1997