[rygel] docs: librygel-renderer: Describe full example

[Murray Cumming <murrayc src gnome org>]

commit af8d00fd79d8c9f53e34c4200c11f8294eaee40c
Author: Murray Cumming <murrayc murrayc com>
Date:   Tue Jan 22 15:03:38 2013 +0100

    docs: librygel-renderer: Describe full example

 .../gtkdoc/implementing-renderer-plugins.xml       |   18 +++++++++++-
 .../gtkdoc/implementing-renderers.xml              |   30 ++++++++++++++++++-
 .../gtkdoc/librygel-renderer-docs.xml              |   11 +------
 3 files changed, 47 insertions(+), 12 deletions(-)
---
diff --git a/doc/reference/librygel-renderer/gtkdoc/implementing-renderer-plugins.xml b/doc/reference/librygel-renderer/gtkdoc/implementing-renderer-plugins.xml
index 574e7e6..2755f84 100644
--- a/doc/reference/librygel-renderer/gtkdoc/implementing-renderer-plugins.xml
+++ b/doc/reference/librygel-renderer/gtkdoc/implementing-renderer-plugins.xml
@@ -6,13 +6,27 @@
 <!ENTITY url_refdocs_librygel_renderer_gst "http:/developer.gnome.org/librygel-renderer-gst/unstable/">
 ]>
 
-<section id="implementing-renderer-plugins">
+<chapter id="implementing-renderer-plugins">
+<title>Implementing Rygel Renderer Plugins</title>
+
+<section id="implementing-renderer-plugins-overview">
+<title>Implementing Renderer Plugins: Overview</title>
+
 
 <para>
 This library may be used to create Rygel renderer plugins by 
 implementing the <link linkend="RygelMediaRendererPlugin">RygelMediaRendererPlugin</link> class.
 </para>
 
+<para>The <link linkend="RygelMediaRendererPlugin">RygelMediaRendererPlugin</link> reference documentation 
+and this example explain how to implement these plugins.
+</para>
+
+</section>
+
+<section id="implementing-renderer-plugins-simple-example">
+<title>Implementing Renderer Plugins: Simple Example</title>
+
 <!-- TODO: Find a way to mention this C example code in the RygelMediaRendererPlugin valadoc comments instead. -->
 <para>
 This example source code shows how to implement a Rygel Renderer plugin.</para>
@@ -48,3 +62,5 @@ librygel-renderer-gst library, used in the <ulink url="&url_git_browse_base_src;
 
 </section>
 
+</chapter>
+
diff --git a/doc/reference/librygel-renderer/gtkdoc/implementing-renderers.xml b/doc/reference/librygel-renderer/gtkdoc/implementing-renderers.xml
index 33fa1c3..4a5e9dd 100644
--- a/doc/reference/librygel-renderer/gtkdoc/implementing-renderers.xml
+++ b/doc/reference/librygel-renderer/gtkdoc/implementing-renderers.xml
@@ -5,7 +5,11 @@
 <!ENTITY url_refdocs_librygel_renderer_gst "http:/developer.gnome.org/librygel-renderer-gst/unstable/">
 ]>
 
-<section id="implementing-renderers-gst">
+<chapter id="implementing-renderers">
+<title>Implementing Renderers</title>
+
+<section id="implementing-renderers-overview">
+<title>Implementing Renderers: Overview</title>
 
 
 <para>
@@ -17,6 +21,13 @@ See the derived
 class, from librygel-renderer-gst, to see how this can be done with GStreamer.
 </para>
 
+</section>
+
+<!-- TODO: Add a non-GST standalone-renderer example. Maybe use the same code as the example renderer plugin.
+<section id="implementing-server-plugins-simple-example">
+<title>Implementing Server Plugins: Simple Example</title>
+-->
+
 <!-- TODO: Find a way to mention this C example code in the RygelPlaybinRenderer valadoc comments instead. -->
 <!--
 <para>
@@ -27,12 +38,27 @@ and connect it to a network interface.
 
 
 <!-- Do not indent the xi:include node. That puts spaces at the start of the code. -->
-<!-- TODO: Add a non-GST standalone-renderer example. Maybe use the same code as the example renderer plugin.
+<!--
 <programlisting role="C">
 <xi:include  href="../../../../examples/standalone-renderer.c"
     parse="text"
     xmlns:xi="http://www.w3.org/2001/XInclude"/>
 </programlisting>
+
+</section>
 -->
 
+<section id="implementing-server-plugins-full-example">
+<title>Implementing Renderers: Full Example</title>
+
+<para>The external <ulink url="http://git.gnome.org/browse/rygel-gst-0-10-fullscreen-renderer";>rygel-gst-0-10-fullscreen-renderer</ulink> project provides a Rygel Renderer executable that uses an older GStreamer version and is an example of an external Rygel Renderer implemented in C. It plays content via UPnP.</para>
+
+<para>The <classname>RygelPlaybinPlayer</classname> class implements the <link linkend="RygelMediaPlayer">RygelMediaPlayer</link> interface, providing implementations for its virtual functions. For instance, see the <literal>rygel_playbin_player_real_set_uri()</literal> function, which delegates to the member <classname>GstPlaybin</classname> <classname>GstElement</classname>. The base class responds appropriately to UPnP messages, calling these virtual functions to request the specific behaviour.</para>
+
+<para>The <classname>RygelPlaybinRenderer</classname> class, derived from <link linkend="RygelMediaRenderer">RygelMediaRenderer</link>, provides the singleton instance of that player to its base class and has a <function>rygel_playbin_renderer_get_playbin()</function> function for convenience.</para>
+
+<para>Our <function>main()</function> instantiates our derived renderer and calls <function>rygel_playbin_renderer_get_playbin()</function> to get its GStreamer playbin element. We then use <function>gst_x_overlay_set_window_handle()</function> in our <literal>GtkWidget:realize</literal> signal handler. We connect the renderer to a network interface via <function>rygel_media_device_add_interface</function>, allowing the renderer to respond to UPnP messages.</para>
+
 </section>
+
+</chapter>
diff --git a/doc/reference/librygel-renderer/gtkdoc/librygel-renderer-docs.xml b/doc/reference/librygel-renderer/gtkdoc/librygel-renderer-docs.xml
index f6ae8d3..fdeb95c 100644
--- a/doc/reference/librygel-renderer/gtkdoc/librygel-renderer-docs.xml
+++ b/doc/reference/librygel-renderer/gtkdoc/librygel-renderer-docs.xml
@@ -20,15 +20,8 @@
     <xi:include href="overview.xml"/>
   </preface>
 
-  <chapter>
-    <title>Implementing Renderers</title>
-    <xi:include href="implementing-renderers.xml"/>
-  </chapter>
-
-  <chapter>
-    <title>Implementing Rygel Renderer Plugins</title>
-    <xi:include href="implementing-renderer-plugins.xml"/>
-  </chapter>
+  <xi:include href="implementing-renderers.xml"/>
+  <xi:include href="implementing-renderer-plugins.xml"/>
 
   <!-- These are generated: -->
   <chapter>