JeVois  1.0
JeVois Smart Embedded Machine Vision Toolkit
jevois::Gadget Class Reference

#include <jevois/Core/Gadget.H>

JeVois gadget driver - exposes a uvcvideo interface to host computer connected over USB.

Gadget is a user-space interface to the Linux kernel's gadget driver implemented by JeVois. A USB gadget driver is a USB driver that runs on a device, as opposed to a USB driver that runs on a host computer. Gadget drivers implement USB functions such as USB printers, USB modems, or USB cameras. In JeVois, the Gadget driver makes the JeVois hardware platform appear as a UVC (USB Video Class) camera. Because UVC has been standardized, no special driver is needed on the host computer to start using the UVC device, as virtually all modern operating systems already provide a built-in driver for UVC-compliant cameras.

The internal operation of Gadget is quite complex, especially due to its tight interaction with the kernel-side UVC gadget driver. Yet, for users, Gadget is just another VideoOutput device: One can set its format, obtain blank image buffers from it using get(), paint results into those buffers, and send them to the host computer when complete using send().

Gadget implements a zero-copy, zero-wait access to output video frames, that is:

  • the pixel data of the image you obtain via get() is directly the memory-mapped pixel buffer that the silicon hardware on the JeVois chip will use via direct-memory-access (DMA) to stream the data out over the USB link;
  • as soon as you call send() that buffer will be queued for sending over USB (as opposed to having a fixed, regular interval at which images may be streamed out). Gadget has several image buffers, allowing one to be streamed out over USB while another is being handed over for filling by your application via get(). These buffers are recycled, i.e., once send() is called, the underlying buffer is streamed over USB and then sent back to the Gadget for future access by your code.

Most programmers will never use Gadget directly, instead using Engine and OutputFrame.

Definition at line 65 of file Gadget.H.

Inheritance diagram for jevois::Gadget:
Collaboration diagram for jevois::Gadget:

Public Member Functions

 Gadget (std::string const &devname, VideoInput *camera, Engine *engine, size_t const nbufs=0)
 Construct and open the device. More...
 
virtual ~Gadget ()
 Close the device and free all resources. More...
 
void setFormat (jevois::VideoMapping const &m) override
 Set the video format and frame rate. More...
 
void get (RawImage &img) override
 Get a pre-allocated image so that we can fill the pixel data and later send out over USB using send() More...
 
void send (RawImage const &img) override
 Send an image out over USB to the host computer. More...
 
void streamOn () override
 Start streaming. More...
 
void abortStream () override
 Abort streaming. More...
 
void streamOff () override
 Stop streaming. More...
 
- Public Member Functions inherited from jevois::VideoOutput
virtual ~VideoOutput ()
 Virtual destructor for safe inheritance. More...
 

Constructor & Destructor Documentation

jevois::Gadget::Gadget ( std::string const &  devname,
jevois::VideoInput camera,
jevois::Engine engine,
size_t const  nbufs = 0 
)

Construct and open the device.

A vaid non-null camera is required for this gadget to work. To avoid testing for a non-null camera on each operation of the gadget, we only test once at construction and then assume the camera will remain operational for the lifetime of the gadget. Use 0 for nbufs to set it automatically.

Definition at line 134 of file Gadget.C.

References jevois::Engine::getDefaultVideoMapping(), JEVOIS_TRACE, LFATAL, LINFO, PLFATAL, UVC_EVENT_DATA, UVC_EVENT_SETUP, UVC_EVENT_STREAMOFF, UVC_EVENT_STREAMON, and XIOCTL.

jevois::Gadget::~Gadget ( )
virtual

Close the device and free all resources.

Definition at line 180 of file Gadget.C.

References JEVOIS_TRACE, PLERROR, and jevois::warnAndIgnoreException().

Member Function Documentation

void jevois::Gadget::abortStream ( )
overridevirtual

Abort streaming.

This only cancels future get() and done() calls, one should still call streamOff() to turn off streaming.

Implements jevois::VideoOutput.

Definition at line 757 of file Gadget.C.

References JEVOIS_TRACE.

void jevois::Gadget::get ( jevois::RawImage img)
overridevirtual

Get a pre-allocated image so that we can fill the pixel data and later send out over USB using send()

May throw if not buffer is available, i.e., all have been queued to send to the host but have not yet been sent. Application code must balance exactly one send() for each get().

Implements jevois::VideoOutput.

Definition at line 793 of file Gadget.C.

References jevois::RawImage::bufindex, JEVOIS_TRACE, LDEBUG, and LFATAL.

void jevois::Gadget::send ( jevois::RawImage const &  img)
overridevirtual

Send an image out over USB to the host computer.

May throw if the format is incorrect or std::overflow_error if we have not yet consumed the previous image.

Implements jevois::VideoOutput.

Definition at line 836 of file Gadget.C.

References jevois::RawImage::bufindex, jevois::RawImage::fmt, jevois::RawImage::height, JEVOIS_TRACE, LDEBUG, LFATAL, and jevois::RawImage::width.

void jevois::Gadget::setFormat ( jevois::VideoMapping const &  m)
overridevirtual
void jevois::Gadget::streamOff ( )
overridevirtual

Stop streaming.

Implements jevois::VideoOutput.

Definition at line 765 of file Gadget.C.

References JEVOIS_TIMED_LOCK, JEVOIS_TRACE, LDEBUG, and XIOCTL_QUIET.

void jevois::Gadget::streamOn ( )
overridevirtual

The documentation for this class was generated from the following files: