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 #include <stdbool.h>
  22
  23 #ifdef __cplusplus
  24 extern "C" {
  25 #endif
  26
  27 /**
  28    Format of actual buffer.
  29 */
  30 typedef enum {
  31         /**
  32            An (old) ev:EventBuffer (LV2_Event_Buffer).
  33         */
  34         LV2_EVBUF_EVENT,
  35
  36         /**
  37            A (new) atom:Sequence (LV2_Atom_Sequence).
  38         */
  39         LV2_EVBUF_ATOM
  40 } LV2_Evbuf_Type;
  41
  42 /**
  43    An abstract/opaque LV2 event buffer.
  44 */
  45 typedef struct LV2_Evbuf_Impl LV2_Evbuf;
  46
  47 /**
  48    An iterator over an LV2_Evbuf.
  49 */
  50 typedef struct {
  51         LV2_Evbuf* evbuf;
  52         uint32_t   offset;
  53 } LV2_Evbuf_Iterator;
  54
  55 /**
  56    Allocate a new, empty event buffer.
  57    The URID for atom:Sequence must be passed for atom_Sequence if type is
  58    LV2_EVBUF_ATOM.
  59 */
  60 LV2_Evbuf*
  61 lv2_evbuf_new(uint32_t capacity, LV2_Evbuf_Type type, uint32_t atom_type);
  62
  63 /**
  64    Free an event buffer allocated with lv2_evbuf_new.
  65 */
  66 void
  67 lv2_evbuf_free(LV2_Evbuf* evbuf);
  68
  69 /**
  70    Change the type of an existing event buffer.  This will clear and reset the
  71    buffer, it is not possible to change the type and preserve the buffer
  72    contents since the formats differ.  The URID for atom:Sequence must be
  73    passed for atom_Sequence if type is LV2_EVBUF_ATOM.
  74 */
  75 void
  76 lv2_evbuf_set_type(LV2_Evbuf* evbuf, LV2_Evbuf_Type type, uint32_t atom_type);
  77
  78 /**
  79    Clear and initialize an existing event buffer.
  80    The contents of buf are ignored entirely and overwritten, except capacity
  81    which is unmodified.
  82 */
  83 void
  84 lv2_evbuf_reset(LV2_Evbuf* evbuf);
  85
  86 /**
  87    Return the total padded size of the events stored in the buffer.
  88 */
  89 uint32_t
  90 lv2_evbuf_get_size(LV2_Evbuf* evbuf);
  91
  92 /**
  93    Return the actual buffer implementation.
  94    The format of the buffer returned depends on the buffer type.
  95 */
  96 void*
  97 lv2_evbuf_get_buffer(LV2_Evbuf* evbuf);
  98
  99 /**
 100    Return an iterator to the start of @p buf.
 101 */
 102 LV2_Evbuf_Iterator
 103 lv2_evbuf_begin(LV2_Evbuf* evbuf);
 104
 105 /**
 106    Return an iterator to the end of @a buf.
 107 */
 108 LV2_Evbuf_Iterator
 109 lv2_evbuf_end(LV2_Evbuf* evbuf);
 110
 111 /**
 112    Check if @p iter is valid.
 113    @return True if @p iter is valid, otherwise false (past end of buffer)
 114 */
 115 bool
 116 lv2_evbuf_is_valid(LV2_Evbuf_Iterator iter);
 117
 118 /**
 119    Advance @p iter forward one event.
 120    @p iter must be valid.
 121    @return True if @p iter is valid, otherwise false (reached end of buffer)
 122 */
 123 LV2_Evbuf_Iterator
 124 lv2_evbuf_next(LV2_Evbuf_Iterator iter);
 125
 126 /**
 127    Dereference an event iterator (i.e. get the event currently pointed to).
 128    @p iter must be valid.
 129    @p type Set to the type of the event.
 130    @p size Set to the size of the event.
 131    @p data Set to the contents of the event.
 132    @return True on success.
 133 */
 134 bool
 135 lv2_evbuf_get(LV2_Evbuf_Iterator iter,
 136               uint32_t*          frames,
 137               uint32_t*          subframes,
 138               uint32_t*          type,
 139               uint32_t*          size,
 140               uint8_t**          data);
 141
 142 /**
 143    Write an event at @p iter.
 144    The event (if any) pointed to by @p iter will be overwritten, and @p iter
 145    incremented to point to the following event (i.e. several calls to this
 146    function can be done in sequence without twiddling iter in-between).
 147    @return True if event was written, otherwise false (buffer is full).
 148 */
 149 bool
 150 lv2_evbuf_write(LV2_Evbuf_Iterator* iter,
 151                 uint32_t            frames,
 152                 uint32_t            subframes,
 153                 uint32_t            type,
 154                 uint32_t            size,
 155                 const uint8_t*      data);
 156
 157 #ifdef __cplusplus
 158 }
 159 #endif
 160
 161 #endif /* LV2_EVBUF_H */