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