CamCap  v0.0.1-2379
C++ camera capture library and tool
CC::Device Class Reference

Class to represent a single camera device. More...

#include <CamCap.hpp>

Collaboration diagram for CC::Device:

Public Types

enum  EV4L2_msg_handling {
  EV4L2_msg_handling::kStdErr,
  EV4L2_msg_handling::kDiscard,
  EV4L2_msg_handling::kKeep
}
 

Public Member Functions

 Device (const std::string &fn="")
 Constructor. More...
 
virtual ~Device (void)
 Destructor. More...
 
virtual Devicereset (void)
 Close the camera device. More...
 
std::string describe (void)
 Creates a large block of text describing the device, what it supports, and the current state. More...
 
virtual Deviceset_v4l2_msg_handling (const EV4L2_msg_handling type=EV4L2_msg_handling::kDiscard)
 Set what CamCap should do with messages from libv4l2. More...
 
std::string get_v4l2_messages (void)
 Obtain the most recent set of libv4l2 messages. More...
 
virtual Deviceinitialize (const bool use_libv4l_interface=true)
 Initialize the camera device. More...
 
virtual Deviceinitialize (const std::string &fn, const bool use_libv4l_interface=true)
 Initialize the given camera device. More...
 
virtual MInputs get_inputs (void) const
 Get a map of all the inputs supported by this device. More...
 
virtual Deviceset_input_index (uint32_t index=0)
 Set the input device to the specified index. More...
 
virtual MFormats get_formats (void) const
 Get a map of all the image formats supported by this device. More...
 
virtual v4l2_format get_format (void) const
 Get a copy of the most recently set image format. More...
 
virtual v4l2_format set_format (v4l2_format format)
 Set the prefered image format the camera should be using. More...
 
virtual v4l2_format set_format (v4l2_fmtdesc format_description, const size_t width=0, const size_t height=0)
 Set the prefered image format using one of the enumerated formats returned by get_formats(). More...
 
virtual v4l2_format set_format (const size_t width, const size_t height)
 Keep the format the same, but specify a specific width and height. More...
 
virtual v4l2_format set_format (const int pixel_format, const size_t width, const size_t height)
 Set a specific pixel format and image dimension to use. More...
 
virtual Devicerequest_memory_mapped_buffers (size_t number_of_buffers_to_use=1)
 Used to request memory blocks used to capture images. More...
 
virtual Devicerelease_memory_mapped_buffers (void)
 Release all memory mapped buffers previously allocated through request_memory_mapped_buffers(). More...
 
virtual Devicestream_start (void)
 Send the V4L call VIDIOC_STREAMON to begin capturing. More...
 
virtual Devicestream_stop (void)
 Send the V4L call VIDIOC_STREAMOFF to stop capturing. More...
 
virtual Devicexopen (const std::string &fn)
 Open the video device file. More...
 
virtual Devicexclose (void)
 Close the video device file. More...
 
virtual void * xmmap (size_t length, off_t offset)
 Mmap a block of memory. More...
 
virtual Devicexmunmap (void *addr, size_t length)
 Unmmap a block of memory. More...
 
virtual int xread (Bytes &bytes)
 Read from the device file descriptor. More...
 
virtual Bytes capture (void)
 Capture an image from the camera device. More...
 
virtual v4l2_buffer capture (Bytes &bytes)
 Capture an image from the camera device. More...
 
virtual v4l2_buffer capture_to_jpeg (const std::string &output_filename)
 Calls capture() and then saves the image to a JPEG file. More...
 
virtual Devicecapture_many (const size_t count, Images &images)
 Capture a sequence of images. More...
 
virtual VStr capture_many_to_jpeg (const size_t count, const std::string &directory=".")
 Capture a sequence of images as JPEG files. More...
 
virtual v4l2_buffer capture_using_mmap_buffers (Bytes &bytes)
 Capture an image using memory mapped buffers. More...
 
virtual v4l2_buffer capture_using_read (Bytes &bytes)
 Capture an image using read() or v4l2_read(). More...
 
virtual std::string get_name (void) const
 Get the device name, such as /dev/video0. This is not set until initialize() is called. More...
 
virtual v4l2_capability get_capabilities (void) const
 The V4L2 device capabilities are used to identify kernel devices compatible with this specification and to obtain information about driver and hardware capabilities. More...
 
virtual MU32Str get_capability_flags (void) const
 Returns a std::map that describes all the capabilities of this camera device. More...
 
virtual Deviceretry_incomplete_captures (const size_t retries=5)
 Determines how many times the CamCap library will retry a capture if an incomplete buffer is returned from V4L. More...
 
virtual bool is_streaming_enabled (void) const
 Determine if streaming is enabled. More...
 
virtual Dimensions get_dimensions (void)
 Query the camera to determine what image sizes are supported. More...
 
virtual Deviceset_libv4l_interface (const bool toggle=true)
 Decides if CamCap accesses the camera directly, or goes through the libv4l interface. More...
 
