From 08203463a3056759e33bff5fda294ddc40eda031 Mon Sep 17 00:00:00 2001 From: David Robillard Date: Sat, 3 Mar 2012 21:12:15 +0000 Subject: Add a warning about the 0 reference problem. --- lv2/lv2plug.in/ns/ext/atom/forge.h | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) (limited to 'lv2/lv2plug.in/ns/ext/atom') 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, -- cgit v1.2.1