1 /*********************************************************************
2 * Software License Agreement (BSD License)
4 * Copyright (C) 2010-2012 Ken Tossell
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions
11 * * Redistributions of source code must retain the above copyright
12 * notice, this list of conditions and the following disclaimer.
13 * * Redistributions in binary form must reproduce the above
14 * copyright notice, this list of conditions and the following
15 * disclaimer in the documentation and/or other materials provided
16 * with the distribution.
17 * * Neither the name of the author nor other contributors may be
18 * used to endorse or promote products derived from this software
19 * without specific prior written permission.
21 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
24 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
25 * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
26 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
27 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
28 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
29 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
31 * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
32 * POSSIBILITY OF SUCH DAMAGE.
33 *********************************************************************/
35 \mainpage libuvc: a cross-platform library for USB video devices
37 \b libuvc is a library that supports enumeration, control and streaming
38 for USB Video Class (UVC) devices, such as consumer webcams.
40 \section features Features
41 \li Asynchronous video streaming (device to host) in isochronous mode
42 \li Synchronous streaming API (but only isochronous streaming is available)
43 \li Read/write access to standard device settings
44 \li Conversion between various RGB and YUV formats
45 \li Tested on Mac and Linux, portable to Windows and some BSDs
47 \section roadmap Roadmap
48 \li Bulk-mode image capture
49 \li One-shot image capture
50 \li Improved support for standard settings
51 \li Support for "extended" (vendor-defined) settings
54 \p The source code can be found at https://github.com/ktossell/libuvc. To build
55 the library, install <a href="http://libusb.org/">libusb</a> 1.0+ and run:
58 $ git clone https://github.com/ktossell/libuvc.git
62 $ cmake -DCMAKE_BUILD_TYPE=Release ..
63 $ make && make install
67 In this example, libuvc is used to acquire images in a 30 fps, 640x480
68 YUV stream from a UVC device such as a standard webcam.
75 * @defgroup init Library initialization/deinitialization
77 #include "libuvc/libuvc.h"
78 #include "libuvc/libuvc_internal.h"
81 * @brief Event handler thread
82 * There's one of these per UVC context.
83 * @todo We shouldn't run this if we don't own the USB context
85 void *_uvc_handle_events(void *arg) {
86 uvc_context_t *ctx = (uvc_context_t *) arg;
88 while (!ctx->kill_handler_thread)
89 libusb_handle_events(ctx->usb_ctx);
93 /** @brief Initializes the UVC context
96 * @note If you provide your own USB context, you must handle
97 * libusb event processing using a function such as libusb_handle_events.
99 * @param[out] pctx The location where the context reference should be stored.
100 * @param[in] usb_ctx Optional USB context to use
101 * @return Error opening context or UVC_SUCCESS
103 uvc_error_t uvc_init(uvc_context_t **pctx, struct libusb_context *usb_ctx) {
104 uvc_error_t ret = UVC_SUCCESS;
105 uvc_context_t *ctx = calloc(1, sizeof(*ctx));
107 if (usb_ctx == NULL) {
108 ret = libusb_init(&ctx->usb_ctx);
109 ctx->own_usb_ctx = 1;
110 if (ret != UVC_SUCCESS) {
115 ctx->own_usb_ctx = 0;
116 ctx->usb_ctx = usb_ctx;
126 * @brief Closes the UVC context, shutting down any active cameras.
129 * @note This function invalides any existing references to the context's
132 * If no USB context was provided to #uvc_init, the UVC-specific USB
133 * context will be destroyed.
135 * @param ctx UVC context to shut down
137 void uvc_exit(uvc_context_t *ctx) {
138 uvc_device_handle_t *devh;
140 DL_FOREACH(ctx->open_devices, devh) {
144 if (ctx->own_usb_ctx)
145 libusb_exit(ctx->usb_ctx);
152 * @brief Spawns a handler thread for the context
155 * This should be called at the end of a successful uvc_open if no devices
156 * are already open (and being handled).
158 void uvc_start_handler_thread(uvc_context_t *ctx) {
159 if (ctx->own_usb_ctx)
160 pthread_create(&ctx->handler_thread, NULL, _uvc_handle_events, (void*) ctx);