interfaces: API: Add GstStreamVolume interface

Fixes bug #567660.

7 files changed, 350 insertions, 1 deletions

diff --git a/docs/libs/gst-plugins-base-libs-docs.sgml b/docs/libs/gst-plugins-base-libs-docs.sgml
index 16db9616f..ea47a7caa 100644
--- a/docs/libs/gst-plugins-base-libs-docs.sgml
+++ b/docs/libs/gst-plugins-base-libs-docs.sgml
@@ -37,6 +37,7 @@
 <!ENTITY GstMixerTrack SYSTEM "xml/gstmixertrack.xml">
 <!ENTITY GstNavigation SYSTEM "xml/gstnavigation.xml">
 <!ENTITY GstPropertyProbe SYSTEM "xml/gstpropertyprobe.xml">
+<!ENTITY GstStreamVolume SYSTEM "xml/gststreamvolume.xml">
 <!ENTITY GstTuner SYSTEM "xml/gsttuner.xml">
 <!ENTITY GstTunerChannel SYSTEM "xml/gsttunerchannel.xml">
 <!ENTITY GstTunerNorm SYSTEM "xml/gsttunernorm.xml">
@@ -186,6 +187,7 @@
       &GstMixerTrack;
       &GstNavigation;
       &GstPropertyProbe;
+      &GstStreamVolume;
       &GstTuner;
       &GstTunerChannel;
       &GstTunerNorm;
diff --git a/docs/libs/gst-plugins-base-libs-sections.txt b/docs/libs/gst-plugins-base-libs-sections.txt
index 6d2908266..5684a7ea6 100644
--- a/docs/libs/gst-plugins-base-libs-sections.txt
+++ b/docs/libs/gst-plugins-base-libs-sections.txt
@@ -580,6 +580,31 @@ gst_property_probe_get_type
 </SECTION>
 
 <SECTION>
+<FILE>gststreamvolume</FILE>
+<INCLUDE>gst/interfaces/streamvolume.h</INCLUDE>
+GstStreamVolume
+GstStreamVolumeFormat
+
+gst_stream_volume_get_volume
+gst_stream_volume_set_volume
+
+gst_stream_volume_get_mute
+gst_stream_volume_set_mute
+
+gst_stream_volume_convert_volume
+
+<SUBSECTION Standard>
+GstStreamVolumeInterface
+GST_TYPE_STREAM_VOLUME
+GST_STREAM_VOLUME
+GST_STREAM_VOLUME_INTERFACE
+GST_STREAM_VOLUME_GET_INTERFACE
+GST_IS_STREAM_VOLUME
+GST_IS_STREAM_VOLUME_INTERFACE
+gst_stream_volume_get_type
+</SECTION>
+
+<SECTION>
 <FILE>gsttuner</FILE>
 <INCLUDE>gst/interfaces/tuner.h</INCLUDE>
 GstTuner
diff --git a/gst-libs/gst/interfaces/Makefile.am b/gst-libs/gst/interfaces/Makefile.am
index 762d28ba4..811c52a9a 100644
--- a/gst-libs/gst/interfaces/Makefile.am
+++ b/gst-libs/gst/interfaces/Makefile.am
@@ -10,6 +10,7 @@ headers_interfaces = 		\
 	mixertrack.h		\
 	navigation.h		\
 	propertyprobe.h		\
+	streamvolume.h          \
 	tuner.h			\
 	tunernorm.h		\
 	tunerchannel.h		\
@@ -43,6 +44,7 @@ libgstinterfaces_@GST_MAJORMINOR@_la_SOURCES = \
 	mixertrack.c		\
 	navigation.c		\
 	propertyprobe.c		\
+	streamvolume.c          \
 	tuner.c			\
 	tunernorm.c		\
 	tunerchannel.c		\
@@ -54,7 +56,7 @@ nodist_libgstinterfaces_@GST_MAJORMINOR@_la_SOURCES = 	\
 	interfaces-marshal.h
 
 libgstinterfaces_@GST_MAJORMINOR@_la_CFLAGS = $(GST_PLUGINS_BASE_CFLAGS) $(GST_CFLAGS)
-libgstinterfaces_@GST_MAJORMINOR@_la_LIBADD = $(GST_LIBS) 
+libgstinterfaces_@GST_MAJORMINOR@_la_LIBADD = $(GST_LIBS) $(LIBM) 
 libgstinterfaces_@GST_MAJORMINOR@_la_LDFLAGS = $(GST_LIB_LDFLAGS) $(GST_ALL_LDFLAGS) $(GST_LT_LDFLAGS)
 
 BUILT_SOURCES = \
