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
29G_BEGIN_DECLS
30
31GST_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 */
47typedef 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 */
78typedef 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
137typedef struct _GstCaps GstCaps;
138typedef struct _GstStaticCaps GstStaticCaps;
139
140GST_API GstCaps * _gst_caps_any;
141
142GST_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 */
194static inline GstCaps *
195gst_caps_ref (GstCaps * caps)
196{
197 return (GstCaps *) gst_mini_object_ref (GST_MINI_OBJECT_CAST (caps));
198}
199
200static inline void
201gst_caps_unref (GstCaps * caps)
202{
203 gst_mini_object_unref (GST_MINI_OBJECT_CAST (caps));
204}
205
206static inline void
207gst_clear_caps (GstCaps ** caps_ptr)
208{
209 gst_clear_mini_object ((GstMiniObject **) caps_ptr);
210}
211#else /* GST_DISABLE_MINIOBJECT_INLINE_FUNCTIONS */
212GST_API
213GstCaps * gst_caps_ref (GstCaps * caps);
214
215GST_API
216void gst_caps_unref (GstCaps * caps);
217
218GST_API
219void gst_clear_caps (GstCaps ** caps_ptr);
220#endif /* GST_DISABLE_MINIOBJECT_INLINE_FUNCTIONS */
221
222/* copy caps */
223GST_API
224GstCaps * 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
259static inline gboolean
260gst_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
265static inline gboolean
266gst_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 */
271GST_API
272gboolean gst_caps_replace (GstCaps ** old_caps,
273 GstCaps * new_caps);
274
275GST_API
276gboolean 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 */
286struct _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 */
299struct _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 */
322typedef 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 */
338typedef 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 */
355typedef gboolean (*GstCapsFilterMapFunc) (GstCapsFeatures *features,
356 GstStructure *structure,
357 gpointer user_data);
358
359
360GST_API
361GType gst_caps_get_type (void);
362
363GST_API
364GstCaps * gst_caps_new_empty (void);
365
366GST_API
367GstCaps * gst_caps_new_any (void);
368
369GST_API
370GstCaps * gst_caps_new_empty_simple (const char *media_type) G_GNUC_WARN_UNUSED_RESULT;
371
372GST_API
373GstCaps * gst_caps_new_simple (const char *media_type,
374 const char *fieldname,
375 ...) G_GNUC_NULL_TERMINATED G_GNUC_WARN_UNUSED_RESULT;
376GST_API
377GstCaps * gst_caps_new_full (GstStructure *struct1,
378 ...) G_GNUC_NULL_TERMINATED G_GNUC_WARN_UNUSED_RESULT;
379GST_API
380GstCaps * 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 */
385GST_API
386GType gst_static_caps_get_type (void);
387
388GST_API
389GstCaps * gst_static_caps_get (GstStaticCaps *static_caps);
390
391GST_API
392void gst_static_caps_cleanup (GstStaticCaps *static_caps);
393
394/* manipulation */
395
396GST_API
397void gst_caps_append (GstCaps *caps1,
398 GstCaps *caps2);
399GST_API
400void gst_caps_append_structure (GstCaps *caps,
401 GstStructure *structure);
402GST_API
403void gst_caps_append_structure_full (GstCaps *caps,
404 GstStructure *structure,
405 GstCapsFeatures *features);
406GST_API
407void gst_caps_remove_structure (GstCaps *caps, guint idx);
408
409GST_API
410GstCaps * gst_caps_merge (GstCaps *caps1,
411 GstCaps *caps2) G_GNUC_WARN_UNUSED_RESULT;
412GST_API
413GstCaps * gst_caps_merge_structure (GstCaps *caps,
414 GstStructure *structure) G_GNUC_WARN_UNUSED_RESULT;
415GST_API
416GstCaps * gst_caps_merge_structure_full (GstCaps *caps,
417 GstStructure *structure,
418 GstCapsFeatures *features) G_GNUC_WARN_UNUSED_RESULT;
419
420GST_API
421guint gst_caps_get_size (const GstCaps *caps);
422
423GST_API
424GstStructure * gst_caps_get_structure (const GstCaps *caps,
425 guint index);
426GST_API
427GstStructure * gst_caps_steal_structure (GstCaps *caps,
428 guint index) G_GNUC_WARN_UNUSED_RESULT;
429GST_API
430void gst_caps_set_features (GstCaps *caps,
431 guint index,
432 GstCapsFeatures * features);
433GST_API
434void gst_caps_set_features_simple (GstCaps *caps,
435 GstCapsFeatures * features);
436
437GST_API
438GstCapsFeatures * gst_caps_get_features (const GstCaps *caps,
439 guint index);
440GST_API
441GstCaps * gst_caps_copy_nth (const GstCaps *caps, guint nth) G_GNUC_WARN_UNUSED_RESULT;
442
443GST_API
444GstCaps * gst_caps_truncate (GstCaps *caps) G_GNUC_WARN_UNUSED_RESULT;
445
446GST_API
447void gst_caps_set_value (GstCaps *caps,
448 const char *field,
449 const GValue *value);
450GST_API
451void gst_caps_set_simple (GstCaps *caps,
452 const char *field, ...) G_GNUC_NULL_TERMINATED;
453GST_API
454void gst_caps_set_simple_valist (GstCaps *caps,
455 const char *field,
456 va_list varargs);
457GST_API
458gboolean gst_caps_foreach (const GstCaps *caps,
459 GstCapsForeachFunc func,
460 gpointer user_data);
461GST_API
462gboolean gst_caps_map_in_place (GstCaps *caps,
463 GstCapsMapFunc func,
464 gpointer user_data);
465GST_API
466void gst_caps_filter_and_map_in_place (GstCaps *caps,
467 GstCapsFilterMapFunc func,
468 gpointer user_data);
469
470/* tests */
471
472GST_API
473gboolean gst_caps_is_any (const GstCaps *caps);
474
475GST_API
476gboolean gst_caps_is_empty (const GstCaps *caps);
477
478GST_API
479gboolean gst_caps_is_fixed (const GstCaps *caps);
480
481GST_API
482gboolean gst_caps_is_always_compatible (const GstCaps *caps1,
483 const GstCaps *caps2);
484GST_API
485gboolean gst_caps_is_subset (const GstCaps *subset,
486 const GstCaps *superset);
487GST_API
488gboolean gst_caps_is_subset_structure (const GstCaps *caps,
489 const GstStructure *structure);
490GST_API
491gboolean gst_caps_is_subset_structure_full (const GstCaps *caps,
492 const GstStructure *structure,
493 const GstCapsFeatures *features);
494GST_API
495gboolean gst_caps_is_equal (const GstCaps *caps1,
496 const GstCaps *caps2);
497GST_API
498gboolean gst_caps_is_equal_fixed (const GstCaps *caps1,
499 const GstCaps *caps2);
500GST_API
501gboolean gst_caps_can_intersect (const GstCaps * caps1,
502 const GstCaps * caps2);
503GST_API
504gboolean gst_caps_is_strictly_equal (const GstCaps *caps1,
505 const GstCaps *caps2);
506
507
508/* operations */
509
510GST_API
511GstCaps * gst_caps_intersect (GstCaps *caps1,
512 GstCaps *caps2) G_GNUC_WARN_UNUSED_RESULT;
513GST_API
514GstCaps * gst_caps_intersect_full (GstCaps *caps1,
515 GstCaps *caps2,
516 GstCapsIntersectMode mode) G_GNUC_WARN_UNUSED_RESULT;
517GST_API
518GstCaps * gst_caps_subtract (GstCaps *minuend,
519 GstCaps *subtrahend) G_GNUC_WARN_UNUSED_RESULT;
520GST_API
521GstCaps * gst_caps_normalize (GstCaps *caps) G_GNUC_WARN_UNUSED_RESULT;
522
523GST_API
524GstCaps * gst_caps_simplify (GstCaps *caps) G_GNUC_WARN_UNUSED_RESULT;
525
526GST_API
527GstCaps * gst_caps_fixate (GstCaps *caps) G_GNUC_WARN_UNUSED_RESULT;
528
529/* utility */
530
531GST_API
532gchar * gst_caps_to_string (const GstCaps *caps) G_GNUC_MALLOC;
533GST_API
534gchar * gst_caps_serialize (const GstCaps *caps, GstSerializeFlags flags) G_GNUC_MALLOC;
535
536GST_API
537GstCaps * gst_caps_from_string (const gchar *string) G_GNUC_WARN_UNUSED_RESULT;
538
539G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstCaps, gst_caps_unref)
540
541G_END_DECLS
542
543#endif /* __GST_CAPS_H__ */
544

source code of include/gstreamer-1.0/gst/gstcaps.h