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_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_needs_copy_on_write    (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 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


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

gboolean    gst_data_needs_copy_on_write    (GstData *data);

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

data :

a GstData to copy

Returns :

TRUE 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_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 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

See Also

GstBuffer, GstBufferPool, GstEvent