diff --git a/gst-libs/gst/interfaces/streamvolume.c b/gst-libs/gst/interfaces/streamvolume.c
new file mode 100644
index 000000000..4a65f15b2
--- /dev/null
+++ b/gst-libs/gst/interfaces/streamvolume.c
@@ -0,0 +1,225 @@
+/* GStreamer Mixer
+ * Copyright (C) 2009 Sebastian Dröge <sebastian.droege@collabora.co.uk>
+ *
+ * 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.
+ */
+
+/**
+ * SECTION:gststreamvolume
+ * @short_description: Interface for elements that provide a stream volume
+ *
+ * <refsect2>
+ * <para>
+ * This interface is implemented by elements that provide a stream volume. Examples for
+ * such elements are #volume and #playbin2.
+ * </para>
+ * <para>
+ * Applications can use this interface to get or set the current stream volume. For this
+ * the "volume" #GObject property can be used or the helper functions gst_stream_volume_set_volume()
+ * and gst_stream_volume_get_volume(). This volume is always a linear factor, i.e. 0.0 is muted
+ * 1.0 is 100%. For showing the volume in a GUI it might make sense to convert it to
+ * a different format by using gst_stream_volume_convert_volume(). Volume sliders should usually
+ * use a cubic volume.
+ *
+ * Separate from the volume the stream can also be muted by the "mute" #GObject property or
+ * gst_stream_volume_set_mute() and gst_stream_volume_get_mute().
+ * </para>
+ * <para>
+ * Elements that provide some kind of stream volume should implement the "volume" and
+ * "mute" #GObject properties and handle setting and getting of them properly.
+ * The volume property is defined to be a linear volume factor.
+ * </para>
+ * </refsect2>
+ */
+
+#ifdef HAVE_CONFIG_H
+#include "config.h"
+#endif
+
+#include "streamvolume.h"
+#include <math.h>
+
+static void
+gst_stream_volume_class_init (GstStreamVolumeInterface * iface)
+{
+  g_object_interface_install_property (iface,
+      g_param_spec_double ("volume",
+          "Volume",
+          "Linear volume factor, 1.0=100%",
+          0.0, G_MAXDOUBLE, 1.0, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
+  g_object_interface_install_property (iface,
+      g_param_spec_boolean ("mute",
+          "Mute",
+          "Mute the audio channel without changing the volume",
+          FALSE, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
+}
+
+GType
+gst_stream_volume_get_type (void)
+{
+  static volatile gsize type = 0;
+  if (g_once_init_enter (&type)) {
+    GType tmp;
+    static const GTypeInfo info = {
+      sizeof (GstStreamVolumeInterface),
+      NULL,                     /* base_init */
+      NULL,                     /* base_finalize */
+      (GClassInitFunc) gst_stream_volume_class_init,    /* class_init */
+      NULL,                     /* class_finalize */
+      NULL,                     /* class_data */
+      0,
+      0,                        /* n_preallocs */
+      NULL                      /* instance_init */
+    };
+    tmp = g_type_register_static (G_TYPE_INTERFACE,
+        "GstStreamVolume", &info, 0);
+    g_type_interface_add_prerequisite (tmp, G_TYPE_OBJECT);
+
+    g_once_init_leave (&type, tmp);
+  }
+  return type;
+}
+
+/**
+ * gst_stream_volume_get_volume:
+ * @volume: #GstStreamVolume that should be used
+ * @format: #GstStreamVolumeFormat which should be returned
+ *
+ * Returns: The current stream volume as linear factor
+ *
+ * Since: 0.10.25
+ */
+gdouble
+gst_stream_volume_get_volume (GstStreamVolume * volume,
+    GstStreamVolumeFormat format)
+{
+  gdouble val;
+
+  g_return_val_if_fail (GST_IS_STREAM_VOLUME (volume), 1.0);
+
+  g_object_get (volume, "volume", &val, NULL);
+  if (format != GST_STREAM_VOLUME_FORMAT_LINEAR)
+    val =
+        gst_stream_volume_convert_volume (GST_STREAM_VOLUME_FORMAT_LINEAR,
+        format, val);
+  return val;
+}
+
+/**
+ * gst_stream_volume_set_volume:
+ * @volume: #GstStreamVolume that should be used
+ * @format: #GstStreamVolumeFormat of @val
+ * @val: Linear volume factor that should be set
+ *
+ * Since: 0.10.25
+ */
+void
+gst_stream_volume_set_volume (GstStreamVolume * volume,
+    GstStreamVolumeFormat format, gdouble val)
+{
+  g_return_if_fail (GST_IS_STREAM_VOLUME (volume));
+
+  if (format != GST_STREAM_VOLUME_FORMAT_LINEAR)
+    val =
+        gst_stream_volume_convert_volume (format,
+        GST_STREAM_VOLUME_FORMAT_LINEAR, val);
+  g_object_set (volume, "volume", val, NULL);
+}
+
+/**
+ * gst_stream_volume_get_mute:
+ * @volume: #GstStreamVolume that should be used
+ *
+ * Returns: Returns %TRUE if the stream is muted
+ *
+ * Since: 0.10.25
+ */
+gboolean
+gst_stream_volume_get_mute (GstStreamVolume * volume)
+{
+  gboolean val;
+
+  g_return_val_if_fail (GST_IS_STREAM_VOLUME (volume), FALSE);
+
+  g_object_get (volume, "mute", &val, NULL);
+  return val;
+}
+
+/**
+ * gst_stream_volume_set_mute:
+ * @volume: #GstStreamVolume that should be used
+ * @mute: Mute state that should be set
+ *
+ * Since: 0.10.25
+ */
+void
+gst_stream_volume_set_mute (GstStreamVolume * volume, gboolean mute)
+{
+  g_return_if_fail (GST_IS_STREAM_VOLUME (volume));
+
+  g_object_set (volume, "mute", mute, NULL);
+}
+
+/**
+ * gst_stream_volume_convert_volume:
+ * @from: #GstStreamVolumeFormat to convert from
+ * @to: #GstStreamVolumeFormat to convert to
+ * @val: Volume in @from format that should be converted
+ *
+ * Returns: the converted volume
+ *
+ * Since: 0.10.25
+ */
+gdouble
+gst_stream_volume_convert_volume (GstStreamVolumeFormat from,
+    GstStreamVolumeFormat to, gdouble val)
+{
+  switch (from) {
+    case GST_STREAM_VOLUME_FORMAT_LINEAR:
+      g_return_val_if_fail (val >= 0.0, 0.0);
+      switch (to) {
+        case GST_STREAM_VOLUME_FORMAT_LINEAR:
+          return val;
+        case GST_STREAM_VOLUME_FORMAT_CUBIC:
+          return cbrt (val);
+        case GST_STREAM_VOLUME_FORMAT_DB:
+          return 20.0 * log10 (val);
+      }
+      break;
+    case GST_STREAM_VOLUME_FORMAT_CUBIC:
+      g_return_val_if_fail (val >= 0.0, 0.0);
+      switch (to) {
+        case GST_STREAM_VOLUME_FORMAT_LINEAR:
+          return val * val * val;
+        case GST_STREAM_VOLUME_FORMAT_CUBIC:
+          return val;
+        case GST_STREAM_VOLUME_FORMAT_DB:
+          return 3.0 * 20.0 * log10 (val);
+      }
+      break;
+    case GST_STREAM_VOLUME_FORMAT_DB:
+      switch (to) {
+        case GST_STREAM_VOLUME_FORMAT_LINEAR:
+          return pow (10.0, val / 20.0);
+        case GST_STREAM_VOLUME_FORMAT_CUBIC:
+          return pow (10.0, val / (3.0 * 20.0));
+        case GST_STREAM_VOLUME_FORMAT_DB:
+          return val;
+      }
+      break;
+  }
+  g_return_val_if_reached (0.0);
+}
diff --git a/gst-libs/gst/interfaces/streamvolume.h b/gst-libs/gst/interfaces/streamvolume.h
new file mode 100644
index 000000000..32a824c75
--- /dev/null
+++ b/gst-libs/gst/interfaces/streamvolume.h
@@ -0,0 +1,87 @@
+/* GStreamer StreamVolume
+ * Copyright (C) 2009 Sebastian Dröge <sebastian.droege@collabora.co.uk>
+ *
+ * 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_STREAM_VOLUME_H__
+#define __GST_STREAM_VOLUME_H__
+
+#include <gst/gst.h>
+
+G_BEGIN_DECLS
+
+#define GST_TYPE_STREAM_VOLUME \
+  (gst_stream_volume_get_type ())
+#define GST_STREAM_VOLUME(obj) \
+  (GST_IMPLEMENTS_INTERFACE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_STREAM_VOLUME, GstStreamVolume))
+#define GST_STREAM_VOLUME_INTERFACE(iface) \
+  (G_TYPE_CHECK_INTERFACE_CAST ((iface), GST_TYPE_STREAM_VOLUME, GstStreamVolumeInterface))
+#define GST_IS_STREAM_VOLUME(obj) \
+  (GST_IMPLEMENTS_INTERFACE_CHECK_INSTANCE_TYPE ((obj), GST_TYPE_STREAM_VOLUME))
+#define GST_IS_STREAM_VOLUME_INTERFACE(iface) \
+  (G_TYPE_CHECK_INTERFACE_TYPE ((iface), GST_TYPE_STREAM_VOLUME))
+#define GST_STREAM_VOLUME_GET_INTERFACE(inst) \
+  (G_TYPE_INSTANCE_GET_INTERFACE ((inst), GST_TYPE_STREAM_VOLUME, GstStreamVolumeInterface))
+
+typedef struct _GstStreamVolume GstStreamVolume;
+typedef struct _GstStreamVolumeInterface GstStreamVolumeInterface;
+
+struct _GstStreamVolumeInterface {
+  GTypeInterface parent;
+
+  /*< private >*/
+  gpointer _gst_reserved[GST_PADDING];
+};
+
+/**
+ * GstStreamVolumeFormat:
+ * @GST_STREAM_VOLUME_FORMAT_LINEAR: Linear scale factor, 1.0 = 100%
+ * @GST_STREAM_VOLUME_FORMAT_CUBIC: Cubic volume scale
+ * @GST_STREAM_VOLUME_FORMAT_DB: Logarithmic volume scale (dB, amplitude not power)
+ *
+ * Different representations of a stream volume. gst_stream_volume_convert()
+ * allows to convert between the different representations.
+ *
+ * Formulas to convert from a linear to a cubic or dB volume are
+ * cbrt(val) and 20 * log10 (val).
+ * 
+ * Since: 0.10.25
+ */
+typedef enum {
+  GST_STREAM_VOLUME_FORMAT_LINEAR = 0,
+  GST_STREAM_VOLUME_FORMAT_CUBIC,
+  GST_STREAM_VOLUME_FORMAT_DB
+} GstStreamVolumeFormat;
+
+GType           gst_stream_volume_get_type        (void);
+void            gst_stream_volume_set_volume      (GstStreamVolume *volume,
+                                                   GstStreamVolumeFormat format,
+                                                   gdouble val);
+gdouble         gst_stream_volume_get_volume      (GstStreamVolume *volume,
+                                                   GstStreamVolumeFormat format);
+
+void            gst_stream_volume_set_mute        (GstStreamVolume *volume,
+                                                   gboolean mute);
+gboolean        gst_stream_volume_get_mute        (GstStreamVolume *volume);
+
+gdouble         gst_stream_volume_convert_volume  (GstStreamVolumeFormat from,
+                                                   GstStreamVolumeFormat to,
+                                                   gdouble val) G_GNUC_CONST;
+
+G_END_DECLS
+
+#endif /* __GST_STREAM_VOLUME_H__ */
diff --git a/gst/playback/Makefile.am b/gst/playback/Makefile.am
index 7b0558707..89f58ae0a 100644
--- a/gst/playback/Makefile.am
+++ b/gst/playback/Makefile.am
@@ -27,6 +27,7 @@ libgstplaybin_la_CFLAGS = $(GST_PLUGINS_BASE_CFLAGS) $(GST_CFLAGS)
 libgstplaybin_la_LDFLAGS = $(GST_PLUGIN_LDFLAGS)
 libgstplaybin_la_LIBADD = \
 	$(top_builddir)/gst-libs/gst/pbutils/libgstpbutils-@GST_MAJORMINOR@.la \
+	$(top_builddir)/gst-libs/gst/interfaces/libgstinterfaces-@GST_MAJORMINOR@.la \
 	$(GST_LIBS)
 libgstplaybin_la_LIBTOOLFLAGS = --tag=disable-static
 
diff --git a/win32/common/libgstinterfaces.def b/win32/common/libgstinterfaces.def
index 191b0a5bc..37f3c05e8 100644
--- a/win32/common/libgstinterfaces.def
+++ b/win32/common/libgstinterfaces.def
@@ -76,6 +76,13 @@ EXPORTS
 	gst_property_probe_probe_and_get_values_name
 	gst_property_probe_probe_property
 	gst_property_probe_probe_property_name
+	gst_stream_volume_convert_volume
+	gst_stream_volume_format_get_type
+	gst_stream_volume_get_mute
+	gst_stream_volume_get_type
+	gst_stream_volume_get_volume
+	gst_stream_volume_set_mute
+	gst_stream_volume_set_volume
 	gst_tuner_channel_changed
 	gst_tuner_channel_flags_get_type
 	gst_tuner_channel_get_type