JeVois  1.5
JeVois Smart Embedded Machine Vision Toolkit
Share this page:
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 144 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...
 
void sendCvGRAY (cv::Mat const &img, int quality=75) const
 Shorthand to send a GRAY cv::Mat after converting it to the current output format. More...
 
void sendCvBGR (cv::Mat const &img, int quality=75) const
 Shorthand to send a BGR cv::Mat after converting it to the current output format. More...
 
void sendCvRGB (cv::Mat const &img, int quality=75) const
 Shorthand to send a RGB cv::Mat after converting it to the current output format. More...
 
void sendCvRGBA (cv::Mat const &img, int quality=75) const
 Shorthand to send a RGBA cv::Mat after converting it to the current output format. More...
 
 ~OutputFrame ()
 Destructor, returns the buffers to the driver as needed. More...
 

Friends

class Engine
 

Constructor & Destructor Documentation

◆ OutputFrame()

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

Move constructor.

◆ ~OutputFrame()

jevois::OutputFrame::~OutputFrame ( )

Destructor, returns the buffers to the driver as needed.

Definition at line 109 of file Module.C.

Member Function Documentation

◆ get()

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 133 of file Module.C.

Referenced by jevois::OutputFramePython::get().

◆ send()

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 141 of file Module.C.

Referenced by jevois::OutputFramePython::send().

◆ sendCvBGR()

void jevois::OutputFrame::sendCvBGR ( cv::Mat const &  img,
int  quality = 75 
) const

Shorthand to send a BGR cv::Mat after converting it to the current output format.

This is mostly intended for Python module writers, as they will likely use OpenCV for all their image processing. The cv::Mat must have same dims as the output frame. C++ module writers should stick to the get()/send() pair as this provides better fine-grained control. Note that the cv::Mat image will always be copied or converted to the destination RawImage and will then be sent out immediately by calling send(), so users should not call send() after using this function. This function is basically equivalent to calling get(), converting the given cv::Mat to the proper output format, and calling send(). quality is used only if the output format is MJPEG and should be between 1 and 100.

Definition at line 157 of file Module.C.

References jevois::rawimage::convertCvBGRtoRawImage(), and jevois::Gadget::send().

Referenced by jevois::OutputFramePython::sendCvBGR(), and jevois::OutputFramePython::sendCvBGR1().

◆ sendCvGRAY()

void jevois::OutputFrame::sendCvGRAY ( cv::Mat const &  img,
int  quality = 75 
) const

Shorthand to send a GRAY cv::Mat after converting it to the current output format.

This is mostly intended for Python module writers, as they will likely use OpenCV for all their image processing. The cv::Mat must have same dims as the output frame. C++ module writers should stick to the get()/send() pair as this provides better fine-grained control. Note that the cv::Mat image will always be copied or converted to the destination RawImage and will then be sent out immediately by calling send(), so users should not call send() after using this function. This function is basically equivalent to calling get(), converting the given cv::Mat to the proper output format, and calling send(). quality is used only if the output format is MJPEG and should be between 1 and 100.

Definition at line 149 of file Module.C.

References jevois::rawimage::convertCvGRAYtoRawImage(), and jevois::Gadget::send().

Referenced by jevois::OutputFramePython::sendCvGRAY(), and jevois::OutputFramePython::sendCvGRAY1().

◆ sendCvRGB()

void jevois::OutputFrame::sendCvRGB ( cv::Mat const &  img,
int  quality = 75 
) const

Shorthand to send a RGB cv::Mat after converting it to the current output format.

This is mostly intended for Python module writers, as they will likely use OpenCV for all their image processing. The cv::Mat must have same dims as the output frame. C++ module writers should stick to the get()/send() pair as this provides better fine-grained control. Note that the cv::Mat image will always be copied or converted to the destination RawImage and will then be sent out immediately by calling send(), so users should not call send() after using this function. This function is basically equivalent to calling get(), converting the given cv::Mat to the proper output format, and calling send(). quality is used only if the output format is MJPEG and should be between 1 and 100.

Definition at line 164 of file Module.C.

References jevois::rawimage::convertCvRGBtoRawImage(), and jevois::Gadget::send().

Referenced by jevois::OutputFramePython::sendCvRGB(), and jevois::OutputFramePython::sendCvRGB1().

◆ sendCvRGBA()

void jevois::OutputFrame::sendCvRGBA ( cv::Mat const &  img,
int  quality = 75 
) const

Shorthand to send a RGBA cv::Mat after converting it to the current output format.

This is mostly intended for Python module writers, as they will likely use OpenCV for all their image processing. The cv::Mat must have same dims as the output frame. C++ module writers should stick to the get()/send() pair as this provides better fine-grained control. Note that the cv::Mat image will always be copied or converted to the destination RawImage and will then be sent out immediately by calling send(), so users should not call send() after using this function. This function is basically equivalent to calling get(), converting the given cv::Mat to the proper output format, and calling send(). quality is used only if the output format is MJPEG and should be between 1 and 100.

Definition at line 172 of file Module.C.

References jevois::rawimage::convertCvRGBAtoRawImage(), and jevois::Gadget::send().

Referenced by jevois::OutputFramePython::sendCvRGBA(), and jevois::OutputFramePython::sendCvRGBA1().

Friends And Related Function Documentation

◆ Engine

friend class Engine
friend

Definition at line 208 of file Module.H.


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