GstData

GstData — Abstract structure for information that is passed among elements

Synopsis


#include <gst/gst.h>


#define     GST_DATA                        (data)
#define     GST_DATA_TYPE                   (data)
#define     GST_DATA_FLAGS                  (data)
#define     GST_DATA_FLAG_SHIFT             (flag)
#define     GST_DATA_FLAG_UNSET             (data,flag)
struct      GstData;
void        (*GstDataFreeFunction)          (GstData *data);
GstData*    (*GstDataCopyFunction)          (const GstData *data);
enum        GstDataFlags;
#define     GST_DATA_REFCOUNT               (data)
#define     GST_DATA_REFCOUNT_VALUE         (data)
#define     GST_DATA_COPY_FUNC              (data)
#define     GST_DATA_FREE_FUNC              (data)
void        gst_data_init                   (GstData *data,
                                             GType type,
                                             guint16 flags,
                                             GstDataFreeFunction free,
                                             GstDataCopyFunction copy);
void        gst_data_dispose                (GstData *data);
void        gst_data_copy_into              (const GstData *data,
                                             GstData *target);
GstData*    gst_data_copy                   (const GstData *data);
gboolean    gst_data_is_writable            (GstData *data);
GstData*    gst_data_copy_on_write          (GstData *data);
GstData*    gst_data_ref                    (GstData *data);
GstData*    gst_data_ref_by_count           (GstData *data,
                                             gint count);
void        gst_data_unref                  (GstData *data);

Description

This abstract structure provides a common base for GstBuffer, GstBufferPool and GstEvent. It is the main data type that is passed along in a pipeline. GstData provides refcounting, freeing and copying for its child classes.

Details

GST_DATA()

#define GST_DATA(data)		((GstData*)(data))

Cast a pointer to a GstData

data : The pointer to cast

GST_DATA_TYPE()

#define GST_DATA_TYPE(data)	(GST_DATA(data)->type)

Get the type of the GstData

data : The data to get the type of

GST_DATA_FLAGS()

#define GST_DATA_FLAGS(data)		(GST_DATA(data)->flags)

Get the flags of this GstData

data : The data to get the flags of

GST_DATA_FLAG_SHIFT()

#define GST_DATA_FLAG_SHIFT(flag)	(1<<(flag))

Shift a given flag so that it can be used in an or operation

flag : The flag to shift

GST_DATA_FLAG_UNSET()

#define GST_DATA_FLAG_UNSET(data,flag) 	G_STMT_START{ (GST_DATA_FLAGS(data) &= ~(1<<(flag))); }G_STMT_END

Unset the given flag

`data` :	The data to unset the flag of
`flag` :	The flag to unset

struct GstData

struct GstData {

  GType 		 type;

  /* refcounting */
  GstAtomicInt		 refcount;

  guint16		 flags;
 
  /* utility function pointers, can override default */
  GstDataFreeFunction 	 free;		/* free the data */
  GstDataCopyFunction 	 copy;		/* copy the data */

  gpointer _gst_reserved[GST_PADDING];
};

The base structure

GType `type`	The type of this data.
GstAtomicInt `refcount`	A refcount
guint16 `flags`	The flags of this GstData
GstDataFreeFunction `free`	A pointer to a custom free function
GstDataCopyFunction `copy`	A pointer to a custom copy function
gpointer `_gst_reserved`[GST_PADDING]	for future extensions

GstDataFreeFunction ()

void        (*GstDataFreeFunction)          (GstData *data);

The signature of the free function. Subclasses should provide a free function with this signature and pass it in the gst_data_init() function.

data : The GstData to free

GstDataCopyFunction ()

GstData*    (*GstDataCopyFunction)          (const GstData *data);

The signature of the copy function. Subclasses should provide a copy function with this signature and pass it in the gst_data_init() function.

`data` :	The GstData to copy
Returns :	A new GstData that is a copy of data

enum GstDataFlags

