
                         YAF CONCEPT OVERVIEW


"One Liner"
========

Simply the idea ist based on the Modell-View-Controller concept.


DESCRIPTION
===========

The YAF library makes it easy to handle multimedia data. A programmer
of a e.g. wav/mp3 player can quickly start with the GUI and
does not have to deal with e.g. "ioctl" of the Soundcard.


The basic concept of the library is, that it offers the programmer
a mechanisms to creates devices, like players, spectrumanalyser,
mixers which then must be conneted to each other.
It's comparable to the "real world": You buy a CD-Player and
must plug it into your Amplifier.

This is a simple code example

cdplayer=new CDPlayer();
audioDevice=new AudioDevice();
cdplayer->connect(audiodevice);

If you then press "play","jump" on the cdplayer he send all
his data to the audiodevice.

The library offers a set of players, and a set of devices.


BACKGROUND
==========

The implementation is similar to the well known modell-view-controller
idea. First you build all the things you currently need, like players,
audiooutputs, recorders. Then you connect all these things together.
This is then your modell.

Then you can create a view, which means : you write a nice GUI to
your modell. These things are completly seperated, thus you must
connect them. The library offers you a method that your modell
emits signals with the toolkits event mechanism. For QT this means
you connect the GUI signal "play" with the slot of the
CDPlayer in the modell:

connect(playButton,SIGNAL(play()),cdplayer,SLOT(play());


This is the way the gui controls the modell. But the modell emits
events es well. The library has "timeDevices". You simple plug them
into the player, then this timedevice emits "timeEvents" which
you can show in your gui.

connect(timeDevice,SIGNAL(time(int)),myTimeGui,SLOT(showSec(int)));

This is the way from the modell to your gui.


RESULT
======

There are a few drawbacks. 

* First, the library makes heavily use of
  POSIX threads, which do not work on older libc-Linuxses.
* Second, threads have the problem that your GUI does not necessarily
  get events in a defined order.(Parts of the library orders 
  signals already in sequences, thus you don't get a "playing ready"
  when your time information says that there is 1 hour remaining to
  play.)
* Third, undiscovered problems: In the test application everthing works fine. 
  But there maybe other (undiscovered) cirumstances under which
  the MVC concept fails.


The testapplication shows that the threaded modell works fine thus
there are no plans to change the threaded modell to
a synchronous one (although this may become an issue in the future)
For the POSIX problem there is simply no workaround. But old Linux
libc systems are dying. 
The library only uses the very basic set of thread functions, 
other platforms compile fine.
The library has been tested on LINUX,FreeBSD and BSD/OS.
On BSD/OS the library showed up a bug in the kernel, which should
be fixed soon.
Commercial Unix have POSIX threads for a long time, so there
should be no porting issue.



KNOWN PROBLEMS
==============

* Controller
------------


One problem which is currently unsolved, is that the controller
calls are asynchronous. This means, if you call:

player->open("my.wav") 

You did not get a result if the call succeds/fails.
The reson is that the underlying toolkit event mechanism is
used for receiving the return code. And if you wait for the
result (block the toolkit) you never get it _because_ the
toolkit is blocked. On the one hand this asynchronous deliver is
not what a programmer (may) likes, but on the other it is sometime usefull,
if you consider sound effects. In a game it is really stupid to call

player->open("rocket-explosion.wav");  // BLOCKS
player->play();  // BLOCKS as well?

and then wait until the explosion is played. 
The best thing would be to make this configurable, like:

player->play("rocket-explosion.wav",_BLOCK_);

But this problem is currently unsolved. The behaviour default to NON_BLOCK.


* Data
------

The Music which is passed around in the Graph does not "age". This
means, a programmer of a game who issue a command

player->open("rocket-explosion.wav",_NON_BLOCK);

cannot say that the sound should be played in the next second, or
if this is not possible, due to systemload, not at all.
This problem can be quickly solved, but currently seems not to
be very important.





