xenial (1) dune.1.gz

Provided by: whitedune_0.30.10-2_amd64 bug

NAME

       dune - graphical vrml97 editor and animation tool

SYNOPSIS

       dune  [  variantoptions  ]  [  stereoviewoptions ] [ inputdeviceoptions [ axisoptions ] [ miscoptions ] [
       file.wrl file.x3dv file.xml ...  ]

       dune [ conversionoption ] filename

       dune -illegal2vrml [ -prefix prefix ] protofile.wrl file.wrl ...

DESCRIPTION

       dune / white_dune is a graphical editor for the  Virtual  Reality  Modeling  Language  (VRML97),  ISO/IEC
       14772-1:1997.
       Additionally it has support for the NurbsSurface Node described in VRML97 Amendment 1.
       white_dune can also load and store VRML encoded X3DV files
       It can also load X3D files with XML encoding, if configured to use a commandline vrml97/x3d translator.
       A filename of - means standart input.
       Dune  has  some  basic  support  for stereographic view usually with shutterglases in OpenGL "quadbuffer"
       mode.
       When used with the conversionoptions or the  -illegal2vrml  commandline argument,  white_dune  is  a  non
       graphical commandline program.
       The  conversionoptions  are  used  to  convert  the VRML/X3DV file into sourcecode or a other 3D graphics
       format. This options are used in the commandline, but some options require a graphics  context  (e.g.  in
       the simplest case a usage within a xterm command), cause some of the conversion options require the usage
       of OpenGL commands. To create a OpenGL context, there are 3 different ways.
       First open a temporay graphics window, do the conversion and close the graphics window and exit. This  is
       currently used under M$Windows.
       Second  is  to  use  Mesa off screen rendering (the program was compiled with the --with-osmesa configure
       option). With Mesa off screen rendering it is possible to use  OpenGL  commands  in  a  pure  commandline
       program.
       Third  is to use glx based off screen rendering under Linux/UNIX/MacOSX.  In this case, no the program do
       not open a graphics window, but requires a working X11 display anyway. On a text  console  the  Xvfb  X11
       server program can be used to get a working X11 display.
       The  -illegal2vrml  option is used to repair VRML97 files with illegal extensions.
       See the illegal2vrml(1) manpage for more information.

VARIANTOPTIONS

       -4kids start dune with a simplified GUI as simple 3D modeller for kids.

       -x3dv  if no file is loaded, start dune with a new X3DV file.
              Per default, dune is started with a new VRML97 file.

       -kambi start dune with support for unportable extension nodes only usable with the kambi VRML gameengine.

       -cover start  dune  with  support  for  unportable extension nodes only usable with the special immersive
              VRML97 viewer cover/covise.

       -4catt start dune with a simplified GUI as a exporter/converter for users of the CATT 8 sound  simulation
              software.

       -bw    Use black and white icons instead of colored icons

       -german
              Use german menu, dialogs and errormessages

       -italian
              Use italian menu and dialogs, errormessages are still in english language

       -english
              Use  english  menu,  dialogs  and  errormessages. This is the default can be used to overwrite the
              setting of the LANG environment variable.

CONVERSIONOPTIONS

       -vrml97
              Convert file to VRML97 ISO/IEC 14772-1:1997, write it to standart output and exit.

       -vrml97levelx3dv
              Convert file to VRML97 ISO/IEC 14772-1:1997 compatible parts of X3D classic VRML encoding  ISO/IEC
              ISO/IEC 19776-2:2005, write it to standart output and exit.

       -x3d   Convert file to XML encoded X3D, write it to standard output and exit.

       -kanim filenamepattern
              Convert file to the kanim fileformat and write it to standard output.
              The  kanim  fileformat  is  a XML file with references to different VRML files. The VRML files are
              generated too, their name is generated based on filenamepattern: The filenamepattern  is  shortend
              from  the  fileextension  and  then  extended  with a underscore, a increasing number and the .wrl
              extension.
              All VRML files describe the same VRML scene with same the  nodes,  but  some  numeric  fields  are
              animated.
              This  type  of  file is used by the open source VRML based Kambi gameengine.  It makes no sense to
              export a kanim file, if the exported  VRML  file  do  not  contain  timesensor/interpolator  based
              animation.

       -wonderland moduleDirectory
              Convert  file  to  a  java  source  file  included  in a directory structure needed to build a SUN
              wonderland version 0.5 module and exit.
              If the root directory of the module is build  from  the  input  filename  (without  extension)  as
              moduleDirectory/exportX3dv/filename
              If  this  directory  and the other needed files do not exists, this files are also created. If the
              other files exist, they are not overwritten, only the target java source  itself  is  overwritten.
              The        name        of        the        target        java        source        file        is
              moduleDirectory/exportX3dv/filename/src/classes/org/jdesktop/wonderland/modules/filename/client/jme/cellrenderer/filename.java
              The first character of the target java source file is uppercase.
              To  get  a  wonderland  module from the moduleDirectory/exportX3dv/filename directory, chance into
              this directory and run the ant command. A usual jar file of the  wonderland  module  can  then  be
              found in the moduleDirectory/exportX3dv/filename/dist directory.
              When  compiling  the  output  of  the wonderland java source export with the command ant, the java
              compiler may get out of memory resources.
              To fix the problem, you can set the  memory  limits  by  extending  the  javac  tag  in  the  file
              wonderland/build-tools/build-scripts/build-setup.xml e.g.
              <javac ...
                     ...
                     fork="true"
                     memoryinitialsize="256m"
                     memorymaximumsize="1024m"
              >
              Currently,  the  -wonderland  option  only  support static 3D modeller output without animation or
              interaction.
              These features are work in progress and are still to be done.
              This option uses OpenGL commands.

       -x3d4wonderland
              Convert file to XML encoded X3D for import in SUN wonderland 0.4, write it to standard output  and
              exit.
              SUN wonderland 0.4 only support IndexedFaceSets with colorPerVertex and fullsize Color nodes. This
              exporter tries to convert other nodes to this IndexedFaceSets, but can (currently)  not  correctly
              convert nodes with colorPerVertex false and fullsize Color nodes.
              This option uses OpenGL commands.

       -ac3d  Convert file to the AC3D format (Version AC3Db), write it to standart output and exit. This option
              uses OpenGL commands.
              The AC3D file format is the input/output file format of the 3D modeller ac3d.
              The ac3d 3d modeller do not support several features of VRML/X3D (e.g. the ac3d 3d modeller do not
              support  animation  or  interaction).   Therefore  the  AC3D file format can not keep the complete
              information of a VRML/X3D file in general.

       -catt8geo outputdir_with_material_geo
              Convert file to the catt geo format (Version 8), write it to several .geo formats to the directory
              outputdir_with_material_geo and exit.
              The catt geo file format is the input geometry file format of the catt acustic simulation program.
              The  master.geo  file in this directory outputdir_with_material_geo will hold include commands for
              the other produced .geo files.
              In the directory, a file material.geo with the needed ABS commands must exist  before  conversion.
              The material names for the ABS names are generated from the DEF names of the VRML nodes.
              If  the  material.geo  file  do not exist in the outputdir_with_material_geo directory, white_dune
              fails with a errormessage.
              Despite the catt programm can export VRML97 files, it do not support several features of VRML/X3D.
              Therefore the catt geo file format can not keep the information of a VRML/X3D file in general.
              This option uses OpenGL commands.

       -ldraw Convert file to the major part of the ldraw fileformat and write it to standard output.
              The header of the ldraw file is not generated. The header is a important part of a ldraw file  and
              should have been written to standard output earlier (typically this is done from a batch script).
              The  ldraw fileformat is a ASCII fileformat which is used to exchange 3D data between several open
              source plastic brick description programs. A example for such a program is LeoCAD.

       -prefix prefix
              The -prefix option in conjunction with conversion is only used for the following options to create
              source  code. It can be used to define a leading prefix for the name of the data structures in the
              source code output.
              For example, the source code creates data types named  "Node",  "Scenegraph"  and  "Callback".  To
              avoid  problems  with  other libraries, adding options like for example "-prefix X3d" would change
              the names to "X3dNode", "X3dSceneGraph" and "X3dCallback".

       -c     Converts file to a C header/source file, write it to standard output and exit.
              Currently, information about routes are not exported.
              See section C/C++/JAVA SOURCE EXPORT for more information.

       +c prefix
              This option is very similar to the -c option, but writes a incomplete source file,  which  can  be
              concatinated to a sourcefile written by the -c option.
              The names of the new defined datatypes in the sourcefile start with the prefix argument.

       -3c    This  option is similar to the -c option, but surfaces are first triangulated and then exported as
              TriangleSet nodes.
              This option uses OpenGL commands.

       +3c prefix
              This option is very similar to the -3c option, but writes a incomplete source file, which  can  be
              concatinated to a sourcefile written by the -3c option.
              The names of the new defined datatypes in the sourcefile start with the prefix argument.

       -meshc This  option  is  similar to the -c option, but surfaces are first converted to a polygon mesh and
              then exported as IndexedFaceSet nodes.

       +meshc prefix
              This option is very similar to the -meshc option, but writes a incomplete source file,  which  can
              be concatinated to a sourcefile written by the -meshc option.
              The names of the new defined datatypes in the sourcefile start with the prefix argument.

       -c++   Converts file to a C++ header/source file, write it to standard output and exit.
              Currently, information about routes are not exported.
              See section C/C++/JAVA SOURCE EXPORT for more information.

       +c++ prefix
              This  option is very similar to the -c++ option, but writes a incomplete source file, which can be
              concatinated to a sourcefile written by the -c++ option.
              The names of the new defined datatypes in the sourcefile start with the prefix argument.

       -3c++  This option is similar to the -c++ option, but surfaces are first triangulated and  then  exported
              as TriangleSet nodes.
              This option uses OpenGL commands.

       +3c++ prefix
              This option is very similar to the -3c++ option, but writes a incomplete source file, which can be
              concatinated to a sourcefile written by the -3c++ option.
              The names of the new defined datatypes in the sourcefile start with the prefix argument.

       -meshc++
              This option is similar to the -c++ option, but surfaces are first converted to a polygon mesh  and
              then exported as IndexedFaceSet nodes.

       +meshc++ prefix
              This option is very similar to the -meshc++ option, but writes a incomplete source file, which can
              be concatinated to a sourcefile written by the -meshc++ option.
              The names of the new defined datatypes in the sourcefile start with the prefix argument.

       -java  Converts file to a java source file, write it to standard output and exit.
              Currently, information about routes are not exported.
              See section C/C++/JAVA SOURCE EXPORT for more information.

       +java prefix
              This option is very similar to the -java option, but writes a incomplete source file, which can be
              concatinated to a sourcefile written by the -java option.
              The names of the new defined datatypes in the sourcefile start with the prefix argument.

       -3java This  option is similar to the -java option, but surfaces are first triangulated and then exported
              as TriangleSet nodes.
              This option uses OpenGL commands.

       +3java prefix
              This option is very similar to the -3java option, but writes a incomplete source file,  which  can
              be concatinated to a sourcefile written by the -3java option.
              The names of the new defined datatypes in the sourcefile start with the prefix argument.

       -meshjava
              This option is similar to the -java option, but surfaces are first converted to a polygon mesh and
              then exported as IndexedFaceSet nodes.

       +meshjava prefix
              This option is very similar to the -meshjava option, but writes a incomplete  source  file,  which
              can be concatinated to a sourcefile written by the -meshjava option.
              The names of the new defined datatypes in the sourcefile start with the prefix argument.

       -manyclasses
              Only valid after the -java, -3java, -meshjava or -wonderland options.
              This option is a brute force attempt to fight against the "too much constants" problem in java. It
              may be impossible to compile the output of a normal java  based  source  code  export,  cause  the
              current  format  of  java  class  files  are  limited  to 64K so called "constants". Not only real
              constants like 1, 2 or 3 are counted, but also things like member variable definitions in  classes
              etc.
              With the -manyclasses option, all data is distributed into many seperated classes.
              The  -manyclasses option should help, if you run into the "too much constants" problem. In case of
              a large number of DEF commands in the vrml/x3dv file, you can still run into "too much  constants"
              problem,  cause  each DEF commands leads to extra member variable in the main scenegraph class. In
              this case, you should reduce the number of DEF commands with the menupoint  actions  ...  rest  of
              scenegraph branch ... remove ... DEF name
              Beside  the  need to increase the memory limits of the javac compiler (-Xms/-Xmx) options, you may
              also need to increase the PermSize memory  limits  (-XX:PermSize=/-XX:MaxPermSize=)  of  the  java
              interpreter.

STEREOVIEWOPTIONS

       -nostereo
              force non stereoview mode on Linux/UNIX (e.g. if you do not own shutterglases)

       -stereo
              force stereoview mode.
              Stereo is only supported for hardware/software combinations, that allow quadbuffer stereo ("stereo
              in a window"), NOT splitscreen stereo (eg. "OpenGlVR").
              Examples for hardware/software combinations with support for quadbuffer stereo  are  graphicscards
              with support for shutterglasses or "stereo cloneview" to connect beamers of a onewall.

       -anaglyph glassestype
              force expermential stereoview mode for use with colored anaglyph glasses.
              glassestype can be red_green, green_red, red_blue or blue_red.
              This  option  uses  the  OpenGL  accumulation  buffer.  This is not hardware-supported by a lot of
              graphics cards/graphics drivers and can result in miserable performance.

       -eyedist eyedistinmeter
              Distance between the two eyes of the viewer.
              Default eyedistinmeter is 0.06, it can be negative to swap  eyes  (no  need  to  reconfigure  your
              hardware if eye swapping problems occure).

       -screendist screendistinmeter
              Distance between the eyes of the viewer and the mid of the monitor screen.
              Default screendistinmeter is 0.8.

       -fieldofview fieldofviewindegree
              Overwrite Field of View field in VRML viewpoints and set to fieldofviewindegree in degree.
              Good stereoviewing may want need to ignore the fieldOfView field of viewpoints. The fieldOfView of
              the human eye is about 18 degrees, the VRML default is 45 degrees.

INPUTDEVICEOPTIONS

       The following options are only valid, if dune was compiled with matching inputdevice driver support (e.g.
       there is not support for a Linux joystick under IRIX).

       -joystick joystickdevice
              Only valid under Linux or M$Windows.
              Under   Linux,  joystickdevice  is  the  device  of  a  Linux  joystick  (usually  something  like
              /dev/input/js0 or /dev/js0).
              Under M$Windows, the joystickdevice is a number. Depending from the M$Windows version, this number
              is either 0, 1 or a number from 0 to 15.

       -SDLjoystick joystickdevice
              Currently only valid under MacOSX.  The joystickdevice is a number (e.g. 0, 1, 2, ...).

       -spaceball spaceballdevice
              spaceballdevice is the serial device connected to the spaceball (usually something like /dev/ttyd2
              or /dev/ttyS0).
              Only valid if binary was compiled with libsball support.

       -nxtdials usbdevice
              This option support a dials like inputdevice made of mindstorms nxt motors.  Just attach  a  wheel
              or  gear  to each of 3 motors, connect them to the brick and connect the brick to the computer via
              USB.
              This option is only valid, if white_dune was compiled with support  of  the  libusb  library  e.g.
              available under Linux.
              usbdevice  is the number of the mindstorms nxt brick connected via USB (0 for the first nxt brick,
              1 for the second nxt brick, etc).
              The -nxtdials option automatically set the wheel axisoption.

       -xinput xinputname
              xinputname is the devicename supported by the Xinput Protocol (usually something like magellan  or
              dialbox).
              Valid on most Unix/X11 implementations.

       -xinputlist
              Print  a list of Xinput devicenames that can be possibly used as xinputname for the -xinput option
              and exit.
              Valid on most Unix/X11 implementations.

       -xinputlistlong
              Print a list of Xinput devicenames with axis information and exit.
              Valid on most Unix/X11 implementations.

       -aflock aflockdevice  [ aflockoptions ]  -tracker birdaddr -wand birdaddr
              aflockdevice is the serial device connected to the Ascension Flock  of  Birds  master  transmitter
              (usually something like /dev/ttyd2 or /dev/ttyS0).
              Dune assumes the following configuration:
              Multiple  FOBs with single RS232 Interface to Host Computer (see "The flock of Birds, Installation
              and Operation Guide, Standalone and Multiple Transmitter/Multiple Sensors Configurations", Page  3
              (chapter "Introduction"), Figure 2).
              birdaddr  is  the  adress  of  the Bird Unit of the magnetic head tracker (-tracker) or "3D Mouse"
              (-wand) in the Fast Bird Bus (FBB adress) as configured with the dipswitches on the Bird Unit.
              This program need to have the Flock of Birds configured in the Normal Address Mode only (see  Page
              12, Figure 4 of the manual decribed above).

       -headnavigation
              Use current transformmode (including rotations) when using a headtracker.
              Default without -headnavigation is using only the translation mode.  This default gives you a very
              natural reaction, when your head moves, the virtual world moves, but if your  head  only  rotates,
              the  virtual  world  stand still. With the headnavigation option, the virtual world reacts to head
              rotations, depending of the current transform mode. Be carefull when you use  this  feature  while
              talking  to  a audience. Talking cause small and fast head rotations and will cause small and fast
              rotations of the virtual world.  Your audience may get a impression like in a  earthquake  and  is
              more in danger to get motion sickness.

       -sendalways
              Tell  dune  that the device sends (almost) always values. This values will then not be interpreted
              automatically as transform commands.
              Automatically used for Ascension Flock of Birds device (-aflock).

       -dontcarefocus
              Inputdevice actions dont care about the window focus.
              This can be useful in situations, when you only work with one  dune  window,  e.g.  when  using  a
              onewall.

AXISOPTIONS

       -x|-y|-z|-xrot|-yrot|-zrot=[-][integer_axisnumber]
              [,[factor][,[accel][,[wheel][,ignore]]]]

       -all|-allxyz|-allrot=[factor][,[accel][,[wheel][,ignore]]]

       -none=integer_axisnumber

       -axes=max_number_axes

AXISLEGEND

       -      used to swap sign of value from axis

       integer_axisnumber
              Integer with the number of the axis, that should be used for the x y z xrot yrot zrot directions.
              This number may not be greater than the number of axes of the inputdevice.
              The integer_axisnumber in the none option is used to disable this axis.

       factor Float with a multiplicator for the axes
              The  factors  of  the  all, allrot and allxyz options are independend of the factors of the single
              axes.

       accel  Float with a expotential accelerator for the axes

       wheel  The string "wheel" means this axis of the inputdevice will not deliver zero if released

       ignore Float with the value (relative to the maximal  value  from  the  device)  which  will  be  ignored
              (insensitivity)

       max_number_axes
              Number of used axes, one of (2,3,4,5).
              This  must  be equal or less to the physical available axes of a device. Main usage of this option
              is to disable bad designed or mechanical defect axes e.g. when you wish, this axis on  a  joystick
              would not exist

AFLOCKOPTIONS

       This options are only valid for the Ascension flock of birds magnetic tracking system.

       -baud baudrate
              Baudrate of the serial line communicating with the transmitter.
              According  to  the  flock  of  bird  manual,  the  following  baudrates  are valid for serial line
              communication: 2400, 4800, 9600, 19200, 38400, 57600 and 115200.
              Default: 38400

       -numbirds numberbirds
              Number of "data delivering" birds attached to the transmitter (e.g. not counting  the  transmitter
              itself, if it is a Extended Range Controller (ERC)).
              Default: 2 (tracker and wand).

       -master birdaddr
              Adress  of  the  master  transmitter  in  the  Fast  Bird  Bus (FBB adress) as configured with the
              dipswitches on the transmitter unit.
              Default: 1

       -masterIsErc
              Used to differ between configurations, where the master is a ERC (Extended  Range  Controller)  or
              not.  If  the  master is not a ERC, the FBB adress is the same as the FBB adress of the tracker or
              the wand.
              Default: not set

       -hemisphere FRONT_HEM|AFT_HEM|UPPER_HEM|LOWER_HEM|LEFT_HEM|RIGHT_HEM
              Hemisphere used. Sit on the antenna block (with the legs near on the side of  the  text)  to  see,
              what is left or right 8-)
              Default: RIGHT_HEM

       -sync 0|1
              Synchronise (1) or not (0) data output to a CRT (Monitor) or your host computer.
              Synchronisation is used to elimiate magnetic effects of a Monitor using the CRT sync cable.
              Default: 0

       -block 0|1
              Set (1) or do not set (0) the FNDELAY flag to the filedescriptor of the serial port.
              Default: 0

       -filter AC_NARROW | AC_WIDE | DC_FILTER
              Enable different filters. Read the Flock of Birds manuals for more information.
              This option can be repeated to use multiple filters.
              Default: no filter set, using filter set by Flock autoconfiguration.

       -suddenchangelock 0|1
              Allow  (0)  or  disallow  (1)  setting  of  messured  position and orientation when a sudden large
              messurement occure.
              Default: 1

       -calfile calibrationfile
              Use a VR Juggler style file to calibrate position messurement.

       -ignoresize delta
              Ignore position jumps from flock bigger than delta.  This is much like suddenchangelock, but  pure
              software based.
              Default: 0

MISCOPTIONS

       -tessellation integer
              Set the default tessellation of NURBS and superformula based parametric shapes to integer.
              The meaning of tessellation decide how many edges are generated in one direction.
              A low default tessellation result in faster rendering of related shapes with tessellation set to 0
              inside the white_dune application, but can give a reduced view, so  details  of  a  shape  may  be
              hidden.
              If no -tessellation option is used, the default tessellation is 32.

       -indirect
              Forces  indirect  OpenGL rendering, even when 3D hardware rendering accelleration is available. In
              case of possible 3D hardware rendering accelleration this option can  drastically  slow  down  the
              program.
              This  option  is most usefull on machines with problematic graphic drivers or halfbaken 3D desktop
              features like compiz.

       -uninstall
              Output information (if available) on the  commandline,  how  the  white_dune  application  can  be
              uninstalled and exit.
              Under  Micro$oft  Windows  it additionally clears all information activly set by white_dune (under
              HKEY_CURRENT_USER) in the Windows registry.

       -psn_???
              Only valid under MacOSX.
              Options starting with the string "-psn_" are generated by the Aqua desktop under on some  versions
              of MacOSX and are silently ignored.

       -fn font
              Only valid under Linux/UNIX/MacOSX.
              Set the unix font. Check for valid fonts with the xlsfonts(1) command.

       -demomode timeout
              This options is intended for running the program as eyecatcher eg. on a fair.
              The  option is only usefull, if a viewpoint animation is running.  In case of input from the mouse
              (mouseclick), keyboard or a 3D inputdevice, the animation is stopped  an  the  user  can  navigate
              through the 3D world.
              timeout seconds after the last input, the viewpoint animation is not supressed anymore.

       -filedialogdir directory
              Change to a specific directory before opening a filedialog.

       -proto category protofile
              Adds  the  VRML PROTO in the file protofile to the list of available PROTOs in the create => proto
              menu in the category submenu and exit.

       -renderslower
              This option uses a slower render mode.

       --version
              Print out version information and exit.

       --copyrightdetails
              Print out detailed copyright informations and exit.

MOUSE/KEYS

       In the 3D view, dune support the following mouse / keyboard commands:

       Mouse Button 1 click:
              Select objects/3D handlers (e.g. arrows or white boxes) under the cursor (or under the top  of  3D
              cursor in stereoview)

       Mouse Button 2 click:
              Additionly  select  white  box  3D  handlers  under  the  cursor (or under the top of 3D cursor in
              stereoview)

       Mouse Button 1 drag:
              Drag objects/3D handlers around

       CTRL-Mouse Button 1 drag:
              Virtual trackball navigation

       SHIFT-Mouse Button 1 drag:
              Forward/backward navigation

       CTRL+SHIFT-Mouse Button 1 drag:
              up/down/left/right navigation

       ALT-Mouse Button 1 drag: (SGI style)
              Virtual trackball navigation

       ALT-Mouse Button 2 drag: (SGI style)
              up/down/left/right navigation

       ALT-Mouse Button 1+2 drag: (SGI style)
              forward/backward navigation

       Navigation icon pressed-Mouse Button 1 drag:
              Virtual trackball navigation

       Navigation icon pressed-Mouse Button 2 drag:
              forward/backward navigation

       Navigation icon-Mouse Button 1+2 drag:
              up/down/left/right navigation

       In the route view, dune support the following mouse / keyboard commands:

       Mouse Button 1 click to event socket of a node and drag to a matching event
              socket:
              create a ROUTE connection

       Mouse Button 1 click to nothing and drag:
              cut a ROUTE connection

       Mouse Button 1 click to a node and drag:
              move node in the route view

       Mouse Button 1 click to a node, hold Mouse Button1, pressing Page Up/Down key
              move node in the route view by one page (works only on correct motif/lesstif implementations)

       Information about other keyboard usage can be found in the toolbar.

       Tips how to use dune can be found in the docs directory of dune
              (http://129.69.35.12/dune/docs/)

C/C++/JAVA SOURCE EXPORT

       The export to source code is a export of the information (numbers and strings) of the VRML/X3D scenegraph
       tree.
       White_dune  do not export something like C source with OpenGL commands.  The exported code is independend
       of any rendering engine, but can be used with any 3D API.
       Additional code is needed to render the scenegraph with a 3D API.  Currently white_dune comes  with  only
       one  set  of  such  additinal code for the Java Monkey Engine (JME). This code can be used as a model for
       writing code for additional renderengines.
       The information of the scenegraph is written into a class/struct with a name concatinated from the string
       of the prefix argument (default "X3d") and the string "SceneGraph". The scenegraph class/struct is filled
       with references to the different VRML/X3D commands ("nodes"). The name of the type  of  such  a  node  is
       concatinated  from  the string of the prefix argument (default "X3d") and "Node". Each node type contains
       the data of the VRML/X3D node in variables named in the same way as the VRML/X3D fields.
       The following table shows the mapping from the VRML/X3D field type to the C, C++ and java datatypes:

                          │              │              │
        VRML/X3D datatype │ C datatype   │ C++ datatype │ java datatype
       ───────────────────┼──────────────┼──────────────┼────────────────
        SFBool            │ short        │ bool         │ boolean
        SFInt32           │ int          │ int          │ int
        SFImage           │ int*         │ int*         │ int[]
        SFFloat           │ float        │ float        │ float
        SFVec2f           │ float[2]     │ float[2]     │ float[2]
        SFVec3f           │ float[3]     │ float[3]     │ float[3]
        SFVec4f           │ float[4]     │ float[4]     │ float[4]
        SFRotation        │ float[4]     │ float[4]     │ float[4]
        SFMatrix3f        │ float[9]     │ float[9]     │ float[9]
        SFMatrix4f        │ float[16]    │ float[16]    │ float[16]
        SFColor           │ float[3]     │ float[3]     │ float[3]

        SFColorRGBA       │ float[4]     │ float[4]     │ float[4]
        SFDouble          │ double       │ double       │ double
        SFVec3d           │ double[3]    │ double[3]    │ double[3]
        SFTime            │ double       │ double       │ double
        SFString          │ const char*  │ const char*  │ String
        SFNode (***)      │ X3dNode*     │ X3dNode*     │ X3dNode
                          │              │              │
        MFBool            │ short*       │ bool*        │ boolean[]
        MFInt32           │ int*         │ int*         │ int[]
        MFFloat           │ float*       │ float*       │ float[]
        MFVec2f           │ float*       │ float*       │ float[]
        MFVec3f           │ float*       │ float*       │ float[]
        MFVec4f           │ float*       │ float*       │ float[]
        MFRotation        │ float*       │ float*       │ float[]
        MFMatrix3f        │ float*       │ float*       │ float[]
        MFMatrix4f        │ float*       │ float*       │ float[]
        MFColor           │ float*       │ float*       │ float[]
        MFColorRGBA       │ float*       │ float*       │ float[]
        MFDouble          │ double*      │ double*      │ double[]
        MFVec3d           │ double*      │ double*      │ double[]
        MFTime            │ double*      │ double*      │ double[]
        MFString          │ const char** │ const char** │ String[]
        MFNode (***)      │ X3dNode**    │ X3dNode**    │ X3dNode[]
       (***) The "X3d" part of the name is the default, it can be replaced by the string of the prefix argument.
       For any MF* type field (and a SFImage type field) the number of int, float etc. values in  the  array  is
       stored  in a variable of the X3dNode struct/class composed from "m_", the name of the field and "_length"
       in case of a C/C++ export.  Java do not need such a variable, cause the  length  of  a  array  is  always
       available as with the .length component of the array.

       The  scenegraph is a tree of nodes. The root of the scenegraph is (similar to the white_dune internals) a
       VRML/X3D Group node named "root".
       In a Group node, the contained nodes are attached via a field named "children" of type MFNode.
       For example imagine the following VRML file:

       #VRML V2.0 utf8

       Group
         {
         children
           [
           Group
             {
             }
           Group
             {
             }
           DEF NAME_OF_FOGNODE Fog
             {
             color 1 0.50000000 1
             }
           ]
         }

       If no prefix argument is used, the first node in a VRML/X3D file is represended in the exported C  source
       as "root->children[0]" in the "X3dSceneGraph" struct.
       If  the  first node in the VRML/X3D file is also a Group node and contain three other nodes, the third of
       this nodes is represended as "root->children[0]->children[2]" in the "X3dSceneGraph" struct.
       If the third of this nodes is a Fog node, the "color" field  of  the  Fog  node  is  represended  in  the
       exported C source as "root->children[0]->children[2]->color" in the "X3dSceneGraph" struct.
       The type of the "color" field of the Fog node is SFColor. The SFColor type is represented as a array of 3
       floating point values in the C source, used to store the red, green and blue part of the color.
       So  the  green   part   of   the   fog   color   is   represended   in   the   exported   C   source   as
       "root->children[0]->children[2]->color[1]" in the "X3dSceneGraph" struct.
       A C++ export would also use "root->children[0]->children[2]->color[1]" in the  "X3dSceneGraph" class.
       A java export would similarly use "root.children[0].children[2].color[1]" in the "X3dSceneGraph" class.

       There is a second way to access the fields of the Fog node.
       In  VRML/X3D  it  is  possible  to  name  nodes  with  a "DEF" command. The string behind the DEF command
       ("NAME_OF_FOGNODE" in the example) also occures in the in the "X3dSceneGraph" struct and can be  directly
       used to access the matching VRML/X3D data.
       So the green part of the fog color is represended in the exported C source as "NAME_OF_FOGNODE->color[1]"
       in the "X3dSceneGraph" struct.
       A C++ export would also use "NAME_OF_FOGNODE->color[1]" in the "X3dSceneGraph" class.
       A java export would use similarly "NAME_OF_FOGNODE.color[1]" in the "X3dSceneGraph" class.
       A problem can occure, if the string behind the DEF command is a reserved keyword in the target  language.
       For example, the 3D modeller wings3d often uses the DEF name "default" when exporting VRML97 files.
       In  this  case,  the  DEF  name  will  be  renamed (e.g. to "default1") and a warning would be written to
       standard error during the export.

       Beside the access of node data directly, there are also 2 sets of callbacks to handle the data of a whole
       scenegraph  (or  a  branch  of  it):  a  set  of callbacks to render the content of the scenegraph branch
       ("*RenderCallback") and a additional set of callbacks for other tasks ("*DoWithDataCallback").
       There are also callbacks to replace the functions, which per default alltogether traverse the  Scenegraph
       ("*TreeRenderCallback" and "*TreeDoWithDataCallback").
       The callback mechanism and the scenegraph initialization differs from programming language to programming
       language.

       C:
       The scenegraph (default argument "X3d" for prefix) can be declarated with
          struct X3dSceneGraph sceneGraph;
       and initialized with
          X3dSceneGraphInit(&sceneGraph);
       A callback function for any X3D node type (like Fog, Text, IndexedFaceSet etc.)  has the declaration
          void mycallbackFunction(X3dNode *self, void *data)
       To access the fields of the X3D node, you usually cast the X3dNode pointer to a pointer to the type build
       from  the string of the prefix argument (default "X3d") and the name of the X3D node type you access with
       this callback (e.g. X3dFog, X3dText, X3dIndexedFaceSet etc.).
          X3dFog *node = (X3dFog *)self;
          X3dText *node = (X3dText *)self;
          X3dIndexedFaceSet *node = (X3dIndexedFaceSet *)self;
          etc.
       With this variable "node" the fields the X3D node can be accessed.
       To install the callback, simply assign you function pointer to "callbackFunction" to  a  variable   build
       from  the  string  of  the  prefix  argument (default "X3d"), the the name of the X3D node and the string
       "RenderCallback" or "DoWithDataCallback". E.g.
          X3dFogRenderCallback = mycallbackFunction;
          X3dTextDoWithDataCallback = mycallbackFunction;
          X3dIndexedFaceSetRenderCallback = mycallbackFunction;
       To run the Render or DoWithData functions with the scenegraph tree, just use
          X3dGroupTreeDoWithData(&sceneGraph.root, NULL);
       Instead of using NULL, other data can be passed to the "data" argument of the callback functions.

       C++:
       The callback mechanism is very similar to the C mechanism.
       The main difference is the storage of the callback functions. While the callbackfunctions in C are stored
       in global space, the C++ callbackfunctions are stored in the static part of the matching node type.
       Instead of using
          X3dFogRenderCallback = mycallbackFunction; // C
       a C++ program would use
          X3dFog dummy;
          dummy.renderCallback = &mycallbackFunction; // C++
       In C++ there is no need to call a initialization function. A constructor is called when the
          X3dSceneGraph sceneGraph;
       declaration is used.
       To  run  the  Render  or  DoWithData  functions  with  the  scenegraph tree "sceneGraph.render(NULL);" or
       "sceneGraph.doWithData(NULL);" is used.
       NULL can be replaced by other data, that will be passed to the "data" argument of the callback function.

       java:
       The java callback mechanism is a bit different, it is based on inheritance.
       The callback function is part of a class, that extends a matching class:
          class  MyCallbackClass extends X3dFogRenderCallback {
             public void render(X3dNode node) {
       The new class is used in the following example:
          MyCallbackClass myCallback = new MyCallbackClass();
          X3dSceneGraph sceneGraph = new X3dSceneGraph();
          X3dText.setX3dTextRenderCallback(myCallback);
          sceneGraph.render();

       With the the -manyclasses option, the last line changes to "X3dSceneGraph.render();".  The  access  to  a
       node with a DEF command in the x3dv/vrml file changes also to a static variable in a similar way.
       See  the  directories  docs/export_example_c, docs/export_example_c++ and docs/export_example_java of the
       source archive for examples.

EXAMPLES

       dune -nostereo
              start dune this way, if  you  have  a  stereo  capable  visual,  but  no  shutterglases  or  other
              shutterbased technology.

       dune  -xinput magellan -allxyz=10,100,,0.0000002 -xinput dialbox-1 -x=0 -y=2 -z=4 -xrot=1 -yrot=3 -zrot=5
       -all=1000,,wheel
              starts dune with a magellan xinputdevice with factor 10, acceleration 100 and a  ignore  value  of
              0.0000002 on the xyz axes and a dialbox device with
              x axis = 0. axis
              y axis = 2. axis
              z axis = 4. axis
              rotation around x axis = 1. axis
              rotation around y axis = 3. axis
              rotation around y axis = 5. axis
              all axes use factor 1000 and all to not deliver zero if released

       dune -joystick /dev/input/js0 -z=,3 -axes=3
              starts  dune  with  a linux joystick, set acceleration of the z axis to 3 and disables the 4. (5.,
              6., ...) axis.

       dune -xinput magellan -z=3 -xrot=2 -none=2
              starts dune with a xinput/magellan device, swapping axis number 2 and axis  number  3,  with  axis
              number 2 disabled.

       dune -nxtdials
              starts dune with a mindstorms nxt usb device, all axes are automatic handled as wheels.

       dune -aflock /dev/ttyS1 -numbirds 2 -master 1 -wand 2 -tracker 3
              starts  dune  with  a  Ascension  Flock of Birds.  Master transmitter (a Extended Range Controller
              (ERC)) at FBB adress 1 is connected to the serial device /dev/ttyS1, use 2 Birds, one attached  to
              a "3D Mouse" device at FBB adress 2 and one attached to a head tracking device at FBB adress 3.

       dune -wonderland wonderland/modules -manyclasses Test.x3dv
              Exports   the   content  of  Test.x3dv  as  java  source  for  wonderland  0.5  to  the  directory
              wonderland/modules/exportX3dv/test.
              To compile the java source to a wonderland module wonderland/modules/exportX3dv/test/dist/test.jar
              change the directory to wonderland/modules/exportX3dv/test and use ant.

FILES

       $HOME/.dunerc
       default file to load/store settings
       (see DUNERC environment variable for more information)

       $HOME/.dune_crash_*_*.wrl
              stores the vrml file in case of a crash

ENVIRONMENT

       DUNERC filename to load/store details of dunes screen layout and
              settings of the "options" menupoint.
              If this filename is not writable, settings are only loaded, not stored.
              If DUNERC is not set, the file $HOME/.dunerc is used under Linux/UNIX/MacOSX or the registry under
              Micro$oft Windows.

       DUNEDOCS  path to documentation directory

       LANG  the first two characters of then environment variable LANG
              are compared to the ISO 3166 country shortcut of the supported languages.  For example, if LANG is
              set to de_DE, german menu, dialogs and errormessages are used.

           Dune, graphical vrml97 editor and animation tool
           Copyright (C) 2000-2002  Stephen F. White and others
           This program is free software; you can redistribute it
           and/or modify it under the terms of the
           GNU General Public License
           as published by the Free Software Foundation; either
           version 2 of the License, or (at your option) any later
           version.

BUGS

       Dune need valid vrml97/x3dv code to work, it can not load a invalid VRML97/X3DV file.
       White_dune can load XML encoded X3D files via a translator.
       Use the menupoint Options -> Input Settings... to configure a X3D/XML to X3DV translator.
       dune  is software in development, it is not 100% free of bugs.  Unsucessful crashes should be rare, lucky
       crashes allow to get back the data. (see "EXIT STATUS").
       Currently  not  all  VRML97/X3D  nodes   are   displayed   (e.g.   MovieTexture,   NurbsSweptSurface   or
       NurbsSwungSurface) or displayed correctly (e.g. Text or Viewpoint).
       Please send bugmessages to the old dune bugtracker sourceforge page ⟨http://sourceforge.net/tracker/
       ?group_id=3356&atid=103356⟩

DIAGNOSTICS

       Exit status is 0 for sucessfull operation.
       Exit status is 1 if inputfile can not be sucessfully read or other initialisation error.
       Exit status is 2 in case of a X11 server crash.
       Exit status is 11 in case of a X11 initialisation error.
       Exit status is 97 in case one of the inputfiles is a VRML 1 file (the VRML 1 format is not supported).
       In case of a coredump/crash, the exit status can be undefined.

EXIT STATUS

       In case of a crash (e.g. X11 server crash or signal (coredump) in case of a internal error),  dune  tries
       to write it's contence to the file $HOME/.dune_crash_*_*.wrl

SEE ALSO

       illegal2vrml(1),  javac(1),  java(1),  Xvfb(1),  xterm(1),  v2x3d(1),  x3dv2(1),  FreeWRL(1),  lookat(1),
       cc3dglut(1), xj3d(1), cosmoplayer(1), cosmoworlds(1),

       ISO/IEC 14772
              ⟨http://www.web3d.org/x3d/specifications/vrml/⟩

       ISO/IEC 19776-2
              ⟨http://www.web3d.org/specifications/⟩

       NIST vrml97/x3d translators
              ⟨http://ovrt.nist.gov/v2_x3d.html

AUTHORS

       Stephen F. White and others
       See README file for details