<page xmlns="http://projectmallard.org/1.0/"
      type="topic"
      id="magic-mirror.vala">

  <info>
    <link type="guide" xref="index#vala"/>

    <desc>Use your webcam as a mirror using the GStreamer framework and Gtk+</desc>

    <revision pkgversion="0.1" version="0.1" date="2011-03-19" status="review"/>
    <credit type="author">
      <name>Daniel G. Siegel</name>
      <email>dgsiegel@gnome.org</email>
    </credit>
    <credit type="author">
      <name>Johannes Schmid</name>
      <email>jhs@gnome.org</email>
    </credit>
  </info>

<title>Magic Mirror</title>

<synopsis>
  <p><em>Your mirror just fell off the wall and broke into a thousand pieces &#x2014; but you need a mirror to shave your beard off or add some makeup! You only have 15 minutes left before catching the bus to work. So what can you do?</em></p>
  <p>In this tutorial, we're going to make a program which lets you use your webcam as a mirror. You will learn how to:</p>
  <list>
    <item><p>Create a GTK+ application</p></item>
    <item><p>Access your webcam using GStreamer and embed the result into a window</p></item>
    <item><p>Grab photos off your webcam</p></item>
  </list>
  <p>You'll need the following to be able to follow this tutorial:</p>
  <list>
    <item><p>An installed copy of the <link xref="getting-ready">Anjuta IDE</link></p></item>
    <item><p>Installed copies of GTK, GStreamer, and a Vala compiler</p></item>
    <item><p>Basic knowledge of an object-oriented programming language</p></item>
  </list>
</synopsis>

<media type="image" mime="image/png" src="media/magic-mirror.png"/>

<section id="anjuta">
  <title>Create a project in Anjuta</title>
  <p>Before you start coding, you'll need to set up a new project in Anjuta. This will create all of the files you need to build and run the code later on. It's also useful for keeping everything together.</p>
  <steps>
    <item>
    <p>Start Anjuta and click <guiseq><gui>File</gui><gui>New</gui><gui>Project</gui></guiseq> to open the project wizard.</p>
    </item>
    <item>
    <p>Choose <gui>Gtk+ (simple)</gui> from the <gui>Vala</gui> tab, click <gui>Forward</gui>, and fill out your details on the next few pages. Use <file>guitar-tuner</file> as project name and directory.</p>
   	</item>
   	<item>
    <p>Disable <gui>Use GtkBuilder for user interface</gui> as we will
    create the UI manually in this tutorial. Check the <link xref="guitar-tuner.vala">Guitar-Tuner</link>
    tutorial using the interface builder.</p>
    </item>
    <item>
    <p>Make sure that <gui>Configure external packages</gui> is selected. On the next page, select
       <em>gstreamer-0.10</em> from the list to include the <app>GStreamer</app> library into your project.</p>
    </item>
    <item>
    <p>Click <gui>Apply</gui> and the project will be created for you. Open <file>src/magic_mirror.vala</file> from the <gui>Project</gui> or <gui>File</gui> tabs. You should see some code which starts with the lines:</p>
    <code mime="text/x-valasrc"><![CDATA[
using GLib;
using Gtk;]]></code>
    </item>
  </steps>
</section>

<section id="build">
  <title>Build the code for the first time</title>
  <p>The code loads an (empty) window and shows it. More details are given below; skip this list if you understand the basics:</p>
  <list>
  <item>
    <p>The two <code>using</code> lines import namespaces so we don't have to name them explicitly.</p>
   </item>
   <item>
    <p>The constructor of the <code>Main</code> class creates a new window and sets its title. Afterwards the window
    is shown and a signal is connected which quits the application if the window is closed. More on signals later on.</p>
   </item>
   <item>
    <p>The static <code>main</code> function is run by default when you start a Vala application. It calls a few functions which create the Main class, set up and then run the application. The <code>Gtk.Main</code> function starts the GTK main loop, which runs the user interface and starts listening for events (like clicks and key presses).</p>
   </item>
  </list>

  <p>This code is ready to be used, so you can compile it by clicking <guiseq><gui>Build</gui><gui>Build Project</gui></guiseq> (or press <keyseq><key>Shift</key><key>F7</key></keyseq>).</p>
  <p>Change the <gui>Configuration</gui> to <gui>Default</gui> and then press <gui>Execute</gui> to configure the build directory. You only need to do this once, for the first build.</p>
</section>

<section id="webcam">
 <title>Access the webcam video stream with GStreamer</title>
 <p>The GStreamer multimedia framework is able to handle video from webcams. Let's add GStreamer to our application and so we can access the video stream.</p>

<code mime="text/x-vala" style="numbered"><![CDATA[
using GLib;
using Gtk;

public class Main : Object 
{
	private Gst.Element camerabin;
	
	public Main () {
		this.camerabin = Gst.ElementFactory.make ("camerabin", "camera");
		this.camerabin.set_state (Gst.State.PLAYING);
	}

	static int main (string[] args) {
		Gtk.init (ref args);
		Gst.init (ref args);
		var app = new Main ();

		Gtk.main ();
		
		return 0;
	}
}
]]></code>
 <steps>
 <item><p>First we remove the window we created before because GStreamer will
 take care of showing the picture on screen.</p>
 </item>
  <item>
  <p>
  Now we are creating a GStreamer element which accesses our webcam. We are
  using the Camerabin element, which is an all-in-one camera element and is
  capable of taking photos, videos, applying effects and much more. Perfect for
  our use case! With <code>this.camerabin.set_state (Gst.State.PLAYING)</code>
  we tell the GStreamer pipeline we just created to start playing. Easy, no?
  </p>
  <p>Of course it is also possible to integrate the video more tighly into other
  windows but that is an advanced topic that includes some details of the X Window
  System we will omit here.
  </p>
  <p>
  Compile and run it again. You will end up with two windows. In the next step
  we will integrate the video into the GTK+ window.
  </p>
  </item>
 </steps>
</section>

<section id="impl">
 <title>Reference Implementation</title>
 <p>If you run into problems with the tutorial, compare your code with this <link href="magic-mirror/magic-mirror.vala">reference code</link>.
 There is also a more <link href="magic-mirror/magic-mirror-advanced.vala">extensive implementation</link> that embeds the window into a regular Gtk.Window
 which involves some advanced techniques, and adds buttons to start/stop the picture.</p>
</section>

<section id="further">
<title>Further reading</title>
<p>To find out more about the Vala programming language you might want to check out the 
<link href="http://live.gnome.org/Vala/Tutorial">Vala Tutorial</link>.</p>
</section>

<section id="conclusion">
<title>Conclusion</title>
  <p>
  That's it, you have managed to create a full-featured webcam photo
  application in 15 minutes. Now you can shave your beard off or add some makeup
  to your beautiful face, right before having a beautiful day at your
  workplace, where you can impress your friends and colleagues with an awesome
  application you just made in 15 minutes.
  </p>

</section>

</page>


