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 *
gst_caps_ref(GstCaps * caps)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
gst_caps_unref(GstCaps * caps)201 gst_caps_unref (GstCaps * caps)
202 {
203 gst_mini_object_unref (GST_MINI_OBJECT_CAST (caps));
204 }
205
206 static inline void
gst_clear_caps(GstCaps ** caps_ptr)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
gst_caps_replace(GstCaps ** old_caps,GstCaps * new_caps)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
gst_caps_take(GstCaps ** old_caps,GstCaps * new_caps)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__ */
544