libs/gst/base/gstcollectpads.h

   1 /* GStreamer
   2  * Copyright (C) 2005 Wim Taymans <wim@fluendo.com>
   3  * Copyright (C) 2008 Mark Nauwelaerts <mnauw@users.sourceforge.net>
   4  *
   5  * gstcollectpads.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., 51 Franklin St, Fifth Floor,
  20  * Boston, MA 02110-1301, USA.
  21  */
  22
  23 #ifndef __GST_COLLECT_PADS_H__
  24 #define __GST_COLLECT_PADS_H__
  25
  26 #include <gst/gst.h>
  27
  28 G_BEGIN_DECLS
  29
  30 #define GST_TYPE_COLLECT_PADS            (gst_collect_pads_get_type())
  31 #define GST_COLLECT_PADS(obj)            (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_COLLECT_PADS,GstCollectPads))
  32 #define GST_COLLECT_PADS_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST((klass),GST_TYPE_COLLECT_PADS,GstCollectPadsClass))
  33 #define GST_COLLECT_PADS_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS ((obj),GST_TYPE_COLLECT_PADS,GstCollectPadsClass))
  34 #define GST_IS_COLLECT_PADS(obj)         (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_COLLECT_PADS))
  35 #define GST_IS_COLLECT_PADS_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_COLLECT_PADS))
  36
  37 typedef struct _GstCollectData GstCollectData;
  38 typedef struct _GstCollectDataPrivate GstCollectDataPrivate;
  39 typedef struct _GstCollectPads GstCollectPads;
  40 typedef struct _GstCollectPadsPrivate GstCollectPadsPrivate;
  41 typedef struct _GstCollectPadsClass GstCollectPadsClass;
  42
  43 /**
  44  * GstCollectDataDestroyNotify:
  45  * @data: the #GstCollectData that will be freed
  46  *
  47  * A function that will be called when the #GstCollectData 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 typedef void (*GstCollectDataDestroyNotify) (GstCollectData *data);
  52
  53 /**
  54  * GstCollectPadsStateFlags:
  55  * @GST_COLLECT_PADS_STATE_EOS:         Set if collectdata's pad is EOS.
  56  * @GST_COLLECT_PADS_STATE_FLUSHING:    Set if collectdata's pad is flushing.
  57  * @GST_COLLECT_PADS_STATE_NEW_SEGMENT: Set if collectdata's pad received a
  58  *                                      new_segment event.
  59  * @GST_COLLECT_PADS_STATE_WAITING:     Set if collectdata's pad must be waited
  60  *                                      for when collecting.
  61  * @GST_COLLECT_PADS_STATE_LOCKED:      Set collectdata's pad WAITING state must
  62  *                                      not be changed.
  63  * #GstCollectPadsStateFlags indicate private state of a collectdata('s pad).
  64  */
  65 typedef enum {
  66   GST_COLLECT_PADS_STATE_EOS = 1 << 0,
  67   GST_COLLECT_PADS_STATE_FLUSHING = 1 << 1,
  68   GST_COLLECT_PADS_STATE_NEW_SEGMENT = 1 << 2,
  69   GST_COLLECT_PADS_STATE_WAITING = 1 << 3,
  70   GST_COLLECT_PADS_STATE_LOCKED = 1 << 4
  71 } GstCollectPadsStateFlags;
  72
  73 /**
  74  * GST_COLLECT_PADS_STATE:
  75  * @data: a #GstCollectData.
  76  *
  77  * A flags word containing #GstCollectPadsStateFlags flags set
  78  * on this collected pad.
  79  */
  80 #define GST_COLLECT_PADS_STATE(data)                 (((GstCollectData *) data)->state)
  81 /**
  82  * GST_COLLECT_PADS_STATE_IS_SET:
  83  * @data: a #GstCollectData.
  84  * @flag: the #GstCollectPadsStateFlags to check.
  85  *
  86  * Gives the status of a specific flag on a collected pad.
  87  */
  88 #define GST_COLLECT_PADS_STATE_IS_SET(data,flag)     !!(GST_COLLECT_PADS_STATE (data) & flag)
  89 /**
  90  * GST_COLLECT_PADS_STATE_SET:
  91  * @data: a #GstCollectData.
  92  * @flag: the #GstCollectPadsStateFlags to set.
  93  *
  94  * Sets a state flag on a collected pad.
  95  */
  96 #define GST_COLLECT_PADS_STATE_SET(data,flag)        (GST_COLLECT_PADS_STATE (data) |= flag)
  97 /**
  98  * GST_COLLECT_PADS_STATE_UNSET:
  99  * @data: a #GstCollectData.
 100  * @flag: the #GstCollectPadsStateFlags to clear.
 101  *
 102  * Clears a state flag on a collected pad.
 103  */
 104 #define GST_COLLECT_PADS_STATE_UNSET(data,flag)      (GST_COLLECT_PADS_STATE (data) &= ~(flag))
 105
 106 /**
 107  * GST_COLLECT_PADS_DTS:
 108  * @data: A #GstCollectData.
 109  *
 110  * Returns the DTS that has been converted to running time when using
 111  * gst_collect_pads_clip_running_time(). Unlike the value saved into
 112  * the buffer, this value is of type gint64 and may be negative. This allow
 113  * properly handling streams with frame reordering where the first DTS may
 114  * be negative. If the initial DTS was not set, this value will be
 115  * set to %G_MININT64.
 116  *
 117  * Since: 1.6
 118  */
 119 #define GST_COLLECT_PADS_DTS(data)                   (((GstCollectData *) data)->ABI.abi.dts)
 120
 121 /**
 122  * GST_COLLECT_PADS_DTS_IS_VALID:
 123  * @data: A #GstCollectData.
 124  *
 125  * Check if running DTS value store is valid.
 126  *
 127  * Since: 1.6
 128  */
 129 #define GST_COLLECT_PADS_DTS_IS_VALID(data)          (GST_CLOCK_STIME_IS_VALID (GST_COLLECT_PADS_DTS (data)))
 130
 131 /**
 132  * GstCollectData:
 133  * @collect: owner #GstCollectPads
 134  * @pad: #GstPad managed by this data
 135  * @buffer: currently queued buffer.
 136  * @pos: position in the buffer
 137  * @segment: last segment received.
 138  * @dts: the signed version of the DTS converted to running time. To access
 139  *       this memeber, use %GST_COLLECT_PADS_DTS macro. (Since 1.6)
 140  *
 141  * Structure used by the collect_pads.
 142  */
 143 struct _GstCollectData
 144 {
 145   /* with STREAM_LOCK of @collect */
 146   GstCollectPads        *collect;
 147   GstPad                *pad;
 148   GstBuffer             *buffer;
 149   guint                  pos;
 150   GstSegment             segment;
 151
 152   /*< private >*/
 153   /* state: bitfield for easier extension;
 154    * eos, flushing, new_segment, waiting */
 155   GstCollectPadsStateFlags    state;
 156
 157   GstCollectDataPrivate *priv;
 158
 159   union {
 160     struct {
 161       /*< public >*/
 162       gint64 dts;
 163       /*< private >*/
 164     } abi;
 165     gpointer _gst_reserved[GST_PADDING];
 166   } ABI;
 167 };
 168
 169 /**
 170  * GstCollectPadsFunction:
 171  * @pads: the #GstCollectPads that triggered the callback
 172  * @user_data: user data passed to gst_collect_pads_set_function()
 173  *
 174  * A function that will be called when all pads have received data.
 175  *
 176  * Returns: %GST_FLOW_OK for success
 177  */
 178 typedef GstFlowReturn (*GstCollectPadsFunction) (GstCollectPads *pads, gpointer user_data);
 179
 180 /**
 181  * GstCollectPadsBufferFunction:
 182  * @pads: the #GstCollectPads that triggered the callback
 183  * @data: the #GstCollectData of pad that has received the buffer
 184  * @buffer: (transfer full): the #GstBuffer
 185  * @user_data: user data passed to gst_collect_pads_set_buffer_function()
 186  *
 187  * A function that will be called when a (considered oldest) buffer can be muxed.
 188  * If all pads have reached EOS, this function is called with %NULL @buffer
 189  * and %NULL @data.
 190  *
 191  * Returns: %GST_FLOW_OK for success
 192  */
 193 typedef GstFlowReturn (*GstCollectPadsBufferFunction) (GstCollectPads *pads, GstCollectData *data,
 194                                                        GstBuffer *buffer, gpointer user_data);
 195
 196 /**
 197  * GstCollectPadsCompareFunction:
 198  * @pads: the #GstCollectPads that is comparing the timestamps
 199  * @data1: the first #GstCollectData
 200  * @timestamp1: the first timestamp
 201  * @data2: the second #GstCollectData
 202  * @timestamp2: the second timestamp
 203  * @user_data: user data passed to gst_collect_pads_set_compare_function()
 204  *
 205  * A function for comparing two timestamps of buffers or newsegments collected on one pad.
 206  *
 207  * Returns: Integer less than zero when first timestamp is deemed older than the second one.
 208  *          Zero if the timestamps are deemed equally old.
 209  *          Integer greater than zero when second timestamp is deemed older than the first one.
 210  */
 211 typedef gint (*GstCollectPadsCompareFunction) (GstCollectPads *pads,
 212                                                GstCollectData * data1, GstClockTime timestamp1,
 213                                                GstCollectData * data2, GstClockTime timestamp2,
 214                                                gpointer user_data);
 215
 216 /**
 217  * GstCollectPadsEventFunction:
 218  * @pads: the #GstCollectPads that triggered the callback
 219  * @pad: the #GstPad that received an event
 220  * @event: the #GstEvent received
 221  * @user_data: user data passed to gst_collect_pads_set_event_function()
 222  *
 223  * A function that will be called while processing an event. It takes
 224  * ownership of the event and is responsible for chaining up (to
 225  * gst_collect_pads_event_default()) or dropping events (such typical cases
 226  * being handled by the default handler).
 227  *
 228  * Returns: %TRUE if the pad could handle the event
 229  */
 230 typedef gboolean (*GstCollectPadsEventFunction)        (GstCollectPads *pads, GstCollectData * pad,
 231                                                         GstEvent * event, gpointer user_data);
 232
 233
 234 /**
 235  * GstCollectPadsQueryFunction:
 236  * @pads: the #GstCollectPads that triggered the callback
 237  * @pad: the #GstPad that received an event
 238  * @query: the #GstEvent received
 239  * @user_data: user data passed to gst_collect_pads_set_query_function()
 240  *
 241  * A function that will be called while processing a query. It takes
 242  * ownership of the query and is responsible for chaining up (to
 243  * events downstream (with gst_pad_event_default()).
 244  *
 245  * Returns: %TRUE if the pad could handle the event
 246  */
 247 typedef gboolean (*GstCollectPadsQueryFunction)        (GstCollectPads *pads, GstCollectData * pad,
 248                                                         GstQuery * query, gpointer user_data);
 249
 250 /**
 251  * GstCollectPadsClipFunction:
 252  * @pads: a #GstCollectPads
 253  * @data: a #GstCollectData
 254  * @inbuffer: (transfer full): the input #GstBuffer
 255  * @outbuffer: the output #GstBuffer
 256  * @user_data: user data
 257  *
 258  * A function that will be called when @inbuffer is received on the pad managed
 259  * by @data in the collectpad object @pads.
 260  *
 261  * The function should use the segment of @data and the negotiated media type on
 262  * the pad to perform clipping of @inbuffer.
 263  *
 264  * This function takes ownership of @inbuffer and should output a buffer in
 265  * @outbuffer or return %NULL in @outbuffer if the buffer should be dropped.
 266  *
 267  * Returns: a #GstFlowReturn that corresponds to the result of clipping.
 268  */
 269 typedef GstFlowReturn (*GstCollectPadsClipFunction) (GstCollectPads *pads, GstCollectData *data,
 270                                                      GstBuffer *inbuffer, GstBuffer **outbuffer,
 271                                                      gpointer user_data);
 272
 273
 274 /**
 275  * GstCollectPadsFlushFunction:
 276  * @pads: a #GstCollectPads
 277  * @user_data: user data
 278  *
 279  * A function that will be called while processing a flushing seek event.
 280  *
 281  * The function should flush any internal state of the element and the state of
 282  * all the pads. It should clear only the state not directly managed by the
 283  * @pads object. It is therefore not necessary to call
 284  * gst_collect_pads_set_flushing nor gst_collect_pads_clear from this function.
 285  *
 286  * Since: 1.4
 287  */
 288 typedef void (*GstCollectPadsFlushFunction) (GstCollectPads *pads, gpointer user_data);
 289
 290 /**
 291  * GST_COLLECT_PADS_GET_STREAM_LOCK:
 292  * @pads: a #GstCollectPads
 293  *
 294  * Get the stream lock of @pads. The stream lock is used to coordinate and
 295  * serialize execution among the various streams being collected, and in
 296  * protecting the resources used to accomplish this.
 297  */
 298 #define GST_COLLECT_PADS_GET_STREAM_LOCK(pads) (&((GstCollectPads *)pads)->stream_lock)
 299 /**
 300  * GST_COLLECT_PADS_STREAM_LOCK:
 301  * @pads: a #GstCollectPads
 302  *
 303  * Lock the stream lock of @pads.
 304  */
 305 #define GST_COLLECT_PADS_STREAM_LOCK(pads)     g_rec_mutex_lock(GST_COLLECT_PADS_GET_STREAM_LOCK (pads))
 306 /**
 307  * GST_COLLECT_PADS_STREAM_UNLOCK:
 308  * @pads: a #GstCollectPads
 309  *
 310  * Unlock the stream lock of @pads.
 311  */
 312 #define GST_COLLECT_PADS_STREAM_UNLOCK(pads)   g_rec_mutex_unlock(GST_COLLECT_PADS_GET_STREAM_LOCK (pads))
 313
 314 /**
 315  * GstCollectPads:
 316  * @data: (element-type GstBase.CollectData): #GList of #GstCollectData managed
 317  *   by this #GstCollectPads.
 318  *
 319  * Collectpads object.
 320  */
 321 struct _GstCollectPads {
 322   GstObject      object;
 323
 324   /*< public >*/ /* with LOCK and/or STREAM_LOCK */
 325   GSList        *data;                  /* list of CollectData items */
 326
 327   /*< private >*/
 328   GRecMutex      stream_lock;          /* used to serialize collection among several streams */
 329
 330   GstCollectPadsPrivate *priv;
 331
 332   gpointer _gst_reserved[GST_PADDING];
 333 };
 334
 335 struct _GstCollectPadsClass {
 336   GstObjectClass parent_class;
 337
 338   /*< private >*/
 339   gpointer _gst_reserved[GST_PADDING];
 340 };
 341
 342 GST_EXPORT
 343 GType           gst_collect_pads_get_type (void);
 344
 345 /* creating the object */
 346
 347 GST_EXPORT
 348 GstCollectPads* gst_collect_pads_new      (void);
 349
 350 /* set the callbacks */
 351
 352 GST_EXPORT
 353 void            gst_collect_pads_set_function         (GstCollectPads *pads,
 354                                                        GstCollectPadsFunction func,
 355                                                        gpointer user_data);
 356 GST_EXPORT
 357 void            gst_collect_pads_set_buffer_function  (GstCollectPads *pads,
 358                                                        GstCollectPadsBufferFunction func,
 359                                                        gpointer user_data);
 360 GST_EXPORT
 361 void            gst_collect_pads_set_event_function   (GstCollectPads *pads,
 362                                                        GstCollectPadsEventFunction func,
 363                                                        gpointer user_data);
 364 GST_EXPORT
 365 void            gst_collect_pads_set_query_function   (GstCollectPads *pads,
 366                                                        GstCollectPadsQueryFunction func,
 367                                                        gpointer user_data);
 368 GST_EXPORT
 369 void            gst_collect_pads_set_compare_function (GstCollectPads *pads,
 370                                                        GstCollectPadsCompareFunction func,
 371                                                        gpointer user_data);
 372 GST_EXPORT
 373 void            gst_collect_pads_set_clip_function    (GstCollectPads *pads,
 374                                                        GstCollectPadsClipFunction clipfunc,
 375                                                        gpointer user_data);
 376 GST_EXPORT
 377 void            gst_collect_pads_set_flush_function    (GstCollectPads *pads,
 378                                                        GstCollectPadsFlushFunction func,
 379                                                        gpointer user_data);
 380
 381 /* pad management */
 382
 383 GST_EXPORT
 384 GstCollectData* gst_collect_pads_add_pad       (GstCollectPads *pads, GstPad *pad, guint size,
 385                                                 GstCollectDataDestroyNotify destroy_notify,
 386                                                 gboolean lock);
 387 GST_EXPORT
 388 gboolean        gst_collect_pads_remove_pad    (GstCollectPads *pads, GstPad *pad);
 389
 390 /* start/stop collection */
 391
 392 GST_EXPORT
 393 void            gst_collect_pads_start         (GstCollectPads *pads);
 394
 395 GST_EXPORT
 396 void            gst_collect_pads_stop          (GstCollectPads *pads);
 397
 398 GST_EXPORT
 399 void            gst_collect_pads_set_flushing  (GstCollectPads *pads, gboolean flushing);
 400
 401 /* get collected buffers */
 402
 403 GST_EXPORT
 404 GstBuffer*      gst_collect_pads_peek          (GstCollectPads *pads, GstCollectData *data);
 405
 406 GST_EXPORT
 407 GstBuffer*      gst_collect_pads_pop           (GstCollectPads *pads, GstCollectData *data);
 408
 409 /* get collected bytes */
 410
 411 GST_EXPORT
 412 guint           gst_collect_pads_available     (GstCollectPads *pads);
 413
 414 GST_EXPORT
 415 guint           gst_collect_pads_flush         (GstCollectPads *pads, GstCollectData *data,
 416                                                 guint size);
 417 GST_EXPORT
 418 GstBuffer*      gst_collect_pads_read_buffer   (GstCollectPads * pads, GstCollectData * data,
 419                                                 guint size);
 420 GST_EXPORT
 421 GstBuffer*      gst_collect_pads_take_buffer   (GstCollectPads * pads, GstCollectData * data,
 422                                                 guint size);
 423
 424 /* setting and unsetting waiting mode */
 425
 426 GST_EXPORT
 427 void            gst_collect_pads_set_waiting   (GstCollectPads *pads, GstCollectData *data,
 428                                                 gboolean waiting);
 429
 430 /* convenience helper */
 431
 432 GST_EXPORT
 433 GstFlowReturn   gst_collect_pads_clip_running_time (GstCollectPads * pads,
 434                                                     GstCollectData * cdata,
 435                                                     GstBuffer * buf, GstBuffer ** outbuf,
 436                                                     gpointer user_data);
 437
 438 /* default handlers */
 439
 440 GST_EXPORT
 441 gboolean        gst_collect_pads_event_default (GstCollectPads * pads, GstCollectData * data,
 442                                                 GstEvent * event, gboolean discard);
 443 GST_EXPORT
 444 gboolean        gst_collect_pads_src_event_default (GstCollectPads * pads, GstPad * pad,
 445                                                     GstEvent * event);
 446 GST_EXPORT
 447 gboolean        gst_collect_pads_query_default (GstCollectPads * pads, GstCollectData * data,
 448                                                 GstQuery * query, gboolean discard);
 449
 450
 451 #ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC
 452 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstCollectPads, gst_object_unref)
 453 #endif
 454
 455 G_END_DECLS
 456
 457 #endif /* __GST_COLLECT_PADS_H__ */