========================================================================
         File: pulsar_03_AA.zip
       Author: Raphael MOLL (raphael.moll@inforoute.cgs.fr)
      Release: 0.2 (dev, July 4th, 1997, 1h24 am... hard at work!)
Compatibility: AA-DR9
     Location: http://www.inforoute.cgs.fr/moll/be/pulsar_03_AA.zip
           or: ftp://ftp.be.com/pub/contrib/audio/pulsar_03_AA.zip
  Description: FFT spectro psychedelic sound analyser
        Notes: New in v0.3 : new CFilter add-on architecture.
========================================================================


Readme diff for v0.3:
---------------------
The Independance Day, for American People of course.
One day, one version.
This version mainly features the final-candidate Filter add-on architecture.
The add-ons are done by deriving (derivating ? huh ?) a class from CFilter.
The class information are well organized, now. Clean & boring stuff there.
Ooops, I wanted to say interesting stuff... clean that's for sure.
New too : Pulsar has been tested -- and approved -- with Jacques Brel songs
(hum, a well known French singer in fact). Voice looks terrific throught
the FFT.
I also tested it on a PowerCenter 150, and you can switch the microphone
+20 db entry on... Then call some guys around you and ask them to make claps
or to shout at the integrated microphone. Very funny.

I encourage anybody to make new add-ons for Pulsar right now !
It easy, just have a look at the fft_addon or sample_addon directory, and
copy the whole directory. You only need CFilter.h, CFilter.cpp, you own
class instance, and then copy your shared lib add-on to the add-on directory.
The first true _third party_ add-on is included, it's a Copper Bar made
by SpH (levesque@inforoute.cgs.fr).
If you follow the guidelines that are written in CFilter.h/.cpp and the
one in the sample_addon, you will be compatible with next versions of
Pulsar. In that case, you might also want to have a look at the todolist.txt
file, in order to know what exactly changed and what will change.

Note that if  you compile add-on, don't forget to create a .xMAP file (BeIDE
settings, linker options) and move it into ./add-ons with your add-on.
When you will break into the debugger, type 'SC' and you will see some line like :
00800 +05C CMySample::processFrame ...
Which means you crashed at assembly offset +5C. Thus first close Pulsar
(see below), then open BeIDE, open you file.cpp, selection Project
Dissassemble and find the mangled C++ name of processFrame, then if you
have included source in dissassembly (settings / dissaembler) you will
easily find the offset and thus your crashing line.

The good point : Pulsar can now safely been closed at any moment. Well,
this means that if the stream is running and the window monitors (fft
or output) are checked, nothing will happen ; as a side effect of trying
to quit the app, the stream will stop. So uncheck the window monitors and
then quit again. It works.
If you crashes, DON'T TYPE 'ES' or close the debug output ! Instead,
uncheck the window, stop the stream, close the parameter window and THEN
you can type ES.

I'm still looking for a way to handle both 32 bits and 8 bits add-on
without including a lot of switch/if-elseif statements. I you have ideas,
just tell me. Maybe the easiest one would be that the add-on provides
two filters, each one limited to either 32 or 8 bpp. Hmmm, sounds cool.

Nevertheless, enjoy, debug and 

------------------------------------------------- > The R'alf < -----

Readme diff for v0.2 :
----------------------
This version features a first version of add-ons.
It still doesn't support the Game Kit, next release will do it.
I'm rating one week per minor release, which is good in fact...
In my terminology, be carefull : a "filter" for Pulsar is just an
add-on that draws in the output window. I call it a filter since it
filters results from the raw sound and the fft.
The following files/directories have been added :
- interface_sample.jpg : a screen shoot of the parameters interface. There
are many paramters planned but you will have to find this self-explanatory
or ask me more details by email, I won't write them down here tonight :-p
- add-ons : the directory where Pulsar is going to search for its add-ons
at statup. This must be located in the same directory than the application
itself. I will plan supporting prefs some time, later..., to redefine this.
- sample_addon : a skeleton for a new add-on. It lacks usefull documentation
but you will find suficient comments in the .cpp and .h.
- fft_addon, loupe_addon and demicercle_addon : the 3 filters add-ons
currently implemented for testing. Note for English people : loupe means
magnify in French and demi-cercle means half circle. You will figure
easily what draws what.
- Pulsar : the app.
- src : the directory with the headers. Will be renamed inc/ later.
The only usefull header is "SFilterAddon.h". It contains self-explanatory
comments (I hope so !) The other header, fastmath.h is just here for
demicercle.cpp who uses it.

Any comment or suggestion is welcome to :
raphael.moll@inforoute.cgs.fr

Greeting go to Chrish (for zip and intercultural discusions via emails),
Tao (DuBeUs, for being a techno-dj) and Adnans (.nl too for BeMP), JiM and
of course SpH for giving me these terrific Rave Mission cds.

---

Note for those who had a look at "interface_sample.jpg" before reading
this : this file contains a screen shoot of how I want the final interface
for the parameters to looks like. This doesn't mean it will be exactly
like that, I'm not porting MFC... Don't blame me, it's a quick & dirty
hack ! But I surely thinks AppSketcher should ship Real Soon Now, so I
can do the same with our beloved gadgets...
---

----------------------------------
Here is the old v0.1 readme file :
----------------------------------

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), -- [done in 0.2]
-3- The game kit window,
-4- nice filter effects for demo purposes, -- [half done in 0.2]
-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)
