GstData

Name

GstData -- Common structure for GstBuffer, GstBufferPool, and GstEvent

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_IS_SET            (data,flag)
#define     GST_DATA_FLAG_SET               (data,flag)
#define     GST_DATA_FLAG_UNSET             (data,flag)
struct      GstData;
void        (*GstDataFreeFunction)          (GstData *data);
GstData*    (*GstDataCopyFunction)          (const GstData *data);
enum        GstDataFlags;
#define     GST_DATA_IS_READONLY            (data)
#define     GST_DATA_REFCOUNT               (data)
#define     GST_DATA_REFCOUNT_VALUE         (data)
#define     GST_DATA_REFCOUNT_READ          (data,value)
#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);
GstData*    gst_data_copy_on_write          (GstData *data);
void        gst_data_free                   (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_IS_SET()

#define GST_DATA_FLAG_IS_SET(data,flag)	(GST_DATA_FLAGS(data) & (1<<(flag)))

Check if a given flag is set on the data

data :The data to check
flag :The flag to check for


GST_DATA_FLAG_SET()

#define GST_DATA_FLAG_SET(data,flag)	G_STMT_START{ (GST_DATA_FLAGS(data) |= (1<<(flag))); }G_STMT_END

Set the flag on the data

data :The data to set the flag on
flag :The flag to set


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 */
};

The base structure

GType typeThe type of this data.
GstAtomicInt refcountA refcount
guint16 flagsThe flags of this GstData
GstDataFreeFunction freeA pointer to a custom free function
GstDataCopyFunction copyA pointer to a custom copy function


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_READONLYThe data is readonly
GST_DATA_FLAG_LASTSubclasses can add additional flags starting from this offset


GST_DATA_IS_READONLY()

#define GST_DATA_IS_READONLY(data)		(GST_DATA_FLAG_IS_SET((data), GST_DATA_READONLY))

Query if the GstData is READONLY

data :The data to query


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_VALUE((&GST_DATA_REFCOUNT (data))))

Get the current refcount value

data :The GstData to query


GST_DATA_REFCOUNT_READ()

#define GST_DATA_REFCOUNT_READ(data,value)	(GST_ATOMIC_INT_READ(&(GST_DATA_REFCOUNT (data)),value)

Read the current refcount value into the specified value

data :The GstData to get the refcount value of
value :A pointer to a gint to hold the refcount value


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_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_free ()

void        gst_data_free                   (GstData *data);

Frees the given GstData. This function will call the custom free function provided by the subclass.

data : a GstData to free


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 freeed.

data : a GstData to unreference

See Also

GstBuffer, GstBufferPool, GstEvent