From 271990ab61ea170a65f01362198c4e9137bd77de Mon Sep 17 00:00:00 2001 From: David Robillard Date: Sat, 18 Feb 2012 07:09:15 +0000 Subject: Update documentation. --- lv2/lv2plug.in/ns/ext/atom/forge.h | 26 ++++++++++++++++++++------ 1 file changed, 20 insertions(+), 6 deletions(-) (limited to 'lv2') diff --git a/lv2/lv2plug.in/ns/ext/atom/forge.h b/lv2/lv2plug.in/ns/ext/atom/forge.h index 0f32db3..19b76e7 100644 --- a/lv2/lv2plug.in/ns/ext/atom/forge.h +++ b/lv2/lv2plug.in/ns/ext/atom/forge.h @@ -21,9 +21,17 @@ atoms by calling the provided functions to append atoms (or atom headers) in the correct order. - All output is written to a user-provided buffer. This entire API is - realtime safe and suitable for writing to output port buffers in the run - method. + The size of containers is automatically handled to any depth. All functions + that start a container take a pointer to an uninitialised stack frame which + will be initialised and must be popped when the container is finished. + + All output is written to a user-provided buffer, or sink function. Thus, + this API can be used to create atoms on the stack, on the heap, in LV2 port + buffers, or in a ringbuffer. + + This entire API is realtime safe if used with a buffer or a realtime safe + sink, except lv2_atom_forge_init(), which is only realtime safe if the URI + map function is. Note these functions are all static inline, do not take their address. @@ -34,7 +42,6 @@ #define LV2_ATOM_FORGE_H #include -#include #include "lv2/lv2plug.in/ns/ext/atom/atom-helpers.h" #include "lv2/lv2plug.in/ns/ext/atom/atom.h" @@ -86,6 +93,12 @@ typedef struct { LV2_URID Vector; } LV2_Atom_Forge; +/** + Push a stack frame. + This is done automatically by container functions (which take a stack frame + pointer), but may be called by the user to push the top level container when + writing to an existing Atom. +*/ static inline LV2_Atom* lv2_atom_forge_push(LV2_Atom_Forge* forge, LV2_Atom_Forge_Frame* frame, @@ -97,6 +110,7 @@ lv2_atom_forge_push(LV2_Atom_Forge* forge, return atom; } +/** Pop a stack frame. This must be called when a container is finished. */ static inline void lv2_atom_forge_pop(LV2_Atom_Forge* forge, LV2_Atom_Forge_Frame* frame) { @@ -158,6 +172,7 @@ lv2_atom_forge_write_nopad(LV2_Atom_Forge* forge, const void* data, uint32_t size) { + /* TODO: Write to sink, if set */ uint8_t* const out = forge->buf + forge->offset; if (forge->offset + size > forge->size) { return NULL; @@ -494,8 +509,7 @@ static inline LV2_Atom_Event* lv2_atom_forge_beat_time(LV2_Atom_Forge* forge, double beats) { - return (LV2_Atom_Event*)lv2_atom_forge_write( - forge, &beats, sizeof(beats)); + return (LV2_Atom_Event*)lv2_atom_forge_write(forge, &beats, sizeof(beats)); } #ifdef __cplusplus -- cgit v1.2.1