clutter-gst: Expose ClutterGstPlayer interface and document API

5 files changed, 259 insertions, 7 deletions

diff --git a/clutter-gst/Makefile.am b/clutter-gst/Makefile.am
index 8424d5d..06f2248 100644
--- a/clutter-gst/Makefile.am
+++ b/clutter-gst/Makefile.am
@@ -27,12 +27,12 @@ source_h = 					\
 	$(srcdir)/clutter-gst-version.h		\
 	$(srcdir)/clutter-gst-video-sink.h 	\
 	$(srcdir)/clutter-gst-video-texture.h 	\
+	$(srcdir)/clutter-gst-player.h		\
 	$(NULL)
 
 source_priv_h =					\
 	$(srcdir)/clutter-gst-debug.h		\
 	$(srcdir)/clutter-gst-marshal.h		\
-	$(srcdir)/clutter-gst-player.h		\
 	$(srcdir)/clutter-gst-private.h		\
 	$(srcdir)/clutter-gst-shaders.h		\
 	$(NULL)
diff --git a/clutter-gst/clutter-gst-player.c b/clutter-gst/clutter-gst-player.c
index 1cb1fb8..704d95e 100644
--- a/clutter-gst/clutter-gst-player.c
+++ b/clutter-gst/clutter-gst-player.c
@@ -26,6 +26,21 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:clutter-gst-player
+ * @short_description: An interface for controlling playback of media data
+ *
+ * #ClutterGstPlayer is an interface for controlling playback of media
+ *  sources. Contrary to most interfaces, you don't need to implement
+ *  #ClutterGstPlayer. It already provides an implementation/logic
+ *  leaving you only tweak a few properties to get the desired behavior.
+ *
+ * #ClutterGstPlayer extends and implements #ClutterMedia to create
+ * enhanced player.
+ *
+ * #ClutterMedia is available since Clutter 0.2
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -1414,6 +1429,17 @@ clutter_gst_player_get_property (GObject    *object,
     }
 }
 
+/**
+ * clutter_gst_player_class_init:
+ * @object_class: a #GObjectClass
+ *
+ * Adds the #ClutterGstPlayer properties to a class and surchages the
+ * set/get_property and dispose of #GObjectClass. You should call this
+ * function at the end of the class_init method of the class
+ * implementing #ClutterGstPlayer.
+ *
+ * Since: 1.4
+ */
 void
 clutter_gst_player_class_init (GObjectClass *object_class)
 {
@@ -1504,6 +1530,18 @@ get_pipeline (void)
   return pipeline;
 }
 
