1 /*********************************************************************
2 * Software License Agreement (BSD License)
3 *
4 * Copyright (C) 2010-2012 Ken Tossell
5 * All rights reserved.
6 *
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions
9 * are met:
10 *
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.
20 *
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 *********************************************************************/
34 /**
35 \mainpage libuvc: a cross-platform library for USB video devices
36
37 \b libuvc is a library that supports enumeration, control and streaming
38 for USB Video Class (UVC) devices, such as consumer webcams.
39
40 \section features Features
41 \li UVC device \ref device "discovery and management" API
42 \li \ref streaming "Video streaming" (device to host) with asynchronous/callback and synchronous/polling modes
43 \li Read/write access to standard \ref ctrl "device settings"
44 \li \ref frame "Conversion" between various formats: RGB, YUV, JPEG, etc.
45 \li Tested on Mac and Linux, portable to Windows and some BSDs
46
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
52
53 \section misc Misc.
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:
56
57 \code
58 $ git clone https://github.com/ktossell/libuvc.git
59 $ cd libuvc
60 $ mkdir build
61 $ cd build
62 $ cmake -DCMAKE_BUILD_TYPE=Release ..
63 $ make && make install
64 \endcode
65
66 \section Example
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.
69
70 \include example.c
71
72 */
73
74 /**
75 * @defgroup init Library initialization/deinitialization
76 * @brief Setup routines used to construct UVC access contexts
77 */
78 #include "libuvc.h"
79 #include "libuvc_internal.h"
80
81 /** @internal
82 * @brief Event handler thread
83 * There's one of these per UVC context.
84 * @todo We shouldn't run this if we don't own the USB context
85 */
_uvc_handle_events(void * arg)86 void *_uvc_handle_events(void *arg) {
87 uvc_context_t *ctx = (uvc_context_t *) arg;
88
89 while (!ctx->kill_handler_thread)
90 {
91 if (ctx->usb_ctx) libusb_handle_events(ctx->usb_ctx);
92 else break;
93 }
94
95 return NULL;
96 }
97
98 /** @brief Initializes the UVC context
99 * @ingroup init
100 *
101 * @note If you provide your own USB context, you must handle
102 * libusb event processing using a function such as libusb_handle_events.
103 *
104 * @param[out] pctx The location where the context reference should be stored.
105 * @param[in] usb_ctx Optional USB context to use
106 * @return Error opening context or UVC_SUCCESS
107 */
uvc_init(uvc_context_t ** pctx,struct libusb_context * usb_ctx)108 uvc_error_t uvc_init(uvc_context_t **pctx, struct libusb_context *usb_ctx) {
109 uvc_error_t ret = UVC_SUCCESS;
110 uvc_context_t *ctx = calloc(1, sizeof(*ctx));
111
112 if (usb_ctx == NULL) {
113 ret = libusb_init(&ctx->usb_ctx);
114 ctx->own_usb_ctx = 1;
115 if (ret != UVC_SUCCESS) {
116 free(ctx);
117 ctx = NULL;
118 }
119 } else {
120 ctx->own_usb_ctx = 0;
121 ctx->usb_ctx = usb_ctx;
122 }
123
124 if (ctx != NULL)
125 *pctx = ctx;
126
127 return ret;
128 }
129
130 /**
131 * @brief Closes the UVC context, shutting down any active cameras.
132 * @ingroup init
133 *
134 * @note This function invalides any existing references to the context's
135 * cameras.
136 *
137 * If no USB context was provided to #uvc_init, the UVC-specific USB
138 * context will be destroyed.
139 *
140 * @param ctx UVC context to shut down
141 */
uvc_exit(uvc_context_t * ctx)142 void uvc_exit(uvc_context_t *ctx) {
143 uvc_device_handle_t *devh;
144
145 DL_FOREACH(ctx->open_devices, devh) {
146 uvc_close(devh);
147 }
148
149 if (ctx->own_usb_ctx)
150 libusb_exit(ctx->usb_ctx);
151
152 free(ctx);
153 }
154
155 /**
156 * @internal
157 * @brief Spawns a handler thread for the context
158 * @ingroup init
159 *
160 * This should be called at the end of a successful uvc_open if no devices
161 * are already open (and being handled).
162 */
uvc_start_handler_thread(uvc_context_t * ctx)163 void uvc_start_handler_thread(uvc_context_t *ctx) {
164 if (ctx->own_usb_ctx)
165 pthread_create(&ctx->handler_thread, NULL, _uvc_handle_events, (void*) ctx);
166 }
167
168