gst/gstparamspecs.c

   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
  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
  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
  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
 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
 124 gst_param_spec_fraction_get_type (void)
 125 {
 126   static volatile 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 *
 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
 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
 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
 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
 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
 305 gst_param_spec_array_get_type (void)
 306 {
 307   static volatile 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 *
 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 }