GstProps

GstProps — Properties

Synopsis


#include <gst/gst.h>


struct      GstProps;
enum        GstPropsType;
enum        GstPropsFlags;
#define     GST_PROPS_TRACE_NAME
#define     GST_PROPS_FLAGS                 (props)
#define     GST_PROPS_FLAG_IS_SET           (props,flag)
#define     GST_PROPS_FLAG_SET              (props,flag)
#define     GST_PROPS_FLAG_UNSET            (props,flag)
#define     GST_PROPS_IS_FIXED              (props)
#define     GST_PROPS_IS_FLOATING           (props)
#define     GST_PROPS_PROPERTIES            (props)
#define     GST_PROPS_REFCOUNT              (props)
#define     GST_TYPE_PROPS
#define     GST_MAKE_FOURCC                 (a,b,c,d)
#define     GST_STR_FOURCC                  (f)
#define     GST_PROPS_LIST                  (...)
#define     GST_PROPS_GLIST                 (a)
#define     GST_PROPS_INT                   (a)
#define     GST_PROPS_INT_ANY
#define     GST_PROPS_INT_RANGE             (a,b)
#define     GST_PROPS_INT_NEGATIVE
#define     GST_PROPS_FOURCC                (a)
#define     GST_PROPS_BOOLEAN               (a)
#define     GST_PROPS_STRING                (a)
#define     GST_PROPS_FLOAT                 (a)
#define     GST_PROPS_FLOAT_RANGE           (a,b)
#define     GST_PROPS_INT_POSITIVE
struct      GstPropsEntry;
#define     GST_PROPS_ENTRY_TRACE_NAME
GstProps*   gst_props_new                   (const gchar *firstname,
                                             ...);
GstProps*   gst_props_newv                  (const gchar *firstname,
                                             va_list var_args);
GstProps*   gst_props_empty_new             (void);
GstProps*   gst_props_merge                 (GstProps *props,
                                             GstProps *tomerge);
GstProps*   gst_props_copy                  (GstProps *props);
GstProps*   gst_props_copy_on_write         (GstProps *props);
GstProps*   gst_props_ref                   (GstProps *props);
GstProps*   gst_props_unref                 (GstProps *props);
void        gst_props_replace               (GstProps **oldprops,
                                             GstProps *newprops);
void        gst_props_replace_sink          (GstProps **oldprops,
                                             GstProps *newprops);
void        gst_props_sink                  (GstProps *props);
gboolean    gst_props_check_compatibility   (GstProps *fromprops,
                                             GstProps *toprops);
gboolean    gst_props_has_property          (GstProps *props,
                                             const gchar *name);
GList*      gst_props_normalize             (GstProps *props);
GstProps*   gst_props_set                   (GstProps *props,
                                             const gchar *name,
                                             ...);
gboolean    gst_props_get                   (GstProps *props,
                                             gchar *first_name,
                                             ...);
gboolean    gst_props_get_safe              (GstProps *props,
                                             gchar *first_name,
                                             ...);
gboolean    gst_props_has_fixed_property    (GstProps *props,
                                             const gchar *name);
gboolean    gst_props_has_property_typed    (GstProps *props,
                                             const gchar *name,
                                             GstPropsType type);
GstProps*   gst_props_intersect             (GstProps *props1,
                                             GstProps *props2);
void        gst_props_debug                 (GstProps *props);
xmlNodePtr  gst_props_save_thyself          (GstProps *props,
                                             xmlNodePtr parent);
GstProps*   gst_props_load_thyself          (xmlNodePtr parent);
const GstPropsEntry* gst_props_get_entry    (GstProps *props,
                                             const gchar *name);
void        gst_props_add_entry             (GstProps *props,
                                             GstPropsEntry *entry);
void        gst_props_remove_entry          (GstProps *props,
                                             GstPropsEntry *entry);
void        gst_props_remove_entry_by_name  (GstProps *props,
                                             const gchar *name);
