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 (but not AAC) 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  * @GST_BUFTYPE_MPEG2_AAC: samples in MPEG-2 AAC format
  98  * @GST_BUFTYPE_MPEG4_AAC: samples in MPEG-4 AAC format
  99  *
 100  * The format of the samples in the ringbuffer.
 101  */
 102 typedef enum
 103 {
 104   GST_BUFTYPE_LINEAR,
 105   GST_BUFTYPE_FLOAT,
 106   GST_BUFTYPE_MU_LAW,
 107   GST_BUFTYPE_A_LAW,
 108   GST_BUFTYPE_IMA_ADPCM,
 109   GST_BUFTYPE_MPEG,
 110   GST_BUFTYPE_GSM,
 111   GST_BUFTYPE_IEC958,
 112   GST_BUFTYPE_AC3,
 113   GST_BUFTYPE_EAC3,
 114   GST_BUFTYPE_DTS,
 115   GST_BUFTYPE_MPEG2_AAC,
 116   GST_BUFTYPE_MPEG4_AAC,
 117 } GstBufferFormatType;
 118
 119 /**
 120  * GstBufferFormat:
 121  * @GST_UNKNOWN: unspecified
 122  * @GST_S8: integer signed 8 bit
 123  * @GST_U8: integer unsigned 8 bit
 124  * @GST_S16_LE: integer signed 16 bit little endian
 125  * @GST_S16_BE: integer signed 16 bit big endian
 126  * @GST_U16_LE: integer unsigned 16 bit little endian
 127  * @GST_U16_BE: integer unsigned 16 bit big endian
 128  * @GST_S24_LE: integer signed 24 bit little endian
 129  * @GST_S24_BE: integer signed 24 bit big endian
 130  * @GST_U24_LE: integer unsigned 24 bit little endian
 131  * @GST_U24_BE: integer unsigned 24 bit big endian
 132  * @GST_S32_LE: integer signed 32 bit little endian
 133  * @GST_S32_BE: integer signed 32 bit big endian
 134  * @GST_U32_LE: integer unsigned 32 bit little endian
 135  * @GST_U32_BE: integer unsigned 32 bit big endian
 136  * @GST_S24_3LE: integer signed 24 bit little endian packed in 3 bytes
 137  * @GST_S24_3BE: integer signed 24 bit big endian packed in 3 bytes
 138  * @GST_U24_3LE: integer unsigned 24 bit little endian packed in 3 bytes
 139  * @GST_U24_3BE: integer unsigned 24 bit big endian packed in 3 bytes
 140  * @GST_S20_3LE: integer signed 20 bit little endian packed in 3 bytes
 141  * @GST_S20_3BE: integer signed 20 bit big endian packed in 3 bytes
 142  * @GST_U20_3LE: integer unsigned 20 bit little endian packed in 3 bytes
 143  * @GST_U20_3BE: integer unsigned 20 bit big endian packed in 3 bytes
 144  * @GST_S18_3LE: integer signed 18 bit little endian packed in 3 bytes
 145  * @GST_S18_3BE: integer signed 18 bit big endian packed in 3 bytes
 146  * @GST_U18_3LE: integer unsigned 18 bit little endian packed in 3 bytes
 147  * @GST_U18_3BE: integer unsigned 18 bit big endian packed in 3 bytes
 148  * @GST_FLOAT32_LE: floating 32 bit little endian
 149  * @GST_FLOAT32_BE: floating 32 bit big endian
 150  * @GST_FLOAT64_LE: floating 64 bit little endian
 151  * @GST_FLOAT64_BE: floating 64 bit big endian
 152  * @GST_MU_LAW: mu-law
 153  * @GST_A_LAW: a-law
 154  * @GST_IMA_ADPCM: ima adpcm
 155  * @GST_MPEG: mpeg audio (but not aac)
 156  * @GST_GSM: gsm
 157  * @GST_IEC958: IEC958 frames
 158  * @GST_AC3: ac3
 159  * @GST_EAC3: eac3
 160  * @GST_DTS: dts
 161  * @GST_MPEG2_AAC: mpeg-2 aac
 162  * @GST_MPEG4_AAC: mpeg-4 aac
 163  *
 164  * The detailed format of the samples in the ringbuffer.
 165  */
 166 typedef enum
 167 {
 168   GST_UNKNOWN,
 169
 170   GST_S8,
 171   GST_U8,
 172
 173   GST_S16_LE,
 174   GST_S16_BE,
 175   GST_U16_LE,
 176   GST_U16_BE,
 177
 178   GST_S24_LE,
 179   GST_S24_BE,
 180   GST_U24_LE,
 181   GST_U24_BE,
 182
 183   GST_S32_LE,
 184   GST_S32_BE,
 185   GST_U32_LE,
 186   GST_U32_BE,
 187
 188   GST_S24_3LE,
 189   GST_S24_3BE,
 190   GST_U24_3LE,
 191   GST_U24_3BE,
 192   GST_S20_3LE,
 193   GST_S20_3BE,
 194   GST_U20_3LE,
 195   GST_U20_3BE,
 196   GST_S18_3LE,
 197   GST_S18_3BE,
 198   GST_U18_3LE,
 199   GST_U18_3BE,
 200
 201   GST_FLOAT32_LE,
 202   GST_FLOAT32_BE,
 203
 204   GST_FLOAT64_LE,
 205   GST_FLOAT64_BE,
 206
 207   GST_MU_LAW,
 208   GST_A_LAW,
 209   GST_IMA_ADPCM,
 210   GST_MPEG,
 211   GST_GSM,
 212   GST_IEC958,
 213   GST_AC3,
 214   GST_EAC3,
 215   GST_DTS,
 216   GST_MPEG2_AAC,
 217   GST_MPEG4_AAC,
 218 } GstBufferFormat;
 219
 220 /**
 221  * GstRingBufferSpec:
 222  * @caps: The caps that generated the Spec.
 223  * @type: the sample type
 224  * @format: the sample format
 225  * @sign: the sample sign
 226  * @bigend: the endianness of the samples
 227  * @width: the width of the samples
 228  * @depth: th depth of the samples
 229  * @rate: the samplerate
 230  * @channels: the number of channels
 231  * @latency_time: the latency in microseconds
 232  * @buffer_time: the total buffer size in microseconds
 233  * @segsize: the size of one segment in bytes
 234  * @segtotal: the total number of segments
 235  * @bytes_per_sample: number of bytes in one sample
 236  * @silence_sample: bytes representing one sample of silence
 237  * @seglatency: number of segments queued in the lower level device,
 238  *  defaults to segtotal
 239  *
 240  * The structure containing the format specification of the ringbuffer.
 241  */
 242 struct _GstRingBufferSpec
 243 {
 244   /*< public >*/
 245   /* in */
 246   GstCaps  *caps;               /* the caps of the buffer */
 247
 248   /* in/out */
 249   GstBufferFormatType   type;
 250   GstBufferFormat format;
 251   gboolean  sign;
 252   gboolean  bigend;
 253   gint      width;
 254   gint      depth;
 255   gint      rate;
 256   gint      channels;
 257
 258   guint64  latency_time;        /* the required/actual latency time, this is the
 259                                  * actual the size of one segment and the
 260                                  * minimum possible latency we can achieve. */
 261   guint64  buffer_time;         /* the required/actual time of the buffer, this is
 262                                  * the total size of the buffer and maximum
 263                                  * latency we can compensate for. */
 264   gint     segsize;             /* size of one buffer segment in bytes, this value
 265                                  * should be chosen to match latency_time as
 266                                  * well as possible. */
 267   gint     segtotal;            /* total number of segments, this value is the
 268                                  * number of segments of @segsize and should be
 269                                  * chosen so that it matches buffer_time as
 270                                  * close as possible. */
 271   /* out */
 272   gint     bytes_per_sample;    /* number of bytes of one sample */
 273   guint8   silence_sample[32];  /* bytes representing silence */
 274
 275   /* ABI added 0.10.20 */
 276   gint     seglatency;          /* number of segments queued in the lower
 277                                  * level device, defaults to segtotal. */
 278
 279   /*< private >*/
 280   /* gpointer _gst_reserved[GST_PADDING]; */
 281   guint8 _gst_reserved[(sizeof (gpointer) * GST_PADDING) - sizeof (gint)];
 282 };
 283
 284 #define GST_RING_BUFFER_GET_COND(buf) (((GstRingBuffer *)buf)->cond)
 285 #define GST_RING_BUFFER_WAIT(buf)     (g_cond_wait (GST_RING_BUFFER_GET_COND (buf), GST_OBJECT_GET_LOCK (buf)))
 286 #define GST_RING_BUFFER_SIGNAL(buf)   (g_cond_signal (GST_RING_BUFFER_GET_COND (buf)))
 287 #define GST_RING_BUFFER_BROADCAST(buf)(g_cond_broadcast (GST_RING_BUFFER_GET_COND (buf)))
 288
 289 /**
 290  * GstRingBuffer:
 291  * @cond: used to signal start/stop/pause/resume actions
 292  * @open: boolean indicating that the ringbuffer is open
 293  * @acquired: boolean indicating that the ringbuffer is acquired
 294  * @data: data in the ringbuffer
 295  * @spec: format and layout of the ringbuffer data
 296  * @segstate: status of each segment in the ringbuffer (unused)
 297  * @samples_per_seg: number of samples in one segment
 298  * @empty_seg: pointer to memory holding one segment of silence samples
 299  * @state: state of the buffer
 300  * @segdone: readpointer in the ringbuffer
 301  * @segbase: segment corresponding to segment 0 (unused)
 302  * @waiting: is a reader or writer waiting for a free segment
 303  *
 304  * The ringbuffer base class structure.
 305  */
 306 struct _GstRingBuffer {
 307   GstObject              object;
 308
 309   /*< public >*/ /* with LOCK */
 310   GCond                 *cond;
 311   gboolean               open;
 312   gboolean               acquired;
 313   GstBuffer             *data;
 314   GstRingBufferSpec      spec;
 315   GstRingBufferSegState *segstate;
 316   gint                   samples_per_seg;
 317   guint8                *empty_seg;
 318
 319   /*< public >*/ /* ATOMIC */
 320   gint                   state;
 321   gint                   segdone;
 322   gint                   segbase;
 323   gint                   waiting;
 324
 325   /*< private >*/
 326   GstRingBufferCallback  callback;
 327   gpointer               cb_data;
 328
 329   /*< private >*/
 330   union {
 331     struct {
 332       gboolean           flushing;
 333       /* ATOMIC */
 334       gint               may_start;
 335       gboolean           active;
 336     } ABI;
 337     /* adding + 0 to mark ABI change to be undone later */
 338     gpointer _gst_reserved[GST_PADDING + 0];
 339   } abidata;
 340 };
 341
 342 /**
 343  * GstRingBufferClass:
 344  * @parent_class: parent class
 345  * @open_device:  open the device, don't set any params or allocate anything
 346  * @acquire: allocate the resources for the ringbuffer using the given spec
 347  * @release: free resources of the ringbuffer
 348  * @close_device: close the device
 349  * @start: start processing of samples
 350  * @pause: pause processing of samples
 351  * @resume: resume processing of samples after pause
 352  * @stop: stop processing of samples
 353  * @delay: get number of samples queued in device
 354  * @activate: activate the thread that starts pulling and monitoring the
 355  * consumed segments in the device. Since 0.10.22
 356  * @commit: write samples into the ringbuffer
 357  * @clear_all: clear the entire ringbuffer Since 0.10.24
 358  *
 359  * The vmethods that subclasses can override to implement the ringbuffer.
 360  */
 361 struct _GstRingBufferClass {
 362   GstObjectClass parent_class;
 363
 364   /*< public >*/
 365   gboolean     (*open_device)  (GstRingBuffer *buf);
 366   gboolean     (*acquire)      (GstRingBuffer *buf, GstRingBufferSpec *spec);
 367   gboolean     (*release)      (GstRingBuffer *buf);
 368   gboolean     (*close_device) (GstRingBuffer *buf);
 369
 370   gboolean     (*start)        (GstRingBuffer *buf);
 371   gboolean     (*pause)        (GstRingBuffer *buf);
 372   gboolean     (*resume)       (GstRingBuffer *buf);
 373   gboolean     (*stop)         (GstRingBuffer *buf);
 374
 375   guint        (*delay)        (GstRingBuffer *buf);
 376
 377   /* ABI added */
 378   gboolean     (*activate)     (GstRingBuffer *buf, gboolean active);
 379
 380   guint        (*commit)       (GstRingBuffer * buf, guint64 *sample,
 381                                 guchar * data, gint in_samples,
 382                                 gint out_samples, gint * accum);
 383
 384   void         (*clear_all)    (GstRingBuffer * buf);
 385
 386   /*< private >*/
 387   gpointer _gst_reserved[GST_PADDING - 3];
 388 };
 389
 390 GType gst_ring_buffer_get_type(void);
 391
 392 /* callback stuff */
 393 void            gst_ring_buffer_set_callback    (GstRingBuffer *buf, GstRingBufferCallback cb,
 394                                                  gpointer user_data);
 395
 396 gboolean        gst_ring_buffer_parse_caps      (GstRingBufferSpec *spec, GstCaps *caps);
 397 void            gst_ring_buffer_debug_spec_caps (GstRingBufferSpec *spec);
 398 void            gst_ring_buffer_debug_spec_buff (GstRingBufferSpec *spec);
 399
 400 gboolean        gst_ring_buffer_convert         (GstRingBuffer * buf, GstFormat src_fmt,
 401                                                  gint64 src_val, GstFormat dest_fmt,
 402                                                  gint64 * dest_val);
 403
 404 /* device state */
 405 gboolean        gst_ring_buffer_open_device     (GstRingBuffer *buf);
 406 gboolean        gst_ring_buffer_close_device    (GstRingBuffer *buf);
 407
 408 gboolean        gst_ring_buffer_device_is_open  (GstRingBuffer *buf);
 409
 410 /* allocate resources */
 411 gboolean        gst_ring_buffer_acquire         (GstRingBuffer *buf, GstRingBufferSpec *spec);
 412 gboolean        gst_ring_buffer_release         (GstRingBuffer *buf);
 413
 414 gboolean        gst_ring_buffer_is_acquired     (GstRingBuffer *buf);
 415
 416 /* activating */
 417 gboolean        gst_ring_buffer_activate        (GstRingBuffer *buf, gboolean active);
 418 gboolean        gst_ring_buffer_is_active       (GstRingBuffer *buf);
 419
 420 /* flushing */
 421 void            gst_ring_buffer_set_flushing    (GstRingBuffer *buf, gboolean flushing);
 422
 423 /* playback/pause */
 424 gboolean        gst_ring_buffer_start           (GstRingBuffer *buf);
 425 gboolean        gst_ring_buffer_pause           (GstRingBuffer *buf);
 426 gboolean        gst_ring_buffer_stop            (GstRingBuffer *buf);
 427
 428 /* get status */
 429 guint           gst_ring_buffer_delay           (GstRingBuffer *buf);
 430 guint64         gst_ring_buffer_samples_done    (GstRingBuffer *buf);
 431
 432 void            gst_ring_buffer_set_sample      (GstRingBuffer *buf, guint64 sample);
 433
 434 /* clear all segments */
 435 void            gst_ring_buffer_clear_all       (GstRingBuffer *buf);
 436
 437 /* commit samples */
 438 guint           gst_ring_buffer_commit          (GstRingBuffer *buf, guint64 sample,
 439                                                  guchar *data, guint len);
 440 guint           gst_ring_buffer_commit_full     (GstRingBuffer * buf, guint64 *sample,
 441                                                  guchar * data, gint in_samples,
 442                                                  gint out_samples, gint * accum);
 443
 444 /* read samples */
 445 guint           gst_ring_buffer_read            (GstRingBuffer *buf, guint64 sample,
 446                                                  guchar *data, guint len);
 447
 448 /* mostly protected */
 449 /* not yet implemented
 450 gboolean        gst_ring_buffer_prepare_write   (GstRingBuffer *buf, gint *segment, guint8 **writeptr, gint *len);
 451 */
 452 gboolean        gst_ring_buffer_prepare_read    (GstRingBuffer *buf, gint *segment, guint8 **readptr, gint *len);
 453 void            gst_ring_buffer_clear           (GstRingBuffer *buf, gint segment);
 454 void            gst_ring_buffer_advance         (GstRingBuffer *buf, guint advance);
 455
 456 void            gst_ring_buffer_may_start       (GstRingBuffer *buf, gboolean allowed);
 457
 458
 459 G_END_DECLS
 460
 461 #endif /* __GST_RING_BUFFER_H__ */