libs/ardour/lv2_evbuf.h

   1 /*
   2   Copyright 2008-2012 David Robillard <http://drobilla.net>
   3
   4   Permission to use, copy, modify, and/or distribute this software for any
   5   purpose with or without fee is hereby granted, provided that the above
   6   copyright notice and this permission notice appear in all copies.
   7
   8   THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
   9   WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  10   MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  11   ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  12   WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  13   ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  14   OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  15 */
  16
  17 #ifndef LV2_EVBUF_H
  18 #define LV2_EVBUF_H
  19
  20 #include <stdint.h>
  21
  22 #ifdef __cplusplus
  23 extern "C" {
  24 #else
  25 #include <stdbool.h>
  26 #endif
  27
  28 /**
  29    Format of actual buffer.
  30 */
  31 typedef enum {
  32         /**
  33            An (old) ev:EventBuffer (LV2_Event_Buffer).
  34         */
  35         LV2_EVBUF_EVENT,
  36
  37         /**
  38            A (new) atom:Sequence (LV2_Atom_Sequence).
  39         */
  40         LV2_EVBUF_ATOM
  41 } LV2_Evbuf_Type;
  42
  43 /**
  44    An abstract/opaque LV2 event buffer.
  45 */
  46 typedef struct LV2_Evbuf_Impl LV2_Evbuf;
  47
  48 /**
  49    An iterator over an LV2_Evbuf.
  50 */
  51 typedef struct {
  52         LV2_Evbuf* evbuf;
  53         uint32_t   offset;
  54 } LV2_Evbuf_Iterator;
  55
  56 /**
  57    Allocate a new, empty event buffer.
  58    URIDs for atom:Chunk and atom:Sequence must be passed for LV2_EVBUF_ATOM.
  59 */
  60 LV2_Evbuf*
  61 lv2_evbuf_new(uint32_t       capacity,
  62               LV2_Evbuf_Type type,
  63               uint32_t       atom_Chunk,
  64               uint32_t       atom_Sequence);
  65
  66 /**
  67    Free an event buffer allocated with lv2_evbuf_new.
  68 */
  69 void
  70 lv2_evbuf_free(LV2_Evbuf* evbuf);
  71
  72 /**
  73    Reset and change the type of an existing event buffer.
  74    URIDs for atom:Chunk and atom:Sequence must be passed for LV2_EVBUF_ATOM.
  75 */
  76 void
  77 lv2_evbuf_set_type(LV2_Evbuf* evbuf, LV2_Evbuf_Type type);
  78
  79 /**
  80    Clear and initialize an existing event buffer.
  81    The contents of buf are ignored entirely and overwritten, except capacity
  82    which is unmodified.
  83    If input is false and this is an atom buffer, the buffer will be prepared
  84    for writing by the plugin.  This MUST be called before every run cycle.
  85 */
  86 void
  87 lv2_evbuf_reset(LV2_Evbuf* evbuf, bool input);
  88
  89 /**
  90    Return the total padded size of the events stored in the buffer.
  91 */
  92 uint32_t
  93 lv2_evbuf_get_size(LV2_Evbuf* evbuf);
  94
  95 /**
  96    Return the actual buffer implementation.
  97    The format of the buffer returned depends on the buffer type.
  98 */
  99 void*
 100 lv2_evbuf_get_buffer(LV2_Evbuf* evbuf);
 101
 102 /**
 103    Return an iterator to the start of @p buf.
 104 */
 105 LV2_Evbuf_Iterator
 106 lv2_evbuf_begin(LV2_Evbuf* evbuf);
 107
 108 /**
 109    Return an iterator to the end of @a buf.
 110 */
 111 LV2_Evbuf_Iterator
 112 lv2_evbuf_end(LV2_Evbuf* evbuf);
 113
 114 /**
 115    Check if @p iter is valid.
 116    @return True if @p iter is valid, otherwise false (past end of buffer)
 117 */
 118 bool
 119 lv2_evbuf_is_valid(LV2_Evbuf_Iterator iter);
 120
 121 /**
 122    Advance @p iter forward one event.
 123    @p iter must be valid.
 124    @return True if @p iter is valid, otherwise false (reached end of buffer)
 125 */
 126 LV2_Evbuf_Iterator
 127 lv2_evbuf_next(LV2_Evbuf_Iterator iter);
 128
 129 /**
 130    Dereference an event iterator (i.e. get the event currently pointed to).
 131    @p iter must be valid.
 132    @p type Set to the type of the event.
 133    @p size Set to the size of the event.
 134    @p data Set to the contents of the event.
 135    @return True on success.
 136 */
 137 bool
 138 lv2_evbuf_get(LV2_Evbuf_Iterator iter,
 139               uint32_t*          frames,
 140               uint32_t*          subframes,
 141               uint32_t*          type,
 142               uint32_t*          size,
 143               uint8_t**          data);
 144
 145 /**
 146    Write an event at @p iter.
 147    The event (if any) pointed to by @p iter will be overwritten, and @p iter
 148    incremented to point to the following event (i.e. several calls to this
 149    function can be done in sequence without twiddling iter in-between).
 150    @return True if event was written, otherwise false (buffer is full).
 151 */
 152 bool
 153 lv2_evbuf_write(LV2_Evbuf_Iterator* iter,
 154                 uint32_t            frames,
 155                 uint32_t            subframes,
 156                 uint32_t            type,
 157                 uint32_t            size,
 158                 const uint8_t*      data);
 159
 160 #ifdef __cplusplus
 161 }
 162 #endif
 163
 164 #endif /* LV2_EVBUF_H */