[LV2] lv2_descriptor() considered harmful

[David Robillard]

On Sun, 2012-02-26 at 14:02 +0100, Martin wrote:
[...]
> my intended workflow of a user is:
> 
> - install binary package containing the .so file (system wide)
> - create dsp code using a scripting language and include all input and 
> output specifications which go into the manifest later. The amount of 
> inputs and outputs is fixed. (at the moment: stereo, 5 controls).
> 
> - parse the script in order to create the manifest
> - copy manifest + .so (already compiled) and all other needed files into 
> .lv2 bundle
> - copy this to into ~/.lv2 (so the script's code can still manipulated 
> by the user - except of the uri and controls)

So you have basically a manual build process and none of this happens at
discovery/instantiation time so we don't have to worry about any of that
as far as the LV2 API.

> after this procedure nothing should be necessary to be compiled. The 
> plugin .so file should be able to read its URI from its own bundle 
> directory at discovery by looking into its manifest (or an extra file in 
> the bundle directory).

... except you need to know what bundle you are in during discovery.
Right, this is the problem other have had (I myself with Ingen).  It is
an error in the core API.

Basically we need a discovery function with a bundle parameter so you
can read <whatever> in the bundle before telling the host what plugins
(i.e. what URIs) are contained in the bundle.

> sure, that's also what I had in mind. I hope reading the uri from the 
> bundle directory is intended... ;)

I definitely think reading from the bundle as discovery time needs to be
possible, for plugins implemented as data or scripts or whatever.  I
think we should wrap up the library stuff in a descriptor so we also get
a sane portable cleanup mechanism in the process, e.g.:

typedef void* LV2_Lib_Handle;

/**
   Descriptor for a plugin library.

   Each plugin shared library has exactly one of these objects,
   accessed via the lv2_lib_descriptor() function in that library.
*/
typedef struct {
	/**
	   Opaque library data which must be passed as the first
	   parameter to all the methods of this struct.
	*/
	LV2_Lib_Handle handle;

	/**
	   The size of this struct.
	*/
	uint32_t size;

	/**
	   Destroy this library descriptor.
	*/
	void (*cleanup)(LV2_Lib_Handle lib_handle);

	/**
	   Plugin accessor.

	   Plugins are accessed by index using values from 0 upwards.
	   Out of range indices MUST result in this function returning
	   NULL, so the host can enumerate plugins by increasing @a
	   index until NULL is returned.
	*/
	LV2_Descriptor const* (*descriptor)(LV2_Lib_Handle lib_handle,
	                                    uint32_t       index);
        
} LV2_Lib_Descriptor;

/**
   Prototype for library accessor function.

   This is the entry point for a plugin library.  Hosts load this
   symbol from the library and call this function to obtain a
   library descriptor which can be used to access all the UIs
   contained in this library.  The returned object must not be
   destroyed (using LV2_Lib_Descriptor::cleanup()) until all
   plugins loaded from that library have been destroyed.
*/
LV2_Lib_Descriptor const*
lv2_lib_descriptor(const char*                bundle_path,
                   const LV2_Feature *const * features);

/**
   Type of the lv2_lib_descriptor() function in an LV2 library.
*/
typedef LV2_Lib_Descriptor const*
(*LV2_Lib_Descriptor_Func)(const char*                bundle_path,
                           const LV2_Feature *const * features);

-dr