virtual Deviceset_transfer_method (const ETransferMethod method=ETransferMethod::kMmap)
 Toggle between memory mapped buffers and direct read when capturing images. More...
 
virtual VCtrls get_all_controls (void)
 Get all of the controls supported by this camera. More...
 
virtual Deviceset_all_controls_to_defaults (void)
 Iterate through the available controls and set all to their default values. More...
 
virtual Deviceset_control (const uint32_t index, const int32_t value)
 Set a specific control to a certain value. More...
 
virtual int32_t get_control (const uint32_t index)
 Get the current value for the specified control. More...
 
virtual uint32_t control_name_to_index (std::string name)
 Map control names to control indexes. More...
 
virtual Deviceset_control (const std::string &name, const int32_t value)
 Similar to the other set_control(), but takes a name instead of the control index. More...
 
virtual int32_t get_control (const std::string &name)
 Similar to the other get_control(), but takes a name instead of the control index. More...
 
virtual std::string describe_controls (void)
 Return a text string showing the state of all camera device controls. More...
 
virtual bool is_initialized (void) const
 Determine if the device has been initialized. Set by initialize(). More...
 
virtual bool is_not_initialized (void) const
 Determine if the device has been initialized. Set by initialize(). More...
 
virtual Devicexioctl (const int request, void *parm, const std::string &name)
 Perform the requested ioctl() call via v4l2_ioctl() from libv4l2. More...
 
virtual int xioctl (const int request, void *parm)
 

Protected Attributes

std::string fname
 Name of the device that was opened. Set in the constructor or initialize(). Will normally be /dev/video0. More...
 
int fd
 File descriptor to the opened camera device. More...
 
bool initialized
 This is set to true once the device has been properly initialized. More...
 
v4l2_capability capabilities
 Device capabilities are obtained in initialize(). More...
 
MInputs inputs
 Map of all the inputs supported by a camera. For most (all?) webcams, there is a single input at index #0. More...
 
MFormats formats
 Map of all the formats supported by the camera. More...
 
v4l2_format selected_format
 The most recently set image format. More...
 
MIdxBufferDetail buffer_details
 Keep track of every memory mapped buffer. More...
 
size_t retry_count
 Determine if partial captures are kept or rejected. More...
 
bool streaming_enabled
 State of streaming. More...
 
bool use_libv4l
 Should CamCap directly access the camera, or use the libv4l interface layer. More...
 
ETransferMethod transfer_method
 Selected transfer method. More...
 
char * v4l2_message_ptr
 Needed to track V4L2 messages. More...
 
size_t v4l2_message_size
 Needed to track V4L2 messages. More...
 

Detailed Description

Class to represent a single camera device.

Methods are provided to manipulate the camera and take pictures. These objects are small and can easily be created on the stack. Any buffers or memory needed internally is then allocated from the heap or using standard containers such as std::map and std::vector.

Example code:

#include <CamCap.hpp>
int main()
{
CC::Device camera_device;
camera_device.initialize( "/dev/video1" );
camera_device.set_format( 640, 480 );
camera_device.capture_to_jpeg( "image.jpg" );
return 0;
}

Member Enumeration Documentation

◆ EV4L2_msg_handling

See also
set_v4l2_msg_handling()
Enumerator
kStdErr 

Tell libv4l2 to send all messages to stderr.

kDiscard 

Redirects all libv4l2 messages to /dev/null.

kKeep 

Internally store all libv4l2 messages.

See also
get_v4l2_messages()

Constructor & Destructor Documentation

◆ Device()

CC::Device::Device ( const std::string &  fn = "")

Constructor.

Parameters
[in]fnSpecifies the device to open. If left blank, then an attempt will be made to auto-detect a device that matches /dev/video*.

Example:

// remember to #include <CamCap.hpp>
CC::Device camera( "/dev/video1" );
camera.capture_to_jpeg( "out.jpg" );

References CC::kMmap, reset(), and set_v4l2_msg_handling().

Here is the call graph for this function:

◆ ~Device()

CC::Device::~Device ( void  )
virtual

Destructor.

References kStdErr, reset(), and set_v4l2_msg_handling().

Here is the call graph for this function:

Member Function Documentation

◆ reset()

CC::Device & CC::Device::reset ( void  )
virtual

Close the camera device.

This is automatically called by the destructor and initialize() prior to opening a new device.

References capabilities, formats, initialized, inputs, is_initialized(), CC::kMmap, release_memory_mapped_buffers(), retry_count, selected_format, streaming_enabled, transfer_method, use_libv4l, xclose(), and ZERO.

Referenced by Device(), initialize(), and ~Device().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ describe()

std::string CC::Device::describe ( void  )

Creates a large block of text describing the device, what it supports, and the current state.

Useful for debugging.

Example output:

