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_NONE: no extra flags (Since 0.10.36)
  38  * @GST_CAPS_FLAGS_ANY: Caps has no specific content, but can contain
  39  *    anything.
  40  *
  41  * Extra flags for a caps.
  42  */
  43 typedef enum {
  44   GST_CAPS_FLAGS_NONE = 0,
  45   GST_CAPS_FLAGS_ANY    = (1 << 0)
  46 } GstCapsFlags;
  47
  48 /**
  49  * GstCapsIntersectMode:
  50  * @GST_CAPS_INTERSECT_ZIG_ZAG  : Zig-zags over both caps.
  51  * @GST_CAPS_INTERSECT_FIRST    : Keeps the first caps order.
  52  *
  53  * Modes of caps intersection
  54  *
  55  * @GST_CAPS_INTERSECT_ZIG_ZAG tries to preserve overall order of both caps
  56  * by iterating on the caps' structures as the following matrix shows:
  57  * |[
  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 #ifndef GST_DISABLE_DEPRECATED
 120 /**
 121  * GST_DEBUG_CAPS:
 122  * @string: a string that should be prepended to the caps data.
 123  * @caps: the #GstCaps instance to print
 124  *
 125  * Convenience macro for printing out the contents of caps with GST_DEBUG().
 126  *
 127  * Deprecated: do not use anymore
 128  */
 129 #define GST_DEBUG_CAPS(string, caps) \
 130   GST_DEBUG ( string "%s: " GST_PTR_FORMAT, caps)
 131
 132 #endif /* GST_DISABLE_DEPRECATED */
 133
 134 /**
 135  * GST_STATIC_CAPS:
 136  * @string: the string describing the caps
 137  *
 138  * Creates a new #GstCaps static caps from an input string.
 139  * This can be used in pad templates.
 140  */
 141 #define GST_STATIC_CAPS(string) \
 142 { \
 143   /* caps */ { 0, 0, (GstCapsFlags) 0, NULL, GST_PADDING_INIT }, \
 144   /* string */ string, \
 145   GST_PADDING_INIT \
 146 }
 147
 148 typedef struct _GstCaps GstCaps;
 149 typedef struct _GstStaticCaps GstStaticCaps;
 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_CAPS(caps))->refcount)
 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)           (g_atomic_int_get (&(GST_CAPS(caps))->refcount))
 166
 167 /**
 168  * GstCaps:
 169  * @type: GType of the caps
 170  * @refcount: the atomic refcount value
 171  * @flags: extra flags for the caps, read only.
 172  *
 173  * Object describing media types.
 174  */
 175 struct _GstCaps {
 176   GType type;
 177
 178   /*< public >*/ /* with COW */
 179   /* refcounting */
 180   gint           refcount;
 181
 182   /*< public >*/ /* read only */
 183   GstCapsFlags flags;
 184
 185   /*< private >*/
 186   GPtrArray *structs;
 187
 188   /*< private >*/
 189   gpointer _gst_reserved[GST_PADDING];
 190 };
 191
 192 /**
 193  * GstStaticCaps:
 194  * @caps: the cached #GstCaps
 195  * @string: a string describing a caps
 196  *
 197  * Datastructure to initialize #GstCaps from a string description usually
 198  * used in conjunction with GST_STATIC_CAPS() and gst_static_caps_get() to
 199  * instantiate a #GstCaps.
 200  */
 201 struct _GstStaticCaps {
 202   /*< public >*/
 203   GstCaps caps;
 204   const char *string;
 205
 206   /*< private >*/
 207   gpointer _gst_reserved[GST_PADDING];
 208 };
 209
 210 GType             gst_caps_get_type                (void);
 211 GstCaps *         gst_caps_new_empty               (void) G_GNUC_MALLOC;
 212 GstCaps *         gst_caps_new_any                 (void) G_GNUC_MALLOC;
 213 GstCaps *         gst_caps_new_simple              (const char    *media_type,
 214                                                     const char    *fieldname,
 215                                                     ...) G_GNUC_MALLOC;
 216 GstCaps *         gst_caps_new_full                (GstStructure  *struct1, ...) G_GNUC_MALLOC;
 217 GstCaps *         gst_caps_new_full_valist         (GstStructure  *structure,
 218                                                     va_list        var_args) G_GNUC_MALLOC;
 219
 220 /* reference counting */
 221 GstCaps *         gst_caps_ref                     (GstCaps       *caps);
 222 GstCaps *         gst_caps_copy                    (const GstCaps *caps) G_GNUC_MALLOC;
 223 GstCaps *         gst_caps_make_writable           (GstCaps       *caps) G_GNUC_WARN_UNUSED_RESULT;
 224 void              gst_caps_unref                   (GstCaps       *caps);
 225
 226 GType             gst_static_caps_get_type         (void);
 227 GstCaps *         gst_static_caps_get              (GstStaticCaps *static_caps);
 228
 229 /* manipulation */
 230 void              gst_caps_append                  (GstCaps       *caps1,
 231                                                     GstCaps       *caps2);
 232 void              gst_caps_merge                   (GstCaps       *caps1,
 233                                                     GstCaps       *caps2);
 234 void              gst_caps_append_structure        (GstCaps       *caps,
 235                                                     GstStructure  *structure);
 236 void              gst_caps_remove_structure        (GstCaps       *caps, guint idx);
 237 void              gst_caps_merge_structure         (GstCaps       *caps,
 238                                                     GstStructure  *structure);
 239 guint             gst_caps_get_size                (const GstCaps *caps);
 240 GstStructure *    gst_caps_get_structure           (const GstCaps *caps,
 241                                                     guint          index);
 242 GstStructure *    gst_caps_steal_structure         (GstCaps *caps,
 243                                                     guint          index) G_GNUC_WARN_UNUSED_RESULT;
 244 GstCaps *         gst_caps_copy_nth                (const GstCaps *caps, guint nth) G_GNUC_MALLOC;
 245 void              gst_caps_truncate                (GstCaps       *caps);
 246 void              gst_caps_set_value               (GstCaps       *caps,
 247                                                     const char    *field,
 248                                                     const GValue  *value);
 249 void              gst_caps_set_simple              (GstCaps       *caps,
 250                                                     const char    *field, ...) G_GNUC_NULL_TERMINATED;
 251 void              gst_caps_set_simple_valist       (GstCaps       *caps,
 252                                                     const char    *field,
 253                                                     va_list        varargs);
 254
 255 /* tests */
 256 gboolean          gst_caps_is_any                  (const GstCaps *caps);
 257 gboolean          gst_caps_is_empty                (const GstCaps *caps);
 258 gboolean          gst_caps_is_fixed                (const GstCaps *caps);
 259 gboolean          gst_caps_is_always_compatible    (const GstCaps *caps1,
 260                                                     const GstCaps *caps2);
 261 gboolean          gst_caps_is_subset               (const GstCaps *subset,
 262                                                     const GstCaps *superset);
 263 gboolean          gst_caps_is_subset_structure     (const GstCaps *caps,
 264                                                     const GstStructure *structure);
 265 gboolean          gst_caps_is_equal                (const GstCaps *caps1,
 266                                                     const GstCaps *caps2);
 267 gboolean          gst_caps_is_equal_fixed          (const GstCaps *caps1,
 268                                                     const GstCaps *caps2);
 269 gboolean          gst_caps_can_intersect           (const GstCaps * caps1,
 270                                                     const GstCaps * caps2);
 271 gboolean          gst_caps_is_strictly_equal       (const GstCaps *caps1,
 272                                                     const GstCaps *caps2);
 273
 274
 275 /* operations */
 276 GstCaps *         gst_caps_intersect               (const GstCaps *caps1,
 277                                                     const GstCaps *caps2) G_GNUC_MALLOC;
 278 GstCaps *         gst_caps_intersect_full          (const GstCaps *caps1,
 279                                                     const GstCaps *caps2,
 280                                                     GstCapsIntersectMode mode) G_GNUC_MALLOC;
 281 GstCaps *         gst_caps_subtract                (const GstCaps *minuend,
 282                                                     const GstCaps *subtrahend) G_GNUC_MALLOC;
 283 GstCaps *         gst_caps_union                   (const GstCaps *caps1,
 284                                                     const GstCaps *caps2) G_GNUC_MALLOC;
 285 GstCaps *         gst_caps_normalize               (const GstCaps *caps) G_GNUC_MALLOC;
 286 gboolean          gst_caps_do_simplify             (GstCaps       *caps);
 287
 288 #if !defined(GST_DISABLE_LOADSAVE) && !defined(GST_DISABLE_DEPRECATED)
 289 xmlNodePtr        gst_caps_save_thyself            (const GstCaps *caps,
 290                                                     xmlNodePtr     parent);
 291 GstCaps *         gst_caps_load_thyself            (xmlNodePtr     parent);
 292 #endif
 293
 294 /* utility */
 295 void              gst_caps_replace                 (GstCaps      **caps,
 296                                                     GstCaps       *newcaps);
 297 gchar *           gst_caps_to_string               (const GstCaps *caps) G_GNUC_MALLOC;
 298 GstCaps *         gst_caps_from_string             (const gchar   *string) G_GNUC_MALLOC;
 299
 300 G_END_DECLS
 301
 302 #endif /* __GST_CAPS_H__ */