JeVois  1.5
JeVois Smart Embedded Machine Vision Toolkit
Share this page:
jevois::Camera Class Reference

#include <jevois/Core/Camera.H>

JeVois camera driver class - grabs frames from a Video4Linux camera sensor.

On the platform hardware, the Camera class provides access to the camera sensor on the parallel camera bus (CSI). On other hardware, it can provide access to any Video4Linux2 camera (e.g., USB webcam), although with some limitations, such as:

  • cannot read/write raw camera registers.
  • usually cannot select any frames/s but instead limited to a few fixed values like 15fps, 30fps.
  • usually limited to 3fps max (no 60fps or 120fps modes like on JeVois platform hardware)
  • usually limited number of controls (exposure, gain, etc) available.

The camera runs a thread that handles capturing frames automatically. Users can access the next grabbed frame using get(), which may block until the frame is fully captured. Once they are finished with a frame obtained through get(), users should hand it back to the Camera by calling done(). When using the JeVois Engine and a Module, get() and done() are automatically called in an exception-safe manner through the use of the InputFrame class. Indeed, video grabbing uses a fixed set of image buffers that are allocated by the Linux kernel when a video format is configured, and the camera hardware then cycles through the buffers. On the platform, the camera image buffers are allocated in the ION carveout memory area, which is a reserved memory zone configured in the Linux kernel, and the USB output buffers are also allocated in that zone. To avoid reserving too much memory that will not be used, the ION carveout reservation is quite small by default, but is sufficient for 3 1280x1024 YUYV buffers.

Camera implements a zero-copy, zero-wait access to input 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 uses via direct-memory-access (DMA) to stream the pixel data from the camera chip to processor memory;
  • as soon as an image is captured by the camera hardware, get() unblocks and returns it (as opposed to having a fixed, regular interval at which images may be available). Camera has several image buffers, allowing one to be captured while another is being handed over for processing via get(). These buffers are recycled, i.e., once done() is called, the underlying buffer is sent back to the camera hardware for future capture.

Camera will drop frames if they are not processed by user code fast enough. That is, if all buffers have been grabbed already and not yet handed over through get() and then returned by done(), then the next camera sensor frame will be dropped.

Most programmers will never use Camera directly, instead using Engine and InputFrame.

Definition at line 64 of file Camera.H.

Inheritance diagram for jevois::Camera:
Collaboration diagram for jevois::Camera:

Public Member Functions

 Camera (std::string const &devname, unsigned int const nbufs=0)
 Construct and open the device. More...
 
 ~Camera ()
 Close the device and free all resources. More...
 
void streamOn () override
 Start streaming. More...
 
void abortStream () override
 Abort streaming. More...
 
void streamOff () override
 Stop streaming. More...
 
void get (RawImage &img) override
 Get the next captured buffer. More...
 
void done (RawImage &img) override
 Indicate that user processing is done with an image previously obtained via get() More...
 
void queryControl (struct v4l2_queryctrl &qc) const override
 Get information about a control, throw if unsupported by hardware. More...
 
void queryMenu (struct v4l2_querymenu &qm) const override
 Get the available menu entry names for a menu-type control, throw if unsupported by hardware. More...
 
void getControl (struct v4l2_control &ctrl) const
 Get a control's current value, throw if unsupported by hardware. More...
 
void setControl (struct v4l2_control const &ctrl) override
 Set a control, throw if control not supported or the hardware rejects the value. More...
 
void setFormat (VideoMapping const &m) override
 Set the video format and frame rate. More...
 
void writeRegister (unsigned char reg, unsigned char val) override
 Write a value to one of the camera's registers. More...
 
unsigned char readRegister (unsigned char reg) override
 Read a value from one of the camera's registers. More...
 
- Public Member Functions inherited from jevois::VideoInput
 VideoInput (std::string const &devname, unsigned int const nbufs=0)
 Constructor. More...
 
virtual ~VideoInput ()
 Virtual destructor for save inheritance. More...
 

Additional Inherited Members

- Protected Attributes inherited from jevois::VideoInput
std::string const itsDevName
 Our device or movie file name. More...
 
unsigned int const itsNbufs
 Our number of buffers. More...
 

Constructor & Destructor Documentation

◆ Camera()

