270 lines
7.0 KiB
Groff
270 lines
7.0 KiB
Groff
.\" $NetBSD: video.4,v 1.9 2013/07/20 21:39:58 wiz 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.
|