--- /dev/null
+/*********************************************************************
+* Software License Agreement (BSD License)
+*
+* Copyright (C) 2010-2012 Ken Tossell
+* All rights reserved.
+*
+* Redistribution and use in source and binary forms, with or without
+* modification, are permitted provided that the following conditions
+* are met:
+*
+* * Redistributions of source code must retain the above copyright
+* notice, this list of conditions and the following disclaimer.
+* * Redistributions in binary form must reproduce the above
+* copyright notice, this list of conditions and the following
+* disclaimer in the documentation and/or other materials provided
+* with the distribution.
+* * Neither the name of the author nor other contributors may be
+* used to endorse or promote products derived from this software
+* without specific prior written permission.
+*
+* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+* FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+* COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+* INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+* BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+* LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+* CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+* ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+* POSSIBILITY OF SUCH DAMAGE.
+*********************************************************************/
+/**
+\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 UVC device \ref device "discovery and management" API
+\li \ref streaming "Video streaming" (device to host) with asynchronous/callback and synchronous/polling modes
+\li Read/write access to standard \ref ctrl "device settings"
+\li \ref frame "Conversion" between various formats: RGB, YUV, JPEG, etc.
+\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
+
+*/
+
+/**
+ * @defgroup init Library initialization/deinitialization
+ * @brief Setup routines used to construct UVC access contexts
+ */
+#include "libuvc/libuvc.h"
+#include "libuvc/libuvc_internal.h"
+
+/** @internal
+ * @brief Event handler thread
+ * There's one of these per UVC context.
+ * @todo We shouldn't run this if we don't own the USB context
+ */
+void *_uvc_handle_events(void *arg) {
+ uvc_context_t *ctx = (uvc_context_t *) arg;
+
+ while (!ctx->kill_handler_thread)
+ libusb_handle_events_completed(ctx->usb_ctx, &ctx->kill_handler_thread);
+ return NULL;
+}
+
+/** @brief Initializes the UVC context
+ * @ingroup init
+ *
+ * @note If you provide your own USB context, you must handle
+ * libusb event processing using a function such as libusb_handle_events.
+ *
+ * @param[out] pctx The location where the context reference should be stored.
+ * @param[in] usb_ctx Optional USB context to use
+ * @return Error opening context or UVC_SUCCESS
+ */
+uvc_error_t uvc_init(uvc_context_t **pctx, struct libusb_context *usb_ctx) {
+ uvc_error_t ret = UVC_SUCCESS;
+ uvc_context_t *ctx = calloc(1, sizeof(*ctx));
+
+ if (usb_ctx == NULL) {
+ ret = libusb_init(&ctx->usb_ctx);
+ ctx->own_usb_ctx = 1;
+ if (ret != UVC_SUCCESS) {
+ free(ctx);
+ ctx = NULL;
+ }
+ } else {
+ ctx->own_usb_ctx = 0;
+ ctx->usb_ctx = usb_ctx;
+ }
+
+ if (ctx != NULL)
+ *pctx = ctx;
+
+ return ret;
+}
+
+/**
+ * @brief Closes the UVC context, shutting down any active cameras.
+ * @ingroup init
+ *
+ * @note This function invalides any existing references to the context's
+ * cameras.
+ *
+ * If no USB context was provided to #uvc_init, the UVC-specific USB
+ * context will be destroyed.
+ *
+ * @param ctx UVC context to shut down
+ */
+void uvc_exit(uvc_context_t *ctx) {
+ uvc_device_handle_t *devh;
+
+ DL_FOREACH(ctx->open_devices, devh) {
+ uvc_close(devh);
+ }
+
+ if (ctx->own_usb_ctx)
+ libusb_exit(ctx->usb_ctx);
+
+ free(ctx);
+}
+
+/**
+ * @internal
+ * @brief Spawns a handler thread for the context
+ * @ingroup init
+ *
+ * This should be called at the end of a successful uvc_open if no devices
+ * are already open (and being handled).
+ */
+void uvc_start_handler_thread(uvc_context_t *ctx) {
+ if (ctx->own_usb_ctx)
+ pthread_create(&ctx->handler_thread, NULL, _uvc_handle_events, (void*) ctx);
+}
+