summaryrefslogtreecommitdiffstats
path: root/docs/manual.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/manual.md')
-rw-r--r--docs/manual.md154
1 files changed, 152 insertions, 2 deletions
diff --git a/docs/manual.md b/docs/manual.md
index 65805f3..ef45d52 100644
--- a/docs/manual.md
+++ b/docs/manual.md
@@ -152,9 +152,13 @@ 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.
+
+
[libpco]: http://ufo.kit.edu/repos/libpco.git/
[gobject-references]: http://developer.gnome.org/gobject/stable/gobject-memory.html#gobject-memory-refcount
+
### Grabbing frames
To synchronously grab frames, first start the camera:
@@ -209,7 +213,7 @@ 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),
+ g_object_set (G_OBJECT (camera),
"roi-width", roi_width,
"exposure-time", exposure_time,
NULL);
@@ -225,6 +229,149 @@ for `UfoFooCamera`. The latest nightly built reference can be found
[libuca-reference]: http://ufo.kit.edu/extra/libuca/reference/
+# More API
+
+In the [last section][], we had a quick glance over the basic API used to
+communicate with the camera. Now we will go into more detail.
+
+## Instantiating cameras
+
+We have already seen how to instantiate a camera object from a name. If you have
+more than one camera connected to a machine, you will most likely want the user
+decide which to use. To do so, you can enumerate all camera strings with
+`uca_camera_get_types`:
+
+~~~ {.c}
+ gchar **types;
+
+ types = uca_camera_get_types ();
+
+ for (guint i = 0; types[i] != NULL; i++)
+ g_print ("%s\n", types[i]);
+
+ /* free the string array */
+ g_strfreev (types);
+~~~
+
+If you _know_ which camera you want to use you can instantiate the sub-classed
+camera object directly. In this case we create a pco-based camera:
+
+~~~ {.c}
+#include <glib-object.h>
+#include <uca/uca-camera-pco.h>
+
+int
+main (int argc, char *argv[])
+{
+ UcaPcoCamera *camera;
+ GError *error = NULL;
+
+ g_type_init ();
+ camera = uca_pco_camera_new (&error);
+ g_object_unref (camera);
+ return 0;
+}
+~~~
+
+[last section]: #first-look-at-the-api
+
+
+## Errors
+
+All public API functions take a location of a pointer to a `GError` structure as
+a last argument. You can pass in a `NULL` value, in which case you cannot be
+notified about exceptional behavior. On the other hand, if you pass in a
+pointer to a `GError`, it must be initialized with `NULL` so that you do not
+accidentally overwrite and miss an error occurred earlier.
+
+Read more about `GError`s in the official GLib
+[documentation][GError].
+
+[GError]: http://developer.gnome.org/glib/stable/glib-Error-Reporting.html
+
+
+## Recording
+
+Recording frames is independent of actually grabbing them and is started with
+`uca_camera_start_recording`. You should always stop the recording with
+`ufo_camera_stop_recording` when you finished. When the recording has started,
+you can grab frames synchronously as described earlier. In this mode, a block to
+`uca_camera_grab` blocks until a frame is read from the camera. Grabbing might
+block indefinitely, when the camera is not functioning correctly or it is not
+triggered automatically.
+
+
+## Triggering
+
+`libuca` supports three trigger modes through the "trigger-mode" property:
+
+1. `UCA_CAMERA_TRIGGER_AUTO`: Exposure is triggered by the camera itself.
+2. `UCA_CAMERA_TRIGGER_INTERNAL`: Exposure is triggered via software.
+3. `UCA_CAMERA_TRIGGER_EXTERNAL`: Exposure is triggered by an external hardware
+ mechanism.
+
+With `UCA_CAMERA_TRIGGER_INTERNAL` you have to trigger with
+`uca_camera_trigger`:
+
+~~~ {.c}
+ /* thread A */
+ g_object_set (G_OBJECT (camera),
+ "trigger-mode", UCA_CAMERA_TRIGGER_INTERNAL,
+ NULL);
+
+ uca_camera_start_recording (camera, NULL);
+ uca_camera_grab (camera, &buffer, NULL);
+ uca_camera_stop_recording (camera, NULL);
+
+ /* thread B */
+ uca_camera_trigger (camera, NULL);
+~~~
+
+
+## Grabbing frames asynchronously
+
+In some applications, it might make sense to setup asynchronous frame
+acquisition, for which you will not be blocked by a call to `libuca`:
+
+~~~ {.c}
+static void
+callback (gpointer buffer, gpointer user_data)
+{
+ /*
+ * Do something useful with the buffer and the string we have got.
+ */
+}
+
+static void
+setup_async (UcaCamera *camera)
+{
+ gchar *s = g_strdup ("lorem ipsum");
+
+ g_object_set (G_OBJECT (camera),
+ "transfer-asynchronously", TRUE,
+ NULL);
+
+ uca_camera_set_grab_func (camera, callback, s);
+ uca_camera_start_recording (camera, NULL);
+
+ /*
+ * We will return here and `callback` will be called for each newo
+ * new frame.
+ */
+}
+~~~
+
+# Integrating new cameras
+
+A new camera is integrated by [sub-classing][] `UcaCamera` and implement all
+virtual methods. The simplest way is to take the `mock` camera and
+rename all occurences. Note, that if you class is going to be called `FooBar`,
+the upper case variant is `FOO_BAR` and the lower case variant is `foo_bar`.
+
+
+[sub-classing]: http://developer.gnome.org/gobject/stable/howto-gobject.html
+
+
# Tools
Several tools are available to ensure `libuca` works as expected. All of them
@@ -262,4 +409,7 @@ grabbing time:
sync 100 3 29848.98 8744.82
async 100 3 15739.43 4611.16
-# Integrating a new camera
+
+# The GObject Tango device
+
+[TODO: Get more information from Volker Kaiser and/or Mihael Koep]