gst-libs/gst/audio/gstringbuffer.h

   1 /* GStreamer
   2  * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
   3  *                    2005 Wim Taymans <wim@fluendo.com>
   4  *
   5  * gstringbuffer.h:
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Library General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Library General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Library General Public
  18  * License along with this library; if not, write to the
  19  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  20  * Boston, MA 02111-1307, USA.
  21  */
  22
  23 #ifndef __GST_RING_BUFFER_H__
  24 #define __GST_RING_BUFFER_H__
  25
  26 #include <gst/gst.h>
  27
  28 G_BEGIN_DECLS
  29
  30 #define GST_TYPE_RING_BUFFER             (gst_ring_buffer_get_type())
  31 #define GST_RING_BUFFER(obj)             (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_RING_BUFFER,GstRingBuffer))
  32 #define GST_RING_BUFFER_CLASS(klass)     (G_TYPE_CHECK_CLASS_CAST((klass),GST_TYPE_RING_BUFFER,GstRingBufferClass))
  33 #define GST_RING_BUFFER_GET_CLASS(obj)    (G_TYPE_INSTANCE_GET_CLASS ((obj), GST_TYPE_RING_BUFFER, GstRingBufferClass))
  34 #define GST_IS_RING_BUFFER(obj)          (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_RING_BUFFER))
  35 #define GST_IS_RING_BUFFER_CLASS(obj)     (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_RING_BUFFER))
  36
  37 typedef struct _GstRingBuffer GstRingBuffer;
  38 typedef struct _GstRingBufferClass GstRingBufferClass;
  39 typedef struct _GstRingBufferSpec GstRingBufferSpec;
  40
  41 /* called to fill data with len bytes of samples */
  42 typedef void (*GstRingBufferCallback) (GstRingBuffer *rbuf, guint8* data, guint len, gpointer user_data);
  43
  44 /**
  45  * GstRingBufferState:
  46  * @GST_RING_BUFFER_STATE_STOPPED: The ringbuffer is stopped
  47  * @GST_RING_BUFFER_STATE_PAUSED: The ringbuffer is paused
  48  * @GST_RING_BUFFER_STATE_STARTED: The ringbuffer is started
  49  *
  50  * The state of the ringbuffer.
  51  */
  52 typedef enum {
  53   GST_RING_BUFFER_STATE_STOPPED,
  54   GST_RING_BUFFER_STATE_PAUSED,
  55   GST_RING_BUFFER_STATE_STARTED,
  56 } GstRingBufferState;
  57
  58 /**
  59  * GstRingBufferSegState:
  60  * @GST_SEGSTATE_INVALID: The content of the segment is invalid
  61  * @GST_SEGSTATE_EMPTY: The segment is empty
  62  * @GST_SEGSTATE_FILLED: The segment contains valid data
  63  * @GST_SEGSTATE_PARTIAL: The segment partially contains valid data
  64  *
  65  * The state of a segment in the ringbuffer.
  66  */
  67 typedef enum {
  68   GST_SEGSTATE_INVALID,
  69   GST_SEGSTATE_EMPTY,
  70   GST_SEGSTATE_FILLED,
  71   GST_SEGSTATE_PARTIAL,
  72 } GstRingBufferSegState;
  73
  74 /**
  75  * GstBufferFormatType:
  76  * @GST_BUFTYPE_LINEAR: samples in linear PCM
  77  * @GST_BUFTYPE_FLOAT: samples in float
  78  * @GST_BUFTYPE_MU_LAW: samples in mulaw
  79  * @GST_BUFTYPE_A_LAW: samples in alaw
  80  * @GST_BUFTYPE_IMA_ADPCM: samples in ima adpcm
  81  * @GST_BUFTYPE_MPEG: samples in mpeg audio format
  82  * @GST_BUFTYPE_GSM: samples in gsm format
  83  *
  84  * The format of the samples in the ringbuffer.
  85  */
  86 typedef enum
  87 {
  88   GST_BUFTYPE_LINEAR,
  89   GST_BUFTYPE_FLOAT,
  90   GST_BUFTYPE_MU_LAW,
  91   GST_BUFTYPE_A_LAW,
  92   GST_BUFTYPE_IMA_ADPCM,
  93   GST_BUFTYPE_MPEG,
  94   GST_BUFTYPE_GSM,
  95 } GstBufferFormatType;
  96
  97 typedef enum
  98 {
  99   GST_UNKNOWN,
 100
 101   GST_S8,
 102   GST_U8,
 103
 104   GST_S16_LE,
 105   GST_S16_BE,
 106   GST_U16_LE,
 107   GST_U16_BE,
 108
 109   GST_S24_LE,
 110   GST_S24_BE,
 111   GST_U24_LE,
 112   GST_U24_BE,
 113
 114   GST_S32_LE,
 115   GST_S32_BE,
 116   GST_U32_LE,
 117   GST_U32_BE,
 118
 119   GST_S24_3LE,
 120   GST_S24_3BE,
 121   GST_U24_3LE,
 122   GST_U24_3BE,
 123   GST_S20_3LE,
 124   GST_S20_3BE,
 125   GST_U20_3LE,
 126   GST_U20_3BE,
 127   GST_S18_3LE,
 128   GST_S18_3BE,
 129   GST_U18_3LE,
 130   GST_U18_3BE,
 131
 132   GST_FLOAT32_LE,
 133   GST_FLOAT32_BE,
 134
 135   GST_FLOAT64_LE,
 136   GST_FLOAT64_BE,
 137
 138   GST_MU_LAW,
 139   GST_A_LAW,
 140   GST_IMA_ADPCM,
 141   GST_MPEG,
 142   GST_GSM,
 143
 144   /* fill me */
 145
 146 } GstBufferFormat;
 147
 148 /**
 149  * GstRingBufferSpec:
 150  * @caps: The caps that generated the Spec.
 151  * @type: the sample type
 152  * @format: the sample format
 153  * @sign: the sample sign
 154  * @bigend: the endianness of the samples
 155  * @width: the width of the samples
 156  * @depth: th depth of the samples
 157  * @rate: the samplerate
 158  * @channels: the number of channels
 159  * @latency_time: the latency in time units
 160  * @buffer_time: the total buffer size in time units
 161  * @segsize: the size of one segment in bytes
 162  * @segtotal: the total number of segments
 163  * @bytes_per_sample: number of bytes in one sample
 164  * @silence_sample: bytes representing one sample of silence
 165  *
 166  * The structure containing the format specification of the ringbuffer.
 167  */
 168 struct _GstRingBufferSpec
 169 {
 170   /*< public >*/
 171   /* in */
 172   GstCaps  *caps;               /* the caps of the buffer */
 173
 174   /* in/out */
 175   GstBufferFormatType   type;
 176   GstBufferFormat format;
 177   gboolean  sign;
 178   gboolean  bigend;
 179   gint      width;
 180   gint      depth;
 181   gint      rate;
 182   gint      channels;
 183
 184   GstClockTime latency_time;    /* the required/actual latency time */
 185   GstClockTime buffer_time;     /* the required/actual time of the buffer */
 186   gint     segsize;             /* size of one buffer segement */
 187   gint     segtotal;            /* total number of segments */
 188
 189   /* out */
 190   gint     bytes_per_sample;    /* number of bytes of one sample */
 191   guint8   silence_sample[32];  /* bytes representing silence */
 192
 193   /*< private >*/
 194   gpointer _gst_reserved[GST_PADDING];
 195 };
 196
 197 #define GST_RING_BUFFER_GET_COND(buf) (((GstRingBuffer *)buf)->cond)
 198 #define GST_RING_BUFFER_WAIT(buf)     (g_cond_wait (GST_RING_BUFFER_GET_COND (buf), GST_OBJECT_GET_LOCK (buf)))
 199 #define GST_RING_BUFFER_SIGNAL(buf)   (g_cond_signal (GST_RING_BUFFER_GET_COND (buf)))
 200 #define GST_RING_BUFFER_BROADCAST(buf)(g_cond_broadcast (GST_RING_BUFFER_GET_COND (buf)))
 201
 202 struct _GstRingBuffer {
 203   GstObject              object;
 204
 205   /*< public >*/ /* with LOCK */
 206   GCond                 *cond;
 207   gboolean               open;
 208   gboolean               acquired;
 209   GstBuffer             *data;
 210   GstRingBufferSpec      spec;
 211   GstRingBufferSegState *segstate;
 212   gint                   samples_per_seg;     /* number of samples per segment */
 213   guint8                *empty_seg;
 214
 215   /*< public >*/ /* ATOMIC */
 216   gint                   state;         /* state of the buffer */
 217   gint                   segdone;       /* number of segments processed since last start */
 218   gint                   segbase;       /* segment corresponding to segment 0 */
 219   gint                   waiting;       /* when waiting for a segment to be freed */
 220
 221   /*< private >*/
 222   GstRingBufferCallback  callback;
 223   gpointer               cb_data;
 224
 225   /*< private >*/
 226   union {
 227     struct {
 228       gboolean           flushing;
 229     };
 230     /* adding + 0 to mark ABI change to be undone later */
 231     gpointer _gst_reserved[GST_PADDING + 0];
 232   };
 233 };
 234
 235 struct _GstRingBufferClass {
 236   GstObjectClass parent_class;
 237
 238   /*< public >*/
 239   /* just open the device, don't set any params or allocate anything */
 240   gboolean     (*open_device)  (GstRingBuffer *buf);
 241   /* allocate the resources for the ringbuffer using the given specs */
 242   gboolean     (*acquire)      (GstRingBuffer *buf, GstRingBufferSpec *spec);
 243   /* free resources of the ringbuffer */
 244   gboolean     (*release)      (GstRingBuffer *buf);
 245   /* close the device */
 246   gboolean     (*close_device) (GstRingBuffer *buf);
 247
 248   /* playback control */
 249   gboolean     (*start)        (GstRingBuffer *buf);
 250   gboolean     (*pause)        (GstRingBuffer *buf);
 251   gboolean     (*resume)       (GstRingBuffer *buf);
 252   gboolean     (*stop)         (GstRingBuffer *buf);
 253
 254   /* number of samples queued in device */
 255   guint        (*delay)        (GstRingBuffer *buf);
 256
 257   /*< private >*/
 258   gpointer _gst_reserved[GST_PADDING];
 259 };
 260
 261 GType gst_ring_buffer_get_type(void);
 262
 263 /* callback stuff */
 264 void            gst_ring_buffer_set_callback    (GstRingBuffer *buf, GstRingBufferCallback cb,
 265                                                  gpointer user_data);
 266
 267 gboolean        gst_ring_buffer_parse_caps      (GstRingBufferSpec *spec, GstCaps *caps);
 268 void            gst_ring_buffer_debug_spec_caps (GstRingBufferSpec *spec);
 269 void            gst_ring_buffer_debug_spec_buff (GstRingBufferSpec *spec);
 270
 271 /* device state */
 272 gboolean        gst_ring_buffer_open_device     (GstRingBuffer *buf);
 273 gboolean        gst_ring_buffer_close_device    (GstRingBuffer *buf);
 274
 275 gboolean        gst_ring_buffer_device_is_open  (GstRingBuffer *buf);
 276
 277 /* allocate resources */
 278 gboolean        gst_ring_buffer_acquire         (GstRingBuffer *buf, GstRingBufferSpec *spec);
 279 gboolean        gst_ring_buffer_release         (GstRingBuffer *buf);
 280
 281 gboolean        gst_ring_buffer_is_acquired     (GstRingBuffer *buf);
 282
 283 /* flushing */
 284 void            gst_ring_buffer_set_flushing    (GstRingBuffer *buf, gboolean flushing);
 285
 286 /* playback/pause */
 287 gboolean        gst_ring_buffer_start           (GstRingBuffer *buf);
 288 gboolean        gst_ring_buffer_pause           (GstRingBuffer *buf);
 289 gboolean        gst_ring_buffer_stop            (GstRingBuffer *buf);
 290
 291 /* get status */
 292 guint           gst_ring_buffer_delay           (GstRingBuffer *buf);
 293 guint64         gst_ring_buffer_samples_done    (GstRingBuffer *buf);
 294
 295 void            gst_ring_buffer_set_sample      (GstRingBuffer *buf, guint64 sample);
 296
 297 /* clear all segments */
 298 void            gst_ring_buffer_clear_all       (GstRingBuffer *buf);
 299
 300 /* commit samples */
 301 guint           gst_ring_buffer_commit          (GstRingBuffer *buf, guint64 sample,
 302                                                  guchar *data, guint len);
 303 /* read samples */
 304 guint           gst_ring_buffer_read            (GstRingBuffer *buf, guint64 sample,
 305                                                  guchar *data, guint len);
 306
 307 /* mostly protected */
 308 gboolean        gst_ring_buffer_prepare_write   (GstRingBuffer *buf, gint *segment, guint8 **writeptr, gint *len);
 309 gboolean        gst_ring_buffer_prepare_read    (GstRingBuffer *buf, gint *segment, guint8 **readptr, gint *len);
 310 void            gst_ring_buffer_clear           (GstRingBuffer *buf, gint segment);
 311 void            gst_ring_buffer_advance         (GstRingBuffer *buf, guint advance);
 312
 313 G_END_DECLS
 314
 315 #endif /* __GST_RING_BUFFER_H__ */