CL-Amp Visual Plugin Document v1

You find the latest version here: http://www4.tripnet.se/~slarti/CL-Amp_Visual_Doc.htm

What's a plugin?

A CL-Amp plugin is simply a AddOn library in which 1 function is known by CL-Amp. CL-Amp is loading the Plugin into memory and is then calling the known function. The function is returning a pointer to a OutputPlugin class object which will be used as an interface between CL-Amp and the plugin.

BeOS = Threads

There is ONE consideration I have to point out! Some of the functions are called from a thread called A and the rest from thread B. Since its important that they dont use memory between each others in a clumpsy way, I try to mark this as clearly as possible in the list below!
Its not anything to worry about, just keep in mind that when a thread has written one variable halfways another thread can read the value. Since some bytes are  from the new value and some are from the old value, the resulting value can be whatever, which will cause dramatic effects and perhaps also crash the program. Simply avoid sharing variables across such functions!
I have tried to keep all thread handling inside CL-Amp to make it easier to make the plugin!
 

The hook functions that should be provided

The functions that should be provided by using OutputPlugin as a base class and overriding the virtual versions are:

Init()  - No thread considerations

Cleanup()  - No thread considerations

void Init ();
void Cleanup ();

Init() is called when the user activates the plugin (or when the activation is restored at startup).

Cleanup() is called when the user or CL-Amp itself deactivates the plugin

If you open a window for showing your effects, it should be opened in Init() and be closed and deleted in Cleanup(). If the plugin itself wants to tell CL-Amp to deactivate it (as if the user click on the plugin's close window button), simply call the SendToCLAmp_Deactivate() function (declared in the VisualizationPlugin class). It will send a message to CL-Amp to deactivate the plugin and Cleanup() will be called (in which the plugin closes the window)...

--- Thread A is calling the following functions ---

About()   - Thread A

Prefs()   - Thread A

bool About (bool Question);
bool Prefs (bool Question);

[These functions doesn't have to be provided... A empty function returning false is enough!]

About() - To show a About window. Make your own window and display it as you like... Telling a little about the plugin and its creator!?
Prefs() - If there are preferences that can be adjusted, it should be done from a window which you can display here...

Please, dont hang in any of these functions!! Display your window and return. Let the window take care of itself!

If Question is TRUE the call is only a question to get to know if this function is supported or not!
ONLY make your window show up if Question is FALSE!
Return value:

GetFlags()   - Thread A

unsigned long GetFlags();

This functions should return flags to tell CL-Amp how to handle certain things. The flags are described near the end of this document!

 --- Thread B is calling the following functions ---

Render()   - Thread B

bool Render(const struct VisAudioInfoStruct *info);

CL-Amp call this function for every audio packet it sends to the MediaKit. The given info is containing the raw audio data and the spectrum analyzer data.

The GetFlags() flags

The different values that can be OR'ed together is:

The VisAudioInfoStruct

This structure is used to let the plugin get info about every block of audio CL-Amp is creating for output... It's given to the Render() function....

struct VisAudioInfoStruct {

int Frequency;
int Channels;
int LatencyTime;
int DelayTime;
int SpectrumChannels;
int WaveFormChannels;
const unsigned char *SpectrumData;
const short *WaveFormData;
};
Copyright Claes Löfqvist