From 08203463a3056759e33bff5fda294ddc40eda031 Mon Sep 17 00:00:00 2001
From: David Robillard <d@drobilla.net>
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(-)
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