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/gstminiobject.h>
  25 #include <gst/gststructure.h>
  26 #include <gst/glib-compat.h>
  27
  28 G_BEGIN_DECLS
  29
  30 extern GType _gst_caps_type;
  31
  32 #define GST_TYPE_CAPS             (_gst_caps_type)
  33 #define GST_CAPS(object)          ((GstCaps*)object)
  34 #define GST_IS_CAPS(object)       (GST_IS_MINI_OBJECT_TYPE(object, GST_TYPE_CAPS))
  35
  36 #define GST_TYPE_STATIC_CAPS      (gst_static_caps_get_type())
  37
  38 /**
  39  * GstCapsFlags:
  40  * @GST_CAPS_FLAGS_ANY: Caps has no specific content, but can contain
  41  *    anything.
  42  *
  43  * Extra flags for a caps.
  44  */
  45 typedef enum {
  46   GST_CAPS_FLAGS_ANY    = (GST_MINI_OBJECT_FLAG_LAST << 0)
  47 } GstCapsFlags;
  48
  49 /**
  50  * GstCapsIntersectMode:
  51  * @GST_CAPS_INTERSECT_ZIG_ZAG  : Zig-zags over both caps.
  52  * @GST_CAPS_INTERSECT_FIRST    : Keeps the first caps order.
  53  *
  54  * Modes of caps intersection
  55  *
  56  * #GST_CAPS_INTERSECT_ZIG_ZAG tries to preserve overall order of both caps
  57  * by iterating on the caps' structures as the following matrix shows:
  58  *          caps1
  59  *       +-------------
  60  *       | 1  2  4  7
  61  * caps2 | 3  5  8 10
  62  *       | 6  9 11 12
  63  *
  64  * Used when there is no explicit precedence of one caps over the other. e.g.
  65  * tee's sink pad getcaps function, it will probe its src pad peers' for their
  66  * caps and intersect them with this mode.
  67  *
  68  * #GST_CAPS_INTERSECT_FIRST is useful when an element wants to preserve
  69  * another element's caps priority order when intersecting with its own caps.
  70  * Example: If caps1 is [A, B, C] and caps2 is [E, B, D, A], the result
  71  * would be [A, B], maintaining the first caps priority on the intersection.
  72  *
  73  * Since: 0.10.33
  74  */
  75 typedef enum {
  76   GST_CAPS_INTERSECT_ZIG_ZAG            =  0,
  77   GST_CAPS_INTERSECT_FIRST              =  1
  78 } GstCapsIntersectMode;
  79
  80 /**
  81  * GST_CAPS_ANY:
  82  *
  83  * Means that the element/pad can output 'anything'. Useful for elements
  84  * that output unknown media, such as filesrc.
  85  */
  86 #define GST_CAPS_ANY              gst_caps_new_any()
  87 /**
  88  * GST_CAPS_NONE:
  89  *
  90  * The opposite of %GST_CAPS_ANY: it means that the pad/element outputs an
  91  * undefined media type that can not be detected.
  92  */
  93 #define GST_CAPS_NONE             gst_caps_new_empty()
  94
  95 /**
  96  * GST_STATIC_CAPS_ANY:
  97  *
  98  * Creates a new #GstCaps static caps that matches anything.
  99  * This can be used in pad templates.
 100  */
 101 #define GST_STATIC_CAPS_ANY       GST_STATIC_CAPS("ANY")
 102 /**
 103  * GST_STATIC_CAPS_NONE:
 104  *
 105  * Creates a new #GstCaps static caps that matches nothing.
 106  * This can be used in pad templates.
 107  */
 108 #define GST_STATIC_CAPS_NONE      GST_STATIC_CAPS("NONE")
 109
 110 /**
 111  * GST_CAPS_IS_SIMPLE:
 112  * @caps: the #GstCaps instance to check
 113  *
 114  * Convenience macro that checks if the number of structures in the given caps
 115  * is exactly one.
 116  */
 117 #define GST_CAPS_IS_SIMPLE(caps) (gst_caps_get_size(caps) == 1)
 118
 119 /**
 120  * GST_STATIC_CAPS:
 121  * @string: the string describing the caps
 122  *
 123  * Creates a new #GstCaps static caps from an input string.
 124  * This can be used in pad templates.
 125  */
 126 #define GST_STATIC_CAPS(string) \
 127 { \
 128   /* miniobject */ { { 0, 0, 0, 0, NULL, NULL, NULL }, \
 129   /* caps */ NULL,  GST_PADDING_INIT }, \
 130   /* string */ string, \
 131   GST_PADDING_INIT \
 132 }
 133
 134 typedef struct _GstCaps GstCaps;
 135 typedef struct _GstStaticCaps GstStaticCaps;
 136
 137 /**
 138  * GST_CAPS_FLAGS:
 139  * @caps: a #GstCaps.
 140  *
 141  * A flags word containing #GstCapsFlags flags set on this caps.
 142  */
 143 #define GST_CAPS_FLAGS(caps)                    GST_MINI_OBJECT_FLAGS(caps)
 144
 145 /* refcount */
 146 /**
 147  * GST_CAPS_REFCOUNT:
 148  * @caps: a #GstCaps
 149  *
 150  * Get access to the reference count field of the caps
 151  */
 152 #define GST_CAPS_REFCOUNT(caps)                 GST_MINI_OBJECT_REFCOUNT(caps)
 153 /**
 154  * GST_CAPS_REFCOUNT_VALUE:
 155  * @caps: a #GstCaps
 156  *
 157  * Get the reference count value of the caps.
 158  */
 159 #define GST_CAPS_REFCOUNT_VALUE(caps)           GST_MINI_OBJECT_REFCOUNT_VALUE(caps)
 160
 161 /**
 162  * GST_CAPS_FLAG_IS_SET:
 163  * @caps: a #GstCaps.
 164  * @flag: the #GstCapsFlag to check.
 165  *
 166  * Gives the status of a specific flag on a caps.
 167  */
 168 #define GST_CAPS_FLAG_IS_SET(caps,flag)        GST_MINI_OBJECT_FLAG_IS_SET (caps, flag)
 169 /**
 170  * GST_CAPS_FLAG_SET:
 171  * @caps: a #GstCaps.
 172  * @flag: the #GstCapsFlag to set.
 173  *
 174  * Sets a caps flag on a caps.
 175  */
 176 #define GST_CAPS_FLAG_SET(caps,flag)           GST_MINI_OBJECT_FLAG_SET (caps, flag)
 177 /**
 178  * GST_CAPS_FLAG_UNSET:
 179  * @caps: a #GstCaps.
 180  * @flag: the #GstCapsFlag to clear.
 181  *
 182  * Clears a caps flag.
 183  */
 184 #define GST_CAPS_FLAG_UNSET(caps,flag)         GST_MINI_OBJECT_FLAG_UNSET (caps, flag)
 185
 186 /* refcounting */
 187 /**
 188  * gst_caps_ref:
 189  * @caps: the #GstCaps to reference
 190  *
 191  * Add a reference to a #GstCaps object.
 192  *
 193  * From this point on, until the caller calls gst_caps_unref() or
 194  * gst_caps_make_writable(), it is guaranteed that the caps object will not
 195  * change. This means its structures won't change, etc. To use a #GstCaps
 196  * object, you must always have a refcount on it -- either the one made
 197  * implicitly by e.g. gst_caps_new_simple(), or via taking one explicitly with
 198  * this function.
 199  *
 200  * Returns: the same #GstCaps object.
 201  */
 202 #ifdef _FOOL_GTK_DOC_
 203 G_INLINE_FUNC GstCaps * gst_caps_ref (GstCaps * caps);
 204 #endif
 205
 206 static inline GstCaps *
 207 gst_caps_ref (GstCaps * caps)
 208 {
 209   return (GstCaps *) gst_mini_object_ref (GST_MINI_OBJECT_CAST (caps));
 210 }
 211
 212 /**
 213  * gst_caps_unref:
 214  * @caps: a #GstCaps.
 215  *
 216  * Unref a #GstCaps and and free all its structures and the
 217  * structures' values when the refcount reaches 0.
 218  */
 219 #ifdef _FOOL_GTK_DOC_
 220 G_INLINE_FUNC void gst_caps_unref (GstCaps * caps);
 221 #endif
 222
 223 static inline void
 224 gst_caps_unref (GstCaps * caps)
 225 {
 226   gst_mini_object_unref (GST_MINI_OBJECT_CAST (caps));
 227 }
 228
 229 /* copy caps */
 230 /**
 231  * gst_caps_copy:
 232  * @caps: a #GstCaps.
 233  *
 234  * Creates a new #GstCaps as a copy of the old @caps. The new caps will have a
 235  * refcount of 1, owned by the caller. The structures are copied as well.
 236  *
 237  * Note that this function is the semantic equivalent of a gst_caps_ref()
 238  * followed by a gst_caps_make_writable(). If you only want to hold on to a
 239  * reference to the data, you should use gst_caps_ref().
 240  *
 241  * When you are finished with the caps, call gst_caps_unref() on it.
 242  *
 243  * Returns: the new #GstCaps
 244  */
 245 #ifdef _FOOL_GTK_DOC_
 246 G_INLINE_FUNC GstCaps * gst_caps_copy (const GstCaps * caps);
 247 #endif
 248
 249 static inline GstCaps *
 250 gst_caps_copy (const GstCaps * caps)
 251 {
 252   return GST_CAPS (gst_mini_object_copy (GST_MINI_OBJECT_CAST (caps)));
 253 }
 254
 255
 256 /**
 257  * GstCaps:
 258  * @mini_object: the parent type
 259  *
 260  * Object describing media types.
 261  */
 262 struct _GstCaps {
 263   GstMiniObject mini_object;
 264
 265   /*< private >*/
 266   GPtrArray *structs;
 267
 268   /*< private >*/
 269   gpointer _gst_reserved[GST_PADDING];
 270 };
 271
 272 /**
 273  * GstStaticCaps:
 274  * @caps: the cached #GstCaps
 275  * @string: a string describing a caps
 276  *
 277  * Datastructure to initialize #GstCaps from a string description usually
 278  * used in conjunction with GST_STATIC_CAPS() and gst_static_caps_get() to
 279  * instantiate a #GstCaps.
 280  */
 281 struct _GstStaticCaps {
 282   /*< public >*/
 283   GstCaps caps;
 284   const char *string;
 285
 286   /*< private >*/
 287   gpointer _gst_reserved[GST_PADDING];
 288 };
 289
 290 GstCaps *         gst_caps_new_empty               (void);
 291 GstCaps *         gst_caps_new_any                 (void);
 292 GstCaps *         gst_caps_new_simple              (const char    *media_type,
 293                                                     const char    *fieldname,
 294                                                     ...);
 295 GstCaps *         gst_caps_new_full                (GstStructure  *struct1, ...);
 296 GstCaps *         gst_caps_new_full_valist         (GstStructure  *structure,
 297                                                     va_list        var_args);
 298
 299 /* reference counting */
 300 GstCaps *         gst_caps_make_writable           (GstCaps       *caps) G_GNUC_WARN_UNUSED_RESULT;
 301
 302 GType             gst_static_caps_get_type         (void);
 303 GstCaps *         gst_static_caps_get              (GstStaticCaps *static_caps);
 304
 305 /* manipulation */
 306 void              gst_caps_append                  (GstCaps       *caps1,
 307                                                     GstCaps       *caps2);
 308 void              gst_caps_merge                   (GstCaps       *caps1,
 309                                                     GstCaps       *caps2);
 310 void              gst_caps_append_structure        (GstCaps       *caps,
 311                                                     GstStructure  *structure);
 312 void              gst_caps_remove_structure        (GstCaps       *caps, guint idx);
 313 void              gst_caps_merge_structure         (GstCaps       *caps,
 314                                                     GstStructure  *structure);
 315 guint             gst_caps_get_size                (const GstCaps *caps);
 316 GstStructure *    gst_caps_get_structure           (const GstCaps *caps,
 317                                                     guint          index);
 318 GstStructure *    gst_caps_steal_structure         (GstCaps *caps,
 319                                                     guint          index);
 320 GstCaps *         gst_caps_copy_nth                (const GstCaps *caps, guint nth);
 321 void              gst_caps_truncate                (GstCaps       *caps);
 322 void              gst_caps_set_value               (GstCaps       *caps,
 323                                                     const char    *field,
 324                                                     const GValue  *value);
 325 void              gst_caps_set_simple              (GstCaps       *caps,
 326                                                     const char    *field, ...) G_GNUC_NULL_TERMINATED;
 327 void              gst_caps_set_simple_valist       (GstCaps       *caps,
 328                                                     const char    *field,
 329                                                     va_list        varargs);
 330
 331 /* tests */
 332 gboolean          gst_caps_is_any                  (const GstCaps *caps);
 333 gboolean          gst_caps_is_empty                (const GstCaps *caps);
 334 gboolean          gst_caps_is_fixed                (const GstCaps *caps);
 335 gboolean          gst_caps_is_always_compatible    (const GstCaps *caps1,
 336                                                     const GstCaps *caps2);
 337 gboolean          gst_caps_is_subset               (const GstCaps *subset,
 338                                                     const GstCaps *superset);
 339 gboolean          gst_caps_is_equal                (const GstCaps *caps1,
 340                                                     const GstCaps *caps2);
 341 gboolean          gst_caps_is_equal_fixed          (const GstCaps *caps1,
 342                                                     const GstCaps *caps2);
 343 gboolean          gst_caps_can_intersect           (const GstCaps * caps1,
 344                                                     const GstCaps * caps2);
 345
 346
 347 /* operations */
 348 GstCaps *         gst_caps_intersect               (const GstCaps *caps1,
 349                                                     const GstCaps *caps2);
 350 GstCaps *         gst_caps_intersect_full          (const GstCaps *caps1,
 351                                                     const GstCaps *caps2,
 352                                                     GstCapsIntersectMode mode);
 353 GstCaps *         gst_caps_subtract                (const GstCaps *minuend,
 354                                                     const GstCaps *subtrahend);
 355 GstCaps *         gst_caps_union                   (const GstCaps *caps1,
 356                                                     const GstCaps *caps2);
 357 GstCaps *         gst_caps_normalize               (const GstCaps *caps);
 358 gboolean          gst_caps_do_simplify             (GstCaps       *caps);
 359
 360 /* utility */
 361 void              gst_caps_replace                 (GstCaps      **caps,
 362                                                     GstCaps       *newcaps);
 363 gchar *           gst_caps_to_string               (const GstCaps *caps);
 364 GstCaps *         gst_caps_from_string             (const gchar   *string);
 365
 366 G_END_DECLS
 367
 368 #endif /* __GST_CAPS_H__ */