Split up the manual

1 files changed, 228 insertions, 0 deletions

diff --git a/docs/quickstart.rst b/docs/quickstart.rst
new file mode 100644
index 0000000..59cb01e
--- /dev/null
+++ b/docs/quickstart.rst
@@ -0,0 +1,228 @@
+Quickstart
+==========
+
+Installation
+------------
+
+Before installing ``libuca`` itself, you should install any drivers and
+SDKs needed to access the cameras you want to access through ``libuca``.
+Now you have two options: install pre-built packages or build from
+source.
+
+
+Installing packages
+~~~~~~~~~~~~~~~~~~~
+
+Packages for the core library and all plugins are currently provided for
+openSUSE. To install them run ``zypper``:
+
+::
+
+    sudo zypper in libuca-x.y.z-x86_64.rpm
+    sudo zypper in uca-plugin-*.rpm
+
+To install development files such as headers, you have to install the
+``libuca-x.y.z-devel.rpm`` package.
+
+
+Building from source
+~~~~~~~~~~~~~~~~~~~~
+
+Building the library and installing from source is simple and
+straightforward. Make sure you have
+
+-  CMake,
+-  a C compiler,
+-  GLib and GObject development libraries and
+-  necessary camera SDKs
+
+installed.
+
+For the base system, install ::
+
+    [Debian] sudo apt-get install libglib2.0 cmake gcc
+    [openSUSE] sudo zypper in glib2-devel cmake gcc
+
+In case you want to use the graphical user interface you also need the
+Gtk+ development libraries::
+
+    [Debian] sudo apt-get install libgtk+2.0-dev
+    [openSUSE] sudo zypper in gtk2-devel
+
+To generate bindings for third-party languages, you have to install ::
+
+    [Debian] sudo apt-get install gobject-introspection
+    [openSUSE] sudo zypper in gobject-introspection-devel
+
+
+Fetching the sources
+^^^^^^^^^^^^^^^^^^^^
+
+Untar the distribution ::
+
+    untar xfz libuca-x.y.z.tar.gz
+
+or clone the repository ::
+
+    git clone http://ufo.kit.edu/git/libuca
+
+and create a new, empty build directory inside::
+
+    cd libuca/
+    mkdir build
+
+
+Configuring and building
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Now you need to create the Makefile with CMake. Go into the build
+directory and point CMake to the ``libuca`` top-level directory::
+
+    cd build/
+    cmake ..
+
+As long as the last line reads "Build files have been written to", the
+configuration stage is successful. In this case you can build ``libuca``
+with ::
+
+    make
+
+and install with ::
+
+    sudo make install
+
+If an *essential* dependency could not be found, the configuration stage
+will stop and build files will not be written. If a *non-essential*
+dependency (such as a certain camera SDK) is not found, the
+configuration stage will continue but that particular camera support not
+built.
+
+If you want to customize the build process you can pass several
+variables to CMake::
+
+    cmake .. -DPREFIX=/usr -DLIBDIR=/usr/lib64
+
+The former tells CMake to install into ``/usr`` instead of
+``/usr/local`` and the latter that we want to install the libraries and
+plugins into the ``lib64`` subdir instead of the default ``lib`` subdir
+as it is common on SUSE systems.
+
+
+Usage
+-----
+
+.. highlight:: c
+
+The API for accessing cameras is straightforward. First you need to
+include the necessary header files::
+
+    #include <glib-object.h>
+    #include <uca/uca-plugin-manager.h>
+    #include <uca/uca-camera.h>
+
+Then you need to setup the type system::
+
+    int
+    main (int argc, char *argv[])
+    {
+        UcaPluginManager *manager;
+        UcaCamera *camera;
+        GError *error = NULL; /* this _must_ be set to NULL */
+
+        g_type_init ();
+
+Now you can instantiate new camera *objects*. Each camera is identified
+by a human-readable string, in this case we want to access any pco
+camera that is supported by
+`libpco <http://ufo.kit.edu/repos/libpco.git/>`__. To instantiate a
+camera we have to create a plugin manager first::
+
+        manager = uca_plugin_manager_new ();
+        camera = uca_plugin_manager_get_camera (manager, "pco", &error);
+
+Errors are indicated with a returned value ``NULL`` and ``error`` set to
+a value other than ``NULL``::
+
+        if (camera == NULL) {
+            g_error ("Initialization: %s", error->message);
+            return 1;
+        }
+
+You should always remove the
+`reference <http://developer.gnome.org/gobject/stable/gobject-memory.html#gobject-memory-refcount>`__
+from the camera object when not using it in order to free all associated
+resources::
+
+        g_object_unref (camera);
+        return 0;
+    }
+
+Compile this program with ::
+
+    cc `pkg-config --cflags --libs libuca glib-2.0` foo.c -o foo
+
+Now, run ``foo`` and verify that no errors occur.
+
+
+Grabbing frames
+~~~~~~~~~~~~~~~
+
+To synchronously grab frames, first start the camera::
+
+        uca_camera_start_recording (camera, &error);
+        g_assert_no_error (error);
+
+Now, you have to allocate a suitably sized buffer and pass it to
+``uca_camera_grab``::
+
+        gpointer buffer = g_malloc0 (640 * 480 * 2);
+
+        uca_camera_grab (camera, buffer, &error);
+
+You have to make sure that the buffer is large enough by querying the
+size of the region of interest and the number of bits that are
+transferred.
+
+
+Getting and setting camera parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Because camera parameters vary tremendously between different vendors
+and products, they are realized with so-called GObject *properties*, a
+mechanism that maps string keys to typed and access restricted values.
+To get a value, you use the ``g_object_get`` function and provide memory
+where the result is stored::
+
+        guint roi_width;
+        gdouble exposure_time;
+
+        g_object_get (G_OBJECT(camera),
+                      "roi-width", &roi_width,
+                      "exposure-time", &exposure_time,
+                      /* The NULL marks the end! */
+                      NULL
+                      );
+
+        g_print ("Width of the region of interest: %d\n", roi_width);
+        g_print ("Exposure time: %3.5s\n", exposure_time);
+
+In a similar way, properties are set with ``g_object_set``::
+
+        guint roi_width = 512;
+        gdouble exposure_time = 0.001;
+
+        g_object_set (G_OBJECT (camera),
+                      "roi-width", roi_width,
+                      "exposure-time", exposure_time,
+                      NULL);
+
+Each property can be associated with a physical unit. To query for the
+unit call ``uca_camera_get_unit`` and pass a property name. The function
+will then return a value from the ``UcaUnit`` enum.
+
+Several essential camera parameters *must* be implemented by all
+cameras. To get a list of them consult the API reference for
+```UcaCamera`` <http://ufo.kit.edu/extra/libuca/reference/UcaCamera.html#UcaCamera.properties>`__.
+For camera specific parameters you need to consult the corresponding API
+reference for ``UfoFooCamera``. The latest nightly built reference can
+be found `here <http://ufo.kit.edu/extra/libuca/reference/>`__.