jevois::Camera::Camera ( std::string const &  devname,
unsigned int const  nbufs = 0 
)

Construct and open the device.

Parameters
devnamedevice name, e.g., /dev/video0
nbufsnumber of video grab buffers, or 0 for automatic.

Definition at line 56 of file Camera.C.

References jevois::fccstr(), JEVOIS_TIMED_LOCK, JEVOIS_TRACE, LDEBUG, LFATAL, LINFO, PLFATAL, XIOCTL, and XIOCTL_QUIET.

◆ ~Camera()

Member Function Documentation

◆ abortStream()

void jevois::Camera::abortStream ( )
overridevirtual

Abort streaming.

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

Implements jevois::VideoInput.

Definition at line 342 of file Camera.C.

References JEVOIS_TRACE.

Referenced by streamOff().

◆ done()

void jevois::Camera::done ( jevois::RawImage img)
overridevirtual

Indicate that user processing is done with an image previously obtained via get()

You should call this as soon after get() as possible, once you are finished with the RawImage data so that it can be recycled.

Calling done() on a RawImage invalidates the image and in particular its pixel buffer. Users should make sure that no attempt to use the image or the pixel buffer will be made after done() is called.

Implements jevois::VideoInput.

Definition at line 413 of file Camera.C.

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

◆ get()

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

Get the next captured buffer.

Throws if we are not streaming or blocks until an image is available (has been captured). img should have been created by the caller (with no pixel buffer allocated) and will be filled in by what we receive from the device here.

Implements jevois::VideoInput.

Definition at line 397 of file Camera.C.

References jevois::RawImage::bufindex, jevois::RawImage::invalidate(), JEVOIS_TRACE, LDEBUG, and jevois::RawImage::valid().

◆ getControl()

void jevois::Camera::getControl ( struct v4l2_control &  ctrl) const
virtual

Get a control's current value, throw if unsupported by hardware.

This is just a pass-through to VIDIOC_G_CTRL, users should zero-out ctrl and then set in ctrl.id the desired control ID.

Implements jevois::VideoInput.

Definition at line 441 of file Camera.C.

References XIOCTL.

◆ queryControl()

void jevois::Camera::queryControl ( struct v4l2_queryctrl &  qc) const
overridevirtual

Get information about a control, throw if unsupported by hardware.

Caller should zero-out qc and then set the id field to the desired control id. See VIDIOC_QUERYCTRL for more information.

Implements jevois::VideoInput.

Definition at line 429 of file Camera.C.

References XIOCTL_QUIET.

◆ queryMenu()

void jevois::Camera::queryMenu ( struct v4l2_querymenu &  qm) const
overridevirtual

Get the available menu entry names for a menu-type control, throw if unsupported by hardware.

Caller should zero-out qm and then set the id and index fields to the desired control id and menu item index. See VIDIOC_QUERYMENU for more information.

Implements jevois::VideoInput.

Definition at line 435 of file Camera.C.

References XIOCTL_QUIET.

◆ readRegister()

unsigned char jevois::Camera::readRegister ( unsigned char  reg)
overridevirtual

Read a value from one of the camera's registers.

This very low-level access is for development of optimal camera settings only and should not be used in normal operation, it can crash your system.

Implements jevois::VideoInput.

Definition at line 470 of file Camera.C.

References LINFO, and XIOCTL.

◆ setControl()

void jevois::Camera::setControl ( struct v4l2_control const &  ctrl)
overridevirtual

Set a control, throw if control not supported or the hardware rejects the value.

This is just a pass-through to VIDIOC_S_CTRL

Implements jevois::VideoInput.

Definition at line 451 of file Camera.C.

References XIOCTL.

◆ setFormat()

void jevois::Camera::setFormat ( jevois::VideoMapping const &  m)
overridevirtual

◆ streamOff()

void jevois::Camera::streamOff ( )
overridevirtual

◆ streamOn()

void jevois::Camera::streamOn ( )
overridevirtual

◆ writeRegister()

void jevois::Camera::writeRegister ( unsigned char  reg,
unsigned char  val 
)
overridevirtual

Write a value to one of the camera's registers.

This very low-level access is for development of optimal camera settings only and should not be used in normal operation, it can crash your system.

Implements jevois::VideoInput.

Definition at line 461 of file Camera.C.

References LINFO, and XIOCTL.


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