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. Since 1.6
 139  *
 140  * Structure used by the collect_pads.
 141  */
 142 struct _GstCollectData
 143 {
 144   /* with STREAM_LOCK of @collect */
 145   GstCollectPads        *collect;
 146   GstPad                *pad;
 147   GstBuffer             *buffer;
 148   guint                  pos;
 149   GstSegment             segment;
 150
 151   /*< private >*/
 152   /* state: bitfield for easier extension;
 153    * eos, flushing, new_segment, waiting */
 154   GstCollectPadsStateFlags    state;
 155
 156   GstCollectDataPrivate *priv;
 157
 158   /*< public >*/
 159   union {
 160     struct {
 161       gint64 dts;
 162     } abi;
 163     /*< private >*/
 164     gpointer _gst_reserved[GST_PADDING];
 165   } ABI;
 166 };
 167
 168 /**
 169  * GstCollectPadsFunction:
 170  * @pads: the #GstCollectPads that triggered the callback
 171  * @user_data: user data passed to gst_collect_pads_set_function()
 172  *
 173  * A function that will be called when all pads have received data.
 174  *
 175  * Returns: %GST_FLOW_OK for success
 176  */
 177 typedef GstFlowReturn (*GstCollectPadsFunction) (GstCollectPads *pads, gpointer user_data);
 178
 179 /**
 180  * GstCollectPadsBufferFunction:
 181  * @pads: the #GstCollectPads that triggered the callback
 182  * @data: the #GstCollectData of pad that has received the buffer
 183  * @buffer: (transfer full): the #GstBuffer
 184  * @user_data: user data passed to gst_collect_pads_set_buffer_function()
 185  *
 186  * A function that will be called when a (considered oldest) buffer can be muxed.
 187  * If all pads have reached EOS, this function is called with %NULL @buffer
 188  * and %NULL @data.
 189  *
 190  * Returns: %GST_FLOW_OK for success
 191  */
 192 typedef GstFlowReturn (*GstCollectPadsBufferFunction) (GstCollectPads *pads, GstCollectData *data,
 193                                                        GstBuffer *buffer, gpointer user_data);
 194
 195 /**
 196  * GstCollectPadsCompareFunction:
 197  * @pads: the #GstCollectPads that is comparing the timestamps
 198  * @data1: the first #GstCollectData
 199  * @timestamp1: the first timestamp
 200  * @data2: the second #GstCollectData
 201  * @timestamp2: the second timestamp
 202  * @user_data: user data passed to gst_collect_pads_set_compare_function()
 203  *
 204  * A function for comparing two timestamps of buffers or newsegments collected on one pad.
 205  *
 206  * Returns: Integer less than zero when first timestamp is deemed older than the second one.
 207  *          Zero if the timestamps are deemed equally old.
 208  *          Integer greater than zero when second timestamp is deemed older than the first one.
 209  */
 210 typedef gint (*GstCollectPadsCompareFunction) (GstCollectPads *pads,
 211                                                GstCollectData * data1, GstClockTime timestamp1,
 212                                                GstCollectData * data2, GstClockTime timestamp2,
 213                                                gpointer user_data);
 214
 215 /**
 216  * GstCollectPadsEventFunction:
 217  * @pads: the #GstCollectPads that triggered the callback
 218  * @pad: the #GstPad that received an event
 219  * @event: the #GstEvent received
 220  * @user_data: user data passed to gst_collect_pads_set_event_function()
 221  *
 222  * A function that will be called while processing an event. It takes
 223  * ownership of the event and is responsible for chaining up (to
 224  * gst_collect_pads_event_default()) or dropping events (such typical cases
 225  * being handled by the default handler).
 226  *
 227  * Returns: %TRUE if the pad could handle the event
 228  */
 229 typedef gboolean (*GstCollectPadsEventFunction)        (GstCollectPads *pads, GstCollectData * pad,
 230                                                         GstEvent * event, gpointer user_data);
 231
 232
 233 /**
 234  * GstCollectPadsQueryFunction:
 235  * @pads: the #GstCollectPads that triggered the callback
 236  * @pad: the #GstPad that received an event
 237  * @query: the #GstEvent received
 238  * @user_data: user data passed to gst_collect_pads_set_query_function()
 239  *
 240  * A function that will be called while processing a query. It takes
 241  * ownership of the query and is responsible for chaining up (to
 242  * events downstream (with gst_pad_event_default()).
 243  *
 244  * Returns: %TRUE if the pad could handle the event
 245  */
 246 typedef gboolean (*GstCollectPadsQueryFunction)        (GstCollectPads *pads, GstCollectData * pad,
 247                                                         GstQuery * query, gpointer user_data);
 248
 249 /**
 250  * GstCollectPadsClipFunction:
 251  * @pads: a #GstCollectPads
 252  * @data: a #GstCollectData
 253  * @inbuffer: (transfer full): the input #GstBuffer
 254  * @outbuffer: the output #GstBuffer
 255  * @user_data: user data
 256  *
 257  * A function that will be called when @inbuffer is received on the pad managed
 258  * by @data in the collectpad object @pads.
 259  *
 260  * The function should use the segment of @data and the negotiated media type on
 261  * the pad to perform clipping of @inbuffer.
 262  *
 263  * This function takes ownership of @inbuffer and should output a buffer in
 264  * @outbuffer or return %NULL in @outbuffer if the buffer should be dropped.
 265  *
 266  * Returns: a #GstFlowReturn that corresponds to the result of clipping.
 267  */
 268 typedef GstFlowReturn (*GstCollectPadsClipFunction) (GstCollectPads *pads, GstCollectData *data,
 269                                                      GstBuffer *inbuffer, GstBuffer **outbuffer,
 270                                                      gpointer user_data);
 271
 272
 273 /**
 274  * GstCollectPadsFlushFunction:
 275  * @pads: a #GstCollectPads
 276  * @user_data: user data
 277  *
 278  * A function that will be called while processing a flushing seek event.
 279  *
 280  * The function should flush any internal state of the element and the state of
 281  * all the pads. It should clear only the state not directly managed by the
 282  * @pads object. It is therefore not necessary to call
 283  * gst_collect_pads_set_flushing nor gst_collect_pads_clear from this function.
 284  *
 285  * Since: 1.4
 286  */
 287 typedef void (*GstCollectPadsFlushFunction) (GstCollectPads *pads, gpointer user_data);
 288
 289 /**
 290  * GST_COLLECT_PADS_GET_STREAM_LOCK:
 291  * @pads: a #GstCollectPads
 292  *
 293  * Get the stream lock of @pads. The stream lock is used to coordinate and
 294  * serialize execution among the various streams being collected, and in
 295  * protecting the resources used to accomplish this.
 296  */
 297 #define GST_COLLECT_PADS_GET_STREAM_LOCK(pads) (&((GstCollectPads *)pads)->stream_lock)
 298 /**
 299  * GST_COLLECT_PADS_STREAM_LOCK:
 300  * @pads: a #GstCollectPads
 301  *
 302  * Lock the stream lock of @pads.
 303  */
 304 #define GST_COLLECT_PADS_STREAM_LOCK(pads)     g_rec_mutex_lock(GST_COLLECT_PADS_GET_STREAM_LOCK (pads))
 305 /**
 306  * GST_COLLECT_PADS_STREAM_UNLOCK:
 307  * @pads: a #GstCollectPads
 308  *
 309  * Unlock the stream lock of @pads.
 310  */
 311 #define GST_COLLECT_PADS_STREAM_UNLOCK(pads)   g_rec_mutex_unlock(GST_COLLECT_PADS_GET_STREAM_LOCK (pads))
 312
 313 /**
 314  * GstCollectPads:
 315  * @data: (element-type GstBase.CollectData): #GList of #GstCollectData managed
 316  *   by this #GstCollectPads.
 317  *
 318  * Collectpads object.
 319  */
 320 struct _GstCollectPads {
 321   GstObject      object;
 322
 323   /*< public >*/ /* with LOCK and/or STREAM_LOCK */
 324   GSList        *data;                  /* list of CollectData items */
 325
 326   /*< private >*/
 327   GRecMutex      stream_lock;          /* used to serialize collection among several streams */
 328
 329   GstCollectPadsPrivate *priv;
 330
 331   gpointer _gst_reserved[GST_PADDING];
 332 };
 333
 334 struct _GstCollectPadsClass {
 335   GstObjectClass parent_class;
 336
 337   /*< private >*/
 338   gpointer _gst_reserved[GST_PADDING];
 339 };
 340
 341 GType gst_collect_pads_get_type(void);
 342
 343 /* creating the object */
 344 GstCollectPads*        gst_collect_pads_new           (void);
 345
 346 /* set the callbacks */
 347 void            gst_collect_pads_set_function         (GstCollectPads *pads,
 348                                                        GstCollectPadsFunction func,
 349                                                        gpointer user_data);
 350 void            gst_collect_pads_set_buffer_function  (GstCollectPads *pads,
 351                                                        GstCollectPadsBufferFunction func,
 352                                                        gpointer user_data);
 353 void            gst_collect_pads_set_event_function   (GstCollectPads *pads,
 354                                                        GstCollectPadsEventFunction func,
 355                                                        gpointer user_data);
 356 void            gst_collect_pads_set_query_function   (GstCollectPads *pads,
 357                                                        GstCollectPadsQueryFunction func,
 358                                                        gpointer user_data);
 359 void            gst_collect_pads_set_compare_function (GstCollectPads *pads,
 360                                                        GstCollectPadsCompareFunction func,
 361                                                        gpointer user_data);
 362 void            gst_collect_pads_set_clip_function    (GstCollectPads *pads,
 363                                                        GstCollectPadsClipFunction clipfunc,
 364                                                        gpointer user_data);
 365 void            gst_collect_pads_set_flush_function    (GstCollectPads *pads,
 366                                                        GstCollectPadsFlushFunction func,
 367                                                        gpointer user_data);
 368
 369 /* pad management */
 370 GstCollectData* gst_collect_pads_add_pad       (GstCollectPads *pads, GstPad *pad, guint size,
 371                                                 GstCollectDataDestroyNotify destroy_notify,
 372                                                 gboolean lock);
 373 gboolean        gst_collect_pads_remove_pad    (GstCollectPads *pads, GstPad *pad);
 374
 375 /* start/stop collection */
 376 void            gst_collect_pads_start         (GstCollectPads *pads);
 377 void            gst_collect_pads_stop          (GstCollectPads *pads);
 378 void            gst_collect_pads_set_flushing  (GstCollectPads *pads, gboolean flushing);
 379
 380 /* get collected buffers */
 381 GstBuffer*      gst_collect_pads_peek          (GstCollectPads *pads, GstCollectData *data);
 382 GstBuffer*      gst_collect_pads_pop           (GstCollectPads *pads, GstCollectData *data);
 383
 384 /* get collected bytes */
 385 guint           gst_collect_pads_available     (GstCollectPads *pads);
 386 guint           gst_collect_pads_flush         (GstCollectPads *pads, GstCollectData *data,
 387                                                 guint size);
 388 GstBuffer*      gst_collect_pads_read_buffer   (GstCollectPads * pads, GstCollectData * data,
 389                                                 guint size);
 390 GstBuffer*      gst_collect_pads_take_buffer   (GstCollectPads * pads, GstCollectData * data,
 391                                                 guint size);
 392
 393 /* setting and unsetting waiting mode */
 394 void            gst_collect_pads_set_waiting   (GstCollectPads *pads, GstCollectData *data,
 395                                                 gboolean waiting);
 396
 397 /* convenience helper */
 398 GstFlowReturn   gst_collect_pads_clip_running_time (GstCollectPads * pads,
 399                                                     GstCollectData * cdata,
 400                                                     GstBuffer * buf, GstBuffer ** outbuf,
 401                                                     gpointer user_data);
 402
 403 /* default handlers */
 404 gboolean        gst_collect_pads_event_default (GstCollectPads * pads, GstCollectData * data,
 405                                                 GstEvent * event, gboolean discard);
 406 gboolean        gst_collect_pads_src_event_default (GstCollectPads * pads, GstPad * pad,
 407                                                     GstEvent * event);
 408 gboolean        gst_collect_pads_query_default (GstCollectPads * pads, GstCollectData * data,
 409                                                 GstQuery * query, gboolean discard);
 410
 411
 412 G_END_DECLS
 413
 414 #endif /* __GST_COLLECT_PADS_H__ */