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  *          caps1
  62  *       +-------------
  63  *       | 1  2  4  7
  64  * caps2 | 3  5  8 10
  65  *       | 6  9 11 12
  66  * ]|
  67  * Used when there is no explicit precedence of one caps over the other. e.g.
  68  * tee's sink pad getcaps function, it will probe its src pad peers' for their
  69  * caps and intersect them with this mode.
  70  *
  71  * @GST_CAPS_INTERSECT_FIRST is useful when an element wants to preserve
  72  * another element's caps priority order when intersecting with its own caps.
  73  * Example: If caps1 is [A, B, C] and caps2 is [E, B, D, A], the result
  74  * would be [A, B], maintaining the first caps priority on the intersection.
  75  */
  76 typedef enum {
  77   GST_CAPS_INTERSECT_ZIG_ZAG            =  0,
  78   GST_CAPS_INTERSECT_FIRST              =  1
  79 } GstCapsIntersectMode;
  80
  81 /**
  82  * GST_CAPS_ANY:
  83  *
  84  * Means that the element/pad can output 'anything'. Useful for elements
  85  * that output unknown media, such as filesrc. This macro returns a singleton and
  86  * should not be unreffed.
  87  */
  88 #define GST_CAPS_ANY              _gst_caps_any
  89 /**
  90  * GST_CAPS_NONE:
  91  *
  92  * The opposite of %GST_CAPS_ANY: it means that the pad/element outputs an
  93  * undefined media type that can not be detected. This macro returns a singleton
  94  * and should not be unreffed.
  95  */
  96 #define GST_CAPS_NONE             _gst_caps_none
  97
  98 /**
  99  * GST_STATIC_CAPS_ANY:
 100  *
 101  * Creates a new #GstCaps static caps that matches anything.
 102  * This can be used in pad templates.
 103  */
 104 #define GST_STATIC_CAPS_ANY       GST_STATIC_CAPS("ANY")
 105 /**
 106  * GST_STATIC_CAPS_NONE:
 107  *
 108  * Creates a new #GstCaps static caps that matches nothing.
 109  * This can be used in pad templates.
 110  */
 111 #define GST_STATIC_CAPS_NONE      GST_STATIC_CAPS("NONE")
 112
 113 /**
 114  * GST_CAPS_IS_SIMPLE:
 115  * @caps: the #GstCaps instance to check
 116  *
 117  * Convenience macro that checks if the number of structures in the given caps
 118  * is exactly one.
 119  */
 120 #define GST_CAPS_IS_SIMPLE(caps) (gst_caps_get_size(caps) == 1)
 121
 122 /**
 123  * GST_STATIC_CAPS:
 124  * @string: the string describing the caps
 125  *
 126  * Creates a new #GstCaps static caps from an input string.
 127  * This can be used in pad templates.
 128  */
 129 #define GST_STATIC_CAPS(string) \
 130 { \
 131   /* caps */ NULL, \
 132   /* string */ string, \
 133   GST_PADDING_INIT \
 134 }
 135
 136 typedef struct _GstCaps GstCaps;
 137 typedef struct _GstStaticCaps GstStaticCaps;
 138
 139 GST_API GstCaps * _gst_caps_any;
 140
 141 GST_API GstCaps * _gst_caps_none;
 142 /**
 143  * GST_CAPS_FLAGS:
 144  * @caps: a #GstCaps.
 145  *
 146  * A flags word containing #GstCapsFlags flags set on this caps.
 147  */
 148 #define GST_CAPS_FLAGS(caps)                    GST_MINI_OBJECT_FLAGS(caps)
 149
 150 /* refcount */
 151 /**
 152  * GST_CAPS_REFCOUNT:
 153  * @caps: a #GstCaps
 154  *
 155  * Get access to the reference count field of the caps
 156  */
 157 #define GST_CAPS_REFCOUNT(caps)                 GST_MINI_OBJECT_REFCOUNT(caps)
 158 /**
 159  * GST_CAPS_REFCOUNT_VALUE:
 160  * @caps: a #GstCaps
 161  *
 162  * Get the reference count value of the caps.
 163  */
 164 #define GST_CAPS_REFCOUNT_VALUE(caps)           GST_MINI_OBJECT_REFCOUNT_VALUE(caps)
 165
 166 /**
 167  * GST_CAPS_FLAG_IS_SET:
 168  * @caps: a #GstCaps.
 169  * @flag: the #GstCapsFlags to check.
 170  *
 171  * Gives the status of a specific flag on a caps.
 172  */
 173 #define GST_CAPS_FLAG_IS_SET(caps,flag)        GST_MINI_OBJECT_FLAG_IS_SET (caps, flag)
 174 /**
 175  * GST_CAPS_FLAG_SET:
 176  * @caps: a #GstCaps.
 177  * @flag: the #GstCapsFlags to set.
 178  *
 179  * Sets a caps flag on a caps.
 180  */
 181 #define GST_CAPS_FLAG_SET(caps,flag)           GST_MINI_OBJECT_FLAG_SET (caps, flag)
 182 /**
 183  * GST_CAPS_FLAG_UNSET:
 184  * @caps: a #GstCaps.
 185  * @flag: the #GstCapsFlags to clear.
 186  *
 187  * Clears a caps flag.
 188  */
 189 #define GST_CAPS_FLAG_UNSET(caps,flag)         GST_MINI_OBJECT_FLAG_UNSET (caps, flag)
 190
 191 /* refcounting */
 192 /**
 193  * gst_caps_ref: (skip)
 194  * @caps: the #GstCaps to reference
 195  *
 196  * Add a reference to a #GstCaps object.
 197  *
 198  * From this point on, until the caller calls gst_caps_unref() or
 199  * gst_caps_make_writable(), it is guaranteed that the caps object will not
 200  * change. This means its structures won't change, etc. To use a #GstCaps
 201  * object, you must always have a refcount on it -- either the one made
 202  * implicitly by e.g. gst_caps_new_simple(), or via taking one explicitly with
 203  * this function.
 204  *
 205  * Returns: the same #GstCaps object.
 206  */
 207 static inline GstCaps * gst_caps_ref (GstCaps * caps);
 208 static inline GstCaps *
 209 gst_caps_ref (GstCaps * caps)
 210 {
 211   return (GstCaps *) gst_mini_object_ref (GST_MINI_OBJECT_CAST (caps));
 212 }
 213
 214 /**
 215  * gst_caps_unref: (skip)
 216  * @caps: a #GstCaps.
 217  *
 218  * Unref a #GstCaps and and free all its structures and the
 219  * structures' values when the refcount reaches 0.
 220  */
 221 static inline void gst_caps_unref (GstCaps * caps);
 222 static inline void
 223 gst_caps_unref (GstCaps * caps)
 224 {
 225   gst_mini_object_unref (GST_MINI_OBJECT_CAST (caps));
 226 }
 227
 228 /**
 229  * gst_clear_caps: (skip)
 230  * @caps_ptr: a pointer to a #GstCaps reference
 231  *
 232  * Clears a reference to a #GstCaps.
 233  *
 234  * @caps_ptr must not be %NULL.
 235  *
 236  * If the reference is %NULL then this function does nothing. Otherwise, the
 237  * reference count of the caps is decreased and the pointer is set to %NULL.
 238  *
 239  * Since: 1.16
 240  */
 241 static inline void
 242 gst_clear_caps (GstCaps ** caps_ptr)
 243 {
 244   gst_clear_mini_object ((GstMiniObject **) caps_ptr);
 245 }
 246
 247 /* copy caps */
 248 GST_API
 249 GstCaps * gst_caps_copy (const GstCaps * caps);
 250
 251 #define gst_caps_copy(caps) GST_CAPS (gst_mini_object_copy (GST_MINI_OBJECT_CAST (caps)))
 252
 253 /**
 254  * gst_caps_is_writable:
 255  * @caps: a #GstCaps
 256  *
 257  * Tests if you can safely modify @caps. It is only safe to modify caps when
 258  * there is only one owner of the caps - ie, the object is writable.
 259  */
 260 #define         gst_caps_is_writable(caps)     gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (caps))
 261
 262 /**
 263  * gst_caps_make_writable:
 264  * @caps: (transfer full): a #GstCaps
 265  *
 266  * Returns a writable copy of @caps.
 267  *
 268  * If there is only one reference count on @caps, the caller must be the owner,
 269  * and so this function will return the caps object unchanged. If on the other
 270  * hand there is more than one reference on the object, a new caps object will
 271  * be returned. The caller's reference on @caps will be removed, and instead the
 272  * caller will own a reference to the returned object.
 273  *
 274  * In short, this function unrefs the caps in the argument and refs the caps
 275  * that it returns. Don't access the argument after calling this function. See
 276  * also: gst_caps_ref().
 277  *
 278  * Returns: (transfer full): a writable caps which may or may not be the
 279  *     same as @caps
 280  */
 281 #define         gst_caps_make_writable(caps)   GST_CAPS_CAST (gst_mini_object_make_writable (GST_MINI_OBJECT_CAST (caps)))
 282
 283 /**
 284  * gst_caps_replace: (skip)
 285  * @old_caps: (inout) (transfer full) (nullable): pointer to a pointer
 286  *     to a #GstCaps to be replaced.
 287  * @new_caps: (transfer none) (allow-none): pointer to a #GstCaps that will
 288  *     replace the caps pointed to by @old_caps.
 289  *
 290  * Modifies a pointer to a #GstCaps to point to a different #GstCaps. The
 291  * modification is done atomically (so this is useful for ensuring thread safety
 292  * in some cases), and the reference counts are updated appropriately (the old
 293  * caps is unreffed, the new is reffed).
 294  *
 295  * Either @new_caps or the #GstCaps pointed to by @old_caps may be %NULL.
 296  *
 297  * Returns: %TRUE if @new_caps was different from @old_caps
 298  */
 299 static inline gboolean gst_caps_replace (GstCaps **old_caps, GstCaps *new_caps);
 300 static inline gboolean
 301 gst_caps_replace (GstCaps **old_caps, GstCaps *new_caps)
 302 {
 303     return gst_mini_object_replace ((GstMiniObject **) old_caps, (GstMiniObject *) new_caps);
 304 }
 305
 306 /**
 307  * gst_caps_take: (skip)
 308  * @old_caps: (inout) (transfer full): pointer to a pointer to a #GstCaps to be
 309  *     replaced.
 310  * @new_caps: (transfer full) (allow-none): pointer to a #GstCaps that will
 311  *     replace the caps pointed to by @old_caps.
 312  *
 313  * Modifies a pointer to a #GstCaps to point to a different #GstCaps. This
 314  * function is similar to gst_caps_replace() except that it takes ownership
 315  * of @new_caps.
 316  *
 317  * Returns: %TRUE if @new_caps was different from @old_caps
 318  */
 319 static inline gboolean gst_caps_take (GstCaps **old_caps, GstCaps *new_caps);
 320 static inline gboolean
 321 gst_caps_take (GstCaps **old_caps, GstCaps *new_caps)
 322 {
 323     return gst_mini_object_take ((GstMiniObject **) old_caps, (GstMiniObject *) new_caps);
 324 }
 325
 326 /**
 327  * GstCaps:
 328  * @mini_object: the parent type
 329  *
 330  * Object describing media types.
 331  */
 332 struct _GstCaps {
 333   GstMiniObject mini_object;
 334 };
 335
 336 /**
 337  * GstStaticCaps:
 338  * @caps: the cached #GstCaps
 339  * @string: a string describing a caps
 340  *
 341  * Datastructure to initialize #GstCaps from a string description usually
 342  * used in conjunction with GST_STATIC_CAPS() and gst_static_caps_get() to
 343  * instantiate a #GstCaps.
 344  */
 345 struct _GstStaticCaps {
 346   /*< public >*/
 347   GstCaps *caps;
 348   const char *string;
 349
 350   /*< private >*/
 351   gpointer _gst_reserved[GST_PADDING];
 352 };
 353
 354 /**
 355  * GstCapsForeachFunc:
 356  * @features: the #GstCapsFeatures
 357  * @structure: the #GstStructure
 358  * @user_data: user data
 359  *
 360  * A function that will be called in gst_caps_foreach(). The function may
 361  * not modify @features or @structure.
 362  *
 363  * Returns: %TRUE if the foreach operation should continue, %FALSE if
 364  * the foreach operation should stop with %FALSE.
 365  *
 366  * Since: 1.6
 367  */
 368 typedef gboolean (*GstCapsForeachFunc) (GstCapsFeatures *features,
 369                                         GstStructure    *structure,
 370                                         gpointer         user_data);
 371
 372 /**
 373  * GstCapsMapFunc:
 374  * @features: the #GstCapsFeatures
 375  * @structure: the #GstStructure
 376  * @user_data: user data
 377  *
 378  * A function that will be called in gst_caps_map_in_place(). The function
 379  * may modify @features and @structure.
 380  *
 381  * Returns: %TRUE if the map operation should continue, %FALSE if
 382  * the map operation should stop with %FALSE.
 383  */
 384 typedef gboolean (*GstCapsMapFunc)     (GstCapsFeatures *features,
 385                                         GstStructure    *structure,
 386                                         gpointer         user_data);
 387
 388 /**
 389  * GstCapsFilterMapFunc:
 390  * @features: the #GstCapsFeatures
 391  * @structure: the #GstStructure
 392  * @user_data: user data
 393  *
 394  * A function that will be called in gst_caps_filter_and_map_in_place().
 395  * The function may modify @features and @structure, and both will be
 396  * removed from the caps if %FALSE is returned.
 397  *
 398  * Returns: %TRUE if the features and structure should be preserved,
 399  * %FALSE if it should be removed.
 400  */
 401 typedef gboolean (*GstCapsFilterMapFunc) (GstCapsFeatures *features,
 402                                           GstStructure    *structure,
 403                                           gpointer user_data);
 404
 405
 406 GST_API
 407 GType             gst_caps_get_type                (void);
 408
 409 GST_API
 410 GstCaps *         gst_caps_new_empty               (void);
 411
 412 GST_API
 413 GstCaps *         gst_caps_new_any                 (void);
 414
 415 GST_API
 416 GstCaps *         gst_caps_new_empty_simple        (const char    *media_type) G_GNUC_WARN_UNUSED_RESULT;
 417
 418 GST_API
 419 GstCaps *         gst_caps_new_simple              (const char    *media_type,
 420                                                     const char    *fieldname,
 421                                                     ...) G_GNUC_NULL_TERMINATED G_GNUC_WARN_UNUSED_RESULT;
 422 GST_API
 423 GstCaps *         gst_caps_new_full                (GstStructure  *struct1,
 424                                                     ...) G_GNUC_NULL_TERMINATED G_GNUC_WARN_UNUSED_RESULT;
 425 GST_API
 426 GstCaps *         gst_caps_new_full_valist         (GstStructure  *structure,
 427                                                     va_list        var_args) G_GNUC_WARN_UNUSED_RESULT;
 428 /**
 429  * gst_static_caps_get_type: (attributes doc.skip=true)
 430  */
 431 GST_API
 432 GType             gst_static_caps_get_type         (void);
 433
 434 GST_API
 435 GstCaps *         gst_static_caps_get              (GstStaticCaps *static_caps);
 436
 437 GST_API
 438 void              gst_static_caps_cleanup          (GstStaticCaps *static_caps);
 439
 440 /* manipulation */
 441
 442 GST_API
 443 void              gst_caps_append                  (GstCaps       *caps1,
 444                                                     GstCaps       *caps2);
 445 GST_API
 446 void              gst_caps_append_structure        (GstCaps       *caps,
 447                                                     GstStructure  *structure);
 448 GST_API
 449 void              gst_caps_append_structure_full   (GstCaps       *caps,
 450                                                     GstStructure  *structure,
 451                                                     GstCapsFeatures *features);
 452 GST_API
 453 void              gst_caps_remove_structure        (GstCaps       *caps, guint idx);
 454
 455 GST_API
 456 GstCaps *         gst_caps_merge                   (GstCaps       *caps1,
 457                                                     GstCaps       *caps2) G_GNUC_WARN_UNUSED_RESULT;
 458 GST_API
 459 GstCaps *         gst_caps_merge_structure         (GstCaps       *caps,
 460                                                     GstStructure  *structure) G_GNUC_WARN_UNUSED_RESULT;
 461 GST_API
 462 GstCaps *         gst_caps_merge_structure_full    (GstCaps       *caps,
 463                                                     GstStructure  *structure,
 464                                                     GstCapsFeatures *features) G_GNUC_WARN_UNUSED_RESULT;
 465
 466 GST_API
 467 guint             gst_caps_get_size                (const GstCaps *caps);
 468
 469 GST_API
 470 GstStructure *    gst_caps_get_structure           (const GstCaps *caps,
 471                                                     guint          index);
 472 GST_API
 473 GstStructure *    gst_caps_steal_structure         (GstCaps       *caps,
 474                                                     guint          index) G_GNUC_WARN_UNUSED_RESULT;
 475 GST_API
 476 void              gst_caps_set_features            (GstCaps *caps,
 477                                                     guint          index,
 478                                                     GstCapsFeatures * features);
 479 GST_API
 480 void              gst_caps_set_features_simple        (GstCaps *caps,
 481                                                        GstCapsFeatures * features);
 482
 483 GST_API
 484 GstCapsFeatures * gst_caps_get_features            (const GstCaps *caps,
 485                                                     guint          index);
 486 GST_API
 487 GstCaps *         gst_caps_copy_nth                (const GstCaps *caps, guint nth) G_GNUC_WARN_UNUSED_RESULT;
 488
 489 GST_API
 490 GstCaps *         gst_caps_truncate                (GstCaps       *caps) G_GNUC_WARN_UNUSED_RESULT;
 491
 492 GST_API
 493 void              gst_caps_set_value               (GstCaps       *caps,
 494                                                     const char    *field,
 495                                                     const GValue  *value);
 496 GST_API
 497 void              gst_caps_set_simple              (GstCaps       *caps,
 498                                                     const char    *field, ...) G_GNUC_NULL_TERMINATED;
 499 GST_API
 500 void              gst_caps_set_simple_valist       (GstCaps       *caps,
 501                                                     const char    *field,
 502                                                     va_list        varargs);
 503 GST_API
 504 gboolean          gst_caps_foreach                 (const GstCaps       *caps,
 505                                                     GstCapsForeachFunc   func,
 506                                                     gpointer             user_data);
 507 GST_API
 508 gboolean          gst_caps_map_in_place            (GstCaps        *caps,
 509                                                     GstCapsMapFunc  func,
 510                                                     gpointer        user_data);
 511 GST_API
 512 void              gst_caps_filter_and_map_in_place (GstCaps              *caps,
 513                                                     GstCapsFilterMapFunc  func,
 514                                                     gpointer              user_data);
 515
 516 /* tests */
 517
 518 GST_API
 519 gboolean          gst_caps_is_any                  (const GstCaps *caps);
 520
 521 GST_API
 522 gboolean          gst_caps_is_empty                (const GstCaps *caps);
 523
 524 GST_API
 525 gboolean          gst_caps_is_fixed                (const GstCaps *caps);
 526
 527 GST_API
 528 gboolean          gst_caps_is_always_compatible    (const GstCaps *caps1,
 529                                                     const GstCaps *caps2);
 530 GST_API
 531 gboolean          gst_caps_is_subset               (const GstCaps *subset,
 532                                                     const GstCaps *superset);
 533 GST_API
 534 gboolean          gst_caps_is_subset_structure     (const GstCaps *caps,
 535                                                     const GstStructure *structure);
 536 GST_API
 537 gboolean          gst_caps_is_subset_structure_full (const GstCaps *caps,
 538                                                      const GstStructure *structure,
 539                                                      const GstCapsFeatures *features);
 540 GST_API
 541 gboolean          gst_caps_is_equal                (const GstCaps *caps1,
 542                                                     const GstCaps *caps2);
 543 GST_API
 544 gboolean          gst_caps_is_equal_fixed          (const GstCaps *caps1,
 545                                                     const GstCaps *caps2);
 546 GST_API
 547 gboolean          gst_caps_can_intersect           (const GstCaps * caps1,
 548                                                     const GstCaps * caps2);
 549 GST_API
 550 gboolean          gst_caps_is_strictly_equal       (const GstCaps *caps1,
 551                                                     const GstCaps *caps2);
 552
 553
 554 /* operations */
 555
 556 GST_API
 557 GstCaps *         gst_caps_intersect               (GstCaps *caps1,
 558                                                     GstCaps *caps2) G_GNUC_WARN_UNUSED_RESULT;
 559 GST_API
 560 GstCaps *         gst_caps_intersect_full          (GstCaps *caps1,
 561                                                     GstCaps *caps2,
 562                                                     GstCapsIntersectMode mode) G_GNUC_WARN_UNUSED_RESULT;
 563 GST_API
 564 GstCaps *         gst_caps_subtract                (GstCaps *minuend,
 565                                                     GstCaps *subtrahend) G_GNUC_WARN_UNUSED_RESULT;
 566 GST_API
 567 GstCaps *         gst_caps_normalize               (GstCaps *caps) G_GNUC_WARN_UNUSED_RESULT;
 568
 569 GST_API
 570 GstCaps *         gst_caps_simplify                (GstCaps *caps) G_GNUC_WARN_UNUSED_RESULT;
 571
 572 GST_API
 573 GstCaps *         gst_caps_fixate                  (GstCaps *caps) G_GNUC_WARN_UNUSED_RESULT;
 574
 575 /* utility */
 576
 577 GST_API
 578 gchar *           gst_caps_to_string               (const GstCaps *caps) G_GNUC_MALLOC;
 579
 580 GST_API
 581 GstCaps *         gst_caps_from_string             (const gchar   *string) G_GNUC_WARN_UNUSED_RESULT;
 582
 583 #ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC
 584 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstCaps, gst_caps_unref)
 585 #endif
 586
 587 G_END_DECLS
 588
 589 #endif /* __GST_CAPS_H__ */