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