[cogl/wip/cogl-gst] cogl-gst: Add some comments to the video player example

[Neil Roberts <nroberts src gnome org>]

commit 9c9c7331316bab9e3ddae3e4fcb9409e30840e7b
Author: Plamena Manolova <plamena n manolova intel com>
Date:   Fri Mar 1 11:29:47 2013 +0000

    cogl-gst: Add some comments to the video player example
    
    Also removes reference to cogl-gst-video-player.h from cogl-gst.h

 cogl-gst/cogl-gst.h                |    1 -
 examples/cogl-basic-video-player.c |   56 ++++++++++++++++++++++++++++++++++-
 2 files changed, 54 insertions(+), 3 deletions(-)
---
diff --git a/cogl-gst/cogl-gst.h b/cogl-gst/cogl-gst.h
index e2cab38..655134c 100644
--- a/cogl-gst/cogl-gst.h
+++ b/cogl-gst/cogl-gst.h
@@ -34,6 +34,5 @@
 #define __COGL_GST_H__
 
 #include <cogl-gst/cogl-gst-video-sink.h>
-#include <cogl-gst/cogl-gst-video-player.h>
 
 #endif
diff --git a/examples/cogl-basic-video-player.c b/examples/cogl-basic-video-player.c
index 183b1e3..d2639ea 100644
--- a/examples/cogl-basic-video-player.c
+++ b/examples/cogl-basic-video-player.c
@@ -62,6 +62,12 @@ _draw  (gpointer instance,
         gpointer user_data)
 {
   Data *data = (Data*) user_data;
+  
+  /* 
+    The cogl pipeline needs to be retrieved from the sink before every draw.
+    This is due to the cogl-gst sink creating a new cogl pipeline for each frame
+    by copying the previous one and attaching the new frame to it.
+  */
   CoglPipeline* current = cogl_gst_video_sink_get_pipeline (data->sink);
 
   if (data->draw_ready)
@@ -83,11 +89,26 @@ _draw  (gpointer instance,
   return TRUE;
 }
 
+/* 
+  A callback like this should be attached to the cogl-pipeline-ready
+  signal. This way requesting the cogl pipeline before its creation 
+  by the sink is avoided. At this point, user textures and snippets can
+  be added to the cogl pipeline.
+*/
+
 static void
 _set_up_pipeline (gpointer instance,
                   gpointer user_data)
-{
+{    
   Data* data = (Data*) user_data;
+  
+  /*
+    The cogl-gst sink, depending on the video format, can use up to 3 texture 
+    layers to render a frame. To avoid overwriting frame data, the first
+    free layer in the cogl pipeline needs to be queried before adding any
+    additional textures.
+  */
+
   int free_layer = cogl_gst_video_sink_get_free_layer (data->sink);
   data->pln = cogl_gst_video_sink_get_pipeline (data->sink);
 
@@ -101,6 +122,14 @@ _set_up_pipeline (gpointer instance,
 
   cogl_onscreen_add_frame_callback(COGL_ONSCREEN (data->fb), _frame_callback,
                                    &data, NULL);
+                                   
+  /* 
+     The cogl-gst-new-frame signal is emitted when the cogl-gst sink has 
+     retrieved a new frame and attached it to the cogl pipeline. This can be 
+     used to make sure cogl doesn't do any unnecessary drawing i.e. keeps to the
+     frame-rate of the video.
+  */
+
   g_signal_connect (data->sink,"cogl-gst-new-frame", G_CALLBACK (_draw), data);
 }
 
@@ -119,6 +148,8 @@ main (int argc,
   GstBus *bus;
   char *uri;
 
+  /* Set the necessary cogl elements */
+  
   ctx = cogl_context_new (NULL, NULL);
   onscreen = cogl_onscreen_new (ctx, 640, 480);
   data.fb = COGL_FRAMEBUFFER (onscreen);
@@ -137,10 +168,20 @@ main (int argc,
                                       640, 480);
   cogl_framebuffer_set_modelview_matrix (data.fb, &view);
 
+  /* Intialize GStreamer */
+ 
   gst_init (&argc, &argv);
   
-  data.sink = cogl_gst_video_sink_new (ctx); 
+  /* 
+     Create the cogl-gst video sink by calling the cogl_gst_video_sink_new
+     function and passing it a CoglContext (this is used to create the
+     CoglPipeline and the texures for each frame). Alternatively you can use 
+     gst_element_factory_make ("coglsink", "some_name") and then set the
+     context with cogl_gst_video_sink_set_context.
+  */
 
+  data.sink = cogl_gst_video_sink_new (ctx); 
+  
   pipeline = gst_pipeline_new ("gst-player");
   bin = gst_element_factory_make ("playbin", "bin");
   
@@ -159,9 +200,20 @@ main (int argc,
   gst_element_set_state (pipeline, GST_STATE_PLAYING);
   bus = gst_pipeline_get_bus (GST_PIPELINE (pipeline));
   gst_bus_add_watch (bus, _bus_watch, &data);
+  
+  /* 
+    Retrieve the GMainLoop from the cogl-gst sink. GStreamer makes the use of a
+    GMainLoop necessary .
+  */
 
   loop = cogl_gst_video_sink_get_main_loop (data.sink);
 
+  /*
+    The cogl-pipeline-ready signal tells you when the cogl pipeline is
+    initialized i.e. when cogl-gst has figured out the video format and 
+    is prepared to retrieve and attach the first frame of the video.
+  */
+
   g_signal_connect (data.sink, "cogl-pipeline-ready",
                     G_CALLBACK (_set_up_pipeline), &data);