whitedune(1)

📦 version 0.30.10, in debian bookworm, ubuntu jammy, ubuntu noble, ubuntu questing

🌸 whitedune 🌸

okay bestie, welcome to the whitedune manual page — this is part of the General Commands Manual, and it's a whole journey, so buckle up 🫶

✨ NAME ✨

whitedune — graphical vrml97 editor and animation tool 💅

🦋 SYNOPSIS 🦋

whitedune [ variantoptions ] [ stereoviewoptions ] [ inputdeviceoptions
[ axisoptions ] [ miscoptions ] [ file.wrl file.x3dv file.xml ...  ]
whitedune [ conversionoption ] filename
whitedune -illegal2vrml [ -prefix prefix ] protofile.wrl file.wrl ...

💖 DESCRIPTION 💖

whitedune / white_whitedune is a graphical editor for the Virtual Reality Modeling Language (VRML97), ISO/IEC 14772-1:1997. no cap, that's the whole vibe.

On top of that, it has support for the NurbsSurface Node described in VRML97 Amendment 1. iconic.

white_whitedune can also load and store VRML encoded X3DV files. it can also load X3D files with XML encoding, if it was configured to use a commandline vrml97/x3d translator. yes, that's a whole if. 👑

A filename of - means standart input. yes bestie, the classic.

Dune has some basic support for stereographic view, usually with shutterglases in OpenGL "quadbuffer" mode. 🕶️

When it's used with the conversionoptions or the -illegal2vrml commandline argument, white_whitedune becomes a non graphical commandline program. lowkey a whole different creature.

The conversionoptions are used to convert the VRML/X3DV file into sourcecode or a other 3D graphics format. These options live on the commandline, but some of them require a graphics context (in the simplest case, like, using it inside an xterm command), because some conversion options need to run OpenGL commands. To create an OpenGL context, there are 3 different ways:

  1. Open a temporay graphics window, do the conversion, close the graphics window and exit. This is currently used under M$Windows.
  2. Use Mesa off screen rendering — the program was compiled with the --with-osmesa configure option. With Mesa off screen rendering it's possible to use OpenGL commands in a pure commandline program. ✨
  3. Use glx based off screen rendering under Linux/UNIX/MacOSX. In this case, no, the program does not open a graphics window, but it 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 whitedune with a simplified GUI as a simple 3D modeller for kids. 🧸
  • -x3dv — if no file is loaded, start whitedune with a new X3DV file. Per default, whitedune is started with a new VRML97 file.
  • -kambi — start whitedune with support for unportable extension nodes only usable with the kambi VRML gameengine.
  • -cover — start whitedune with support for unportable extension nodes only usable with the special immersive VRML97 viewer cover/covise.
  • -4catt — start whitedune 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, and it 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 an 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_whitedune 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". slay ✨

  • -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 — literally the -meshc option's twin flame, except it writes an incomplete source file that you can concatenate onto a sourcefile written by -meshc. The names of the new defined datatypes in the sourcefile start with the prefix argument. 💅
  • -c++ — converts file to a C++ header/source file, writes it to standard output and exits. Currently, information about routes are not exported. Go read the C/C++/JAVA SOURCE EXPORT section for the tea. ☕
  • +c++ prefix — basically -c++ again but it writes an incomplete source file, concatenatable onto a sourcefile written by -c++. New defined datatype names in the sourcefile start with the prefix argument.
  • -3c++ — like -c++, but the surfaces get triangulated first and then exported as TriangleSet nodes. Heads up: this option uses OpenGL commands. ✨
  • +3c++ prefix — the -3c++ twin: writes an incomplete source file, concatenatable onto a sourcefile written by -3c++. New datatype names start with the prefix argument.
  • -meshc++ — like -c++, but surfaces are first converted to a polygon mesh and then exported as IndexedFaceSet nodes. 🦋
  • +meshc++ prefix — the incomplete-file version of -meshc++, concatenatable onto a sourcefile written by -meshc++. New defined datatype names in the sourcefile start with the prefix argument.
  • -java — converts file to a java source file, writes it to standard output and exits. Currently, information about routes are not exported. See the C/C++/JAVA SOURCE EXPORT section. 🌸
  • +java prefix — same energy as -java, but writes an incomplete source file that can be concatenated onto a sourcefile written by -java. New defined datatype names start with the prefix argument.
  • -3java — like -java, but surfaces are first triangulated and then exported as TriangleSet nodes. And yes, this option uses OpenGL commands. 💅
  • +3java prefix — the incomplete-file twin of -3java, concatenatable onto a sourcefile written by -3java. New datatype names start with the prefix argument.
  • -meshjava — like -java, but surfaces are first converted to a polygon mesh and then exported as IndexedFaceSet nodes.
  • +meshjava prefix — incomplete-file version of -meshjava, concatenatable onto a sourcefile written by -meshjava. New defined datatype names in the sourcefile start with the prefix argument.
  • -manyclasses — only valid after the -java, -3java, -meshjava or -wonderland options. Bestie, this one is a brute force attempt to fight 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". And it's not just the real constants like 1, 2 or 3 being counted — it's also things like member variable definitions in classes etc. With -manyclasses, all data is distributed into many separated classes.

It should help if you run into that "too much constants" problem. BUT — in case of a large number of DEF commands in the vrml/x3dv file, you can still run into it, cause each DEF command leads to an extra member variable in the main scenegraph class. In that case, 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). No glasses, no problem. 💅
  • -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 of hardware/software combos 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, and 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. Fun fact: the fieldOfView of the human eye is about 18 degrees, the VRML default is 45 degrees. 🌈

