subprojects/gstreamer/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., 51 Franklin St, Fifth Floor,
  17  * Boston, MA 02110-1301, 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/gstcapsfeatures.h>
  27 #include <gst/glib-compat.h>
  28
  29 G_BEGIN_DECLS
  30
  31 GST_API GType _gst_caps_type;
  32
  33 #define GST_TYPE_CAPS             (_gst_caps_type)
  34 #define GST_IS_CAPS(obj)          (GST_IS_MINI_OBJECT_TYPE((obj), GST_TYPE_CAPS))
  35 #define GST_CAPS_CAST(obj)        ((GstCaps*)(obj))
  36 #define GST_CAPS(obj)             (GST_CAPS_CAST(obj))
  37
  38 #define GST_TYPE_STATIC_CAPS      (gst_static_caps_get_type())
  39
  40 /**
  41  * GstCapsFlags:
  42  * @GST_CAPS_FLAG_ANY: Caps has no specific content, but can contain
  43  *    anything.
  44  *
  45  * Extra flags for a caps.
  46  */
  47 typedef enum {
  48   GST_CAPS_FLAG_ANY     = (GST_MINI_OBJECT_FLAG_LAST << 0)
  49 } GstCapsFlags;
  50
  51 /**
  52  * GstCapsIntersectMode:
  53  * @GST_CAPS_INTERSECT_ZIG_ZAG  : Zig-zags over both caps.
  54  * @GST_CAPS_INTERSECT_FIRST    : Keeps the first caps order.
  55  *
  56  * Modes of caps intersection
  57  *
  58  * %GST_CAPS_INTERSECT_ZIG_ZAG tries to preserve overall order of both caps
  59  * by iterating on the caps' structures as the following matrix shows:
  60  *
  61  * ```
  62  *          caps1
  63  *       +-------------
  64  *       | 1  2  4  7
  65  * caps2 | 3  5  8 10
  66  *       | 6  9 11 12
  67  * ```
  68  *
  69  * Used when there is no explicit precedence of one caps over the other. e.g.
  70  * tee's sink pad getcaps function, it will probe its src pad peers' for their
  71  * caps and intersect them with this mode.
  72  *
  73  * %GST_CAPS_INTERSECT_FIRST is useful when an element wants to preserve
  74  * another element's caps priority order when intersecting with its own caps.
  75  * Example: If caps1 is `[A, B, C]` and caps2 is `[E, B, D, A]`, the result
  76  * would be `[A, B]`, maintaining the first caps priority on the intersection.
  77  */
  78 typedef enum {
  79   GST_CAPS_INTERSECT_ZIG_ZAG            =  0,
  80   GST_CAPS_INTERSECT_FIRST              =  1
  81 } GstCapsIntersectMode;
  82
  83 /**
  84  * GST_CAPS_ANY:
  85  *
  86  * Means that the element/pad can output 'anything'. Useful for elements
  87  * that output unknown media, such as filesrc. This macro returns a singleton and
  88  * should not be unreffed.
  89  */
  90 #define GST_CAPS_ANY              _gst_caps_any
  91 /**
  92  * GST_CAPS_NONE:
  93  *
  94  * The opposite of %GST_CAPS_ANY: it means that the pad/element outputs an
  95  * undefined media type that can not be detected. This macro returns a singleton
  96  * and should not be unreffed.
  97  */
  98 #define GST_CAPS_NONE             _gst_caps_none
  99
 100 /**
 101  * GST_STATIC_CAPS_ANY:
 102  *
 103  * Creates a new #GstCaps static caps that matches anything.
 104  * This can be used in pad templates.
 105  */
 106 #define GST_STATIC_CAPS_ANY       GST_STATIC_CAPS("ANY")
 107 /**
 108  * GST_STATIC_CAPS_NONE:
 109  *
 110  * Creates a new #GstCaps static caps that matches nothing.
 111  * This can be used in pad templates.
 112  */
 113 #define GST_STATIC_CAPS_NONE      GST_STATIC_CAPS("NONE")
 114
 115 /**
 116  * GST_CAPS_IS_SIMPLE:
 117  * @caps: the #GstCaps instance to check
 118  *
 119  * Checks if the number of structures in the given caps 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   /* caps */ NULL, \
 133   /* string */ string, \
 134   GST_PADDING_INIT \
 135 }
 136
 137 typedef struct _GstCaps GstCaps;
 138 typedef struct _GstStaticCaps GstStaticCaps;
 139
 140 GST_API GstCaps * _gst_caps_any;
 141
 142 GST_API GstCaps * _gst_caps_none;
 143 /**
 144  * GST_CAPS_FLAGS:
 145  * @caps: a #GstCaps.
 146  *
 147  * Gets 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  * Gives 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  * Gets 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 #ifndef GST_DISABLE_MINIOBJECT_INLINE_FUNCTIONS
 193 /* refcounting */
 194 static inline GstCaps *
 195 gst_caps_ref (GstCaps * caps)
 196 {
 197   return (GstCaps *) gst_mini_object_ref (GST_MINI_OBJECT_CAST (caps));
 198 }
 199
 200 static inline void
 201 gst_caps_unref (GstCaps * caps)
 202 {
 203   gst_mini_object_unref (GST_MINI_OBJECT_CAST (caps));
 204 }
 205
 206 static inline void
 207 gst_clear_caps (GstCaps ** caps_ptr)
 208 {
 209   gst_clear_mini_object ((GstMiniObject **) caps_ptr);
 210 }
 211 #else /* GST_DISABLE_MINIOBJECT_INLINE_FUNCTIONS */
 212 GST_API
 213 GstCaps * gst_caps_ref   (GstCaps * caps);
 214
 215 GST_API
 216 void      gst_caps_unref (GstCaps * caps);
 217
 218 GST_API
 219 void      gst_clear_caps (GstCaps ** caps_ptr);
 220 #endif /* GST_DISABLE_MINIOBJECT_INLINE_FUNCTIONS */
 221
 222 /* copy caps */
 223 GST_API
 224 GstCaps * gst_caps_copy (const GstCaps * caps);
 225
 226 #define gst_caps_copy(caps) GST_CAPS (gst_mini_object_copy (GST_MINI_OBJECT_CAST (caps)))
 227
 228 /**
 229  * gst_caps_is_writable:
 230  * @caps: a #GstCaps
 231  *
 232  * Tests if you can safely modify @caps. It is only safe to modify caps when
 233  * there is only one owner of the caps - ie, the object is writable.
 234  */
 235 #define         gst_caps_is_writable(caps)     gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (caps))
 236
 237 /**
 238  * gst_caps_make_writable:
 239  * @caps: (transfer full): a #GstCaps
 240  *
 241  * Returns a writable copy of @caps.
 242  *
 243  * If there is only one reference count on @caps, the caller must be the owner,
 244  * and so this function will return the caps object unchanged. If on the other
 245  * hand there is more than one reference on the object, a new caps object will
 246  * be returned. The caller's reference on @caps will be removed, and instead the
 247  * caller will own a reference to the returned object.
 248  *
 249  * In short, this function unrefs the caps in the argument and refs the caps
 250  * that it returns. Don't access the argument after calling this function. See
 251  * also: gst_caps_ref().
 252  *
 253  * Returns: (transfer full): a writable caps which may or may not be the
 254  *     same as @caps
 255  */
 256 #define         gst_caps_make_writable(caps)   GST_CAPS_CAST (gst_mini_object_make_writable (GST_MINI_OBJECT_CAST (caps)))
 257
 258 #ifndef GST_DISABLE_MINIOBJECT_INLINE_FUNCTIONS
 259 static inline gboolean
 260 gst_caps_replace (GstCaps **old_caps, GstCaps *new_caps)
 261 {
 262     return gst_mini_object_replace ((GstMiniObject **) old_caps, (GstMiniObject *) new_caps);
 263 }
 264
 265 static inline gboolean
 266 gst_caps_take (GstCaps **old_caps, GstCaps *new_caps)
 267 {
 268     return gst_mini_object_take ((GstMiniObject **) old_caps, (GstMiniObject *) new_caps);
 269 }
 270 #else  /* GST_DISABLE_MINIOBJECT_INLINE_FUNCTIONS */
 271 GST_API
 272 gboolean  gst_caps_replace (GstCaps ** old_caps,
 273                             GstCaps * new_caps);
 274
 275 GST_API
 276 gboolean  gst_caps_take    (GstCaps ** old_caps,
 277                             GstCaps * new_caps);
 278 #endif /* GST_DISABLE_MINIOBJECT_INLINE_FUNCTIONS */
 279
 280 /**
 281  * GstCaps:
 282  * @mini_object: the parent type
 283  *
 284  * Object describing media types.
 285  */
 286 struct _GstCaps {
 287   GstMiniObject mini_object;
 288 };
 289
 290 /**
 291  * GstStaticCaps:
 292  * @caps: the cached #GstCaps
 293  * @string: a string describing a caps
 294  *
 295  * Data structure to initialize #GstCaps from a string description usually
 296  * used in conjunction with GST_STATIC_CAPS() and gst_static_caps_get() to
 297  * instantiate a #GstCaps.
 298  */
 299 struct _GstStaticCaps {
 300   /*< public >*/
 301   GstCaps *caps;
 302   const char *string;
 303
 304   /*< private >*/
 305   gpointer _gst_reserved[GST_PADDING];
 306 };
 307
 308 /**
 309  * GstCapsForeachFunc:
 310  * @features: the #GstCapsFeatures
 311  * @structure: the #GstStructure
 312  * @user_data: user data
 313  *
 314  * A function that will be called in gst_caps_foreach(). The function may
 315  * not modify @features or @structure.
 316  *
 317  * Returns: %TRUE if the foreach operation should continue, %FALSE if
 318  * the foreach operation should stop with %FALSE.
 319  *
 320  * Since: 1.6
 321  */
 322 typedef gboolean (*GstCapsForeachFunc) (GstCapsFeatures *features,
 323                                         GstStructure    *structure,
 324                                         gpointer         user_data);
 325
 326 /**
 327  * GstCapsMapFunc:
 328  * @features: the #GstCapsFeatures
 329  * @structure: the #GstStructure
 330  * @user_data: user data
 331  *
 332  * A function that will be called in gst_caps_map_in_place(). The function
 333  * may modify @features and @structure.
 334  *
 335  * Returns: %TRUE if the map operation should continue, %FALSE if
 336  * the map operation should stop with %FALSE.
 337  */
 338 typedef gboolean (*GstCapsMapFunc)     (GstCapsFeatures *features,
 339                                         GstStructure    *structure,
 340                                         gpointer         user_data);
 341
 342 /**
 343  * GstCapsFilterMapFunc:
 344  * @features: the #GstCapsFeatures
 345  * @structure: the #GstStructure
 346  * @user_data: user data
 347  *
 348  * A function that will be called in gst_caps_filter_and_map_in_place().
 349  * The function may modify @features and @structure, and both will be
 350  * removed from the caps if %FALSE is returned.
 351  *
 352  * Returns: %TRUE if the features and structure should be preserved,
 353  * %FALSE if it should be removed.
 354  */
 355 typedef gboolean (*GstCapsFilterMapFunc) (GstCapsFeatures *features,
 356                                           GstStructure    *structure,
 357                                           gpointer user_data);
 358
 359
 360 GST_API
 361 GType             gst_caps_get_type                (void);
 362
 363 GST_API
 364 GstCaps *         gst_caps_new_empty               (void);
 365
 366 GST_API
 367 GstCaps *         gst_caps_new_any                 (void);
 368
 369 GST_API
 370 GstCaps *         gst_caps_new_empty_simple        (const char    *media_type) G_GNUC_WARN_UNUSED_RESULT;
 371
 372 GST_API
 373 GstCaps *         gst_caps_new_simple              (const char    *media_type,
 374                                                     const char    *fieldname,
 375                                                     ...) G_GNUC_NULL_TERMINATED G_GNUC_WARN_UNUSED_RESULT;
 376 GST_API
 377 GstCaps *         gst_caps_new_full                (GstStructure  *struct1,
 378                                                     ...) G_GNUC_NULL_TERMINATED G_GNUC_WARN_UNUSED_RESULT;
 379 GST_API
 380 GstCaps *         gst_caps_new_full_valist         (GstStructure  *structure,
 381                                                     va_list        var_args) G_GNUC_WARN_UNUSED_RESULT;
 382 /**
 383  * gst_static_caps_get_type: (attributes doc.skip=true)
 384  */
 385 GST_API
 386 GType             gst_static_caps_get_type         (void);
 387
 388 GST_API
 389 GstCaps *         gst_static_caps_get              (GstStaticCaps *static_caps);
 390
 391 GST_API
 392 void              gst_static_caps_cleanup          (GstStaticCaps *static_caps);
 393
 394 /* manipulation */
 395
 396 GST_API
 397 void              gst_caps_append                  (GstCaps       *caps1,
 398                                                     GstCaps       *caps2);
 399 GST_API
 400 void              gst_caps_append_structure        (GstCaps       *caps,
 401                                                     GstStructure  *structure);
 402 GST_API
 403 void              gst_caps_append_structure_full   (GstCaps       *caps,
 404                                                     GstStructure  *structure,
 405                                                     GstCapsFeatures *features);
 406 GST_API
 407 void              gst_caps_remove_structure        (GstCaps       *caps, guint idx);
 408
 409 GST_API
 410 GstCaps *         gst_caps_merge                   (GstCaps       *caps1,
 411                                                     GstCaps       *caps2) G_GNUC_WARN_UNUSED_RESULT;
 412 GST_API
 413 GstCaps *         gst_caps_merge_structure         (GstCaps       *caps,
 414                                                     GstStructure  *structure) G_GNUC_WARN_UNUSED_RESULT;
 415 GST_API
 416 GstCaps *         gst_caps_merge_structure_full    (GstCaps       *caps,
 417                                                     GstStructure  *structure,
 418                                                     GstCapsFeatures *features) G_GNUC_WARN_UNUSED_RESULT;
 419
 420 GST_API
 421 guint             gst_caps_get_size                (const GstCaps *caps);
 422
 423 GST_API
 424 GstStructure *    gst_caps_get_structure           (const GstCaps *caps,
 425                                                     guint          index);
 426 GST_API
 427 GstStructure *    gst_caps_steal_structure         (GstCaps       *caps,
 428                                                     guint          index) G_GNUC_WARN_UNUSED_RESULT;
 429 GST_API
 430 void              gst_caps_set_features            (GstCaps *caps,
 431                                                     guint          index,
 432                                                     GstCapsFeatures * features);
 433 GST_API
 434 void              gst_caps_set_features_simple        (GstCaps *caps,
 435                                                        GstCapsFeatures * features);
 436
 437 GST_API
 438 GstCapsFeatures * gst_caps_get_features            (const GstCaps *caps,
 439                                                     guint          index);
 440 GST_API
 441 GstCaps *         gst_caps_copy_nth                (const GstCaps *caps, guint nth) G_GNUC_WARN_UNUSED_RESULT;
 442
 443 GST_API
 444 GstCaps *         gst_caps_truncate                (GstCaps       *caps) G_GNUC_WARN_UNUSED_RESULT;
 445
 446 GST_API
 447 void              gst_caps_set_value               (GstCaps       *caps,
 448                                                     const char    *field,
 449                                                     const GValue  *value);
 450 GST_API
 451 void              gst_caps_set_simple              (GstCaps       *caps,
 452                                                     const char    *field, ...) G_GNUC_NULL_TERMINATED;
 453 GST_API
 454 void              gst_caps_set_simple_valist       (GstCaps       *caps,
 455                                                     const char    *field,
 456                                                     va_list        varargs);
 457 GST_API
 458 gboolean          gst_caps_foreach                 (const GstCaps       *caps,
 459                                                     GstCapsForeachFunc   func,
 460                                                     gpointer             user_data);
 461 GST_API
 462 gboolean          gst_caps_map_in_place            (GstCaps        *caps,
 463                                                     GstCapsMapFunc  func,
 464                                                     gpointer        user_data);
 465 GST_API
 466 void              gst_caps_filter_and_map_in_place (GstCaps              *caps,
 467                                                     GstCapsFilterMapFunc  func,
 468                                                     gpointer              user_data);
 469
 470 /* tests */
 471
 472 GST_API
 473 gboolean          gst_caps_is_any                  (const GstCaps *caps);
 474
 475 GST_API
 476 gboolean          gst_caps_is_empty                (const GstCaps *caps);
 477
 478 GST_API
 479 gboolean          gst_caps_is_fixed                (const GstCaps *caps);
 480
 481 GST_API
 482 gboolean          gst_caps_is_always_compatible    (const GstCaps *caps1,
 483                                                     const GstCaps *caps2);
 484 GST_API
 485 gboolean          gst_caps_is_subset               (const GstCaps *subset,
 486                                                     const GstCaps *superset);
 487 GST_API
 488 gboolean          gst_caps_is_subset_structure     (const GstCaps *caps,
 489                                                     const GstStructure *structure);
 490 GST_API
 491 gboolean          gst_caps_is_subset_structure_full (const GstCaps *caps,
 492                                                      const GstStructure *structure,
 493                                                      const GstCapsFeatures *features);
 494 GST_API
 495 gboolean          gst_caps_is_equal                (const GstCaps *caps1,
 496                                                     const GstCaps *caps2);
 497 GST_API
 498 gboolean          gst_caps_is_equal_fixed          (const GstCaps *caps1,
 499                                                     const GstCaps *caps2);
 500 GST_API
 501 gboolean          gst_caps_can_intersect           (const GstCaps * caps1,
 502                                                     const GstCaps * caps2);
 503 GST_API
 504 gboolean          gst_caps_is_strictly_equal       (const GstCaps *caps1,
 505                                                     const GstCaps *caps2);
 506
 507
 508 /* operations */
 509
 510 GST_API
 511 GstCaps *         gst_caps_intersect               (GstCaps *caps1,
 512                                                     GstCaps *caps2) G_GNUC_WARN_UNUSED_RESULT;
 513 GST_API
 514 GstCaps *         gst_caps_intersect_full          (GstCaps *caps1,
 515                                                     GstCaps *caps2,
 516                                                     GstCapsIntersectMode mode) G_GNUC_WARN_UNUSED_RESULT;
 517 GST_API
 518 GstCaps *         gst_caps_subtract                (GstCaps *minuend,
 519                                                     GstCaps *subtrahend) G_GNUC_WARN_UNUSED_RESULT;
 520 GST_API
 521 GstCaps *         gst_caps_normalize               (GstCaps *caps) G_GNUC_WARN_UNUSED_RESULT;
 522
 523 GST_API
 524 GstCaps *         gst_caps_simplify                (GstCaps *caps) G_GNUC_WARN_UNUSED_RESULT;
 525
 526 GST_API
 527 GstCaps *         gst_caps_fixate                  (GstCaps *caps) G_GNUC_WARN_UNUSED_RESULT;
 528
 529 /* utility */
 530
 531 GST_API
 532 gchar *           gst_caps_to_string               (const GstCaps *caps) G_GNUC_MALLOC;
 533 GST_API
 534 gchar *           gst_caps_serialize               (const GstCaps *caps, GstSerializeFlags flags) G_GNUC_MALLOC;
 535
 536 GST_API
 537 GstCaps *         gst_caps_from_string             (const gchar   *string) G_GNUC_WARN_UNUSED_RESULT;
 538
 539 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstCaps, gst_caps_unref)
 540
 541 G_END_DECLS
 542
 543 #endif /* __GST_CAPS_H__ */