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 available capacity of the buffer
  97 */
  98 uint32_t
  99 lv2_evbuf_get_capacity(LV2_Evbuf* evbuf);
 100
 101 /**
 102    Return the actual buffer implementation.
 103    The format of the buffer returned depends on the buffer type.
 104 */
 105 void*
 106 lv2_evbuf_get_buffer(LV2_Evbuf* evbuf);
 107
 108 /**
 109    Return an iterator to the start of @p buf.
 110 */
 111 LV2_Evbuf_Iterator
 112 lv2_evbuf_begin(LV2_Evbuf* evbuf);
 113
 114 /**
 115    Return an iterator to the end of @a buf.
 116 */
 117 LV2_Evbuf_Iterator
 118 lv2_evbuf_end(LV2_Evbuf* evbuf);
 119
 120 /**
 121    Check if @p iter is valid.
 122    @return True if @p iter is valid, otherwise false (past end of buffer)
 123 */
 124 bool
 125 lv2_evbuf_is_valid(LV2_Evbuf_Iterator iter);
 126
 127 /**
 128    Advance @p iter forward one event.
 129    @p iter must be valid.
 130    @return True if @p iter is valid, otherwise false (reached end of buffer)
 131 */
 132 LV2_Evbuf_Iterator
 133 lv2_evbuf_next(LV2_Evbuf_Iterator iter);
 134
 135 /**
 136    Dereference an event iterator (i.e. get the event currently pointed to).
 137    @p iter must be valid.
 138    @p type Set to the type of the event.
 139    @p size Set to the size of the event.
 140    @p data Set to the contents of the event.
 141    @return True on success.
 142 */
 143 bool
 144 lv2_evbuf_get(LV2_Evbuf_Iterator iter,
 145               uint32_t*          frames,
 146               uint32_t*          subframes,
 147               uint32_t*          type,
 148               uint32_t*          size,
 149               uint8_t**          data);
 150
 151 /**
 152    Write an event at @p iter.
 153    The event (if any) pointed to by @p iter will be overwritten, and @p iter
 154    incremented to point to the following event (i.e. several calls to this
 155    function can be done in sequence without twiddling iter in-between).
 156    @return True if event was written, otherwise false (buffer is full).
 157 */
 158 bool
 159 lv2_evbuf_write(LV2_Evbuf_Iterator* iter,
 160                 uint32_t            frames,
 161                 uint32_t            subframes,
 162                 uint32_t            type,
 163                 uint32_t            size,
 164                 const uint8_t*      data);
 165
 166 #ifdef __cplusplus
 167 }
 168 #endif
 169
 170 #endif /* LV2_EVBUF_H */