#include <jevois/Core/OutputFrame.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:

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.

Definition at line 52 of file OutputFrame.H.

Public Member Functions
	OutputFrame (OutputFrame &&other)=default
	Move constructor. More...

const RawImage &	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	sendCv (cv::Mat const &img, int quality=75) const
	Shorthand to send a cv::Mat after converting / scaling it to the current output format. 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...

void	sendScaledCvGRAY (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	sendScaledCvBGR (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	sendScaledCvRGB (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	sendScaledCvRGBA (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 31 of file OutputFrame.C.

Member Function Documentation

◆ get()

const jevois::RawImage & 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 55 of file OutputFrame.C.

◆ 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 63 of file OutputFrame.C.

◆ sendCv()

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

Shorthand to send a cv::Mat after converting / scaling 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 will be rescaled to the same dims as the output frame.

The pixel format of the given cv::Mat is guessed as follows:

if img.type() == CV_8UC3, assume BGR pixels
if img.type() == CV_8UC1, assume GRAY pixels
if img.type() == CV_8UC4, assume RGBA pixels

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 71 of file OutputFrame.C.

References jevois::cvtypestr(), and LFATAL.

◆ 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 91 of file OutputFrame.C.

References jevois::rawimage::convertCvBGRtoRawImage(), and jevois::imu::get().

◆ 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 83 of file OutputFrame.C.

References jevois::rawimage::convertCvGRAYtoRawImage(), and jevois::imu::get().

◆ 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 98 of file OutputFrame.C.

References jevois::rawimage::convertCvRGBtoRawImage(), and jevois::imu::get().

◆ 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 106 of file OutputFrame.C.

References jevois::rawimage::convertCvRGBAtoRawImage(), and jevois::imu::get().

◆ sendScaledCvBGR()

void jevois::OutputFrame::sendScaledCvBGR	(	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 will be rescaled to the 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 123 of file OutputFrame.C.

References jevois::rawimage::convertCvBGRtoRawImage(), jevois::imu::get(), jevois::RawImage::height, jevois::rescaleCv(), and jevois::RawImage::width.

◆ sendScaledCvGRAY()

void jevois::OutputFrame::sendScaledCvGRAY	(	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 will be rescaled to the 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 114 of file OutputFrame.C.

References jevois::rawimage::convertCvGRAYtoRawImage(), jevois::imu::get(), jevois::RawImage::height, jevois::rescaleCv(), and jevois::RawImage::width.

◆ sendScaledCvRGB()

void jevois::OutputFrame::sendScaledCvRGB	(	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 will be rescaled to the 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 131 of file OutputFrame.C.

References jevois::rawimage::convertCvRGBtoRawImage(), jevois::imu::get(), jevois::RawImage::height, jevois::rescaleCv(), and jevois::RawImage::width.

◆ sendScaledCvRGBA()

void jevois::OutputFrame::sendScaledCvRGBA	(	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 will be rescaled to the 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 140 of file OutputFrame.C.

References jevois::rawimage::convertCvRGBAtoRawImage(), jevois::imu::get(), jevois::RawImage::height, jevois::rescaleCv(), and jevois::RawImage::width.

Friends And Related Function Documentation

◆ Engine

friend class Engine

friend

Definition at line 172 of file OutputFrame.H.

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

include/jevois/Core/OutputFrame.H
src/jevois/Core/OutputFrame.C

Public Member Functions

Friends