#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:

[legend]

Collaboration diagram for jevois::Gadget:

[legend]

Public Member Functions
	Gadget (std::string const &devname, VideoInput camera, Engine engine, size_t const nbufs=0, bool multicam=false)
	Construct and open the device.

virtual	~Gadget ()
	Close the device and free all resources.

void	setFormat (jevois::VideoMapping const &m) override
	Set the video format and frame rate.

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()

void	send (RawImage const &img) override
	Send an image out over USB to the host computer.

void	streamOn () override
	Start streaming.

void	abortStream () override
	Abort streaming.

void	streamOff () override
	Stop streaming.

Public Member Functions inherited from jevois::VideoOutput
virtual	~VideoOutput ()
	Virtual destructor for safe inheritance.

Constructor & Destructor Documentation

◆ Gadget()

jevois::Gadget::Gadget	(	std::string const &	devname,
		jevois::VideoInput *	camera,
		jevois::Engine *	engine,
		size_t const	nbufs = `0`,
		bool	multicam = `false`
	)

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 139 of file Gadget.C.

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

◆ ~Gadget()

jevois::Gadget::~Gadget ( )

virtual

Close the device and free all resources.

Definition at line 185 of file Gadget.C.

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

Member Function Documentation

◆ abortStream()

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 777 of file Gadget.C.

References JEVOIS_TRACE.

◆ get()

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 813 of file Gadget.C.

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