1 /*
2  * This file is part of gtkD.
3  *
4  * gtkD is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU Lesser General Public License
6  * as published by the Free Software Foundation; either version 3
7  * of the License, or (at your option) any later version, with
8  * some exceptions, please read the COPYING file.
9  *
10  * gtkD is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13  * GNU Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public License
16  * along with gtkD; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
18  */
19 
20 // generated automatically - do not change
21 // find conversion definition on APILookup.txt
22 // implement new conversion functionalities on the wrap.utils pakage
23 
24 
25 module gstreamer.Caps;
26 
27 private import glib.ConstructionException;
28 private import glib.Str;
29 private import gobject.ObjectG;
30 private import gobject.Value;
31 private import gstreamer.CapsFeatures;
32 private import gstreamer.Structure;
33 private import gstreamerc.gstreamer;
34 public  import gstreamerc.gstreamertypes;
35 
36 
37 /**
38  * Caps (capabilities) are lightweight refcounted objects describing media types.
39  * They are composed of an array of #GstStructure.
40  * 
41  * Caps are exposed on #GstPadTemplate to describe all possible types a
42  * given pad can handle. They are also stored in the #GstRegistry along with
43  * a description of the #GstElement.
44  * 
45  * Caps are exposed on the element pads using the gst_pad_query_caps() pad
46  * function. This function describes the possible types that the pad can
47  * handle or produce at runtime.
48  * 
49  * A #GstCaps can be constructed with the following code fragment:
50  * |[<!-- language="C" -->
51  * GstCaps *caps = gst_caps_new_simple ("video/x-raw",
52  * "format", G_TYPE_STRING, "I420",
53  * "framerate", GST_TYPE_FRACTION, 25, 1,
54  * "pixel-aspect-ratio", GST_TYPE_FRACTION, 1, 1,
55  * "width", G_TYPE_INT, 320,
56  * "height", G_TYPE_INT, 240,
57  * NULL);
58  * ]|
59  * 
60  * A #GstCaps is fixed when it has no properties with ranges or lists. Use
61  * gst_caps_is_fixed() to test for fixed caps. Fixed caps can be used in a
62  * caps event to notify downstream elements of the current media type.
63  * 
64  * Various methods exist to work with the media types such as subtracting
65  * or intersecting.
66  * 
67  * Be aware that the current #GstCaps / #GstStructure serialization into string
68  * has limited support for nested #GstCaps / #GstStructure fields. It can only
69  * support one level of nesting. Using more levels will lead to unexpected
70  * behavior when using serialization features, such as gst_caps_to_string() or
71  * gst_value_serialize() and their counterparts.
72  */
73 public class Caps
74 {
75 	/** the main Gtk struct */
76 	protected GstCaps* gstCaps;
77 	protected bool ownedRef;
78 
79 	/** Get the main Gtk struct */
80 	public GstCaps* getCapsStruct()
81 	{
82 		return gstCaps;
83 	}
84 
85 	/** the main Gtk struct as a void* */
86 	protected void* getStruct()
87 	{
88 		return cast(void*)gstCaps;
89 	}
90 
91 	/**
92 	 * Sets our main struct and passes it to the parent class.
93 	 */
94 	public this (GstCaps* gstCaps, bool ownedRef = false)
95 	{
96 		this.gstCaps = gstCaps;
97 		this.ownedRef = ownedRef;
98 	}
99 
100 	/**
101 	 * Creates a new GstCaps that indicates that it is compatible with
102 	 * any media format.
103 	 * Returns:
104 	 *  the new GstCaps
105 	 */
106 	public static Caps newAny()
107 	{
108 		// GstCaps* gst_caps_new_any (void);
109 		auto p = cast(GstCaps*)gst_caps_new_any();
110 		
111 		if(p is null)
112 		{
113 			throw new ConstructionException("null returned by gst_caps_new_any");
114 		}
115 		
116 		return new Caps(cast(GstCaps*)p); //, true);
117 	}
118 
119 	/**
120 	 */
121 
122 	/** */
123 	public static GType getType()
124 	{
125 		return gst_caps_get_type();
126 	}
127 
128 	/**
129 	 * Creates a new #GstCaps that is empty.  That is, the returned
130 	 * #GstCaps contains no media formats.
131 	 * The #GstCaps is guaranteed to be writable.
132 	 * Caller is responsible for unreffing the returned caps.
133 	 *
134 	 * Return: the new #GstCaps
135 	 *
136 	 * Throws: ConstructionException GTK+ fails to create the object.
137 	 */
138 	public this()
139 	{
140 		auto p = gst_caps_new_empty();
141 		
142 		if(p is null)
143 		{
144 			throw new ConstructionException("null returned by new_empty");
145 		}
146 		
147 		this(cast(GstCaps*) p);
148 	}
149 
150 	/**
151 	 * Creates a new #GstCaps that contains one #GstStructure with name
152 	 * @media_type.
153 	 * Caller is responsible for unreffing the returned caps.
154 	 *
155 	 * Params:
156 	 *     mediaType = the media type of the structure
157 	 *
158 	 * Return: the new #GstCaps
159 	 *
160 	 * Throws: ConstructionException GTK+ fails to create the object.
161 	 */
162 	public this(string mediaType)
163 	{
164 		auto p = gst_caps_new_empty_simple(Str.toStringz(mediaType));
165 		
166 		if(p is null)
167 		{
168 			throw new ConstructionException("null returned by new_empty_simple");
169 		}
170 		
171 		this(cast(GstCaps*) p);
172 	}
173 
174 	/**
175 	 * Creates a new #GstCaps and adds all the structures listed as
176 	 * arguments.  The list must be %NULL-terminated.  The structures
177 	 * are not copied; the returned #GstCaps owns the structures.
178 	 *
179 	 * Params:
180 	 *     structure = the first structure to add
181 	 *     varArgs = additional structures to add
182 	 *
183 	 * Return: the new #GstCaps
184 	 *
185 	 * Throws: ConstructionException GTK+ fails to create the object.
186 	 */
187 	public this(Structure structure, void* varArgs)
188 	{
189 		auto p = gst_caps_new_full_valist((structure is null) ? null : structure.getStructureStruct(), varArgs);
190 		
191 		if(p is null)
192 		{
193 			throw new ConstructionException("null returned by new_full_valist");
194 		}
195 		
196 		this(cast(GstCaps*) p);
197 	}
198 
199 	/**
200 	 * Appends the structures contained in @caps2 to @caps1. The structures in
201 	 * @caps2 are not copied -- they are transferred to @caps1, and then @caps2 is
202 	 * freed. If either caps is ANY, the resulting caps will be ANY.
203 	 *
204 	 * Params:
205 	 *     caps2 = the #GstCaps to append
206 	 */
207 	public void append(Caps caps2)
208 	{
209 		gst_caps_append(gstCaps, (caps2 is null) ? null : caps2.getCapsStruct());
210 	}
211 
212 	/**
213 	 * Appends @structure to @caps.  The structure is not copied; @caps
214 	 * becomes the owner of @structure.
215 	 *
216 	 * Params:
217 	 *     structure = the #GstStructure to append
218 	 */
219 	public void appendStructure(Structure structure)
220 	{
221 		gst_caps_append_structure(gstCaps, (structure is null) ? null : structure.getStructureStruct());
222 	}
223 
224 	/**
225 	 * Appends @structure with @features to @caps.  The structure is not copied; @caps
226 	 * becomes the owner of @structure.
227 	 *
228 	 * Params:
229 	 *     structure = the #GstStructure to append
230 	 *     features = the #GstCapsFeatures to append
231 	 *
232 	 * Since: 1.2
233 	 */
234 	public void appendStructureFull(Structure structure, CapsFeatures features)
235 	{
236 		gst_caps_append_structure_full(gstCaps, (structure is null) ? null : structure.getStructureStruct(), (features is null) ? null : features.getCapsFeaturesStruct());
237 	}
238 
239 	/**
240 	 * Tries intersecting @caps1 and @caps2 and reports whether the result would not
241 	 * be empty
242 	 *
243 	 * Params:
244 	 *     caps2 = a #GstCaps to intersect
245 	 *
246 	 * Return: %TRUE if intersection would be not empty
247 	 */
248 	public bool canIntersect(Caps caps2)
249 	{
250 		return gst_caps_can_intersect(gstCaps, (caps2 is null) ? null : caps2.getCapsStruct()) != 0;
251 	}
252 
253 	/**
254 	 * Creates a new #GstCaps and appends a copy of the nth structure
255 	 * contained in @caps.
256 	 *
257 	 * Params:
258 	 *     nth = the nth structure to copy
259 	 *
260 	 * Return: the new #GstCaps
261 	 */
262 	public Caps copyNth(uint nth)
263 	{
264 		auto p = gst_caps_copy_nth(gstCaps, nth);
265 		
266 		if(p is null)
267 		{
268 			return null;
269 		}
270 		
271 		return ObjectG.getDObject!(Caps)(cast(GstCaps*) p, true);
272 	}
273 
274 	/**
275 	 * Calls the provided function once for each structure and caps feature in the
276 	 * #GstCaps. In contrast to gst_caps_foreach(), the function may modify the
277 	 * structure and features. In contrast to gst_caps_filter_and_map_in_place(),
278 	 * the structure and features are removed from the caps if %FALSE is returned
279 	 * from the function.
280 	 * The caps must be mutable.
281 	 *
282 	 * Params:
283 	 *     func = a function to call for each field
284 	 *     userData = private data
285 	 *
286 	 * Since: 1.6
287 	 */
288 	public void filterAndMapInPlace(GstCapsFilterMapFunc func, void* userData)
289 	{
290 		gst_caps_filter_and_map_in_place(gstCaps, func, userData);
291 	}
292 
293 	/**
294 	 * Modifies the given @caps into a representation with only fixed
295 	 * values. First the caps will be truncated and then the first structure will be
296 	 * fixated with gst_structure_fixate().
297 	 *
298 	 * This function takes ownership of @caps and will call gst_caps_make_writable()
299 	 * on it so you must not use @caps afterwards unless you keep an additional
300 	 * reference to it with gst_caps_ref().
301 	 *
302 	 * Return: the fixated caps
303 	 */
304 	public Caps fixate()
305 	{
306 		auto p = gst_caps_fixate(gstCaps);
307 		
308 		if(p is null)
309 		{
310 			return null;
311 		}
312 		
313 		return ObjectG.getDObject!(Caps)(cast(GstCaps*) p, true);
314 	}
315 
316 	/**
317 	 * Calls the provided function once for each structure and caps feature in the
318 	 * #GstCaps. The function must not modify the fields.
319 	 * Also see gst_caps_map_in_place() and gst_caps_filter_and_map_in_place().
320 	 *
321 	 * Params:
322 	 *     func = a function to call for each field
323 	 *     userData = private data
324 	 *
325 	 * Return: %TRUE if the supplied function returns %TRUE for each call,
326 	 *     %FALSE otherwise.
327 	 *
328 	 * Since: 1.6
329 	 */
330 	public bool foreac(GstCapsForeachFunc func, void* userData)
331 	{
332 		return gst_caps_foreach(gstCaps, func, userData) != 0;
333 	}
334 
335 	/**
336 	 * Finds the features in @caps that has the index @index, and
337 	 * returns it.
338 	 *
339 	 * WARNING: This function takes a const GstCaps *, but returns a
340 	 * non-const GstCapsFeatures *.  This is for programming convenience --
341 	 * the caller should be aware that structures inside a constant
342 	 * #GstCaps should not be modified. However, if you know the caps
343 	 * are writable, either because you have just copied them or made
344 	 * them writable with gst_caps_make_writable(), you may modify the
345 	 * features returned in the usual way, e.g. with functions like
346 	 * gst_caps_features_add().
347 	 *
348 	 * You do not need to free or unref the structure returned, it
349 	 * belongs to the #GstCaps.
350 	 *
351 	 * Params:
352 	 *     index = the index of the structure
353 	 *
354 	 * Return: a pointer to the #GstCapsFeatures corresponding
355 	 *     to @index
356 	 *
357 	 * Since: 1.2
358 	 */
359 	public CapsFeatures getFeatures(uint index)
360 	{
361 		auto p = gst_caps_get_features(gstCaps, index);
362 		
363 		if(p is null)
364 		{
365 			return null;
366 		}
367 		
368 		return ObjectG.getDObject!(CapsFeatures)(cast(GstCapsFeatures*) p);
369 	}
370 
371 	/**
372 	 * Gets the number of structures contained in @caps.
373 	 *
374 	 * Return: the number of structures that @caps contains
375 	 */
376 	public uint getSize()
377 	{
378 		return gst_caps_get_size(gstCaps);
379 	}
380 
381 	/**
382 	 * Finds the structure in @caps that has the index @index, and
383 	 * returns it.
384 	 *
385 	 * WARNING: This function takes a const GstCaps *, but returns a
386 	 * non-const GstStructure *.  This is for programming convenience --
387 	 * the caller should be aware that structures inside a constant
388 	 * #GstCaps should not be modified. However, if you know the caps
389 	 * are writable, either because you have just copied them or made
390 	 * them writable with gst_caps_make_writable(), you may modify the
391 	 * structure returned in the usual way, e.g. with functions like
392 	 * gst_structure_set().
393 	 *
394 	 * You do not need to free or unref the structure returned, it
395 	 * belongs to the #GstCaps.
396 	 *
397 	 * Params:
398 	 *     index = the index of the structure
399 	 *
400 	 * Return: a pointer to the #GstStructure corresponding
401 	 *     to @index
402 	 */
403 	public Structure getStructure(uint index)
404 	{
405 		auto p = gst_caps_get_structure(gstCaps, index);
406 		
407 		if(p is null)
408 		{
409 			return null;
410 		}
411 		
412 		return ObjectG.getDObject!(Structure)(cast(GstStructure*) p);
413 	}
414 
415 	/**
416 	 * Creates a new #GstCaps that contains all the formats that are common
417 	 * to both @caps1 and @caps2. Defaults to %GST_CAPS_INTERSECT_ZIG_ZAG mode.
418 	 *
419 	 * Params:
420 	 *     caps2 = a #GstCaps to intersect
421 	 *
422 	 * Return: the new #GstCaps
423 	 */
424 	public Caps intersect(Caps caps2)
425 	{
426 		auto p = gst_caps_intersect(gstCaps, (caps2 is null) ? null : caps2.getCapsStruct());
427 		
428 		if(p is null)
429 		{
430 			return null;
431 		}
432 		
433 		return ObjectG.getDObject!(Caps)(cast(GstCaps*) p, true);
434 	}
435 
436 	/**
437 	 * Creates a new #GstCaps that contains all the formats that are common
438 	 * to both @caps1 and @caps2, the order is defined by the #GstCapsIntersectMode
439 	 * used.
440 	 *
441 	 * Params:
442 	 *     caps2 = a #GstCaps to intersect
443 	 *     mode = The intersection algorithm/mode to use
444 	 *
445 	 * Return: the new #GstCaps
446 	 */
447 	public Caps intersectFull(Caps caps2, GstCapsIntersectMode mode)
448 	{
449 		auto p = gst_caps_intersect_full(gstCaps, (caps2 is null) ? null : caps2.getCapsStruct(), mode);
450 		
451 		if(p is null)
452 		{
453 			return null;
454 		}
455 		
456 		return ObjectG.getDObject!(Caps)(cast(GstCaps*) p, true);
457 	}
458 
459 	/**
460 	 * A given #GstCaps structure is always compatible with another if
461 	 * every media format that is in the first is also contained in the
462 	 * second.  That is, @caps1 is a subset of @caps2.
463 	 *
464 	 * Params:
465 	 *     caps2 = the #GstCaps to test
466 	 *
467 	 * Return: %TRUE if @caps1 is a subset of @caps2.
468 	 */
469 	public bool isAlwaysCompatible(Caps caps2)
470 	{
471 		return gst_caps_is_always_compatible(gstCaps, (caps2 is null) ? null : caps2.getCapsStruct()) != 0;
472 	}
473 
474 	/**
475 	 * Determines if @caps represents any media format.
476 	 *
477 	 * Return: %TRUE if @caps represents any format.
478 	 */
479 	public bool isAny()
480 	{
481 		return gst_caps_is_any(gstCaps) != 0;
482 	}
483 
484 	/**
485 	 * Determines if @caps represents no media formats.
486 	 *
487 	 * Return: %TRUE if @caps represents no formats.
488 	 */
489 	public bool isEmpty()
490 	{
491 		return gst_caps_is_empty(gstCaps) != 0;
492 	}
493 
494 	/**
495 	 * Checks if the given caps represent the same set of caps.
496 	 *
497 	 * Params:
498 	 *     caps2 = another #GstCaps
499 	 *
500 	 * Return: %TRUE if both caps are equal.
501 	 */
502 	public bool isEqual(Caps caps2)
503 	{
504 		return gst_caps_is_equal(gstCaps, (caps2 is null) ? null : caps2.getCapsStruct()) != 0;
505 	}
506 
507 	/**
508 	 * Tests if two #GstCaps are equal.  This function only works on fixed
509 	 * #GstCaps.
510 	 *
511 	 * Params:
512 	 *     caps2 = the #GstCaps to test
513 	 *
514 	 * Return: %TRUE if the arguments represent the same format
515 	 */
516 	public bool isEqualFixed(Caps caps2)
517 	{
518 		return gst_caps_is_equal_fixed(gstCaps, (caps2 is null) ? null : caps2.getCapsStruct()) != 0;
519 	}
520 
521 	/**
522 	 * Fixed #GstCaps describe exactly one format, that is, they have exactly
523 	 * one structure, and each field in the structure describes a fixed type.
524 	 * Examples of non-fixed types are GST_TYPE_INT_RANGE and GST_TYPE_LIST.
525 	 *
526 	 * Return: %TRUE if @caps is fixed
527 	 */
528 	public bool isFixed()
529 	{
530 		return gst_caps_is_fixed(gstCaps) != 0;
531 	}
532 
533 	/**
534 	 * Checks if the given caps are exactly the same set of caps.
535 	 *
536 	 * Params:
537 	 *     caps2 = another #GstCaps
538 	 *
539 	 * Return: %TRUE if both caps are strictly equal.
540 	 */
541 	public bool isStrictlyEqual(Caps caps2)
542 	{
543 		return gst_caps_is_strictly_equal(gstCaps, (caps2 is null) ? null : caps2.getCapsStruct()) != 0;
544 	}
545 
546 	/**
547 	 * Checks if all caps represented by @subset are also represented by @superset.
548 	 *
549 	 * Params:
550 	 *     superset = a potentially greater #GstCaps
551 	 *
552 	 * Return: %TRUE if @subset is a subset of @superset
553 	 */
554 	public bool isSubset(Caps superset)
555 	{
556 		return gst_caps_is_subset(gstCaps, (superset is null) ? null : superset.getCapsStruct()) != 0;
557 	}
558 
559 	/**
560 	 * Checks if @structure is a subset of @caps. See gst_caps_is_subset()
561 	 * for more information.
562 	 *
563 	 * Params:
564 	 *     structure = a potential #GstStructure subset of @caps
565 	 *
566 	 * Return: %TRUE if @structure is a subset of @caps
567 	 */
568 	public bool isSubsetStructure(Structure structure)
569 	{
570 		return gst_caps_is_subset_structure(gstCaps, (structure is null) ? null : structure.getStructureStruct()) != 0;
571 	}
572 
573 	/**
574 	 * Checks if @structure is a subset of @caps. See gst_caps_is_subset()
575 	 * for more information.
576 	 *
577 	 * Params:
578 	 *     structure = a potential #GstStructure subset of @caps
579 	 *     features = a #GstCapsFeatures for @structure
580 	 *
581 	 * Return: %TRUE if @structure is a subset of @caps
582 	 *
583 	 * Since: 1.2
584 	 */
585 	public bool isSubsetStructureFull(Structure structure, CapsFeatures features)
586 	{
587 		return gst_caps_is_subset_structure_full(gstCaps, (structure is null) ? null : structure.getStructureStruct(), (features is null) ? null : features.getCapsFeaturesStruct()) != 0;
588 	}
589 
590 	/**
591 	 * Calls the provided function once for each structure and caps feature in the
592 	 * #GstCaps. In contrast to gst_caps_foreach(), the function may modify but not
593 	 * delete the structures and features. The caps must be mutable.
594 	 *
595 	 * Params:
596 	 *     func = a function to call for each field
597 	 *     userData = private data
598 	 *
599 	 * Return: %TRUE if the supplied function returns %TRUE for each call,
600 	 *     %FALSE otherwise.
601 	 *
602 	 * Since: 1.6
603 	 */
604 	public bool mapInPlace(GstCapsMapFunc func, void* userData)
605 	{
606 		return gst_caps_map_in_place(gstCaps, func, userData) != 0;
607 	}
608 
609 	/**
610 	 * Appends the structures contained in @caps2 to @caps1 if they are not yet
611 	 * expressed by @caps1. The structures in @caps2 are not copied -- they are
612 	 * transferred to a writable copy of @caps1, and then @caps2 is freed.
613 	 * If either caps is ANY, the resulting caps will be ANY.
614 	 *
615 	 * Params:
616 	 *     caps2 = the #GstCaps to merge in
617 	 *
618 	 * Return: the merged caps.
619 	 */
620 	public Caps merge(Caps caps2)
621 	{
622 		auto p = gst_caps_merge(gstCaps, (caps2 is null) ? null : caps2.getCapsStruct());
623 		
624 		if(p is null)
625 		{
626 			return null;
627 		}
628 		
629 		return ObjectG.getDObject!(Caps)(cast(GstCaps*) p, true);
630 	}
631 
632 	/**
633 	 * Appends @structure to @caps if its not already expressed by @caps.
634 	 *
635 	 * Params:
636 	 *     structure = the #GstStructure to merge
637 	 *
638 	 * Return: the merged caps.
639 	 */
640 	public Caps mergeStructure(Structure structure)
641 	{
642 		auto p = gst_caps_merge_structure(gstCaps, (structure is null) ? null : structure.getStructureStruct());
643 		
644 		if(p is null)
645 		{
646 			return null;
647 		}
648 		
649 		return ObjectG.getDObject!(Caps)(cast(GstCaps*) p, true);
650 	}
651 
652 	/**
653 	 * Appends @structure with @features to @caps if its not already expressed by @caps.
654 	 *
655 	 * Params:
656 	 *     structure = the #GstStructure to merge
657 	 *     features = the #GstCapsFeatures to merge
658 	 *
659 	 * Return: the merged caps.
660 	 *
661 	 * Since: 1.2
662 	 */
663 	public Caps mergeStructureFull(Structure structure, CapsFeatures features)
664 	{
665 		auto p = gst_caps_merge_structure_full(gstCaps, (structure is null) ? null : structure.getStructureStruct(), (features is null) ? null : features.getCapsFeaturesStruct());
666 		
667 		if(p is null)
668 		{
669 			return null;
670 		}
671 		
672 		return ObjectG.getDObject!(Caps)(cast(GstCaps*) p, true);
673 	}
674 
675 	/**
676 	 * Returns a #GstCaps that represents the same set of formats as
677 	 * @caps, but contains no lists.  Each list is expanded into separate
678 	 * @GstStructures.
679 	 *
680 	 * This function takes ownership of @caps and will call gst_caps_make_writable()
681 	 * on it so you must not use @caps afterwards unless you keep an additional
682 	 * reference to it with gst_caps_ref().
683 	 *
684 	 * Return: the normalized #GstCaps
685 	 */
686 	public Caps normalize()
687 	{
688 		auto p = gst_caps_normalize(gstCaps);
689 		
690 		if(p is null)
691 		{
692 			return null;
693 		}
694 		
695 		return ObjectG.getDObject!(Caps)(cast(GstCaps*) p, true);
696 	}
697 
698 	/**
699 	 * removes the structure with the given index from the list of structures
700 	 * contained in @caps.
701 	 *
702 	 * Params:
703 	 *     idx = Index of the structure to remove
704 	 */
705 	public void removeStructure(uint idx)
706 	{
707 		gst_caps_remove_structure(gstCaps, idx);
708 	}
709 
710 	/**
711 	 * Sets the #GstCapsFeatures @features for the structure at @index.
712 	 *
713 	 * Params:
714 	 *     index = the index of the structure
715 	 *     features = the #GstCapsFeatures to set
716 	 *
717 	 * Since: 1.2
718 	 */
719 	public void setFeatures(uint index, CapsFeatures features)
720 	{
721 		gst_caps_set_features(gstCaps, index, (features is null) ? null : features.getCapsFeaturesStruct());
722 	}
723 
724 	/**
725 	 * Sets fields in a #GstCaps.  The arguments must be passed in the same
726 	 * manner as gst_structure_set(), and be %NULL-terminated.
727 	 *
728 	 * Params:
729 	 *     field = first field to set
730 	 *     varargs = additional parameters
731 	 */
732 	public void setSimpleValist(string field, void* varargs)
733 	{
734 		gst_caps_set_simple_valist(gstCaps, Str.toStringz(field), varargs);
735 	}
736 
737 	/**
738 	 * Sets the given @field on all structures of @caps to the given @value.
739 	 * This is a convenience function for calling gst_structure_set_value() on
740 	 * all structures of @caps.
741 	 *
742 	 * Params:
743 	 *     field = name of the field to set
744 	 *     value = value to set the field to
745 	 */
746 	public void setValue(string field, Value value)
747 	{
748 		gst_caps_set_value(gstCaps, Str.toStringz(field), (value is null) ? null : value.getValueStruct());
749 	}
750 
751 	/**
752 	 * Converts the given @caps into a representation that represents the
753 	 * same set of formats, but in a simpler form.  Component structures that are
754 	 * identical are merged.  Component structures that have values that can be
755 	 * merged are also merged.
756 	 *
757 	 * This function takes ownership of @caps and will call gst_caps_make_writable()
758 	 * on it if necessary, so you must not use @caps afterwards unless you keep an
759 	 * additional reference to it with gst_caps_ref().
760 	 *
761 	 * This method does not preserve the original order of @caps.
762 	 *
763 	 * Return: The simplified caps.
764 	 */
765 	public Caps simplify()
766 	{
767 		auto p = gst_caps_simplify(gstCaps);
768 		
769 		if(p is null)
770 		{
771 			return null;
772 		}
773 		
774 		return ObjectG.getDObject!(Caps)(cast(GstCaps*) p, true);
775 	}
776 
777 	/**
778 	 * Retrieves the structure with the given index from the list of structures
779 	 * contained in @caps. The caller becomes the owner of the returned structure.
780 	 *
781 	 * Params:
782 	 *     index = Index of the structure to retrieve
783 	 *
784 	 * Return: a pointer to the #GstStructure corresponding
785 	 *     to @index.
786 	 */
787 	public Structure stealStructure(uint index)
788 	{
789 		auto p = gst_caps_steal_structure(gstCaps, index);
790 		
791 		if(p is null)
792 		{
793 			return null;
794 		}
795 		
796 		return ObjectG.getDObject!(Structure)(cast(GstStructure*) p, true);
797 	}
798 
799 	/**
800 	 * Subtracts the @subtrahend from the @minuend.
801 	 * <note>This function does not work reliably if optional properties for caps
802 	 * are included on one caps and omitted on the other.</note>
803 	 *
804 	 * Params:
805 	 *     subtrahend = #GstCaps to subtract
806 	 *
807 	 * Return: the resulting caps
808 	 */
809 	public Caps subtract(Caps subtrahend)
810 	{
811 		auto p = gst_caps_subtract(gstCaps, (subtrahend is null) ? null : subtrahend.getCapsStruct());
812 		
813 		if(p is null)
814 		{
815 			return null;
816 		}
817 		
818 		return ObjectG.getDObject!(Caps)(cast(GstCaps*) p, true);
819 	}
820 
821 	/**
822 	 * Converts @caps to a string representation.  This string representation
823 	 * can be converted back to a #GstCaps by gst_caps_from_string().
824 	 *
825 	 * For debugging purposes its easier to do something like this:
826 	 * |[<!-- language="C" -->
827 	 * GST_LOG ("caps are %" GST_PTR_FORMAT, caps);
828 	 * ]|
829 	 * This prints the caps in human readable form.
830 	 *
831 	 * The current implementation of serialization will lead to unexpected results
832 	 * when there are nested #GstCaps / #GstStructure deeper than one level.
833 	 *
834 	 * Return: a newly allocated string representing @caps.
835 	 */
836 	public override string toString()
837 	{
838 		auto retStr = gst_caps_to_string(gstCaps);
839 		
840 		scope(exit) Str.freeString(retStr);
841 		return Str.toString(retStr);
842 	}
843 
844 	/**
845 	 * Discard all but the first structure from @caps. Useful when
846 	 * fixating.
847 	 *
848 	 * This function takes ownership of @caps and will call gst_caps_make_writable()
849 	 * on it if necessary, so you must not use @caps afterwards unless you keep an
850 	 * additional reference to it with gst_caps_ref().
851 	 *
852 	 * Return: truncated caps
853 	 */
854 	public Caps truncate()
855 	{
856 		auto p = gst_caps_truncate(gstCaps);
857 		
858 		if(p is null)
859 		{
860 			return null;
861 		}
862 		
863 		return ObjectG.getDObject!(Caps)(cast(GstCaps*) p, true);
864 	}
865 
866 	/**
867 	 * Converts @caps from a string representation.
868 	 *
869 	 * The current implementation of serialization will lead to unexpected results
870 	 * when there are nested #GstCaps / #GstStructure deeper than one level.
871 	 *
872 	 * Params:
873 	 *     str = a string to convert to #GstCaps
874 	 *
875 	 * Return: a newly allocated #GstCaps
876 	 */
877 	public static Caps fromString(string str)
878 	{
879 		auto p = gst_caps_from_string(Str.toStringz(str));
880 		
881 		if(p is null)
882 		{
883 			return null;
884 		}
885 		
886 		return ObjectG.getDObject!(Caps)(cast(GstCaps*) p, true);
887 	}
888 }