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 (olddata: (GstMiniObject **) old_caps, newdata: (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 (olddata: (GstMiniObject **) old_caps, newdata: (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 | |