Visualisation plugin API for XBMC

[Frodo]

hi,

i'm setting up an architecture which allows other devs to develop a visualisation plugin for xbmc

from the settings->music the end-user can select which visz. he/she wants and xbmc will use that one.
so how does it work?
first :
1. visz. plugins are normal .dlls but with the extension .vis
2. visz. plugins should b copied into the visualisations/ subdirectory on your xbox
3. visz. plugins must use a minimal set of dependencies. they should not depend on windows kernel/gdi or other things!


so how to program one?
here's a skeleton of a visz. plugin .dll:

// spectrum.cpp: implementation of the cspectrum class.
//
//////////////////////////////////////////////////////////////////////

#include <xtl.h>
#pragma comment (lib, "lib/xbox_dx8.lib" )

extern "c"
{
struct vis_info {
bool bwantsfreq;
int isyncdelay;
// int iaudiodatalength;
// int ifreqdatalength;
};
};

vis_info vinfo;
static lpdirect3ddevice8 m_pd3ddevice;
extern "c" void create(lpdirect3ddevice8 pd3ddevice, int iscreenwidth, int iscreenheight, const char* szvisname)
{
}

extern "c" void start(int ichannels, int isamplespersec, int ibitspersample, const char* szsongname)
{
}


extern "c" void audiodata(short* paudiodata, int iaudiodatalength, float *pfreqdata, int ifreqdatalength)
{
}

extern "c" void render()
{
}


extern "c" void stop()
{
}


extern "c" void getinfo(vis_info* pinfo)
{
memcpy(pinfo,&vinfo,sizeof(struct vis_info ) );
}
extern "c"
{
struct visualisation
{
public:
// gets called once during initialisation. allows vis. plugin to initialize itself
// pd3ddevice is a pointer to the dx8 device which you can use for dx8
// iscreenwidth/iscreenheight are the gui's screenwidth/screenheight in pixels
// szvisualisationname contains the name of the visualisation like goom or spectrum,...
void (--cdecl* create)(lpdirect3ddevice8 pd3ddevice, int iscreenwidth, int iscreenheight, const char* szvisualisationname);

// gets called at the start of a new song
// ichannels = number of audio channels
// ibitspersample = bits of each sample ( 8 or 16)
// isamplespersec = number of samples / sec.
// szsongname = name of the current song
void (--cdecl* start)(int ichannels, int isamplespersec, int ibitspersample, const char* szsongname);

// gets called if xbmc has new audio samples for the vis. plugin
// paudiodata is a short [channels][iaudiodatalength] array of raw audio samples
// pfreqdata is a array of float[channels][ifreqdatalength] of fft-ed audio samples
void (--cdecl* audiodata)(short* paudiodata, int iaudiodatalength, float *pfreqdata, int ifreqdatalength);

// gets called if vis. plugin should render itself
void (--cdecl* render) ();

// gets called if vis. should stop & cleanup
void (--cdecl* stop)();

// gets called if xbmc wants to know the visz. parameters specified by the vis_info struct
void (--cdecl* getinfo)(vis_info* pinfo);
};

void --declspec(dllexport) get_module(struct visualisation* pvisz)
{
pvisz->create = create;
pvisz->start = start;
pvisz->audiodata = audiodata;
pvisz->render = render;
pvisz->stop = stop;
pvisz->getinfo = getinfo;
}
};

please note that due to a bug in the forums i cant post any underscores. so i replaced the underscores with --
xbmc will first call get_module() to retrieve the visualisation struct. the plugin will give xbmc the visualisation struct filled with function pointers to all visz. routines needed by xbmc


well thats it for now. remember this is all premature.
no plugins are available yet, but hopefully we'll see one soon

frodo

[jmarshall]

frodo:

what a great interface! i wonder how long it will take me to port the spectrum analyser...

perhaps having the possibility to transfer other information regarding the audio would be a good feature - things such as track, album, artist info etc. might be an idea?

i'll look at compiling up the spectrum analyser plugin - the only other dependencies are xmldocument for loading the config file iirc.

cheers,
jonathan

[Frodo]

hehehe, yeah i must admit i copied the ideas from you visz. classes :d
about copying more info, i'll see if i can come up with something

frodo

[jmarshall]

that's cool. have you implemented the fft code + delay stuff? if so, i'll look at having a play with getting the sa into a dll. (i haven't done any dll based stuff before, so this should be an adventure - i may ask some questions when i get stuck)

cheers,
jonathan

[Frodo]

have you implemented the fft code + delay stuff?

yes, well you did. i just copied it into xbmc
anyway i forgot 2 add a method to pass the vis_info struct.
its added now (see updated skeleton above)

when we got a basic plugin working i'll add other things like the album/artist etc info.

about the dll, yes its tricky.
compiling a .dll is easy, but we dont want any dependencies on windows. so i'm writing my own import libraries now which you can use. when its working i'll put it in cvs together with an complete working example plugin project

frodo

[Gamester17]

very cool, but just wondering how the customizable part in viz such as jmarshall's spectrum analyzer gonna work?
(maybe add a set of parameters inside that can be selected from within gui, and/or a seprate xml file for it?)

[Frodo]

but just wondering how the customizable part in viz such as jmarshall's spectrum analyzer gonna work?

for version 1 :seperate xml

frodo

[Gamester17]

Originally Posted by (frodo @ oct. 13 2003,13:59)

for version 1 :seperate xml

k, for v2 maybe devide xml into sections (each which own name) & make those selectable from gui

[jmarshall]

sounds good, frodo.

the vis_info struct i figured might be the way to transfer info in the future, but i hadn't really thought about it all that much, though.

i had a play with doing some dll stuff last night. i basically just generated a .dll project, then "modified" it via editing the .vcproj file to use xbox stuff. had to muck around with .lib files to include when linking + still didn't get all the stuff it needed - i was kind of shooting in the dark to be honest!

let me know when you have some import libraries sorted + the example project and i'll do the sa.

cheers,
jonathan

[Frodo]

well here's the status so far.
1. i ported your spectrum analyser to a visz. dll
2. xbmc can load it
3. all the function calls seem 2 work (create/stop/start/render...)

but the 2nd time i call render() it crashes
my guess is that there's something wrong with the directx linking, so i'll look into it

frodo