diff options
| -rw-r--r-- | lv2/lv2plug.in/ns/ext/atom/forge.h | 18 |
1 files changed, 10 insertions, 8 deletions
diff --git a/lv2/lv2plug.in/ns/ext/atom/forge.h b/lv2/lv2plug.in/ns/ext/atom/forge.h index 82e80eb..2860ab1 100644 --- a/lv2/lv2plug.in/ns/ext/atom/forge.h +++ b/lv2/lv2plug.in/ns/ext/atom/forge.h @@ -145,14 +145,16 @@ lv2_atom_forge_set_buffer(LV2_Atom_Forge* forge, uint8_t* buf, size_t size) /** Set the sink function where @p forge will write output. - The return value of forge functions is a pointer to the written data, which - is used for updating parent sizes. To enable this, the sink function must - return a valid pointer to a contiguous LV2_Atom header. For ringbuffers, - this should be possible as long as the size of the buffer is a multiple of - sizeof(LV2_Atom), since atoms are always aligned. When using a ringbuffer, - the returned pointers may not point to a complete atom (including body). - The user must take care to only use these return values in a way compatible - with the sink used. + The return value of forge functions is an LV2_Atom_Forge_Ref which is an + integer type safe to use as a pointer but is otherwise opaque. The sink + function must return a ref that can be dereferenced to access as least + sizeof(LV2_Atom) bytes of the written data, so sizes can be updated. For + ringbuffers, this should be possible as long as the size of the buffer is a + multiple of sizeof(LV2_Atom), since atoms are always aligned. + + Note that 0 is an invalid reference, so if you are using a buffer offset be + sure to offset it such that 0 is never a valid reference. You will get + confusing errors otherwise. */ static inline void lv2_atom_forge_set_sink(LV2_Atom_Forge* forge, |