GstPropsEntry* gst_props_entry_new          (const gchar *name,
                                             ...);
GstPropsEntry* gst_props_entry_copy         (const GstPropsEntry *entry);
void        gst_props_entry_destroy         (GstPropsEntry *entry);
gboolean    gst_props_entry_get             (const GstPropsEntry *entry,
                                             ...);
GType       gst_props_entry_get_type        (void);
gboolean    gst_props_entry_get_boolean     (const GstPropsEntry *entry,
                                             gboolean *val);
gboolean    gst_props_entry_get_float       (const GstPropsEntry *entry,
                                             gfloat *val);
gboolean    gst_props_entry_get_float_range (const GstPropsEntry *entry,
                                             gfloat *min,
                                             gfloat *max);
gboolean    gst_props_entry_get_fourcc_int  (const GstPropsEntry *entry,
                                             guint32 *val);
gboolean    gst_props_entry_get_int         (const GstPropsEntry *entry,
                                             gint *val);
gboolean    gst_props_entry_get_int_range   (const GstPropsEntry *entry,
                                             gint *min,
                                             gint *max);
gboolean    gst_props_entry_get_list        (const GstPropsEntry *entry,
                                             const GList **val);
const gchar* gst_props_entry_get_name       (const GstPropsEntry *entry);
gboolean    gst_props_entry_get_string      (const GstPropsEntry *entry,
                                             const gchar **val);
GType       gst_props_entry_get_type        (void);
gboolean    gst_props_entry_is_fixed        (const GstPropsEntry *entry);

Description

GstProps is used to attach certain properties to a pad. Properties are usually used in conjunction with GstCaps.

Details

struct GstProps

struct GstProps {

  gint   refcount;
  gint   flags;

  GList *properties;		/* real property entries for this property */
};

The props structure

gint refcounta refcount for this struct
gint flags
GList *propertiesthe properties

enum GstPropsType

typedef enum {
   GST_PROPS_END_TYPE = 0,

   GST_PROPS_INVALID_TYPE,

   GST_PROPS_INT_TYPE,
   GST_PROPS_FLOAT_TYPE,
   GST_PROPS_FOURCC_TYPE,
   GST_PROPS_BOOLEAN_TYPE,
   GST_PROPS_STRING_TYPE,

   GST_PROPS_VAR_TYPE,   /* after this marker start the variable properties */

   GST_PROPS_LIST_TYPE,
   GST_PROPS_GLIST_TYPE,
   GST_PROPS_FLOAT_RANGE_TYPE,
   GST_PROPS_INT_RANGE_TYPE,

   GST_PROPS_LAST_TYPE = GST_PROPS_END_TYPE + 16
} GstPropsType;

The property type


enum GstPropsFlags

typedef enum {
  GST_PROPS_FIXED        = (1 << 0),	/* props has no variable entries */
  GST_PROPS_FLOATING     = (1 << 1)	/* props is floating */
} GstPropsFlags;

Flags for this property

GST_PROPS_FIXEDThe property has no variable entries
GST_PROPS_FLOATINGThe property is not owned by anyone

GST_PROPS_TRACE_NAME

#define	GST_PROPS_TRACE_NAME "GstProps"

The name used for tracing memory allocations for the properties


GST_PROPS_FLAGS()

#define GST_PROPS_FLAGS(props)            ((props)->flags)

The flags of this property

props :The props to query

GST_PROPS_FLAG_IS_SET()

#define GST_PROPS_FLAG_IS_SET(props,flag) (GST_PROPS_FLAGS (props) &   (flag))

Check if a flag is set on the property

props :The property to check
flag :The flag to check for

GST_PROPS_FLAG_SET()

#define GST_PROPS_FLAG_SET(props,flag)    (GST_PROPS_FLAGS (props) |=  (flag))

Set a flag on the property

props :The property to modify
flag :The flag to set

GST_PROPS_FLAG_UNSET()

#define GST_PROPS_FLAG_UNSET(props,flag)  (GST_PROPS_FLAGS (props) &= ~(flag))

