<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY url_refdocs_librygel_renderer_gst "http:/developer.gnome.org/librygel-renderer-gst/unstable/">
]>

<chapter id="implementing-renderers">
<title>Implementing Renderers</title>

<section id="implementing-renderers-overview">
<title>Implementing Renderers: Overview</title>


<para>
This library may be used to create in-process UPnP/DLNA Renderers, or Players, via
the <link linkend="RygelMediaRenderer">RygelMediaRenderer</link> class. For instance,
this may be used to add UPnP/DLNA Renderer or Player capability to an existing media player application.
See the derived
<ulink url="&url_refdocs_librygel_renderer_gst;RygelPlaybinRenderer.html">RygelPlaybinRenderer</ulink>
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>
This example program shows how to instantiate the renderer then configure its GStreamer playbin element
and connect it to a network interface.
</para>
-->


<!-- Do not indent the xi:include node. That puts spaces at the start of the code. -->
<!--
<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-renderers-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, based on the implementation code in <ulink url="http://developer.gnome.org/librygel-renderer-gst/unstable/">librygel-renderer-gst</ulink>. 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>
