diff options
Diffstat (limited to 'docs/manual.md')
| -rw-r--r-- | docs/manual.md | 154 |
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] |