Unset a flag in the property

props :The property to modify
flag :The flag to unset

GST_PROPS_IS_FIXED()

#define GST_PROPS_IS_FIXED(props)         (GST_PROPS_FLAG_IS_SET ((props), GST_PROPS_FIXED))

Check if the property is fixed, ie. it has no variable property entries.

props :The property to check

GST_PROPS_IS_FLOATING()

#define GST_PROPS_IS_FLOATING(props)      (GST_PROPS_FLAG_IS_SET ((props), GST_PROPS_FLOATING))

Check if the property is floating

props :The property to check

GST_PROPS_PROPERTIES()

#define GST_PROPS_PROPERTIES(props)       ((props) ? ((props)->properties) : NULL)

Get the property entries of this property

props :The property to query

GST_PROPS_REFCOUNT()

#define GST_PROPS_REFCOUNT(props)         ((props)->refcount)

Get the refcount of the property

props :The property to query

GST_TYPE_PROPS

#define GST_TYPE_PROPS	(_gst_props_type)

The GType of the props boxed type, for use in GValues.


GST_MAKE_FOURCC()

#define     GST_MAKE_FOURCC(a,b,c,d)

Create a FOURCC value that can easily be used to construct a fourcc property.

  ...
  "format", GST_PROPS_FOURCC (GST_MAKE_FOURCC ('Y','U','Y','2')),
  ...

a :first fourcc byte
b :second fourcc byte
c :third fourcc byte
d :fourth fourcc byte

GST_STR_FOURCC()

#define     GST_STR_FOURCC(f)

Create a FOURCC value from a string. example:

  ...
  "format", GST_PROPS_FOURCC (GST_STR_FOURCC ("YUY2")),
  ...

f :the string describing the fourcc value.

GST_PROPS_LIST()

#define     GST_PROPS_LIST(...)

Create a list of properties.

... :the list of GstProps

GST_PROPS_GLIST()

#define GST_PROPS_GLIST(a) 		GST_PROPS_GLIST_TYPE,(a)

Create a list from a GList of GstPropsEntry.

a :A GList of props entries

GST_PROPS_INT()

#define GST_PROPS_INT(a) 		GST_PROPS_INT_TYPE,(a)

Create an integer property.

a :the integer property

GST_PROPS_INT_ANY

#define GST_PROPS_INT_ANY		GST_PROPS_INT_RANGE(G_MININT,G_MAXINT)

Create an integer property that can hold any int.


GST_PROPS_INT_RANGE()

#define GST_PROPS_INT_RANGE(a,b) 	GST_PROPS_INT_RANGE_TYPE,(a),(b)

Create an integer range property.

a :the min value for the range
b :the max value for the range

GST_PROPS_INT_NEGATIVE

#define GST_PROPS_INT_NEGATIVE		GST_PROPS_INT_RANGE(G_MININT,0)

Create an integer property that can hold negative ints.


GST_PROPS_FOURCC()

#define GST_PROPS_FOURCC(a) 		GST_PROPS_FOURCC_TYPE,(a)

Construct a fourcc property out of four bytes.

a :a fourcc value usualy created with GST_FOURCC_MAKE()

GST_PROPS_BOOLEAN()

#define GST_PROPS_BOOLEAN(a) 		GST_PROPS_BOOLEAN_TYPE,(a)

Create a boolean property.

a :the boolean property

GST_PROPS_STRING()

#define GST_PROPS_STRING(a) 		GST_PROPS_STRING_TYPE,(a)

Create a string value.

a :the string value.

GST_PROPS_FLOAT()

#define GST_PROPS_FLOAT(a) 		GST_PROPS_FLOAT_TYPE,((float)(a))

Create a floating point value.

a :the float value

GST_PROPS_FLOAT_RANGE()

#define GST_PROPS_FLOAT_RANGE(a,b) 	GST_PROPS_FLOAT_RANGE_TYPE,((float)(a)),((float)(b))

