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., 59 Temple Place - Suite 330,

    20  * Boston, MA 02111-1307, 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/gstcaps.h>

    30 

    31 G_BEGIN_DECLS

    32 

    33 typedef struct _GstBuffer GstBuffer;

    34 typedef struct _GstBufferClass GstBufferClass;

    35 

    36 /**

    37  * GST_BUFFER_TRACE_NAME:

    38  *

    39  * The name used for tracing memory allocations.

    40  */

    41 #define GST_BUFFER_TRACE_NAME		"GstBuffer"

    42 

    43 #define GST_TYPE_BUFFER				(gst_buffer_get_type())

    44 #define GST_IS_BUFFER(obj)                      (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GST_TYPE_BUFFER))

    45 #define GST_IS_BUFFER_CLASS(klass)              (G_TYPE_CHECK_CLASS_TYPE ((klass), GST_TYPE_BUFFER))

    46 #define GST_BUFFER_GET_CLASS(obj)               (G_TYPE_INSTANCE_GET_CLASS ((obj), GST_TYPE_BUFFER, GstBufferClass))

    47 #define GST_BUFFER(obj)                         (G_TYPE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_BUFFER, GstBuffer))

    48 #define GST_BUFFER_CLASS(klass)                 (G_TYPE_CHECK_CLASS_CAST ((klass), GST_TYPE_BUFFER, GstBufferClass))

    49 #define GST_BUFFER_CAST(obj)                    ((GstBuffer *)(obj))

    50 

    51 /**

    52  * GST_BUFFER_FLAGS:

    53  * @buf: a #GstBuffer.

    54  *

    55  * A flags word containing #GstBufferFlag flags set on this buffer.

    56  */

    57 #define GST_BUFFER_FLAGS(buf)                   GST_MINI_OBJECT_FLAGS(buf)

    58 /**

    59  * GST_BUFFER_FLAG_IS_SET:

    60  * @buf: a #GstBuffer.

    61  * @flag: the #GstBufferFlag to check.

    62  *

    63  * Gives the status of a specific flag on a buffer.

    64  */

    65 #define GST_BUFFER_FLAG_IS_SET(buf,flag)        GST_MINI_OBJECT_FLAG_IS_SET (buf, flag)

    66 /**

    67  * GST_BUFFER_FLAG_SET:

    68  * @buf: a #GstBuffer.

    69  * @flag: the #GstBufferFlag to set.

    70  *

    71  * Sets a buffer flag on a buffer.

    72  */

    73 #define GST_BUFFER_FLAG_SET(buf,flag)           GST_MINI_OBJECT_FLAG_SET (buf, flag)

    74 /**

    75  * GST_BUFFER_FLAG_UNSET:

    76  * @buf: a #GstBuffer.

    77  * @flag: the #GstBufferFlag to clear.

    78  *

    79  * Clears a buffer flag.

    80  */

    81 #define GST_BUFFER_FLAG_UNSET(buf,flag)         GST_MINI_OBJECT_FLAG_UNSET (buf, flag)

    82 

    83 /**

    84  * GST_BUFFER_DATA:

    85  * @buf: a #GstBuffer.

    86  *

    87  * A pointer to the data element of this buffer.

    88  */

    89 #define GST_BUFFER_DATA(buf)			(GST_BUFFER_CAST(buf)->data)

    90 /**

    91  * GST_BUFFER_SIZE:

    92  * @buf: a #GstBuffer.

    93  *

    94  * The size in bytes of the data in this buffer.

    95  */

    96 #define GST_BUFFER_SIZE(buf)			(GST_BUFFER_CAST(buf)->size)

    97 /**

    98  * GST_BUFFER_TIMESTAMP:

    99  * @buf: a #GstBuffer.:

   100  *

   101  * The timestamp in nanoseconds (as a #GstClockTime) of the data in the buffer.

   102  * Value will be %GST_CLOCK_TIME_NONE if the timestamp is unknown.

   103  *

   104  */

   105 #define GST_BUFFER_TIMESTAMP(buf)		(GST_BUFFER_CAST(buf)->timestamp)

   106 /**

   107  * GST_BUFFER_DURATION:

   108  * @buf: a #GstBuffer.

   109  *

   110  * The duration in nanoseconds (as a #GstClockTime) of the data in the buffer.

   111  * Value will be %GST_CLOCK_TIME_NONE if the duration is unknown.

   112  */

   113 #define GST_BUFFER_DURATION(buf)		(GST_BUFFER_CAST(buf)->duration)

   114 /**

   115  * GST_BUFFER_CAPS:

   116  * @buf: a #GstBuffer.

   117  *

   118  * The caps for this buffer.

   119  */

   120 #define GST_BUFFER_CAPS(buf)			(GST_BUFFER_CAST(buf)->caps)

   121 /**

   122  * GST_BUFFER_OFFSET:

   123  * @buf: a #GstBuffer.

   124  *

   125  * The offset in the source file of the beginning of this buffer.

   126  */

   127 #define GST_BUFFER_OFFSET(buf)			(GST_BUFFER_CAST(buf)->offset)

   128 /**

   129  * GST_BUFFER_OFFSET_END:

   130  * @buf: a #GstBuffer.

   131  *

   132  * The offset in the source file of the end of this buffer.

   133  */

   134 #define GST_BUFFER_OFFSET_END(buf)		(GST_BUFFER_CAST(buf)->offset_end)

   135 /**

   136  * GST_BUFFER_MALLOCDATA:

   137  * @buf: a #GstBuffer.

   138  *

   139  * A pointer to any data allocated for this buffer using g_malloc(). If this is 

   140  * non-NULL, this memory will be freed at the end of the buffer's lifecycle 

   141  * (i.e. when its refcount becomes zero).

   142  */

   143 #define GST_BUFFER_MALLOCDATA(buf)		(GST_BUFFER_CAST(buf)->malloc_data)

   144 

   145 /**

   146  * GST_BUFFER_OFFSET_NONE:

   147  *

   148  * Constant for no-offset return results.

   149  */

   150 #define GST_BUFFER_OFFSET_NONE	((guint64)-1)

   151 

   152 /**

   153  * GST_BUFFER_DURATION_IS_VALID:

   154  * @buffer: a #GstBuffer

   155  *

   156  * Tests if the duration is known.

   157  */

   158 #define GST_BUFFER_DURATION_IS_VALID(buffer)	(GST_CLOCK_TIME_IS_VALID (GST_BUFFER_DURATION (buffer)))

   159 /**

   160  * GST_BUFFER_TIMESTAMP_IS_VALID:

   161  * @buffer: a #GstBuffer

   162  *

   163  * Tests if the timestamp is known.

   164  */

   165 #define GST_BUFFER_TIMESTAMP_IS_VALID(buffer)	(GST_CLOCK_TIME_IS_VALID (GST_BUFFER_TIMESTAMP (buffer)))

   166 /**

   167  * GST_BUFFER_OFFSET_IS_VALID:

   168  * @buffer: a #GstBuffer

   169  *

   170  * Tests if the start offset is known.

   171  */

   172 #define GST_BUFFER_OFFSET_IS_VALID(buffer)	(GST_BUFFER_OFFSET (buffer) != GST_BUFFER_OFFSET_NONE)

   173 /**

   174  * GST_BUFFER_OFFSET_END_IS_VALID:

   175  * @buffer: a #GstBuffer

   176  *

   177  * Tests if the end offset is known.

   178  */

   179 #define GST_BUFFER_OFFSET_END_IS_VALID(buffer)	(GST_BUFFER_OFFSET_END (buffer) != GST_BUFFER_OFFSET_NONE)

   180 /**

   181  * GST_BUFFER_IS_DISCONT:

   182  * @buffer: a #GstBuffer

   183  *

   184  * Tests if the buffer marks a discontinuity in the stream.

   185  *

   186  * Since: 0.10.9

   187  */

   188 #define GST_BUFFER_IS_DISCONT(buffer)	(GST_BUFFER_FLAG_IS_SET (buffer, GST_BUFFER_FLAG_DISCONT))

   189 

   190 /**

   191  * GstBufferFlag:

   192  * @GST_BUFFER_FLAG_READONLY: the buffer is read-only. This means the data of

   193  * the buffer should not be modified. The metadata might still be modified.

   194  * @GST_BUFFER_FLAG_PREROLL: the buffer is part of a preroll and should not be

   195  * displayed.

   196  * @GST_BUFFER_FLAG_DISCONT: the buffer marks a discontinuity in the stream.

   197  * This typically occurs after a seek or a dropped buffer from a live or

   198  * network source.

   199  * @GST_BUFFER_FLAG_IN_CAPS: the buffer has been added as a field in a #GstCaps.

   200  * @GST_BUFFER_FLAG_GAP: the buffer has been created to fill a gap in the

   201  * stream and contains media neutral data (elements can switch to optimized code

   202  * path that ignores the buffer content).

   203  * @GST_BUFFER_FLAG_DELTA_UNIT: this unit cannot be decoded independently.

   204  * @GST_BUFFER_FLAG_LAST: additional flags can be added starting from this flag.

   205  *

   206  * A set of buffer flags used to describe properties of a #GstBuffer.

   207  */

   208 typedef enum {

   209   GST_BUFFER_FLAG_READONLY   = GST_MINI_OBJECT_FLAG_READONLY,

   210   GST_BUFFER_FLAG_PREROLL    = (GST_MINI_OBJECT_FLAG_LAST << 0),

   211   GST_BUFFER_FLAG_DISCONT    = (GST_MINI_OBJECT_FLAG_LAST << 1),

   212   GST_BUFFER_FLAG_IN_CAPS    = (GST_MINI_OBJECT_FLAG_LAST << 2),

   213   GST_BUFFER_FLAG_GAP        = (GST_MINI_OBJECT_FLAG_LAST << 3),

   214   GST_BUFFER_FLAG_DELTA_UNIT = (GST_MINI_OBJECT_FLAG_LAST << 4),

   215   /* padding */

   216   GST_BUFFER_FLAG_LAST       = (GST_MINI_OBJECT_FLAG_LAST << 8)

   217 } GstBufferFlag;

   218 

   219 /**

   220  * GstBuffer:

   221  * @mini_object: the parent structure

   222  * @data: pointer to the buffer data

   223  * @size: size of buffer data

   224  * @timestamp: timestamp of the buffer, can be #GST_CLOCK_TIME_NONE when the

   225  *     timestamp is not known or relevant.

   226  * @duration: duration in time of the buffer data, can be #GST_CLOCK_TIME_NONE

   227  *     when the duration is not known or relevant.

   228  * @caps: the #GstCaps describing the data format in this buffer

   229  * @offset: a media specific offset for the buffer data. 

   230  *     For video frames, this is the frame number of this buffer.

   231  *     For audio samples, this is the offset of the first sample in this buffer.

   232  *     For file data or compressed data this is the byte offset of the first

   233  *       byte in this buffer.

   234  * @offset_end: the last offset contained in this buffer. It has the same 

   235  *     format as @offset.

   236  * @malloc_data: a pointer to the allocated memory associated with this buffer.

   237  *     When the buffer is freed, this data will freed with g_free().

   238  *

   239  * The structure of a #GstBuffer. Use the associated macros to access the public

   240  * variables.

   241  */

   242 struct _GstBuffer {

   243   GstMiniObject		 mini_object;

   244 

   245   /*< public >*/ /* with COW */

   246   /* pointer to data and its size */

   247   guint8		*data;

   248   guint			 size;

   249 

   250   /* timestamp */

   251   GstClockTime		 timestamp;

   252   GstClockTime		 duration;

   253 

   254   /* the media type of this buffer */

   255   GstCaps		*caps;

   256 

   257   /* media specific offset */

   258   guint64		 offset;

   259   guint64		 offset_end;

   260 

   261   guint8                *malloc_data;

   262 

   263   /*< private >*/

   264   gpointer _gst_reserved[GST_PADDING];

   265 };

   266 

   267 struct _GstBufferClass {

   268   GstMiniObjectClass    mini_object_class;

   269 };

   270 #ifdef __SYMBIAN32__

   271 IMPORT_C

   272 #endif

   273 

   274 

   275 GType       gst_buffer_get_type (void);

   276 

   277 /* allocation */

   278 #ifdef __SYMBIAN32__

   279 IMPORT_C

   280 #endif

   281 

   282 GstBuffer * gst_buffer_new               (void);

   283 #ifdef __SYMBIAN32__

   284 IMPORT_C

   285 #endif

   286 

   287 GstBuffer * gst_buffer_new_and_alloc     (guint size);

   288 #ifdef __SYMBIAN32__

   289 IMPORT_C

   290 #endif

   291 

   292 GstBuffer * gst_buffer_try_new_and_alloc (guint size);

   293 

   294 /**

   295  * gst_buffer_set_data:

   296  * @buf: a #GstBuffer

   297  * @data: The data (a #guint8 *) to set on the buffer.

   298  * @size: The size (in bytes, as a #guint) of the data being set.

   299  *

   300  * A convenience function to set the data and size on a buffer.

   301  * This will replace any existing data pointer set on this buffer, but will

   302  * not change GST_BUFFER_MALLOCDATA(), if any. Callers should ensure that

   303  * GST_BUFFER_MALLOCDATA() is non-NULL, or should free that and set it to NULL.

   304  *

   305  * No checks are done on the data or size arguments passed.

   306  */

   307 #define		gst_buffer_set_data(buf, data, size)	\

   308 G_STMT_START {						\

   309   GST_BUFFER_DATA (buf) = data;				\

   310   GST_BUFFER_SIZE (buf) = size;				\

   311 } G_STMT_END

   312 

   313 /* refcounting */

   314 /**

   315  * gst_buffer_ref:

   316  * @buf: a #GstBuffer.

   317  *

   318  * Increases the refcount of the given buffer by one.

   319  *

   320  * Note that the refcount affects the writeability

   321  * of @buf and its metadata, see gst_buffer_is_writable() and

   322  * gst_buffer_is_metadata_writable(). It is

   323  * important to note that keeping additional references to

   324  * GstBuffer instances can potentially increase the number

   325  * of memcpy operations in a pipeline.

   326  *

   327  * Returns: @buf

   328  */

   329 #ifdef _FOOL_GTK_DOC_

   330 G_INLINE_FUNC GstBuffer * gst_buffer_ref (GstBuffer * buf);

   331 #endif

   332 

   333 static inline GstBuffer *

   334 gst_buffer_ref (GstBuffer * buf)

   335 {

   336   /* not using a macro here because gcc-4.1 will complain

   337    * if the return value isn't used (because of the cast) */

   338   return (GstBuffer *) gst_mini_object_ref (GST_MINI_OBJECT_CAST (buf));

   339 }

   340 

   341 /**

   342  * gst_buffer_unref:

   343  * @buf: a #GstBuffer.

   344  *

   345  * Decreases the refcount of the buffer. If the refcount reaches 0, the buffer

   346  * will be freed. If GST_BUFFER_MALLOCDATA() is non-NULL, this pointer will

   347  * also be freed at this time.

   348  */

   349 #define		gst_buffer_unref(buf)		gst_mini_object_unref (GST_MINI_OBJECT_CAST (buf))

   350 

   351 /* copy buffer */

   352 /**

   353  * gst_buffer_copy:

   354  * @buf: a #GstBuffer.

   355  *

   356  * Create a copy of the given buffer. This will also make a newly allocated

   357  * copy of the data the source buffer contains.

   358  */

   359 #define		gst_buffer_copy(buf)		GST_BUFFER_CAST (gst_mini_object_copy (GST_MINI_OBJECT_CAST (buf)))

   360 

   361 /**

   362  * GstBufferCopyFlags:

   363  * @GST_BUFFER_COPY_FLAGS: flag indicating that buffer flags should be copied

   364  * @GST_BUFFER_COPY_TIMESTAMPS: flag indicating that buffer timestamp, duration,

   365  * offset and offset_end should be copied

   366  * @GST_BUFFER_COPY_CAPS: flag indicating that buffer caps should be copied

   367  *

   368  * A set of flags that can be provided to the gst_buffer_copy_metadata()

   369  * function to specify which metadata fields should be copied.

   370  *

   371  * Since: 0.10.13

   372  */

   373 typedef enum {

   374   GST_BUFFER_COPY_FLAGS      = (1 << 0),

   375   GST_BUFFER_COPY_TIMESTAMPS = (1 << 1),

   376   GST_BUFFER_COPY_CAPS       = (1 << 2)

   377 } GstBufferCopyFlags;

   378 

   379 /**

   380  * GST_BUFFER_COPY_ALL:

   381  *

   382  * Combination of all possible fields that can be copied with

   383  * gst_buffer_copy_metadata().

   384  *

   385  * Since: 0.10.13

   386  */

   387 #define GST_BUFFER_COPY_ALL (GST_BUFFER_COPY_FLAGS | GST_BUFFER_COPY_TIMESTAMPS | GST_BUFFER_COPY_CAPS)

   388 

   389 /* copies metadata into newly allocated buffer */

   390 #ifdef __SYMBIAN32__

   391 IMPORT_C

   392 #endif

   393 

   394 void            gst_buffer_copy_metadata        (GstBuffer *dest, const GstBuffer *src,

   395                                                  GstBufferCopyFlags flags);

   396 

   397 /**

   398  * gst_buffer_is_writable:

   399  * @buf: a #GstBuffer

   400  *

   401  * Tests if you can safely write data into a buffer's data array or validly

   402  * modify the caps and timestamp metadata. Metadata in a GstBuffer is always

   403  * writable, but it is only safe to change it when there is only one owner

   404  * of the buffer - ie, the refcount is 1. 

   405  */

   406 #define		gst_buffer_is_writable(buf)	gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (buf))

   407 /**

   408  * gst_buffer_make_writable:

   409  * @buf: a #GstBuffer

   410  *

   411  * Makes a writable buffer from the given buffer. If the source buffer is

   412  * already writable, this will simply return the same buffer. A copy will 

   413  * otherwise be made using gst_buffer_copy().

   414  */

   415 #define		gst_buffer_make_writable(buf)   GST_BUFFER_CAST (gst_mini_object_make_writable (GST_MINI_OBJECT_CAST (buf)))

   416 

   417 /* Ensure that the metadata of the buffer is writable, even if the buffer data

   418  * isn't */

   419 #ifdef __SYMBIAN32__

   420 IMPORT_C

   421 #endif

   422 

   423 gboolean        gst_buffer_is_metadata_writable (GstBuffer *buf);

   424 #ifdef __SYMBIAN32__

   425 IMPORT_C

   426 #endif

   427 

   428 GstBuffer*      gst_buffer_make_metadata_writable (GstBuffer *buf);

   429 

   430 /**

   431  * gst_buffer_replace:

   432  * @obuf: pointer to a pointer to a #GstBuffer to be replaced.

   433  * @nbuf: pointer to a #GstBuffer that will replace the buffer pointed to by 

   434  *        @obuf.

   435  *

   436  * Modifies a pointer to a #Gstbuffer to point to a different #GstBuffer. The

   437  * modification is done atomically (so this is useful for ensuring thread safety

   438  * in some cases), and the reference counts are updated appropriately (the old 

   439  * buffer is unreffed, the new is reffed).

   440  *

   441  * Either @nbuf or the #GstBuffer pointed to by @obuf may be NULL.

   442  */

   443 #define		gst_buffer_replace(obuf,nbuf) \

   444 G_STMT_START {						                      \

   445   GstBuffer **___obufaddr = (GstBuffer **)(obuf);         \

   446   gst_mini_object_replace ((GstMiniObject **)___obufaddr, \

   447       GST_MINI_OBJECT_CAST (nbuf));                       \

   448 } G_STMT_END

   449 #ifdef __SYMBIAN32__

   450 IMPORT_C

   451 #endif

   452 

   453 

   454 GstCaps*	gst_buffer_get_caps		(GstBuffer *buffer);

   455 #ifdef __SYMBIAN32__

   456 IMPORT_C

   457 #endif

   458 

   459 void		gst_buffer_set_caps		(GstBuffer *buffer, GstCaps *caps);

   460 

   461 /* creating a subbuffer */

   462 #ifdef __SYMBIAN32__

   463 IMPORT_C

   464 #endif

   465 

   466 GstBuffer*	gst_buffer_create_sub		(GstBuffer *parent, guint offset, guint size);

   467 

   468 /* span, two buffers, intelligently */

   469 #ifdef __SYMBIAN32__

   470 IMPORT_C

   471 #endif

   472 

   473 gboolean	gst_buffer_is_span_fast		(GstBuffer *buf1, GstBuffer *buf2);

   474 #ifdef __SYMBIAN32__

   475 IMPORT_C

   476 #endif

   477 

   478 GstBuffer*	gst_buffer_span			(GstBuffer *buf1, guint32 offset, GstBuffer *buf2, guint32 len);

   479 

   480 /**

   481  * gst_value_set_buffer:

   482  * @v: a #GstValue to receive the data

   483  * @b: a #GstBuffer to assign to the GstValue

   484  *

   485  * Sets @b as the value of @v.  Caller retains reference to buffer.

   486  */

   487 #define		gst_value_set_buffer(v,b)	gst_value_set_mini_object(v, GST_MINI_OBJECT_CAST(b))

   488 /**

   489  * gst_value_take_buffer:

   490  * @v: a #GstValue to receive the data

   491  * @b: a #GstBuffer to assign to the GstValue

   492  *

   493  * Sets @b as the value of @v.  Caller gives away reference to buffer.

   494  */

   495 #define		gst_value_take_buffer(v,b)	gst_value_take_mini_object(v, GST_MINI_OBJECT_CAST(b))

   496 /**

   497  * gst_value_get_buffer:

   498  * @v: a #GstValue to qeury

   499  *

   500  * Receives a #GstBuffer as the value of @v. Does not return a reference to

   501  * the buffer, so the pointer is only valid for as long as the caller owns

   502  * a reference to @v.

   503  */

   504 #define		gst_value_get_buffer(v)		GST_BUFFER_CAST (gst_value_get_mini_object(v))

   505 

   506 G_END_DECLS

   507 

   508 #endif /* __GST_BUFFER_H__ */