libs/gst/base/gstcollectpads2.h

   1 /* GStreamer
   2  * Copyright (C) 2005 Wim Taymans <wim@fluendo.com>
   3  * Copyright (C) 2008 Mark Nauwelaerts <mnauw@users.sourceforge.net>
   4  *
   5  * gstcollectpads2.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_COLLECT_PADS2_H__
  24 #define __GST_COLLECT_PADS2_H__
  25
  26 #include <gst/gst.h>
  27
  28 G_BEGIN_DECLS
  29
  30 #define GST_TYPE_COLLECT_PADS2            (gst_collect_pads2_get_type())
  31 #define GST_COLLECT_PADS2(obj)            (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_COLLECT_PADS2,GstCollectPads2))
  32 #define GST_COLLECT_PADS2_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST((klass),GST_TYPE_COLLECT_PADS2,GstCollectPads2Class))
  33 #define GST_COLLECT_PADS2_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS ((obj),GST_TYPE_COLLECT_PADS2,GstCollectPads2Class))
  34 #define GST_IS_COLLECT_PADS2(obj)         (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_COLLECT_PADS2))
  35 #define GST_IS_COLLECT_PADS2_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_COLLECT_PADS2))
  36
  37 typedef struct _GstCollectData2 GstCollectData2;
  38 typedef struct _GstCollectData2Private GstCollectData2Private;
  39 typedef struct _GstCollectPads2 GstCollectPads2;
  40 typedef struct _GstCollectPads2Private GstCollectPads2Private;
  41 typedef struct _GstCollectPads2Class GstCollectPads2Class;
  42
  43 /**
  44  * GstCollectData2DestroyNotify:
  45  * @data: the #GstCollectData2 that will be freed
  46  *
  47  * A function that will be called when the #GstCollectData2 will be freed.
  48  * It is passed the pointer to the structure and should free any custom
  49  * memory and resources allocated for it.
  50  *
  51  * Since: 0.10.36
  52  */
  53 typedef void (*GstCollectData2DestroyNotify) (GstCollectData2 *data);
  54
  55 /**
  56  * GstCollectPads2StateFlags:
  57  * @GST_COLLECT_PADS2_STATE_EOS:         Set if collectdata's pad is EOS.
  58  * @GST_COLLECT_PADS2_STATE_FLUSHING:    Set if collectdata's pad is flushing.
  59  * @GST_COLLECT_PADS2_STATE_NEW_SEGMENT: Set if collectdata's pad received a
  60  *                                      new_segment event.
  61  * @GST_COLLECT_PADS2_STATE_WAITING:     Set if collectdata's pad must be waited
  62  *                                      for when collecting.
  63  * @GST_COLLECT_PADS2_STATE_LOCKED:      Set collectdata's pad WAITING state must
  64  *                                      not be changed.
  65  * #GstCollectPads2StateFlags indicate private state of a collectdata('s pad).
  66  *
  67  * Since: 0.10.36
  68  */
  69 typedef enum {
  70   GST_COLLECT_PADS2_STATE_EOS = 1 << 0,
  71   GST_COLLECT_PADS2_STATE_FLUSHING = 1 << 1,
  72   GST_COLLECT_PADS2_STATE_NEW_SEGMENT = 1 << 2,
  73   GST_COLLECT_PADS2_STATE_WAITING = 1 << 3,
  74   GST_COLLECT_PADS2_STATE_LOCKED = 1 << 4
  75 } GstCollectPads2StateFlags;
  76
  77 /**
  78  * GST_COLLECT_PADS2_STATE:
  79  * @data: a #GstCollectData2.
  80  *
  81  * A flags word containing #GstCollectPads2StateFlags flags set
  82  * on this collected pad.
  83  *
  84  * Since: 0.10.36
  85  */
  86 #define GST_COLLECT_PADS2_STATE(data)                 (((GstCollectData2 *) data)->state)
  87 /**
  88  * GST_COLLECT_PADS2_STATE_IS_SET:
  89  * @data: a #GstCollectData2.
  90  * @flag: the #GstCollectPads2StateFlags to check.
  91  *
  92  * Gives the status of a specific flag on a collected pad.
  93  *
  94  * Since: 0.10.36
  95  */
  96 #define GST_COLLECT_PADS2_STATE_IS_SET(data,flag)     !!(GST_COLLECT_PADS2_STATE (data) & flag)
  97 /**
  98  * GST_COLLECT_PADS2_STATE_SET:
  99  * @data: a #GstCollectData2.
 100  * @flag: the #GstCollectPads2StateFlags to set.
 101  *
 102  * Sets a state flag on a collected pad.
 103  *
 104  * Since: 0.10.36
 105  */
 106 #define GST_COLLECT_PADS2_STATE_SET(data,flag)        (GST_COLLECT_PADS2_STATE (data) |= flag)
 107 /**
 108  * GST_COLLECT_PADS2_STATE_UNSET:
 109  * @data: a #GstCollectData2.
 110  * @flag: the #GstCollectPads2StateFlags to clear.
 111  *
 112  * Clears a state flag on a collected pad.
 113  *
 114  * Since: 0.10.36
 115  */
 116 #define GST_COLLECT_PADS2_STATE_UNSET(data,flag)      (GST_COLLECT_PADS2_STATE (data) &= ~(flag))
 117
 118 /**
 119  * GstCollectData2:
 120  * @collect: owner #GstCollectPads2
 121  * @pad: #GstPad managed by this data
 122  * @buffer: currently queued buffer.
 123  * @pos: position in the buffer
 124  * @segment: last segment received.
 125  *
 126  * Structure used by the collect_pads2.
 127  *
 128  * Since: 0.10.36
 129  */
 130 struct _GstCollectData2
 131 {
 132   /* with STREAM_LOCK of @collect */
 133   GstCollectPads2       *collect;
 134   GstPad                *pad;
 135   GstBuffer             *buffer;
 136   guint                  pos;
 137   GstSegment             segment;
 138
 139   /*< private >*/
 140   /* state: bitfield for easier extension;
 141    * eos, flushing, new_segment, waiting */
 142   GstCollectPads2StateFlags    state;
 143
 144   GstCollectData2Private *priv;
 145
 146   gpointer _gst_reserved[GST_PADDING];
 147 };
 148
 149 /**
 150  * GstCollectPads2Function:
 151  * @pads: the #GstCollectPads2 that trigered the callback
 152  * @user_data: user data passed to gst_collect_pads2_set_function()
 153  *
 154  * A function that will be called when all pads have received data.
 155  *
 156  * Returns: #GST_FLOW_OK for success
 157  *
 158  * Since: 0.10.36
 159  */
 160 typedef GstFlowReturn (*GstCollectPads2Function) (GstCollectPads2 *pads, gpointer user_data);
 161
 162 /**
 163  * GstCollectPads2BufferFunction:
 164  * @pads: the #GstCollectPads2 that trigered the callback
 165  * @data: the #GstCollectData2 of pad that has received the buffer
 166  * @buffer: the #GstBuffer
 167  * @user_data: user data passed to gst_collect_pads2_set_buffer_function()
 168  *
 169  * A function that will be called when a (considered oldest) buffer can be muxed.
 170  * If all pads have reached EOS, this function is called with NULL @buffer
 171  * and NULL @data.
 172  *
 173  * Returns: #GST_FLOW_OK for success
 174  *
 175  * Since: 0.10.36
 176  */
 177 typedef GstFlowReturn (*GstCollectPads2BufferFunction) (GstCollectPads2 *pads, GstCollectData2 *data,
 178                                                         GstBuffer *buffer, gpointer user_data);
 179
 180 /**
 181  * GstCollectPads2CompareFunction:
 182  * @pads: the #GstCollectPads that is comparing the timestamps
 183  * @data1: the first #GstCollectData2
 184  * @timestamp1: the first timestamp
 185  * @data2: the second #GstCollectData2
 186  * @timestamp2: the second timestamp
 187  * @user_data: user data passed to gst_collect_pads2_set_compare_function()
 188  *
 189  * A function for comparing two timestamps of buffers or newsegments collected on one pad.
 190  *
 191  * Returns: Integer less than zero when first timestamp is deemed older than the second one.
 192  *          Zero if the timestamps are deemed equally old.
 193  *          Integer greate than zero when second timestamp is deemed older than the first one.
 194  *
 195  * Since: 0.10.36
 196  */
 197 typedef gint (*GstCollectPads2CompareFunction) (GstCollectPads2 *pads,
 198                                                 GstCollectData2 * data1, GstClockTime timestamp1,
 199                                                 GstCollectData2 * data2, GstClockTime timestamp2,
 200                                                 gpointer user_data);
 201
 202 /**
 203  * GstCollectPads2EventFunction:
 204  * @pads: the #GstCollectPads2 that trigered the callback
 205  * @pad: the #GstPad that received an event
 206  * @event: the #GstEvent received
 207  * @user_data: user data passed to gst_collect_pads2_set_event_function()
 208  *
 209  * A function that will be called while processing an event. It takes
 210  * ownership of the event and is responsible for chaining up (to
 211  * gst_collect_pads2_event_default()) or dropping events (such typical cases
 212  * being handled by the default handler).
 213  *
 214  * Returns: %TRUE if the pad could handle the event
 215  *
 216  * Since: 0.10.36
 217  */
 218 typedef gboolean (*GstCollectPads2EventFunction)        (GstCollectPads2 *pads, GstCollectData2 * pad,
 219                                                          GstEvent * event, gpointer user_data);
 220
 221
 222 /**
 223  * GstCollectPads2QueryFunction:
 224  * @pads: the #GstCollectPads2 that trigered the callback
 225  * @pad: the #GstPad that received an event
 226  * @query: the #GstEvent received
 227  * @user_data: user data passed to gst_collect_pads2_set_query_function()
 228  *
 229  * A function that will be called while processing a query. It takes
 230  * ownership of the query and is responsible for chaining up (to
 231  * events downstream (with gst_pad_event_default()).
 232  *
 233  * Returns: %TRUE if the pad could handle the event
 234  *
 235  * Since: 0.11.x
 236  */
 237 typedef gboolean (*GstCollectPads2QueryFunction)        (GstCollectPads2 *pads, GstCollectData2 * pad,
 238                                                          GstQuery * query, gpointer user_data);
 239
 240 /**
 241  * GstCollectPads2ClipFunction:
 242  * @pads: a #GstCollectPads2
 243  * @data: a #GstCollectData2
 244  * @inbuffer: the input #GstBuffer
 245  * @outbuffer: the output #GstBuffer
 246  * @user_data: user data
 247  *
 248  * A function that will be called when @inbuffer is received on the pad managed
 249  * by @data in the collecpad object @pads.
 250  *
 251  * The function should use the segment of @data and the negotiated media type on
 252  * the pad to perform clipping of @inbuffer.
 253  *
 254  * This function takes ownership of @inbuffer and should output a buffer in
 255  * @outbuffer or return %NULL in @outbuffer if the buffer should be dropped.
 256  *
 257  * Returns: a #GstFlowReturn that corresponds to the result of clipping.
 258  *
 259  * Since: 0.10.36
 260  */
 261 typedef GstFlowReturn (*GstCollectPads2ClipFunction) (GstCollectPads2 *pads, GstCollectData2 *data,
 262                                                    GstBuffer *inbuffer, GstBuffer **outbuffer,
 263                                                    gpointer user_data);
 264
 265 /**
 266  * GST_COLLECT_PADS2_GET_STREAM_LOCK:
 267  * @pads: a #GstCollectPads2
 268  *
 269  * Get the stream lock of @pads. The stream lock is used to coordinate and
 270  * serialize execution among the various streams being collected, and in
 271  * protecting the resources used to accomplish this.
 272  *
 273  * Since: 0.10.36
 274  */
 275 #define GST_COLLECT_PADS2_GET_STREAM_LOCK(pads) (&((GstCollectPads2 *)pads)->stream_lock)
 276 /**
 277  * GST_COLLECT_PADS2_STREAM_LOCK:
 278  * @pads: a #GstCollectPads2
 279  *
 280  * Lock the stream lock of @pads.
 281  *
 282  * Since: 0.10.36
 283  */
 284 #define GST_COLLECT_PADS2_STREAM_LOCK(pads)     g_rec_mutex_lock(GST_COLLECT_PADS2_GET_STREAM_LOCK (pads))
 285 /**
 286  * GST_COLLECT_PADS2_STREAM_UNLOCK:
 287  * @pads: a #GstCollectPads2
 288  *
 289  * Unlock the stream lock of @pads.
 290  *
 291  * Since: 0.10.36
 292  */
 293 #define GST_COLLECT_PADS2_STREAM_UNLOCK(pads)   g_rec_mutex_unlock(GST_COLLECT_PADS2_GET_STREAM_LOCK (pads))
 294
 295 /**
 296  * GstCollectPads2:
 297  * @data: #GList of #GstCollectData2 managed by this #GstCollectPads2.
 298  *
 299  * Collectpads object.
 300  *
 301  * Since: 0.10.36
 302  */
 303 struct _GstCollectPads2 {
 304   GstObject      object;
 305
 306   /*< public >*/ /* with LOCK and/or STREAM_LOCK */
 307   GSList        *data;                  /* list of CollectData items */
 308
 309   /*< private >*/
 310   GRecMutex      stream_lock;          /* used to serialize collection among several streams */
 311
 312   GstCollectPads2Private *priv;
 313
 314   gpointer _gst_reserved[GST_PADDING];
 315 };
 316
 317 struct _GstCollectPads2Class {
 318   GstObjectClass parent_class;
 319
 320   /*< private >*/
 321   gpointer _gst_reserved[GST_PADDING];
 322 };
 323
 324 GType gst_collect_pads2_get_type(void);
 325
 326 /* creating the object */
 327 GstCollectPads2*        gst_collect_pads2_new           (void);
 328
 329 /* set the callbacks */
 330 void            gst_collect_pads2_set_function         (GstCollectPads2 *pads,
 331                                                         GstCollectPads2Function func,
 332                                                         gpointer user_data);
 333 void            gst_collect_pads2_set_buffer_function  (GstCollectPads2 *pads,
 334                                                         GstCollectPads2BufferFunction func,
 335                                                         gpointer user_data);
 336 void            gst_collect_pads2_set_event_function   (GstCollectPads2 *pads,
 337                                                         GstCollectPads2EventFunction func,
 338                                                         gpointer user_data);
 339 void            gst_collect_pads2_set_query_function   (GstCollectPads2 *pads,
 340                                                         GstCollectPads2QueryFunction func,
 341                                                         gpointer user_data);
 342 void            gst_collect_pads2_set_compare_function (GstCollectPads2 *pads,
 343                                                         GstCollectPads2CompareFunction func,
 344                                                         gpointer user_data);
 345 void            gst_collect_pads2_set_clip_function    (GstCollectPads2 *pads,
 346                                                         GstCollectPads2ClipFunction clipfunc,
 347                                                         gpointer user_data);
 348
 349 /* pad management */
 350 GstCollectData2* gst_collect_pads2_add_pad      (GstCollectPads2 *pads, GstPad *pad, guint size);
 351 GstCollectData2* gst_collect_pads2_add_pad_full (GstCollectPads2 *pads, GstPad *pad, guint size,
 352                                                  GstCollectData2DestroyNotify destroy_notify,
 353                                                  gboolean lock);
 354 gboolean        gst_collect_pads2_remove_pad    (GstCollectPads2 *pads, GstPad *pad);
 355 gboolean        gst_collect_pads2_is_active     (GstCollectPads2 *pads, GstPad *pad);
 356
 357 /* start/stop collection */
 358 GstFlowReturn   gst_collect_pads2_collect       (GstCollectPads2 *pads);
 359 GstFlowReturn   gst_collect_pads2_collect_range (GstCollectPads2 *pads, guint64 offset, guint length);
 360
 361 void            gst_collect_pads2_start         (GstCollectPads2 *pads);
 362 void            gst_collect_pads2_stop          (GstCollectPads2 *pads);
 363 void            gst_collect_pads2_set_flushing  (GstCollectPads2 *pads, gboolean flushing);
 364
 365 /* get collected buffers */
 366 GstBuffer*      gst_collect_pads2_peek          (GstCollectPads2 *pads, GstCollectData2 *data);
 367 GstBuffer*      gst_collect_pads2_pop           (GstCollectPads2 *pads, GstCollectData2 *data);
 368
 369 /* get collected bytes */
 370 guint           gst_collect_pads2_available     (GstCollectPads2 *pads);
 371 guint           gst_collect_pads2_flush         (GstCollectPads2 *pads, GstCollectData2 *data,
 372                                                  guint size);
 373 GstBuffer*      gst_collect_pads2_read_buffer   (GstCollectPads2 * pads, GstCollectData2 * data,
 374                                                  guint size);
 375 GstBuffer*      gst_collect_pads2_take_buffer   (GstCollectPads2 * pads, GstCollectData2 * data,
 376                                                  guint size);
 377
 378 /* setting and unsetting waiting mode */
 379 void            gst_collect_pads2_set_waiting   (GstCollectPads2 *pads, GstCollectData2 *data,
 380                                                  gboolean waiting);
 381
 382 /* convenience helper */
 383 GstFlowReturn   gst_collect_pads2_clip_running_time (GstCollectPads2 * pads,
 384                                                 GstCollectData2 * cdata, GstBuffer * buf, GstBuffer ** outbuf,
 385                                                 gpointer user_data);
 386
 387 /* default handlers */
 388 gboolean        gst_collect_pads2_event_default (GstCollectPads2 * pads2, GstCollectData2 * data,
 389                                                  GstEvent * event, gboolean discard);
 390 gboolean        gst_collect_pads2_query_default (GstCollectPads2 * pads, GstCollectData2 * data,
 391                                                  GstQuery * query, gboolean discard);
 392
 393
 394 G_END_DECLS
 395
 396 #endif /* __GST_COLLECT_PADS22_H__ */