gst/gstcaps.h

   1 /* GStreamer
   2  * Copyright (C) 2003 David A. Schleef <ds@schleef.org>
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Library General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Library General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Library General Public
  15  * License along with this library; if not, write to the
  16  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17  * Boston, MA 02111-1307, USA.
  18  */
  19
  20 #ifndef __GST_CAPS_H__
  21 #define __GST_CAPS_H__
  22
  23 #include <gst/gstconfig.h>
  24 #include <gst/gststructure.h>
  25 #include <gst/glib-compat.h>
  26
  27 G_BEGIN_DECLS
  28
  29 #define GST_TYPE_CAPS             (gst_caps_get_type())
  30 #define GST_CAPS(object)          ((GstCaps*)object)
  31 #define GST_IS_CAPS(object)       ((object) && (GST_CAPS(object)->type == GST_TYPE_CAPS))
  32
  33 #define GST_TYPE_STATIC_CAPS      (gst_static_caps_get_type())
  34
  35 /**
  36  * GstCapsFlags:
  37  * @GST_CAPS_FLAGS_ANY: Caps has no specific content, but can contain
  38  *    anything.
  39  *
  40  * Extra flags for a caps.
  41  */
  42 typedef enum {
  43   GST_CAPS_FLAGS_ANY    = (1 << 0)
  44 } GstCapsFlags;
  45
  46 /**
  47  * GST_CAPS_ANY:
  48  *
  49  * Means that the element/pad can output 'anything'. Useful for elements
  50  * that output unknown media, such as filesrc.
  51  */
  52 #define GST_CAPS_ANY              gst_caps_new_any()
  53 /**
  54  * GST_CAPS_NONE:
  55  *
  56  * The opposite of %GST_CAPS_ANY: it means that the pad/element outputs an
  57  * undefined media type that can not be detected.
  58  */
  59 #define GST_CAPS_NONE             gst_caps_new_empty()
  60
  61 /**
  62  * GST_STATIC_CAPS_ANY:
  63  *
  64  * Creates a new #GstCaps static caps that matches anything.
  65  * This can be used in pad templates.
  66  */
  67 #define GST_STATIC_CAPS_ANY       GST_STATIC_CAPS("ANY")
  68 /**
  69  * GST_STATIC_CAPS_NONE:
  70  *
  71  * Creates a new #GstCaps static caps that matches nothing.
  72  * This can be used in pad templates.
  73  */
  74 #define GST_STATIC_CAPS_NONE      GST_STATIC_CAPS("NONE")
  75
  76 /**
  77  * GST_CAPS_IS_SIMPLE:
  78  * @caps: the #GstCaps instance to check
  79  *
  80  * Convenience macro that checks if the number of structures in the given caps
  81  * is exactly one.
  82  */
  83 #define GST_CAPS_IS_SIMPLE(caps) (gst_caps_get_size(caps) == 1)
  84
  85 #ifndef GST_DISABLE_DEPRECATED
  86 /**
  87  * GST_DEBUG_CAPS:
  88  * @string: a string that should be prepended to the caps data.
  89  * @caps: the #GstCaps instance to print
  90  *
  91  * Convenience macro for printing out the contents of caps with GST_DEBUG().
  92  *
  93  * Deprecated: do not use anymore
  94  */
  95 #define GST_DEBUG_CAPS(string, caps) \
  96   GST_DEBUG ( string "%s: " GST_PTR_FORMAT, caps)
  97
  98 #endif /* GST_DISABLE_DEPRECATED */
  99
 100 /**
 101  * GST_STATIC_CAPS:
 102  * @string: the string describing the caps
 103  *
 104  * Creates a new #GstCaps static caps from an input string.
 105  * This can be used in pad templates.
 106  */
 107 #define GST_STATIC_CAPS(string) \
 108 { \
 109   /* caps */ { 0, 0, (GstCapsFlags) 0, NULL, GST_PADDING_INIT }, \
 110   /* string */ string, \
 111   GST_PADDING_INIT \
 112 }
 113
 114 typedef struct _GstCaps GstCaps;
 115 typedef struct _GstStaticCaps GstStaticCaps;
 116
 117 /* refcount */
 118 /**
 119  * GST_CAPS_REFCOUNT:
 120  * @caps: a #GstCaps
 121  *
 122  * Get access to the reference count field of the caps
 123  */
 124 #define GST_CAPS_REFCOUNT(caps)                 ((GST_CAPS(caps))->refcount)
 125 /**
 126  * GST_CAPS_REFCOUNT_VALUE:
 127  * @caps: a #GstCaps
 128  *
 129  * Get the reference count value of the caps.
 130  */
 131 #define GST_CAPS_REFCOUNT_VALUE(caps)           (g_atomic_int_get (&(GST_CAPS(caps))->refcount))
 132
 133 /**
 134  * GstCaps:
 135  * @type: GType of the caps
 136  * @refcount: the atomic refcount value
 137  * @flags: extra flags for the caps, read only.
 138  *
 139  * Object describing media types.
 140  */
 141 struct _GstCaps {
 142   GType type;
 143
 144   /*< public >*/ /* with COW */
 145   /* refcounting */
 146   gint           refcount;
 147
 148   /*< public >*/ /* read only */
 149   GstCapsFlags flags;
 150
 151   /*< private >*/
 152   GPtrArray *structs;
 153
 154   /*< private >*/
 155   gpointer _gst_reserved[GST_PADDING];
 156 };
 157
 158 /**
 159  * GstStaticCaps:
 160  * @caps: the cached #GstCaps
 161  * @string: a string describing a caps
 162  *
 163  * Datastructure to initialize #GstCaps from a string description usually
 164  * used in conjunction with GST_STATIC_CAPS() and gst_static_caps_get() to
 165  * instantiate a #GstCaps.
 166  */
 167 struct _GstStaticCaps {
 168   /*< public >*/
 169   GstCaps caps;
 170   const char *string;
 171
 172   /*< private >*/
 173   gpointer _gst_reserved[GST_PADDING];
 174 };
 175
 176 GType             gst_caps_get_type                (void);
 177 GstCaps *         gst_caps_new_empty               (void);
 178 GstCaps *         gst_caps_new_any                 (void);
 179 GstCaps *         gst_caps_new_simple              (const char    *media_type,
 180                                                     const char    *fieldname,
 181                                                     ...);
 182 GstCaps *         gst_caps_new_full                (GstStructure  *struct1, ...);
 183 GstCaps *         gst_caps_new_full_valist         (GstStructure  *structure,
 184                                                     va_list        var_args);
 185
 186 /* reference counting */
 187 GstCaps *         gst_caps_ref                     (GstCaps       *caps);
 188 GstCaps *         gst_caps_copy                    (const GstCaps *caps);
 189 GstCaps *         gst_caps_make_writable           (GstCaps       *caps);
 190 void              gst_caps_unref                   (GstCaps       *caps);
 191
 192 GType             gst_static_caps_get_type         (void);
 193 GstCaps *         gst_static_caps_get              (GstStaticCaps *static_caps);
 194
 195 /* manipulation */
 196 void              gst_caps_append                  (GstCaps       *caps1,
 197                                                     GstCaps       *caps2);
 198 void              gst_caps_merge                   (GstCaps       *caps1,
 199                                                     GstCaps       *caps2);
 200 void              gst_caps_append_structure        (GstCaps       *caps,
 201                                                     GstStructure  *structure);
 202 void              gst_caps_remove_structure        (GstCaps       *caps, guint idx);
 203 void              gst_caps_merge_structure         (GstCaps       *caps,
 204                                                     GstStructure  *structure);
 205 guint             gst_caps_get_size                (const GstCaps *caps);
 206 GstStructure *    gst_caps_get_structure           (const GstCaps *caps,
 207                                                     guint          index);
 208 GstCaps *         gst_caps_copy_nth                (const GstCaps *caps, guint nth);
 209 void              gst_caps_truncate                (GstCaps       *caps);
 210 void              gst_caps_set_simple              (GstCaps       *caps,
 211                                                     const char    *field, ...) G_GNUC_NULL_TERMINATED;
 212 void              gst_caps_set_simple_valist       (GstCaps       *caps,
 213                                                     const char    *field,
 214                                                     va_list        varargs);
 215
 216 /* tests */
 217 gboolean          gst_caps_is_any                  (const GstCaps *caps);
 218 gboolean          gst_caps_is_empty                (const GstCaps *caps);
 219 gboolean          gst_caps_is_fixed                (const GstCaps *caps);
 220 gboolean          gst_caps_is_always_compatible    (const GstCaps *caps1,
 221                                                     const GstCaps *caps2);
 222 gboolean          gst_caps_is_subset               (const GstCaps *subset,
 223                                                     const GstCaps *superset);
 224 gboolean          gst_caps_is_equal                (const GstCaps *caps1,
 225                                                     const GstCaps *caps2);
 226 gboolean          gst_caps_is_equal_fixed          (const GstCaps *caps1,
 227                                                     const GstCaps *caps2);
 228
 229
 230 /* operations */
 231 GstCaps *         gst_caps_intersect               (const GstCaps *caps1,
 232                                                     const GstCaps *caps2);
 233 GstCaps *         gst_caps_subtract                (const GstCaps *minuend,
 234                                                     const GstCaps *subtrahend);
 235 GstCaps *         gst_caps_union                   (const GstCaps *caps1,
 236                                                     const GstCaps *caps2);
 237 GstCaps *         gst_caps_normalize               (const GstCaps *caps);
 238 gboolean          gst_caps_do_simplify             (GstCaps       *caps);
 239
 240 #ifndef GST_DISABLE_LOADSAVE
 241 xmlNodePtr        gst_caps_save_thyself            (const GstCaps *caps,
 242                                                     xmlNodePtr     parent);
 243 GstCaps *         gst_caps_load_thyself            (xmlNodePtr     parent);
 244 #endif
 245
 246 /* utility */
 247 void              gst_caps_replace                 (GstCaps      **caps,
 248                                                     GstCaps       *newcaps);
 249 gchar *           gst_caps_to_string               (const GstCaps *caps);
 250 GstCaps *         gst_caps_from_string             (const gchar   *string);
 251
 252 G_END_DECLS
 253
 254 #endif /* __GST_CAPS_H__ */