+/**
+ * clutter_gst_player_init:
+ * @player: a #ClutterGstPlayer
+ *
+ * Initialize a #ClutterGstPlayer instance. You should call this
+ * function at the beginning of the init method of the class
+ * implementing #ClutterGstPlayer.
+ *
+ * Return value: TRUE if the initialization was successfull, FALSE otherwise.
+ *
+ * Since: 1.4
+ */
 gboolean
 clutter_gst_player_init (ClutterGstPlayer *player)
 {
@@ -1518,6 +1556,7 @@ clutter_gst_player_init (ClutterGstPlayer *player)
   priv = g_slice_new0 (ClutterGstPlayerPrivate);
   PLAYER_SET_PRIVATE (player, priv);
 
+  priv->is_idle = TRUE;
   priv->in_seek = FALSE;
   priv->is_changing_uri = FALSE;
   priv->in_download_buffering = FALSE;
@@ -1585,13 +1624,27 @@ clutter_gst_player_default_init (ClutterGstPlayerIface *iface)
 {
   GParamSpec *pspec;
 
-  pspec = g_param_spec_string ("idle",
-                               "Idle",
-                               "Idle state of the player's pipeline",
-                               NULL,
-                               CLUTTER_GST_PARAM_READABLE);
+  /**
+   * ClutterGstPlayer:idle:
+   *
+   * Whether the #ClutterGstPlayer is in idle mode.
+   *
+   * Since: 1.4
+   */
+  pspec = g_param_spec_boolean ("idle",
+                                "Idle",
+                                "Idle state of the player's pipeline",
+                                TRUE,
+                                CLUTTER_GST_PARAM_READABLE);
   g_object_interface_install_property (iface, pspec);
 
+  /**
+   * ClutterGstPlayer:user-agent:
+   *
+   * The User Agent used by #ClutterGstPlayer with network protocols.
+   *
+   * Since: 1.4
+   */
   pspec = g_param_spec_string ("user-agent",
                                "User Agent",
                                "User Agent used with network protocols",
@@ -1599,6 +1652,13 @@ clutter_gst_player_default_init (ClutterGstPlayerIface *iface)
                                CLUTTER_GST_PARAM_READWRITE);
   g_object_interface_install_property (iface, pspec);
 
+  /**
+   * ClutterGstPlayer:seek-flags:
+   *
+   * Flags to use when seeking.
+   *
+   * Since: 1.4
+   */
   pspec = g_param_spec_flags ("seek-flags",
                               "Seek Flags",
                               "Flags to use when seeking",
@@ -1607,12 +1667,26 @@ clutter_gst_player_default_init (ClutterGstPlayerIface *iface)
                               CLUTTER_GST_PARAM_READWRITE);
   g_object_interface_install_property (iface, pspec);
 
+  /**
+   * ClutterGstPlayer:audio-streams:
+   *
+   * List of audio streams available on the current media.
+   *
+   * Since: 1.4
+   */
   pspec = g_param_spec_pointer ("audio-streams",
                                 "Audio Streams",
                                 "List of the audio streams of the media",
                                 CLUTTER_GST_PARAM_READABLE);
   g_object_interface_install_property (iface, pspec);
 
+  /**
+   * ClutterGstPlayer:audio-stream:
+   *
+   * Index of the current audio stream.
+   *
+   * Since: 1.4
+   */
   pspec = g_param_spec_int ("audio-stream",
                             "Audio Stream",
                             "Index of the current audio stream",
@@ -1621,6 +1695,18 @@ clutter_gst_player_default_init (ClutterGstPlayerIface *iface)
   g_object_interface_install_property (iface, pspec);
 
   /* Signals */
+
+  /**
+   * ClutterGstPlayer::download-buffering:
+   * @player: the #ClutterGstPlayer instance that received the signal
+   * @start: start position of the buffering
+   * @stop: start position of the buffering
+   *
+   * The ::download-buffering signal is emitted each time their an
+   * update about the buffering of the current media.
+   *
+   * Since: 1.4
+   */
   signals[DOWNLOAD_BUFFERING] =
     g_signal_new ("download-buffering",
                   CLUTTER_GST_TYPE_PLAYER,
@@ -1641,6 +1727,18 @@ clutter_gst_player_default_init (ClutterGstPlayerIface *iface)
     }
 }
 
+/**
+ * clutter_gst_player_get_pipeline:
+ * @player: a #ClutterGstPlayer
+ *
+ * Retrieves the #GstPipeline used by the @player, for direct use with
+ * GStreamer API.
+ *
+ * Return value: (transfer none): the #GstPipeline element used by the
+ * video texture
+ *
+ * Since: 1.4
+ */
 GstElement *
 clutter_gst_player_get_pipeline (ClutterGstPlayer *player)
 {
@@ -1653,6 +1751,17 @@ clutter_gst_player_get_pipeline (ClutterGstPlayer *player)
   return priv->pipeline;
 }
 
+/**
+ * clutter_gst_player_get_user_agent:
+ * @player: a #ClutterGstPlayer
+ *
+ * Retrieves the user agent used when streaming.
+ *
+ * Return value: the user agent used. The returned string has to be freed with
+ * g_free()
+ *
+ * Since: 1.4
+ */
 gchar *
 clutter_gst_player_get_user_agent (ClutterGstPlayer *player)
 {
@@ -1685,6 +1794,19 @@ clutter_gst_player_get_user_agent (ClutterGstPlayer *player)
   return user_agent;
 }
 
+/**
+ * clutter_gst_player_set_user_agent:
+ * @player: a #ClutterGstPlayer
+ * @user_agent: the user agent
+ *
+ * Sets the user agent to use when streaming.
+ *
+ * When streaming content, you might want to set a custom user agent, eg. to
+ * promote your software, make it appear in statistics or because the server
+ * requires a special user agent you want to impersonate.
+ *
+ * Since: 1.4
+ */
 void
 clutter_gst_player_set_user_agent (ClutterGstPlayer *player,
                                    const gchar      *user_agent)
@@ -1704,6 +1826,16 @@ clutter_gst_player_set_user_agent (ClutterGstPlayer *player,
   player_set_user_agent (player, user_agent);
 }
 
+/**
+ * clutter_gst_player_get_seek_flags:
+ * @player: a #ClutterGstPlayer
+ *
+ * Get the current value of the seek-flags property.
+ *
+ * Return value: a combination of #ClutterGstSeekFlags
+ *
+ * Since: 1.4
+ */
 ClutterGstSeekFlags
 clutter_gst_player_get_seek_flags (ClutterGstPlayer *player)
 {
@@ -1720,6 +1852,16 @@ clutter_gst_player_get_seek_flags (ClutterGstPlayer *player)
     return CLUTTER_GST_SEEK_FLAG_NONE;
 }
 
+/**
+ * clutter_gst_player_set_seek_flags:
+ * @player: a #ClutterGstPlayer
+ * @flags: a combination of #ClutterGstSeekFlags
+ *
+ * Seeking can be done with several trade-offs. Clutter-gst defaults
+ * to %CLUTTER_GST_SEEK_FLAG_NONE.
+ *
+ * Since: 1.4
+ */
 void
 clutter_gst_player_set_seek_flags (ClutterGstPlayer    *player,
                                    ClutterGstSeekFlags  flags)
@@ -1736,6 +1878,14 @@ clutter_gst_player_set_seek_flags (ClutterGstPlayer    *player,
     priv->seek_flags = GST_SEEK_FLAG_ACCURATE;
 }
 
+/**
+ * clutter_gst_player_get_buffering_mode:
+ * @player: a #ClutterGstPlayer
+ *
+ * Return value: a #ClutterGstBufferingMode
+ *
+ * Since: 1.4
+ */
 ClutterGstBufferingMode
 clutter_gst_player_get_buffering_mode (ClutterGstPlayer *player)
 {
@@ -1755,6 +1905,13 @@ clutter_gst_player_get_buffering_mode (ClutterGstPlayer *player)
   return CLUTTER_GST_BUFFERING_MODE_STREAM;
 }
 
+/**
+ * clutter_gst_player_set_buffering_mode:
+ * @player: a #ClutterGstPlayer
+ * @mode: a #ClutterGstBufferingMode
+ *
+ * Since: 1.4
+ */
 void
 clutter_gst_player_set_buffering_mode (ClutterGstPlayer        *player,
                                        ClutterGstBufferingMode  mode)
@@ -1786,6 +1943,16 @@ clutter_gst_player_set_buffering_mode (ClutterGstPlayer        *player,
   g_object_set (G_OBJECT (priv->pipeline), "flags", flags, NULL);
 }
 
+/**
+ * clutter_gst_player_get_audio_streams:
+ * @player: a #ClutterGstPlayer
+ *
+ * Get the list of audio streams of the current media.
+ *
+ * Return value: a list of strings describing the available audio streams
+ *
+ * Since: 1.4
+ */
 GList *
 clutter_gst_player_get_audio_streams (ClutterGstPlayer *player)
 {
@@ -1807,6 +1974,19 @@ clutter_gst_player_get_audio_streams (ClutterGstPlayer *player)
   return priv->audio_streams;
 }
 
+/**
+ * clutter_gst_player_get_audio_stream:
+ * @player: a #ClutterGstPlayer
+ *
+ * Get the current audio stream. The number returned in the index of the
+ * audio stream playing in the list returned by
+ * clutter_gst_player_get_audio_streams().
+ *
+ * Return value: the index of the current audio stream, -1 if the media has no
+ * audio stream
+ *
+ * Since: 1.4
+ */
 gint
 clutter_gst_player_get_audio_stream (ClutterGstPlayer *player)
 {
@@ -1826,6 +2006,16 @@ clutter_gst_player_get_audio_stream (ClutterGstPlayer *player)
   return index_;
 }
 
+/**
+ * clutter_gst_player_set_audio_stream:
+ * @player: a #ClutterGstPlayer
+ * @index_: the index of the audio stream
+ *
+ * Set the audio stream to play. @index_ is the index of the stream
+ * in the list returned by clutter_gst_player_get_audio_streams().
+ *
+ * Since: 1.4
+ */
 void
 clutter_gst_player_set_audio_stream (ClutterGstPlayer *player,
                                      gint              index_)
@@ -1846,6 +2036,16 @@ clutter_gst_player_set_audio_stream (ClutterGstPlayer *player,
                 NULL);
 }
 
+/**
+ * clutter_gst_player_get_idle:
+ * @player: a #ClutterGstPlayer
+ *
+ * Get the idle state of the pipeline.
+ *
+ * Return value: TRUE if the pipline is in idle mode, FALSE otherwise.
+ *
+ * Since: 1.4
+ */
 gboolean
 clutter_gst_player_get_idle (ClutterGstPlayer *player)
 {
diff --git a/clutter-gst/clutter-gst-player.h b/clutter-gst/clutter-gst-player.h
index 120e59c..cd3fb3f 100644
--- a/clutter-gst/clutter-gst-player.h
+++ b/clutter-gst/clutter-gst-player.h
@@ -56,6 +56,23 @@ typedef struct _ClutterGstPlayerIface ClutterGstPlayerIface;
 typedef struct _ClutterGstPlayerIfacePrivate ClutterGstPlayerIfacePrivate;
 
 
+/**
+ * ClutterGstPlayer
+ *
+ * #ClutterGstPlayer is an opaque structure whose members cannot be
+ * directly accessed
+ *
+ * Since: 1.4
+ */
+
+/**
+ * ClutterGstPlayerIface:
+ * @download_buffering: handler for the #ClutterGstPlayer::download-buffering signal
+ *
+ * Interface vtable for #ClutterGstPlayer implementations
+ *
+ * Since: 1.4
+ */
 struct _ClutterGstPlayerIface
 {
   /*< private >*/
@@ -64,9 +81,15 @@ struct _ClutterGstPlayerIface
   ClutterGstPlayerIfacePrivate *priv;
 
   /*< public >*/
+  /* signals */
   void (* download_buffering) (ClutterGstPlayer *player,
 			       gdouble           start,
 			       gdouble           stop);
+  void (* _clutter_reserved2) (void);
+  void (* _clutter_reserved3) (void);
+  void (* _clutter_reserved4) (void);
+  void (* _clutter_reserved5) (void);
+  void (* _clutter_reserved6) (void);
 };
 
 GType clutter_gst_player_get_type (void) G_GNUC_CONST;
diff --git a/doc/reference/clutter-gst-docs.sgml b/doc/reference/clutter-gst-docs.sgml
index 1a78000..80fe1f7 100644
--- a/doc/reference/clutter-gst-docs.sgml
+++ b/doc/reference/clutter-gst-docs.sgml
@@ -1,5 +1,5 @@
 <?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
 <!ENTITY version SYSTEM "version.xml">
 ]>
@@ -55,6 +55,7 @@
 
   <chapter>
     <title>Clutter Actors And Objects</title>
+    <xi:include href="xml/clutter-gst-player.xml"/>
     <xi:include href="xml/clutter-gst-video-texture.xml"/>
     <xi:include href="xml/clutter-gst-video-sink.xml"/>
     <xi:include href="xml/clutter-gst-util.xml"/>
diff --git a/doc/reference/clutter-gst-sections.txt b/doc/reference/clutter-gst-sections.txt
index 6bc2120..78e2dbf 100644
--- a/doc/reference/clutter-gst-sections.txt
+++ b/doc/reference/clutter-gst-sections.txt
@@ -11,6 +11,34 @@ CLUTTER_GST_TYPE_BUFFERING_MODE
 </SECTION>
 
 <SECTION>
+<FILE>clutter-gst-player</FILE>
+<TITLE>ClutterGstPlayer</TITLE>
+ClutterGstPlayer
+ClutterGstPlayerIface
+clutter_gst_player_class_init
+clutter_gst_player_init
+clutter_gst_player_get_pipeline
+clutter_gst_player_get_user_agent
+clutter_gst_player_set_user_agent
+clutter_gst_player_set_seek_flags
+clutter_gst_player_get_seek_flags
+clutter_gst_player_get_buffering_mode
+clutter_gst_player_set_buffering_mode
+clutter_gst_player_get_audio_streams
+clutter_gst_player_get_audio_stream
+clutter_gst_player_set_audio_stream
+clutter_gst_player_get_idle
+<SUBSECTION Standard>
+CLUTTER_GST_PLAYER
+CLUTTER_GST_IS_PLAYER
+CLUTTER_GST_TYPE_PLAYER
+clutter_gst_player_get_type
+CLUTTER_GST_PLAYER_GET_INTERFACE
+<SUBSECTION Private>
+ClutterGstPlayerIfacePrivate
+</SECTION>
+
+<SECTION>
 <FILE>clutter-gst-video-texture</FILE>
 <TITLE>ClutterGstVideoTexture</TITLE>
 ClutterGstVideoTexture