aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorDavid Robillard <d@drobilla.net>2012-03-03 21:12:15 +0000
committerDavid Robillard <d@drobilla.net>2012-03-03 21:12:15 +0000
commit08203463a3056759e33bff5fda294ddc40eda031 (patch)
tree9912807cd95843042d0a5f1679c68fba2a4edc0b
parent2a931ba3f49217dd1041fef9587421495041e6ce (diff)
downloadlv2-08203463a3056759e33bff5fda294ddc40eda031.tar.xz
Add a warning about the 0 reference problem.
-rw-r--r--lv2/lv2plug.in/ns/ext/atom/forge.h18
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,