[LV2] Questions about passing strings and other data from UI to LV2 plugin

[David Robillard]

On Sun, 2016-11-27 at 09:58 +0100, Torbjörn Rathsman wrote:
> I need to pass a string from the UI to the plugin. From the eg-sample, it
> appears that an LV2 atom should be written to a atom port.
> 
> If I understand it correctly
> 
> 
>    1. Allocate a LV2_Atom_Forge. May that object be on the stack or does it
>    have to survive after the UI event callback has returned?
>    2. Call lv2_atom_forge_set_buffer. How do I know the required size of
>    the buffer? Is it the size of the payload (the string), or does it include
>    any headers. The example sets it to 1024 bytes for no reason. May the
>    buffer be allocated on the stack or does it have to survive the UI after
>    the UI event callback has returned?
>    3. Add some objects. The API uses key-value pairs. Should the size of
>    keys be included in the buffer size?
>    4. Write the data to an atom input port
> 
> Is that correct?

The forge is just a utility to make constructing atoms simple.  It is
not a part of the actual protocol or specification, so there are no
lifetime requirements like that.  Once you have constructed your buffer,
the forge is irrelevant.  Similarly, the buffer is irrelevant after
sending from the UI, the host must copy the data at the time of the
write call.  In this case, think of the buffer as a holder for a
message: once you send it, it's gone.  Not a "buffer" like in a plugin
that has a lifetime and is accessed externally.

That said, it's easiest to just create one for whatever purpose and keep
it around so you don't need to construct it every time (and necessary on
the plugin side since initializing it is not realtime safe).

The buffer size simply needs to be large enough to hold whatever you're
writing.  Trying to be very precise about this is tedious, since it must
include the sizes of all the atom headers and whatnot.  If you know some
reasonable upper limit of your payload, you're better off just
allocating a "large enough" buffer with sufficient space for all the
atom overhead (hence 1024 in that case).

-- 
dr