Filename: "/dev/video0"
Initialized: true
Driver name: uvcvideo v4.4.40
Device name: USB 2.0 Camera
Location: usb-0000:00:0b.0-1
Flags: 0x85200001
The device supports the single-planar API through the Video Capture interface.
The device supports the struct v4l2_pix_format extended fields.
The device supports the read() and/or write() I/O methods.
The device supports the streaming I/O method.
The driver fills the device_caps field.
Device input #0:
name: Camera 1
type: V4L2_INPUT_TYPE_CAMERA
Image format #0:
buffer type: V4L2_BUF_TYPE_VIDEO_CAPTURE
flags: 0
description: YUYV 4:2:2
Fourcc: YUYV
...

References CC::BufferDetail::address, CC::BufferDetail::buffer, buffer_details, capabilities, describe_controls(), fname, CC::fourcc_to_string(), CC::gcd(), get_all_controls(), get_capability_flags(), get_dimensions(), get_formats(), get_inputs(), CC::get_version(), is_initialized(), is_streaming_enabled(), CC::kMmap, CC::kRead, retry_count, selected_format, transfer_method, use_libv4l, V4L2_COLORSPACE_DEFAULT, and V4L2_COLORSPACE_RAW.

Referenced by main().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ set_v4l2_msg_handling()

CC::Device & CC::Device::set_v4l2_msg_handling ( const EV4L2_msg_handling  type = EV4L2_msg_handling::kDiscard)
virtual

Set what CamCap should do with messages from libv4l2.

Default behaviour is to redirect them to /dev/null.

Note
libv4l2 has a single global error message file pointer, so if you have multiple CC::Device objects then you'll need to leave it at kStdErr, or manage the v4l2_log_file file pointer yourself.

References kDiscard, kKeep, kStdErr, v4l2_message_ptr, and v4l2_message_size.

Referenced by Device(), and ~Device().

Here is the caller graph for this function:

◆ get_v4l2_messages()

std::string CC::Device::get_v4l2_messages ( void  )

Obtain the most recent set of libv4l2 messages.

This only works when the v4l2 message handling has been set to EV4L2_msg_handling::kKeep, otherwise an empty string is returned.

Note
Messages that are retrieved are removed from the internal buffer.
See also
set_v4l2_msg_handling()

References v4l2_message_ptr, and v4l2_message_size.

◆ is_initialized()

virtual bool CC::Device::is_initialized ( void  ) const
inlinevirtual

Determine if the device has been initialized. Set by initialize().

Referenced by describe(), initialize(), and reset().

Here is the caller graph for this function:

◆ is_not_initialized()

virtual bool CC::Device::is_not_initialized ( void  ) const
inlinevirtual

◆ initialize() [1/2]

CC::Device & CC::Device::initialize ( const bool  use_libv4l_interface = true)
virtual

Initialize the camera device.

Will attempt to scan for an auto-detect a device, and repeatedly call initialize() until a device is initialized, or all video devices have been tried.

Parameters
[in]use_libv4l_interfacedetermines if CamCap accesses the camera directly or through the libv4l interface. Default true is to use libv4l. Set to false to bypass libv4l. This can also be toggled through set_libv4l_interface().
Exceptions
std::runtime_errorif a camera device cannot be initialized

References fname, is_initialized(), reset(), and use_libv4l.

Referenced by capture(), capture_to_jpeg(), get_all_controls(), get_dimensions(), main(), request_memory_mapped_buffers(), retry_incomplete_captures(), set_all_controls_to_defaults(), set_format(), set_transfer_method(), stream_start(), and stream_stop().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ initialize() [2/2]

CC::Device & CC::Device::initialize ( const std::string &  fn,
const bool  use_libv4l_interface = true 
)
virtual

Initialize the given camera device.

Does not make any attempt to auto-detect.

Parameters
[in]fnProvide the name of the camera device to open, such as /dev/video0.
[in]use_libv4l_interfacedetermines if CamCap accesses the camera directly or through the libv4l interface. Default true is to use libv4l. Set to false to bypass libv4l. This can also be toggled through set_libv4l_interface().
Exceptions
std::invalid_argumentif the camera device name is empty
std::runtime_errorif enumerating the supported image formats fails to return anything

References capabilities, fname, formats, initialized, inputs, reset(), set_format(), set_input_index(), use_libv4l, xioctl(), xopen(), and ZERO.

Here is the call graph for this function:

◆ get_inputs()

virtual MInputs CC::Device::get_inputs ( void  ) const
inlinevirtual

Get a map of all the inputs supported by this device.

Normally a webcam will have a single input.

See also
https://linuxtv.org/downloads/v4l-dvb-apis/uapi/v4l/vidioc-enuminput.html

Referenced by describe().

Here is the caller graph for this function:

◆ set_input_index()

virtual Device& CC::Device::set_input_index ( uint32_t  index = 0)
inlinevirtual

Set the input device to the specified index.

This is automatically called by initialize() to select the first input index returned by VIDIOC_ENUMINPUT.

