# NOTES
# $Id: NOTES,v 1.3 2002/11/08 03:39:48 andy Exp $

~~~ XPYRE TECHNICAL NOTES ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

--- threading -----------------------------------------------------------------

xpyre makes use of three threads, two of which it is responsible for:

(1) xmms thread
This thread is not really a part of xpyre--it's just the main xmms thread, the
same one that's responsible (so it seems) for gui stuff, reading lists of
files, and everything else that unthreaded visualization plugins will lag.  In
this thread, xmms calls the init, cleanup, and pcm functions (xpyre/xmms.c),
most importantly pcm.  The really fast visualization plugins actually do
drawing in the pcm (and freq) functions, but this makes the xmms gui very
slow.  I did that before I got the hang of threading, and I'm still a little
ashamed. ;^)  Anyway, my functions in the xmms thread are as minimal as
possible: init creates the main thread, cleanup stops the main thread, and pcm
makes the pcm data available to other threads.

(2) main thread
This thread is responsible for managing the timer thread.  It also updates the
screen at regular intervals.  Since I do as little as possible in the xmms
thread, I have the main thread handle miscellaneous initialization and cleanup
details, like loading the configuration.  The main thread checks for song
changes.

(3) timer thread
This thread is ludicrously simple.  All it does it increment the timer variable
at regular intervals.  The timer variable is used by the main thread to
determine when it's time to display the output of the drawing code.

xpyre also may cause a few other threads to be opened, but this is only because
it uses the Allegro library to manage its X connection.  I hope to eventually
eliminate all platform-specific Allegro stuff and manage my windows myself.
This will fix that stupid crash on xmms shutdown.  But first I must learn how
to use Xlib (or whatever) for my big blit, for keyboard stuff, and for general
window management.  Even after switching to Xlib (or whatever), I'll still be
able to use Allegro for all internal pixel pushing, so I won't really miss
anything.  But maybe even that's not necessary.

--- my_rand -------------------------------------------------------------------

The my_rand function is a wrapper around the system rand function that takes
advantage of the fact that most of the times that I use random numbers I only
need a very small range.  It calls the rand function whenever it must, but the
rest of the time it just returns previously-unused bits of the cached random
number value.  For example, with just one call to the system rand function,
my_rand can return eight random numbers from 0 to 15.  I find that while the
system rand function produces good-quality random numbers, it is expensive to
use, especially in inner loops.  With my_rand, I lose none of this quality,
have all of my values automatically in range, and minimize the cpu time
utilization incurred by the system rand function.

--- the future ----------------------------------------------------------------

I am writing xpyre to be the base for another visualization plugin that I'm
planning and hoping to someday create.  This new plugin is to be at least as
user-configurable as WinAMP's Advanced Visualization Studio (AVS).  The main
difference will be that whereas the AVS has a (clumsy) tree view interface I'll
make my presets out of text files using either C or a C-like language.  Maybe
somebody could modify Janusz Gregorczyk's xvs plugin to be an AVS-like editor
for my presets.

# vim: set ts=4 sts=4 sw=4 tw=80 et syntax=off:
# EOF
