[Cogl] [PATCH] cogl-gst: Add some comments to the video player example

[Plamena Manolova]

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);
 
-- 
1.8.1.2

---------------------------------------------------------------------
Intel Corporation (UK) Limited
Registered No. 1134945 (England)
Registered Office: Pipers Way, Swindon SN3 1RJ
VAT No: 860 2173 47

This e-mail and any attachments may contain confidential material for
the sole use of the intended recipient(s). Any review or distribution
by others is strictly prohibited. If you are not the intended
recipient, please contact the sender and delete all copies.