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

#include <jevois/Core/Module.H>

Exception-safe wrapper around a raw image to be sent over USB.

This wrapper operates much like std:future in standard C++11. Users can get the next memory-allocated but blank image to be sent over USB by calling get(), which may block if all buffers are still being sent over USB by Gadget and no blank one is available, or may throw if getting that buffer fails for some reason (e.g., usb disconnect, user just changed video mode in their webcam software or closed it). The allocated image size and pixel type is as defined by the current VideoMapping, USB section, i.e., it is the USB video mode currently selected by the user. To save time, image buffers are not zeroed out, so you should not assume that the image is filled with black pixels, it could contain random pixels, or previous output frames. In addition, a send() function is provided which users may use as soon as they are finished with writing the pixel data into the image obtained via get(), to allow the USB driver to send that image to the connected host computer. If send() has not been called by the time the OutputFrame is destroyed, it will be called automatically, if get() had been called.

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

  1. 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;
  2. 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.

Definition at line 110 of file Module.H.

Public Member Functions

 OutputFrame (OutputFrame &&other)=default
 Move constructor. More...
RawImage const & get () const
 Get a pre-allocated image so that we can fill the pixel data and later send out over USB using send() More...
void send () const
 Send an image out over USB to the host computer. More...
 ~OutputFrame ()
 Destructor, returns the buffers to the driver as needed. More...


class Engine

Constructor & Destructor Documentation

jevois::OutputFrame::OutputFrame ( OutputFrame &&  other)

Move constructor.

jevois::OutputFrame::~OutputFrame ( )

Destructor, returns the buffers to the driver as needed.

Definition at line 65 of file Module.C.

Member Function Documentation

jevois::RawImage const & jevois::OutputFrame::get ( ) const

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

Definition at line 78 of file Module.C.

void jevois::OutputFrame::send ( ) const

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.

Definition at line 86 of file Module.C.

Friends And Related Function Documentation

friend class Engine

Definition at line 133 of file Module.H.

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