gst/gstprops.h

   1 /* GStreamer
   2  * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
   3  *                    2000 Wim Taymans <wtay@chello.be>
   4  *
   5  * gstprops.h: Header for properties subsystem
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Library General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Library General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Library General Public
  18  * License along with this library; if not, write to the
  19  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  20  * Boston, MA 02111-1307, USA.
  21  */
  22
  23
  24 #ifndef __GST_PROPS_H__
  25 #define __GST_PROPS_H__
  26
  27 #include <gst/gstconfig.h>
  28
  29 #include <glib-object.h>
  30
  31 G_BEGIN_DECLS
  32
  33 typedef struct _GstProps GstProps;
  34 extern GType _gst_props_type;
  35
  36 #define GST_PROPS_TRACE_NAME "GstProps"
  37
  38 #define GST_TYPE_PROPS  (_gst_props_type)
  39
  40 typedef enum {
  41    GST_PROPS_END_TYPE = 0,
  42
  43    GST_PROPS_INVALID_TYPE,
  44
  45    GST_PROPS_INT_TYPE,
  46    GST_PROPS_FLOAT_TYPE,
  47    GST_PROPS_FOURCC_TYPE,
  48    GST_PROPS_BOOLEAN_TYPE,
  49    GST_PROPS_STRING_TYPE,
  50
  51    GST_PROPS_VAR_TYPE,   /* after this marker start the variable properties */
  52
  53    GST_PROPS_LIST_TYPE,
  54    GST_PROPS_GLIST_TYPE,
  55    GST_PROPS_FLOAT_RANGE_TYPE,
  56    GST_PROPS_INT_RANGE_TYPE,
  57
  58    GST_PROPS_LAST_TYPE = GST_PROPS_END_TYPE + 16
  59 } GstPropsType;
  60
  61 #define GST_MAKE_FOURCC(a,b,c,d)        (guint32)((a)|(b)<<8|(c)<<16|(d)<<24)
  62 #define GST_STR_FOURCC(f)               (guint32)(((f)[0])|((f)[1]<<8)|((f)[2]<<16)|((f)[3]<<24))
  63
  64 #ifdef G_HAVE_ISO_VARARGS
  65 #  define GST_PROPS_LIST(...)       GST_PROPS_LIST_TYPE,__VA_ARGS__,NULL
  66 #elif defined(G_HAVE_GNUC_VARARGS)
  67 #  define GST_PROPS_LIST(a...)      GST_PROPS_LIST_TYPE,a,NULL
  68 #endif
  69
  70 #define GST_PROPS_GLIST(a)              GST_PROPS_GLIST_TYPE,(a)
  71 #define GST_PROPS_INT(a)                GST_PROPS_INT_TYPE,(a)
  72 #define GST_PROPS_INT_RANGE(a,b)        GST_PROPS_INT_RANGE_TYPE,(a),(b)
  73 #define GST_PROPS_FLOAT(a)              GST_PROPS_FLOAT_TYPE,((float)(a))
  74 #define GST_PROPS_FLOAT_RANGE(a,b)      GST_PROPS_FLOAT_RANGE_TYPE,((float)(a)),((float)(b))
  75 #define GST_PROPS_FOURCC(a)             GST_PROPS_FOURCC_TYPE,(a)
  76 #define GST_PROPS_BOOLEAN(a)            GST_PROPS_BOOLEAN_TYPE,(a)
  77 #define GST_PROPS_STRING(a)             GST_PROPS_STRING_TYPE,(a)
  78
  79 #define GST_PROPS_INT_POSITIVE          GST_PROPS_INT_RANGE(0,G_MAXINT)
  80 #define GST_PROPS_INT_NEGATIVE          GST_PROPS_INT_RANGE(G_MININT,0)
  81 #define GST_PROPS_INT_ANY               GST_PROPS_INT_RANGE(G_MININT,G_MAXINT)
  82
  83 /* propsentries are private */
  84 typedef struct _GstPropsEntry GstPropsEntry;
  85 extern GType _gst_props_entry_type;
  86
  87 #define GST_PROPS_ENTRY_TRACE_NAME "GstPropsEntry"
  88
  89 #define GST_TYPE_PROPS_ENTRY    (_gst_props_entry_type)
  90
  91 typedef enum {
  92   GST_PROPS_FIXED        = (1 << 0),    /* props has no variable entries */
  93   GST_PROPS_FLOATING     = (1 << 1)     /* props is floating */
  94 } GstPropsFlags;
  95
  96 #define GST_PROPS_FLAGS(props)            ((props)->flags)
  97 #define GST_PROPS_FLAG_IS_SET(props,flag) (GST_PROPS_FLAGS (props) & flag)
  98 #define GST_PROPS_FLAG_SET(props,flag)    (GST_PROPS_FLAGS (props) |= (flag))
  99 #define GST_PROPS_FLAG_UNSET(props,flag)  (GST_PROPS_FLAGS (props) &= ~(flag))
 100
 101 #define GST_PROPS_REFCOUNT(props)         ((props)->refcount)
 102 #define GST_PROPS_PROPERTIES(props)       ((props)->properties)
 103
 104 #define GST_PROPS_IS_FIXED(props)         (GST_PROPS_FLAGS (props) & GST_PROPS_FIXED)
 105 #define GST_PROPS_IS_FLOATING(props)      (GST_PROPS_FLAGS (props) & GST_PROPS_FLOATING)
 106
 107 struct _GstProps {
 108   gint   refcount;
 109   gint   flags;
 110
 111   GList *properties;            /* real property entries for this property */
 112 };
 113
 114 /* initialize the subsystem */
 115 void                    _gst_props_initialize           (void);
 116
 117 /* creating new properties */
 118 GstProps*               gst_props_new                   (const gchar *firstname, ...);
 119 GstProps*               gst_props_newv                  (const gchar *firstname, va_list var_args);
 120 GstProps*               gst_props_empty_new             (void);
 121
 122 /* replace pointer to props, doing proper refcounting */
 123 void                    gst_props_replace               (GstProps **oldprops, GstProps *newprops);
 124 void                    gst_props_replace_sink          (GstProps **oldprops, GstProps *newprops);
 125
 126 /* lifecycle management */
 127 GstProps*               gst_props_unref                 (GstProps *props);
 128 GstProps*               gst_props_ref                   (GstProps *props);
 129 void                    gst_props_sink                  (GstProps *props);
 130 void                    gst_props_destroy               (GstProps *props);
 131
 132 /* dump property debug info to the log */
 133 void                    gst_props_debug                 (GstProps *props);
 134
 135 /* copy */
 136 GstProps*               gst_props_copy                  (GstProps *props);
 137 GstProps*               gst_props_copy_on_write         (GstProps *props);
 138
 139 /* check if fromprops is subset of toprops */
 140 gboolean                gst_props_check_compatibility   (GstProps *fromprops, GstProps *toprops);
 141
 142 /* operation on props */
 143 GstProps*               gst_props_merge                 (GstProps *props, GstProps *tomerge);
 144 GstProps*               gst_props_intersect             (GstProps *props1, GstProps *props2);
 145 GList*                  gst_props_normalize             (GstProps *props);
 146
 147 /* modify entries */
 148 GstProps*               gst_props_set                   (GstProps *props, const gchar *name, ...);
 149 gboolean                gst_props_get                   (GstProps *props, gchar *first_name, ...);
 150 gboolean                gst_props_get_safe              (GstProps *props, gchar *first_name, ...);
 151
 152 /* query entries */
 153 gboolean                gst_props_has_property          (GstProps *props, const gchar *name);
 154 gboolean                gst_props_has_property_typed    (GstProps *props, const gchar *name, GstPropsType type);
 155 gboolean                gst_props_has_fixed_property    (GstProps *props, const gchar *name);
 156
 157 /* add/get entries */
 158 const GstPropsEntry*    gst_props_get_entry             (GstProps *props, const gchar *name);
 159 void                    gst_props_add_entry             (GstProps *props, GstPropsEntry *entry);
 160 void                    gst_props_remove_entry          (GstProps *props, GstPropsEntry *entry);
 161 void                    gst_props_remove_entry_by_name  (GstProps *props, const gchar *name);
 162
 163 /* working with props entries */
 164 GstPropsEntry*          gst_props_entry_new             (const gchar *name, ...);
 165
 166 void                    gst_props_entry_destroy         (GstPropsEntry *entry);
 167 GstPropsEntry*          gst_props_entry_copy            (const GstPropsEntry *entry);
 168 GstPropsType            gst_props_entry_get_type        (const GstPropsEntry *entry);
 169 const gchar*            gst_props_entry_get_name        (const GstPropsEntry *entry);
 170 gboolean                gst_props_entry_is_fixed        (const GstPropsEntry *entry);
 171
 172 gboolean                gst_props_entry_get             (const GstPropsEntry *entry, ...);
 173
 174 gboolean                gst_props_entry_get_int         (const GstPropsEntry *entry, gint *val);
 175 gboolean                gst_props_entry_get_float       (const GstPropsEntry *entry, gfloat *val);
 176 gboolean                gst_props_entry_get_fourcc_int  (const GstPropsEntry *entry, guint32 *val);
 177 gboolean                gst_props_entry_get_boolean     (const GstPropsEntry *entry, gboolean *val);
 178 gboolean                gst_props_entry_get_string      (const GstPropsEntry *entry, const gchar **val);
 179 gboolean                gst_props_entry_get_int_range   (const GstPropsEntry *entry, gint *min, gint *max);
 180 gboolean                gst_props_entry_get_float_range (const GstPropsEntry *entry, gfloat *min, gfloat *max);
 181 gboolean                gst_props_entry_get_list        (const GstPropsEntry *entry, const GList **val);
 182
 183
 184 #ifndef GST_DISABLE_LOADSAVE
 185 xmlNodePtr              gst_props_save_thyself          (GstProps *props, xmlNodePtr parent);
 186 GstProps*               gst_props_load_thyself          (xmlNodePtr parent);
 187 #endif
 188
 189
 190 G_END_DECLS
 191
 192 #endif /* __GST_PROPS_H__ */