CL-Amp
Output Plugin Document v1
You find the latest version here: http://www4.tripnet.se/~slarti/CL-Amp_OutPlug_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. This 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 read 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 once when CL-Amp
has loaded the plugin into memory.
Cleanup() is called once when
CL-Amp is going to unload the plugin from memory.
--- 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:
-
If Question is TRUE
-
TRUE = This function is supported
-
FALSE = This function is NOT supported
-
If Question is FALSE:
-
TRUE = Success
FALSE = Something went wrong
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
---
InitRecording() - Thread
B
bool InitRecording(const char *FileName, const
char *FileName2, long Frequency, short Channels, bool SampleIsOnly8Bits);
CL-Amp call this function for every new song it's starting to play.
Your plugin should open necessary files, allocate memory or hardware or
whatever and be prepared to receive audio data...
The audio data is normally 16 bits but if SampleIsOnly8Bits
is true it's just 8 bits!
FileName is always given and
is the name of the current file.
FileName2 is seldom given (mostly
NULL) but it's the name of the new file when crossfading is in progress!
PutAudio() - Thread
B
bool PutAudio(const char *Buff, long Size);
CL-Amp will give you audio data through this function. The data shall
be of the format stated in the InitRecording()
call.
CleanupRecording() - Thread
B
void CleanupPlaying ();
Called when the recording session is over. A chance to close files
and clean things up...
The PlayerInfoStruct Flags
The different values that can be OR'ed together is:
-
OUTPLUG_AFTER_MIXER
The plugin will always get 44100Hz, 16bit, Stereo sound with cross
fadings and DSP effects included.
(Without this flag the cross fading is forbidden in CL-Amp and the plugin
will receive the raw audio data from the current Input plugin)
-
OUTPLUG_CROSSFADE_START
The start of a cross fade section will be treated as the beginning
of a new song
-
OUTPLUG_CROSSFADE_END
The ending of a cross fade section will be treated as the beginning
of a new song
(Giving both OUTPLUG_CROSSFADE_START
and OUTPLUG_CROSSFADE_END will treat
the cross fade section as an own file. And not given the flags at all will
make songs that's glued together with cross fade to be treated as one large
file)
-
OUTPLUG_FORBID_FADE
Fading will NOT be done when this output plugin is used (it's turned
off anyway if the OUTPLUG_AFTER_MIXER
is not given!)
Copyright Claes
Löfqvist