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

#include <CamCap.hpp>

Collaboration diagram for CC::Device:

[legend]

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 Device &	reset (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 Device &	set_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 Device &	initialize (const bool use_libv4l_interface=true)
	Initialize the camera device. More...

virtual Device &	initialize (const std::string &fn, const bool use_libv4l_interface=true)
	Initialize the given camera device. More...

virtual Device &	initialize (const char *const fn)
	Same as other calls to `initialize()`, but required to prevent string literals from being incorrectly interpreted as booleans. More...

virtual MInputs	get_inputs (void) const
	Get a map of all the inputs supported by this device. More...

virtual Device &	set_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 Device &	request_memory_mapped_buffers (size_t number_of_buffers_to_use=1)
	Used to request memory blocks used to capture images. More...

virtual Device &	release_memory_mapped_buffers (void)
	Release all memory mapped buffers previously allocated through request_memory_mapped_buffers(). More...

virtual Device &	stream_start (void)
	Send the V4L call VIDIOC_STREAMON to begin capturing. More...

virtual Device &	stream_stop (void)
	Send the V4L call VIDIOC_STREAMOFF to stop capturing. More...

virtual Device &	xopen (const std::string &fn)
	Open the video device file. More...

virtual Device &	xclose (void)
	Close the video device file. More...

virtual void *	xmmap (size_t length, off_t offset)
	Mmap a block of memory. More...

virtual Device &	xmunmap (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 Device &	capture_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 Device &	retry_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 Device &	set_libv4l_interface (const bool toggle=true)
	Decides if CamCap accesses the camera directly, or goes through the libv4l interface. More...

virtual Device &	set_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 Device &	set_all_controls_to_defaults (void)
	Iterate through the available controls and set all to their default values. More...

virtual Device &	set_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 Device &	set_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 Device &	xioctl (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

enum CC::Device::EV4L2_msg_handling

strong

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] fn Specifies 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

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

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

Here is the caller graph for this function:

◆ initialize() [1/3]

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_interface determines 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_error if 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/3]

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]	fn	Provide the name of the camera device to open, such as `/dev/video0`.
[in]	use_libv4l_interface	determines 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_argument	if the camera device name is empty
std::runtime_error	if 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:

◆ initialize() [3/3]

virtual Device& CC::Device::initialize ( const char *const fn )

inlinevirtual

Same as other calls to initialize(), but required to prevent string literals from being incorrectly interpreted as booleans.

References initialize().

Referenced by initialize().

Here is the call graph for this function:

Here is the caller 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]	width	The requested image width. If zero, the camera will use the smallest value it supports.
[in]	height	The 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_format	One of the V4L2 defines, such as `V4L2_PIX_FMT_YUYV` or `V4L2_PIX_FMT_RGB24`
[in]	width	The requested image width. If zero, the camera will use the smallest value it supports.
[in]	height	The 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_use is 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]	request	V4L2 ioctl request, such as `VIDIOC_QUERYCAP`.
[in]	parm	Pointer to V4L2 structure to pass as the 3rd parameter to `ioctl()`.
[in]	name	Text name corresponding to the ioctl request. Will be used to generate an error message if the call to `ioctl()` fails.

Exceptions

std::runtime_error	if the file descriptor is invalid (device not initialized?)
std::runtime_error	if the camera device has not yet been fully initialized
std::runtime_error	if 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_error if 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_error if 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_error if 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_argument if 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]	count	Number of images to capture.
[in,out]	images	Vector of captured images.

Example:

CC::Device camera_device;
CC::Device::Images images;
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]	count	Number of images to capture.
[in]	directory	Directory 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_error if 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] retries Determine 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]	toggle	Set to `true` to use the compatibility layer offered by `libv4l`.
[in]	toggle	Set 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_argument	if the control name is empty
std::runtime_error	if 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

Device capabilities are obtained in initialize().

See also: get_capabilities(); https://linuxtv.org/downloads/v4l-dvb-apis/uapi/v4l/vidioc-querycap.html#c.v4l2_capability

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

◆ 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

v4l2_format CC::Device::selected_format

protected

The most recently set image format.

See also: get_format(); https://linuxtv.org/downloads/v4l-dvb-apis/uapi/v4l/vidioc-g-fmt.html

Referenced by capture_using_mmap_buffers(), capture_using_read(), describe(), get_dimensions(), request_memory_mapped_buffers(), reset(), and set_format().

◆ buffer_details

MIdxBufferDetail CC::Device::buffer_details

protected

Keep track of every memory mapped buffer.

Referenced by capture_using_mmap_buffers(), describe(), release_memory_mapped_buffers(), request_memory_mapped_buffers(), and stream_start().

◆ 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:

Public Types

Public Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ EV4L2_msg_handling

Constructor & Destructor Documentation

◆ Device()

◆ ~Device()

Member Function Documentation

◆ reset()

◆ describe()

◆ set_v4l2_msg_handling()

◆ get_v4l2_messages()

◆ is_initialized()

◆ is_not_initialized()

◆ initialize() [1/3]

◆ initialize() [2/3]

◆ initialize() [3/3]

◆ get_inputs()

◆ set_input_index()

◆ get_formats()

◆ get_format()

◆ set_format() [1/4]

◆ set_format() [2/4]

◆ set_format() [3/4]

◆ set_format() [4/4]

◆ request_memory_mapped_buffers()

◆ release_memory_mapped_buffers()

◆ stream_start()

◆ stream_stop()

◆ xioctl() [1/2]

◆ xioctl() [2/2]

◆ xopen()

◆ xclose()

◆ xmmap()

◆ xmunmap()

◆ xread()

◆ capture() [1/2]

◆ capture() [2/2]

◆ capture_to_jpeg()

◆ capture_many()

◆ capture_many_to_jpeg()

◆ capture_using_mmap_buffers()

◆ capture_using_read()

◆ get_name()

◆ get_capabilities()

◆ get_capability_flags()

◆ retry_incomplete_captures()

◆ is_streaming_enabled()

◆ get_dimensions()

◆ set_libv4l_interface()

◆ set_transfer_method()

◆ get_all_controls()

◆ set_all_controls_to_defaults()

◆ set_control() [1/2]

◆ get_control() [1/2]

◆ control_name_to_index()

◆ set_control() [2/2]

◆ get_control() [2/2]

◆ describe_controls()

Member Data Documentation

◆ fname

◆ fd

◆ initialized

◆ v4l2_message_ptr

◆ v4l2_message_size

◆ capabilities

◆ inputs

◆ formats

◆ selected_format

◆ buffer_details

◆ retry_count

◆ streaming_enabled

◆ use_libv4l

◆ transfer_method