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_VALUE_H__ 21 #define __GST_VALUE_H__ 22 23 #include <gst/gstconfig.h> 24 #include <gst/gstcaps.h> 25 #include <gst/gststructure.h> 26 #include <gst/gstcapsfeatures.h> 27 28 G_BEGIN_DECLS 29 30 /** 31 * GST_MAKE_FOURCC: 32 * @a: the first character 33 * @b: the second character 34 * @c: the third character 35 * @d: the fourth character 36 * 37 * Transform four characters into a #guint32 fourcc value with host 38 * endianness. 39 * 40 * |[ 41 * guint32 fourcc = GST_MAKE_FOURCC ('M', 'J', 'P', 'G'); 42 * ]| 43 * 44 */ 45 #define GST_MAKE_FOURCC(a,b,c,d) \ 46 ( (guint32)(a) | ((guint32) (b)) << 8 | ((guint32) (c)) << 16 | ((guint32) (d)) << 24 ) 47 48 /** 49 * GST_STR_FOURCC: 50 * @f: a string with at least four characters 51 * 52 * Transform an input string into a #guint32 fourcc value with host 53 * endianness. 54 * Caller is responsible for ensuring the input string consists of at least 55 * four characters. 56 * 57 * |[ 58 * guint32 fourcc = GST_STR_FOURCC ("MJPG"); 59 * ]| 60 * 61 */ 62 #define GST_STR_FOURCC(f) ((guint32)(((f)[0])|((f)[1]<<8)|((f)[2]<<16)|((f)[3]<<24))) 63 64 /** 65 * GST_FOURCC_FORMAT: (skip): 66 * 67 * Can be used together with #GST_FOURCC_ARGS to properly output a 68 * #guint32 fourcc value in a printf()-style text message. 69 * 70 * |[ 71 * printf ("fourcc: %" GST_FOURCC_FORMAT "\n", GST_FOURCC_ARGS (fcc)); 72 * ]| 73 * 74 */ 75 #define GST_FOURCC_FORMAT "c%c%c%c" 76 77 /** 78 * GST_FOURCC_ARGS: (skip): 79 * @fourcc: a #guint32 fourcc value to output 80 * 81 * Can be used together with #GST_FOURCC_FORMAT to properly output a 82 * #guint32 fourcc value in a printf()-style text message. 83 */ 84 85 #define __GST_PRINT_CHAR(c) \ 86 g_ascii_isprint(c) ? (c) : '.' 87 #define GST_FOURCC_ARGS(fourcc) \ 88 __GST_PRINT_CHAR((fourcc) & 0xff), \ 89 __GST_PRINT_CHAR(((fourcc) >> 8) & 0xff), \ 90 __GST_PRINT_CHAR(((fourcc) >> 16) & 0xff), \ 91 __GST_PRINT_CHAR(((fourcc) >> 24) & 0xff) 92 /** 93 * GST_VALUE_HOLDS_INT_RANGE: 94 * @x: the #GValue to check 95 * 96 * Checks if the given #GValue contains a #GST_TYPE_INT_RANGE value. 97 */ 98 #define GST_VALUE_HOLDS_INT_RANGE(x) ((x) != NULL && G_VALUE_TYPE(x) == _gst_int_range_type) 99 100 /** 101 * GST_VALUE_HOLDS_INT64_RANGE: 102 * @x: the #GValue to check 103 * 104 * Checks if the given #GValue contains a #GST_TYPE_INT64_RANGE value. 105 */ 106 #define GST_VALUE_HOLDS_INT64_RANGE(x) ((x) != NULL && G_VALUE_TYPE(x) == _gst_int64_range_type) 107 108 /** 109 * GST_VALUE_HOLDS_DOUBLE_RANGE: 110 * @x: the #GValue to check 111 * 112 * Checks if the given #GValue contains a #GST_TYPE_DOUBLE_RANGE value. 113 */ 114 #define GST_VALUE_HOLDS_DOUBLE_RANGE(x) ((x) != NULL && G_VALUE_TYPE(x) == _gst_double_range_type) 115 116 /** 117 * GST_VALUE_HOLDS_FRACTION_RANGE: 118 * @x: the #GValue to check 119 * 120 * Checks if the given #GValue contains a #GST_TYPE_FRACTION_RANGE value. 121 */ 122 #define GST_VALUE_HOLDS_FRACTION_RANGE(x) ((x) != NULL && G_VALUE_TYPE(x) == _gst_fraction_range_type) 123 124 /** 125 * GST_VALUE_HOLDS_LIST: 126 * @x: the #GValue to check 127 * 128 * Checks if the given #GValue contains a #GST_TYPE_LIST value. 129 */ 130 #define GST_VALUE_HOLDS_LIST(x) ((x) != NULL && G_VALUE_TYPE(x) == _gst_value_list_type) 131 132 /** 133 * GST_VALUE_HOLDS_ARRAY: 134 * @x: the #GValue to check 135 * 136 * Checks if the given #GValue contains a #GST_TYPE_ARRAY value. 137 */ 138 #define GST_VALUE_HOLDS_ARRAY(x) ((x) != NULL && G_VALUE_TYPE(x) == _gst_value_array_type) 139 140 /** 141 * GST_VALUE_HOLDS_CAPS: 142 * @x: the #GValue to check 143 * 144 * Checks if the given #GValue contains a #GST_TYPE_CAPS value. 145 */ 146 #define GST_VALUE_HOLDS_CAPS(x) ((x) != NULL && G_VALUE_TYPE(x) == _gst_caps_type) 147 148 /** 149 * GST_VALUE_HOLDS_STRUCTURE: 150 * @x: the #GValue to check 151 * 152 * Checks if the given #GValue contains a #GST_TYPE_STRUCTURE value. 153 */ 154 #define GST_VALUE_HOLDS_STRUCTURE(x) (G_VALUE_HOLDS((x), _gst_structure_type)) 155 156 /** 157 * GST_VALUE_HOLDS_CAPS_FEATURES: 158 * @x: the #GValue to check 159 * 160 * Checks if the given #GValue contains a #GST_TYPE_CAPS_FEATURES value. 161 */ 162 #define GST_VALUE_HOLDS_CAPS_FEATURES(x) (G_VALUE_HOLDS((x), _gst_caps_features_type)) 163 164 /** 165 * GST_VALUE_HOLDS_BUFFER: 166 * @x: the #GValue to check 167 * 168 * Checks if the given #GValue contains a #GST_TYPE_BUFFER value. 169 */ 170 #define GST_VALUE_HOLDS_BUFFER(x) ((x) != NULL && G_VALUE_TYPE(x) == _gst_buffer_type) 171 172 /** 173 * GST_VALUE_HOLDS_SAMPLE: 174 * @x: the #GValue to check 175 * 176 * Checks if the given #GValue contains a #GST_TYPE_SAMPLE value. 177 */ 178 #define GST_VALUE_HOLDS_SAMPLE(x) ((x) != NULL && G_VALUE_TYPE(x) == _gst_sample_type) 179 180 /** 181 * GST_VALUE_HOLDS_FRACTION: 182 * @x: the #GValue to check 183 * 184 * Checks if the given #GValue contains a #GST_TYPE_FRACTION value. 185 */ 186 #define GST_VALUE_HOLDS_FRACTION(x) ((x) != NULL && G_VALUE_TYPE(x) == _gst_fraction_type) 187 188 /** 189 * GST_VALUE_HOLDS_DATE_TIME: 190 * @x: the #GValue to check 191 * 192 * Checks if the given #GValue contains a #GST_TYPE_DATE_TIME value. 193 */ 194 #define GST_VALUE_HOLDS_DATE_TIME(x) ((x) != NULL && G_VALUE_TYPE(x) == _gst_date_time_type) 195 196 /** 197 * GST_VALUE_HOLDS_BITMASK: 198 * @x: the #GValue to check 199 * 200 * Checks if the given #GValue contains a #GST_TYPE_BITMASK value. 201 */ 202 #define GST_VALUE_HOLDS_BITMASK(x) ((x) != NULL && G_VALUE_TYPE(x) == _gst_bitmask_type) 203 204 /** 205 * GST_VALUE_HOLDS_FLAG_SET: 206 * @x: the #GValue to check 207 * 208 * Checks if the given #GValue contains a #GST_TYPE_FLAG_SET value. 209 * 210 * Since: 1.6 211 */ 212 #define GST_VALUE_HOLDS_FLAG_SET(x) (G_TYPE_CHECK_VALUE_TYPE ((x), GST_TYPE_FLAG_SET)) 213 214 /** 215 * GST_FLAG_SET_MASK_EXACT: (value 4294967295) (type guint) 216 * 217 * A mask value with all bits set, for use as a 218 * GstFlagSet mask where all flag bits must match 219 * exactly 220 * 221 * Since: 1.6 222 */ 223 #define GST_FLAG_SET_MASK_EXACT ((guint)(-1)) 224 225 GST_API GType _gst_int_range_type; 226 227 /** 228 * GST_TYPE_INT_RANGE: 229 * 230 * a #GValue type that represents an integer range 231 * 232 * Returns: the #GType of GstIntRange 233 */ 234 #define GST_TYPE_INT_RANGE (_gst_int_range_type) 235 236 GST_API GType _gst_int64_range_type; 237 238 /** 239 * GST_TYPE_INT64_RANGE: 240 * 241 * a #GValue type that represents an #gint64 range 242 * 243 * Returns: the #GType of GstInt64Range 244 */ 245 #define GST_TYPE_INT64_RANGE (_gst_int64_range_type) 246 247 GST_API GType _gst_double_range_type; 248 249 /** 250 * GST_TYPE_DOUBLE_RANGE: 251 * 252 * a #GValue type that represents a floating point range with double precision 253 * 254 * Returns: the #GType of GstIntRange 255 */ 256 #define GST_TYPE_DOUBLE_RANGE (_gst_double_range_type) 257 258 GST_API GType _gst_fraction_range_type; 259 260 /** 261 * GST_TYPE_FRACTION_RANGE: 262 * 263 * a #GValue type that represents a GstFraction range 264 * 265 * Returns: the #GType of GstFractionRange 266 */ 267 #define GST_TYPE_FRACTION_RANGE (_gst_fraction_range_type) 268 269 GST_API GType _gst_value_list_type; 270 271 /** 272 * GST_TYPE_LIST: 273 * 274 * a #GValue type that represents an unordered list of #GValue values. This 275 * is used for example to express a list of possible values for a field in 276 * a caps structure, like a list of possible sample rates, of which only one 277 * will be chosen in the end. This means that all values in the list are 278 * meaningful on their own. 279 * 280 * Returns: the #GType of GstValueList (which is not explicitly typed) 281 */ 282 #define GST_TYPE_LIST (_gst_value_list_type) 283 284 GST_API GType _gst_value_array_type; 285 286 /** 287 * GST_TYPE_ARRAY: 288 * 289 * a #GValue type that represents an ordered list of #GValue values. This is 290 * used to express a set of values that is meaningful only in their specific 291 * combination and order of values. Each value on its own is not particularly 292 * meaningful, only the ordered array in its entirety is meaningful. This is 293 * used for example to express channel layouts for multichannel audio where 294 * each channel needs to be mapped to a position in the room. 295 * 296 * Returns: the #GType of GstArrayList (which is not explicitly typed) 297 */ 298 #define GST_TYPE_ARRAY (_gst_value_array_type) 299 300 GST_API GType _gst_fraction_type; 301 302 /** 303 * GST_TYPE_FRACTION: 304 * 305 * a #GValue type that represents a fraction of an integer numerator over 306 * an integer denominator 307 * 308 * Returns: the #GType of GstFraction (which is not explicitly typed) 309 */ 310 311 #define GST_TYPE_FRACTION (_gst_fraction_type) 312 313 GST_API GType _gst_bitmask_type; 314 315 /** 316 * GST_TYPE_BITMASK: 317 * 318 * a #GValue type that represents a 64-bit bitmask. 319 * 320 * Returns: the #GType of GstBitmask (which is not explicitly typed) 321 */ 322 323 #define GST_TYPE_BITMASK (_gst_bitmask_type) 324 325 GST_API GType _gst_flagset_type; 326 327 /** 328 * GST_TYPE_FLAG_SET: 329 * 330 * a #GValue type that represents a 32-bit flag bitfield, with 32-bit 331 * mask indicating which of the bits in the field are explicitly set. 332 * Useful for negotiation. 333 * 334 * Returns: the #GType of GstFlags (which is not explicitly typed) 335 * 336 * Since: 1.6 337 */ 338 #define GST_TYPE_FLAG_SET (_gst_flagset_type) 339 340 /** 341 * GST_TYPE_G_THREAD: 342 * 343 * a boxed #GValue type for #GThread that represents a thread. 344 * 345 * Returns: the #GType of GstGThread 346 */ 347 348 #define GST_TYPE_G_THREAD gst_g_thread_get_type () 349 350 /** 351 * GST_VALUE_LESS_THAN: 352 * 353 * Indicates that the first value provided to a comparison function 354 * (gst_value_compare()) is lesser than the second one. 355 */ 356 #define GST_VALUE_LESS_THAN (-1) 357 358 /** 359 * GST_VALUE_EQUAL: 360 * 361 * Indicates that the first value provided to a comparison function 362 * (gst_value_compare()) is equal to the second one. 363 */ 364 #define GST_VALUE_EQUAL 0 365 366 /** 367 * GST_VALUE_GREATER_THAN: 368 * 369 * Indicates that the first value provided to a comparison function 370 * (gst_value_compare()) is greater than the second one. 371 */ 372 #define GST_VALUE_GREATER_THAN 1 373 374 /** 375 * GST_VALUE_UNORDERED: 376 * 377 * Indicates that the comparison function (gst_value_compare()) can not 378 * determine a order for the two provided values. 379 */ 380 #define GST_VALUE_UNORDERED 2 381 382 /** 383 * GstValueCompareFunc: 384 * @value1: first value for comparison 385 * @value2: second value for comparison 386 * 387 * Used together with gst_value_compare() to compare #GValue items. 388 * 389 * Returns: one of GST_VALUE_LESS_THAN, GST_VALUE_EQUAL, GST_VALUE_GREATER_THAN 390 * or GST_VALUE_UNORDERED 391 */ 392 typedef gint (* GstValueCompareFunc) (const GValue *value1, 393 const GValue *value2); 394 395 /** 396 * GstValueSerializeFunc: 397 * @value1: a #GValue 398 * 399 * Used by gst_value_serialize() to obtain a non-binary form of the #GValue. 400 * 401 * Free-function: g_free 402 * 403 * Returns: (transfer full): the string representation of the value 404 */ 405 typedef gchar * (* GstValueSerializeFunc) (const GValue *value1); 406 407 /** 408 * GstValueDeserializeFunc: 409 * @dest: a #GValue 410 * @s: a string 411 * 412 * Used by gst_value_deserialize() to parse a non-binary form into the #GValue. 413 * 414 * Returns: %TRUE for success 415 */ 416 typedef gboolean (* GstValueDeserializeFunc) (GValue *dest, 417 const gchar *s); 418 419 typedef struct _GstValueTable GstValueTable; 420 /** 421 * GstValueTable: 422 * @type: a #GType 423 * @compare: a #GstValueCompareFunc 424 * @serialize: a #GstValueSerializeFunc 425 * @deserialize: a #GstValueDeserializeFunc 426 * 427 * VTable for the #GValue @type. 428 */ 429 struct _GstValueTable { 430 GType type; 431 GstValueCompareFunc compare; 432 GstValueSerializeFunc serialize; 433 GstValueDeserializeFunc deserialize; 434 435 /*< private >*/ 436 gpointer _gst_reserved [GST_PADDING]; 437 }; 438 439 GST_API 440 GType gst_int_range_get_type (void); 441 442 GST_API 443 GType gst_int64_range_get_type (void); 444 445 GST_API 446 GType gst_double_range_get_type (void); 447 448 GST_API 449 GType gst_fraction_range_get_type (void); 450 451 GST_API 452 GType gst_fraction_get_type (void); 453 454 GST_API 455 GType gst_value_list_get_type (void); 456 457 GST_API 458 GType gst_value_array_get_type (void); 459 460 GST_API 461 GType gst_bitmask_get_type (void); 462 463 GST_API 464 GType gst_flagset_get_type (void); 465 466 /* Hide this compatibility type from introspection */ 467 #ifndef __GI_SCANNER__ 468 GST_API 469 GType gst_g_thread_get_type (void); 470 #endif 471 472 GST_API 473 void gst_value_register (const GstValueTable *table); 474 475 GST_API 476 void gst_value_init_and_copy (GValue *dest, 477 const GValue *src); 478 GST_API 479 gchar * gst_value_serialize (const GValue *value) G_GNUC_MALLOC; 480 481 GST_API 482 gboolean gst_value_deserialize (GValue *dest, 483 const gchar *src); 484 485 /* list */ 486 487 GST_API 488 void gst_value_list_append_value (GValue *value, 489 const GValue *append_value); 490 GST_API 491 void gst_value_list_append_and_take_value (GValue *value, 492 GValue *append_value); 493 GST_API 494 void gst_value_list_prepend_value (GValue *value, 495 const GValue *prepend_value); 496 GST_API 497 void gst_value_list_concat (GValue *dest, 498 const GValue *value1, 499 const GValue *value2); 500 GST_API 501 void gst_value_list_merge (GValue *dest, 502 const GValue *value1, 503 const GValue *value2); 504 GST_API 505 guint gst_value_list_get_size (const GValue *value); 506 507 GST_API 508 const GValue * gst_value_list_get_value (const GValue *value, 509 guint index); 510 511 /* array */ 512 513 GST_API 514 void gst_value_array_append_value (GValue *value, 515 const GValue *append_value); 516 GST_API 517 void gst_value_array_append_and_take_value (GValue *value, 518 GValue *append_value); 519 GST_API 520 void gst_value_array_prepend_value (GValue *value, 521 const GValue *prepend_value); 522 GST_API 523 guint gst_value_array_get_size (const GValue *value); 524 525 GST_API 526 const GValue * gst_value_array_get_value (const GValue *value, 527 guint index); 528 529 /* int range */ 530 531 GST_API 532 void gst_value_set_int_range (GValue *value, 533 gint start, 534 gint end); 535 GST_API 536 void gst_value_set_int_range_step (GValue *value, 537 gint start, 538 gint end, 539 gint step); 540 GST_API 541 gint gst_value_get_int_range_min (const GValue *value); 542 543 GST_API 544 gint gst_value_get_int_range_max (const GValue *value); 545 546 GST_API 547 gint gst_value_get_int_range_step (const GValue *value); 548 549 /* int64 range */ 550 551 GST_API 552 void gst_value_set_int64_range (GValue *value, 553 gint64 start, 554 gint64 end); 555 GST_API 556 void gst_value_set_int64_range_step (GValue *value, 557 gint64 start, 558 gint64 end, 559 gint64 step); 560 GST_API 561 gint64 gst_value_get_int64_range_min (const GValue *value); 562 563 GST_API 564 gint64 gst_value_get_int64_range_max (const GValue *value); 565 566 GST_API 567 gint64 gst_value_get_int64_range_step (const GValue *value); 568 569 /* double range */ 570 571 GST_API 572 void gst_value_set_double_range (GValue *value, 573 gdouble start, 574 gdouble end); 575 GST_API 576 gdouble gst_value_get_double_range_min (const GValue *value); 577 578 GST_API 579 gdouble gst_value_get_double_range_max (const GValue *value); 580 581 /* caps */ 582 583 GST_API 584 const GstCaps * gst_value_get_caps (const GValue *value); 585 586 GST_API 587 void gst_value_set_caps (GValue *value, 588 const GstCaps *caps); 589 590 /* structure */ 591 592 GST_API 593 const GstStructure * 594 gst_value_get_structure (const GValue *value); 595 596 GST_API 597 void gst_value_set_structure (GValue *value, 598 const GstStructure *structure); 599 600 /* caps features */ 601 602 GST_API 603 const GstCapsFeatures * 604 gst_value_get_caps_features (const GValue *value); 605 606 GST_API 607 void gst_value_set_caps_features (GValue *value, 608 const GstCapsFeatures *features); 609 610 /* fraction */ 611 612 GST_API 613 void gst_value_set_fraction (GValue *value, 614 gint numerator, 615 gint denominator); 616 GST_API 617 gint gst_value_get_fraction_numerator (const GValue *value); 618 619 GST_API 620 gint gst_value_get_fraction_denominator (const GValue *value); 621 622 GST_API 623 gboolean gst_value_fraction_multiply (GValue *product, 624 const GValue *factor1, 625 const GValue *factor2); 626 GST_API 627 gboolean gst_value_fraction_subtract (GValue * dest, 628 const GValue * minuend, 629 const GValue * subtrahend); 630 631 /* fraction range */ 632 633 GST_API 634 void gst_value_set_fraction_range (GValue *value, 635 const GValue *start, 636 const GValue *end); 637 GST_API 638 void gst_value_set_fraction_range_full (GValue *value, 639 gint numerator_start, 640 gint denominator_start, 641 gint numerator_end, 642 gint denominator_end); 643 GST_API 644 const GValue *gst_value_get_fraction_range_min (const GValue *value); 645 646 GST_API 647 const GValue *gst_value_get_fraction_range_max (const GValue *value); 648 649 /* bitmask */ 650 651 GST_API 652 guint64 gst_value_get_bitmask (const GValue *value); 653 654 GST_API 655 void gst_value_set_bitmask (GValue *value, 656 guint64 bitmask); 657 /* flagset */ 658 659 GST_API 660 void gst_value_set_flagset (GValue * value, guint flags, guint mask); 661 662 GST_API 663 guint gst_value_get_flagset_flags (const GValue * value); 664 665 GST_API 666 guint gst_value_get_flagset_mask (const GValue * value); 667 668 /* compare */ 669 670 GST_API 671 gint gst_value_compare (const GValue *value1, 672 const GValue *value2); 673 GST_API 674 gboolean gst_value_can_compare (const GValue *value1, 675 const GValue *value2); 676 GST_API 677 gboolean gst_value_is_subset (const GValue *value1, 678 const GValue *value2); 679 680 /* union */ 681 682 GST_API 683 gboolean gst_value_union (GValue *dest, 684 const GValue *value1, 685 const GValue *value2); 686 GST_API 687 gboolean gst_value_can_union (const GValue *value1, 688 const GValue *value2); 689 690 /* intersection */ 691 692 GST_API 693 gboolean gst_value_intersect (GValue *dest, 694 const GValue *value1, 695 const GValue *value2); 696 GST_API 697 gboolean gst_value_can_intersect (const GValue *value1, 698 const GValue *value2); 699 700 /* subtraction */ 701 702 GST_API 703 gboolean gst_value_subtract (GValue *dest, 704 const GValue *minuend, 705 const GValue *subtrahend); 706 GST_API 707 gboolean gst_value_can_subtract (const GValue *minuend, 708 const GValue *subtrahend); 709 710 /* fixation */ 711 712 GST_API 713 gboolean gst_value_is_fixed (const GValue *value); 714 715 GST_API 716 gboolean gst_value_fixate (GValue *dest, 717 const GValue *src); 718 719 /* Flagset registration wrapper */ 720 721 GST_API 722 GType gst_flagset_register (GType flags_type); 723 724 G_END_DECLS 725 726 #endif 727 728 729