🧚 INPUTDEVICEOPTIONS 🧚

The following options are only valid, if whitedune was compiled with matching inputdevice driver support (e.g. there is not support for a Linux joystick under IRIX). So like... vibe check your build first, bestie. 😭

  • -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_whitedune 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). Don't skip this one, fr fr. 🙈
  • -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 whitedune 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 whitedune 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

These are the literal shapes of it, bestie — copy them character for character and you're golden. ✨

✨ AXISLEGEND ✨

Okay so this is the legend for the axis stuff, bestie. No cap, every single one matters.

  • - — 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 independent 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 🦋

Okay so this options are ONLY valid for the Ascension flock of birds magnetic tracking system. Periodt.

  • -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_whitedune 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_whitedune application can be uninstalled and exit. Under Micro$oft Windows it additionally clears all information activly set by white_whitedune (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, whitedune 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, whitedune 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 whitedune can be found in the docs directory of whitedune (http://129.69.35.12/whitedune/docs/)

🌈 C/C++/JAVA SOURCE EXPORT 🌈

okay bestie, this one's a whole vibe. the source-code export is literally just the information (numbers and strings) of the VRML/X3D scenegraph tree, poured out into code. 💖

white_whitedune does not export anything like C source with OpenGL commands in it. the exported code is independent of any rendering engine, so you can pair it with literally any 3D API you want. ✨

you will need extra code to actually render the scenegraph with a 3D API. right now white_whitedune ships with exactly one set of such additional code, and it's for the Java Monkey Engine (JME). that code is your blueprint if you wanna write code for other render engines. 🎀

so here's how it goes: the information of the scenegraph gets written into a class/struct whose name is the string of the prefix argument (default "X3d") concatenated with the string "SceneGraph". that scenegraph class/struct gets filled with references to the different VRML/X3D commands ("nodes"). the name of the type of such a node is the prefix argument string (default "X3d") concatenated with "Node". every node type holds the data of the VRML/X3D node in variables named exactly the same way as the VRML/X3D fields. slay. 💅

the mapping table, bestie (VRML/X3D field type → C, C++, java datatype): 🦋

  • SFBool — C: short, C++: bool, java: boolean
  • SFInt32 — C: int, C++: int, java: int
  • SFImage — C: int*, C++: int*, java: int[]
  • SFFloat — C: float, C++: float, java: float
  • SFVec2f — C: float[2], C++: float[2], java: float[2]
  • SFVec3f — C: float[3], C++: float[3], java: float[3]
  • SFVec4f — C: float[4], C++: float[4], java: float[4]
  • SFRotation — C: float[4], C++: float[4], java: float[4]
  • SFMatrix3f — C: float[9], C++: float[9], java: float[9]
  • SFMatrix4f — C: float[16], C++: float[16], java: float[16]
  • SFColor — C: float[3], C++: float[3], java: float[3]
  • SFColorRGBA — C: float[4], C++: float[4], java: float[4]
  • SFDouble — C: double, C++: double, java: double
  • SFVec3d — C: double[3], C++: double[3], java: double[3]
  • SFTime — C: double, C++: double, java: double
  • SFString — C: const char*, C++: const char*, java: String
  • SFNode (*)** — C: X3dNode*, C++: X3dNode*, java: X3dNode
  • MFBool — C: short*, C++: bool*, java: boolean[]
  • MFInt32 — C: int*, C++: int*, java: int[]
  • MFFloat — C: float*, C++: float*, java: float[]
  • MFVec2f — C: float*, C++: float*, java: float[]
  • MFVec3f — C: float*, C++: float*, java: float[]
  • MFVec4f — C: float*, C++: float*, java: float[]
  • MFRotation — C: float*, C++: float*, java: float[]
  • MFMatrix3f — C: float*, C++: float*, java: float[]
  • MFMatrix4f — C: float*, C++: float*, java: float[]
  • MFColor — C: float*, C++: float*, java: float[]
  • MFColorRGBA — C: float*, C++: float*, java: float[]
  • MFDouble — C: double*, C++: double*, java: double[]
  • MFVec3d — C: double*, C++: double*, java: double[]
  • MFTime — C: double*, C++: double*, java: double[]
  • MFString — C: const char**, C++: const char**, java: String[]
  • MFNode (*)** — C: X3dNode**, C++: X3dNode**, java: X3dNode[]

() heads up:* the "X3d" part of the name is the default — it can be swapped out for the string of the prefix argument. 💅

for any MF* type field (and an SFImage type field too, bestie), the number of int, float etc. values in the array gets stored in a variable of the X3dNode struct/class composed from "m_", the name of the field and "_length" — in the case of a C/C++ export. java doesn't need such a variable, cause the length of an array is always right there as the .length component of the array. 🌸

the scenegraph is a tree of nodes. the root of the scenegraph is (just like in the white_whitedune 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 this VRML file right here: 👑

#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 represented 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 contains three other nodes, the third of these nodes is represented as "root->children[0]->children[2]" in the "X3dSceneGraph" struct.

if the third of these nodes is a Fog node, the "color" field of the Fog node is represented 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 an 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 represented 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's a second way to access the fields of the Fog node. 👀

in VRML/X3D it's possible to name nodes with a "DEF" command. the string behind the DEF command ("NAME_OF_FOGNODE" in the example) also occurs in the "X3dSceneGraph" struct and can be used directly to access the matching VRML/X3D data.

so the green part of the fog color is represented 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 occur 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. no cap, watch your terminal. 😭

beside accessing 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 an additional set of callbacks for other tasks ("*DoWithDataCallback"). 🌟

there are also callbacks to replace the functions which by default all together traverse the Scenegraph ("*TreeRenderCallback" and "*TreeDoWithDataCallback").

the callback mechanism and the scenegraph initialization differ from programming language to programming language. iykyk. 💜

C 💙

the scenegraph (default argument "X3d" for prefix) can be declared 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 built 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 of the X3D node can be accessed. ✨

to install the callback, simply assign your function pointer to "callbackFunction" to a variable built from the string of the prefix argument (default "X3d"), 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 callback functions in C are stored in global space, the C++ callback functions 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 an 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's 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 -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 ✨

okay bestie, real talk — these are the exact invocations, no cap. type them as-is and you're golden. 💖

whitedune -nostereo

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

the magellan + dialbox combo

whitedune -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 whitedune 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

whitedune -joystick /dev/input/js0 -z=,3 -axes=3

starts whitedune with a linux joystick, set acceleration of the z axis to 3 and disables the 4. (5., 6., ...) axis.

whitedune -xinput magellan -z=3 -xrot=2 -none=2

starts whitedune with a xinput/magellan device, swapping axis number 2 and axis number 3, with axis number 2 disabled.

whitedune -nxtdials

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

whitedune -aflock /dev/ttyS1 -numbirds 2 -master 1 -wand 2 -tracker 3

starts whitedune 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.

whitedune -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/.whitedunerc — default file to load/store settings (see WHITEDUNERC environment variable for more information)
  • $HOME/.whitedune_crash_*_*.wrl — stores the vrml file in case of a crash

🌍 ENVIRONMENT 🌍

  • WHITEDUNERC — filename to load/store details of whitedunes screen layout and settings of the "options" menupoint. If this filename is not writable, settings are only loaded, not stored. If WHITEDUNERC is not set, the file $HOME/.whitedunerc is used under Linux/UNIX/MacOSX or the registry under Micro$oft Windows.
  • WHITEDUNEDOCS — 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_whitedune can load XML encoded X3D files via a translator.

Use the menupoint Options -> Input Settings... to configure a X3D/XML to X3DV translator.

whitedune 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 whitedune 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), whitedune tries to write it's contence to the file $HOME/.whitedune_crash_*_*.wrl

👀 SEE ALSO 👀

👑 AUTHORS 👑

Stephen F. White and others

See README file for details

this iconic little manual is white_whitedune 0.29beta, dated 2006-12-10 — periodt, bestie 💅✨🫶

📦 where this page comes from