Heilan X3D Browser
------------------

--------------------------------------------------------------------------------
Description
-----------
Heilan is an OpenGL X3D browser designed for audio work.  Specifically, it forms
the environment within which I am developing an audiovisual instrument for my
PhD (http://www.niallmoody.com/phdstuff/).  As such, it has a number of features
not commonly found in X3D browsers:
    - Low latency audio courtesy of PortAudio (ASIO on Windows, Jack on Linux,
      CoreAudio on OSX).
    - A 1st order B-format Ambisonic
      (http://www.york.ac.uk/inst/mustech/3d_audio/ambis2.htm) audio engine,
      allowing for full 3d sound, capable of accommodating virtually any speaker
      configuration (at the moment this is limited to preset configurations, but
      that will change in the future).
    - Open Sound Control (http://cnmat.berkeley.edu/OpenSoundControl/) support
      for all nodes, allowing a node's attributes to be manipulated in realtime,
      potentially by multiple users.
    - A multi-threaded audio engine, able to split off different nodes' audio
      processing into separate threads (and potentially, separate cpus/cores).
      This can be configured by the scene author.

At present, the browser is strictly offline - there is no browser plugin
version, and it will not load files via http/ftp protocols.  The browser itself
is a command line program, though there is a GUI front end (Heilan Front End
http://www.niallmoody.com/heilan/download.htm - it may be included with this
file if you downloaded a binary package rather than the source code one)
written using the JUCE toolkit, to accompany it.  To make it easy to extend the
browser's capabilities, it can load libraries which may contain extra node
types, navigation types, and sound file loaders.  There is one library
(libheilanextras) included, containing the various audiovisual experiments I've
conducted as part of my PhD (these consist primarily of new node types, with a
couple of new navigation types).


--------------------------------------------------------------------------------
Usage
-----

Command line options:
---------------------

Usage:
HeilanBrowser [flags] <x3d_file>

Flags:
--width [val] | -w [val]:       Set the width of the window.
--height [val] | -h [val]:      Set the height of the window.
--antialias [val] | -a [val]:   Sets the antialiasing level.
--library [file] | -l [file]:   Adds a (node/nav/sound) library to be loaded.
--audioAPI [val] | -aa [val]:   Sets the audio API to use.
--audioDevice [val] | -ad [val]: Sets the audio device to use.
--audioSamplerate [val] | -as [val]: Sets the audio samplerate to use.
--audioSpeakers [val] <file> | -ap [val] <file>: Sets the speaker configuration to use.
--audioBlockSize [val] | -ab [val]: Sets the audio block size to use.
--OSCPort [val] | -op [val]:    Sets the port to listen for OSC packets on.
--noAudio | -na:                Disables sound.
--noOSC | -nO:                  Disables Open Sound Control support.
--fullscreen | -f:              Sets whether to go fullscreen or not.
--bloom | -b:                   Turns on a bloom filter post-processing.  This requires a graphics card with support for frame buffer objects and shaders.
--offline [seconds] [file] | -of [seconds] [file]: Renders visuals and audio offline for [seconds]s of the scene.  Renders video to a sequence of jpegs (named [file]xxxx.jpg), and audio to a number of wav files (named [file]xx.wav).
--recordOSC [file] | -rO [file]: Saves all OSC messages input to a text file for later playback.
--cursor | -c:                  Sets whether to display a mouse cursor or not.
--help:                         Display this help.
--version | -v:                 Display version.
--nodes | -n:                   Display available X3D nodes.

audioSpeakers Usage:
0: Mono
1: Stereo
2: Square
3: Pentagon
4: Hexagon
5: Octagon1
6: Octagon2
7: Surround1
8: Cube
9: Dodecahedron1
10: Dodecahedron2

It should be noted that  some of the (non-audio) nodes still rely on the audio
ngine to obtain timing information, so specifying the --noAudio option may have
unforseen side-effects with nodes such as TimeSensor.

Runtime Options:
----------------
Esc             - Quits the program.
L               - Toggles the headlight.
F               - Toggles fullscreen operation.
PgUp            - Go to next Viewpoint.
PgDown          - Go to previous Viewpoint.
Home            - Go to first Viewpoint.
End             - Go to last Viewpoint.
Left mouse      - Rotates the scene (in EXAMINE mode).
Middle mouse    - Zooms and pans (x-axis) the scene (in EXAMINE mode).
Right mouse     - Pans the scene (x- and y-axis) (in EXAMINE mode).

Scene Authors:
--------------
For the most part Heilan should behave the same as any Interchange-profile
supporting X3D browser, meaning any Interchange profile X3D files you have
should work (see ToDo below for some caveats).  It does however also have some
features specific to itself:
- OSC support:              Any node can make it's attributes accessible to an
                            OSC client.  To do this, simply give a node a DEF
                            name.  This then means it will have an OSC address
                            and can respond to OSC messages.  To control it from
                            an OSC client, you just send messages to
                            /heilan/<node address>/<node attribute>.  If you are
                            trying to control an attribute that may have
                            multiple values (e.g. a position vector), you can
                            control it by adding the index of the value you want
                            to control to the end of the address, e.g.
                            /heilan/bob/position.0 (the first four indices can
                            also be replaced with x, y, z, r respectively).  You
                            may want to look at my MouseToOSC program
                            (http://www.niallmoody.com/otherprograms.htm) for a
                            simple way to send OSC messages to Heilan.
- Audio Parallelisation:    Any ParentNode can split the audio processing of
                            its children into separate threads.  To do this,
                            create a MetadataString node as a child of the
                            ParentNode whose children you want to parallelise,
                            and give it a name of "heilan_parallelChildren" and
                            a value of "TRUE".  This will create a separate
                            audio thread for each of the ParentNode's children.
- Viewpoint nodes:          When used with the TimedViewpoint navigation type in
                            libheilanextras, Viewpoint nodes can be assigned
                            times, to create fly-throughs of the scene.  To do
                            this, create two MetadataString nodes as children
                            of the specified Viewpoint node, one with the name
                            "heilan_timeToGetHere", and one with the name
                            "heilan_pauseTime".  The values should be the number
                            of seconds you require for each section (where
                            timeToGetHere is the time it takes to move to this
                            Viewpoint from the previous one, and pauseTime is
                            how long to wait before moving on to the next
                            Viewpoint).  To be honest, this option is largely
                            superfluous, as the same thing can be achieved in
                            standard X3D syntax by just automating a Viewpoint's
                            position with a PositionInterpolator object.

The use of the MetadataString node type to control these operations should mean
that the resultant X3D files remain compatible with other browsers, even if
they don't have Heilan's specific functionality.

There are a number of x3d files in the src directory which I've used to test the
browser's capabilities.  Some of them may not work correctly due to missing
sound files (I didn't want to add to the file size), but they're included to
give an example of how to use those nodes.


--------------------------------------------------------------------------------
Supported Formats:
------------------
X3D Formats:    For now, just plain .X3D files are supported.  Support for .X3DZ
                may come in the future, though it's unlikely that the VRML-based
                formats will be supported.
Image Formats:  Anything supported by SDL_image: BMP, GIF, JPEG, LBM, PCX, PNG,
                PNM, TGA, TIFF, XCF, XPM, XV.
Audio Formats:  Anything supported by libsndfile: WAV, AIFF, AIFC, DEC, AU, SND,
                RAW, PAF, IFF, SVX, SF, VOC, W64, MAT4, MAT5, PVF, XI, HTK, CAF,
                FLAC(?).
                Also Ogg Vorbis, courtesy of libvorbisfile.


--------------------------------------------------------------------------------
ToDo:
-----
You can see the TODO file for a comprehensive list of the things still to do,
but there are some fairly major things still missing from Heilan.  Specifically,
the browser does not support the PROTO keyword (and there is no SAI/scripting
support), though DEF, USE and ROUTE are supported.  All the Interchange profile
nodes are implemented, though some of them do not have all their attributes
implemented yet.  I'm hoping I can support the Interactive profile in the
future.


--------------------------------------------------------------------------------
List of Supported Nodes:
------------------------
(note: as mentioned above, some of these nodes are not fully implemented yet)

X3D nodes:
----------
Appearance
AudioClip
Background
Billboard
BooleanFilter
BooleanSequencer
BooleanToggle
BooleanTrigger
Box
Color
ColorInterpolator
ColorRGBA
Cone
Coordinate
CoordinateInterpolator
Cylinder
DirectionalLight
ElevationGrid
Fog
Group
ImageTexture
IndexedFaceSet
IndexedLineSet
IndexedTriangleFanSet
IndexedTriangleSet
IndexedTriangleStripSet
Inline
IntegerSequencer
IntegerTrigger
KeySensor
LineProperties
LineSet
Material
MetadatSet
MetadataDouble
MetadataFloat
MetadataInteger
MetadataString
MultiTexture
MultiTextureCoordinate
MultiTextureTransform
NavigationInfo
Normal
NormalInterpolator
NurbsCurve
NurbsPatchSurface
OrientationInterpolator
PixelTexture
PointLight
PointSet
PositionInterpolator
ProgramShader
ProximitySensor
ScalarInterpolator
Scene
ShaderProgram
Shape
Sound
Sphere
SpotLight
StringSensor
Switch
TextureCoordinate
TextureCoordinateGenerator
TextureTransform
TimeSensor
TimeTrigger
Transform
TriangleFanSet
TriangleSet
TriangleStripSet
Viewpoint
WorldInfo

libheilanextras Nodes:
----------------------
(see ExtraNotes.txt or doc/libheilanextras for details of these nodes'
 attributes)

AccelLine
AccelTransform
AmpCube
Ashitaka
Ashitaka2
Atom
AtomController
AtomSphere
CollisionCubes
DeformableNurbs
DeformableSphere
DeformableSphere2
DynamicTexture
GhostImage
Jiko
JumpCube
KeyTrigger
Kodama
Koroku
MassSpringDamper
Moro
MotionBlur
Nago
Okkoto
OscPlayback
PaintingBackground
ParticleGenerator
PhysicalModel
PhysicalSurface
PixelArray
PulseCubes
RandCubes
SimpleFilterCube
SineTest
SparkParticles
StarCubes
StretchyBackground
Toki
TransientDetector
WebcamTexture
Yakul


--------------------------------------------------------------------------------
Credits:
--------
Heilan is built on the following libraries:
- SDL (http://www.libsdl.org)
- SDL_image (http://www.libsdl.org/projects/SDL_image/)
- PortAudio (http://www.portaudio.com)
- TinyXML (http://www.grinninglizard.com/tinyxml/)
- libsndfile (http://www.mega-nerd.com/libsndfile/)
- libvorbisfile (optional) (http://xiph.org/vorbis/)
- libjpeg (optional: for offscreen rendering) (http://www.ijg.org/)
- FFTW (optional: for libheilanextras) (http://www.fftw.org/)

Though I don't believe any code was directly taken from it for this version of
the browser, the X3DToolKit (http://artis.imag.fr/Software/X3D/) was used in a
previous version, and surely influenced Heilan's design.

My PhD supervisors: Dr. Nick Fells and Dr. Nicholas Bailey.


--------------------------------------------------------------------------------
License:
--------
Heilan Browser is released under the GPL, see COPYING for the full license:

Copyright (C) 2005-2008  Niall Moody

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 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.


--------------------------------------------------------------------------------
Niall Moody,
Centre for Music Technology,
University of Glasgow.
