snowflakes
----------

Description:
------------
snowflakes is a small audiovisual instrument, designed to be played with a
gamepad.  It's meant to be kind of soothing and peaceful, and is fairly
customisable.  It consists of a number of snowflakes, each of which are assigned
a pitch from a list of three.  The snowflake's position on the screen determines
it's panning and amplitude.  The gamepad's main use is to change which pitches
the snowflakes are using, with button presses initiating a nice glissando to
the new pitches.

OpenGL is used for the graphics (via SDL), and PortAudio is used for the audio.


Usage:
------
Sorry, there's quite a lot of information here...

For playing the instrument as-is, the gamepad controls are as following:
buttons 1-8     Sets the current chord to one of the 8 presets.
button 9        Toggles stars on and off.
button 10       Fires a shooting star from a random position.
<left>          Changes the background colour to the previous stored preset.
<right>         Changes the background colour to the next stored preset.
<up>            Changes the snowflakes' amplitude to the next stored preset.
<down>          Changes the snowflakes' amplitude to the previous stored preset.

If you don't have a gamepad, you can use a standard keyboard.  The controls in
this case are mapped as so:
a-h                 gamepad buttons 1-8.
i                   gamepad button 9.
j                   gamepad button 10.
<direction keys>    gamepad directional pad.

The program has various command-line options:
Usage:
snowflakes.exe -w [width] -h [height] -a [val] -o [val] -r [path] -l [path]
-ro [seconds] [path] -f -ns -nb

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 (2, 4, or 6).
--osc-port [val] | -o [val]:    Sets the port to listen for OSC messages on.
--record-events [path] | -r [path]: Records any user events to [path].
--load-events [path] | -l [path]: Plays back the events stored in the file at
                                  [path].
--render-offline [seconds] [path] | -ro [seconds] [path]: Saves the audiovisual
                                                          output as a sequence
                                                          of jpegs and a wav
                                                          file.
--fullscreen | -f:              Sets whether to go fullscreen or not.
--nosound | -ns:                Switches off the sound output.
--noblur | -nb:                 Switches off the snowflakes' blur.
--help:                         Display this help.

Of these, here's a more detailed description of the less-obvious ones:
--osc-port          snowflakes acts as an Open Sound Control client, this sets
                    the port to listen on for OSC messages.
                    The messages it will respond to are:
                    /stars [int32] Toggles stars on(1)/off(0).
                    /amplitudeRate [float32] Sets the rate the snowflakes'
                                             amplitude changes (0->1).
                    /pitchRate [float32] Sets the rate the snowflakes' pitch
                                         changes (0->1).
                    /colourRate [float32] Sets the rate the background colour
                                          changes (0->1).
                    /rotationRate [float32] Sets the rate the snowflakes rotate
                                            at (-360->360).
                    /fallRate [float32] Sets the speed at which the snowflakes
                                        fall (0->~).
                    /volume [float32] Sets the snowflakes' volume directly
                                      (0->1).
                    /volumeIndex [int32] Changes to the indexed volume preset
                                         (0...numStoredVolumes).
                    /colourIndex [int32] Changes to the indexed background
                                         colour preset (0...numStoredColours).
                    /pitchIndex [int32] Changes to the indexed pitch preset
                                        (0...numStoredPitches).
                    /shootingStar [int32] Fires a shooting star (~).
--record-events     This will save any user events (either from the gamepad/
                    keyboard, or via OSC) to the file at [path].
--load-events       This will play back the events saved at [path] from a
                    previous --record-events run.
--render-offline    This will run the program in offline mode for [seconds].
                    This means each visual frame will get saved as an individual
                    jpeg file in [path], and the audio will be saved as a stereo
                    wav file.  You can then use something like mencoder to turn
                    these files into a video.
--noblur            On older graphics cards, snowflakes can be quite graphics-
                    intensive.  This switches off some of the more demanding
                    visual effects.

On top of all this, snowflakes uses a config file to set all of these (and more)
parameters.  This file is located at:
Windows XP: \Documents and Settings\<your login>\Application Data\snowflakes\
            snowflakes.conf
Windows Vista: \Users\<your login>\AppData\Roaming\snowflakes\snowflakes.conf
OSX: \Users\<your login>\Library\Application Support\snowflakes\snowflakes.conf
Linux: \home\<your login>\.snowflakes\snowflakes.conf

The config file is loaded by the program at startup, though it will get
overridden if you start the program with any additional command-line parameters,
which will be used in preference to the settings in the config file.  To store
any of the above command-line parameters in the file, you just use the short
version of the parameter, minus the '-', like so:
w 800
h 600
a 6
f 0
ns 0
nb 0
(etc.)

The config file also lets you set the various presets mentioned previously,
however.  Here are the available options:
s [val]         Whether to start with visible stars or not (0/1).
ra [val]        The snowflakes' amplitude rate (0->1).
rp [val]        The snowflakes' pitch rate (0->1).
rc [val]        The background colour's rate of change (0->1).
rr [val]        The speed the snowflakes rotate at (-360->360).
rf [val]        The speed at which the snowflakes fall (0->~).
v [val]         Volume preset (0->1).  There can be any number of these.  The
                first one in the file is the one the program will be set to on
                startup.
p [v1] [v2] [v3]The three starting pitches.  New snowflakes are given a random
                pitch from one of the three current pitches.
j [v1] [v2] [v3]A pitch/chord preset.  The order of these in the file
                corresponds to which button on the gamepad/key on the keyboard
                they are mapped to (the first 'j . . .' is the first gamepad
                button/'a' on the keyboard, etc.).
j stars         Maps the toggling of stars to a gamepad button/keyboard key.
                Again, the button/key it is mapped to is dependent on where this
                j appears in the file.
j shootingStar  Maps the firing of shooting stars to a gamepad button/keyboard
                key.  See above.

As far as pitches go, the program expects them to be provided in Hz.  As such,
you're not limited to equal temperament, and can do fancy microtonal things if
you want.  You can only set 3 pitches for a preset though - the program will
probably break if you try to add more.


--------------------------------------------------------------------------------
Note: If the program runs slowly, there are two things you can do to improve
      things; Turn off antialiasing (-a 0), and use the --noblur/-nb option.
--------------------------------------------------------------------------------


Licensing:
----------
The source code is released under the GNU GPL v3:

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/>.


Any images are released under the Creative Commons
Sampling Plus license
(http://creativecommons.org/licenses/sampling+/1.0/deed.en_GB).


SDL, SDL_image and libsndfile are released under the GNU LGPL.  PortAudio is
released under the MIT license.  See the accompanying license docs for the full
terms.


- Niall Moody (3/9/08).
