[clutter-gst/expose-logic-interface] clutter-gst: Expose ClutterGstPlayer interface and document API

[Lionel Landwerlin <llandwerlin src gnome org>]

commit 19b6781a8f78b92cd0f4373799b622913e471376
Author: Lionel Landwerlin <lionel g landwerlin linux intel com>
Date:   Thu Aug 25 17:17:02 2011 +0100

    clutter-gst: Expose ClutterGstPlayer interface and document API

 clutter-gst/Makefile.am          |    2 +-
 clutter-gst/clutter-gst-player.c |  136 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 137 insertions(+), 1 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..80cbab3 100644
--- a/clutter-gst/clutter-gst-player.c
+++ b/clutter-gst/clutter-gst-player.c
@@ -1414,6 +1414,17 @@ clutter_gst_player_get_property (GObject    *object,
     }
 }
 
+/**
+ * clutter_gst_player_class_init:
+ * @player: a #ClutterGstPlayer
+ *
+ * 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 +1515,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)
 {
@@ -1641,6 +1664,17 @@ 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 pipeline element used by the video texture
+ *
+ * Since: 1.4
+ */
 GstElement *
 clutter_gst_player_get_pipeline (ClutterGstPlayer *player)
 {
@@ -1653,6 +1687,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 +1730,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 +1762,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 +1788,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 +1814,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 +1841,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 +1879,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 +1910,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 +1942,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 +1972,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)
 {