Documentation update

Author: ktossell

doxygen.conf

@@ -803,7 +803,7 @@ EXCLUDE_SYMBOLS        =
 # that contain example code fragments that are included (see the \include
 # command).
 
-EXAMPLE_PATH           =
+EXAMPLE_PATH           = src
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and

src/example.c

@@ -0,0 +1,148 @@
+#include "libuvc/libuvc.h"
+#include <stdio.h>
+
+/* This callback function runs once per frame. Use it to perform any
+ * quick processing you need, or have it put the frame into your application's
+ * input queue. If this function takes too long, you'll start losing frames. */
+void cb(uvc_frame_t *frame, void *ptr) {
+  uvc_frame_t *bgr;
+  uvc_error_t ret;
+
+  /* We'll convert the image from YUV/JPEG to BGR, so allocate space */
+  bgr = uvc_allocate_frame(frame->width * frame->height * 3);
+  if (!bgr) {
+    printf("unable to allocate bgr frame!");
+    return;
+  }
+
+  /* Do the BGR conversion */
+  ret = uvc_any2bgr(frame, bgr);
+  if (ret) {
+    uvc_perror(ret, "uvc_any2bgr");
+    uvc_free_frame(bgr);
+    return;
+  }
+
+  /* Call a user function:
+   *
+   * my_type *my_obj = (*my_type) ptr;
+   * my_user_function(ptr, bgr);
+   * my_other_function(ptr, bgr->data, bgr->width, bgr->height);
+   */
+
+  /* Call a C++ method:
+   *
+   * my_type *my_obj = (*my_type) ptr;
+   * my_obj->my_func(bgr);
+   */
+
+  /* Use opencv.highgui to display the image:
+   * 
+   * cvImg = cvCreateImageHeader(
+   *     cvSize(bgr->width, bgr->height),
+   *     IPL_DEPTH_8U,
+   *     3);
+   *
+   * cvSetData(cvImg, bgr->data, bgr->width * 3); 
+   *
+   * cvNamedWindow("Test", CV_WINDOW_AUTOSIZE);
+   * cvShowImage("Test", cvImg);
+   * cvWaitKey(10);
+   *
+   * cvReleaseImageHeader(&cvImg);
+   */
+
+  uvc_free_frame(bgr);
+}
+
+int main(int argc, char **argv) {
+  uvc_context_t *ctx;
+  uvc_device_t *dev;
+  uvc_device_handle_t *devh;
+  uvc_stream_ctrl_t ctrl;
+  uvc_error_t res;
+
+  /* Initialize a UVC service context. Libuvc will set up its own libusb
+   * context. Replace NULL with a libusb_context pointer to run libuvc
+   * from an existing libusb context. */
+  res = uvc_init(&ctx, NULL);
+
+  if (res < 0) {
+    uvc_perror(res, "uvc_init");
+    return res;
+  }
+
+  puts("UVC initialized");
+
+  /* Locates the first attached UVC device, stores in dev */
+  res = uvc_find_device(
+      ctx, &dev,
+      0, 0, NULL); /* filter devices: vendor_id, product_id, "serial_num" */
+
+  if (res < 0) {
+    uvc_perror(res, "uvc_find_device"); /* no devices found */
+  } else {
+    puts("Device found");
+
+    /* Try to open the device: requires exclusive access */
+    res = uvc_open(dev, &devh);
+
+    if (res < 0) {
+      uvc_perror(res, "uvc_open"); /* unable to open device */
+    } else {
+      puts("Device opened");
+
+      /* Print out a message containing all the information that libuvc
+       * knows about the device */
+      uvc_print_diag(devh, stderr);
+
+      /* Try to negotiate a 640x480 30 fps YUYV stream profile */
+      res = uvc_get_stream_ctrl_format_size(
+          devh, &ctrl, /* result stored in ctrl */
+          UVC_COLOR_FORMAT_YUYV, /* YUV 422, aka YUV 4:2:2. try _COMPRESSED */
+          640, 480, 30 /* width, height, fps */
+      );
+
+      /* Print out the result */
+      uvc_print_stream_ctrl(&ctrl, stderr);
+
+      if (res < 0) {
+        uvc_perror(res, "get_mode"); /* device doesn't provide a matching stream */
+      } else {
+        /* Start the video stream in isochronous mode. The library will
+         * call user function cb: cb(frame, (void*) 12345)
+         */
+        res = uvc_start_iso_streaming(devh, &ctrl, cb, 12345);
+
+        if (res < 0) {
+          uvc_perror(res, "start_streaming"); /* unable to start stream */
+        } else {
+          puts("Streaming...");
+
+          uvc_set_ae_mode(devh, 1); /* e.g., turn on auto exposure */
+
+          sleep(10); /* stream for 10 seconds */
+
+          /* End the stream. Blocks until last callback is serviced */
+          uvc_stop_streaming(devh);
+          puts("Done streaming.");
+        }
+      }
+
+      /* Release our handle on the device */
+      uvc_close(devh);
+      puts("Device closed");
+    }
+
+    /* Release the device descriptor */
+    uvc_unref_device(dev);
+  }
+
+  /* Close the UVC context. This closes and cleans up any existing device handles,
+   * and it closes the libusb context if one was not provided. */
+  uvc_exit(ctx);
+  puts("UVC exited");
+
+  return 0;
+}
+

src/init.c

@@ -32,12 +32,43 @@
 *  POSSIBILITY OF SUCH DAMAGE.
 *********************************************************************/
 /**
-\mainpage
-\htmlinclude manifest.html
+\mainpage libuvc: a cross-platform library for USB video devices
 
 \b libuvc is a library that supports enumeration, control and streaming
 for USB Video Class (UVC) devices, such as consumer webcams.
 
+\section features Features
+\li Asynchronous video streaming (device to host) in isochronous mode
+\li Synchronous streaming API (but only isochronous streaming is available)
+\li Read/write access to standard device settings
+\li Conversion between various RGB and YUV formats
+\li Tested on Mac and Linux, portable to Windows and some BSDs
+
+\section roadmap Roadmap
+\li Bulk-mode image capture
+\li One-shot image capture
+\li Improved support for standard settings
+\li Support for "extended" (vendor-defined) settings
+
+\section misc Misc.
+\p The source code can be found at https://github.com/ktossell/libuvc. To build
+the library, install <a href="http://libusb.org/">libusb</a> 1.0+ and run:
+
+\code
+$ git clone https://github.com/ktossell/libuvc.git
+$ cd libuvc
+$ mkdir build
+$ cd build
+$ cmake -DCMAKE_BUILD_TYPE=Release ..
+$ make && make install
+\endcode
+
+\section Example
+In this example, libuvc is used to acquire images in a 30 fps, 640x480
+YUV stream from a UVC device such as a standard webcam.
+
+\include example.c
+
 */
 
 /**