See also
https://linuxtv.org/downloads/v4l-dvb-apis/uapi/v4l/vidioc-g-input.html

Referenced by initialize().

Here is the caller graph for this function:

◆ get_formats()

virtual MFormats CC::Device::get_formats ( void  ) const
inlinevirtual

Get a map of all the image formats supported by this device.

See also
https://linuxtv.org/downloads/v4l-dvb-apis/uapi/v4l/vidioc-enum-fmt.html

Referenced by describe(), and main().

Here is the caller graph for this function:

◆ get_format()

virtual v4l2_format CC::Device::get_format ( void  ) const
inlinevirtual

Get a copy of the most recently set image format.

Example:

CC::Device camera_device;
camera_device.initialize();
v4l2_format format = camera_device.get_format();
std::cout << "width: " << format.fmt.pix.width << std::endl
<< "height: " << format.fmt.pix.height << std::endl
<< "pixel format: " << CC::fourcc_to_string(format.fmt.pix.pixelformat) << std::endl
<< "field: " << format.fmt.pix.field << std::endl
<< "bytes per line: " << format.fmt.pix.bytesperline << std::endl
<< "image size: " << format.fmt.pix.sizeimage << std::endl
<< "colour space: " << format.fmt.pix.colorspace << std::endl;
See also
https://linuxtv.org/downloads/v4l-dvb-apis/uapi/v4l/vidioc-g-fmt.html#c.v4l2_format

Referenced by capture_to_jpeg(), and main().

Here is the caller graph for this function:

◆ set_format() [1/4]

v4l2_format CC::Device::set_format ( v4l2_format  format)
virtual

Set the prefered image format the camera should be using.

This includes the image dimensions and byte format.

Returns
Returns the format the camera has decided to use, which may not be exactly the same as what was requested. For example, the final image width and height may not be what had been requested.
See also
get_formats()
https://linuxtv.org/downloads/v4l-dvb-apis/uapi/v4l/vidioc-g-fmt.html

References initialize(), is_not_initialized(), release_memory_mapped_buffers(), selected_format, and xioctl().

Referenced by capture_to_jpeg(), initialize(), main(), and set_format().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ set_format() [2/4]

v4l2_format CC::Device::set_format ( v4l2_fmtdesc  format_description,
const size_t  width = 0,
const size_t  height = 0 
)
virtual

Set the prefered image format using one of the enumerated formats returned by get_formats().

Returns
Returns the format the camera has decided to use, which may not be exactly the same as what was requested. For example, the final image width and height may not be what had been requested.
See also
https://linuxtv.org/downloads/v4l-dvb-apis/uapi/v4l/vidioc-g-fmt.html

References initialize(), is_not_initialized(), selected_format, set_format(), V4L2_PIX_FMT_PRIV_MAGIC, and ZERO.

Here is the call graph for this function:

◆ set_format() [3/4]

v4l2_format CC::Device::set_format ( const size_t  width,
const size_t  height 
)
virtual

Keep the format the same, but specify a specific width and height.

Parameters
[in]widthThe requested image width. If zero, the camera will use the smallest value it supports.
[in]heightThe requested image height. If zero, the camera will use the smallest value it supports.
Returns
Returns the format the camera has decided to use, which may not be exactly the same as what was requested. For example, the final image width and height may have been adjusted to dimensions supported by the camera.
See also
https://linuxtv.org/downloads/v4l-dvb-apis/uapi/v4l/vidioc-g-fmt.html

References initialize(), is_not_initialized(), selected_format, and set_format().

Here is the call graph for this function:

◆ set_format() [4/4]

v4l2_format CC::Device::set_format ( const int  pixel_format,
const size_t  width,
const size_t  height 
)
virtual

Set a specific pixel format and image dimension to use.

Parameters
[in]pixel_formatOne of the V4L2 defines, such as V4L2_PIX_FMT_YUYV or V4L2_PIX_FMT_RGB24
[in]widthThe requested image width. If zero, the camera will use the smallest value it supports.
[in]heightThe requested image height. If zero, the camera will use the smallest value it supports.
Returns
Returns the format the camera has decided to use, which may not be exactly the same as what was requested. For example, the final image width and height may have been adjusted to dimensions supported by the camera.
See also
https://linuxtv.org/downloads/v4l-dvb-apis/uapi/v4l/vidioc-g-fmt.html

References initialize(), is_not_initialized(), selected_format, and set_format().

Here is the call graph for this function:

◆ request_memory_mapped_buffers()

CC::Device & CC::Device::request_memory_mapped_buffers ( size_t  number_of_buffers_to_use = 1)
virtual

Used to request memory blocks used to capture images.

This is called automatically by functions such as initialize() and set_format(). The only reason you'd need to manually this is if you want to manually set the number of buffers to use.

