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_IS_CAPS(obj)          (GST_IS_MINI_OBJECT_TYPE((obj), GST_TYPE_CAPS))
  34 #define GST_CAPS_CAST(obj)        ((GstCaps*)(obj))
  35 #define GST_CAPS(obj)             (GST_CAPS_CAST(obj))
  36
  37 #define GST_TYPE_STATIC_CAPS      (gst_static_caps_get_type())
  38
  39 /**
  40  * GstCapsFlags:
  41  * @GST_CAPS_FLAG_ANY: Caps has no specific content, but can contain
  42  *    anything.
  43  *
  44  * Extra flags for a caps.
  45  */
  46 typedef enum {
  47   GST_CAPS_FLAG_ANY     = (GST_MINI_OBJECT_FLAG_LAST << 0)
  48 } GstCapsFlags;
  49
  50 /**
  51  * GstCapsIntersectMode:
  52  * @GST_CAPS_INTERSECT_ZIG_ZAG  : Zig-zags over both caps.
  53  * @GST_CAPS_INTERSECT_FIRST    : Keeps the first caps order.
  54  *
  55  * Modes of caps intersection
  56  *
  57  * @GST_CAPS_INTERSECT_ZIG_ZAG tries to preserve overall order of both caps
  58  * by iterating on the caps' structures as the following matrix shows:
  59  * |[
  60  *          caps1
  61  *       +-------------
  62  *       | 1  2  4  7
  63  * caps2 | 3  5  8 10
  64  *       | 6  9 11 12
  65  * ]|
  66  * Used when there is no explicit precedence of one caps over the other. e.g.
  67  * tee's sink pad getcaps function, it will probe its src pad peers' for their
  68  * caps and intersect them with this mode.
  69  *
  70  * @GST_CAPS_INTERSECT_FIRST is useful when an element wants to preserve
  71  * another element's caps priority order when intersecting with its own caps.
  72  * Example: If caps1 is [A, B, C] and caps2 is [E, B, D, A], the result
  73  * would be [A, B], maintaining the first caps priority on the intersection.
  74  *
  75  * Since: 0.10.33
  76  */
  77 typedef enum {
  78   GST_CAPS_INTERSECT_ZIG_ZAG            =  0,
  79   GST_CAPS_INTERSECT_FIRST              =  1
  80 } GstCapsIntersectMode;
  81
  82 /**
  83  * GST_CAPS_ANY:
  84  *
  85  * Means that the element/pad can output 'anything'. Useful for elements
  86  * that output unknown media, such as filesrc. This macro returns a singleton and
  87  * should not be unreffed.
  88  */
  89 #define GST_CAPS_ANY              _gst_caps_any
  90 /**
  91  * GST_CAPS_NONE:
  92  *
  93  * The opposite of %GST_CAPS_ANY: it means that the pad/element outputs an
  94  * undefined media type that can not be detected. This macro returns a singleton
  95  * and should not be unreffed.
  96  */
  97 #define GST_CAPS_NONE             _gst_caps_none
  98
  99 /**
 100  * GST_STATIC_CAPS_ANY:
 101  *
 102  * Creates a new #GstCaps static caps that matches anything.
 103  * This can be used in pad templates.
 104  */
 105 #define GST_STATIC_CAPS_ANY       GST_STATIC_CAPS("ANY")
 106 /**
 107  * GST_STATIC_CAPS_NONE:
 108  *
 109  * Creates a new #GstCaps static caps that matches nothing.
 110  * This can be used in pad templates.
 111  */
 112 #define GST_STATIC_CAPS_NONE      GST_STATIC_CAPS("NONE")
 113
 114 /**
 115  * GST_CAPS_IS_SIMPLE:
 116  * @caps: the #GstCaps instance to check
 117  *
 118  * Convenience macro that checks if the number of structures in the given caps
 119  * is exactly one.
 120  */
 121 #define GST_CAPS_IS_SIMPLE(caps) (gst_caps_get_size(caps) == 1)
 122
 123 /**
 124  * GST_STATIC_CAPS:
 125  * @string: the string describing the caps
 126  *
 127  * Creates a new #GstCaps static caps from an input string.
 128  * This can be used in pad templates.
 129  */
 130 #define GST_STATIC_CAPS(string) \
 131 { \
 132   /* miniobject */ { { 0, 0, 0, 0, NULL, NULL, NULL, 0, NULL }, \
 133   /* caps */ NULL }, \
 134   /* string */ string, \
 135   GST_PADDING_INIT \
 136 }
 137
 138 typedef struct _GstCaps GstCaps;
 139 typedef struct _GstStaticCaps GstStaticCaps;
 140
 141 extern GstCaps * _gst_caps_any;
 142 extern GstCaps * _gst_caps_none;
 143 /**
 144  * GST_CAPS_FLAGS:
 145  * @caps: a #GstCaps.
 146  *
 147  * A flags word containing #GstCapsFlags flags set on this caps.
 148  */
 149 #define GST_CAPS_FLAGS(caps)                    GST_MINI_OBJECT_FLAGS(caps)
 150
 151 /* refcount */
 152 /**
 153  * GST_CAPS_REFCOUNT:
 154  * @caps: a #GstCaps
 155  *
 156  * Get access to the reference count field of the caps
 157  */
 158 #define GST_CAPS_REFCOUNT(caps)                 GST_MINI_OBJECT_REFCOUNT(caps)
 159 /**
 160  * GST_CAPS_REFCOUNT_VALUE:
 161  * @caps: a #GstCaps
 162  *
 163  * Get the reference count value of the caps.
 164  */
 165 #define GST_CAPS_REFCOUNT_VALUE(caps)           GST_MINI_OBJECT_REFCOUNT_VALUE(caps)
 166
 167 /**
 168  * GST_CAPS_FLAG_IS_SET:
 169  * @caps: a #GstCaps.
 170  * @flag: the #GstCapsFlags to check.
 171  *
 172  * Gives the status of a specific flag on a caps.
 173  */
 174 #define GST_CAPS_FLAG_IS_SET(caps,flag)        GST_MINI_OBJECT_FLAG_IS_SET (caps, flag)
 175 /**
 176  * GST_CAPS_FLAG_SET:
 177  * @caps: a #GstCaps.
 178  * @flag: the #GstCapsFlags to set.
 179  *
 180  * Sets a caps flag on a caps.
 181  */
 182 #define GST_CAPS_FLAG_SET(caps,flag)           GST_MINI_OBJECT_FLAG_SET (caps, flag)
 183 /**
 184  * GST_CAPS_FLAG_UNSET:
 185  * @caps: a #GstCaps.
 186  * @flag: the #GstCapsFlags to clear.
 187  *
 188  * Clears a caps flag.
 189  */
 190 #define GST_CAPS_FLAG_UNSET(caps,flag)         GST_MINI_OBJECT_FLAG_UNSET (caps, flag)
 191
 192 /* refcounting */
 193 /**
 194  * gst_caps_ref:
 195  * @caps: the #GstCaps to reference
 196  *
 197  * Add a reference to a #GstCaps object.
 198  *
 199  * From this point on, until the caller calls gst_caps_unref() or
 200  * gst_caps_make_writable(), it is guaranteed that the caps object will not
 201  * change. This means its structures won't change, etc. To use a #GstCaps
 202  * object, you must always have a refcount on it -- either the one made
 203  * implicitly by e.g. gst_caps_new_simple(), or via taking one explicitly with
 204  * this function.
 205  *
 206  * Returns: the same #GstCaps object.
 207  */
 208 #ifdef _FOOL_GTK_DOC_
 209 G_INLINE_FUNC GstCaps * gst_caps_ref (GstCaps * caps);
 210 #endif
 211
 212 static inline GstCaps *
 213 gst_caps_ref (GstCaps * caps)
 214 {
 215   return (GstCaps *) gst_mini_object_ref (GST_MINI_OBJECT_CAST (caps));
 216 }
 217
 218 /**
 219  * gst_caps_unref:
 220  * @caps: a #GstCaps.
 221  *
 222  * Unref a #GstCaps and and free all its structures and the
 223  * structures' values when the refcount reaches 0.
 224  */
 225 #ifdef _FOOL_GTK_DOC_
 226 G_INLINE_FUNC void gst_caps_unref (GstCaps * caps);
 227 #endif
 228
 229 static inline void
 230 gst_caps_unref (GstCaps * caps)
 231 {
 232   gst_mini_object_unref (GST_MINI_OBJECT_CAST (caps));
 233 }
 234
 235 /* copy caps */
 236 /**
 237  * gst_caps_copy:
 238  * @caps: a #GstCaps.
 239  *
 240  * Creates a new #GstCaps as a copy of the old @caps. The new caps will have a
 241  * refcount of 1, owned by the caller. The structures are copied as well.
 242  *
 243  * Note that this function is the semantic equivalent of a gst_caps_ref()
 244  * followed by a gst_caps_make_writable(). If you only want to hold on to a
 245  * reference to the data, you should use gst_caps_ref().
 246  *
 247  * When you are finished with the caps, call gst_caps_unref() on it.
 248  *
 249  * Returns: the new #GstCaps
 250  */
 251 #ifdef _FOOL_GTK_DOC_
 252 G_INLINE_FUNC GstCaps * gst_caps_copy (const GstCaps * caps);
 253 #endif
 254
 255 static inline GstCaps *
 256 gst_caps_copy (const GstCaps * caps)
 257 {
 258   return GST_CAPS (gst_mini_object_copy (GST_MINI_OBJECT_CAST (caps)));
 259 }
 260
 261 /**
 262  * gst_caps_is_writable:
 263  * @caps: a #GstCaps
 264  *
 265  * Tests if you can safely modify @caps. It is only safe to modify caps when
 266  * there is only one owner of the caps - ie, the refcount is 1.
 267  */
 268 #define         gst_caps_is_writable(caps)     gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (caps))
 269
 270 /**
 271  * gst_caps_make_writable:
 272  * @caps: (transfer full): a #GstCaps
 273  *
 274  * Returns a writable copy of @caps.
 275  *
 276  * If there is only one reference count on @caps, the caller must be the owner,
 277  * and so this function will return the caps object unchanged. If on the other
 278  * hand there is more than one reference on the object, a new caps object will
 279  * be returned. The caller's reference on @caps will be removed, and instead the
 280  * caller will own a reference to the returned object.
 281  *
 282  * In short, this function unrefs the caps in the argument and refs the caps
 283  * that it returns. Don't access the argument after calling this function. See
 284  * also: gst_caps_ref().
 285  *
 286  * Returns: (transfer full): a writable caps which may or may not be the
 287  *     same as @caps
 288  */
 289 #define         gst_caps_make_writable(caps)   GST_CAPS_CAST (gst_mini_object_make_writable (GST_MINI_OBJECT_CAST (caps)))
 290
 291 /**
 292  * gst_caps_replace:
 293  * @old_caps: (inout) (transfer full): pointer to a pointer to a #GstCaps to be
 294  *     replaced.
 295  * @new_caps: (transfer none) (allow-none): pointer to a #GstCaps that will
 296  *     replace the caps pointed to by @ocaps.
 297  *
 298  * Modifies a pointer to a #GstCaps to point to a different #GstCaps. The
 299  * modification is done atomically (so this is useful for ensuring thread safety
 300  * in some cases), and the reference counts are updated appropriately (the old
 301  * caps is unreffed, the new is reffed).
 302  *
 303  * Either @ncaps or the #GstCaps pointed to by @ocaps may be NULL.
 304  *
 305  * Returns: TRUE if @new_caps was different from @old_caps
 306  */
 307 #ifdef _FOOL_GTK_DOC_
 308 G_INLINE_FUNC gboolean gst_caps_replace (GstCaps **old_caps, GstCaps *new_caps);
 309 #endif
 310
 311 static inline gboolean
 312 gst_caps_replace (GstCaps **old_caps, GstCaps *new_caps)
 313 {
 314     return gst_mini_object_replace ((GstMiniObject **) old_caps, (GstMiniObject *) new_caps);
 315 }
 316
 317 /**
 318  * gst_caps_take:
 319  * @old_caps: (inout) (transfer full): pointer to a pointer to a #GstCaps to be
 320  *     replaced.
 321  * @new_caps: (transfer full) (allow-none): pointer to a #GstCaps that will
 322  *     replace the caps pointed to by @ocaps.
 323  *
 324  * Modifies a pointer to a #GstCaps to point to a different #GstCaps. This
 325  * function is similar to gst_caps_replace() except that it takes ownership
 326  * of @new_caps.
 327  *
 328  * Returns: TRUE if @new_caps was different from @old_caps
 329  */
 330 #ifdef _FOOL_GTK_DOC_
 331 G_INLINE_FUNC gboolean gst_caps_take (GstCaps **old_caps, GstCaps *new_caps);
 332 #endif
 333
 334 static inline gboolean
 335 gst_caps_take (GstCaps **old_caps, GstCaps *new_caps)
 336 {
 337     return gst_mini_object_take ((GstMiniObject **) old_caps, (GstMiniObject *) new_caps);
 338 }
 339
 340 /**
 341  * GstCaps:
 342  * @mini_object: the parent type
 343  *
 344  * Object describing media types.
 345  */
 346 struct _GstCaps {
 347   GstMiniObject mini_object;
 348
 349   /*< private >*/
 350   gpointer     priv;
 351 };
 352
 353 /**
 354  * GstStaticCaps:
 355  * @caps: the cached #GstCaps
 356  * @string: a string describing a caps
 357  *
 358  * Datastructure to initialize #GstCaps from a string description usually
 359  * used in conjunction with GST_STATIC_CAPS() and gst_static_caps_get() to
 360  * instantiate a #GstCaps.
 361  */
 362 struct _GstStaticCaps {
 363   /*< public >*/
 364   GstCaps caps;
 365   const char *string;
 366
 367   /*< private >*/
 368   gpointer _gst_reserved[GST_PADDING];
 369 };
 370
 371 GType             gst_caps_get_type                (void);
 372
 373 GstCaps *         gst_caps_new_empty               (void);
 374 GstCaps *         gst_caps_new_any                 (void);
 375 GstCaps *         gst_caps_new_empty_simple        (const char    *media_type) G_GNUC_WARN_UNUSED_RESULT;
 376 GstCaps *         gst_caps_new_simple              (const char    *media_type,
 377                                                     const char    *fieldname,
 378                                                     ...) G_GNUC_NULL_TERMINATED G_GNUC_WARN_UNUSED_RESULT;
 379 GstCaps *         gst_caps_new_full                (GstStructure  *struct1,
 380                                                     ...) G_GNUC_NULL_TERMINATED G_GNUC_WARN_UNUSED_RESULT;
 381 GstCaps *         gst_caps_new_full_valist         (GstStructure  *structure,
 382                                                     va_list        var_args) G_GNUC_WARN_UNUSED_RESULT;
 383
 384 GType             gst_static_caps_get_type         (void);
 385 GstCaps *         gst_static_caps_get              (GstStaticCaps *static_caps);
 386 void              gst_static_caps_cleanup          (GstStaticCaps *static_caps);
 387
 388 /* manipulation */
 389 void              gst_caps_append                  (GstCaps       *caps1,
 390                                                     GstCaps       *caps2);
 391 void              gst_caps_merge                   (GstCaps       *caps1,
 392                                                     GstCaps       *caps2);
 393 void              gst_caps_append_structure        (GstCaps       *caps,
 394                                                     GstStructure  *structure);
 395 void              gst_caps_remove_structure        (GstCaps       *caps, guint idx);
 396 void              gst_caps_merge_structure         (GstCaps       *caps,
 397                                                     GstStructure  *structure);
 398 guint             gst_caps_get_size                (const GstCaps *caps);
 399 GstStructure *    gst_caps_get_structure           (const GstCaps *caps,
 400                                                     guint          index);
 401 GstStructure *    gst_caps_steal_structure         (GstCaps *caps,
 402                                                     guint          index) G_GNUC_WARN_UNUSED_RESULT;
 403 GstCaps *         gst_caps_copy_nth                (const GstCaps *caps, guint nth) G_GNUC_WARN_UNUSED_RESULT;
 404 void              gst_caps_truncate                (GstCaps       *caps);
 405 void              gst_caps_set_value               (GstCaps       *caps,
 406                                                     const char    *field,
 407                                                     const GValue  *value);
 408 void              gst_caps_set_simple              (GstCaps       *caps,
 409                                                     const char    *field, ...) G_GNUC_NULL_TERMINATED;
 410 void              gst_caps_set_simple_valist       (GstCaps       *caps,
 411                                                     const char    *field,
 412                                                     va_list        varargs);
 413
 414 /* tests */
 415 gboolean          gst_caps_is_any                  (const GstCaps *caps);
 416 gboolean          gst_caps_is_empty                (const GstCaps *caps);
 417 gboolean          gst_caps_is_fixed                (const GstCaps *caps);
 418 gboolean          gst_caps_is_always_compatible    (const GstCaps *caps1,
 419                                                     const GstCaps *caps2);
 420 gboolean          gst_caps_is_subset               (const GstCaps *subset,
 421                                                     const GstCaps *superset);
 422 gboolean          gst_caps_is_subset_structure     (const GstCaps *caps,
 423                                                     const GstStructure *structure);
 424 gboolean          gst_caps_is_equal                (const GstCaps *caps1,
 425                                                     const GstCaps *caps2);
 426 gboolean          gst_caps_is_equal_fixed          (const GstCaps *caps1,
 427                                                     const GstCaps *caps2);
 428 gboolean          gst_caps_can_intersect           (const GstCaps * caps1,
 429                                                     const GstCaps * caps2);
 430 gboolean          gst_caps_is_strictly_equal       (const GstCaps *caps1,
 431                                                     const GstCaps *caps2);
 432
 433
 434 /* operations */
 435 GstCaps *         gst_caps_intersect               (const GstCaps *caps1,
 436                                                     const GstCaps *caps2) G_GNUC_WARN_UNUSED_RESULT;
 437 GstCaps *         gst_caps_intersect_full          (const GstCaps *caps1,
 438                                                     const GstCaps *caps2,
 439                                                     GstCapsIntersectMode mode) G_GNUC_WARN_UNUSED_RESULT;
 440 GstCaps *         gst_caps_subtract                (const GstCaps *minuend,
 441                                                     const GstCaps *subtrahend) G_GNUC_WARN_UNUSED_RESULT;
 442 GstCaps *         gst_caps_union                   (const GstCaps *caps1,
 443                                                     const GstCaps *caps2) G_GNUC_WARN_UNUSED_RESULT;
 444 GstCaps *         gst_caps_normalize               (const GstCaps *caps) G_GNUC_WARN_UNUSED_RESULT;
 445 gboolean          gst_caps_do_simplify             (GstCaps       *caps);
 446
 447 void              gst_caps_fixate                  (GstCaps       *caps);
 448
 449 /* utility */
 450 gchar *           gst_caps_to_string               (const GstCaps *caps) G_GNUC_MALLOC;
 451 GstCaps *         gst_caps_from_string             (const gchar   *string) G_GNUC_WARN_UNUSED_RESULT;
 452
 453 G_END_DECLS
 454
 455 #endif /* __GST_CAPS_H__ */