GstProps

Name

GstProps -- Properties

Synopsis


#include <gst/gst.h>


struct      GstProps;
enum        GstPropsType;
#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;
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);
void        gst_props_destroy               (GstProps *props);
GstProps*   gst_props_ref                   (GstProps *props);
GstProps*   gst_props_unref                 (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_property          (GstProps *props,
                                             const gchar *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);
GstPropsEntry* gst_props_entry_new          (const gchar *name,
                                             ...);
gboolean    gst_props_entry_get             (const GstPropsEntry *entry,
                                             ...);
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);
GstPropsType gst_props_entry_get_type       (const GstPropsEntry *entry);
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 refcount

a refcount for this struct

gint flags

GList *properties

the 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


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) 	(guint32)((a)|(b)<<8|(c)<<16|(d)<<24)

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)		(guint32)(((f)[0])|((f)[1]<<8)|((f)[2]<<16)|((f)[3]<<24))

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

void        gst_props_destroy               (GstProps *props);

Destroy the property, freeing all the memory that was allocated.

props :

the props to destroy


gst_props_ref ()

GstProps*   gst_props_ref                   (GstProps *props);

Increase the refcount of the property structure.

props :

the props to ref

Returns :

refcounted GstProps.


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 :

refcounted GstProps or NULL if props was destroyed.


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.


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.

props :

the props to query

first_name :

the first key

... :

a pointer to a datastructure that can hold the value.

Returns :

TRUE is the props entry 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 is the props entry could be fetched.


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


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 geven name

props :

the props to query

name :

the name of the entry to get

Returns :

The props entry with the geven name or NULL when the entry was not found.


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


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.


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.


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.


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.


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.


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.


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.


gst_props_entry_get_type ()

GstPropsType gst_props_entry_get_type       (const GstPropsEntry *entry);

Get the type of the given props entry.

entry :

the props entry to query

Returns :

The type of the props entry.


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