Parameters
[in]number_of_buffers_to_useis usually a small number, such as 1 or 2..
See also
https://linuxtv.org/downloads/v4l-dvb-apis/uapi/v4l/vidioc-reqbufs.html
https://linuxtv.org/downloads/v4l-dvb-apis/uapi/v4l/vidioc-querybuf.html
https://linuxtv.org/downloads/v4l-dvb-apis/uapi/v4l/vidioc-qbuf.html

References CC::BufferDetail::buffer, buffer_details, initialize(), is_not_initialized(), release_memory_mapped_buffers(), selected_format, xioctl(), xmmap(), and ZERO.

Referenced by capture_using_mmap_buffers(), set_transfer_method(), and stream_start().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ release_memory_mapped_buffers()

CC::Device & CC::Device::release_memory_mapped_buffers ( void  )
virtual

Release all memory mapped buffers previously allocated through request_memory_mapped_buffers().

This is automatically called when necessary, including in the destructor, so normally you shouldn't need to call this directly.

See also
https://linuxtv.org/downloads/v4l-dvb-apis/uapi/v4l/vidioc-reqbufs.html

References CC::BufferDetail::address, CC::BufferDetail::buffer, buffer_details, stream_stop(), xioctl(), xmunmap(), and ZERO.

Referenced by capture_using_read(), request_memory_mapped_buffers(), reset(), set_format(), and set_transfer_method().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ stream_start()

CC::Device & CC::Device::stream_start ( void  )
virtual

Send the V4L call VIDIOC_STREAMON to begin capturing.

This is automatically called when necessary.

See also
https://linuxtv.org/downloads/v4l-dvb-apis/uapi/v4l/vidioc-streamon.html

References buffer_details, initialize(), is_not_initialized(), CC::kMmap, request_memory_mapped_buffers(), streaming_enabled, transfer_method, and xioctl().

Referenced by capture_many(), capture_many_to_jpeg(), capture_using_mmap_buffers(), and main().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ stream_stop()

CC::Device & CC::Device::stream_stop ( void  )
virtual

Send the V4L call VIDIOC_STREAMOFF to stop capturing.

This is automatically called when necessary.

See also
https://linuxtv.org/downloads/v4l-dvb-apis/uapi/v4l/vidioc-streamon.html

References initialize(), is_not_initialized(), streaming_enabled, and xioctl().

Referenced by release_memory_mapped_buffers().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ xioctl() [1/2]

CC::Device & CC::Device::xioctl ( const int  request,
void *  parm,
const std::string &  name 
)
virtual

Perform the requested ioctl() call via v4l2_ioctl() from libv4l2.

Parameters
[in]requestV4L2 ioctl request, such as VIDIOC_QUERYCAP.
[in]parmPointer to V4L2 structure to pass as the 3rd parameter to ioctl().
[in]nameText name corresponding to the ioctl request. Will be used to generate an error message if the call to ioctl() fails.
Exceptions
std::runtime_errorif the file descriptor is invalid (device not initialized?)
std::runtime_errorif the camera device has not yet been fully initialized
std::runtime_errorif the requested ioctl failed
Returns
only if the ioctl call successed, otherwise throws an exception.

References fd, fname, and is_not_initialized().

Referenced by capture_using_mmap_buffers(), get_all_controls(), get_control(), get_dimensions(), initialize(), release_memory_mapped_buffers(), request_memory_mapped_buffers(), set_control(), set_format(), stream_start(), and stream_stop().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ xioctl() [2/2]

int CC::Device::xioctl ( const int  request,
void *  parm 
)
virtual
Returns
Returns the result of calling v4l2_ioctl(). This version of xioctl() does not throw.

References fd, and use_libv4l.

◆ xopen()

CC::Device & CC::Device::xopen ( const std::string &  fn)
virtual

Open the video device file.

Exceptions
std::runtime_errorif the device named fails to open

References fd, use_libv4l, and xclose().

Referenced by initialize().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ xclose()

CC::Device & CC::Device::xclose ( void  )
virtual

Close the video device file.

References fd, and use_libv4l.

Referenced by reset(), and xopen().

Here is the caller graph for this function:

◆ xmmap()

void * CC::Device::xmmap ( size_t  length,
off_t  offset 
)
virtual

Mmap a block of memory.

Exceptions
std::runtime_errorif mmap() fails to return an address to use for a buffer

References fd, and use_libv4l.

Referenced by request_memory_mapped_buffers().

Here is the caller graph for this function:

◆ xmunmap()

CC::Device & CC::Device::xmunmap ( void *  addr,
size_t  length 
)
virtual

Unmmap a block of memory.

References use_libv4l.

Referenced by release_memory_mapped_buffers().

Here is the caller graph for this function:

◆ xread()

int CC::Device::xread ( Bytes bytes)
virtual

Read from the device file descriptor.

Returns
Returns the errno result after the read finished.
Exceptions
std::runtime_errorif the read request failed

References fd, fname, and use_libv4l.

Referenced by capture_using_read().

Here is the caller graph for this function:

◆ capture() [1/2]

CC::Bytes CC::Device::capture ( void  )
virtual

Capture an image from the camera device.

This automatically calls initialize() if it hasn't already been called. The format of the captured bytes depends on the currently selected image format.

Example:

CC::Device camera_device;
CC::Bytes bytes = camera_device.capture();

Referenced by capture_many(), capture_to_jpeg(), and main().

Here is the caller graph for this function:

◆ capture() [2/2]

v4l2_buffer CC::Device::capture ( Bytes bytes)
virtual

Capture an image from the camera device.

This automatically calls initialize() if it hasn't already been called. The format of the captured bytes depends on the currently selected image format.

Example:

CC::Device camera_device;
CC::Bytes bytes;
v4l2_buffer meta_data = camera_device.capture( bytes );
See also
https://linuxtv.org/downloads/v4l-dvb-apis/uapi/v4l/buffer.html#c.v4l2_buffer

References capture_using_mmap_buffers(), capture_using_read(), initialize(), is_not_initialized(), CC::kMmap, CC::kRead, and transfer_method.

Here is the call graph for this function:

◆ capture_to_jpeg()

v4l2_buffer CC::Device::capture_to_jpeg ( const std::string &  output_filename)
virtual

Calls capture() and then saves the image to a JPEG file.

Warning
The image format may be automatically changed via a call to set_format() if the current image format is not optimal for converting to JPEG.
Returns
Returns a V4L2 structure with meta information on the captured image.

Example:

CC::Device camera_device;
camera_device.capture_to_jpeg( "output.jpg" );
See also
https://linuxtv.org/downloads/v4l-dvb-apis/uapi/v4l/vidioc-qbuf.html
https://linuxtv.org/downloads/v4l-dvb-apis/uapi/v4l/buffer.html#c.v4l2_buffer
Exceptions
std::invalid_argumentif the filename is empty

References capture(), get_format(), initialize(), is_not_initialized(), and set_format().

Referenced by capture_many_to_jpeg(), and main().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ capture_many()

CC::Device & CC::Device::capture_many ( const size_t  count,
Images images 
)
virtual

Capture a sequence of images.

Parameters
[in]countNumber of images to capture.
[in,out]imagesVector of captured images.

Example:

CC::Device camera_device;
camera_device.capture_many( 10, images );
for ( const auto img : images )
{
process_image( img.bytes );
}

References CC::CaptureAndBuffer::bytes, capture(), CC::CaptureAndBuffer::info, and stream_start().

Here is the call graph for this function:

◆ capture_many_to_jpeg()

CC::VStr CC::Device::capture_many_to_jpeg ( const size_t  count,
const std::string &  directory = "." 
)
virtual

Capture a sequence of images as JPEG files.

Parameters
[in]countNumber of images to capture.
[in]directoryDirectory into which the jpeg files are saved.
Returns
Returns a vector of filenames.

Example:

CC::Device camera_device;
CC::VStr v = camera_device.capture_many_to_jpeg( 10, "/tmp" );
for ( const auto filename : v )
{
std::cout << filename << std::endl;
}

References capture_to_jpeg(), fname, and stream_start().

Referenced by main().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ capture_using_mmap_buffers()

v4l2_buffer CC::Device::capture_using_mmap_buffers ( Bytes bytes)
virtual

Capture an image using memory mapped buffers.

Returns
Returns a V4L2 structure with meta information on the captured image.

References CC::BufferDetail::address, CC::BufferDetail::buffer, buffer_details, request_memory_mapped_buffers(), retry_count, selected_format, stream_start(), xioctl(), and ZERO.

Referenced by capture().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ capture_using_read()

v4l2_buffer CC::Device::capture_using_read ( Bytes bytes)
virtual

Capture an image using read() or v4l2_read().

Returns
The v4l2_buffer returned is emulated, and most fields are set to zero.

References release_memory_mapped_buffers(), retry_count, selected_format, xread(), and ZERO.

Referenced by capture().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ get_name()

virtual std::string CC::Device::get_name ( void  ) const
inlinevirtual

Get the device name, such as /dev/video0. This is not set until initialize() is called.

Referenced by main().

Here is the caller graph for this function:

◆ get_capabilities()

virtual v4l2_capability CC::Device::get_capabilities ( void  ) const
inlinevirtual

The V4L2 device capabilities are used to identify kernel devices compatible with this specification and to obtain information about driver and hardware capabilities.

This is automatically called during initialization, and normally does not need to be manually called.

See also
get_capability_flags()
https://linuxtv.org/downloads/v4l-dvb-apis/uapi/v4l/vidioc-querycap.html

◆ get_capability_flags()

CC::MU32Str CC::Device::get_capability_flags ( void  ) const
virtual

Returns a std::map that describes all the capabilities of this camera device.

Example:

CC::Device camera_device;
camera_device.initialize();
for ( const auto iter : camera_device.get_capability_flags() )
{
std::cout << "\t" << iter.second << std::endl;
}
See also
https://linuxtv.org/downloads/v4l-dvb-apis/uapi/v4l/vidioc-querycap.html
Exceptions
std::runtime_errorif the device is unitialized.

References capabilities, is_not_initialized(), V4L2_CAP_EXT_PIX_FORMAT, V4L2_CAP_SDR_CAPTURE, V4L2_CAP_SDR_OUTPUT, and V4L2_CAP_TOUCH.

Referenced by describe().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ retry_incomplete_captures()

CC::Device & CC::Device::retry_incomplete_captures ( const size_t  retries = 5)
virtual

Determines how many times the CamCap library will retry a capture if an incomplete buffer is returned from V4L.

Some cameras or drivers seem to return partial buffers. CamCap can try multiple times to transfer an image from the camera when this condition is detected.

Parameters
[in]retriesDetermine the number of times a capture will be restarted. Normally is a relatively small number greater than zero.

References initialize(), is_not_initialized(), and retry_count.

Referenced by main().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ is_streaming_enabled()

virtual bool CC::Device::is_streaming_enabled ( void  ) const
inlinevirtual

Determine if streaming is enabled.

See also
stream_start()
stream_stop()

Referenced by describe().

Here is the caller graph for this function:

◆ get_dimensions()

CC::Dimensions CC::Device::get_dimensions ( void  )
virtual

Query the camera to determine what image sizes are supported.

References initialize(), is_not_initialized(), selected_format, xioctl(), and ZERO.

Referenced by describe().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ set_libv4l_interface()

virtual Device& CC::Device::set_libv4l_interface ( const bool  toggle = true)
inlinevirtual

Decides if CamCap accesses the camera directly, or goes through the libv4l interface.

This is also a parameter to initialize() since it can impact from very early on how the camera device is opened.

Parameters
[in]toggleSet to true to use the compatibility layer offered by libv4l.
[in]toggleSet to false if libv4l should be ignored.

References CC::kMmap.

◆ set_transfer_method()

CC::Device & CC::Device::set_transfer_method ( const ETransferMethod  method = ETransferMethod::kMmap)
virtual

Toggle between memory mapped buffers and direct read when capturing images.

See also
https://linuxtv.org/downloads/v4l-dvb-apis/uapi/v4l/rw.html
https://linuxtv.org/downloads/v4l-dvb-apis/uapi/v4l/mmap.html

References initialize(), is_not_initialized(), CC::kMmap, CC::kRead, release_memory_mapped_buffers(), request_memory_mapped_buffers(), and transfer_method.

Referenced by main().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ get_all_controls()

CC::VCtrls CC::Device::get_all_controls ( void  )
virtual

Get all of the controls supported by this camera.

Note
Controls typically keep their values even when the device is closed and re-opened.

This does not include

See also
set_all_controls_to_defaults()

References initialize(), is_not_initialized(), xioctl(), and ZERO.

Referenced by control_name_to_index(), describe(), describe_controls(), main(), and set_all_controls_to_defaults().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ set_all_controls_to_defaults()

CC::Device & CC::Device::set_all_controls_to_defaults ( void  )
virtual

Iterate through the available controls and set all to their default values.

Note
Controls typically keep their values even when the device is closed and re-opened. It may be beneficial to call this method to ensure the camera controls are in a known state prior to capturing images.

References get_all_controls(), initialize(), is_not_initialized(), and set_control().

Referenced by main().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ set_control() [1/2]

CC::Device & CC::Device::set_control ( const uint32_t  index,
const int32_t  value 
)
virtual

Set a specific control to a certain value.

Examples (not the full list!) of common V4L control indexes defined in videodev2.h which may be supported by cameras are:

  • V4L2_CID_BRIGHTNESS
  • V4L2_CID_CONTRAST
  • V4L2_CID_SATURATION
  • V4L2_CID_HUE
  • V4L2_CID_AUTO_WHITE_BALANCE
  • V4L2_CID_GAMMA
  • V4L2_CID_GAIN
  • V4L2_CID_POWER_LINE_FREQUENCY
  • V4L2_CID_WHITE_BALANCE_TEMPERATURE
  • V4L2_CID_SHARPNESS
  • V4L2_CID_BACKLIGHT_COMPENSATION
  • V4L2_CID_EXPOSURE_AUTO
  • V4L2_CID_EXPOSURE_ABSOLUTE
  • V4L2_CID_EXPOSURE_AUTO_PRIORITY
See also
get_all_controls()
set_all_controls_to_defaults()

References xioctl(), and ZERO.

Referenced by main(), set_all_controls_to_defaults(), and set_control().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ get_control() [1/2]

int32_t CC::Device::get_control ( const uint32_t  index)
virtual

Get the current value for the specified control.

See also
set_control()
get_all_controls()

References xioctl(), and ZERO.

Referenced by describe_controls(), get_control(), and main().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ control_name_to_index()