typedef enum
{
  GST_DATA_READONLY 	= 1,

  /* insert more */
  GST_DATA_FLAG_LAST 	= 8
} GstDataFlags;

Various flags that can be set on a GstData

`GST_DATA_READONLY`	The data is readonly
`GST_DATA_FLAG_LAST`	Subclasses can add additional flags starting from this offset

GST_DATA_REFCOUNT()

#define GST_DATA_REFCOUNT(data)			((GST_DATA(data))->refcount)

Get access to the refcount field of the GstData

data : The GstData to get the refcount field of

GST_DATA_REFCOUNT_VALUE()

#define GST_DATA_REFCOUNT_VALUE(data)		(gst_atomic_int_read (&(GST_DATA(data))->refcount))

Get the current refcount value

data : The GstData to query

GST_DATA_COPY_FUNC()

#define GST_DATA_COPY_FUNC(data) 		(GST_DATA(data)->copy)

Get access to the copy function of the data

data : The data to query

GST_DATA_FREE_FUNC()

#define GST_DATA_FREE_FUNC(data) 		(GST_DATA(data)->free)

Get access to the free function of the data

data : The data to query

gst_data_init ()

void        gst_data_init                   (GstData *data,
                                             GType type,
                                             guint16 flags,
                                             GstDataFreeFunction free,
                                             GstDataCopyFunction copy);

Initialize the given data structure with the given parameters. The free and copy function will be called when this data is freed or copied respectively.

`data` :	a GstData to initialize
`type` :	the type of this data
`flags` :	flags for this data
`free` :	a free function
`copy` :	a copy function

gst_data_dispose ()

void        gst_data_dispose                (GstData *data);

Free all the resources allocated in the gst_data_init() function, mainly used by subclass implementors.

data : a GstData to dispose

gst_data_copy_into ()

void        gst_data_copy_into              (const GstData *data,
                                             GstData *target);

Copy the GstData into the specified target GstData structure. Thos method is mainly used by subclasses when they want to copy the relevant GstData info.

`data` :	a GstData to copy
`target` :	the target GstData to copy into

gst_data_copy ()

GstData*    gst_data_copy                   (const GstData *data);

Copies the given GstData. This function will call the custom subclass copy function or return NULL if no function was provided by the subclass.

`data` :	a GstData to copy
Returns :	a copy of the data or NULL if the data cannot be copied. The refcount of the original buffer is not changed so you should unref it when you don't need it anymore.

gst_data_is_writable ()

gboolean    gst_data_is_writable            (GstData *data);

Query if the gstdata needs to be copied before it can safely be modified.

`data` :	a GstData to copy
Returns :	FALSE if the given GstData is potentially shared and needs to be copied before it can be modified safely.

gst_data_copy_on_write ()

GstData*    gst_data_copy_on_write          (GstData *data);

Copies the given GstData if the refcount is greater than 1 so that the GstData object can be written to safely.

`data` :	a GstData to copy
Returns :	a copy of the data if the refcount is > 1 or the buffer is marked READONLY, data if the refcount == 1, or NULL if the data could not be copied. The refcount of the original buffer is decreased when a copy is made, so you are not supposed to use it after a call to this function.

gst_data_ref ()

GstData*    gst_data_ref                    (GstData *data);

Increments the reference count of this data.

`data` :	a GstData to reference
Returns :	the data

gst_data_ref_by_count ()

GstData*    gst_data_ref_by_count           (GstData *data,
                                             gint count);

Increments the reference count of this data by the given number.

`data` :	a GstData to reference
`count` :	the number to increment the reference count by
Returns :	the data

gst_data_unref ()

void        gst_data_unref                  (GstData *data);

Decrements the refcount of this data. If the refcount is zero, the data will be freed.

When you add data to a pipeline, the pipeline takes ownership of the data. When the data has been used by some plugin, it must unref()s it. Applications usually don't need to unref() anything.

data : a GstData to unreference