USB Video Class Gadget Library - libguvc

From RidgeRun Developer Connection
Jump to: navigation, search

RR Eval SDK download button.png RR Pre built demo image download.png RR Contact Us.png

Introduction

The USB Video Class Gadget Library or libguvc for short is a platform agnostic library that simplifies the development of UVC based gadget devices by encapsulating the most of the UVC communication leaving just the basic setup to the user. It runs on top of the UVC function driver in the user space and takes care of the communication between the user application and the linux driver stack. The figure 1 depicts the software stack on a common use case scenario.

Figure 1. Software stack description using libguvc

libguvc in action

Features

The following table list the main features provided by the libguvc and the corresponding library version:

Feature Release version
User Pointer support 1.0.x
Extension Units support 1.0.x
YUY2 video format support 1.0.x
USB requests support 1.0.x
Pull mode support 1.0.x
MMAP support 1.1.x
MJPEG support 1.1.x
gst-uvc-sink element 1.2.x
H264 support* 1.3.x
  • The libguvc library only implements the UVC 1.1 specification since the linux kernel driver only implements UVC 1.1. Future support for UVC 1.5 can be added after the Linux kernel driver adds the support.

Platform agnostic

The libguvc library can be integrated on any embedded device and it is independent of the SoC architecture and kernel version. It only requires UVC gadget driver to be enabled in the platform.

Note: libguvc uses the kernel's UVC gadget driver as is; the patches provided are intended to demonstrate how to add support for features such as H264 and MJPEG, they are not intended to fix any issues (if any) on the UVC driver or the platform's USB stack.

Independent of the host OS

The libguvc uses the Linux UVC gadget driver and implements the UVC standard so that the gadget device using the library can be used on any OS that supports the UVC standard such as Linux, Windows* and Mac OS X. Likewise it can be used by any standard capture application such as Skype, VLC, guvcview, among others.

* For Windows it is required to create a custom Windows INF file in order for the device to be successfully registered on the system

Independent of user application implementation

The libguvc library can be integrated with any user application and only requires to be feed with video frames that will be send to the USB endpoint. Its design allows to easily integrate the library with any video frame wrappers such as V4L2 buffers or GStreamer buffers, among others; taking care only of the real video content and allowing the user to specify the memory management for the buffer types used.

As an example of its flexibility the library comes with sample code using different implementation methods such as specific V4L2 application and GStreamer based application. The sample code can be found at $(LIBGUVC_DIR)/src/test directory.

GStreamer integration

On release 1.2.x the library includes a GStreamer element that can be used to send UVC data directly to a host computer on a simple GStreamer pipeline speeding up the development time for a UVC based application.

User Pointer and MMAP support

libguvc can be used on User Pointer or MMAP mode in order to increase the compatibility with the user space applications.

Extension Units support

As part of the key features on the libguvc there is the support for UVC Extension Units (XU) allowing the user to implement custom controls in order to meet specific design requirements with a minimum of effort.

USB requests support

libguvc allows the installation of callback functions on the user application in order to receive any USB request on the controls exposed, this provides a direct communication between the host computer and the user application.

Video formats support

On version 1.0.x the libguvc provides support for YUY2 video format only. Releases 1.1.x and 1.3.x provide support for MJPEG and H264 video formats as well.

How does it work?

To use libguvc is really simply, the API is widely explained in the Doxygen documentation at $(LIBGUVC_DIR)/src/docs/.

A simple pseudo code that depicts the basic API sequence is shown below. libguvc API allows the user to interact with the UVC driver using just a set of methods and callbacks, abstracting all the complexity of driver interaction and configuration.

#include <libguvc.h>


uvc_device * device;

void release_buffer (void **entity, void *args) 
{
   /* Release the buffer data that has been sent through the UVC */
}

void fill_uvc_buffer (unsigned long *data_addr, int *data_size, int *bytes_used, void **entity, void *args)
{
    /* send the video data and custom information to the library */
}

int main (int argc ,  char **argv)
{
   ...

   uvc_init (device, "/dev/video0");

   ... 

   /* Set the callbacks to pass and release the video content */
   uvc_set_pull_data_handler (device, fill_uvc_buffer, NULL);
   uvc_set_release_data_handler (device, release_buffer, NULL);

   ...

   uvc_start (device);

   ...

   uvc_close (device);

   return 0;

}

Additionally the API provides support for a wide range of configurable settings to use specific features such as Extension Units or UVC controls requests.

Demo Images

FAQ: What is the difference between a trial version and the full? Both versions are fully functional, the trial version is fixed to a few set of pre-defined video resolutions and runs only for about 5min before it disconnects the UVC session automatically.

You can download the following demo sd card images in order to test a trial version of the library.

Since the libguvc is platform agnostic, you can also request for a custom demo image for any other platform by posting your Inquiry at our Contact Us Link directly...