========================================================================
         File: pulsar_01_AA.tgz
       Author: Raphael MOLL (raphael.moll@inforoute.cgs.fr)
      Release: 0.1 (dev, June 20, 1997, 1h34 am... hard at work!)
Compatibility: AA-DR9
     Location: http://www.inforoute.cgs.fr/moll/be/pulsar_01_AA.zip
  Description: FFT spectro psychedelic sound analyser
        Notes: New in v0.1 : effects more interesting
========================================================================

What you will find below : Description, Installation, Crash limitations,
Bug list and To Do List;
Please read it, it was quite boring to write it all.
---

Description (Idealistic)
========================
Pulsar is an app I started after listening Trance Techno music.
Hey, come back ! It also works with other type of music, if you like !

The main idea is that it runs an FFT on the music and displays psychedelic
stuff in full screen, using your parameters.


Description (Realistic)
=======================
Currently, the application let you choose the input stream (ADC or DAC) and
the position in the stream (beginning or end).
It also displays the two FFT computes from the music and the raw music
grabbed from the stream.

The Pulsar FFT window should up four views :
- the top right view is the true FFT that comes from the input stream at 44.1 kHz,
with a range of 512 points. Actually what you see are the 256 first points, so it
ranges from 0 Hz to 22.05 kHz.
- the top left view is decimated FFT, decreased by a factor of 16, so you see
256 points from 0 to 1378 Hz (+/- epsilon).
- the bottom view is the first 512 points of the raw music coming from the input
stream.
- the middle view is 512 points large. This is unusefull information that I give
you just because I find it perfectly boring. Beside that it is green. This also
is unusefull.
"You know what it is ? It's a phoque". Hmmm, French joke, sorry, I couldn't
resist, just because I know you don't understand it :-)
"You're a monster ! I know"...
So I come back with the explanation : the middle view is just a mean of every
16 points of the raw music coming from the input stream (sic). It has the nice
side effect of scrolling 16th time slower than the bottom view. It also has the
nice side effect of being used to compute the top left FFT.

The Pulsar Filled Window shows a 320x200 bitmap of the actual (un)interesting
output. This is just debug stuff. In fact it should be 640x480 using the game kit,
but that is not written yet.

The main idea is that the ouput of this window will be the sum of some "video"
stream filters. Each filter will be an add-on and will have some configurable
paramters. Each filter grabs values from the FFT arrays and displays whatever
effect he wants on the output bitmap.
Currently, I did some quick and dirty, hard coded, filters. The first
draws strange yellow to white frames, and translates them with a kind of
sinus. The second filter add the sliding colored bar on the middle on the
window.
These effects are not interesting at all but a future version will issue
better things. Before that, I must write the add-on API...


Installation
============
-1- Gunzip the archive and untar it somewhere. A new directory will be created.
The very needed files are Pulsar, the exec, and fondfft.jpg.
You also need to have Datatype installed. I use the latest (1.5.2) version.
You can get it from BeWare or on the ftp.be.com site.

There is also a .xMAP file for the debugger, and a non-optimized version.
If you don't know what these files are for, just ignore them.

-2- Put a CD in your CDROM drive and open the CD Player panel. Play some
cool techno, the one you want. You can try some cool classical music too.
The more bass there are, the better. For my own, I prefer Trance, Dream and
the Saint Saens Concerto for Orgue. :-)

-3- Run the Pulsar application. In the parameter window, do the following, in that
order and all will be fine :
a) check the "Pulse FFT view" box,
b) pull the "Start" radiobutton,
c) pull the "ADC" radiobutton,
d) push the Start button.
The FFT will start running.

-4- try unchecking the "Pulse FFT view" and checking "Pulse Filled view".
This will animated the 320x200 small window.
Currently, what shows in the Filled Window is a (bad) example of what can be
done with that. See the TO DO list below for more info.


Speed
=====
Since the FFT stuff is just for setting the future parameters, it doesn't
lock the machine CPU for its own purpose. I use some strange scheme that make
the FFT window "slow down" if you work with your box. It's a bad side effect of
how I use messages, but it works fine.
The good point is that I can run two version of Pulsar on my BeBox Dual-133 with
my (slow) S3 1MB card without degrading severely the performances.

If you make pulse both the FFT and the Filled window, both will slow down. This
is not bad : these are just here for setting parameters and debugging, so I
don't really care.


Crash version
=============
The exec you have in hand is a full developement release.
This means that I can't be blamed if it crashes your machine and I'm not
responsible for loss of data or productivity that may result from the usage
of this (cool) stuff.

Anyway, the version you have is rather stable (see the bug list below).
I beta tested it using this kind of music :
- Ultra Techno, vol 1 (the best one),
- Rave Mission vol 7,
- Rave Mision vol 9, (another best one),
- Saint-Saens, symphony n°3, "Organ" (concerto for orgue),


Bug list
========
Main rule : anything odd that might happen will hapen.
Douglas Adams would add that everything that must happen, will happen or the like
(I don't have the English translation for that, match your own exeperience).

-1- Main bug : quitting is not savvy.
Currently, there is a work around, so it is always safe to quit, whatever you
do, but this is crazyness. I should better learn programming at the kid school :-)
The idea is that you must always uncheck the "Pulse XX view", then stop the
stream, then quit.
If you don't do that, it won't crash, but it might be very long to quit.
("very long" is a short hand to say "0 <= x < B_INFINITE_TIMEOUT").

-2- Don't try to zoom the Filled Window (I think I disactivated this but you
never know...)

-3- So bad AppSketcher is getting late. I started the interface with AppSketcher
in DR8... I was (not so) hard to rewrite the interface by hand but the bad
point is that I won't restart the interface again using AppSketcher. Well
maybe I will do it... -- sigh --

-4- the bass FFT is strange on classic music : it doesn't match the "bass"
part of the high FFT.


TO DO LIST
==========
-1- Everything for the BeOS,
-2- the filter API (public of course),
-3- The game kit window,
-4- nice filter effects for demo purposes,
-5- the parameters for the effects in the parameter window,
-6- as well as the selection of the filter and their order,
-7- loading/saving configuration files.
-8- including some features of the CD player panel right in the interface.

(end of this readme file)