uint32_t CC::Device::control_name_to_index ( std::string  name)
virtual

Map control names to control indexes.

The match is partial-word and case-insensitive. The full list of control names is specific to each camera, though some common names found on most devices include:

  • brightness
  • contrast
  • sturation
  • hue
  • gamma
  • gain
  • sharpness
Note
If a text match cannot be found, this method will also attempt to parse the name as a hexadecimal value.
Exceptions
std::invalid_argumentif the control name is empty
std::runtime_errorif a control with the given name cannot be found

References get_all_controls().

Referenced by get_control(), main(), and set_control().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ set_control() [2/2]

CC::Device & CC::Device::set_control ( const std::string &  name,
const int32_t  value 
)
virtual

Similar to the other set_control(), but takes a name instead of the control index.

The name comparison is case-insitive. For example, "gain" and "GaIn" both match "Gain".

References control_name_to_index(), and set_control().

Here is the call graph for this function:

◆ get_control() [2/2]

int32_t CC::Device::get_control ( const std::string &  name)
virtual

Similar to the other get_control(), but takes a name instead of the control index.

The name comparison is partial-word and case-insensitive. For example, "gain" and "GaIn" both match "Gain".

References control_name_to_index(), and get_control().

Here is the call graph for this function:

◆ describe_controls()

std::string CC::Device::describe_controls ( void  )
virtual

Return a text string showing the state of all camera device controls.

For example:

Index Min Def Max Value Description
------ ---- ---- ---- ----- -----------
980900 -64 0 64 0 Brightness
980901 0 32 64 32 Contrast
980902 0 64 128 64 Saturation
980903 -40 0 40 0 Hue
98090c 0 1 1 1 White Balance Temperature, Auto
980910 72 100 500 100 Gamma
980913 0 0 100 0 Gain
980918 0 1 2 2 Power Line Frequency
98091a 2800 4600 6500 4600 White Balance Temperature
98091b 0 3 6 3 Sharpness
98091c 0 1 2 1 Backlight Compensation
9a0901 0 3 3 3 Exposure, Auto
9a0902 1 157 5000 157 Exposure (Absolute)
9a0903 0 0 1 1 Exposure, Auto Priority

References get_all_controls(), and get_control().

Referenced by describe(), and main().

Here is the call graph for this function:
Here is the caller graph for this function:

Member Data Documentation

◆ fname

std::string CC::Device::fname
protected

Name of the device that was opened. Set in the constructor or initialize(). Will normally be /dev/video0.

Referenced by capture_many_to_jpeg(), describe(), initialize(), xioctl(), and xread().

◆ fd

int CC::Device::fd
protected

File descriptor to the opened camera device.

Referenced by xclose(), xioctl(), xmmap(), xopen(), and xread().

◆ initialized

bool CC::Device::initialized
protected

This is set to true once the device has been properly initialized.

See also
is_initialized()

Referenced by initialize(), and reset().

◆ v4l2_message_ptr

char* CC::Device::v4l2_message_ptr
protected

Needed to track V4L2 messages.

See also
set_v4l2_msg_handling()
get_v4l2_messages()

Referenced by get_v4l2_messages(), and set_v4l2_msg_handling().

◆ v4l2_message_size

size_t CC::Device::v4l2_message_size
protected

Needed to track V4L2 messages.

See also
set_v4l2_msg_handling()
get_v4l2_messages()

Referenced by get_v4l2_messages(), and set_v4l2_msg_handling().

◆ capabilities

v4l2_capability CC::Device::capabilities
protected

◆ inputs

MInputs CC::Device::inputs
protected

Map of all the inputs supported by a camera. For most (all?) webcams, there is a single input at index #0.

Referenced by initialize(), and reset().

◆ formats

MFormats CC::Device::formats
protected

Map of all the formats supported by the camera.

Referenced by initialize(), and reset().

◆ selected_format

◆ buffer_details

MIdxBufferDetail CC::Device::buffer_details
protected

◆ retry_count

size_t CC::Device::retry_count
protected

Determine if partial captures are kept or rejected.

See also
retry_incomplete_captures()

Referenced by capture_using_mmap_buffers(), capture_using_read(), describe(), reset(), and retry_incomplete_captures().

◆ streaming_enabled

bool CC::Device::streaming_enabled
protected

State of streaming.

See also
stream_start()
stream_stop()

Referenced by reset(), stream_start(), and stream_stop().

◆ use_libv4l

bool CC::Device::use_libv4l
protected

Should CamCap directly access the camera, or use the libv4l interface layer.

Referenced by describe(), initialize(), reset(), xclose(), xioctl(), xmmap(), xmunmap(), xopen(), and xread().

◆ transfer_method

ETransferMethod CC::Device::transfer_method
protected

Selected transfer method.

See also
set_transfer_method()

Referenced by capture(), describe(), reset(), set_transfer_method(), and stream_start().


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