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
28G_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
225GST_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
236GST_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
247GST_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
258GST_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
269GST_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
284GST_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
300GST_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
313GST_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
325GST_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 */
392typedef 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 */
405typedef 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 */
416typedef gboolean (* GstValueDeserializeFunc) (GValue *dest,
417 const gchar *s);
418
419typedef 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 */
429struct _GstValueTable {
430 GType type;
431 GstValueCompareFunc compare;
432 GstValueSerializeFunc serialize;
433 GstValueDeserializeFunc deserialize;
434
435 /*< private >*/
436 gpointer _gst_reserved [GST_PADDING];
437};
438
439GST_API
440GType gst_int_range_get_type (void);
441
442GST_API
443GType gst_int64_range_get_type (void);
444
445GST_API
446GType gst_double_range_get_type (void);
447
448GST_API
449GType gst_fraction_range_get_type (void);
450
451GST_API
452GType gst_fraction_get_type (void);
453
454GST_API
455GType gst_value_list_get_type (void);
456
457GST_API
458GType gst_value_array_get_type (void);
459
460GST_API
461GType gst_bitmask_get_type (void);
462
463GST_API
464GType gst_flagset_get_type (void);
465
466/* Hide this compatibility type from introspection */
467#ifndef __GI_SCANNER__
468GST_API
469GType gst_g_thread_get_type (void);
470#endif
471
472GST_API
473void gst_value_register (const GstValueTable *table);
474
475GST_API
476void gst_value_init_and_copy (GValue *dest,
477 const GValue *src);
478GST_API
479gchar * gst_value_serialize (const GValue *value) G_GNUC_MALLOC;
480
481GST_API
482gboolean gst_value_deserialize (GValue *dest,
483 const gchar *src);
484
485/* list */
486
487GST_API
488void gst_value_list_append_value (GValue *value,
489 const GValue *append_value);
490GST_API
491void gst_value_list_append_and_take_value (GValue *value,
492 GValue *append_value);
493GST_API
494void gst_value_list_prepend_value (GValue *value,
495 const GValue *prepend_value);
496GST_API
497void gst_value_list_concat (GValue *dest,
498 const GValue *value1,
499 const GValue *value2);
500GST_API
501void gst_value_list_merge (GValue *dest,
502 const GValue *value1,
503 const GValue *value2);
504GST_API
505guint gst_value_list_get_size (const GValue *value);
506
507GST_API
508const GValue * gst_value_list_get_value (const GValue *value,
509 guint index);
510
511/* array */
512
513GST_API
514void gst_value_array_append_value (GValue *value,
515 const GValue *append_value);
516GST_API
517void gst_value_array_append_and_take_value (GValue *value,
518 GValue *append_value);
519GST_API
520void gst_value_array_prepend_value (GValue *value,
521 const GValue *prepend_value);
522GST_API
523guint gst_value_array_get_size (const GValue *value);
524
525GST_API
526const GValue * gst_value_array_get_value (const GValue *value,
527 guint index);
528
529/* int range */
530
531GST_API
532void gst_value_set_int_range (GValue *value,
533 gint start,
534 gint end);
535GST_API
536void gst_value_set_int_range_step (GValue *value,
537 gint start,
538 gint end,
539 gint step);
540GST_API
541gint gst_value_get_int_range_min (const GValue *value);
542
543GST_API
544gint gst_value_get_int_range_max (const GValue *value);
545
546GST_API
547gint gst_value_get_int_range_step (const GValue *value);
548
549/* int64 range */
550
551GST_API
552void gst_value_set_int64_range (GValue *value,
553 gint64 start,
554 gint64 end);
555GST_API
556void gst_value_set_int64_range_step (GValue *value,
557 gint64 start,
558 gint64 end,
559 gint64 step);
560GST_API
561gint64 gst_value_get_int64_range_min (const GValue *value);
562
563GST_API
564gint64 gst_value_get_int64_range_max (const GValue *value);
565
566GST_API
567gint64 gst_value_get_int64_range_step (const GValue *value);
568
569/* double range */
570
571GST_API
572void gst_value_set_double_range (GValue *value,
573 gdouble start,
574 gdouble end);
575GST_API
576gdouble gst_value_get_double_range_min (const GValue *value);
577
578GST_API
579gdouble gst_value_get_double_range_max (const GValue *value);
580
581/* caps */
582
583GST_API
584const GstCaps * gst_value_get_caps (const GValue *value);
585
586GST_API
587void gst_value_set_caps (GValue *value,
588 const GstCaps *caps);
589
590/* structure */
591
592GST_API
593const GstStructure *
594 gst_value_get_structure (const GValue *value);
595
596GST_API
597void gst_value_set_structure (GValue *value,
598 const GstStructure *structure);
599
600/* caps features */
601
602GST_API
603const GstCapsFeatures *
604 gst_value_get_caps_features (const GValue *value);
605
606GST_API
607void gst_value_set_caps_features (GValue *value,
608 const GstCapsFeatures *features);
609
610/* fraction */
611
612GST_API
613void gst_value_set_fraction (GValue *value,
614 gint numerator,
615 gint denominator);
616GST_API
617gint gst_value_get_fraction_numerator (const GValue *value);
618
619GST_API
620gint gst_value_get_fraction_denominator (const GValue *value);
621
622GST_API
623gboolean gst_value_fraction_multiply (GValue *product,
624 const GValue *factor1,
625 const GValue *factor2);
626GST_API
627gboolean gst_value_fraction_subtract (GValue * dest,
628 const GValue * minuend,
629 const GValue * subtrahend);
630
631/* fraction range */
632
633GST_API
634void gst_value_set_fraction_range (GValue *value,
635 const GValue *start,
636 const GValue *end);
637GST_API
638void gst_value_set_fraction_range_full (GValue *value,
639 gint numerator_start,
640 gint denominator_start,
641 gint numerator_end,
642 gint denominator_end);
643GST_API
644const GValue *gst_value_get_fraction_range_min (const GValue *value);
645
646GST_API
647const GValue *gst_value_get_fraction_range_max (const GValue *value);
648
649/* bitmask */
650
651GST_API
652guint64 gst_value_get_bitmask (const GValue *value);
653
654GST_API
655void gst_value_set_bitmask (GValue *value,
656 guint64 bitmask);
657/* flagset */
658
659GST_API
660void gst_value_set_flagset (GValue * value, guint flags, guint mask);
661
662GST_API
663guint gst_value_get_flagset_flags (const GValue * value);
664
665GST_API
666guint gst_value_get_flagset_mask (const GValue * value);
667
668/* compare */
669
670GST_API
671gint gst_value_compare (const GValue *value1,
672 const GValue *value2);
673GST_API
674gboolean gst_value_can_compare (const GValue *value1,
675 const GValue *value2);
676GST_API
677gboolean gst_value_is_subset (const GValue *value1,
678 const GValue *value2);
679
680/* union */
681
682GST_API
683gboolean gst_value_union (GValue *dest,
684 const GValue *value1,
685 const GValue *value2);
686GST_API
687gboolean gst_value_can_union (const GValue *value1,
688 const GValue *value2);
689
690/* intersection */
691
692GST_API
693gboolean gst_value_intersect (GValue *dest,
694 const GValue *value1,
695 const GValue *value2);
696GST_API
697gboolean gst_value_can_intersect (const GValue *value1,
698 const GValue *value2);
699
700/* subtraction */
701
702GST_API
703gboolean gst_value_subtract (GValue *dest,
704 const GValue *minuend,
705 const GValue *subtrahend);
706GST_API
707gboolean gst_value_can_subtract (const GValue *minuend,
708 const GValue *subtrahend);
709
710/* fixation */
711
712GST_API
713gboolean gst_value_is_fixed (const GValue *value);
714
715GST_API
716gboolean gst_value_fixate (GValue *dest,
717 const GValue *src);
718
719/* Flagset registration wrapper */
720
721GST_API
722GType gst_flagset_register (GType flags_type);
723
724G_END_DECLS
725
726#endif
727
728
729