Create a float range value.

a :lower float bounds
b :upper float bounds

GST_PROPS_INT_POSITIVE

#define GST_PROPS_INT_POSITIVE		GST_PROPS_INT_RANGE(0,G_MAXINT)

Create an integer property that can hold positive ints.


struct GstPropsEntry

struct GstPropsEntry;

An entry hols one key/value pair.


GST_PROPS_ENTRY_TRACE_NAME

#define	GST_PROPS_ENTRY_TRACE_NAME "GstPropsEntry"

The name used for tracing memory allocations.


gst_props_new ()

GstProps*   gst_props_new                   (const gchar *firstname,
                                             ...);

Create a new property from the given key/value pairs

firstname : the first property name
... : the property values
Returns : the new property

gst_props_newv ()

GstProps*   gst_props_newv                  (const gchar *firstname,
                                             va_list var_args);

Create a new property from the list of entries.

firstname : the first property name
var_args : the property values
Returns : the new property created from the list of entries

gst_props_empty_new ()

GstProps*   gst_props_empty_new             (void);

Create a new empty property.

Returns : the new property

gst_props_merge ()

GstProps*   gst_props_merge                 (GstProps *props,
                                             GstProps *tomerge);

Merge the properties of tomerge into props.

props : the property to merge into
tomerge : the property to merge
Returns : the new merged property

gst_props_copy ()

GstProps*   gst_props_copy                  (GstProps *props);

Copy the property structure.

props : the props to copy
Returns : the new property that is a copy of the original one.

gst_props_copy_on_write ()

GstProps*   gst_props_copy_on_write         (GstProps *props);

Copy the property structure if the refcount is >1.

props : the props to copy on write
Returns : A new props that can be safely written to.

gst_props_ref ()

GstProps*   gst_props_ref                   (GstProps *props);

Increase the refcount of the property structure.

props : the props to ref
Returns : handle to refed props.

gst_props_unref ()

GstProps*   gst_props_unref                 (GstProps *props);

Decrease the refcount of the property structure, destroying the property if the refcount is 0.

props : the props to unref
Returns : handle to unrefed props or NULL when it was destroyed.

gst_props_replace ()

void        gst_props_replace               (GstProps **oldprops,
                                             GstProps *newprops);

Replace the pointer to the props, doing proper refcounting.

oldprops : the props to take replace
newprops : the props to take replace

gst_props_replace_sink ()

void        gst_props_replace_sink          (GstProps **oldprops,
                                             GstProps *newprops);

Replace the pointer to the props and take ownership.

oldprops : the props to take replace
newprops : the props to take replace

gst_props_sink ()

void        gst_props_sink                  (GstProps *props);

If the props if floating, decrease its refcount. Usually used with gst_props_ref() to take ownership of the props.

props : the props to sink

gst_props_check_compatibility ()

gboolean    gst_props_check_compatibility   (GstProps *fromprops,
                                             GstProps *toprops);

Checks whether two capabilities are compatible.

fromprops : a property
toprops : a property
Returns : TRUE if compatible, FALSE otherwise

gst_props_has_property ()

gboolean    gst_props_has_property          (GstProps *props,
                                             const gchar *name);

Checks if a given props has a property with the given name.

props : the props to check
name : the name of the key to find
Returns : TRUE if the property was found, FALSE otherwise.

gst_props_normalize ()

GList*      gst_props_normalize             (GstProps *props);

Unrolls all lists in the given GstProps. This is usefull if you want to loop over the props.

props : a property
Returns : A GList with the unrolled props entries. g_list_free after usage.

gst_props_set ()

GstProps*   gst_props_set                   (GstProps *props,
                                             const gchar *name,
                                             ...);

Modifies the value of the given entry in the props struct. For the optional args, use GST_PROPS_FOO, where FOO is INT, STRING, etc. This macro expands to a variable number of arguments, hence the lack of precision in the function prototype. No terminating NULL is necessary as only one property can be changed.

