[linux-audio-dev] Plugin APIs (again)

David Olofson david at olofson.net
Mon Dec 9 20:31:01 UTC 2002


On Tuesday 10 December 2002 01.18, Tim Hockin wrote:
> Long context, sorry
>
> > > Do let me see if I get this right:
> > >
> > > Host allocates the VVID pool (perhaps a bitmask or some other
> > > way of indicating usage)
> > > Host wants to send a VOICE_ON:
> > > 	allocates an unused VVID
> > > 	sends VOICE_ON with that VVID
> > > 	when it sends a VOICE_OFF or receives a VOICE_OFF it can mark
> > > that VVID as unused again.
> >
> > It seems like this would be a host global matter... What would be
> > the point in that? All you need is a way to address Voices within
> > *one Channel* - you don't have to worry about other Plugins, or
> > even other Channels on the same Plugin. (For table based
> > implementations, plugins have one table per Channel, and for
> > tag/search
> > implementations, you just tag Voices with VVIDs *and* Channel
> > indices.)
> >
> > > Plugin wants to send a VOICE_ON:
> > > 	calls host->get_vvids(32)
> > > 	host allocates it 32 VVIDs
> >
> > You do this when the host tells you to connect to an event port,
> > and what you do is actually:
> >
> > 	first_id = host->get_vvids(target_port, number_of_VVIDs);
> > 	if(first_id < 0)
> > 		give_up;
> >
> > Note that the first_id thing is actually *only* needed when the
> > host connects multiple output ports to the same input port.
> > Normally, it will be 0.
> >
> > The host will at some point ask the plugin, or rather *tell* the
> > plugin how many VVIDs are needed for each Event Input port it
> > wants to connect. Plugins may say
> >
> > 	"I don't have Voices!"
> > 		(No need for VVIDs...)
> >
> > or
> >
> > 	"Anything that fits makes a fine VVID for me."
> > 		(Full 32 bit range, no actual allocation needed.
> >
> > or
> >
> > 	"I need internal tables. How many VVIDs do you need?"
> > 		(Host says N, and plugin allocates tables for N
> > 		VVIDs, addressed as 0..N-1.)
>
> OK, let me again see if I understand (sorry for being dense,
> something is not clicking this week..)

Well, this isn't trivial stuff - and at times, I'm exceptionally good 
at writing lots of text without saying much that makes sense...! :-)


> // Normal case of host connecting to an event_port
> Host somewhere:
>   evp = instrument->get_event_port(n);
>   vvid_max = instrument->alloc_vvids(evp, 256); /* should be
>   enough! */

(It's actually related to Channels the way I see it, but that doesn't 
matter much here.)


> Plugin alloc_vvids:
>   /* make room for specified number of vvids, or what not */
>   return the requested # back, or negative on error

Yeah. If you use tag/search, just return "OK" here (or NULL callback 
pointer for this?), since anything that fits in the field goes.


> Host again:
>   store the number of VVIDs somehow - array/list

Yeah.


> So how does a plugin controlling another plugin go?

*Someone* has to decide how many Virtual Voices a "sender" needs to 
be able to express what it's going to send. Something tells me that 
this is not obviously either "user decides" or "sender decides", but 
rather something in between. *heh* Any ideas? (It's somewhat like 
setting up a voice reserve for a synth, but not as "hard" a 
restriction as that....)

Anyway, say you want to connect a sequencer output channel (a bunch 
of controls) to this instrument. The host starts by asking the 
sequencer output to connect to the instrument:

	sequencer->connect_output(seq_output_channel,
			instrument, inst_input_channel);

In the sequencer plugin:

connect_output(output, target, target_ch)
{
	/*
	 * Allocate a range of VVIDs for out target channel.
	 * need_vvids would be this mystical number that either
	 * we (the sequencer) or the user must decide on.
	 */
	first_vvid = host->get_vvids(target, target_ch, need_vvids);
	if(first_vvid < 0)
		return "FAILURE";
	/*
	 * We may now use VVIDs in the range
	 * [first_vvid, first_vvid + need_vvids - 1]
	 */

	...connect our output controls, getting control IDs and stuff...

	return "OK";
}


In get_vvids(), the host will try to allocate a contiguous range of 
VVIDs from the range allocated from the instrument. Obviously, if 
there are not enough VVIDs, the host must call 
instrument->alloc_vvids() again, to allocate a larger number of 
VVIDs, before it can grant the request from the sequencer's connect 
function. If that fails (cannot be done due to the connection being 
done from RT context or something), the connection will simply fail.


If you now connect another output channel to the same input channel 
of that instrument, the host will have to allocate a different range 
of VVIDs. So, you may quickly run out of VVIDs if you have a similar 
default allocation size for sequencers and the like. They'll need at 
least some 88 VVIDs to be on the safe side, which means you can't 
connect more than two outputs to one input before running out of 
VVIDs - even if you actually only use a few VVIDs on each output. 


//David Olofson - Programmer, Composer, Open Source Advocate

.- The Return of Audiality! --------------------------------.
| Free/Open Source Audio Engine for use in Games or Studio. |
| RT and off-line synth. Scripting. Sample accurate timing. |
`---------------------------> http://olofson.net/audiality -'
.- M A I A -------------------------------------------------.
|    The Multimedia Application Integration Architecture    |
`----------------------------> http://www.linuxdj.com/maia -'
   --- http://olofson.net --- http://www.reologica.se ---



More information about the Linux-audio-dev mailing list