.\"	$NetBSD: video.4,v 1.10 2014/03/18 18:20:39 riastradh Exp $
.\"
.\" Copyright (c) 2008 Patrick Mahoney
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd March 5, 2011
.Dt VIDEO 4
.Os
.Sh NAME
.Nm video
.Nd device-independent video driver layer
.Sh SYNOPSIS
.In sys/videoio.h
.Sh DESCRIPTION
The
.Nm
driver provides support for various video peripherals.
It provides a uniform programming interface layer above different
underlying video hardware drivers.
The video layer provides a
.Tn Video4Linux2
compatible API.
A number of
.Xr ioctl 2
commands are supported controlling the device.
.Pp
The device file for video operation is
.Pa /dev/video .
.Sh READING VIDEO SAMPLES
Video data is separated into logical video samples which will
typically be one complete video frame.
With compressed formats, a video sample may be one logical chunk
and not one complete frame depending on the compression format.
Video samples may be read from
.Pa /dev/video
in one of several different modes.
.Pp
In read mode, calls to
.Xr read 2
will return at most the data of one video sample.
If the entire sample is not read, then subsequent reads will return
at most the remaining data in that video sample.
.Pp
Video samples may be mapped into memory with
.Xr mmap 2 .
The driver allocates internal buffers for a number of video samples
which are mapped into memory.
Initiating this mode requires several
.Xr ioctl 2
commands:
.Dv VIDIOC_REQBUFS
to request the driver reserve buffers,
.Dv VIDIOC_QUERYBUF
to query the details of each buffer,
.Xr mmap 2
to map each buffer into memory,
.Dv VIDIOC_QBUF
to queue the buffers for receiving video data,
.Dv VIDIOC_STREAMON
to begin streaming of video data, and
.Dv VIDIOC_DQBUF
to remove a filled buffer from the queue.
At this point the video data from the dequeued buffer is valid.
.Sh DEVICE CAPABILITIES
.Bl -tag -width indent
.It Dv VIDIOC_QUERYCAP (struct v4l2_capability)
This command queries the capabilities of the device.
The first three fields are informational NULL terminated strings
filled by the driver:
.Va driver
describes the driver used by this device,
.Va card
describes the video capture card or camera, and
.Va buf_info
represents the bus to which the hardware device is attached.
.Pp
The
.Va capabilities
field contains a number of flags indicating various features supported
by the driver or hardware:
.Pp
.Bl -tag -width indent
.It Dv V4L2_CAP_VIDEO_CAPTURE
support video capturing
.It Dv V4L2_CAP_READWRITE
supports the
.Xr read 2
and/or
.Xr write 2
mode
.It Dv V4L2_CAP_STREAMING
supports
.Xr mmap 2
mode
.El
.Bd -literal
struct v4l2_capability {
	uint8_t		driver[16];
	uint8_t		card[32];
	uint8_t		bus_info[32];
	uint32_t	version;
	uint32_t	capabilities;
	uint32_t	reserved[4];
};
.Ed
.El
.Sh STREAMING INTERFACE
.Bl -tag -width indent
.It Dv VIDIOC_REQBUFS (struct v4l2_requestbuffers)
This command requests that the driver reserve space for
.Va count
samples.
.Va type
must be set to
.Dv V4L2_BUF_TYPE_VIDEO_CAPTURE
and
.Va memory
to
.Dv V4L2_MEMORY_MMAP .
The returned
.Va count
represents the actual number of samples reserved which may be more
or fewer than requested.
.Bd -literal
struct v4l2_requestbuffers {
	uint32_t		count;
	enum v4l2_buf_type	type;
	enum v4l2_memory	memory;
	uint32_t		reserved[2];
};
.Ed
.It Dv VIDIOC_QUERYBUF (struct v4l2_buffer)
This command should be called for each buffer in
.Va count
above.
The fields
.Va index ,
.Va type ,
and
.Va memory
must be set to a valid index from 0 to
.Va count-1 ,
and the same type and memory as used in
.Dv VIDIOC_QUERYBUF .
The driver returns
.Va m.offset
and
.Va length .
.Bd -literal
struct v4l2_buffer {
	uint32_t		index;
	enum v4l2_buf_type	type;
	uint32_t		bytesused;
	uint32_t		flags;
	enum v4l2_field		field;
	struct timeval		timestamp;
	struct v4l2_timecode	timecode;
	uint32_t		sequence;
	enum v4l2_memory	memory;
	union {
		uint32_t	offset;
		unsigned long	userptr;
	} m;
	uint32_t		length;
	uint32_t		input;
	uint32_t		reserved;
};
.Ed
.It Xr mmap 2
Each buffer must be mapped with a call to
.Xr mmap 2 ,
passing the
.Va length
and
.Va m.offset
values obtained above.
The prot
.Dv PROT_READ|PROT_WRITE
and flags
.Dv MAP_SHARED
are recommended.
.It Dv VIDIOC_QBUF (struct v4l2_buffer)
This command indicates to the driver that the buffer is ready to
receive a video sample.
The following fields must be set:
.Va index ,
set to a valid buffer index from 0 to
.Va count
\- 1;
.Va type ,
set to the same type used above; and
.Va memory ,
set to the same memory used above.
Each buffer should be queued with this command.
Order is not important.
.It Dv VIDIOC_STREAMON (int)
This command starts streaming.
Queued buffers will be filled with data.
.Xr select 2
will indicate that a buffer is done and available for reading.
.It Dv VIDIOC_DQBUF (struct v4l2_buffer)
This command dequeues an available buffer from the driver.
If no buffer is available, it blocks until one is, unless
.Dv O_NONBLOCK
was specified to
.Xr open 2 ,
in which case it returns
.Er EAGAIN .
.Xr select 2 ,
or
.Xr poll 2
prior to initiating any other mode will begin streaming of video for
reading with
.Xr read 2 .
In this streaming mode
.Xr select 2
or
.Xr poll 2
indicate the availability of a video frame.
Calls to
.Xr read 2
will return at most the video data of one video sample.
If the entire sample is not read, then subsequent reads will return
at most the remaining data in that video sample.
.El
.Sh FILES
.Bl -tag -width /dev/video -compact
.It Pa /dev/video
.El
.Sh SEE ALSO
.Xr auvitek 4 ,
.Xr pseye 4 ,
.Xr uvideo 4 ,
.Xr video 9
.Pp
.Lk http://v4l2spec.bytesex.org/ "V4L2 API Specification"
.Sh HISTORY
The
.Nm
device driver first appeared in
.Nx 5.0 .
.Sh AUTHORS
.An Patrick Mahoney Aq Mt pat@polycrystal.org
.Sh BUGS
Does not support the complete V4L2 API.
Only supports the capture interface.
Does not support writing, overlay, VBI, tuner, audio, radio, or
asyncio.