props : the props to modify
name : the name of the entry to modify
... : The prop entry.
Returns : the new modified property structure.

gst_props_get ()

gboolean    gst_props_get                   (GstProps *props,
                                             gchar *first_name,
                                             ...);

Gets the contents of the props into given key/value pairs. Make sure you pass a NULL terminated list.

props : the props to query
first_name : the first key
... : a pointer to a datastructure that can hold the value.
Returns : TRUE if all of the props entries could be fetched.

gst_props_get_safe ()

gboolean    gst_props_get_safe              (GstProps *props,
                                             gchar *first_name,
                                             ...);

Gets the contents of the props into given key/value pairs.

props : the props to query
first_name : the first key
... : a pointer to a datastructure that can hold the value.
Returns : TRUE if all of the props entries could be fetched.

gst_props_has_fixed_property ()

gboolean    gst_props_has_fixed_property    (GstProps *props,
                                             const gchar *name);

Checks if a given props has a property with the given name that is also fixed, ie. is not a list or a range.

props : the props to check
name : the name of the key to find
Returns : TRUE if the property was found, FALSE otherwise.

gst_props_has_property_typed ()

gboolean    gst_props_has_property_typed    (GstProps *props,
                                             const gchar *name,
                                             GstPropsType type);

Checks if a given props has a property with the given name and the given type.

props : the props to check
name : the name of the key to find
type : the type of the required property
Returns : TRUE if the property was found, FALSE otherwise.

gst_props_intersect ()

GstProps*   gst_props_intersect             (GstProps *props1,
                                             GstProps *props2);

Calculates the intersection bewteen two GstProps.

props1 : a property
props2 : another property
Returns : a GstProps with the intersection or NULL if the intersection is empty. The new GstProps is floating and must be unreffed afetr use.

gst_props_debug ()

void        gst_props_debug                 (GstProps *props);

Dump the contents of the given properties into the DEBUG log.

props : the props to debug

gst_props_save_thyself ()

xmlNodePtr  gst_props_save_thyself          (GstProps *props,
                                             xmlNodePtr parent);

Saves the property into an XML representation.

props : a property to save
parent : the parent XML tree
Returns : the new XML tree

gst_props_load_thyself ()

GstProps*   gst_props_load_thyself          (xmlNodePtr parent);

Creates a new property out of an XML tree.

parent : the XML tree to load from
Returns : the new property

gst_props_get_entry ()

const GstPropsEntry* gst_props_get_entry    (GstProps *props,
                                             const gchar *name);

Get the props entry with the given name

props : the props to query
name : the name of the entry to get
Returns : The props entry with the given name or NULL if the entry does not exist.

gst_props_add_entry ()

void        gst_props_add_entry             (GstProps *props,
                                             GstPropsEntry *entry);

Addes the given propsentry to the props

props : the property to add the entry to
entry : the entry to add

gst_props_remove_entry ()

void        gst_props_remove_entry          (GstProps *props,
                                             GstPropsEntry *entry);

Removes the given propsentry from the props.

props : the property to remove the entry from
entry : the entry to remove

gst_props_remove_entry_by_name ()

void        gst_props_remove_entry_by_name  (GstProps *props,
                                             const gchar *name);

Removes the propsentry with the given name from the props.

props : the property to remove the entry from
name : the name of the entry to remove

gst_props_entry_new ()

GstPropsEntry* gst_props_entry_new          (const gchar *name,
                                             ...);

Create a new property entry with the given key/value.

name : the name of the props entry
... : the value of the entry
Returns : the new entry.

gst_props_entry_copy ()

GstPropsEntry* gst_props_entry_copy         (const GstPropsEntry *entry);

Copy the propsentry.

entry : the entry to copy
Returns : a new GstPropsEntry that is a copy of the original given entry.

gst_props_entry_destroy ()

void        gst_props_entry_destroy         (GstPropsEntry *entry);

Free the given propsentry

entry : the entry to destroy

gst_props_entry_get ()

