API: add GstParamSpecFraction, so elements can have fraction properties without lots of painful string parsing (#4446...

Original commit message from CVS:
* docs/gst/gstreamer-sections.txt:
* gst/Makefile.am:
* gst/gst.c:
* gst/gst.h:
* gst/gstparamspecs.c: (_gst_param_fraction_init),
(_gst_param_fraction_set_default), (_gst_param_fraction_validate),
(_gst_param_fraction_values_cmp),
(gst_param_spec_fraction_get_type), (gst_param_spec_fraction):
* gst/gstparamspecs.h:
* gst/gstvalue.c:
* tests/check/Makefile.am:
* tests/check/gst/.cvsignore:
* tests/check/gst/gstparamspecs.c: (gst_dummy_obj_base_init),
(gst_dummy_obj_class_init), (gst_dummy_obj_init),
(gst_dummy_obj_set_property), (gst_dummy_obj_get_property),
(GST_START_TEST), (gst_param_spec_suite):
API: add GstParamSpecFraction, so elements can have fraction
properties without lots of painful string parsing (#444648).

ChangeLog

@@ -1,3 +1,24 @@
+2007-06-06  Tim-Philipp Müller  <tim at centricular dot net>
+
+	* docs/gst/gstreamer-sections.txt:
+	* gst/Makefile.am:
+	* gst/gst.c:
+	* gst/gst.h:
+	* gst/gstparamspecs.c: (_gst_param_fraction_init),
+	(_gst_param_fraction_set_default), (_gst_param_fraction_validate),
+	(_gst_param_fraction_values_cmp),
+	(gst_param_spec_fraction_get_type), (gst_param_spec_fraction):
+	* gst/gstparamspecs.h:
+	* gst/gstvalue.c:
+	* tests/check/Makefile.am:
+	* tests/check/gst/.cvsignore:
+	* tests/check/gst/gstparamspecs.c: (gst_dummy_obj_base_init),
+	(gst_dummy_obj_class_init), (gst_dummy_obj_init),
+	(gst_dummy_obj_set_property), (gst_dummy_obj_get_property),
+	(GST_START_TEST), (gst_param_spec_suite):
+	  API: add GstParamSpecFraction, so elements can have fraction
+	  properties without lots of painful string parsing (#444648).
+
 2007-06-05  Wim Taymans  <wim@fluendo.com>
 
 	* gst/gstobject.c: (gst_object_class_init):

docs/gst/gstreamer-sections.txt

@@ -2198,6 +2198,10 @@ gst_value_get_fraction_denominator
 gst_value_fraction_multiply
 gst_value_fraction_subtract
 
+<SUBSECTION paramspecfraction>
+GstParamSpecFraction
+gst_param_spec_fraction
+
 <SUBSECTION fractionrange>
 GST_VALUE_HOLDS_FRACTION_RANGE
 GST_TYPE_FRACTION_RANGE
@@ -2261,6 +2265,11 @@ gst_value_array_get_value
 gst_value_array_prepend_value
 
 <SUBSECTION Standard>
+GST_IS_PARAM_SPEC_FRACTION
+GST_PARAM_SPEC_FRACTION
+GST_TYPE_PARAM_FRACTION
+gst_param_spec_fraction_get_type
+
 <SUBSECTION Private>
 gst_date_get_type
 gst_double_range_get_type

gst/Makefile.am

@@ -97,6 +97,7 @@ libgstreamer_@GST_MAJORMINOR@_la_SOURCES = \
 	gstminiobject.c		\
 	gstpad.c		\
 	gstpadtemplate.c	\
+	gstparamspecs.c		\
 	gstpipeline.c		\
 	gstplugin.c		\
 	gstpluginfeature.c	\
@@ -178,6 +179,7 @@ gst_headers =			\
 	gstminiobject.h		\
 	gstpad.h		\
 	gstpadtemplate.h	\
+	gstparamspecs.h		\
 	gstpipeline.h		\
 	gstplugin.h		\
 	gstpluginfeature.h	\

gst/gst.c

@@ -965,6 +965,7 @@ init_post (GOptionContext * context, GOptionGroup * group, gpointer data,
 
   gst_structure_get_type ();
   _gst_value_initialize ();
+  gst_param_spec_fraction_get_type ();
   gst_caps_get_type ();
   _gst_event_initialize ();
   _gst_buffer_initialize ();

gst/gst.h

@@ -50,6 +50,7 @@
 #include <gst/gstminiobject.h>
 #include <gst/gstobject.h>
 #include <gst/gstpad.h>
+#include <gst/gstparamspecs.h>
 #include <gst/gstpipeline.h>
 #include <gst/gstplugin.h>
 #include <gst/gstquery.h>

gst/gstparamspecs.c

@@ -0,0 +1,194 @@
+/* GStreamer - GParamSpecs for some of our types
+ * Copyright (C) 2007 Tim-Philipp Müller  <tim centricular net>
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Library General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Library General Public License for more details.
+ *
+ * You should have received a copy of the GNU Library General Public
+ * License along with this library; if not, write to the
+ * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ * Boston, MA 02111-1307, USA.
+ */
+
+#ifdef HAVE_CONFIG_H
+#include "config.h"
+#endif
+
+#include "gst_private.h"
+#include "glib-compat-private.h"
+#include "gstparamspecs.h"
+
+/* --- GstParamSpecFraction --- */
+
+static void
+_gst_param_fraction_init (GParamSpec * pspec)
+{
+  GstParamSpecFraction *fspec = GST_PARAM_SPEC_FRACTION (pspec);
+
+  fspec->min_num = 0;
+  fspec->min_den = 1;
+  fspec->max_num = G_MAXINT;
+  fspec->max_den = 1;
+  fspec->def_num = 1;
+  fspec->def_den = 1;
+}
+
+static void
+_gst_param_fraction_set_default (GParamSpec * pspec, GValue * value)
+{
+  value->data[0].v_int = GST_PARAM_SPEC_FRACTION (pspec)->def_num;
+  value->data[1].v_int = GST_PARAM_SPEC_FRACTION (pspec)->def_den;
+}
+
+static gboolean
+_gst_param_fraction_validate (GParamSpec * pspec, GValue * value)
+{
+  GstParamSpecFraction *fspec = GST_PARAM_SPEC_FRACTION (pspec);
+  gboolean within_range = FALSE;
+  GValue f_this = { 0, };
+  GValue f_min = { 0, };
+  GValue f_max = { 0, };
+  gint res;
+
+  g_value_init (&f_this, GST_TYPE_FRACTION);
+  gst_value_set_fraction (&f_this, value->data[0].v_int, value->data[1].v_int);
+
+  g_value_init (&f_min, GST_TYPE_FRACTION);
+  gst_value_set_fraction (&f_min, fspec->min_num, fspec->min_den);
+
+  g_value_init (&f_max, GST_TYPE_FRACTION);
+  gst_value_set_fraction (&f_max, fspec->max_num, fspec->max_den);
+
+  res = gst_value_compare (&f_min, &f_this);
+  GST_LOG ("comparing %d/%d to %d/%d, result = %d", fspec->min_num,
+      fspec->min_den, value->data[0].v_int, value->data[1].v_int, res);
+  if (res != GST_VALUE_LESS_THAN && res != GST_VALUE_EQUAL)
+    goto out;
+
+  GST_LOG ("comparing %d/%d to %d/%d, result = %d", value->data[0].v_int,
+      value->data[1].v_int, fspec->max_num, fspec->max_den, res);
+  res = gst_value_compare (&f_this, &f_max);
+  if (res != GST_VALUE_LESS_THAN && res != GST_VALUE_EQUAL)
+    goto out;
+
+  within_range = TRUE;
+
+out:
+
+  g_value_unset (&f_min);
+  g_value_unset (&f_max);
+  g_value_unset (&f_this);
+
+  GST_LOG ("%swithin range", (within_range) ? "" : "not ");
+
+  /* return FALSE if everything ok, otherwise TRUE */
+  return !within_range;
+}
+
+static gint
+_gst_param_fraction_values_cmp (GParamSpec * pspec, const GValue * value1,
+    const GValue * value2)
+{
+  gint res;
+
+  res = gst_value_compare (value1, value2);
+
+  g_assert (res != GST_VALUE_UNORDERED);
+
+  /* GST_VALUE_LESS_THAN is -1, EQUAL is 0, and GREATER_THAN is 1 */
+  return res;
+}
+
+GType
+gst_param_spec_fraction_get_type (void)
+{
+  static GType type;            /* 0 */
+
+  /* register GST_TYPE_PARAM_FRACTION */
+  if (type == 0) {
+    static GParamSpecTypeInfo pspec_info = {
+      sizeof (GstParamSpecFraction),    /* instance_size     */
+      0,                        /* n_preallocs       */
+      _gst_param_fraction_init, /* instance_init     */
+      G_TYPE_INVALID,           /* value_type        */
+      NULL,                     /* finalize          */
+      _gst_param_fraction_set_default,  /* value_set_default */
+      _gst_param_fraction_validate,     /* value_validate    */
+      _gst_param_fraction_values_cmp,   /* values_cmp        */
+    };
+    pspec_info.value_type = GST_TYPE_FRACTION;
+    type =
+        g_param_type_register_static (g_intern_static_string
+        ("GstParamFraction"), &pspec_info);
+  }
+  return type;
+}
+
+/**
+ * gst_param_spec_fraction:
+ * @name: canonical name of the property specified
+ * @nick: nick name for the property specified
+ * @blurb: description of the property specified
+ * @min_num: minimum value (fraction numerator)
+ * @min_denom: minimum value (fraction denominator)
+ * @max_num: maximum value (fraction numerator)
+ * @max_denom: maximum value (fraction denominator)
+ * @default_num: default value (fraction numerator)
+ * @default_denom: default value (fraction denominator)
+ * @flags: flags for the property specified
+ *
+ * This function creates a fraction GParamSpec for use by objects/elements
+ * that want to expose properties of fraction type. This function is typically
+ * used in connection with g_object_class_install_property() in a GObjects's
+ * instance_init function.
+ *
+ * Returns: a newly created parameter specification
+ *
+ * Since: 0.10.14
+ */
+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)
+{
+  GstParamSpecFraction *fspec;
+  GParamSpec *pspec;
+  GValue default_val = { 0, };
+
+  fspec =
+      g_param_spec_internal (GST_TYPE_PARAM_FRACTION, name, nick, blurb, flags);
+
+  fspec->min_num = min_num;
+  fspec->min_den = min_denom;
+  fspec->max_num = max_num;
+  fspec->max_den = max_denom;
+  fspec->def_num = default_num;
+  fspec->def_den = default_denom;
+
+  pspec = G_PARAM_SPEC (fspec);
+
+  /* check that min <= default <= max */
+  g_value_init (&default_val, GST_TYPE_FRACTION);
+  gst_value_set_fraction (&default_val, default_num, default_denom);
+  /* validate returns TRUE if the validation fails */
+  if (_gst_param_fraction_validate (pspec, &default_val)) {
+    g_critical ("GstParamSpec of type 'fraction' for property '%s' has a "
+        "default value of %d/%d, which is not within the allowed range of "
+        "%d/%d to %d/%d", name, default_num, default_denom, min_num,
+        min_denom, max_num, max_denom);
+    g_param_spec_ref (pspec);
+    g_param_spec_sink (pspec);
+    g_param_spec_unref (pspec);
+    pspec = NULL;
+  }
+  g_value_unset (&default_val);
+
+  return pspec;
+}

gst/gstparamspecs.h

@@ -0,0 +1,65 @@
+/* GStreamer - GParamSpecs for for some of our types
+ * Copyright (C) 2007 Tim-Philipp Müller  <tim centricular net>
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Library General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Library General Public License for more details.
+ *
+ * You should have received a copy of the GNU Library General Public
+ * License along with this library; if not, write to the
+ * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ * Boston, MA 02111-1307, USA.
+ */
+
+#ifndef __GST_PARAMSPECS_H__
+#define __GST_PARAMSPECS_H__
+
+#include <gst/gstvalue.h>
+
+G_BEGIN_DECLS
+
+/* --- type macros --- */
+
+#define GST_TYPE_PARAM_FRACTION           (gst_param_spec_fraction_get_type ())
+#define GST_IS_PARAM_SPEC_FRACTION(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), GST_TYPE_PARAM_FRACTION))
+#define GST_PARAM_SPEC_FRACTION(pspec)    (G_TYPE_CHECK_INSTANCE_CAST ((pspec), GST_TYPE_PARAM_FRACTION, GstParamSpecFraction))
+
+
+/* --- get_type functions --- */
+
+GType  gst_param_spec_fraction_get_type (void);
+
+
+/* --- typedefs & structures --- */
+
+typedef struct _GstParamSpecFraction GstParamSpecFraction;
+
+struct _GstParamSpecFraction {
+  GParamSpec    parent_instance;
+  
+  gint          min_num, min_den;
+  gint          max_num, max_den;
+  gint          def_num, def_den;
+};
+
+
+/* --- GParamSpec prototypes --- */
+
+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);
+
+G_END_DECLS
+
+#endif /* __GST_PARAMSPECS_H__ */
+

gst/gstvalue.c

@@ -19,9 +19,10 @@
 
 /**
  * SECTION:gstvalue
- * @short_description: GValue implementations specific to GStreamer
+ * @short_description: GValue and GParamSpec implementations specific
+ * to GStreamer
  *
- * GValue implementations specific to GStreamer.
+ * GValue and GParamSpec implementations specific to GStreamer.
  *
  * Note that operations on the same GstValue (or GValue) from multiple
  * threads may lead to undefined behaviour. 

tests/check/Makefile.am

@@ -79,6 +79,7 @@ check_PROGRAMS =				\
 	gst/gstminiobject 			\
 	gst/gstobject				\
 	gst/gstpad				\
+	gst/gstparamspecs			\
 	gst/gstsegment				\
 	gst/gstsystemclock			\
 	gst/gststructure			\

tests/check/gst/.gitignore

@@ -14,6 +14,7 @@ gstmessage
 gstminiobject
 gstobject
 gstpad
+gstparamspecs
 gstpipeline
 gstplugin
 gstregistry

tests/check/gst/gstparamspecs.c

@@ -0,0 +1,132 @@
+/* GStreamer GstParamSpec unit tests
+ * Copyright (C) 2007 Tim-Philipp Müller <tim centricular net>
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Library General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Library General Public License for more details.
+ *
+ * You should have received a copy of the GNU Library General Public
+ * License along with this library; if not, write to the
+ * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ * Boston, MA 02111-1307, USA.
+ */
+
+#include <gst/check/gstcheck.h>
+#include <gst/gst.h>
+#include <string.h>
+
+/* some minimal dummy object */
+#define GST_TYPE_DUMMY_OBJ gst_dummy_obj_get_type()
+
+typedef struct
+{
+  GstElement parent;
+  guint num, denom;
+} GstDummyObj;
+
+typedef GstElementClass GstDummyObjClass;
+
+GST_BOILERPLATE (GstDummyObj, gst_dummy_obj, GstElement, GST_TYPE_ELEMENT);
+
+static void
+gst_dummy_obj_get_property (GObject * obj, guint prop_id, GValue * val,
+    GParamSpec * pspec);
+static void
+gst_dummy_obj_set_property (GObject * obj, guint prop_id, const GValue * val,
+    GParamSpec * pspec);
+
+static void
+gst_dummy_obj_base_init (gpointer g_class)
+{
+}
+
+static void
+gst_dummy_obj_class_init (GstDummyObjClass * klass)
+{
+  GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
+
+  gobject_class->get_property = gst_dummy_obj_get_property;
+  gobject_class->set_property = gst_dummy_obj_set_property;
+
+  ASSERT_CRITICAL (
+      /* default value is out of bounds, should print a warning */
+      g_object_class_install_property (gobject_class, 1,
+          gst_param_spec_fraction ("ratio", "ratio", "ratio", 0, 1, 2, 1,
+              16, 4, G_PARAM_READWRITE)););
+
+  /* should be within bounds */
+  g_object_class_install_property (gobject_class, 2,
+      gst_param_spec_fraction ("other-ratio", "other ratio", "other ratio",
+          0, 1, 2, 1, 16, 9, G_PARAM_READWRITE));
+
+  g_object_class_install_property (gobject_class, 3,
+      g_param_spec_boolean ("foo", "foo", "foo", TRUE, G_PARAM_READWRITE));
+}
+
+static void
+gst_dummy_obj_init (GstDummyObj * obj, GstDummyObjClass * klass)
+{
+  /* nothing to do there */
+}
+
+static void
+gst_dummy_obj_set_property (GObject * obj, guint prop_id, const GValue * val,
+    GParamSpec * pspec)
+{
+  GstDummyObj *dobj = (GstDummyObj *) obj;
+
+  fail_unless_equals_int (prop_id, 2);
+  dobj->num = gst_value_get_fraction_numerator (val);
+  dobj->denom = gst_value_get_fraction_denominator (val);
+}
+
+static void
+gst_dummy_obj_get_property (GObject * obj, guint prop_id, GValue * val,
+    GParamSpec * pspec)
+{
+  GstDummyObj *dobj = (GstDummyObj *) obj;
+
+  fail_unless_equals_int (prop_id, 2);
+  gst_value_set_fraction (val, dobj->num, dobj->denom);
+}
+
+GST_START_TEST (test_param_spec_fraction)
+{
+  GObject *obj;
+  GValue val = { 0, };
+  gint n = 0, d = 0;
+
+  obj = g_object_new (GST_TYPE_DUMMY_OBJ, "other-ratio", 15, 8, NULL);
+
+  g_value_init (&val, GST_TYPE_FRACTION);
+  g_object_get_property (G_OBJECT (obj), "other-ratio", &val);
+  fail_unless_equals_int (gst_value_get_fraction_numerator (&val), 15);
+  fail_unless_equals_int (gst_value_get_fraction_denominator (&val), 8);
+  g_value_unset (&val);
+
+  g_object_get (obj, "other-ratio", &n, &d, NULL);
+  fail_unless_equals_int (n, 15);
+  fail_unless_equals_int (d, 8);
+
+  g_object_unref (obj);
+}
+
+GST_END_TEST static Suite *
+gst_param_spec_suite (void)
+{
+  Suite *s = suite_create ("GstParamSpec");
+  TCase *tc_chain = tcase_create ("general");
+
+  suite_add_tcase (s, tc_chain);
+  tcase_add_test (tc_chain, test_param_spec_fraction);
+
+  return s;
+}
+
+GST_CHECK_MAIN (gst_param_spec);