[cogl/wip/cogl-gst-1.x: 9/29] cogl-gst: Add some comments to the video player example

[Lionel Landwerlin <llandwerlin src gnome org>]

commit 39766301204850a9a65b8a831bb2bec72c99ca2d
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 |   52 ++++++++++++++++++++++++++++++++++++
 2 files changed, 52 insertions(+), 1 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 95c616c..3ccd876 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,8 +168,18 @@ main (int argc,
                                       640, 480);
   cogl_framebuffer_set_modelview_matrix (data.fb, &view);
 
+  /* Intialize GStreamer */
+
   gst_init (&argc, &argv);
 
+  /*
+     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");
@@ -160,8 +201,19 @@ main (int argc,
   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);