1 | /* GStreamer |
2 | * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu> |
3 | * 2000 Wim Taymans <wtay@chello.be> |
4 | * |
5 | * gstbuffer.h: Header for GstBuffer object |
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 | |
24 | #ifndef __GST_BUFFER_H__ |
25 | #define __GST_BUFFER_H__ |
26 | |
27 | #include <gst/gstminiobject.h> |
28 | #include <gst/gstclock.h> |
29 | #include <gst/gstallocator.h> |
30 | #include <gst/gstcaps.h> |
31 | |
32 | G_BEGIN_DECLS |
33 | |
34 | GST_API GType _gst_buffer_type; |
35 | |
36 | typedef struct _GstBuffer GstBuffer; |
37 | typedef struct _GstBufferPool GstBufferPool; |
38 | |
39 | #include <gst/gstmeta.h> |
40 | |
41 | #define GST_TYPE_BUFFER (_gst_buffer_type) |
42 | #define GST_IS_BUFFER(obj) (GST_IS_MINI_OBJECT_TYPE(obj, GST_TYPE_BUFFER)) |
43 | #define GST_BUFFER_CAST(obj) ((GstBuffer *)(obj)) |
44 | #define GST_BUFFER(obj) (GST_BUFFER_CAST(obj)) |
45 | |
46 | /** |
47 | * GST_BUFFER_FLAGS: |
48 | * @buf: a #GstBuffer. |
49 | * |
50 | * Returns a flags word containing #GstBufferFlags flags set on this buffer. |
51 | */ |
52 | #define GST_BUFFER_FLAGS(buf) GST_MINI_OBJECT_FLAGS(buf) |
53 | /** |
54 | * GST_BUFFER_FLAG_IS_SET: |
55 | * @buf: a #GstBuffer. |
56 | * @flag: the #GstBufferFlags flag to check. |
57 | * |
58 | * Gives the status of a specific flag on a buffer. |
59 | */ |
60 | #define GST_BUFFER_FLAG_IS_SET(buf,flag) GST_MINI_OBJECT_FLAG_IS_SET (buf, flag) |
61 | /** |
62 | * GST_BUFFER_FLAG_SET: |
63 | * @buf: a #GstBuffer. |
64 | * @flag: the #GstBufferFlags flag to set. |
65 | * |
66 | * Sets a buffer flag on a buffer. |
67 | */ |
68 | #define GST_BUFFER_FLAG_SET(buf,flag) GST_MINI_OBJECT_FLAG_SET (buf, flag) |
69 | /** |
70 | * GST_BUFFER_FLAG_UNSET: |
71 | * @buf: a #GstBuffer. |
72 | * @flag: the #GstBufferFlags flag to clear. |
73 | * |
74 | * Clears a buffer flag. |
75 | */ |
76 | #define GST_BUFFER_FLAG_UNSET(buf,flag) GST_MINI_OBJECT_FLAG_UNSET (buf, flag) |
77 | |
78 | |
79 | /** |
80 | * GST_BUFFER_PTS: |
81 | * @buf: a #GstBuffer.: |
82 | * |
83 | * Gets the presentation timestamp (pts) in nanoseconds (as a #GstClockTime) |
84 | * of the data in the buffer. This is the timestamp when the media should be |
85 | * presented to the user. |
86 | * |
87 | * Value will be %GST_CLOCK_TIME_NONE if the pts is unknown. |
88 | */ |
89 | #define GST_BUFFER_PTS(buf) (GST_BUFFER_CAST(buf)->pts) |
90 | /** |
91 | * GST_BUFFER_DTS: |
92 | * @buf: a #GstBuffer. |
93 | * |
94 | * Gets the decoding timestamp (dts) in nanoseconds (as a #GstClockTime) |
95 | * of the data in the buffer. This is the timestamp when the media should be |
96 | * decoded or processed otherwise. |
97 | * |
98 | * Value will be %GST_CLOCK_TIME_NONE if the dts is unknown. |
99 | */ |
100 | #define GST_BUFFER_DTS(buf) (GST_BUFFER_CAST(buf)->dts) |
101 | /** |
102 | * GST_BUFFER_DTS_OR_PTS: |
103 | * @buf: a #GstBuffer. |
104 | * |
105 | * Returns the buffer decoding timestamp (dts) if valid, else the buffer |
106 | * presentation time (pts) |
107 | * |
108 | * Since: 1.8 |
109 | */ |
110 | #define GST_BUFFER_DTS_OR_PTS(buf) (GST_BUFFER_DTS_IS_VALID(buf) ? GST_BUFFER_DTS(buf) : GST_BUFFER_PTS (buf)) |
111 | /** |
112 | * GST_BUFFER_DURATION: |
113 | * @buf: a #GstBuffer. |
114 | * |
115 | * Gets the duration in nanoseconds (as a #GstClockTime) of the data in the buffer. |
116 | * |
117 | * Value will be %GST_CLOCK_TIME_NONE if the duration is unknown. |
118 | */ |
119 | #define GST_BUFFER_DURATION(buf) (GST_BUFFER_CAST(buf)->duration) |
120 | /** |
121 | * GST_BUFFER_OFFSET: |
122 | * @buf: a #GstBuffer. |
123 | * |
124 | * Gets the offset in the source file of the beginning of this buffer. |
125 | */ |
126 | #define GST_BUFFER_OFFSET(buf) (GST_BUFFER_CAST(buf)->offset) |
127 | /** |
128 | * GST_BUFFER_OFFSET_END: |
129 | * @buf: a #GstBuffer. |
130 | * |
131 | * Gets the offset in the source file of the end of this buffer. |
132 | */ |
133 | #define GST_BUFFER_OFFSET_END(buf) (GST_BUFFER_CAST(buf)->offset_end) |
134 | |
135 | /** |
136 | * GST_BUFFER_OFFSET_NONE: |
137 | * |
138 | * Constant for no-offset return results. |
139 | */ |
140 | #define GST_BUFFER_OFFSET_NONE ((guint64)-1) |
141 | |
142 | /** |
143 | * GST_BUFFER_DURATION_IS_VALID: |
144 | * @buffer: a #GstBuffer |
145 | * |
146 | * Tests if the duration is known. |
147 | */ |
148 | #define GST_BUFFER_DURATION_IS_VALID(buffer) (GST_CLOCK_TIME_IS_VALID (GST_BUFFER_DURATION (buffer))) |
149 | /** |
150 | * GST_BUFFER_PTS_IS_VALID: |
151 | * @buffer: a #GstBuffer |
152 | * |
153 | * Tests if the pts is known. |
154 | */ |
155 | #define GST_BUFFER_PTS_IS_VALID(buffer) (GST_CLOCK_TIME_IS_VALID (GST_BUFFER_PTS (buffer))) |
156 | /** |
157 | * GST_BUFFER_DTS_IS_VALID: |
158 | * @buffer: a #GstBuffer |
159 | * |
160 | * Tests if the dts is known. |
161 | */ |
162 | #define GST_BUFFER_DTS_IS_VALID(buffer) (GST_CLOCK_TIME_IS_VALID (GST_BUFFER_DTS (buffer))) |
163 | /** |
164 | * GST_BUFFER_OFFSET_IS_VALID: |
165 | * @buffer: a #GstBuffer |
166 | * |
167 | * Tests if the start offset is known. |
168 | */ |
169 | #define GST_BUFFER_OFFSET_IS_VALID(buffer) (GST_BUFFER_OFFSET (buffer) != GST_BUFFER_OFFSET_NONE) |
170 | /** |
171 | * GST_BUFFER_OFFSET_END_IS_VALID: |
172 | * @buffer: a #GstBuffer |
173 | * |
174 | * Tests if the end offset is known. |
175 | */ |
176 | #define GST_BUFFER_OFFSET_END_IS_VALID(buffer) (GST_BUFFER_OFFSET_END (buffer) != GST_BUFFER_OFFSET_NONE) |
177 | /** |
178 | * GST_BUFFER_IS_DISCONT: |
179 | * @buffer: a #GstBuffer |
180 | * |
181 | * Tests if the buffer marks a discontinuity in the stream. |
182 | */ |
183 | #define GST_BUFFER_IS_DISCONT(buffer) (GST_BUFFER_FLAG_IS_SET (buffer, GST_BUFFER_FLAG_DISCONT)) |
184 | |
185 | /** |
186 | * GstBufferFlags: |
187 | * @GST_BUFFER_FLAG_LIVE: the buffer is live data and should be discarded in |
188 | * the PAUSED state. |
189 | * @GST_BUFFER_FLAG_DECODE_ONLY: the buffer contains data that should be dropped |
190 | * because it will be clipped against the segment |
191 | * boundaries or because it does not contain data |
192 | * that should be shown to the user. |
193 | * @GST_BUFFER_FLAG_DISCONT: the buffer marks a data discontinuity in the stream. |
194 | * This typically occurs after a seek or a dropped buffer |
195 | * from a live or network source. |
196 | * @GST_BUFFER_FLAG_RESYNC: the buffer timestamps might have a discontinuity |
197 | * and this buffer is a good point to resynchronize. |
198 | * @GST_BUFFER_FLAG_CORRUPTED: the buffer data is corrupted. |
199 | * @GST_BUFFER_FLAG_MARKER: the buffer contains a media specific marker. for |
200 | * video this is the end of a frame boundary, for audio |
201 | * this is the start of a talkspurt. |
202 | * @GST_BUFFER_FLAG_HEADER: the buffer contains header information that is |
203 | * needed to decode the following data. |
204 | * @GST_BUFFER_FLAG_GAP: the buffer has been created to fill a gap in the |
205 | * stream and contains media neutral data (elements can |
206 | * switch to optimized code path that ignores the buffer |
207 | * content). |
208 | * @GST_BUFFER_FLAG_DROPPABLE: the buffer can be dropped without breaking the |
209 | * stream, for example to reduce bandwidth. |
210 | * @GST_BUFFER_FLAG_DELTA_UNIT: this unit cannot be decoded independently. |
211 | * @GST_BUFFER_FLAG_TAG_MEMORY: this flag is set when memory of the buffer |
212 | * is added/removed |
213 | * @GST_BUFFER_FLAG_LAST: additional media specific flags can be added starting from |
214 | * this flag. |
215 | * |
216 | * A set of buffer flags used to describe properties of a #GstBuffer. |
217 | */ |
218 | typedef enum { |
219 | GST_BUFFER_FLAG_LIVE = (GST_MINI_OBJECT_FLAG_LAST << 0), |
220 | GST_BUFFER_FLAG_DECODE_ONLY = (GST_MINI_OBJECT_FLAG_LAST << 1), |
221 | GST_BUFFER_FLAG_DISCONT = (GST_MINI_OBJECT_FLAG_LAST << 2), |
222 | GST_BUFFER_FLAG_RESYNC = (GST_MINI_OBJECT_FLAG_LAST << 3), |
223 | GST_BUFFER_FLAG_CORRUPTED = (GST_MINI_OBJECT_FLAG_LAST << 4), |
224 | GST_BUFFER_FLAG_MARKER = (GST_MINI_OBJECT_FLAG_LAST << 5), |
225 | = (GST_MINI_OBJECT_FLAG_LAST << 6), |
226 | GST_BUFFER_FLAG_GAP = (GST_MINI_OBJECT_FLAG_LAST << 7), |
227 | GST_BUFFER_FLAG_DROPPABLE = (GST_MINI_OBJECT_FLAG_LAST << 8), |
228 | GST_BUFFER_FLAG_DELTA_UNIT = (GST_MINI_OBJECT_FLAG_LAST << 9), |
229 | GST_BUFFER_FLAG_TAG_MEMORY = (GST_MINI_OBJECT_FLAG_LAST << 10), |
230 | |
231 | /** |
232 | * GST_BUFFER_FLAG_SYNC_AFTER: |
233 | * |
234 | * Elements which write to disk or permanent storage should ensure the data |
235 | * is synced after writing the contents of this buffer. |
236 | * |
237 | * Since: 1.6 |
238 | */ |
239 | GST_BUFFER_FLAG_SYNC_AFTER = (GST_MINI_OBJECT_FLAG_LAST << 11), |
240 | |
241 | /** |
242 | * GST_BUFFER_FLAG_NON_DROPPABLE: |
243 | * |
244 | * This buffer is important and should not be dropped. |
245 | * |
246 | * This can be used to mark important buffers, e.g. to flag RTP packets |
247 | * carrying keyframes or codec setup data for RTP Forward Error Correction |
248 | * purposes, or to prevent still video frames from being dropped by elements |
249 | * due to QoS. |
250 | * |
251 | * Since: 1.14 |
252 | */ |
253 | GST_BUFFER_FLAG_NON_DROPPABLE = (GST_MINI_OBJECT_FLAG_LAST << 12), |
254 | |
255 | GST_BUFFER_FLAG_LAST = (GST_MINI_OBJECT_FLAG_LAST << 16) |
256 | } GstBufferFlags; |
257 | |
258 | /** |
259 | * GstBuffer: |
260 | * @mini_object: the parent structure |
261 | * @pool: pointer to the pool owner of the buffer |
262 | * @pts: presentation timestamp of the buffer, can be #GST_CLOCK_TIME_NONE when the |
263 | * pts is not known or relevant. The pts contains the timestamp when the |
264 | * media should be presented to the user. |
265 | * @dts: decoding timestamp of the buffer, can be #GST_CLOCK_TIME_NONE when the |
266 | * dts is not known or relevant. The dts contains the timestamp when the |
267 | * media should be processed. |
268 | * @duration: duration in time of the buffer data, can be #GST_CLOCK_TIME_NONE |
269 | * when the duration is not known or relevant. |
270 | * @offset: a media specific offset for the buffer data. |
271 | * For video frames, this is the frame number of this buffer. |
272 | * For audio samples, this is the offset of the first sample in this buffer. |
273 | * For file data or compressed data this is the byte offset of the first |
274 | * byte in this buffer. |
275 | * @offset_end: the last offset contained in this buffer. It has the same |
276 | * format as @offset. |
277 | * |
278 | * The structure of a #GstBuffer. Use the associated macros to access the public |
279 | * variables. |
280 | */ |
281 | struct _GstBuffer { |
282 | GstMiniObject mini_object; |
283 | |
284 | /*< public >*/ /* with COW */ |
285 | GstBufferPool *pool; |
286 | |
287 | /* timestamp */ |
288 | GstClockTime pts; |
289 | GstClockTime dts; |
290 | GstClockTime duration; |
291 | |
292 | /* media specific offset */ |
293 | guint64 offset; |
294 | guint64 offset_end; |
295 | }; |
296 | |
297 | GST_API |
298 | GType gst_buffer_get_type (void); |
299 | |
300 | GST_API |
301 | guint gst_buffer_get_max_memory (void); |
302 | |
303 | /* allocation */ |
304 | |
305 | GST_API |
306 | GstBuffer * gst_buffer_new (void); |
307 | |
308 | GST_API |
309 | GstBuffer * gst_buffer_new_allocate (GstAllocator * allocator, gsize size, |
310 | GstAllocationParams * params); |
311 | GST_API |
312 | GstBuffer * gst_buffer_new_wrapped_full (GstMemoryFlags flags, gpointer data, gsize maxsize, |
313 | gsize offset, gsize size, gpointer user_data, |
314 | GDestroyNotify notify); |
315 | GST_API |
316 | GstBuffer * gst_buffer_new_wrapped (gpointer data, gsize size); |
317 | |
318 | GST_API |
319 | GstBuffer * gst_buffer_new_wrapped_bytes (GBytes * bytes); |
320 | |
321 | GST_API |
322 | GstBuffer * gst_buffer_new_memdup (gconstpointer data, gsize size); |
323 | |
324 | /* memory blocks */ |
325 | |
326 | GST_API |
327 | guint gst_buffer_n_memory (GstBuffer *buffer); |
328 | |
329 | GST_API |
330 | void gst_buffer_insert_memory (GstBuffer *buffer, gint idx, GstMemory *mem); |
331 | |
332 | GST_API |
333 | void gst_buffer_replace_memory_range (GstBuffer *buffer, guint idx, gint length, GstMemory *mem); |
334 | |
335 | GST_API |
336 | GstMemory * gst_buffer_peek_memory (GstBuffer *buffer, guint idx); |
337 | |
338 | GST_API |
339 | GstMemory * gst_buffer_get_memory_range (GstBuffer *buffer, guint idx, gint length); |
340 | |
341 | GST_API |
342 | void gst_buffer_remove_memory_range (GstBuffer *buffer, guint idx, gint length); |
343 | |
344 | GST_API |
345 | void gst_buffer_prepend_memory (GstBuffer *buffer, GstMemory *mem); |
346 | |
347 | GST_API |
348 | void gst_buffer_append_memory (GstBuffer *buffer, GstMemory *mem); |
349 | |
350 | GST_API |
351 | void gst_buffer_replace_memory (GstBuffer *buffer, guint idx, GstMemory *mem); |
352 | |
353 | GST_API |
354 | void gst_buffer_replace_all_memory (GstBuffer *buffer, GstMemory *mem); |
355 | |
356 | GST_API |
357 | GstMemory * gst_buffer_get_memory (GstBuffer *buffer, guint idx); |
358 | |
359 | GST_API |
360 | GstMemory * gst_buffer_get_all_memory (GstBuffer *buffer); |
361 | |
362 | GST_API |
363 | void gst_buffer_remove_memory (GstBuffer *buffer, guint idx); |
364 | |
365 | GST_API |
366 | void gst_buffer_remove_all_memory (GstBuffer *buffer); |
367 | |
368 | GST_API |
369 | gboolean gst_buffer_find_memory (GstBuffer *buffer, gsize offset, gsize size, |
370 | guint *idx, guint *length, gsize *skip); |
371 | GST_API |
372 | gboolean gst_buffer_is_memory_range_writable (GstBuffer *buffer, guint idx, gint length); |
373 | |
374 | GST_API |
375 | gboolean gst_buffer_is_all_memory_writable (GstBuffer *buffer); |
376 | |
377 | GST_API |
378 | gsize gst_buffer_fill (GstBuffer *buffer, gsize offset, |
379 | gconstpointer src, gsize size); |
380 | GST_API |
381 | gsize (GstBuffer *buffer, gsize offset, |
382 | gpointer dest, gsize size); |
383 | GST_API |
384 | gint gst_buffer_memcmp (GstBuffer *buffer, gsize offset, |
385 | gconstpointer mem, gsize size); |
386 | GST_API |
387 | gsize gst_buffer_memset (GstBuffer *buffer, gsize offset, |
388 | guint8 val, gsize size); |
389 | GST_API |
390 | gsize gst_buffer_get_sizes_range (GstBuffer *buffer, guint idx, gint length, |
391 | gsize *offset, gsize *maxsize); |
392 | GST_API |
393 | gboolean gst_buffer_resize_range (GstBuffer *buffer, guint idx, gint length, |
394 | gssize offset, gssize size); |
395 | GST_API |
396 | gsize gst_buffer_get_sizes (GstBuffer *buffer, gsize *offset, gsize *maxsize); |
397 | |
398 | GST_API |
399 | gsize gst_buffer_get_size (GstBuffer *buffer); |
400 | |
401 | GST_API |
402 | void gst_buffer_resize (GstBuffer *buffer, gssize offset, gssize size); |
403 | |
404 | GST_API |
405 | void gst_buffer_set_size (GstBuffer *buffer, gssize size); |
406 | |
407 | GST_API |
408 | gboolean gst_buffer_map_range (GstBuffer *buffer, guint idx, gint length, |
409 | GstMapInfo *info, GstMapFlags flags); |
410 | GST_API |
411 | gboolean gst_buffer_map (GstBuffer *buffer, GstMapInfo *info, GstMapFlags flags); |
412 | |
413 | GST_API |
414 | void gst_buffer_unmap (GstBuffer *buffer, GstMapInfo *info); |
415 | |
416 | GST_API |
417 | void (GstBuffer *buffer, gsize offset, |
418 | gsize size, gpointer *dest, |
419 | gsize *dest_size); |
420 | GST_API |
421 | GstBufferFlags gst_buffer_get_flags (GstBuffer * buffer); |
422 | |
423 | GST_API |
424 | gboolean gst_buffer_has_flags (GstBuffer * buffer, GstBufferFlags flags); |
425 | |
426 | GST_API |
427 | gboolean gst_buffer_set_flags (GstBuffer * buffer, GstBufferFlags flags); |
428 | |
429 | GST_API |
430 | gboolean gst_buffer_unset_flags (GstBuffer * buffer, GstBufferFlags flags); |
431 | |
432 | |
433 | #ifndef GST_DISABLE_MINIOBJECT_INLINE_FUNCTIONS |
434 | /* refcounting */ |
435 | static inline GstBuffer * |
436 | gst_buffer_ref (GstBuffer * buf) |
437 | { |
438 | return (GstBuffer *) gst_mini_object_ref (GST_MINI_OBJECT_CAST (buf)); |
439 | } |
440 | |
441 | static inline void |
442 | gst_buffer_unref (GstBuffer * buf) |
443 | { |
444 | gst_mini_object_unref (GST_MINI_OBJECT_CAST (buf)); |
445 | } |
446 | |
447 | static inline void |
448 | gst_clear_buffer (GstBuffer ** buf_ptr) |
449 | { |
450 | gst_clear_mini_object ((GstMiniObject **) buf_ptr); |
451 | } |
452 | |
453 | /* copy buffer */ |
454 | static inline GstBuffer * |
455 | gst_buffer_copy (const GstBuffer * buf) |
456 | { |
457 | return GST_BUFFER (gst_mini_object_copy (GST_MINI_OBJECT_CONST_CAST (buf))); |
458 | } |
459 | #else /* GST_DISABLE_MINIOBJECT_INLINE_FUNCTIONS */ |
460 | GST_API |
461 | GstBuffer * gst_buffer_ref (GstBuffer * buf); |
462 | |
463 | GST_API |
464 | void gst_buffer_unref (GstBuffer * buf); |
465 | |
466 | GST_API |
467 | void gst_clear_buffer (GstBuffer ** buf_ptr); |
468 | |
469 | GST_API |
470 | GstBuffer * gst_buffer_copy (const GstBuffer * buf); |
471 | #endif /* GST_DISABLE_MINIOBJECT_INLINE_FUNCTIONS */ |
472 | |
473 | GST_API |
474 | GstBuffer * gst_buffer_copy_deep (const GstBuffer * buf); |
475 | |
476 | /** |
477 | * GstBufferCopyFlags: |
478 | * @GST_BUFFER_COPY_NONE: copy nothing |
479 | * @GST_BUFFER_COPY_FLAGS: flag indicating that buffer flags should be copied |
480 | * @GST_BUFFER_COPY_TIMESTAMPS: flag indicating that buffer pts, dts, |
481 | * duration, offset and offset_end should be copied |
482 | * @GST_BUFFER_COPY_MEMORY: flag indicating that buffer memory should be reffed |
483 | * and appended to already existing memory. Unless the memory is marked as |
484 | * NO_SHARE, no actual copy of the memory is made but it is simply reffed. |
485 | * Add @GST_BUFFER_COPY_DEEP to force a real copy. |
486 | * @GST_BUFFER_COPY_MERGE: flag indicating that buffer memory should be |
487 | * merged |
488 | * @GST_BUFFER_COPY_META: flag indicating that buffer meta should be |
489 | * copied |
490 | * |
491 | * A set of flags that can be provided to the gst_buffer_copy_into() |
492 | * function to specify which items should be copied. |
493 | */ |
494 | typedef enum { |
495 | GST_BUFFER_COPY_NONE = 0, |
496 | GST_BUFFER_COPY_FLAGS = (1 << 0), |
497 | GST_BUFFER_COPY_TIMESTAMPS = (1 << 1), |
498 | GST_BUFFER_COPY_META = (1 << 2), |
499 | GST_BUFFER_COPY_MEMORY = (1 << 3), |
500 | GST_BUFFER_COPY_MERGE = (1 << 4), |
501 | |
502 | /** |
503 | * GST_BUFFER_COPY_DEEP: |
504 | * |
505 | * flag indicating that memory should always be copied instead of reffed |
506 | * |
507 | * Since: 1.2 |
508 | */ |
509 | GST_BUFFER_COPY_DEEP = (1 << 5) |
510 | } GstBufferCopyFlags; |
511 | |
512 | /** |
513 | * GST_BUFFER_COPY_METADATA: (value 7) (type GstBufferCopyFlags) |
514 | * |
515 | * Combination of all possible metadata fields that can be copied with |
516 | * gst_buffer_copy_into(). |
517 | */ |
518 | #define GST_BUFFER_COPY_METADATA ((GstBufferCopyFlags) (GST_BUFFER_COPY_FLAGS |\ |
519 | GST_BUFFER_COPY_TIMESTAMPS | GST_BUFFER_COPY_META)) |
520 | |
521 | /** |
522 | * GST_BUFFER_COPY_ALL: (value 15) (type GstBufferCopyFlags) |
523 | * |
524 | * Combination of all possible fields that can be copied with |
525 | * gst_buffer_copy_into(). |
526 | */ |
527 | #define GST_BUFFER_COPY_ALL ((GstBufferCopyFlags)(GST_BUFFER_COPY_METADATA | GST_BUFFER_COPY_MEMORY)) |
528 | |
529 | /* copies memory or metadata into newly allocated buffer */ |
530 | |
531 | GST_API |
532 | gboolean gst_buffer_copy_into (GstBuffer *dest, GstBuffer *src, |
533 | GstBufferCopyFlags flags, |
534 | gsize offset, gsize size); |
535 | |
536 | /** |
537 | * gst_buffer_is_writable: |
538 | * @buf: a #GstBuffer |
539 | * |
540 | * Tests if you can safely write to a buffer's metadata or its memory array. |
541 | * It is only safe to change buffer metadata when the current reference is |
542 | * writable, i.e. nobody can see the modifications you will make. |
543 | */ |
544 | #define gst_buffer_is_writable(buf) gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (buf)) |
545 | /** |
546 | * gst_buffer_make_writable: |
547 | * @buf: (transfer full): a #GstBuffer |
548 | * |
549 | * Returns a writable copy of @buf. If the source buffer is |
550 | * already writable, this will simply return the same buffer. |
551 | * |
552 | * Use this function to ensure that a buffer can be safely modified before |
553 | * making changes to it, including changing the metadata such as PTS/DTS. |
554 | * |
555 | * If the reference count of the source buffer @buf is exactly one, the caller |
556 | * is the sole owner and this function will return the buffer object unchanged. |
557 | * |
558 | * If there is more than one reference on the object, a copy will be made using |
559 | * gst_buffer_copy(). The passed-in @buf will be unreffed in that case, and the |
560 | * caller will now own a reference to the new returned buffer object. Note |
561 | * that this just copies the buffer structure itself, the underlying memory is |
562 | * not copied if it can be shared amongst multiple buffers. |
563 | * |
564 | * In short, this function unrefs the buf in the argument and refs the buffer |
565 | * that it returns. Don't access the argument after calling this function unless |
566 | * you have an additional reference to it. |
567 | * |
568 | * Returns: (transfer full): a writable buffer which may or may not be the |
569 | * same as @buf |
570 | */ |
571 | #define gst_buffer_make_writable(buf) GST_BUFFER_CAST (gst_mini_object_make_writable (GST_MINI_OBJECT_CAST (buf))) |
572 | |
573 | #ifndef GST_DISABLE_MINIOBJECT_INLINE_FUNCTIONS |
574 | static inline gboolean |
575 | gst_buffer_replace (GstBuffer **obuf, GstBuffer *nbuf) |
576 | { |
577 | return gst_mini_object_replace (olddata: (GstMiniObject **) obuf, newdata: (GstMiniObject *) nbuf); |
578 | } |
579 | #else /* GST_DISABLE_MINIOBJECT_INLINE_FUNCTIONS */ |
580 | GST_API |
581 | gboolean gst_buffer_replace (GstBuffer ** obuf, |
582 | GstBuffer * nbuf); |
583 | #endif /* GST_DISABLE_MINIOBJECT_INLINE_FUNCTIONS */ |
584 | |
585 | /* creating a region */ |
586 | |
587 | GST_API |
588 | GstBuffer* gst_buffer_copy_region (GstBuffer *parent, GstBufferCopyFlags flags, |
589 | gsize offset, gsize size); |
590 | |
591 | /* append two buffers */ |
592 | |
593 | GST_API |
594 | GstBuffer* gst_buffer_append_region (GstBuffer *buf1, GstBuffer *buf2, |
595 | gssize offset, gssize size); |
596 | GST_API |
597 | GstBuffer* gst_buffer_append (GstBuffer *buf1, GstBuffer *buf2); |
598 | |
599 | /* metadata */ |
600 | #include <gst/gstmeta.h> |
601 | |
602 | /** |
603 | * GstBufferForeachMetaFunc: |
604 | * @buffer: a #GstBuffer |
605 | * @meta: (out) (nullable): a pointer to a #GstMeta |
606 | * @user_data: user data passed to gst_buffer_foreach_meta() |
607 | * |
608 | * A function that will be called from gst_buffer_foreach_meta(). The @meta |
609 | * field will point to a the reference of the meta. |
610 | * |
611 | * @buffer should not be modified from this callback. |
612 | * |
613 | * When this function returns %TRUE, the next meta will be |
614 | * returned. When %FALSE is returned, gst_buffer_foreach_meta() will return. |
615 | * |
616 | * When @meta is set to %NULL, the item will be removed from the buffer. |
617 | * |
618 | * Returns: %FALSE when gst_buffer_foreach_meta() should stop |
619 | */ |
620 | typedef gboolean (*GstBufferForeachMetaFunc) (GstBuffer *buffer, GstMeta **meta, |
621 | gpointer user_data); |
622 | |
623 | GST_API |
624 | GstMeta * gst_buffer_get_meta (GstBuffer *buffer, GType api); |
625 | |
626 | GST_API |
627 | guint gst_buffer_get_n_meta (GstBuffer *buffer, GType api_type); |
628 | |
629 | GST_API |
630 | GstMeta * gst_buffer_add_meta (GstBuffer *buffer, const GstMetaInfo *info, |
631 | gpointer params); |
632 | GST_API |
633 | gboolean gst_buffer_remove_meta (GstBuffer *buffer, GstMeta *meta); |
634 | |
635 | GST_API |
636 | GstMeta * gst_buffer_iterate_meta (GstBuffer *buffer, gpointer *state); |
637 | |
638 | GST_API |
639 | GstMeta * gst_buffer_iterate_meta_filtered (GstBuffer * buffer, |
640 | gpointer * state, |
641 | GType meta_api_type); |
642 | GST_API |
643 | gboolean gst_buffer_foreach_meta (GstBuffer *buffer, |
644 | GstBufferForeachMetaFunc func, |
645 | gpointer user_data); |
646 | |
647 | GST_API |
648 | GstCustomMeta * gst_buffer_add_custom_meta (GstBuffer *buffer, |
649 | const gchar *name); |
650 | |
651 | GST_API |
652 | GstCustomMeta * gst_buffer_get_custom_meta (GstBuffer *buffer, |
653 | const gchar *name); |
654 | |
655 | /** |
656 | * gst_value_set_buffer: |
657 | * @v: a #GValue to receive the data |
658 | * @b: (transfer none): a #GstBuffer to assign to the GstValue |
659 | * |
660 | * Sets @b as the value of @v. Caller retains reference to buffer. |
661 | */ |
662 | #define gst_value_set_buffer(v,b) g_value_set_boxed((v),(b)) |
663 | /** |
664 | * gst_value_take_buffer: |
665 | * @v: a #GValue to receive the data |
666 | * @b: (transfer full): a #GstBuffer to assign to the GstValue |
667 | * |
668 | * Sets @b as the value of @v. Caller gives away reference to buffer. |
669 | */ |
670 | #define gst_value_take_buffer(v,b) g_value_take_boxed(v,(b)) |
671 | /** |
672 | * gst_value_get_buffer: |
673 | * @v: a #GValue to query |
674 | * |
675 | * Receives a #GstBuffer as the value of @v. Does not return a reference to |
676 | * the buffer, so the pointer is only valid for as long as the caller owns |
677 | * a reference to @v. |
678 | * |
679 | * Returns: (transfer none): buffer |
680 | */ |
681 | #define gst_value_get_buffer(v) GST_BUFFER_CAST (g_value_get_boxed(v)) |
682 | |
683 | typedef struct _GstParentBufferMeta GstParentBufferMeta; |
684 | |
685 | /** |
686 | * GstParentBufferMeta: |
687 | * @parent: the parent #GstMeta structure |
688 | * @buffer: the #GstBuffer on which a reference is being held. |
689 | * |
690 | * The #GstParentBufferMeta is a #GstMeta which can be attached to a #GstBuffer |
691 | * to hold a reference to another buffer that is only released when the child |
692 | * #GstBuffer is released. |
693 | * |
694 | * Typically, #GstParentBufferMeta is used when the child buffer is directly |
695 | * using the #GstMemory of the parent buffer, and wants to prevent the parent |
696 | * buffer from being returned to a buffer pool until the #GstMemory is available |
697 | * for re-use. |
698 | * |
699 | * Since: 1.6 |
700 | */ |
701 | struct _GstParentBufferMeta |
702 | { |
703 | GstMeta parent; |
704 | |
705 | /*< public >*/ |
706 | GstBuffer *buffer; |
707 | }; |
708 | |
709 | GST_API |
710 | GType gst_parent_buffer_meta_api_get_type (void); |
711 | #ifndef GST_DISABLE_DEPRECATED |
712 | #define GST_TYPE_PARENT_BUFFER_META_API_TYPE GST_PARENT_BUFFER_META_API_TYPE |
713 | #endif |
714 | #define GST_PARENT_BUFFER_META_API_TYPE (gst_parent_buffer_meta_api_get_type()) |
715 | |
716 | /** |
717 | * gst_buffer_get_parent_buffer_meta: |
718 | * @b: a #GstBuffer |
719 | * |
720 | * Finds and returns a #GstParentBufferMeta if one exists on the |
721 | * buffer |
722 | */ |
723 | #define gst_buffer_get_parent_buffer_meta(b) \ |
724 | ((GstParentBufferMeta*)gst_buffer_get_meta((b),GST_PARENT_BUFFER_META_API_TYPE)) |
725 | |
726 | GST_API |
727 | const GstMetaInfo *gst_parent_buffer_meta_get_info (void); |
728 | #define GST_PARENT_BUFFER_META_INFO (gst_parent_buffer_meta_get_info()) |
729 | |
730 | /* implementation */ |
731 | |
732 | GST_API |
733 | GstParentBufferMeta *gst_buffer_add_parent_buffer_meta (GstBuffer *buffer, |
734 | GstBuffer *ref); |
735 | |
736 | typedef struct _GstReferenceTimestampMeta GstReferenceTimestampMeta; |
737 | |
738 | /** |
739 | * GstReferenceTimestampMeta: |
740 | * @parent: the parent #GstMeta structure |
741 | * @reference: identifier for the timestamp reference. |
742 | * @timestamp: timestamp |
743 | * @duration: duration, or %GST_CLOCK_TIME_NONE |
744 | * |
745 | * #GstReferenceTimestampMeta can be used to attach alternative timestamps and |
746 | * possibly durations to a #GstBuffer. These are generally not according to |
747 | * the pipeline clock and could be e.g. the NTP timestamp when the media was |
748 | * captured. |
749 | * |
750 | * The reference is stored as a #GstCaps in @reference. Examples of valid |
751 | * references would be `timestamp/x-drivername-stream` for timestamps that are locally |
752 | * generated by some driver named `drivername` when generating the stream, |
753 | * e.g. based on a frame counter, or `timestamp/x-ntp, host=pool.ntp.org, |
754 | * port=123` for timestamps based on a specific NTP server. |
755 | * |
756 | * Since: 1.14 |
757 | */ |
758 | struct _GstReferenceTimestampMeta |
759 | { |
760 | GstMeta parent; |
761 | |
762 | /*< public >*/ |
763 | GstCaps *reference; |
764 | GstClockTime timestamp, duration; |
765 | }; |
766 | |
767 | GST_API |
768 | GType gst_reference_timestamp_meta_api_get_type (void); |
769 | #define GST_REFERENCE_TIMESTAMP_META_API_TYPE (gst_reference_timestamp_meta_api_get_type()) |
770 | |
771 | GST_API |
772 | const GstMetaInfo *gst_reference_timestamp_meta_get_info (void); |
773 | #define GST_REFERENCE_TIMESTAMP_META_INFO (gst_reference_timestamp_meta_get_info()) |
774 | |
775 | /* implementation */ |
776 | |
777 | GST_API |
778 | GstReferenceTimestampMeta * gst_buffer_add_reference_timestamp_meta (GstBuffer * buffer, |
779 | GstCaps * reference, |
780 | GstClockTime timestamp, |
781 | GstClockTime duration); |
782 | |
783 | GST_API |
784 | GstReferenceTimestampMeta * gst_buffer_get_reference_timestamp_meta (GstBuffer * buffer, |
785 | GstCaps * reference); |
786 | |
787 | G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstBuffer, gst_buffer_unref) |
788 | |
789 | G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstBufferPool, gst_object_unref) |
790 | |
791 | G_END_DECLS |
792 | |
793 | #endif /* __GST_BUFFER_H__ */ |
794 | |