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 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstCollectPads, gst_object_unref) 453 454 G_END_DECLS 455 456 #endif /* __GST_COLLECT_PADS_H__ */ 457