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_RING_BUFFER_CAST(obj)        ((GstRingBuffer *)obj)
  35 #define GST_IS_RING_BUFFER(obj)          (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_RING_BUFFER))
  36 #define GST_IS_RING_BUFFER_CLASS(klass)  (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_RING_BUFFER))
  37
  38 typedef struct _GstRingBuffer GstRingBuffer;
  39 typedef struct _GstRingBufferClass GstRingBufferClass;
  40 typedef struct _GstRingBufferSpec GstRingBufferSpec;
  41
  42 /**
  43  * GstRingBufferCallback:
  44  * @rbuf: a #GstRingBuffer
  45  * @data: target to fill
  46  * @len: amount to fill
  47  * @user_data: user data
  48  *
  49  * This function is set with gst_ring_buffer_set_callback() and is
  50  * called to fill the memory at @data with @len bytes of samples.
  51  */
  52 typedef void (*GstRingBufferCallback) (GstRingBuffer *rbuf, guint8* data, guint len, gpointer user_data);
  53
  54 /**
  55  * GstRingBufferState:
  56  * @GST_RING_BUFFER_STATE_STOPPED: The ringbuffer is stopped
  57  * @GST_RING_BUFFER_STATE_PAUSED: The ringbuffer is paused
  58  * @GST_RING_BUFFER_STATE_STARTED: The ringbuffer is started
  59  *
  60  * The state of the ringbuffer.
  61  */
  62 typedef enum {
  63   GST_RING_BUFFER_STATE_STOPPED,
  64   GST_RING_BUFFER_STATE_PAUSED,
  65   GST_RING_BUFFER_STATE_STARTED
  66 } GstRingBufferState;
  67
  68 /**
  69  * GstRingBufferSegState:
  70  * @GST_SEGSTATE_INVALID: The content of the segment is invalid
  71  * @GST_SEGSTATE_EMPTY: The segment is empty
  72  * @GST_SEGSTATE_FILLED: The segment contains valid data
  73  * @GST_SEGSTATE_PARTIAL: The segment partially contains valid data
  74  *
  75  * The state of a segment in the ringbuffer.
  76  */
  77 typedef enum {
  78   GST_SEGSTATE_INVALID,
  79   GST_SEGSTATE_EMPTY,
  80   GST_SEGSTATE_FILLED,
  81   GST_SEGSTATE_PARTIAL
  82 } GstRingBufferSegState;
  83
  84 /**
  85  * GstBufferFormatType:
  86  * @GST_BUFTYPE_LINEAR: samples in linear PCM
  87  * @GST_BUFTYPE_FLOAT: samples in float
  88  * @GST_BUFTYPE_MU_LAW: samples in mulaw
  89  * @GST_BUFTYPE_A_LAW: samples in alaw
  90  * @GST_BUFTYPE_IMA_ADPCM: samples in ima adpcm
  91  * @GST_BUFTYPE_MPEG: samples in mpeg audio format
  92  * @GST_BUFTYPE_GSM: samples in gsm format
  93  * @GST_BUFTYPE_IEC958: samples in IEC958 frames (e.g. AC3)
  94  * @GST_BUFTYPE_AC3: samples in AC3 format
  95  * @GST_BUFTYPE_EAC3: samples in EAC3 format
  96  * @GST_BUFTYPE_DTS: samples in DTS format
  97  *
  98  * The format of the samples in the ringbuffer.
  99  */
 100 typedef enum
 101 {
 102   GST_BUFTYPE_LINEAR,
 103   GST_BUFTYPE_FLOAT,
 104   GST_BUFTYPE_MU_LAW,
 105   GST_BUFTYPE_A_LAW,
 106   GST_BUFTYPE_IMA_ADPCM,
 107   GST_BUFTYPE_MPEG,
 108   GST_BUFTYPE_GSM,
 109   GST_BUFTYPE_IEC958,
 110   GST_BUFTYPE_AC3,
 111   GST_BUFTYPE_EAC3,
 112   GST_BUFTYPE_DTS
 113 } GstBufferFormatType;
 114
 115 typedef enum
 116 {
 117   GST_UNKNOWN,
 118
 119   GST_S8,
 120   GST_U8,
 121
 122   GST_S16_LE,
 123   GST_S16_BE,
 124   GST_U16_LE,
 125   GST_U16_BE,
 126
 127   GST_S24_LE,
 128   GST_S24_BE,
 129   GST_U24_LE,
 130   GST_U24_BE,
 131
 132   GST_S32_LE,
 133   GST_S32_BE,
 134   GST_U32_LE,
 135   GST_U32_BE,
 136
 137   GST_S24_3LE,
 138   GST_S24_3BE,
 139   GST_U24_3LE,
 140   GST_U24_3BE,
 141   GST_S20_3LE,
 142   GST_S20_3BE,
 143   GST_U20_3LE,
 144   GST_U20_3BE,
 145   GST_S18_3LE,
 146   GST_S18_3BE,
 147   GST_U18_3LE,
 148   GST_U18_3BE,
 149
 150   GST_FLOAT32_LE,
 151   GST_FLOAT32_BE,
 152
 153   GST_FLOAT64_LE,
 154   GST_FLOAT64_BE,
 155
 156   GST_MU_LAW,
 157   GST_A_LAW,
 158   GST_IMA_ADPCM,
 159   GST_MPEG,
 160   GST_GSM,
 161   GST_IEC958,
 162   GST_AC3,
 163   GST_EAC3,
 164   GST_DTS
 165 } GstBufferFormat;
 166
 167 /**
 168  * GstRingBufferSpec:
 169  * @caps: The caps that generated the Spec.
 170  * @type: the sample type
 171  * @format: the sample format
 172  * @sign: the sample sign
 173  * @bigend: the endianness of the samples
 174  * @width: the width of the samples
 175  * @depth: th depth of the samples
 176  * @rate: the samplerate
 177  * @channels: the number of channels
 178  * @latency_time: the latency in microseconds
 179  * @buffer_time: the total buffer size in microseconds
 180  * @segsize: the size of one segment in bytes
 181  * @segtotal: the total number of segments
 182  * @bytes_per_sample: number of bytes in one sample
 183  * @silence_sample: bytes representing one sample of silence
 184  * @seglatency: number of segments queued in the lower level device,
 185  *  defaults to segtotal
 186  *
 187  * The structure containing the format specification of the ringbuffer.
 188  */
 189 struct _GstRingBufferSpec
 190 {
 191   /*< public >*/
 192   /* in */
 193   GstCaps  *caps;               /* the caps of the buffer */
 194
 195   /* in/out */
 196   GstBufferFormatType   type;
 197   GstBufferFormat format;
 198   gboolean  sign;
 199   gboolean  bigend;
 200   gint      width;
 201   gint      depth;
 202   gint      rate;
 203   gint      channels;
 204
 205   guint64  latency_time;        /* the required/actual latency time, this is the
 206                                  * actual the size of one segment and the
 207                                  * minimum possible latency we can achieve. */
 208   guint64  buffer_time;         /* the required/actual time of the buffer, this is
 209                                  * the total size of the buffer and maximum
 210                                  * latency we can compensate for. */
 211   gint     segsize;             /* size of one buffer segment in bytes, this value
 212                                  * should be chosen to match latency_time as
 213                                  * well as possible. */
 214   gint     segtotal;            /* total number of segments, this value is the
 215                                  * number of segments of @segsize and should be
 216                                  * chosen so that it matches buffer_time as
 217                                  * close as possible. */
 218   /* out */
 219   gint     bytes_per_sample;    /* number of bytes of one sample */
 220   guint8   silence_sample[32];  /* bytes representing silence */
 221
 222   /* ABI added 0.10.20 */
 223   gint     seglatency;          /* number of segments queued in the lower
 224                                  * level device, defaults to segtotal. */
 225
 226   /*< private >*/
 227   /* gpointer _gst_reserved[GST_PADDING]; */
 228   guint8 _gst_reserved[(sizeof (gpointer) * GST_PADDING) - sizeof (gint)];
 229 };
 230
 231 #define GST_RING_BUFFER_GET_COND(buf) (((GstRingBuffer *)buf)->cond)
 232 #define GST_RING_BUFFER_WAIT(buf)     (g_cond_wait (GST_RING_BUFFER_GET_COND (buf), GST_OBJECT_GET_LOCK (buf)))
 233 #define GST_RING_BUFFER_SIGNAL(buf)   (g_cond_signal (GST_RING_BUFFER_GET_COND (buf)))
 234 #define GST_RING_BUFFER_BROADCAST(buf)(g_cond_broadcast (GST_RING_BUFFER_GET_COND (buf)))
 235
 236 /**
 237  * GstRingBuffer:
 238  * @cond: used to signal start/stop/pause/resume actions
 239  * @open: boolean indicating that the ringbuffer is open
 240  * @acquired: boolean indicating that the ringbuffer is acquired
 241  * @data: data in the ringbuffer
 242  * @spec: format and layout of the ringbuffer data
 243  * @segstate: status of each segment in the ringbuffer (unused)
 244  * @samples_per_seg: number of samples in one segment
 245  * @empty_seg: pointer to memory holding one segment of silence samples
 246  * @state: state of the buffer
 247  * @segdone: readpointer in the ringbuffer
 248  * @segbase: segment corresponding to segment 0 (unused)
 249  * @waiting: is a reader or writer waiting for a free segment
 250  *
 251  * The ringbuffer base class structure.
 252  */
 253 struct _GstRingBuffer {
 254   GstObject              object;
 255
 256   /*< public >*/ /* with LOCK */
 257   GCond                 *cond;
 258   gboolean               open;
 259   gboolean               acquired;
 260   GstBuffer             *data;
 261   GstRingBufferSpec      spec;
 262   GstRingBufferSegState *segstate;
 263   gint                   samples_per_seg;
 264   guint8                *empty_seg;
 265
 266   /*< public >*/ /* ATOMIC */
 267   gint                   state;
 268   gint                   segdone;
 269   gint                   segbase;
 270   gint                   waiting;
 271
 272   /*< private >*/
 273   GstRingBufferCallback  callback;
 274   gpointer               cb_data;
 275
 276   /*< private >*/
 277   union {
 278     struct {
 279       gboolean           flushing;
 280       /* ATOMIC */
 281       gint               may_start;
 282       gboolean           active;
 283     } ABI;
 284     /* adding + 0 to mark ABI change to be undone later */
 285     gpointer _gst_reserved[GST_PADDING + 0];
 286   } abidata;
 287 };
 288
 289 /**
 290  * GstRingBufferClass:
 291  * @parent_class: parent class
 292  * @open_device:  open the device, don't set any params or allocate anything
 293  * @acquire: allocate the resources for the ringbuffer using the given spec
 294  * @release: free resources of the ringbuffer
 295  * @close_device: close the device
 296  * @start: start processing of samples
 297  * @pause: pause processing of samples
 298  * @resume: resume processing of samples after pause
 299  * @stop: stop processing of samples
 300  * @delay: get number of samples queued in device
 301  * @activate: activate the thread that starts pulling and monitoring the
 302  * consumed segments in the device. Since 0.10.22
 303  * @commit: write samples into the ringbuffer
 304  * @clear_all: clear the entire ringbuffer Since 0.10.24
 305  *
 306  * The vmethods that subclasses can override to implement the ringbuffer.
 307  */
 308 struct _GstRingBufferClass {
 309   GstObjectClass parent_class;
 310
 311   /*< public >*/
 312   gboolean     (*open_device)  (GstRingBuffer *buf);
 313   gboolean     (*acquire)      (GstRingBuffer *buf, GstRingBufferSpec *spec);
 314   gboolean     (*release)      (GstRingBuffer *buf);
 315   gboolean     (*close_device) (GstRingBuffer *buf);
 316
 317   gboolean     (*start)        (GstRingBuffer *buf);
 318   gboolean     (*pause)        (GstRingBuffer *buf);
 319   gboolean     (*resume)       (GstRingBuffer *buf);
 320   gboolean     (*stop)         (GstRingBuffer *buf);
 321
 322   guint        (*delay)        (GstRingBuffer *buf);
 323
 324   /* ABI added */
 325   gboolean     (*activate)     (GstRingBuffer *buf, gboolean active);
 326
 327   guint        (*commit)       (GstRingBuffer * buf, guint64 *sample,
 328                                 guchar * data, gint in_samples,
 329                                 gint out_samples, gint * accum);
 330
 331   void         (*clear_all)    (GstRingBuffer * buf);
 332
 333   /*< private >*/
 334   gpointer _gst_reserved[GST_PADDING - 3];
 335 };
 336
 337 GType gst_ring_buffer_get_type(void);
 338
 339 /* callback stuff */
 340 void            gst_ring_buffer_set_callback    (GstRingBuffer *buf, GstRingBufferCallback cb,
 341                                                  gpointer user_data);
 342
 343 gboolean        gst_ring_buffer_parse_caps      (GstRingBufferSpec *spec, GstCaps *caps);
 344 void            gst_ring_buffer_debug_spec_caps (GstRingBufferSpec *spec);
 345 void            gst_ring_buffer_debug_spec_buff (GstRingBufferSpec *spec);
 346
 347 gboolean        gst_ring_buffer_convert         (GstRingBuffer * buf, GstFormat src_fmt,
 348                                                  gint64 src_val, GstFormat dest_fmt,
 349                                                  gint64 * dest_val);
 350
 351 /* device state */
 352 gboolean        gst_ring_buffer_open_device     (GstRingBuffer *buf);
 353 gboolean        gst_ring_buffer_close_device    (GstRingBuffer *buf);
 354
 355 gboolean        gst_ring_buffer_device_is_open  (GstRingBuffer *buf);
 356
 357 /* allocate resources */
 358 gboolean        gst_ring_buffer_acquire         (GstRingBuffer *buf, GstRingBufferSpec *spec);
 359 gboolean        gst_ring_buffer_release         (GstRingBuffer *buf);
 360
 361 gboolean        gst_ring_buffer_is_acquired     (GstRingBuffer *buf);
 362
 363 /* activating */
 364 gboolean        gst_ring_buffer_activate        (GstRingBuffer *buf, gboolean active);
 365 gboolean        gst_ring_buffer_is_active       (GstRingBuffer *buf);
 366
 367 /* flushing */
 368 void            gst_ring_buffer_set_flushing    (GstRingBuffer *buf, gboolean flushing);
 369
 370 /* playback/pause */
 371 gboolean        gst_ring_buffer_start           (GstRingBuffer *buf);
 372 gboolean        gst_ring_buffer_pause           (GstRingBuffer *buf);
 373 gboolean        gst_ring_buffer_stop            (GstRingBuffer *buf);
 374
 375 /* get status */
 376 guint           gst_ring_buffer_delay           (GstRingBuffer *buf);
 377 guint64         gst_ring_buffer_samples_done    (GstRingBuffer *buf);
 378
 379 void            gst_ring_buffer_set_sample      (GstRingBuffer *buf, guint64 sample);
 380
 381 /* clear all segments */
 382 void            gst_ring_buffer_clear_all       (GstRingBuffer *buf);
 383
 384 /* commit samples */
 385 guint           gst_ring_buffer_commit          (GstRingBuffer *buf, guint64 sample,
 386                                                  guchar *data, guint len);
 387 guint           gst_ring_buffer_commit_full     (GstRingBuffer * buf, guint64 *sample,
 388                                                  guchar * data, gint in_samples,
 389                                                  gint out_samples, gint * accum);
 390
 391 /* read samples */
 392 guint           gst_ring_buffer_read            (GstRingBuffer *buf, guint64 sample,
 393                                                  guchar *data, guint len);
 394
 395 /* mostly protected */
 396 /* not yet implemented
 397 gboolean        gst_ring_buffer_prepare_write   (GstRingBuffer *buf, gint *segment, guint8 **writeptr, gint *len);
 398 */
 399 gboolean        gst_ring_buffer_prepare_read    (GstRingBuffer *buf, gint *segment, guint8 **readptr, gint *len);
 400 void            gst_ring_buffer_clear           (GstRingBuffer *buf, gint segment);
 401 void            gst_ring_buffer_advance         (GstRingBuffer *buf, guint advance);
 402
 403 void            gst_ring_buffer_may_start       (GstRingBuffer *buf, gboolean allowed);
 404
 405
 406 G_END_DECLS
 407
 408 #endif /* __GST_RING_BUFFER_H__ */