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