Debian Codegraph @

libs/gst/base/gstcollectpads.h

raw
1 /* GStreamer
2 * Copyright (C) 2005 Wim Taymans <[email protected]>
3 * Copyright (C) 2008 Mark Nauwelaerts <[email protected]>
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) G_GNUC_WARN_UNUSED_RESULT;
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) G_GNUC_WARN_UNUSED_RESULT;
406
407 GST_BASE_API
408 GstBuffer* gst_collect_pads_pop (GstCollectPads *pads, GstCollectData *data) G_GNUC_WARN_UNUSED_RESULT;
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) G_GNUC_WARN_UNUSED_RESULT;
421 GST_BASE_API
422 GstBuffer* gst_collect_pads_take_buffer (GstCollectPads * pads, GstCollectData * data,
423 guint size) G_GNUC_WARN_UNUSED_RESULT;
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__ */