1 /* GStreamer - GParamSpecs for some of our types
2 * Copyright (C) 2007 Tim-Philipp Müller <tim centricular net>
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 * SECTION:gstparamspec
21 * @title: GstParamSpec
22 * @short_description: GParamSpec implementations specific
23 * to GStreamer
24 *
25 * GParamSpec implementations specific to GStreamer.
26 */
27
28 #ifdef HAVE_CONFIG_H
29 #include "config.h"
30 #endif
31
32 #include "gst_private.h"
33 #include "glib-compat-private.h"
34 #include "gstparamspecs.h"
35
36 /* --- GstParamSpecFraction --- */
37
38 static void
_gst_param_fraction_init(GParamSpec * pspec)39 _gst_param_fraction_init (GParamSpec * pspec)
40 {
41 GstParamSpecFraction *fspec = GST_PARAM_SPEC_FRACTION (pspec);
42
43 fspec->min_num = 0;
44 fspec->min_den = 1;
45 fspec->max_num = G_MAXINT;
46 fspec->max_den = 1;
47 fspec->def_num = 1;
48 fspec->def_den = 1;
49 }
50
51 static void
_gst_param_fraction_set_default(GParamSpec * pspec,GValue * value)52 _gst_param_fraction_set_default (GParamSpec * pspec, GValue * value)
53 {
54 value->data[0].v_int = GST_PARAM_SPEC_FRACTION (pspec)->def_num;
55 value->data[1].v_int = GST_PARAM_SPEC_FRACTION (pspec)->def_den;
56 }
57
58 static gboolean
_gst_param_fraction_validate(GParamSpec * pspec,GValue * value)59 _gst_param_fraction_validate (GParamSpec * pspec, GValue * value)
60 {
61 GstParamSpecFraction *fspec = GST_PARAM_SPEC_FRACTION (pspec);
62 gboolean within_range = FALSE;
63 GValue f_this = { 0, };
64 GValue f_min = { 0, };
65 GValue f_max = { 0, };
66 gint res;
67
68 g_value_init (&f_this, GST_TYPE_FRACTION);
69 gst_value_set_fraction (&f_this, value->data[0].v_int, value->data[1].v_int);
70
71 g_value_init (&f_min, GST_TYPE_FRACTION);
72 gst_value_set_fraction (&f_min, fspec->min_num, fspec->min_den);
73
74 g_value_init (&f_max, GST_TYPE_FRACTION);
75 gst_value_set_fraction (&f_max, fspec->max_num, fspec->max_den);
76
77 res = gst_value_compare (&f_min, &f_this);
78 #ifndef GST_DISABLE_GST_DEBUG
79 GST_LOG ("comparing %d/%d to %d/%d, result = %d", fspec->min_num,
80 fspec->min_den, value->data[0].v_int, value->data[1].v_int, res);
81 #endif
82 if (res != GST_VALUE_LESS_THAN && res != GST_VALUE_EQUAL)
83 goto out;
84
85 #ifndef GST_DISABLE_GST_DEBUG
86 GST_LOG ("comparing %d/%d to %d/%d, result = %d", value->data[0].v_int,
87 value->data[1].v_int, fspec->max_num, fspec->max_den, res);
88 #endif
89 res = gst_value_compare (&f_this, &f_max);
90 if (res != GST_VALUE_LESS_THAN && res != GST_VALUE_EQUAL)
91 goto out;
92
93 within_range = TRUE;
94
95 out:
96
97 g_value_unset (&f_min);
98 g_value_unset (&f_max);
99 g_value_unset (&f_this);
100
101 #ifndef GST_DISABLE_GST_DEBUG
102 GST_LOG ("%swithin range", (within_range) ? "" : "not ");
103 #endif
104
105 /* return FALSE if everything ok, otherwise TRUE */
106 return !within_range;
107 }
108
109 static gint
_gst_param_fraction_values_cmp(GParamSpec * pspec,const GValue * value1,const GValue * value2)110 _gst_param_fraction_values_cmp (GParamSpec * pspec, const GValue * value1,
111 const GValue * value2)
112 {
113 gint res;
114
115 res = gst_value_compare (value1, value2);
116
117 g_assert (res != GST_VALUE_UNORDERED);
118
119 /* GST_VALUE_LESS_THAN is -1, EQUAL is 0, and GREATER_THAN is 1 */
120 return res;
121 }
122
123 GType
gst_param_spec_fraction_get_type(void)124 gst_param_spec_fraction_get_type (void)
125 {
126 static GType gst_faction_type = 0;
127
128 /* register GST_TYPE_PARAM_FRACTION */
129 if (g_once_init_enter (&gst_faction_type)) {
130 GType type;
131 static GParamSpecTypeInfo pspec_info = {
132 sizeof (GstParamSpecFraction), /* instance_size */
133 0, /* n_preallocs */
134 _gst_param_fraction_init, /* instance_init */
135 G_TYPE_INVALID, /* value_type */
136 NULL, /* finalize */
137 _gst_param_fraction_set_default, /* value_set_default */
138 _gst_param_fraction_validate, /* value_validate */
139 _gst_param_fraction_values_cmp, /* values_cmp */
140 };
141 pspec_info.value_type = gst_fraction_get_type ();
142 type = g_param_type_register_static ("GstParamFraction", &pspec_info);
143 g_once_init_leave (&gst_faction_type, type);
144 }
145
146 return gst_faction_type;
147 }
148
149 /**
150 * gst_param_spec_fraction:
151 * @name: canonical name of the property specified
152 * @nick: nick name for the property specified
153 * @blurb: description of the property specified
154 * @min_num: minimum value (fraction numerator)
155 * @min_denom: minimum value (fraction denominator)
156 * @max_num: maximum value (fraction numerator)
157 * @max_denom: maximum value (fraction denominator)
158 * @default_num: default value (fraction numerator)
159 * @default_denom: default value (fraction denominator)
160 * @flags: flags for the property specified
161 *
162 * This function creates a fraction GParamSpec for use by objects/elements
163 * that want to expose properties of fraction type. This function is typically
164 * used in connection with g_object_class_install_property() in a GObjects's
165 * instance_init function.
166 *
167 * Returns: (transfer full) (nullable): a newly created parameter specification
168 */
169 GParamSpec *
gst_param_spec_fraction(const gchar * name,const gchar * nick,const gchar * blurb,gint min_num,gint min_denom,gint max_num,gint max_denom,gint default_num,gint default_denom,GParamFlags flags)170 gst_param_spec_fraction (const gchar * name, const gchar * nick,
171 const gchar * blurb, gint min_num, gint min_denom, gint max_num,
172 gint max_denom, gint default_num, gint default_denom, GParamFlags flags)
173 {
174 GstParamSpecFraction *fspec;
175 GParamSpec *pspec;
176 GValue default_val = { 0, };
177
178 fspec =
179 g_param_spec_internal (GST_TYPE_PARAM_FRACTION, name, nick, blurb, flags);
180
181 fspec->min_num = min_num;
182 fspec->min_den = min_denom;
183 fspec->max_num = max_num;
184 fspec->max_den = max_denom;
185 fspec->def_num = default_num;
186 fspec->def_den = default_denom;
187
188 pspec = G_PARAM_SPEC (fspec);
189
190 /* check that min <= default <= max */
191 g_value_init (&default_val, GST_TYPE_FRACTION);
192 gst_value_set_fraction (&default_val, default_num, default_denom);
193 /* validate returns TRUE if the validation fails */
194 if (_gst_param_fraction_validate (pspec, &default_val)) {
195 g_critical ("GstParamSpec of type 'fraction' for property '%s' has a "
196 "default value of %d/%d, which is not within the allowed range of "
197 "%d/%d to %d/%d", name, default_num, default_denom, min_num,
198 min_denom, max_num, max_denom);
199 g_param_spec_ref (pspec);
200 g_param_spec_sink (pspec);
201 g_param_spec_unref (pspec);
202 pspec = NULL;
203 }
204 g_value_unset (&default_val);
205
206 return pspec;
207 }
208
209 static void
_gst_param_array_init(GParamSpec * pspec)210 _gst_param_array_init (GParamSpec * pspec)
211 {
212 GstParamSpecArray *aspec = GST_PARAM_SPEC_ARRAY_LIST (pspec);
213
214 aspec->element_spec = NULL;
215 }
216
217 static void
_gst_param_array_finalize(GParamSpec * pspec)218 _gst_param_array_finalize (GParamSpec * pspec)
219 {
220 GstParamSpecArray *aspec = GST_PARAM_SPEC_ARRAY_LIST (pspec);
221 GParamSpecClass *parent_class =
222 g_type_class_peek (g_type_parent (GST_TYPE_PARAM_ARRAY_LIST));
223
224 if (aspec->element_spec) {
225 g_param_spec_unref (aspec->element_spec);
226 aspec->element_spec = NULL;
227 }
228
229 parent_class->finalize (pspec);
230 }
231
232 static gboolean
_gst_param_array_validate(GParamSpec * pspec,GValue * value)233 _gst_param_array_validate (GParamSpec * pspec, GValue * value)
234 {
235 GstParamSpecArray *aspec = GST_PARAM_SPEC_ARRAY_LIST (pspec);
236 gboolean ret = FALSE;
237
238 /* ensure array values validity against a present element spec */
239 if (aspec->element_spec) {
240 GParamSpec *element_spec = aspec->element_spec;
241 guint i;
242
243 for (i = 0; i < gst_value_array_get_size (value); i++) {
244 GValue *element = (GValue *) gst_value_array_get_value (value, i);
245
246 /* need to fixup value type, or ensure that the array value is initialized at all */
247 if (!g_value_type_compatible (G_VALUE_TYPE (element),
248 G_PARAM_SPEC_VALUE_TYPE (element_spec))) {
249 if (G_VALUE_TYPE (element) != 0)
250 g_value_unset (element);
251 g_value_init (element, G_PARAM_SPEC_VALUE_TYPE (element_spec));
252 g_param_value_set_default (element_spec, element);
253 ret = TRUE;
254 }
255
256 /* validate array value against element_spec */
257 if (g_param_value_validate (element_spec, element))
258 ret = TRUE;
259 }
260 }
261
262 return ret;
263 }
264
265 static gint
_gst_param_array_values_cmp(GParamSpec * pspec,const GValue * value1,const GValue * value2)266 _gst_param_array_values_cmp (GParamSpec * pspec, const GValue * value1,
267 const GValue * value2)
268 {
269 GstParamSpecArray *aspec = GST_PARAM_SPEC_ARRAY_LIST (pspec);
270 guint size1, size2;
271
272 if (!value1 || !value2)
273 return value2 ? -1 : value1 != value2;
274
275 size1 = gst_value_array_get_size (value1);
276 size2 = gst_value_array_get_size (value2);
277
278 if (size1 != size2)
279 return size1 < size2 ? -1 : 1;
280 else if (!aspec->element_spec) {
281 /* we need an element specification for comparisons, so there's not much
282 * to compare here, try to at least provide stable lesser/greater result
283 */
284 return size1 < size2 ? -1 : size1 > size2;
285 } else { /* size1 == size2 */
286 guint i;
287
288 for (i = 0; i < size1; i++) {
289 const GValue *element1 = gst_value_array_get_value (value1, i);
290 const GValue *element2 = gst_value_array_get_value (value2, i);
291 gint cmp;
292
293 /* need corresponding element types, provide stable result otherwise */
294 if (G_VALUE_TYPE (element1) != G_VALUE_TYPE (element2))
295 return G_VALUE_TYPE (element1) < G_VALUE_TYPE (element2) ? -1 : 1;
296 cmp = g_param_values_cmp (aspec->element_spec, element1, element2);
297 if (cmp)
298 return cmp;
299 }
300 return 0;
301 }
302 }
303
304 GType
gst_param_spec_array_get_type(void)305 gst_param_spec_array_get_type (void)
306 {
307 static GType gst_array_type = 0;
308
309 /* register GST_TYPE_PARAM_FRACTION */
310 if (g_once_init_enter (&gst_array_type)) {
311 GType type;
312 static GParamSpecTypeInfo pspec_info = {
313 sizeof (GstParamSpecArray), /* instance_size */
314 0, /* n_preallocs */
315 _gst_param_array_init, /* instance_init */
316 G_TYPE_INVALID, /* value_type */
317 _gst_param_array_finalize, /* finalize */
318 NULL, /* value_set_default */
319 _gst_param_array_validate, /* value_validate */
320 _gst_param_array_values_cmp, /* values_cmp */
321 };
322 pspec_info.value_type = gst_value_array_get_type ();
323 type = g_param_type_register_static ("GstParamArray", &pspec_info);
324 g_once_init_leave (&gst_array_type, type);
325 }
326
327 return gst_array_type;
328 }
329
330 /**
331 * gst_param_spec_array:
332 * @name: canonical name of the property specified
333 * @nick: nick name for the property specified
334 * @blurb: description of the property specified
335 * @element_spec: GParamSpec of the array
336 * @flags: flags for the property specified
337 *
338 * This function creates a GstArray GParamSpec for use by objects/elements
339 * that want to expose properties of GstArray type. This function is
340 * typically * used in connection with g_object_class_install_property() in a
341 * GObjects's instance_init function.
342 *
343 * Returns: (transfer full): a newly created parameter specification
344 *
345 * Since: 1.14
346 */
347
348 GParamSpec *
gst_param_spec_array(const gchar * name,const gchar * nick,const gchar * blurb,GParamSpec * element_spec,GParamFlags flags)349 gst_param_spec_array (const gchar * name,
350 const gchar * nick,
351 const gchar * blurb, GParamSpec * element_spec, GParamFlags flags)
352 {
353 GstParamSpecArray *aspec;
354
355 g_return_val_if_fail (element_spec == NULL
356 || G_IS_PARAM_SPEC (element_spec), NULL);
357
358 aspec = g_param_spec_internal (GST_TYPE_PARAM_ARRAY_LIST,
359 name, nick, blurb, flags);
360 if (aspec == NULL)
361 return NULL;
362
363 if (element_spec) {
364 aspec->element_spec = g_param_spec_ref (element_spec);
365 g_param_spec_sink (element_spec);
366 }
367
368 return G_PARAM_SPEC (aspec);
369 }
370