gboolean    gst_props_entry_get             (const GstPropsEntry *entry,
                                             ...);

Gets the contents of the entry.

entry : the props entry to query
... : a pointer to a type that can hold the value.
Returns : TRUE is the props entry could be fetched.

gst_props_entry_get_type ()

GType       gst_props_entry_get_type        (void);

Returns :

gst_props_entry_get_boolean ()

gboolean    gst_props_entry_get_boolean     (const GstPropsEntry *entry,
                                             gboolean *val);

Get the contents of the entry into the given gboolean.

entry : the props entry to query
val : a pointer to a gboolean to hold the value.
Returns : TRUE is the value could be fetched. FALSE if the entry is not of given type or did not exist.

gst_props_entry_get_float ()

gboolean    gst_props_entry_get_float       (const GstPropsEntry *entry,
                                             gfloat *val);

Get the contents of the entry into the given gfloat.

entry : the props entry to query
val : a pointer to a gfloat to hold the value.
Returns : TRUE is the value could be fetched. FALSE if the entry is not of given type or did not exist.

gst_props_entry_get_float_range ()

gboolean    gst_props_entry_get_float_range (const GstPropsEntry *entry,
                                             gfloat *min,
                                             gfloat *max);

Get the contents of the entry into the given gfloats.

entry : the props entry to query
min : a pointer to a gfloat to hold the minimun value.
max : a pointer to a gfloat to hold the maximum value.
Returns : TRUE is the value could be fetched. FALSE if the entry is not of given type or did not exist.

gst_props_entry_get_fourcc_int ()

gboolean    gst_props_entry_get_fourcc_int  (const GstPropsEntry *entry,
                                             guint32 *val);

Get the contents of the entry into the given guint32.

entry : the props entry to query
val : a pointer to a guint32 to hold the value.
Returns : TRUE is the value could be fetched. FALSE if the entry is not of given type or did not exist.

gst_props_entry_get_int ()

gboolean    gst_props_entry_get_int         (const GstPropsEntry *entry,
                                             gint *val);

Get the contents of the entry into the given gint.

entry : the props entry to query
val : a pointer to a gint to hold the value.
Returns : TRUE is the value could be fetched. FALSE if the entry is not of given type or did not exist.

gst_props_entry_get_int_range ()

gboolean    gst_props_entry_get_int_range   (const GstPropsEntry *entry,
                                             gint *min,
                                             gint *max);

Get the contents of the entry into the given gints.

entry : the props entry to query
min : a pointer to a gint to hold the minimun value.
max : a pointer to a gint to hold the maximum value.
Returns : TRUE is the value could be fetched. FALSE if the entry is not of given type or did not exist.

gst_props_entry_get_list ()

gboolean    gst_props_entry_get_list        (const GstPropsEntry *entry,
                                             const GList **val);

Get the contents of the entry into the given GList.

entry : the props entry to query
val : a pointer to a GList to hold the value.
Returns : TRUE is the value could be fetched. FALSE if the entry is not of given type or did not exist.

gst_props_entry_get_name ()

const gchar* gst_props_entry_get_name       (const GstPropsEntry *entry);

Get the name of the given props entry.

entry : the props entry to query
Returns : The name of the props entry.

gst_props_entry_get_string ()

gboolean    gst_props_entry_get_string      (const GstPropsEntry *entry,
                                             const gchar **val);

Get the contents of the entry into the given gchar*.

entry : the props entry to query
val : a pointer to a gchar* to hold the value.
Returns : TRUE is the value could be fetched. FALSE if the entry is not of given type or did not exist.

gst_props_entry_get_type ()

GType       gst_props_entry_get_type        (void);

Returns :

gst_props_entry_is_fixed ()

gboolean    gst_props_entry_is_fixed        (const GstPropsEntry *entry);

Checks if the props entry is fixe, ie. is not a list or a range.

entry : the props entry to query
Returns : TRUE is the props entry is fixed.

See Also

GstCaps