tobi/M7350
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

M7350v1_en_gpl

Browse Source
This commit is contained in:
T
2024-09-09 08:52:07 +00:00
commit f9cc65cfda
65988 changed files with 26357421 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
kernel/Documentation/DocBook/media/v4l/biblio.xml
+200
View File
@@ -0,0 +1,200 @@
<bibliography>
<title>References</title>
<biblioentry id="eia608">
<abbrev>EIA&nbsp;608-B</abbrev>
<authorgroup>
<corpauthor>Electronic Industries Alliance (<ulink
url="http://www.eia.org">http://www.eia.org</ulink>)</corpauthor>
</authorgroup>
<title>EIA 608-B "Recommended Practice for Line 21 Data
Service"</title>
</biblioentry>
<biblioentry id="en300294">
<abbrev>EN&nbsp;300&nbsp;294</abbrev>
<authorgroup>
<corpauthor>European Telecommunication Standards Institute
(<ulink url="http://www.etsi.org">http://www.etsi.org</ulink>)</corpauthor>
</authorgroup>
<title>EN 300 294 "625-line television Wide Screen Signalling
(WSS)"</title>
</biblioentry>
<biblioentry id="ets300231">
<abbrev>ETS&nbsp;300&nbsp;231</abbrev>
<authorgroup>
<corpauthor>European Telecommunication Standards Institute
(<ulink
url="http://www.etsi.org">http://www.etsi.org</ulink>)</corpauthor>
</authorgroup>
<title>ETS 300 231 "Specification of the domestic video
Programme Delivery Control system (PDC)"</title>
</biblioentry>
<biblioentry id="ets300706">
<abbrev>ETS&nbsp;300&nbsp;706</abbrev>
<authorgroup>
<corpauthor>European Telecommunication Standards Institute
(<ulink url="http://www.etsi.org">http://www.etsi.org</ulink>)</corpauthor>
</authorgroup>
<title>ETS 300 706 "Enhanced Teletext specification"</title>
</biblioentry>
<biblioentry id="mpeg2part1">
<abbrev>ISO&nbsp;13818-1</abbrev>
<authorgroup>
<corpauthor>International Telecommunication Union (<ulink
url="http://www.itu.ch">http://www.itu.ch</ulink>), International
Organisation for Standardisation (<ulink
url="http://www.iso.ch">http://www.iso.ch</ulink>)</corpauthor>
</authorgroup>
<title>ITU-T Rec. H.222.0 | ISO/IEC 13818-1 "Information
technology &mdash; Generic coding of moving pictures and associated
audio information: Systems"</title>
</biblioentry>
<biblioentry id="mpeg2part2">
<abbrev>ISO&nbsp;13818-2</abbrev>
<authorgroup>
<corpauthor>International Telecommunication Union (<ulink
url="http://www.itu.ch">http://www.itu.ch</ulink>), International
Organisation for Standardisation (<ulink
url="http://www.iso.ch">http://www.iso.ch</ulink>)</corpauthor>
</authorgroup>
<title>ITU-T Rec. H.262 | ISO/IEC 13818-2 "Information
technology &mdash; Generic coding of moving pictures and associated
audio information: Video"</title>
</biblioentry>
<biblioentry id="itu470">
<abbrev>ITU&nbsp;BT.470</abbrev>
<authorgroup>
<corpauthor>International Telecommunication Union (<ulink
url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor>
</authorgroup>
<title>ITU-R Recommendation BT.470-6 "Conventional Television
Systems"</title>
</biblioentry>
<biblioentry id="itu601">
<abbrev>ITU&nbsp;BT.601</abbrev>
<authorgroup>
<corpauthor>International Telecommunication Union (<ulink
url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor>
</authorgroup>
<title>ITU-R Recommendation BT.601-5 "Studio Encoding Parameters
of Digital Television for Standard 4:3 and Wide-Screen 16:9 Aspect
Ratios"</title>
</biblioentry>
<biblioentry id="itu653">
<abbrev>ITU&nbsp;BT.653</abbrev>
<authorgroup>
<corpauthor>International Telecommunication Union (<ulink
url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor>
</authorgroup>
<title>ITU-R Recommendation BT.653-3 "Teletext systems"</title>
</biblioentry>
<biblioentry id="itu709">
<abbrev>ITU&nbsp;BT.709</abbrev>
<authorgroup>
<corpauthor>International Telecommunication Union (<ulink
url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor>
</authorgroup>
<title>ITU-R Recommendation BT.709-5 "Parameter values for the
HDTV standards for production and international programme
exchange"</title>
</biblioentry>
<biblioentry id="itu1119">
<abbrev>ITU&nbsp;BT.1119</abbrev>
<authorgroup>
<corpauthor>International Telecommunication Union (<ulink
url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor>
</authorgroup>
<title>ITU-R Recommendation BT.1119 "625-line
television Wide Screen Signalling (WSS)"</title>
</biblioentry>
<biblioentry id="jfif">
<abbrev>JFIF</abbrev>
<authorgroup>
<corpauthor>Independent JPEG Group (<ulink
url="http://www.ijg.org">http://www.ijg.org</ulink>)</corpauthor>
</authorgroup>
<title>JPEG File Interchange Format</title>
<subtitle>Version 1.02</subtitle>
</biblioentry>
<biblioentry id="itu-t81">
<abbrev>ITU-T.81</abbrev>
<authorgroup>
<corpauthor>International Telecommunication Union
(<ulink url="http://www.itu.int">http://www.itu.int</ulink>)</corpauthor>
</authorgroup>
<title>ITU-T Recommendation T.81
"Information Technology &mdash; Digital Compression and Coding of Continous-Tone
Still Images &mdash; Requirements and Guidelines"</title>
</biblioentry>
<biblioentry id="w3c-jpeg-jfif">
<abbrev>W3C JPEG JFIF</abbrev>
<authorgroup>
<corpauthor>The World Wide Web Consortium (<ulink
url="http://www.w3.org/Graphics/JPEG">http://www.w3.org</ulink>)</corpauthor>
</authorgroup>
<title>JPEG JFIF</title>
</biblioentry>
<biblioentry id="smpte12m">
<abbrev>SMPTE&nbsp;12M</abbrev>
<authorgroup>
<corpauthor>Society of Motion Picture and Television Engineers
(<ulink url="http://www.smpte.org">http://www.smpte.org</ulink>)</corpauthor>
</authorgroup>
<title>SMPTE 12M-1999 "Television, Audio and Film - Time and
Control Code"</title>
</biblioentry>
<biblioentry id="smpte170m">
<abbrev>SMPTE&nbsp;170M</abbrev>
<authorgroup>
<corpauthor>Society of Motion Picture and Television Engineers
(<ulink url="http://www.smpte.org">http://www.smpte.org</ulink>)</corpauthor>
</authorgroup>
<title>SMPTE 170M-1999 "Television - Composite Analog Video
Signal - NTSC for Studio Applications"</title>
</biblioentry>
<biblioentry id="smpte240m">
<abbrev>SMPTE&nbsp;240M</abbrev>
<authorgroup>
<corpauthor>Society of Motion Picture and Television Engineers
(<ulink url="http://www.smpte.org">http://www.smpte.org</ulink>)</corpauthor>
</authorgroup>
<title>SMPTE 240M-1999 "Television - Signal Parameters -
1125-Line High-Definition Production"</title>
</biblioentry>
<biblioentry id="en50067">
<abbrev>EN&nbsp;50067</abbrev>
<authorgroup>
<corpauthor>European Committee for Electrotechnical Standardization
(<ulink url="http://www.cenelec.eu">http://www.cenelec.eu</ulink>)</corpauthor>
</authorgroup>
<title>Specification of the radio data system (RDS) for VHF/FM sound broadcasting
in the frequency range from 87,5 to 108,0 MHz</title>
</biblioentry>
<biblioentry id="nrsc4">
<abbrev>NRSC-4</abbrev>
<authorgroup>
<corpauthor>National Radio Systems Committee
(<ulink url="http://www.nrscstandards.org">http://www.nrscstandards.org</ulink>)</corpauthor>
</authorgroup>
<title>NTSC-4: United States RBDS Standard</title>
</biblioentry>
</bibliography>
kernel/Documentation/DocBook/media/v4l/capture.c.xml
+659
View File
@@ -0,0 +1,659 @@
<programlisting>
/*
* V4L2 video capture example
*
* This program can be used and distributed without restrictions.
*
* This program is provided with the V4L2 API
* see http://linuxtv.org/docs.php for more information
*/
#include &lt;stdio.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;string.h&gt;
#include &lt;assert.h&gt;
#include &lt;getopt.h&gt; /* getopt_long() */
#include &lt;fcntl.h&gt; /* low-level i/o */
#include &lt;unistd.h&gt;
#include &lt;errno.h&gt;
#include &lt;sys/stat.h&gt;
#include &lt;sys/types.h&gt;
#include &lt;sys/time.h&gt;
#include &lt;sys/mman.h&gt;
#include &lt;sys/ioctl.h&gt;
#include &lt;linux/videodev2.h&gt;
#define CLEAR(x) memset(&amp;(x), 0, sizeof(x))
enum io_method {
IO_METHOD_READ,
IO_METHOD_MMAP,
IO_METHOD_USERPTR,
};
struct buffer {
void *start;
size_t length;
};
static char *dev_name;
static enum io_method io = IO_METHOD_MMAP;
static int fd = -1;
struct buffer *buffers;
static unsigned int n_buffers;
static int out_buf;
static int force_format;
static int frame_count = 70;
static void errno_exit(const char *s)
{
fprintf(stderr, "%s error %d, %s\n", s, errno, strerror(errno));
exit(EXIT_FAILURE);
}
static int xioctl(int fh, int request, void *arg)
{
int r;
do {
r = ioctl(fh, request, arg);
} while (-1 == r &amp;&amp; EINTR == errno);
return r;
}
static void process_image(const void *p, int size)
{
if (out_buf)
fwrite(p, size, 1, stdout);
fflush(stderr);
fprintf(stderr, ".");
fflush(stdout);
}
static int read_frame(void)
{
struct <link linkend="v4l2-buffer">v4l2_buffer</link> buf;
unsigned int i;
switch (io) {
case IO_METHOD_READ:
if (-1 == read(fd, buffers[0].start, buffers[0].length)) {
switch (errno) {
case EAGAIN:
return 0;
case EIO:
/* Could ignore EIO, see spec. */
/* fall through */
default:
errno_exit("read");
}
}
process_image(buffers[0].start, buffers[0].length);
break;
case IO_METHOD_MMAP:
CLEAR(buf);
buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
buf.memory = V4L2_MEMORY_MMAP;
if (-1 == xioctl(fd, VIDIOC_DQBUF, &amp;buf)) {
switch (errno) {
case EAGAIN:
return 0;
case EIO:
/* Could ignore EIO, see spec. */
/* fall through */
default:
errno_exit("VIDIOC_DQBUF");
}
}
assert(buf.index &lt; n_buffers);
process_image(buffers[buf.index].start, buf.bytesused);
if (-1 == xioctl(fd, VIDIOC_QBUF, &amp;buf))
errno_exit("VIDIOC_QBUF");
break;
case IO_METHOD_USERPTR:
CLEAR(buf);
buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
buf.memory = V4L2_MEMORY_USERPTR;
if (-1 == xioctl(fd, VIDIOC_DQBUF, &amp;buf)) {
switch (errno) {
case EAGAIN:
return 0;
case EIO:
/* Could ignore EIO, see spec. */
/* fall through */
default:
errno_exit("VIDIOC_DQBUF");
}
}
for (i = 0; i &lt; n_buffers; ++i)
if (buf.m.userptr == (unsigned long)buffers[i].start
&amp;&amp; buf.length == buffers[i].length)
break;
assert(i &lt; n_buffers);
process_image((void *)buf.m.userptr, buf.bytesused);
if (-1 == xioctl(fd, VIDIOC_QBUF, &amp;buf))
errno_exit("VIDIOC_QBUF");
break;
}
return 1;
}
static void mainloop(void)
{
unsigned int count;
count = frame_count;
while (count-- &gt; 0) {
for (;;) {
fd_set fds;
struct timeval tv;
int r;
FD_ZERO(&amp;fds);
FD_SET(fd, &amp;fds);
/* Timeout. */
tv.tv_sec = 2;
tv.tv_usec = 0;
r = select(fd + 1, &amp;fds, NULL, NULL, &amp;tv);
if (-1 == r) {
if (EINTR == errno)
continue;
errno_exit("select");
}
if (0 == r) {
fprintf(stderr, "select timeout\n");
exit(EXIT_FAILURE);
}
if (read_frame())
break;
/* EAGAIN - continue select loop. */
}
}
}
static void stop_capturing(void)
{
enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type;
switch (io) {
case IO_METHOD_READ:
/* Nothing to do. */
break;
case IO_METHOD_MMAP:
case IO_METHOD_USERPTR:
type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
if (-1 == xioctl(fd, VIDIOC_STREAMOFF, &amp;type))
errno_exit("VIDIOC_STREAMOFF");
break;
}
}
static void start_capturing(void)
{
unsigned int i;
enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type;
switch (io) {
case IO_METHOD_READ:
/* Nothing to do. */
break;
case IO_METHOD_MMAP:
for (i = 0; i &lt; n_buffers; ++i) {
struct <link linkend="v4l2-buffer">v4l2_buffer</link> buf;
CLEAR(buf);
buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
buf.memory = V4L2_MEMORY_MMAP;
buf.index = i;
if (-1 == xioctl(fd, VIDIOC_QBUF, &amp;buf))
errno_exit("VIDIOC_QBUF");
}
type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
if (-1 == xioctl(fd, VIDIOC_STREAMON, &amp;type))
errno_exit("VIDIOC_STREAMON");
break;
case IO_METHOD_USERPTR:
for (i = 0; i &lt; n_buffers; ++i) {
struct <link linkend="v4l2-buffer">v4l2_buffer</link> buf;
CLEAR(buf);
buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
buf.memory = V4L2_MEMORY_USERPTR;
buf.index = i;
buf.m.userptr = (unsigned long)buffers[i].start;
buf.length = buffers[i].length;
if (-1 == xioctl(fd, VIDIOC_QBUF, &amp;buf))
errno_exit("VIDIOC_QBUF");
}
type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
if (-1 == xioctl(fd, VIDIOC_STREAMON, &amp;type))
errno_exit("VIDIOC_STREAMON");
break;
}
}
static void uninit_device(void)
{
unsigned int i;
switch (io) {
case IO_METHOD_READ:
free(buffers[0].start);
break;
case IO_METHOD_MMAP:
for (i = 0; i &lt; n_buffers; ++i)
if (-1 == munmap(buffers[i].start, buffers[i].length))
errno_exit("munmap");
break;
case IO_METHOD_USERPTR:
for (i = 0; i &lt; n_buffers; ++i)
free(buffers[i].start);
break;
}
free(buffers);
}
static void init_read(unsigned int buffer_size)
{
buffers = calloc(1, sizeof(*buffers));
if (!buffers) {
fprintf(stderr, "Out of memory\n");
exit(EXIT_FAILURE);
}
buffers[0].length = buffer_size;
buffers[0].start = malloc(buffer_size);
if (!buffers[0].start) {
fprintf(stderr, "Out of memory\n");
exit(EXIT_FAILURE);
}
}
static void init_mmap(void)
{
struct <link linkend="v4l2-requestbuffers">v4l2_requestbuffers</link> req;
CLEAR(req);
req.count = 4;
req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
req.memory = V4L2_MEMORY_MMAP;
if (-1 == xioctl(fd, VIDIOC_REQBUFS, &amp;req)) {
if (EINVAL == errno) {
fprintf(stderr, "%s does not support "
"memory mapping\n", dev_name);
exit(EXIT_FAILURE);
} else {
errno_exit("VIDIOC_REQBUFS");
}
}
if (req.count &lt; 2) {
fprintf(stderr, "Insufficient buffer memory on %s\n",
dev_name);
exit(EXIT_FAILURE);
}
buffers = calloc(req.count, sizeof(*buffers));
if (!buffers) {
fprintf(stderr, "Out of memory\n");
exit(EXIT_FAILURE);
}
for (n_buffers = 0; n_buffers &lt; req.count; ++n_buffers) {
struct <link linkend="v4l2-buffer">v4l2_buffer</link> buf;
CLEAR(buf);
buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
buf.memory = V4L2_MEMORY_MMAP;
buf.index = n_buffers;
if (-1 == xioctl(fd, VIDIOC_QUERYBUF, &amp;buf))
errno_exit("VIDIOC_QUERYBUF");
buffers[n_buffers].length = buf.length;
buffers[n_buffers].start =
mmap(NULL /* start anywhere */,
buf.length,
PROT_READ | PROT_WRITE /* required */,
MAP_SHARED /* recommended */,
fd, buf.m.offset);
if (MAP_FAILED == buffers[n_buffers].start)
errno_exit("mmap");
}
}
static void init_userp(unsigned int buffer_size)
{
struct <link linkend="v4l2-requestbuffers">v4l2_requestbuffers</link> req;
CLEAR(req);
req.count = 4;
req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
req.memory = V4L2_MEMORY_USERPTR;
if (-1 == xioctl(fd, VIDIOC_REQBUFS, &amp;req)) {
if (EINVAL == errno) {
fprintf(stderr, "%s does not support "
"user pointer i/o\n", dev_name);
exit(EXIT_FAILURE);
} else {
errno_exit("VIDIOC_REQBUFS");
}
}
buffers = calloc(4, sizeof(*buffers));
if (!buffers) {
fprintf(stderr, "Out of memory\n");
exit(EXIT_FAILURE);
}
for (n_buffers = 0; n_buffers &lt; 4; ++n_buffers) {
buffers[n_buffers].length = buffer_size;
buffers[n_buffers].start = malloc(buffer_size);
if (!buffers[n_buffers].start) {
fprintf(stderr, "Out of memory\n");
exit(EXIT_FAILURE);
}
}
}
static void init_device(void)
{
struct <link linkend="v4l2-capability">v4l2_capability</link> cap;
struct <link linkend="v4l2-cropcap">v4l2_cropcap</link> cropcap;
struct <link linkend="v4l2-crop">v4l2_crop</link> crop;
struct <link linkend="v4l2-format">v4l2_format</link> fmt;
unsigned int min;
if (-1 == xioctl(fd, VIDIOC_QUERYCAP, &amp;cap)) {
if (EINVAL == errno) {
fprintf(stderr, "%s is no V4L2 device\n",
dev_name);
exit(EXIT_FAILURE);
} else {
errno_exit("VIDIOC_QUERYCAP");
}
}
if (!(cap.capabilities &amp; V4L2_CAP_VIDEO_CAPTURE)) {
fprintf(stderr, "%s is no video capture device\n",
dev_name);
exit(EXIT_FAILURE);
}
switch (io) {
case IO_METHOD_READ:
if (!(cap.capabilities &amp; V4L2_CAP_READWRITE)) {
fprintf(stderr, "%s does not support read i/o\n",
dev_name);
exit(EXIT_FAILURE);
}
break;
case IO_METHOD_MMAP:
case IO_METHOD_USERPTR:
if (!(cap.capabilities &amp; V4L2_CAP_STREAMING)) {
fprintf(stderr, "%s does not support streaming i/o\n",
dev_name);
exit(EXIT_FAILURE);
}
break;
}
/* Select video input, video standard and tune here. */
CLEAR(cropcap);
cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
if (0 == xioctl(fd, VIDIOC_CROPCAP, &amp;cropcap)) {
crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
crop.c = cropcap.defrect; /* reset to default */
if (-1 == xioctl(fd, VIDIOC_S_CROP, &amp;crop)) {
switch (errno) {
case EINVAL:
/* Cropping not supported. */
break;
default:
/* Errors ignored. */
break;
}
}
} else {
/* Errors ignored. */
}
CLEAR(fmt);
fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
if (force_format) {
fmt.fmt.pix.width = 640;
fmt.fmt.pix.height = 480;
fmt.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV;
fmt.fmt.pix.field = V4L2_FIELD_INTERLACED;
if (-1 == xioctl(fd, VIDIOC_S_FMT, &amp;fmt))
errno_exit("VIDIOC_S_FMT");
/* Note VIDIOC_S_FMT may change width and height. */
} else {
/* Preserve original settings as set by v4l2-ctl for example */
if (-1 == xioctl(fd, VIDIOC_G_FMT, &amp;fmt))
errno_exit("VIDIOC_G_FMT");
}
/* Buggy driver paranoia. */
min = fmt.fmt.pix.width * 2;
if (fmt.fmt.pix.bytesperline &lt; min)
fmt.fmt.pix.bytesperline = min;
min = fmt.fmt.pix.bytesperline * fmt.fmt.pix.height;
if (fmt.fmt.pix.sizeimage &lt; min)
fmt.fmt.pix.sizeimage = min;
switch (io) {
case IO_METHOD_READ:
init_read(fmt.fmt.pix.sizeimage);
break;
case IO_METHOD_MMAP:
init_mmap();
break;
case IO_METHOD_USERPTR:
init_userp(fmt.fmt.pix.sizeimage);
break;
}
}
static void close_device(void)
{
if (-1 == close(fd))
errno_exit("close");
fd = -1;
}
static void open_device(void)
{
struct stat st;
if (-1 == stat(dev_name, &amp;st)) {
fprintf(stderr, "Cannot identify '%s': %d, %s\n",
dev_name, errno, strerror(errno));
exit(EXIT_FAILURE);
}
if (!S_ISCHR(st.st_mode)) {
fprintf(stderr, "%s is no device\n", dev_name);
exit(EXIT_FAILURE);
}
fd = open(dev_name, O_RDWR /* required */ | O_NONBLOCK, 0);
if (-1 == fd) {
fprintf(stderr, "Cannot open '%s': %d, %s\n",
dev_name, errno, strerror(errno));
exit(EXIT_FAILURE);
}
}
static void usage(FILE *fp, int argc, char **argv)
{
fprintf(fp,
"Usage: %s [options]\n\n"
"Version 1.3\n"
"Options:\n"
"-d | --device name Video device name [%s]\n"
"-h | --help Print this message\n"
"-m | --mmap Use memory mapped buffers [default]\n"
"-r | --read Use read() calls\n"
"-u | --userp Use application allocated buffers\n"
"-o | --output Outputs stream to stdout\n"
"-f | --format Force format to 640x480 YUYV\n"
"-c | --count Number of frames to grab [%i]\n"
"",
argv[0], dev_name, frame_count);
}
static const char short_options[] = "d:hmruofc:";
static const struct option
long_options[] = {
{ "device", required_argument, NULL, 'd' },
{ "help", no_argument, NULL, 'h' },
{ "mmap", no_argument, NULL, 'm' },
{ "read", no_argument, NULL, 'r' },
{ "userp", no_argument, NULL, 'u' },
{ "output", no_argument, NULL, 'o' },
{ "format", no_argument, NULL, 'f' },
{ "count", required_argument, NULL, 'c' },
{ 0, 0, 0, 0 }
};
int main(int argc, char **argv)
{
dev_name = "/dev/video0";
for (;;) {
int idx;
int c;
c = getopt_long(argc, argv,
short_options, long_options, &amp;idx);
if (-1 == c)
break;
switch (c) {
case 0: /* getopt_long() flag */
break;
case 'd':
dev_name = optarg;
break;
case 'h':
usage(stdout, argc, argv);
exit(EXIT_SUCCESS);
case 'm':
io = IO_METHOD_MMAP;
break;
case 'r':
io = IO_METHOD_READ;
break;
case 'u':
io = IO_METHOD_USERPTR;
break;
case 'o':
out_buf++;
break;
case 'f':
force_format++;
break;
case 'c':
errno = 0;
frame_count = strtol(optarg, NULL, 0);
if (errno)
errno_exit(optarg);
break;
default:
usage(stderr, argc, argv);
exit(EXIT_FAILURE);
}
}
open_device();
init_device();
start_capturing();
mainloop();
stop_capturing();
uninit_device();
close_device();
fprintf(stderr, "\n");
return 0;
}
</programlisting>
kernel/Documentation/DocBook/media/v4l/common.xml
+1199
View File
File diff suppressed because it is too large Load Diff
kernel/Documentation/DocBook/media/v4l/compat.xml
+2543
View File
File diff suppressed because it is too large Load Diff
kernel/Documentation/DocBook/media/v4l/controls.xml
+3602
View File
File diff suppressed because it is too large Load Diff
kernel/Documentation/DocBook/media/v4l/crop.pdf
BIN
View File
Binary file not shown.
kernel/Documentation/DocBook/media/v4l/dev-capture.xml
+110
View File
@@ -0,0 +1,110 @@
<title>Video Capture Interface</title>
<para>Video capture devices sample an analog video signal and store
the digitized images in memory. Today nearly all devices can capture
at full 25 or 30 frames/second. With this interface applications can
control the capture process and move images from the driver into user
space.</para>
<para>Conventionally V4L2 video capture devices are accessed through
character device special files named <filename>/dev/video</filename>
and <filename>/dev/video0</filename> to
<filename>/dev/video63</filename> with major number 81 and minor
numbers 0 to 63. <filename>/dev/video</filename> is typically a
symbolic link to the preferred video device. Note the same device
files are used for video output devices.</para>
<section>
<title>Querying Capabilities</title>
<para>Devices supporting the video capture interface set the
<constant>V4L2_CAP_VIDEO_CAPTURE</constant> or
<constant>V4L2_CAP_VIDEO_CAPTURE_MPLANE</constant> flag in the
<structfield>capabilities</structfield> field of &v4l2-capability;
returned by the &VIDIOC-QUERYCAP; ioctl. As secondary device functions
they may also support the <link linkend="overlay">video overlay</link>
(<constant>V4L2_CAP_VIDEO_OVERLAY</constant>) and the <link
linkend="raw-vbi">raw VBI capture</link>
(<constant>V4L2_CAP_VBI_CAPTURE</constant>) interface. At least one of
the read/write or streaming I/O methods must be supported. Tuners and
audio inputs are optional.</para>
</section>
<section>
<title>Supplemental Functions</title>
<para>Video capture devices shall support <link
linkend="audio">audio input</link>, <link
linkend="tuner">tuner</link>, <link linkend="control">controls</link>,
<link linkend="crop">cropping and scaling</link> and <link
linkend="streaming-par">streaming parameter</link> ioctls as needed.
The <link linkend="video">video input</link> and <link
linkend="standard">video standard</link> ioctls must be supported by
all video capture devices.</para>
</section>
<section>
<title>Image Format Negotiation</title>
<para>The result of a capture operation is determined by
cropping and image format parameters. The former select an area of the
video picture to capture, the latter how images are stored in memory,
&ie; in RGB or YUV format, the number of bits per pixel or width and
height. Together they also define how images are scaled in the
process.</para>
<para>As usual these parameters are <emphasis>not</emphasis> reset
at &func-open; time to permit Unix tool chains, programming a device
and then reading from it as if it was a plain file. Well written V4L2
applications ensure they really get what they want, including cropping
and scaling.</para>
<para>Cropping initialization at minimum requires to reset the
parameters to defaults. An example is given in <xref
linkend="crop" />.</para>
<para>To query the current image format applications set the
<structfield>type</structfield> field of a &v4l2-format; to
<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> or
<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant> and call the
&VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill
the &v4l2-pix-format; <structfield>pix</structfield> or the
&v4l2-pix-format-mplane; <structfield>pix_mp</structfield> member of the
<structfield>fmt</structfield> union.</para>
<para>To request different parameters applications set the
<structfield>type</structfield> field of a &v4l2-format; as above and
initialize all fields of the &v4l2-pix-format;
<structfield>vbi</structfield> member of the
<structfield>fmt</structfield> union, or better just modify the
results of <constant>VIDIOC_G_FMT</constant>, and call the
&VIDIOC-S-FMT; ioctl with a pointer to this structure. Drivers may
adjust the parameters and finally return the actual parameters as
<constant>VIDIOC_G_FMT</constant> does.</para>
<para>Like <constant>VIDIOC_S_FMT</constant> the
&VIDIOC-TRY-FMT; ioctl can be used to learn about hardware limitations
without disabling I/O or possibly time consuming hardware
preparations.</para>
<para>The contents of &v4l2-pix-format; and &v4l2-pix-format-mplane;
are discussed in <xref linkend="pixfmt" />. See also the specification of the
<constant>VIDIOC_G_FMT</constant>, <constant>VIDIOC_S_FMT</constant>
and <constant>VIDIOC_TRY_FMT</constant> ioctls for details. Video
capture devices must implement both the
<constant>VIDIOC_G_FMT</constant> and
<constant>VIDIOC_S_FMT</constant> ioctl, even if
<constant>VIDIOC_S_FMT</constant> ignores all requests and always
returns default parameters as <constant>VIDIOC_G_FMT</constant> does.
<constant>VIDIOC_TRY_FMT</constant> is optional.</para>
</section>
<section>
<title>Reading Images</title>
<para>A video capture device may support the <link
linkend="rw">read() function</link> and/or streaming (<link
linkend="mmap">memory mapping</link> or <link
linkend="userp">user pointer</link>) I/O. See <xref
linkend="io" /> for details.</para>
</section>
kernel/Documentation/DocBook/media/v4l/dev-codec.xml
+18
View File
@@ -0,0 +1,18 @@
<title>Codec Interface</title>
<note>
<title>Suspended</title>
<para>This interface has been be suspended from the V4L2 API
implemented in Linux 2.6 until we have more experience with codec
device interfaces.</para>
</note>
<para>A V4L2 codec can compress, decompress, transform, or otherwise
convert video data from one format into another format, in memory.
Applications send data to be converted to the driver through a
&func-write; call, and receive the converted data through a
&func-read; call. For efficiency a driver may also support streaming
I/O.</para>
<para>[to do]</para>
kernel/Documentation/DocBook/media/v4l/dev-effect.xml
+17
View File
@@ -0,0 +1,17 @@
<title>Effect Devices Interface</title>
<note>
<title>Suspended</title>
<para>This interface has been be suspended from the V4L2 API
implemented in Linux 2.6 until we have more experience with effect
device interfaces.</para>
</note>
<para>A V4L2 video effect device can do image effects, filtering, or
combine two or more images or image streams. For example video
transitions or wipes. Applications send data to be processed and
receive the result data either with &func-read; and &func-write;
functions, or through the streaming I/O mechanism.</para>
<para>[to do]</para>
kernel/Documentation/DocBook/media/v4l/dev-event.xml
+43
View File
@@ -0,0 +1,43 @@
<title>Event Interface</title>
<para>The V4L2 event interface provides a means for a user to get
immediately notified on certain conditions taking place on a device.
This might include start of frame or loss of signal events, for
example. Changes in the value or state of a V4L2 control can also be
reported through events.
</para>
<para>To receive events, the events the user is interested in first must
be subscribed using the &VIDIOC-SUBSCRIBE-EVENT; ioctl. Once an event is
subscribed, the events of subscribed types are dequeueable using the
&VIDIOC-DQEVENT; ioctl. Events may be unsubscribed using
VIDIOC_UNSUBSCRIBE_EVENT ioctl. The special event type V4L2_EVENT_ALL may
be used to unsubscribe all the events the driver supports.</para>
<para>The event subscriptions and event queues are specific to file
handles. Subscribing an event on one file handle does not affect
other file handles.</para>
<para>The information on dequeueable events is obtained by using select or
poll system calls on video devices. The V4L2 events use POLLPRI events on
poll system call and exceptions on select system call.</para>
<para>Starting with kernel 3.1 certain guarantees can be given with
regards to events:<orderedlist>
<listitem>
<para>Each subscribed event has its own internal dedicated event queue.
This means that flooding of one event type will not interfere with other
event types.</para>
</listitem>
<listitem>
<para>If the internal event queue for a particular subscribed event
becomes full, then the oldest event in that queue will be dropped.</para>
</listitem>
<listitem>
<para>Where applicable, certain event types can ensure that the payload
of the oldest event that is about to be dropped will be merged with the payload
of the next oldest event. Thus ensuring that no information is lost, but only an
intermediate step leading up to that information. See the documentation for the
event you want to subscribe to whether this is applicable for that event or not.</para>
</listitem>
</orderedlist></para>
kernel/Documentation/DocBook/media/v4l/dev-osd.xml
+156
View File
@@ -0,0 +1,156 @@
<title>Video Output Overlay Interface</title>
<subtitle>Also known as On-Screen Display (OSD)</subtitle>
<note>
<title>Experimental</title>
<para>This is an <link linkend="experimental">experimental</link>
interface and may change in the future.</para>
</note>
<para>Some video output devices can overlay a framebuffer image onto
the outgoing video signal. Applications can set up such an overlay
using this interface, which borrows structures and ioctls of the <link
linkend="overlay">Video Overlay</link> interface.</para>
<para>The OSD function is accessible through the same character
special file as the <link linkend="capture">Video Output</link> function.
Note the default function of such a <filename>/dev/video</filename> device
is video capturing or output. The OSD function is only available after
calling the &VIDIOC-S-FMT; ioctl.</para>
<section>
<title>Querying Capabilities</title>
<para>Devices supporting the <wordasword>Video Output
Overlay</wordasword> interface set the
<constant>V4L2_CAP_VIDEO_OUTPUT_OVERLAY</constant> flag in the
<structfield>capabilities</structfield> field of &v4l2-capability;
returned by the &VIDIOC-QUERYCAP; ioctl.</para>
</section>
<section>
<title>Framebuffer</title>
<para>Contrary to the <wordasword>Video Overlay</wordasword>
interface the framebuffer is normally implemented on the TV card and
not the graphics card. On Linux it is accessible as a framebuffer
device (<filename>/dev/fbN</filename>). Given a V4L2 device,
applications can find the corresponding framebuffer device by calling
the &VIDIOC-G-FBUF; ioctl. It returns, amongst other information, the
physical address of the framebuffer in the
<structfield>base</structfield> field of &v4l2-framebuffer;. The
framebuffer device ioctl <constant>FBIOGET_FSCREENINFO</constant>
returns the same address in the <structfield>smem_start</structfield>
field of struct <structname>fb_fix_screeninfo</structname>. The
<constant>FBIOGET_FSCREENINFO</constant> ioctl and struct
<structname>fb_fix_screeninfo</structname> are defined in the
<filename>linux/fb.h</filename> header file.</para>
<para>The width and height of the framebuffer depends on the
current video standard. A V4L2 driver may reject attempts to change
the video standard (or any other ioctl which would imply a framebuffer
size change) with an &EBUSY; until all applications closed the
framebuffer device.</para>
<example>
<title>Finding a framebuffer device for OSD</title>
<programlisting>
#include &lt;linux/fb.h&gt;
&v4l2-framebuffer; fbuf;
unsigned int i;
int fb_fd;
if (-1 == ioctl (fd, VIDIOC_G_FBUF, &amp;fbuf)) {
perror ("VIDIOC_G_FBUF");
exit (EXIT_FAILURE);
}
for (i = 0; i &gt; 30; ++i) {
char dev_name[16];
struct fb_fix_screeninfo si;
snprintf (dev_name, sizeof (dev_name), "/dev/fb%u", i);
fb_fd = open (dev_name, O_RDWR);
if (-1 == fb_fd) {
switch (errno) {
case ENOENT: /* no such file */
case ENXIO: /* no driver */
continue;
default:
perror ("open");
exit (EXIT_FAILURE);
}
}
if (0 == ioctl (fb_fd, FBIOGET_FSCREENINFO, &amp;si)) {
if (si.smem_start == (unsigned long) fbuf.base)
break;
} else {
/* Apparently not a framebuffer device. */
}
close (fb_fd);
fb_fd = -1;
}
/* fb_fd is the file descriptor of the framebuffer device
for the video output overlay, or -1 if no device was found. */
</programlisting>
</example>
</section>
<section>
<title>Overlay Window and Scaling</title>
<para>The overlay is controlled by source and target rectangles.
The source rectangle selects a subsection of the framebuffer image to
be overlaid, the target rectangle an area in the outgoing video signal
where the image will appear. Drivers may or may not support scaling,
and arbitrary sizes and positions of these rectangles. Further drivers
may support any (or none) of the clipping/blending methods defined for
the <link linkend="overlay">Video Overlay</link> interface.</para>
<para>A &v4l2-window; defines the size of the source rectangle,
its position in the framebuffer and the clipping/blending method to be
used for the overlay. To get the current parameters applications set
the <structfield>type</structfield> field of a &v4l2-format; to
<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant> and call the
&VIDIOC-G-FMT; ioctl. The driver fills the
<structname>v4l2_window</structname> substructure named
<structfield>win</structfield>. It is not possible to retrieve a
previously programmed clipping list or bitmap.</para>
<para>To program the source rectangle applications set the
<structfield>type</structfield> field of a &v4l2-format; to
<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant>, initialize
the <structfield>win</structfield> substructure and call the
&VIDIOC-S-FMT; ioctl. The driver adjusts the parameters against
hardware limits and returns the actual parameters as
<constant>VIDIOC_G_FMT</constant> does. Like
<constant>VIDIOC_S_FMT</constant>, the &VIDIOC-TRY-FMT; ioctl can be
used to learn about driver capabilities without actually changing
driver state. Unlike <constant>VIDIOC_S_FMT</constant> this also works
after the overlay has been enabled.</para>
<para>A &v4l2-crop; defines the size and position of the target
rectangle. The scaling factor of the overlay is implied by the width
and height given in &v4l2-window; and &v4l2-crop;. The cropping API
applies to <wordasword>Video Output</wordasword> and <wordasword>Video
Output Overlay</wordasword> devices in the same way as to
<wordasword>Video Capture</wordasword> and <wordasword>Video
Overlay</wordasword> devices, merely reversing the direction of the
data flow. For more information see <xref linkend="crop" />.</para>
</section>
<section>
<title>Enabling Overlay</title>
<para>There is no V4L2 ioctl to enable or disable the overlay,
however the framebuffer interface of the driver may support the
<constant>FBIOBLANK</constant> ioctl.</para>
</section>
kernel/Documentation/DocBook/media/v4l/dev-output.xml
+106
View File
@@ -0,0 +1,106 @@
<title>Video Output Interface</title>
<para>Video output devices encode stills or image sequences as
analog video signal. With this interface applications can
control the encoding process and move images from user space to
the driver.</para>
<para>Conventionally V4L2 video output devices are accessed through
character device special files named <filename>/dev/video</filename>
and <filename>/dev/video0</filename> to
<filename>/dev/video63</filename> with major number 81 and minor
numbers 0 to 63. <filename>/dev/video</filename> is typically a
symbolic link to the preferred video device. Note the same device
files are used for video capture devices.</para>
<section>
<title>Querying Capabilities</title>
<para>Devices supporting the video output interface set the
<constant>V4L2_CAP_VIDEO_OUTPUT</constant> or
<constant>V4L2_CAP_VIDEO_OUTPUT_MPLANE</constant> flag in the
<structfield>capabilities</structfield> field of &v4l2-capability;
returned by the &VIDIOC-QUERYCAP; ioctl. As secondary device functions
they may also support the <link linkend="raw-vbi">raw VBI
output</link> (<constant>V4L2_CAP_VBI_OUTPUT</constant>) interface. At
least one of the read/write or streaming I/O methods must be
supported. Modulators and audio outputs are optional.</para>
</section>
<section>
<title>Supplemental Functions</title>
<para>Video output devices shall support <link
linkend="audio">audio output</link>, <link
linkend="tuner">modulator</link>, <link linkend="control">controls</link>,
<link linkend="crop">cropping and scaling</link> and <link
linkend="streaming-par">streaming parameter</link> ioctls as needed.
The <link linkend="video">video output</link> and <link
linkend="standard">video standard</link> ioctls must be supported by
all video output devices.</para>
</section>
<section>
<title>Image Format Negotiation</title>
<para>The output is determined by cropping and image format
parameters. The former select an area of the video picture where the
image will appear, the latter how images are stored in memory, &ie; in
RGB or YUV format, the number of bits per pixel or width and height.
Together they also define how images are scaled in the process.</para>
<para>As usual these parameters are <emphasis>not</emphasis> reset
at &func-open; time to permit Unix tool chains, programming a device
and then writing to it as if it was a plain file. Well written V4L2
applications ensure they really get what they want, including cropping
and scaling.</para>
<para>Cropping initialization at minimum requires to reset the
parameters to defaults. An example is given in <xref
linkend="crop" />.</para>
<para>To query the current image format applications set the
<structfield>type</structfield> field of a &v4l2-format; to
<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> or
<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant> and call the
&VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill
the &v4l2-pix-format; <structfield>pix</structfield> or the
&v4l2-pix-format-mplane; <structfield>pix_mp</structfield> member of the
<structfield>fmt</structfield> union.</para>
<para>To request different parameters applications set the
<structfield>type</structfield> field of a &v4l2-format; as above and
initialize all fields of the &v4l2-pix-format;
<structfield>vbi</structfield> member of the
<structfield>fmt</structfield> union, or better just modify the
results of <constant>VIDIOC_G_FMT</constant>, and call the
&VIDIOC-S-FMT; ioctl with a pointer to this structure. Drivers may
adjust the parameters and finally return the actual parameters as
<constant>VIDIOC_G_FMT</constant> does.</para>
<para>Like <constant>VIDIOC_S_FMT</constant> the
&VIDIOC-TRY-FMT; ioctl can be used to learn about hardware limitations
without disabling I/O or possibly time consuming hardware
preparations.</para>
<para>The contents of &v4l2-pix-format; and &v4l2-pix-format-mplane;
are discussed in <xref linkend="pixfmt" />. See also the specification of the
<constant>VIDIOC_G_FMT</constant>, <constant>VIDIOC_S_FMT</constant>
and <constant>VIDIOC_TRY_FMT</constant> ioctls for details. Video
output devices must implement both the
<constant>VIDIOC_G_FMT</constant> and
<constant>VIDIOC_S_FMT</constant> ioctl, even if
<constant>VIDIOC_S_FMT</constant> ignores all requests and always
returns default parameters as <constant>VIDIOC_G_FMT</constant> does.
<constant>VIDIOC_TRY_FMT</constant> is optional.</para>
</section>
<section>
<title>Writing Images</title>
<para>A video output device may support the <link
linkend="rw">write() function</link> and/or streaming (<link
linkend="mmap">memory mapping</link> or <link
linkend="userp">user pointer</link>) I/O. See <xref
linkend="io" /> for details.</para>
</section>
kernel/Documentation/DocBook/media/v4l/dev-overlay.xml
+371
View File
@@ -0,0 +1,371 @@
<title>Video Overlay Interface</title>
<subtitle>Also known as Framebuffer Overlay or Previewing</subtitle>
<para>Video overlay devices have the ability to genlock (TV-)video
into the (VGA-)video signal of a graphics card, or to store captured
images directly in video memory of a graphics card, typically with
clipping. This can be considerable more efficient than capturing
images and displaying them by other means. In the old days when only
nuclear power plants needed cooling towers this used to be the only
way to put live video into a window.</para>
<para>Video overlay devices are accessed through the same character
special files as <link linkend="capture">video capture</link> devices.
Note the default function of a <filename>/dev/video</filename> device
is video capturing. The overlay function is only available after
calling the &VIDIOC-S-FMT; ioctl.</para>
<para>The driver may support simultaneous overlay and capturing
using the read/write and streaming I/O methods. If so, operation at
the nominal frame rate of the video standard is not guaranteed. Frames
may be directed away from overlay to capture, or one field may be used
for overlay and the other for capture if the capture parameters permit
this.</para>
<para>Applications should use different file descriptors for
capturing and overlay. This must be supported by all drivers capable
of simultaneous capturing and overlay. Optionally these drivers may
also permit capturing and overlay with a single file descriptor for
compatibility with V4L and earlier versions of V4L2.<footnote>
<para>A common application of two file descriptors is the
XFree86 <link linkend="xvideo">Xv/V4L</link> interface driver and
a V4L2 application. While the X server controls video overlay, the
application can take advantage of memory mapping and DMA.</para>
<para>In the opinion of the designers of this API, no driver
writer taking the efforts to support simultaneous capturing and
overlay will restrict this ability by requiring a single file
descriptor, as in V4L and earlier versions of V4L2. Making this
optional means applications depending on two file descriptors need
backup routines to be compatible with all drivers, which is
considerable more work than using two fds in applications which do
not. Also two fd's fit the general concept of one file descriptor for
each logical stream. Hence as a complexity trade-off drivers
<emphasis>must</emphasis> support two file descriptors and
<emphasis>may</emphasis> support single fd operation.</para>
</footnote></para>
<section>
<title>Querying Capabilities</title>
<para>Devices supporting the video overlay interface set the
<constant>V4L2_CAP_VIDEO_OVERLAY</constant> flag in the
<structfield>capabilities</structfield> field of &v4l2-capability;
returned by the &VIDIOC-QUERYCAP; ioctl. The overlay I/O method specified
below must be supported. Tuners and audio inputs are optional.</para>
</section>
<section>
<title>Supplemental Functions</title>
<para>Video overlay devices shall support <link
linkend="audio">audio input</link>, <link
linkend="tuner">tuner</link>, <link linkend="control">controls</link>,
<link linkend="crop">cropping and scaling</link> and <link
linkend="streaming-par">streaming parameter</link> ioctls as needed.
The <link linkend="video">video input</link> and <link
linkend="standard">video standard</link> ioctls must be supported by
all video overlay devices.</para>
</section>
<section>
<title>Setup</title>
<para>Before overlay can commence applications must program the
driver with frame buffer parameters, namely the address and size of
the frame buffer and the image format, for example RGB 5:6:5. The
&VIDIOC-G-FBUF; and &VIDIOC-S-FBUF; ioctls are available to get
and set these parameters, respectively. The
<constant>VIDIOC_S_FBUF</constant> ioctl is privileged because it
allows to set up DMA into physical memory, bypassing the memory
protection mechanisms of the kernel. Only the superuser can change the
frame buffer address and size. Users are not supposed to run TV
applications as root or with SUID bit set. A small helper application
with suitable privileges should query the graphics system and program
the V4L2 driver at the appropriate time.</para>
<para>Some devices add the video overlay to the output signal
of the graphics card. In this case the frame buffer is not modified by
the video device, and the frame buffer address and pixel format are
not needed by the driver. The <constant>VIDIOC_S_FBUF</constant> ioctl
is not privileged. An application can check for this type of device by
calling the <constant>VIDIOC_G_FBUF</constant> ioctl.</para>
<para>A driver may support any (or none) of five clipping/blending
methods:<orderedlist>
<listitem>
<para>Chroma-keying displays the overlaid image only where
pixels in the primary graphics surface assume a certain color.</para>
</listitem>
<listitem>
<para>A bitmap can be specified where each bit corresponds
to a pixel in the overlaid image. When the bit is set, the
corresponding video pixel is displayed, otherwise a pixel of the
graphics surface.</para>
</listitem>
<listitem>
<para>A list of clipping rectangles can be specified. In
these regions <emphasis>no</emphasis> video is displayed, so the
graphics surface can be seen here.</para>
</listitem>
<listitem>
<para>The framebuffer has an alpha channel that can be used
to clip or blend the framebuffer with the video.</para>
</listitem>
<listitem>
<para>A global alpha value can be specified to blend the
framebuffer contents with video images.</para>
</listitem>
</orderedlist></para>
<para>When simultaneous capturing and overlay is supported and
the hardware prohibits different image and frame buffer formats, the
format requested first takes precedence. The attempt to capture
(&VIDIOC-S-FMT;) or overlay (&VIDIOC-S-FBUF;) may fail with an
&EBUSY; or return accordingly modified parameters..</para>
</section>
<section>
<title>Overlay Window</title>
<para>The overlaid image is determined by cropping and overlay
window parameters. The former select an area of the video picture to
capture, the latter how images are overlaid and clipped. Cropping
initialization at minimum requires to reset the parameters to
defaults. An example is given in <xref linkend="crop" />.</para>
<para>The overlay window is described by a &v4l2-window;. It
defines the size of the image, its position over the graphics surface
and the clipping to be applied. To get the current parameters
applications set the <structfield>type</structfield> field of a
&v4l2-format; to <constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant> and
call the &VIDIOC-G-FMT; ioctl. The driver fills the
<structname>v4l2_window</structname> substructure named
<structfield>win</structfield>. It is not possible to retrieve a
previously programmed clipping list or bitmap.</para>
<para>To program the overlay window applications set the
<structfield>type</structfield> field of a &v4l2-format; to
<constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>, initialize the
<structfield>win</structfield> substructure and call the
&VIDIOC-S-FMT; ioctl. The driver adjusts the parameters against
hardware limits and returns the actual parameters as
<constant>VIDIOC_G_FMT</constant> does. Like
<constant>VIDIOC_S_FMT</constant>, the &VIDIOC-TRY-FMT; ioctl can be
used to learn about driver capabilities without actually changing
driver state. Unlike <constant>VIDIOC_S_FMT</constant> this also works
after the overlay has been enabled.</para>
<para>The scaling factor of the overlaid image is implied by the
width and height given in &v4l2-window; and the size of the cropping
rectangle. For more information see <xref linkend="crop" />.</para>
<para>When simultaneous capturing and overlay is supported and
the hardware prohibits different image and window sizes, the size
requested first takes precedence. The attempt to capture or overlay as
well (&VIDIOC-S-FMT;) may fail with an &EBUSY; or return accordingly
modified parameters.</para>
<table pgwide="1" frame="none" id="v4l2-window">
<title>struct <structname>v4l2_window</structname></title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>&v4l2-rect;</entry>
<entry><structfield>w</structfield></entry>
<entry>Size and position of the window relative to the
top, left corner of the frame buffer defined with &VIDIOC-S-FBUF;. The
window can extend the frame buffer width and height, the
<structfield>x</structfield> and <structfield>y</structfield>
coordinates can be negative, and it can lie completely outside the
frame buffer. The driver clips the window accordingly, or if that is
not possible, modifies its size and/or position.</entry>
</row>
<row>
<entry>&v4l2-field;</entry>
<entry><structfield>field</structfield></entry>
<entry>Applications set this field to determine which
video field shall be overlaid, typically one of
<constant>V4L2_FIELD_ANY</constant> (0),
<constant>V4L2_FIELD_TOP</constant>,
<constant>V4L2_FIELD_BOTTOM</constant> or
<constant>V4L2_FIELD_INTERLACED</constant>. Drivers may have to choose
a different field order and return the actual setting here.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>chromakey</structfield></entry>
<entry>When chroma-keying has been negotiated with
&VIDIOC-S-FBUF; applications set this field to the desired pixel value
for the chroma key. The format is the same as the pixel format of the
framebuffer (&v4l2-framebuffer;
<structfield>fmt.pixelformat</structfield> field), with bytes in host
order. E.&nbsp;g. for <link
linkend="V4L2-PIX-FMT-BGR32"><constant>V4L2_PIX_FMT_BGR24</constant></link>
the value should be 0xRRGGBB on a little endian, 0xBBGGRR on a big
endian host.</entry>
</row>
<row>
<entry>&v4l2-clip; *</entry>
<entry><structfield>clips</structfield></entry>
<entry>When chroma-keying has <emphasis>not</emphasis>
been negotiated and &VIDIOC-G-FBUF; indicated this capability,
applications can set this field to point to an array of
clipping rectangles.</entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry>Like the window coordinates
<structfield>w</structfield>, clipping rectangles are defined relative
to the top, left corner of the frame buffer. However clipping
rectangles must not extend the frame buffer width and height, and they
must not overlap. If possible applications should merge adjacent
rectangles. Whether this must create x-y or y-x bands, or the order of
rectangles, is not defined. When clip lists are not supported the
driver ignores this field. Its contents after calling &VIDIOC-S-FMT;
are undefined.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>clipcount</structfield></entry>
<entry>When the application set the
<structfield>clips</structfield> field, this field must contain the
number of clipping rectangles in the list. When clip lists are not
supported the driver ignores this field, its contents after calling
<constant>VIDIOC_S_FMT</constant> are undefined. When clip lists are
supported but no clipping is desired this field must be set to
zero.</entry>
</row>
<row>
<entry>void *</entry>
<entry><structfield>bitmap</structfield></entry>
<entry>When chroma-keying has
<emphasis>not</emphasis> been negotiated and &VIDIOC-G-FBUF; indicated
this capability, applications can set this field to point to a
clipping bit mask.</entry>
</row>
<row>
<entry spanname="hspan"><para>It must be of the same size
as the window, <structfield>w.width</structfield> and
<structfield>w.height</structfield>. Each bit corresponds to a pixel
in the overlaid image, which is displayed only when the bit is
<emphasis>set</emphasis>. Pixel coordinates translate to bits like:
<programlisting>
((__u8 *) <structfield>bitmap</structfield>)[<structfield>w.width</structfield> * y + x / 8] &amp; (1 &lt;&lt; (x &amp; 7))</programlisting></para><para>where <structfield>0</structfield> &le; x &lt;
<structfield>w.width</structfield> and <structfield>0</structfield> &le;
y &lt;<structfield>w.height</structfield>.<footnote>
<para>Should we require
<structfield>w.width</structfield> to be a multiple of
eight?</para>
</footnote></para><para>When a clipping
bit mask is not supported the driver ignores this field, its contents
after calling &VIDIOC-S-FMT; are undefined. When a bit mask is supported
but no clipping is desired this field must be set to
<constant>NULL</constant>.</para><para>Applications need not create a
clip list or bit mask. When they pass both, or despite negotiating
chroma-keying, the results are undefined. Regardless of the chosen
method, the clipping abilities of the hardware may be limited in
quantity or quality. The results when these limits are exceeded are
undefined.<footnote>
<para>When the image is written into frame buffer
memory it will be undesirable if the driver clips out less pixels
than expected, because the application and graphics system are not
aware these regions need to be refreshed. The driver should clip out
more pixels or not write the image at all.</para>
</footnote></para></entry>
</row>
<row>
<entry>__u8</entry>
<entry><structfield>global_alpha</structfield></entry>
<entry>The global alpha value used to blend the
framebuffer with video images, if global alpha blending has been
negotiated (<constant>V4L2_FBUF_FLAG_GLOBAL_ALPHA</constant>, see
&VIDIOC-S-FBUF;, <xref linkend="framebuffer-flags" />).</entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry>Note this field was added in Linux 2.6.23, extending the structure. However
the <link linkend="vidioc-g-fmt">VIDIOC_G/S/TRY_FMT</link> ioctls,
which take a pointer to a <link
linkend="v4l2-format">v4l2_format</link> parent structure with padding
bytes at the end, are not affected.</entry>
</row>
</tbody>
</tgroup>
</table>
<table pgwide="1" frame="none" id="v4l2-clip">
<title>struct <structname>v4l2_clip</structname><footnote>
<para>The X Window system defines "regions" which are
vectors of struct BoxRec { short x1, y1, x2, y2; } with width = x2 -
x1 and height = y2 - y1, so one cannot pass X11 clip lists
directly.</para>
</footnote></title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>&v4l2-rect;</entry>
<entry><structfield>c</structfield></entry>
<entry>Coordinates of the clipping rectangle, relative to
the top, left corner of the frame buffer. Only window pixels
<emphasis>outside</emphasis> all clipping rectangles are
displayed.</entry>
</row>
<row>
<entry>&v4l2-clip; *</entry>
<entry><structfield>next</structfield></entry>
<entry>Pointer to the next clipping rectangle, NULL when
this is the last rectangle. Drivers ignore this field, it cannot be
used to pass a linked list of clipping rectangles.</entry>
</row>
</tbody>
</tgroup>
</table>
<!-- NB for easier reading this table is duplicated
in the vidioc-cropcap chapter.-->
<table pgwide="1" frame="none" id="v4l2-rect">
<title>struct <structname>v4l2_rect</structname></title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>__s32</entry>
<entry><structfield>left</structfield></entry>
<entry>Horizontal offset of the top, left corner of the
rectangle, in pixels.</entry>
</row>
<row>
<entry>__s32</entry>
<entry><structfield>top</structfield></entry>
<entry>Vertical offset of the top, left corner of the
rectangle, in pixels. Offsets increase to the right and down.</entry>
</row>
<row>
<entry>__s32</entry>
<entry><structfield>width</structfield></entry>
<entry>Width of the rectangle, in pixels.</entry>
</row>
<row>
<entry>__s32</entry>
<entry><structfield>height</structfield></entry>
<entry>Height of the rectangle, in pixels. Width and
height cannot be negative, the fields are signed for hysterical
reasons. <!-- video4linux-list@redhat.com on 22 Oct 2002 subject
"Re:[V4L][patches!] Re:v4l2/kernel-2.5" --></entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section>
<title>Enabling Overlay</title>
<para>To start or stop the frame buffer overlay applications call
the &VIDIOC-OVERLAY; ioctl.</para>
</section>
kernel/Documentation/DocBook/media/v4l/dev-radio.xml
+49
View File
@@ -0,0 +1,49 @@
<title>Radio Interface</title>
<para>This interface is intended for AM and FM (analog) radio
receivers and transmitters.</para>
<para>Conventionally V4L2 radio devices are accessed through
character device special files named <filename>/dev/radio</filename>
and <filename>/dev/radio0</filename> to
<filename>/dev/radio63</filename> with major number 81 and minor
numbers 64 to 127.</para>
<section>
<title>Querying Capabilities</title>
<para>Devices supporting the radio interface set the
<constant>V4L2_CAP_RADIO</constant> and
<constant>V4L2_CAP_TUNER</constant> or
<constant>V4L2_CAP_MODULATOR</constant> flag in the
<structfield>capabilities</structfield> field of &v4l2-capability;
returned by the &VIDIOC-QUERYCAP; ioctl. Other combinations of
capability flags are reserved for future extensions.</para>
</section>
<section>
<title>Supplemental Functions</title>
<para>Radio devices can support <link
linkend="control">controls</link>, and must support the <link
linkend="tuner">tuner or modulator</link> ioctls.</para>
<para>They do not support the video input or output, audio input
or output, video standard, cropping and scaling, compression and
streaming parameter, or overlay ioctls. All other ioctls and I/O
methods are reserved for future extensions.</para>
</section>
<section>
<title>Programming</title>
<para>Radio devices may have a couple audio controls (as discussed
in <xref linkend="control" />) such as a volume control, possibly custom
controls. Further all radio devices have one tuner or modulator (these are
discussed in <xref linkend="tuner" />) with index number zero to select
the radio frequency and to determine if a monaural or FM stereo
program is received/emitted. Drivers switch automatically between AM and FM
depending on the selected frequency. The &VIDIOC-G-TUNER; or
&VIDIOC-G-MODULATOR; ioctl
reports the supported frequency range.</para>
</section>
kernel/Documentation/DocBook/media/v4l/dev-raw-vbi.xml
+339
View File
@@ -0,0 +1,339 @@
<title>Raw VBI Data Interface</title>
<para>VBI is an abbreviation of Vertical Blanking Interval, a gap
in the sequence of lines of an analog video signal. During VBI
no picture information is transmitted, allowing some time while the
electron beam of a cathode ray tube TV returns to the top of the
screen. Using an oscilloscope you will find here the vertical
synchronization pulses and short data packages ASK
modulated<footnote><para>ASK: Amplitude-Shift Keying. A high signal
level represents a '1' bit, a low level a '0' bit.</para></footnote>
onto the video signal. These are transmissions of services such as
Teletext or Closed Caption.</para>
<para>Subject of this interface type is raw VBI data, as sampled off
a video signal, or to be added to a signal for output.
The data format is similar to uncompressed video images, a number of
lines times a number of samples per line, we call this a VBI image.</para>
<para>Conventionally V4L2 VBI devices are accessed through character
device special files named <filename>/dev/vbi</filename> and
<filename>/dev/vbi0</filename> to <filename>/dev/vbi31</filename> with
major number 81 and minor numbers 224 to 255.
<filename>/dev/vbi</filename> is typically a symbolic link to the
preferred VBI device. This convention applies to both input and output
devices.</para>
<para>To address the problems of finding related video and VBI
devices VBI capturing and output is also available as device function
under <filename>/dev/video</filename>. To capture or output raw VBI
data with these devices applications must call the &VIDIOC-S-FMT;
ioctl. Accessed as <filename>/dev/vbi</filename>, raw VBI capturing
or output is the default device function.</para>
<section>
<title>Querying Capabilities</title>
<para>Devices supporting the raw VBI capturing or output API set
the <constant>V4L2_CAP_VBI_CAPTURE</constant> or
<constant>V4L2_CAP_VBI_OUTPUT</constant> flags, respectively, in the
<structfield>capabilities</structfield> field of &v4l2-capability;
returned by the &VIDIOC-QUERYCAP; ioctl. At least one of the
read/write, streaming or asynchronous I/O methods must be
supported. VBI devices may or may not have a tuner or modulator.</para>
</section>
<section>
<title>Supplemental Functions</title>
<para>VBI devices shall support <link linkend="video">video
input or output</link>, <link linkend="tuner">tuner or
modulator</link>, and <link linkend="control">controls</link> ioctls
as needed. The <link linkend="standard">video standard</link> ioctls provide
information vital to program a VBI device, therefore must be
supported.</para>
</section>
<section>
<title>Raw VBI Format Negotiation</title>
<para>Raw VBI sampling abilities can vary, in particular the
sampling frequency. To properly interpret the data V4L2 specifies an
ioctl to query the sampling parameters. Moreover, to allow for some
flexibility applications can also suggest different parameters.</para>
<para>As usual these parameters are <emphasis>not</emphasis>
reset at &func-open; time to permit Unix tool chains, programming a
device and then reading from it as if it was a plain file. Well
written V4L2 applications should always ensure they really get what
they want, requesting reasonable parameters and then checking if the
actual parameters are suitable.</para>
<para>To query the current raw VBI capture parameters
applications set the <structfield>type</structfield> field of a
&v4l2-format; to <constant>V4L2_BUF_TYPE_VBI_CAPTURE</constant> or
<constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant>, and call the
&VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill
the &v4l2-vbi-format; <structfield>vbi</structfield> member of the
<structfield>fmt</structfield> union.</para>
<para>To request different parameters applications set the
<structfield>type</structfield> field of a &v4l2-format; as above and
initialize all fields of the &v4l2-vbi-format;
<structfield>vbi</structfield> member of the
<structfield>fmt</structfield> union, or better just modify the
results of <constant>VIDIOC_G_FMT</constant>, and call the
&VIDIOC-S-FMT; ioctl with a pointer to this structure. Drivers return
an &EINVAL; only when the given parameters are ambiguous, otherwise
they modify the parameters according to the hardware capabilites and
return the actual parameters. When the driver allocates resources at
this point, it may return an &EBUSY; to indicate the returned
parameters are valid but the required resources are currently not
available. That may happen for instance when the video and VBI areas
to capture would overlap, or when the driver supports multiple opens
and another process already requested VBI capturing or output. Anyway,
applications must expect other resource allocation points which may
return <errorcode>EBUSY</errorcode>, at the &VIDIOC-STREAMON; ioctl
and the first read(), write() and select() call.</para>
<para>VBI devices must implement both the
<constant>VIDIOC_G_FMT</constant> and
<constant>VIDIOC_S_FMT</constant> ioctl, even if
<constant>VIDIOC_S_FMT</constant> ignores all requests and always
returns default parameters as <constant>VIDIOC_G_FMT</constant> does.
<constant>VIDIOC_TRY_FMT</constant> is optional.</para>
<table pgwide="1" frame="none" id="v4l2-vbi-format">
<title>struct <structname>v4l2_vbi_format</structname></title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>__u32</entry>
<entry><structfield>sampling_rate</structfield></entry>
<entry>Samples per second, i.&nbsp;e. unit 1 Hz.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>offset</structfield></entry>
<entry><para>Horizontal offset of the VBI image,
relative to the leading edge of the line synchronization pulse and
counted in samples: The first sample in the VBI image will be located
<structfield>offset</structfield> /
<structfield>sampling_rate</structfield> seconds following the leading
edge. See also <xref linkend="vbi-hsync" />.</para></entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>samples_per_line</structfield></entry>
<entry></entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>sample_format</structfield></entry>
<entry><para>Defines the sample format as in <xref
linkend="pixfmt" />, a four-character-code.<footnote>
<para>A few devices may be unable to
sample VBI data at all but can extend the video capture window to the
VBI region.</para>
</footnote> Usually this is
<constant>V4L2_PIX_FMT_GREY</constant>, i.&nbsp;e. each sample
consists of 8 bits with lower values oriented towards the black level.
Do not assume any other correlation of values with the signal level.
For example, the MSB does not necessarily indicate if the signal is
'high' or 'low' because 128 may not be the mean value of the
signal. Drivers shall not convert the sample format by software.</para></entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>start</structfield>[2]</entry>
<entry>This is the scanning system line number
associated with the first line of the VBI image, of the first and the
second field respectively. See <xref linkend="vbi-525" /> and
<xref linkend="vbi-625" /> for valid values. VBI input drivers can
return start values 0 if the hardware cannot reliable identify
scanning lines, VBI acquisition may not require this
information.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>count</structfield>[2]</entry>
<entry>The number of lines in the first and second
field image, respectively.</entry>
</row>
<row>
<entry spanname="hspan"><para>Drivers should be as
flexibility as possible. For example, it may be possible to extend or
move the VBI capture window down to the picture area, implementing a
'full field mode' to capture data service transmissions embedded in
the picture.</para><para>An application can set the first or second
<structfield>count</structfield> value to zero if no data is required
from the respective field; <structfield>count</structfield>[1] if the
scanning system is progressive, &ie; not interlaced. The
corresponding start value shall be ignored by the application and
driver. Anyway, drivers may not support single field capturing and
return both count values non-zero.</para><para>Both
<structfield>count</structfield> values set to zero, or line numbers
outside the bounds depicted in <xref linkend="vbi-525" /> and <xref
linkend="vbi-625" />, or a field image covering
lines of two fields, are invalid and shall not be returned by the
driver.</para><para>To initialize the <structfield>start</structfield>
and <structfield>count</structfield> fields, applications must first
determine the current video standard selection. The &v4l2-std-id; or
the <structfield>framelines</structfield> field of &v4l2-standard; can
be evaluated for this purpose.</para></entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>flags</structfield></entry>
<entry>See <xref linkend="vbifmt-flags" /> below. Currently
only drivers set flags, applications must set this field to
zero.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>reserved</structfield>[2]</entry>
<entry>This array is reserved for future extensions.
Drivers and applications must set it to zero.</entry>
</row>
</tbody>
</tgroup>
</table>
<table pgwide="1" frame="none" id="vbifmt-flags">
<title>Raw VBI Format Flags</title>
<tgroup cols="3">
&cs-def;
<tbody valign="top">
<row>
<entry><constant>V4L2_VBI_UNSYNC</constant></entry>
<entry>0x0001</entry>
<entry><para>This flag indicates hardware which does not
properly distinguish between fields. Normally the VBI image stores the
first field (lower scanning line numbers) first in memory. This may be
a top or bottom field depending on the video standard. When this flag
is set the first or second field may be stored first, however the
fields are still in correct temporal order with the older field first
in memory.<footnote>
<para>Most VBI services transmit on both fields, but
some have different semantics depending on the field number. These
cannot be reliable decoded or encoded when
<constant>V4L2_VBI_UNSYNC</constant> is set.</para>
</footnote></para></entry>
</row>
<row>
<entry><constant>V4L2_VBI_INTERLACED</constant></entry>
<entry>0x0002</entry>
<entry>By default the two field images will be passed
sequentially; all lines of the first field followed by all lines of
the second field (compare <xref linkend="field-order" />
<constant>V4L2_FIELD_SEQ_TB</constant> and
<constant>V4L2_FIELD_SEQ_BT</constant>, whether the top or bottom
field is first in memory depends on the video standard). When this
flag is set, the two fields are interlaced (cf.
<constant>V4L2_FIELD_INTERLACED</constant>). The first line of the
first field followed by the first line of the second field, then the
two second lines, and so on. Such a layout may be necessary when the
hardware has been programmed to capture or output interlaced video
images and is unable to separate the fields for VBI capturing at
the same time. For simplicity setting this flag implies that both
<structfield>count</structfield> values are equal and non-zero.</entry>
</row>
</tbody>
</tgroup>
</table>
<figure id="vbi-hsync">
<title>Line synchronization</title>
<mediaobject>
<imageobject>
<imagedata fileref="vbi_hsync.pdf" format="PS" />
</imageobject>
<imageobject>
<imagedata fileref="vbi_hsync.gif" format="GIF" />
</imageobject>
<textobject>
<phrase>Line synchronization diagram</phrase>
</textobject>
</mediaobject>
</figure>
<figure id="vbi-525">
<title>ITU-R 525 line numbering (M/NTSC and M/PAL)</title>
<mediaobject>
<imageobject>
<imagedata fileref="vbi_525.pdf" format="PS" />
</imageobject>
<imageobject>
<imagedata fileref="vbi_525.gif" format="GIF" />
</imageobject>
<textobject>
<phrase>NTSC field synchronization diagram</phrase>
</textobject>
<caption>
<para>(1) For the purpose of this specification field 2
starts in line 264 and not 263.5 because half line capturing is not
supported.</para>
</caption>
</mediaobject>
</figure>
<figure id="vbi-625">
<title>ITU-R 625 line numbering</title>
<mediaobject>
<imageobject>
<imagedata fileref="vbi_625.pdf" format="PS" />
</imageobject>
<imageobject>
<imagedata fileref="vbi_625.gif" format="GIF" />
</imageobject>
<textobject>
<phrase>PAL/SECAM field synchronization diagram</phrase>
</textobject>
<caption>
<para>(1) For the purpose of this specification field 2
starts in line 314 and not 313.5 because half line capturing is not
supported.</para>
</caption>
</mediaobject>
</figure>
<para>Remember the VBI image format depends on the selected
video standard, therefore the application must choose a new standard or
query the current standard first. Attempts to read or write data ahead
of format negotiation, or after switching the video standard which may
invalidate the negotiated VBI parameters, should be refused by the
driver. A format change during active I/O is not permitted.</para>
</section>
<section>
<title>Reading and writing VBI images</title>
<para>To assure synchronization with the field number and easier
implementation, the smallest unit of data passed at a time is one
frame, consisting of two fields of VBI images immediately following in
memory.</para>
<para>The total size of a frame computes as follows:</para>
<programlisting>
(<structfield>count</structfield>[0] + <structfield>count</structfield>[1]) *
<structfield>samples_per_line</structfield> * sample size in bytes</programlisting>
<para>The sample size is most likely always one byte,
applications must check the <structfield>sample_format</structfield>
field though, to function properly with other drivers.</para>
<para>A VBI device may support <link
linkend="rw">read/write</link> and/or streaming (<link
linkend="mmap">memory mapping</link> or <link
linkend="userp">user pointer</link>) I/O. The latter bears the
possibility of synchronizing video and
VBI data by using buffer timestamps.</para>
<para>Remember the &VIDIOC-STREAMON; ioctl and the first read(),
write() and select() call can be resource allocation points returning
an &EBUSY; if the required hardware resources are temporarily
unavailable, for example the device is already in use by another
process.</para>
</section>
kernel/Documentation/DocBook/media/v4l/dev-rds.xml
+196
View File
@@ -0,0 +1,196 @@
<title>RDS Interface</title>
<para>The Radio Data System transmits supplementary
information in binary format, for example the station name or travel
information, on an inaudible audio subcarrier of a radio program. This
interface is aimed at devices capable of receiving and/or transmitting RDS
information.</para>
<para>For more information see the core RDS standard <xref linkend="en50067" />
and the RBDS standard <xref linkend="nrsc4" />.</para>
<para>Note that the RBDS standard as is used in the USA is almost identical
to the RDS standard. Any RDS decoder/encoder can also handle RBDS. Only some of the
fields have slightly different meanings. See the RBDS standard for more
information.</para>
<para>The RBDS standard also specifies support for MMBS (Modified Mobile Search).
This is a proprietary format which seems to be discontinued. The RDS interface does not
support this format. Should support for MMBS (or the so-called 'E blocks' in general)
be needed, then please contact the linux-media mailing list: &v4l-ml;.</para>
<section>
<title>Querying Capabilities</title>
<para>Devices supporting the RDS capturing API set
the <constant>V4L2_CAP_RDS_CAPTURE</constant> flag in
the <structfield>capabilities</structfield> field of &v4l2-capability;
returned by the &VIDIOC-QUERYCAP; ioctl. Any tuner that supports RDS
will set the <constant>V4L2_TUNER_CAP_RDS</constant> flag in
the <structfield>capability</structfield> field of &v4l2-tuner;. If
the driver only passes RDS blocks without interpreting the data
the <constant>V4L2_TUNER_CAP_RDS_BLOCK_IO</constant> flag has to be
set, see <link linkend="reading-rds-data">Reading RDS data</link>.
For future use the
flag <constant>V4L2_TUNER_CAP_RDS_CONTROLS</constant> has also been
defined. However, a driver for a radio tuner with this capability does
not yet exist, so if you are planning to write such a driver you
should discuss this on the linux-media mailing list: &v4l-ml;.</para>
<para> Whether an RDS signal is present can be detected by looking
at the <structfield>rxsubchans</structfield> field of &v4l2-tuner;:
the <constant>V4L2_TUNER_SUB_RDS</constant> will be set if RDS data
was detected.</para>
<para>Devices supporting the RDS output API
set the <constant>V4L2_CAP_RDS_OUTPUT</constant> flag in
the <structfield>capabilities</structfield> field of &v4l2-capability;
returned by the &VIDIOC-QUERYCAP; ioctl.
Any modulator that supports RDS will set the
<constant>V4L2_TUNER_CAP_RDS</constant> flag in the <structfield>capability</structfield>
field of &v4l2-modulator;.
In order to enable the RDS transmission one must set the <constant>V4L2_TUNER_SUB_RDS</constant>
bit in the <structfield>txsubchans</structfield> field of &v4l2-modulator;.
If the driver only passes RDS blocks without interpreting the data
the <constant>V4L2_TUNER_CAP_RDS_BLOCK_IO</constant> flag has to be set. If the
tuner is capable of handling RDS entities like program identification codes and radio
text, the flag <constant>V4L2_TUNER_CAP_RDS_CONTROLS</constant> should be set,
see <link linkend="writing-rds-data">Writing RDS data</link> and
<link linkend="fm-tx-controls">FM Transmitter Control Reference</link>.</para>
</section>
<section id="reading-rds-data">
<title>Reading RDS data</title>
<para>RDS data can be read from the radio device
with the &func-read; function. The data is packed in groups of three bytes.</para>
</section>
<section id="writing-rds-data">
<title>Writing RDS data</title>
<para>RDS data can be written to the radio device
with the &func-write; function. The data is packed in groups of three bytes,
as follows:</para>
</section>
<section>
<title>RDS datastructures</title>
<table frame="none" pgwide="1" id="v4l2-rds-data">
<title>struct
<structname>v4l2_rds_data</structname></title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" />
<colspec colname="c2" colwidth="1*" />
<colspec colname="c3" colwidth="5*" />
<tbody valign="top">
<row>
<entry>__u8</entry>
<entry><structfield>lsb</structfield></entry>
<entry>Least Significant Byte of RDS Block</entry>
</row>
<row>
<entry>__u8</entry>
<entry><structfield>msb</structfield></entry>
<entry>Most Significant Byte of RDS Block</entry>
</row>
<row>
<entry>__u8</entry>
<entry><structfield>block</structfield></entry>
<entry>Block description</entry>
</row>
</tbody>
</tgroup>
</table>
<table frame="none" pgwide="1" id="v4l2-rds-block">
<title>Block description</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="1*" />
<colspec colname="c2" colwidth="5*" />
<tbody valign="top">
<row>
<entry>Bits 0-2</entry>
<entry>Block (aka offset) of the received data.</entry>
</row>
<row>
<entry>Bits 3-5</entry>
<entry>Deprecated. Currently identical to bits 0-2. Do not use these bits.</entry>
</row>
<row>
<entry>Bit 6</entry>
<entry>Corrected bit. Indicates that an error was corrected for this data block.</entry>
</row>
<row>
<entry>Bit 7</entry>
<entry>Error bit. Indicates that an uncorrectable error occurred during reception of this block.</entry>
</row>
</tbody>
</tgroup>
</table>
<table frame="none" pgwide="1" id="v4l2-rds-block-codes">
<title>Block defines</title>
<tgroup cols="4">
<colspec colname="c1" colwidth="1*" />
<colspec colname="c2" colwidth="1*" />
<colspec colname="c3" colwidth="1*" />
<colspec colname="c4" colwidth="5*" />
<tbody valign="top">
<row>
<entry>V4L2_RDS_BLOCK_MSK</entry>
<entry> </entry>
<entry>7</entry>
<entry>Mask for bits 0-2 to get the block ID.</entry>
</row>
<row>
<entry>V4L2_RDS_BLOCK_A</entry>
<entry> </entry>
<entry>0</entry>
<entry>Block A.</entry>
</row>
<row>
<entry>V4L2_RDS_BLOCK_B</entry>
<entry> </entry>
<entry>1</entry>
<entry>Block B.</entry>
</row>
<row>
<entry>V4L2_RDS_BLOCK_C</entry>
<entry> </entry>
<entry>2</entry>
<entry>Block C.</entry>
</row>
<row>
<entry>V4L2_RDS_BLOCK_D</entry>
<entry> </entry>
<entry>3</entry>
<entry>Block D.</entry>
</row>
<row>
<entry>V4L2_RDS_BLOCK_C_ALT</entry>
<entry> </entry>
<entry>4</entry>
<entry>Block C'.</entry>
</row>
<row>
<entry>V4L2_RDS_BLOCK_INVALID</entry>
<entry>read-only</entry>
<entry>7</entry>
<entry>An invalid block.</entry>
</row>
<row>
<entry>V4L2_RDS_BLOCK_CORRECTED</entry>
<entry>read-only</entry>
<entry>0x40</entry>
<entry>A bit error was detected but corrected.</entry>
</row>
<row>
<entry>V4L2_RDS_BLOCK_ERROR</entry>
<entry>read-only</entry>
<entry>0x80</entry>
<entry>An uncorrectable error occurred.</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
kernel/Documentation/DocBook/media/v4l/dev-sliced-vbi.xml
+699
View File
@@ -0,0 +1,699 @@
<title>Sliced VBI Data Interface</title>
<para>VBI stands for Vertical Blanking Interval, a gap in the
sequence of lines of an analog video signal. During VBI no picture
information is transmitted, allowing some time while the electron beam
of a cathode ray tube TV returns to the top of the screen.</para>
<para>Sliced VBI devices use hardware to demodulate data transmitted
in the VBI. V4L2 drivers shall <emphasis>not</emphasis> do this by
software, see also the <link linkend="raw-vbi">raw VBI
interface</link>. The data is passed as short packets of fixed size,
covering one scan line each. The number of packets per video frame is
variable.</para>
<para>Sliced VBI capture and output devices are accessed through the
same character special files as raw VBI devices. When a driver
supports both interfaces, the default function of a
<filename>/dev/vbi</filename> device is <emphasis>raw</emphasis> VBI
capturing or output, and the sliced VBI function is only available
after calling the &VIDIOC-S-FMT; ioctl as defined below. Likewise a
<filename>/dev/video</filename> device may support the sliced VBI API,
however the default function here is video capturing or output.
Different file descriptors must be used to pass raw and sliced VBI
data simultaneously, if this is supported by the driver.</para>
<section>
<title>Querying Capabilities</title>
<para>Devices supporting the sliced VBI capturing or output API
set the <constant>V4L2_CAP_SLICED_VBI_CAPTURE</constant> or
<constant>V4L2_CAP_SLICED_VBI_OUTPUT</constant> flag respectively, in
the <structfield>capabilities</structfield> field of &v4l2-capability;
returned by the &VIDIOC-QUERYCAP; ioctl. At least one of the
read/write, streaming or asynchronous <link linkend="io">I/O
methods</link> must be supported. Sliced VBI devices may have a tuner
or modulator.</para>
</section>
<section>
<title>Supplemental Functions</title>
<para>Sliced VBI devices shall support <link linkend="video">video
input or output</link> and <link linkend="tuner">tuner or
modulator</link> ioctls if they have these capabilities, and they may
support <link linkend="control">control</link> ioctls. The <link
linkend="standard">video standard</link> ioctls provide information
vital to program a sliced VBI device, therefore must be
supported.</para>
</section>
<section id="sliced-vbi-format-negotitation">
<title>Sliced VBI Format Negotiation</title>
<para>To find out which data services are supported by the
hardware applications can call the &VIDIOC-G-SLICED-VBI-CAP; ioctl.
All drivers implementing the sliced VBI interface must support this
ioctl. The results may differ from those of the &VIDIOC-S-FMT; ioctl
when the number of VBI lines the hardware can capture or output per
frame, or the number of services it can identify on a given line are
limited. For example on PAL line 16 the hardware may be able to look
for a VPS or Teletext signal, but not both at the same time.</para>
<para>To determine the currently selected services applications
set the <structfield>type </structfield> field of &v4l2-format; to
<constant> V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant> or <constant>
V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant>, and the &VIDIOC-G-FMT;
ioctl fills the <structfield>fmt.sliced</structfield> member, a
&v4l2-sliced-vbi-format;.</para>
<para>Applications can request different parameters by
initializing or modifying the <structfield>fmt.sliced</structfield>
member and calling the &VIDIOC-S-FMT; ioctl with a pointer to the
<structname>v4l2_format</structname> structure.</para>
<para>The sliced VBI API is more complicated than the raw VBI API
because the hardware must be told which VBI service to expect on each
scan line. Not all services may be supported by the hardware on all
lines (this is especially true for VBI output where Teletext is often
unsupported and other services can only be inserted in one specific
line). In many cases, however, it is sufficient to just set the
<structfield>service_set</structfield> field to the required services
and let the driver fill the <structfield>service_lines</structfield>
array according to hardware capabilities. Only if more precise control
is needed should the programmer set the
<structfield>service_lines</structfield> array explicitly.</para>
<para>The &VIDIOC-S-FMT; ioctl modifies the parameters
according to hardware capabilities. When the driver allocates
resources at this point, it may return an &EBUSY; if the required
resources are temporarily unavailable. Other resource allocation
points which may return <errorcode>EBUSY</errorcode> can be the
&VIDIOC-STREAMON; ioctl and the first &func-read;, &func-write; and
&func-select; call.</para>
<table frame="none" pgwide="1" id="v4l2-sliced-vbi-format">
<title>struct
<structname>v4l2_sliced_vbi_format</structname></title>
<tgroup cols="5">
<colspec colname="c1" colwidth="3*" />
<colspec colname="c2" colwidth="3*" />
<colspec colname="c3" colwidth="2*" />
<colspec colname="c4" colwidth="2*" />
<colspec colname="c5" colwidth="2*" />
<spanspec namest="c3" nameend="c5" spanname="hspan" />
<tbody valign="top">
<row>
<entry>__u32</entry>
<entry><structfield>service_set</structfield></entry>
<entry spanname="hspan"><para>If
<structfield>service_set</structfield> is non-zero when passed with
&VIDIOC-S-FMT; or &VIDIOC-TRY-FMT;, the
<structfield>service_lines</structfield> array will be filled by the
driver according to the services specified in this field. For example,
if <structfield>service_set</structfield> is initialized with
<constant>V4L2_SLICED_TELETEXT_B | V4L2_SLICED_WSS_625</constant>, a
driver for the cx25840 video decoder sets lines 7-22 of both
fields<footnote><para>According to <link
linkend="ets300706">ETS&nbsp;300&nbsp;706</link> lines 6-22 of the
first field and lines 5-22 of the second field may carry Teletext
data.</para></footnote> to <constant>V4L2_SLICED_TELETEXT_B</constant>
and line 23 of the first field to
<constant>V4L2_SLICED_WSS_625</constant>. If
<structfield>service_set</structfield> is set to zero, then the values
of <structfield>service_lines</structfield> will be used instead.
</para><para>On return the driver sets this field to the union of all
elements of the returned <structfield>service_lines</structfield>
array. It may contain less services than requested, perhaps just one,
if the hardware cannot handle more services simultaneously. It may be
empty (zero) if none of the requested services are supported by the
hardware.</para></entry>
</row>
<row>
<entry>__u16</entry>
<entry><structfield>service_lines</structfield>[2][24]</entry>
<entry spanname="hspan"><para>Applications initialize this
array with sets of data services the driver shall look for or insert
on the respective scan line. Subject to hardware capabilities drivers
return the requested set, a subset, which may be just a single
service, or an empty set. When the hardware cannot handle multiple
services on the same line the driver shall choose one. No assumptions
can be made on which service the driver chooses.</para><para>Data
services are defined in <xref linkend="vbi-services2" />. Array indices
map to ITU-R line numbers (see also <xref linkend="vbi-525" /> and <xref
linkend="vbi-625" />) as follows: <!-- No nested
tables, sigh. --></para></entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry>Element</entry>
<entry>525 line systems</entry>
<entry>625 line systems</entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry><structfield>service_lines</structfield>[0][1]</entry>
<entry align="center">1</entry>
<entry align="center">1</entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry><structfield>service_lines</structfield>[0][23]</entry>
<entry align="center">23</entry>
<entry align="center">23</entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry><structfield>service_lines</structfield>[1][1]</entry>
<entry align="center">264</entry>
<entry align="center">314</entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry><structfield>service_lines</structfield>[1][23]</entry>
<entry align="center">286</entry>
<entry align="center">336</entry>
</row>
<!-- End of line numbers table. -->
<row>
<entry></entry>
<entry></entry>
<entry spanname="hspan">Drivers must set
<structfield>service_lines</structfield>[0][0] and
<structfield>service_lines</structfield>[1][0] to zero.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>io_size</structfield></entry>
<entry spanname="hspan">Maximum number of bytes passed by
one &func-read; or &func-write; call, and the buffer size in bytes for
the &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl. Drivers set this field to
the size of &v4l2-sliced-vbi-data; times the number of non-zero
elements in the returned <structfield>service_lines</structfield>
array (that is the number of lines potentially carrying data).</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>reserved</structfield>[2]</entry>
<entry spanname="hspan">This array is reserved for future
extensions. Applications and drivers must set it to zero.</entry>
</row>
</tbody>
</tgroup>
</table>
<!-- See also vidioc-g-sliced-vbi-cap.sgml -->
<table frame="none" pgwide="1" id="vbi-services2">
<title>Sliced VBI services</title>
<tgroup cols="5">
<colspec colname="c1" colwidth="2*" />
<colspec colname="c2" colwidth="1*" />
<colspec colname="c3" colwidth="1*" />
<colspec colname="c4" colwidth="2*" />
<colspec colname="c5" colwidth="2*" />
<spanspec namest="c3" nameend="c5" spanname="rlp" />
<thead>
<row>
<entry>Symbol</entry>
<entry>Value</entry>
<entry>Reference</entry>
<entry>Lines, usually</entry>
<entry>Payload</entry>
</row>
</thead>
<tbody valign="top">
<row>
<entry><constant>V4L2_SLICED_TELETEXT_B</constant>
(Teletext System B)</entry>
<entry>0x0001</entry>
<entry><xref linkend="ets300706" />, <xref linkend="itu653" /></entry>
<entry>PAL/SECAM line 7-22, 320-335 (second field 7-22)</entry>
<entry>Last 42 of the 45 byte Teletext packet, that is
without clock run-in and framing code, lsb first transmitted.</entry>
</row>
<row>
<entry><constant>V4L2_SLICED_VPS</constant></entry>
<entry>0x0400</entry>
<entry><xref linkend="ets300231" /></entry>
<entry>PAL line 16</entry>
<entry>Byte number 3 to 15 according to Figure 9 of
ETS&nbsp;300&nbsp;231, lsb first transmitted.</entry>
</row>
<row>
<entry><constant>V4L2_SLICED_CAPTION_525</constant></entry>
<entry>0x1000</entry>
<entry><xref linkend="eia608" /></entry>
<entry>NTSC line 21, 284 (second field 21)</entry>
<entry>Two bytes in transmission order, including parity
bit, lsb first transmitted.</entry>
</row>
<row>
<entry><constant>V4L2_SLICED_WSS_625</constant></entry>
<entry>0x4000</entry>
<entry><xref linkend="itu1119" />, <xref linkend="en300294" /></entry>
<entry>PAL/SECAM line 23</entry>
<entry><screen>
Byte 0 1
msb lsb msb lsb
Bit 7 6 5 4 3 2 1 0 x x 13 12 11 10 9
</screen></entry>
</row>
<row>
<entry><constant>V4L2_SLICED_VBI_525</constant></entry>
<entry>0x1000</entry>
<entry spanname="rlp">Set of services applicable to 525
line systems.</entry>
</row>
<row>
<entry><constant>V4L2_SLICED_VBI_625</constant></entry>
<entry>0x4401</entry>
<entry spanname="rlp">Set of services applicable to 625
line systems.</entry>
</row>
</tbody>
</tgroup>
</table>
<para>Drivers may return an &EINVAL; when applications attempt to
read or write data without prior format negotiation, after switching
the video standard (which may invalidate the negotiated VBI
parameters) and after switching the video input (which may change the
video standard as a side effect). The &VIDIOC-S-FMT; ioctl may return
an &EBUSY; when applications attempt to change the format while i/o is
in progress (between a &VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; call,
and after the first &func-read; or &func-write; call).</para>
</section>
<section>
<title>Reading and writing sliced VBI data</title>
<para>A single &func-read; or &func-write; call must pass all data
belonging to one video frame. That is an array of
<structname>v4l2_sliced_vbi_data</structname> structures with one or
more elements and a total size not exceeding
<structfield>io_size</structfield> bytes. Likewise in streaming I/O
mode one buffer of <structfield>io_size</structfield> bytes must
contain data of one video frame. The <structfield>id</structfield> of
unused <structname>v4l2_sliced_vbi_data</structname> elements must be
zero.</para>
<table frame="none" pgwide="1" id="v4l2-sliced-vbi-data">
<title>struct
<structname>v4l2_sliced_vbi_data</structname></title>
<tgroup cols="3">
&cs-def;
<tbody valign="top">
<row>
<entry>__u32</entry>
<entry><structfield>id</structfield></entry>
<entry>A flag from <xref linkend="vbi-services" />
identifying the type of data in this packet. Only a single bit must be
set. When the <structfield>id</structfield> of a captured packet is
zero, the packet is empty and the contents of other fields are
undefined. Applications shall ignore empty packets. When the
<structfield>id</structfield> of a packet for output is zero the
contents of the <structfield>data</structfield> field are undefined
and the driver must no longer insert data on the requested
<structfield>field</structfield> and
<structfield>line</structfield>.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>field</structfield></entry>
<entry>The video field number this data has been captured
from, or shall be inserted at. <constant>0</constant> for the first
field, <constant>1</constant> for the second field.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>line</structfield></entry>
<entry>The field (as opposed to frame) line number this
data has been captured from, or shall be inserted at. See <xref
linkend="vbi-525" /> and <xref linkend="vbi-625" /> for valid
values. Sliced VBI capture devices can set the line number of all
packets to <constant>0</constant> if the hardware cannot reliably
identify scan lines. The field number must always be valid.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>reserved</structfield></entry>
<entry>This field is reserved for future extensions.
Applications and drivers must set it to zero.</entry>
</row>
<row>
<entry>__u8</entry>
<entry><structfield>data</structfield>[48]</entry>
<entry>The packet payload. See <xref
linkend="vbi-services" /> for the contents and number of
bytes passed for each data type. The contents of padding bytes at the
end of this array are undefined, drivers and applications shall ignore
them.</entry>
</row>
</tbody>
</tgroup>
</table>
<para>Packets are always passed in ascending line number order,
without duplicate line numbers. The &func-write; function and the
&VIDIOC-QBUF; ioctl must return an &EINVAL; when applications violate
this rule. They must also return an &EINVAL; when applications pass an
incorrect field or line number, or a combination of
<structfield>field</structfield>, <structfield>line</structfield> and
<structfield>id</structfield> which has not been negotiated with the
&VIDIOC-G-FMT; or &VIDIOC-S-FMT; ioctl. When the line numbers are
unknown the driver must pass the packets in transmitted order. The
driver can insert empty packets with <structfield>id</structfield> set
to zero anywhere in the packet array.</para>
<para>To assure synchronization and to distinguish from frame
dropping, when a captured frame does not carry any of the requested
data services drivers must pass one or more empty packets. When an
application fails to pass VBI data in time for output, the driver
must output the last VPS and WSS packet again, and disable the output
of Closed Caption and Teletext data, or output data which is ignored
by Closed Caption and Teletext decoders.</para>
<para>A sliced VBI device may support <link
linkend="rw">read/write</link> and/or streaming (<link
linkend="mmap">memory mapping</link> and/or <link linkend="userp">user
pointer</link>) I/O. The latter bears the possibility of synchronizing
video and VBI data by using buffer timestamps.</para>
</section>
<section>
<title>Sliced VBI Data in MPEG Streams</title>
<para>If a device can produce an MPEG output stream, it may be
capable of providing <link
linkend="sliced-vbi-format-negotitation">negotiated sliced VBI
services</link> as data embedded in the MPEG stream. Users or
applications control this sliced VBI data insertion with the <link
linkend="v4l2-mpeg-stream-vbi-fmt">V4L2_CID_MPEG_STREAM_VBI_FMT</link>
control.</para>
<para>If the driver does not provide the <link
linkend="v4l2-mpeg-stream-vbi-fmt">V4L2_CID_MPEG_STREAM_VBI_FMT</link>
control, or only allows that control to be set to <link
linkend="v4l2-mpeg-stream-vbi-fmt"><constant>
V4L2_MPEG_STREAM_VBI_FMT_NONE</constant></link>, then the device
cannot embed sliced VBI data in the MPEG stream.</para>
<para>The <link linkend="v4l2-mpeg-stream-vbi-fmt">
V4L2_CID_MPEG_STREAM_VBI_FMT</link> control does not implicitly set
the device driver to capture nor cease capturing sliced VBI data. The
control only indicates to embed sliced VBI data in the MPEG stream, if
an application has negotiated sliced VBI service be captured.</para>
<para>It may also be the case that a device can embed sliced VBI
data in only certain types of MPEG streams: for example in an MPEG-2
PS but not an MPEG-2 TS. In this situation, if sliced VBI data
insertion is requested, the sliced VBI data will be embedded in MPEG
stream types when supported, and silently omitted from MPEG stream
types where sliced VBI data insertion is not supported by the device.
</para>
<para>The following subsections specify the format of the
embedded sliced VBI data.</para>
<section>
<title>MPEG Stream Embedded, Sliced VBI Data Format: NONE</title>
<para>The <link linkend="v4l2-mpeg-stream-vbi-fmt"><constant>
V4L2_MPEG_STREAM_VBI_FMT_NONE</constant></link> embedded sliced VBI
format shall be interpreted by drivers as a control to cease
embedding sliced VBI data in MPEG streams. Neither the device nor
driver shall insert "empty" embedded sliced VBI data packets in the
MPEG stream when this format is set. No MPEG stream data structures
are specified for this format.</para>
</section>
<section>
<title>MPEG Stream Embedded, Sliced VBI Data Format: IVTV</title>
<para>The <link linkend="v4l2-mpeg-stream-vbi-fmt"><constant>
V4L2_MPEG_STREAM_VBI_FMT_IVTV</constant></link> embedded sliced VBI
format, when supported, indicates to the driver to embed up to 36
lines of sliced VBI data per frame in an MPEG-2 <emphasis>Private
Stream 1 PES</emphasis> packet encapsulated in an MPEG-2 <emphasis>
Program Pack</emphasis> in the MPEG stream.</para>
<para><emphasis>Historical context</emphasis>: This format
specification originates from a custom, embedded, sliced VBI data
format used by the <filename>ivtv</filename> driver. This format
has already been informally specified in the kernel sources in the
file <filename>Documentation/video4linux/cx2341x/README.vbi</filename>
. The maximum size of the payload and other aspects of this format
are driven by the CX23415 MPEG decoder's capabilities and limitations
with respect to extracting, decoding, and displaying sliced VBI data
embedded within an MPEG stream.</para>
<para>This format's use is <emphasis>not</emphasis> exclusive to
the <filename>ivtv</filename> driver <emphasis>nor</emphasis>
exclusive to CX2341x devices, as the sliced VBI data packet insertion
into the MPEG stream is implemented in driver software. At least the
<filename>cx18</filename> driver provides sliced VBI data insertion
into an MPEG-2 PS in this format as well.</para>
<para>The following definitions specify the payload of the
MPEG-2 <emphasis>Private Stream 1 PES</emphasis> packets that contain
sliced VBI data when <link linkend="v4l2-mpeg-stream-vbi-fmt">
<constant>V4L2_MPEG_STREAM_VBI_FMT_IVTV</constant></link> is set.
(The MPEG-2 <emphasis>Private Stream 1 PES</emphasis> packet header
and encapsulating MPEG-2 <emphasis>Program Pack</emphasis> header are
not detailed here. Please refer to the MPEG-2 specifications for
details on those packet headers.)</para>
<para>The payload of the MPEG-2 <emphasis>Private Stream 1 PES
</emphasis> packets that contain sliced VBI data is specified by
&v4l2-mpeg-vbi-fmt-ivtv;. The payload is variable
length, depending on the actual number of lines of sliced VBI data
present in a video frame. The payload may be padded at the end with
unspecified fill bytes to align the end of the payload to a 4-byte
boundary. The payload shall never exceed 1552 bytes (2 fields with
18 lines/field with 43 bytes of data/line and a 4 byte magic number).
</para>
<table frame="none" pgwide="1" id="v4l2-mpeg-vbi-fmt-ivtv">
<title>struct <structname>v4l2_mpeg_vbi_fmt_ivtv</structname>
</title>
<tgroup cols="4">
&cs-ustr;
<tbody valign="top">
<row>
<entry>__u8</entry>
<entry><structfield>magic</structfield>[4]</entry>
<entry></entry>
<entry>A "magic" constant from <xref
linkend="v4l2-mpeg-vbi-fmt-ivtv-magic" /> that indicates
this is a valid sliced VBI data payload and also indicates which
member of the anonymous union, <structfield>itv0</structfield> or
<structfield>ITV0</structfield>, to use for the payload data.</entry>
</row>
<row>
<entry>union</entry>
<entry>(anonymous)</entry>
</row>
<row>
<entry></entry>
<entry>struct <link linkend="v4l2-mpeg-vbi-itv0">
<structname>v4l2_mpeg_vbi_itv0</structname></link>
</entry>
<entry><structfield>itv0</structfield></entry>
<entry>The primary form of the sliced VBI data payload
that contains anywhere from 1 to 35 lines of sliced VBI data.
Line masks are provided in this form of the payload indicating
which VBI lines are provided.</entry>
</row>
<row>
<entry></entry>
<entry>struct <link linkend="v4l2-mpeg-vbi-itv0-1">
<structname>v4l2_mpeg_vbi_ITV0</structname></link>
</entry>
<entry><structfield>ITV0</structfield></entry>
<entry>An alternate form of the sliced VBI data payload
used when 36 lines of sliced VBI data are present. No line masks are
provided in this form of the payload; all valid line mask bits are
implcitly set.</entry>
</row>
</tbody>
</tgroup>
</table>
<table frame="none" pgwide="1" id="v4l2-mpeg-vbi-fmt-ivtv-magic">
<title>Magic Constants for &v4l2-mpeg-vbi-fmt-ivtv;
<structfield>magic</structfield> field</title>
<tgroup cols="3">
&cs-def;
<thead>
<row>
<entry align="left">Defined Symbol</entry>
<entry align="left">Value</entry>
<entry align="left">Description</entry>
</row>
</thead>
<tbody valign="top">
<row>
<entry><constant>V4L2_MPEG_VBI_IVTV_MAGIC0</constant>
</entry>
<entry>"itv0"</entry>
<entry>Indicates the <structfield>itv0</structfield>
member of the union in &v4l2-mpeg-vbi-fmt-ivtv; is valid.</entry>
</row>
<row>
<entry><constant>V4L2_MPEG_VBI_IVTV_MAGIC1</constant>
</entry>
<entry>"ITV0"</entry>
<entry>Indicates the <structfield>ITV0</structfield>
member of the union in &v4l2-mpeg-vbi-fmt-ivtv; is valid and
that 36 lines of sliced VBI data are present.</entry>
</row>
</tbody>
</tgroup>
</table>
<table frame="none" pgwide="1" id="v4l2-mpeg-vbi-itv0">
<title>struct <structname>v4l2_mpeg_vbi_itv0</structname>
</title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>__le32</entry>
<entry><structfield>linemask</structfield>[2]</entry>
<entry><para>Bitmasks indicating the VBI service lines
present. These <structfield>linemask</structfield> values are stored
in little endian byte order in the MPEG stream. Some reference
<structfield>linemask</structfield> bit positions with their
corresponding VBI line number and video field are given below.
b<subscript>0</subscript> indicates the least significant bit of a
<structfield>linemask</structfield> value:<screen>
<structfield>linemask</structfield>[0] b<subscript>0</subscript>: line 6 first field
<structfield>linemask</structfield>[0] b<subscript>17</subscript>: line 23 first field
<structfield>linemask</structfield>[0] b<subscript>18</subscript>: line 6 second field
<structfield>linemask</structfield>[0] b<subscript>31</subscript>: line 19 second field
<structfield>linemask</structfield>[1] b<subscript>0</subscript>: line 20 second field
<structfield>linemask</structfield>[1] b<subscript>3</subscript>: line 23 second field
<structfield>linemask</structfield>[1] b<subscript>4</subscript>-b<subscript>31</subscript>: unused and set to 0</screen></para></entry>
</row>
<row>
<entry>struct <link linkend="v4l2-mpeg-vbi-itv0-line">
<structname>v4l2_mpeg_vbi_itv0_line</structname></link>
</entry>
<entry><structfield>line</structfield>[35]</entry>
<entry>This is a variable length array that holds from 1
to 35 lines of sliced VBI data. The sliced VBI data lines present
correspond to the bits set in the <structfield>linemask</structfield>
array, starting from b<subscript>0</subscript> of <structfield>
linemask</structfield>[0] up through b<subscript>31</subscript> of
<structfield>linemask</structfield>[0], and from b<subscript>0
</subscript> of <structfield>linemask</structfield>[1] up through b
<subscript>3</subscript> of <structfield>linemask</structfield>[1].
<structfield>line</structfield>[0] corresponds to the first bit
found set in the <structfield>linemask</structfield> array,
<structfield>line</structfield>[1] corresponds to the second bit
found set in the <structfield>linemask</structfield> array, etc.
If no <structfield>linemask</structfield> array bits are set, then
<structfield>line</structfield>[0] may contain one line of
unspecified data that should be ignored by applications.</entry>
</row>
</tbody>
</tgroup>
</table>
<table frame="none" pgwide="1" id="v4l2-mpeg-vbi-itv0-1">
<title>struct <structname>v4l2_mpeg_vbi_ITV0</structname>
</title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>struct <link linkend="v4l2-mpeg-vbi-itv0-line">
<structname>v4l2_mpeg_vbi_itv0_line</structname></link>
</entry>
<entry><structfield>line</structfield>[36]</entry>
<entry>A fixed length array of 36 lines of sliced VBI
data. <structfield>line</structfield>[0] through <structfield>line
</structfield>[17] correspond to lines 6 through 23 of the
first field. <structfield>line</structfield>[18] through
<structfield>line</structfield>[35] corresponds to lines 6
through 23 of the second field.</entry>
</row>
</tbody>
</tgroup>
</table>
<table frame="none" pgwide="1" id="v4l2-mpeg-vbi-itv0-line">
<title>struct <structname>v4l2_mpeg_vbi_itv0_line</structname>
</title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>__u8</entry>
<entry><structfield>id</structfield></entry>
<entry>A line identifier value from
<xref linkend="ITV0-Line-Identifier-Constants" /> that indicates
the type of sliced VBI data stored on this line.</entry>
</row>
<row>
<entry>__u8</entry>
<entry><structfield>data</structfield>[42]</entry>
<entry>The sliced VBI data for the line.</entry>
</row>
</tbody>
</tgroup>
</table>
<table frame="none" pgwide="1" id="ITV0-Line-Identifier-Constants">
<title>Line Identifiers for struct <link
linkend="v4l2-mpeg-vbi-itv0-line"><structname>
v4l2_mpeg_vbi_itv0_line</structname></link> <structfield>id
</structfield> field</title>
<tgroup cols="3">
&cs-def;
<thead>
<row>
<entry align="left">Defined Symbol</entry>
<entry align="left">Value</entry>
<entry align="left">Description</entry>
</row>
</thead>
<tbody valign="top">
<row>
<entry><constant>V4L2_MPEG_VBI_IVTV_TELETEXT_B</constant>
</entry>
<entry>1</entry>
<entry>Refer to <link linkend="vbi-services2">
Sliced VBI services</link> for a description of the line payload.</entry>
</row>
<row>
<entry><constant>V4L2_MPEG_VBI_IVTV_CAPTION_525</constant>
</entry>
<entry>4</entry>
<entry>Refer to <link linkend="vbi-services2">
Sliced VBI services</link> for a description of the line payload.</entry>
</row>
<row>
<entry><constant>V4L2_MPEG_VBI_IVTV_WSS_625</constant>
</entry>
<entry>5</entry>
<entry>Refer to <link linkend="vbi-services2">
Sliced VBI services</link> for a description of the line payload.</entry>
</row>
<row>
<entry><constant>V4L2_MPEG_VBI_IVTV_VPS</constant>
</entry>
<entry>7</entry>
<entry>Refer to <link linkend="vbi-services2">
Sliced VBI services</link> for a description of the line payload.</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
</section>
kernel/Documentation/DocBook/media/v4l/dev-subdev.xml
+313
View File
@@ -0,0 +1,313 @@
<title>Sub-device Interface</title>
<note>
<title>Experimental</title>
<para>This is an <link linkend="experimental">experimental</link>
interface and may change in the future.</para>
</note>
<para>The complex nature of V4L2 devices, where hardware is often made of
several integrated circuits that need to interact with each other in a
controlled way, leads to complex V4L2 drivers. The drivers usually reflect
the hardware model in software, and model the different hardware components
as software blocks called sub-devices.</para>
<para>V4L2 sub-devices are usually kernel-only objects. If the V4L2 driver
implements the media device API, they will automatically inherit from media
entities. Applications will be able to enumerate the sub-devices and discover
the hardware topology using the media entities, pads and links enumeration
API.</para>
<para>In addition to make sub-devices discoverable, drivers can also choose
to make them directly configurable by applications. When both the sub-device
driver and the V4L2 device driver support this, sub-devices will feature a
character device node on which ioctls can be called to
<itemizedlist>
<listitem><para>query, read and write sub-devices controls</para></listitem>
<listitem><para>subscribe and unsubscribe to events and retrieve them</para></listitem>
<listitem><para>negotiate image formats on individual pads</para></listitem>
</itemizedlist>
</para>
<para>Sub-device character device nodes, conventionally named
<filename>/dev/v4l-subdev*</filename>, use major number 81.</para>
<section>
<title>Controls</title>
<para>Most V4L2 controls are implemented by sub-device hardware. Drivers
usually merge all controls and expose them through video device nodes.
Applications can control all sub-devices through a single interface.</para>
<para>Complex devices sometimes implement the same control in different
pieces of hardware. This situation is common in embedded platforms, where
both sensors and image processing hardware implement identical functions,
such as contrast adjustment, white balance or faulty pixels correction. As
the V4L2 controls API doesn't support several identical controls in a single
device, all but one of the identical controls are hidden.</para>
<para>Applications can access those hidden controls through the sub-device
node with the V4L2 control API described in <xref linkend="control" />. The
ioctls behave identically as when issued on V4L2 device nodes, with the
exception that they deal only with controls implemented in the sub-device.
</para>
<para>Depending on the driver, those controls might also be exposed through
one (or several) V4L2 device nodes.</para>
</section>
<section>
<title>Events</title>
<para>V4L2 sub-devices can notify applications of events as described in
<xref linkend="event" />. The API behaves identically as when used on V4L2
device nodes, with the exception that it only deals with events generated by
the sub-device. Depending on the driver, those events might also be reported
on one (or several) V4L2 device nodes.</para>
</section>
<section id="pad-level-formats">
<title>Pad-level Formats</title>
<warning><para>Pad-level formats are only applicable to very complex device that
need to expose low-level format configuration to user space. Generic V4L2
applications do <emphasis>not</emphasis> need to use the API described in
this section.</para></warning>
<note><para>For the purpose of this section, the term
<wordasword>format</wordasword> means the combination of media bus data
format, frame width and frame height.</para></note>
<para>Image formats are typically negotiated on video capture and output
devices using the <link linkend="crop">cropping and scaling</link> ioctls.
The driver is responsible for configuring every block in the video pipeline
according to the requested format at the pipeline input and/or
output.</para>
<para>For complex devices, such as often found in embedded systems,
identical image sizes at the output of a pipeline can be achieved using
different hardware configurations. One such example is shown on
<xref linkend="pipeline-scaling" />, where
image scaling can be performed on both the video sensor and the host image
processing hardware.</para>
<figure id="pipeline-scaling">
<title>Image Format Negotiation on Pipelines</title>
<mediaobject>
<imageobject>
<imagedata fileref="pipeline.pdf" format="PS" />
</imageobject>
<imageobject>
<imagedata fileref="pipeline.png" format="PNG" />
</imageobject>
<textobject>
<phrase>High quality and high speed pipeline configuration</phrase>
</textobject>
</mediaobject>
</figure>
<para>The sensor scaler is usually of less quality than the host scaler, but
scaling on the sensor is required to achieve higher frame rates. Depending
on the use case (quality vs. speed), the pipeline must be configured
differently. Applications need to configure the formats at every point in
the pipeline explicitly.</para>
<para>Drivers that implement the <link linkend="media-controller-intro">media
API</link> can expose pad-level image format configuration to applications.
When they do, applications can use the &VIDIOC-SUBDEV-G-FMT; and
&VIDIOC-SUBDEV-S-FMT; ioctls. to negotiate formats on a per-pad basis.</para>
<para>Applications are responsible for configuring coherent parameters on
the whole pipeline and making sure that connected pads have compatible
formats. The pipeline is checked for formats mismatch at &VIDIOC-STREAMON;
time, and an &EPIPE; is then returned if the configuration is
invalid.</para>
<para>Pad-level image format configuration support can be tested by calling
the &VIDIOC-SUBDEV-G-FMT; ioctl on pad 0. If the driver returns an &EINVAL;
pad-level format configuration is not supported by the sub-device.</para>
<section>
<title>Format Negotiation</title>
<para>Acceptable formats on pads can (and usually do) depend on a number
of external parameters, such as formats on other pads, active links, or
even controls. Finding a combination of formats on all pads in a video
pipeline, acceptable to both application and driver, can't rely on formats
enumeration only. A format negotiation mechanism is required.</para>
<para>Central to the format negotiation mechanism are the get/set format
operations. When called with the <structfield>which</structfield> argument
set to <constant>V4L2_SUBDEV_FORMAT_TRY</constant>, the
&VIDIOC-SUBDEV-G-FMT; and &VIDIOC-SUBDEV-S-FMT; ioctls operate on a set of
formats parameters that are not connected to the hardware configuration.
Modifying those 'try' formats leaves the device state untouched (this
applies to both the software state stored in the driver and the hardware
state stored in the device itself).</para>
<para>While not kept as part of the device state, try formats are stored
in the sub-device file handles. A &VIDIOC-SUBDEV-G-FMT; call will return
the last try format set <emphasis>on the same sub-device file
handle</emphasis>. Several applications querying the same sub-device at
the same time will thus not interact with each other.</para>
<para>To find out whether a particular format is supported by the device,
applications use the &VIDIOC-SUBDEV-S-FMT; ioctl. Drivers verify and, if
needed, change the requested <structfield>format</structfield> based on
device requirements and return the possibly modified value. Applications
can then choose to try a different format or accept the returned value and
continue.</para>
<para>Formats returned by the driver during a negotiation iteration are
guaranteed to be supported by the device. In particular, drivers guarantee
that a returned format will not be further changed if passed to an
&VIDIOC-SUBDEV-S-FMT; call as-is (as long as external parameters, such as
formats on other pads or links' configuration are not changed).</para>
<para>Drivers automatically propagate formats inside sub-devices. When a
try or active format is set on a pad, corresponding formats on other pads
of the same sub-device can be modified by the driver. Drivers are free to
modify formats as required by the device. However, they should comply with
the following rules when possible:
<itemizedlist>
<listitem><para>Formats should be propagated from sink pads to source pads.
Modifying a format on a source pad should not modify the format on any
sink pad.</para></listitem>
<listitem><para>Sub-devices that scale frames using variable scaling factors
should reset the scale factors to default values when sink pads formats
are modified. If the 1:1 scaling ratio is supported, this means that
source pads formats should be reset to the sink pads formats.</para></listitem>
</itemizedlist>
</para>
<para>Formats are not propagated across links, as that would involve
propagating them from one sub-device file handle to another. Applications
must then take care to configure both ends of every link explicitly with
compatible formats. Identical formats on the two ends of a link are
guaranteed to be compatible. Drivers are free to accept different formats
matching device requirements as being compatible.</para>
<para><xref linkend="sample-pipeline-config" />
shows a sample configuration sequence for the pipeline described in
<xref linkend="pipeline-scaling" /> (table
columns list entity names and pad numbers).</para>
<table pgwide="0" frame="none" id="sample-pipeline-config">
<title>Sample Pipeline Configuration</title>
<tgroup cols="3">
<colspec colname="what"/>
<colspec colname="sensor-0" />
<colspec colname="frontend-0" />
<colspec colname="frontend-1" />
<colspec colname="scaler-0" />
<colspec colname="scaler-1" />
<thead>
<row>
<entry></entry>
<entry>Sensor/0</entry>
<entry>Frontend/0</entry>
<entry>Frontend/1</entry>
<entry>Scaler/0</entry>
<entry>Scaler/1</entry>
</row>
</thead>
<tbody valign="top">
<row>
<entry>Initial state</entry>
<entry>2048x1536</entry>
<entry>-</entry>
<entry>-</entry>
<entry>-</entry>
<entry>-</entry>
</row>
<row>
<entry>Configure frontend input</entry>
<entry>2048x1536</entry>
<entry><emphasis>2048x1536</emphasis></entry>
<entry><emphasis>2046x1534</emphasis></entry>
<entry>-</entry>
<entry>-</entry>
</row>
<row>
<entry>Configure scaler input</entry>
<entry>2048x1536</entry>
<entry>2048x1536</entry>
<entry>2046x1534</entry>
<entry><emphasis>2046x1534</emphasis></entry>
<entry><emphasis>2046x1534</emphasis></entry>
</row>
<row>
<entry>Configure scaler output</entry>
<entry>2048x1536</entry>
<entry>2048x1536</entry>
<entry>2046x1534</entry>
<entry>2046x1534</entry>
<entry><emphasis>1280x960</emphasis></entry>
</row>
</tbody>
</tgroup>
</table>
<para>
<orderedlist>
<listitem><para>Initial state. The sensor output is set to its native 3MP
resolution. Resolutions on the host frontend and scaler input and output
pads are undefined.</para></listitem>
<listitem><para>The application configures the frontend input pad resolution to
2048x1536. The driver propagates the format to the frontend output pad.
Note that the propagated output format can be different, as in this case,
than the input format, as the hardware might need to crop pixels (for
instance when converting a Bayer filter pattern to RGB or YUV).</para></listitem>
<listitem><para>The application configures the scaler input pad resolution to
2046x1534 to match the frontend output resolution. The driver propagates
the format to the scaler output pad.</para></listitem>
<listitem><para>The application configures the scaler output pad resolution to
1280x960.</para></listitem>
</orderedlist>
</para>
<para>When satisfied with the try results, applications can set the active
formats by setting the <structfield>which</structfield> argument to
<constant>V4L2_SUBDEV_FORMAT_ACTIVE</constant>. Active formats are changed
exactly as try formats by drivers. To avoid modifying the hardware state
during format negotiation, applications should negotiate try formats first
and then modify the active settings using the try formats returned during
the last negotiation iteration. This guarantees that the active format
will be applied as-is by the driver without being modified.
</para>
</section>
<section>
<title>Cropping and scaling</title>
<para>Many sub-devices support cropping frames on their input or output
pads (or possible even on both). Cropping is used to select the area of
interest in an image, typically on a video sensor or video decoder. It can
also be used as part of digital zoom implementations to select the area of
the image that will be scaled up.</para>
<para>Crop settings are defined by a crop rectangle and represented in a
&v4l2-rect; by the coordinates of the top left corner and the rectangle
size. Both the coordinates and sizes are expressed in pixels.</para>
<para>The crop rectangle is retrieved and set using the
&VIDIOC-SUBDEV-G-CROP; and &VIDIOC-SUBDEV-S-CROP; ioctls. Like for pad
formats, drivers store try and active crop rectangles. The format
negotiation mechanism applies to crop settings as well.</para>
<para>On input pads, cropping is applied relatively to the current pad
format. The pad format represents the image size as received by the
sub-device from the previous block in the pipeline, and the crop rectangle
represents the sub-image that will be transmitted further inside the
sub-device for processing. The crop rectangle be entirely containted
inside the input image size.</para>
<para>Input crop rectangle are reset to their default value when the input
image format is modified. Drivers should use the input image size as the
crop rectangle default value, but hardware requirements may prevent this.
</para>
<para>Cropping behaviour on output pads is not defined.</para>
</section>
</section>
&sub-subdev-formats;
kernel/Documentation/DocBook/media/v4l/dev-teletext.xml
+29
View File
@@ -0,0 +1,29 @@
<title>Teletext Interface</title>
<para>This interface was aimed at devices receiving and demodulating
Teletext data [<xref linkend="ets300706" />, <xref linkend="itu653" />], evaluating the
Teletext packages and storing formatted pages in cache memory. Such
devices are usually implemented as microcontrollers with serial
interface (I<superscript>2</superscript>C) and could be found on old
TV cards, dedicated Teletext decoding cards and home-brew devices
connected to the PC parallel port.</para>
<para>The Teletext API was designed by Martin Buck. It was defined in
the kernel header file <filename>linux/videotext.h</filename>, the
specification is available from <ulink url="ftp://ftp.gwdg.de/pub/linux/misc/videotext/">
ftp://ftp.gwdg.de/pub/linux/misc/videotext/</ulink>. (Videotext is the name of
the German public television Teletext service.)</para>
<para>Eventually the Teletext API was integrated into the V4L API
with character device file names <filename>/dev/vtx0</filename> to
<filename>/dev/vtx31</filename>, device major number 81, minor numbers
192 to 223.</para>
<para>However, teletext decoders were quickly replaced by more
generic VBI demodulators and those dedicated teletext decoders no longer exist.
For many years the vtx devices were still around, even though nobody used
them. So the decision was made to finally remove support for the Teletext API in
kernel 2.6.37.</para>
<para>Modern devices all use the <link linkend="raw-vbi">raw</link> or
<link linkend="sliced">sliced</link> VBI API.</para>
kernel/Documentation/DocBook/media/v4l/driver.xml
+200
View File
@@ -0,0 +1,200 @@
<title>V4L2 Driver Programming</title>
<!-- This part defines the interface between the "videodev"
module and individual drivers. -->
<para>to do</para>
<!--
<para>V4L2 is a two-layer driver system. The top layer is the "videodev"
kernel module. When videodev initializes it registers as character device
with major number 81, and it registers a set of file operations. All V4L2
drivers are really clients of videodev, which calls V4L2 drivers through
driver method functions. V4L2 drivers are also written as kernel modules.
After probing the hardware they register one or more devices with
videodev.</para>
<section id="driver-modules">
<title>Driver Modules</title>
<para>V4L2 driver modules must have an initialization function which is
called after the module was loaded into kernel, an exit function whis is
called before the module is removed. When the driver is compiled into the
kernel these functions called at system boot and shutdown time.</para>
<informalexample>
<programlisting>
#include &lt;linux/module.h&gt;
/* Export information about this module. For details and other useful
macros see <filename>linux/module.h</filename>. */
MODULE_DESCRIPTION("my - driver for my hardware");
MODULE_AUTHOR("Your name here");
MODULE_LICENSE("GPL");
static void
my_module_exit (void)
{
/* Free all resources allocated by my_module_init(). */
}
static int
my_module_init (void)
{
/* Bind the driver to the supported hardware, see
<link linkend="driver-pci"> and
<link linkend="driver-usb"> for examples. */
return 0; /* a negative value on error, 0 on success. */
}
/* Export module functions. */
module_init (my_module_init);
module_exit (my_module_exit);
</programlisting>
</informalexample>
<para>Users can add parameters when kernel modules are inserted:</para>
<informalexample>
<programlisting>
include &lt;linux/moduleparam.h&gt;
static int my_option = 123;
static int my_option_array[47];
/* Export the symbol, an int, with access permissions 0664.
See <filename>linux/moduleparam.h</filename> for other types. */
module_param (my_option, int, 0644);
module_param_array (my_option_array, int, NULL, 0644);
MODULE_PARM_DESC (my_option, "Does magic things, default 123");
</programlisting>
</informalexample>
<para>One parameter should be supported by all V4L2 drivers, the minor
number of the device it will register. Purpose is to predictably link V4L2
drivers to device nodes if more than one video device is installed. Use the
name of the device node followed by a "_nr" suffix, for example "video_nr"
for <filename>/dev/video</filename>.</para>
<informalexample>
<programlisting>
/* Minor number of the device, -1 to allocate the first unused. */
static int video_nr = -1;
module_param (video_nr, int, 0444);
</programlisting>
</informalexample>
</section>
<section id="driver-pci">
<title>PCI Devices</title>
<para>PCI devices are initialized like this:</para>
<informalexample>
<programlisting>
typedef struct {
/* State of one physical device. */
} my_device;
static int
my_resume (struct pci_dev * pci_dev)
{
/* Restore the suspended device to working state. */
}
static int
my_suspend (struct pci_dev * pci_dev,
pm_message_t state)
{
/* This function is called before the system goes to sleep.
Stop all DMAs and disable interrupts, then put the device
into a low power state. For details see the kernel
sources under <filename>Documentation/power</filename>. */
return 0; /* a negative value on error, 0 on success. */
}
static void __devexit
my_remove (struct pci_dev * pci_dev)
{
my_device *my = pci_get_drvdata (pci_dev);
/* Describe me. */
}
static int __devinit
my_probe (struct pci_dev * pci_dev,
const struct pci_device_id * pci_id)
{
my_device *my;
/* Describe me. */
/* You can allocate per-device data here and store a pointer
to it in the pci_dev structure. */
my = ...;
pci_set_drvdata (pci_dev, my);
return 0; /* a negative value on error, 0 on success. */
}
/* A list of supported PCI devices. */
static struct pci_device_id
my_pci_device_ids [] = {
{ PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0 },
{ 0 } /* end of list */
};
/* Load our module if supported PCI devices are installed. */
MODULE_DEVICE_TABLE (pci, my_pci_device_ids);
static struct pci_driver
my_pci_driver = {
.name = "my",
.id_table = my_pci_device_ids,
.probe = my_probe,
.remove = __devexit_p (my_remove),
/* Power management functions. */
.suspend = my_suspend,
.resume = my_resume,
};
static void
my_module_exit (void)
{
pci_unregister_driver (&my_pci_driver);
}
static int
my_module_init (void)
{
return pci_register_driver (&my_pci_driver);
}
</programlisting>
</informalexample>
</section>
<section id="driver-usb">
<title>USB Devices</title>
<para>to do</para>
</section>
<section id="driver-registering">
<title>Registering V4L2 Drivers</title>
<para>After a V4L2 driver probed the hardware it registers one or more
devices with the videodev module.</para>
</section>
<section id="driver-file-ops">
<title>File Operations</title>
<para>to do</para>
</section>
<section id="driver-internal-api">
<title>Internal API</title>
<para>to do</para>
</section>
-->
kernel/Documentation/DocBook/media/v4l/fdl-appendix.xml
+671
View File
@@ -0,0 +1,671 @@
<!--
The GNU Free Documentation License 1.1 in DocBook
Markup by Eric Baudais <baudais@okstate.edu>
Maintained by the GNOME Documentation Project
http://live.gnome.org/DocumentationProject
Version: 1.0.1
Last Modified: Nov 16, 2000
-->
<appendix id="fdl">
<appendixinfo>
<releaseinfo>
Version 1.1, March 2000
</releaseinfo>
<copyright>
<year>2000</year><holder>Free Software Foundation, Inc.</holder>
</copyright>
<legalnotice id="fdl-legalnotice">
<para>
<address>Free Software Foundation, Inc. <street>59 Temple Place,
Suite 330</street>, <city>Boston</city>, <state>MA</state>
<postcode>02111-1307</postcode> <country>USA</country></address>
Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.
</para>
</legalnotice>
</appendixinfo>
<title>GNU Free Documentation License</title>
<sect1 id="fdl-preamble">
<title>0. PREAMBLE</title>
<para>
The purpose of this License is to make a manual, textbook, or
other written document <quote>free</quote> in the sense of
freedom: to assure everyone the effective freedom to copy and
redistribute it, with or without modifying it, either
commercially or noncommercially. Secondarily, this License
preserves for the author and publisher a way to get credit for
their work, while not being considered responsible for
modifications made by others.
</para>
<para>
This License is a kind of <quote>copyleft</quote>, which means
that derivative works of the document must themselves be free in
the same sense. It complements the GNU General Public License,
which is a copyleft license designed for free software.
</para>
<para>
We have designed this License in order to use it for manuals for
free software, because free software needs free documentation: a
free program should come with manuals providing the same
freedoms that the software does. But this License is not limited
to software manuals; it can be used for any textual work,
regardless of subject matter or whether it is published as a
printed book. We recommend this License principally for works
whose purpose is instruction or reference.
</para>
</sect1>
<sect1 id="fdl-section1">
<title>1. APPLICABILITY AND DEFINITIONS</title>
<para id="fdl-document">
This License applies to any manual or other work that contains a
notice placed by the copyright holder saying it can be
distributed under the terms of this License. The
<quote>Document</quote>, below, refers to any such manual or
work. Any member of the public is a licensee, and is addressed
as <quote>you</quote>.
</para>
<para id="fdl-modified">
A <quote>Modified Version</quote> of the Document means any work
containing the Document or a portion of it, either copied
verbatim, or with modifications and/or translated into another
language.
</para>
<para id="fdl-secondary">
A <quote>Secondary Section</quote> is a named appendix or a
front-matter section of the <link
linkend="fdl-document">Document</link> that deals exclusively
with the relationship of the publishers or authors of the
Document to the Document's overall subject (or to related
matters) and contains nothing that could fall directly within
that overall subject. (For example, if the Document is in part a
textbook of mathematics, a Secondary Section may not explain any
mathematics.) The relationship could be a matter of historical
connection with the subject or with related matters, or of
legal, commercial, philosophical, ethical or political position
regarding them.
</para>
<para id="fdl-invariant">
The <quote>Invariant Sections</quote> are certain <link
linkend="fdl-secondary"> Secondary Sections</link> whose titles
are designated, as being those of Invariant Sections, in the
notice that says that the <link
linkend="fdl-document">Document</link> is released under this
License.
</para>
<para id="fdl-cover-texts">
The <quote>Cover Texts</quote> are certain short passages of
text that are listed, as Front-Cover Texts or Back-Cover Texts,
in the notice that says that the <link
linkend="fdl-document">Document</link> is released under this
License.
</para>
<para id="fdl-transparent">
A <quote>Transparent</quote> copy of the <link
linkend="fdl-document"> Document</link> means a machine-readable
copy, represented in a format whose specification is available
to the general public, whose contents can be viewed and edited
directly and straightforwardly with generic text editors or (for
images composed of pixels) generic paint programs or (for
drawings) some widely available drawing editor, and that is
suitable for input to text formatters or for automatic
translation to a variety of formats suitable for input to text
formatters. A copy made in an otherwise Transparent file format
whose markup has been designed to thwart or discourage
subsequent modification by readers is not Transparent. A copy
that is not <quote>Transparent</quote> is called
<quote>Opaque</quote>.
</para>
<para>
Examples of suitable formats for Transparent copies include
plain ASCII without markup, Texinfo input format, LaTeX input
format, SGML or XML using a publicly available DTD, and
standard-conforming simple HTML designed for human
modification. Opaque formats include PostScript, PDF,
proprietary formats that can be read and edited only by
proprietary word processors, SGML or XML for which the DTD
and/or processing tools are not generally available, and the
machine-generated HTML produced by some word processors for
output purposes only.
</para>
<para id="fdl-title-page">
The <quote>Title Page</quote> means, for a printed book, the
title page itself, plus such following pages as are needed to
hold, legibly, the material this License requires to appear in
the title page. For works in formats which do not have any title
page as such, <quote>Title Page</quote> means the text near the
most prominent appearance of the work's title, preceding the
beginning of the body of the text.
</para>
</sect1>
<sect1 id="fdl-section2">
<title>2. VERBATIM COPYING</title>
<para>
You may copy and distribute the <link
linkend="fdl-document">Document</link> in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License
applies to the Document are reproduced in all copies, and that
you add no other conditions whatsoever to those of this
License. You may not use technical measures to obstruct or
control the reading or further copying of the copies you make or
distribute. However, you may accept compensation in exchange for
copies. If you distribute a large enough number of copies you
must also follow the conditions in <link
linkend="fdl-section3">section 3</link>.
</para>
<para>
You may also lend copies, under the same conditions stated
above, and you may publicly display copies.
</para>
</sect1>
<sect1 id="fdl-section3">
<title>3. COPYING IN QUANTITY</title>
<para>
If you publish printed copies of the <link
linkend="fdl-document">Document</link> numbering more than 100,
and the Document's license notice requires <link
linkend="fdl-cover-texts">Cover Texts</link>, you must enclose
the copies in covers that carry, clearly and legibly, all these
Cover Texts: Front-Cover Texts on the front cover, and
Back-Cover Texts on the back cover. Both covers must also
clearly and legibly identify you as the publisher of these
copies. The front cover must present the full title with all
words of the title equally prominent and visible. You may add
other material on the covers in addition. Copying with changes
limited to the covers, as long as they preserve the title of the
<link linkend="fdl-document">Document</link> and satisfy these
conditions, can be treated as verbatim copying in other
respects.
</para>
<para>
If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto
adjacent pages.
</para>
<para>
If you publish or distribute <link
linkend="fdl-transparent">Opaque</link> copies of the <link
linkend="fdl-document">Document</link> numbering more than 100,
you must either include a machine-readable <link
linkend="fdl-transparent">Transparent</link> copy along with
each Opaque copy, or state in or with each Opaque copy a
publicly-accessible computer-network location containing a
complete Transparent copy of the Document, free of added
material, which the general network-using public has access to
download anonymously at no charge using public-standard network
protocols. If you use the latter option, you must take
reasonably prudent steps, when you begin distribution of Opaque
copies in quantity, to ensure that this Transparent copy will
remain thus accessible at the stated location until at least one
year after the last time you distribute an Opaque copy (directly
or through your agents or retailers) of that edition to the
public.
</para>
<para>
It is requested, but not required, that you contact the authors
of the <link linkend="fdl-document">Document</link> well before
redistributing any large number of copies, to give them a chance
to provide you with an updated version of the Document.
</para>
</sect1>
<sect1 id="fdl-section4">
<title>4. MODIFICATIONS</title>
<para>
You may copy and distribute a <link
linkend="fdl-modified">Modified Version</link> of the <link
linkend="fdl-document">Document</link> under the conditions of
sections <link linkend="fdl-section2">2</link> and <link
linkend="fdl-section3">3</link> above, provided that you release
the Modified Version under precisely this License, with the
Modified Version filling the role of the Document, thus
licensing distribution and modification of the Modified Version
to whoever possesses a copy of it. In addition, you must do
these things in the Modified Version:
</para>
<itemizedlist mark="opencircle">
<listitem>
<formalpara>
<title>A</title>
<para>
Use in the <link linkend="fdl-title-page">Title
Page</link> (and on the covers, if any) a title distinct
from that of the <link
linkend="fdl-document">Document</link>, and from those of
previous versions (which should, if there were any, be
listed in the History section of the Document). You may
use the same title as a previous version if the original
publisher of that version gives permission.
</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>B</title>
<para>
List on the <link linkend="fdl-title-page">Title
Page</link>, as authors, one or more persons or entities
responsible for authorship of the modifications in the
<link linkend="fdl-modified">Modified Version</link>,
together with at least five of the principal authors of
the <link linkend="fdl-document">Document</link> (all of
its principal authors, if it has less than five).
</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>C</title>
<para>
State on the <link linkend="fdl-title-page">Title
Page</link> the name of the publisher of the <link
linkend="fdl-modified">Modified Version</link>, as the
publisher.
</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>D</title>
<para>
Preserve all the copyright notices of the <link
linkend="fdl-document">Document</link>.
</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>E</title>
<para>
Add an appropriate copyright notice for your modifications
adjacent to the other copyright notices.
</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>F</title>
<para>
Include, immediately after the copyright notices, a
license notice giving the public permission to use the
<link linkend="fdl-modified">Modified Version</link> under
the terms of this License, in the form shown in the
Addendum below.
</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>G</title>
<para>
Preserve in that license notice the full lists of <link
linkend="fdl-invariant"> Invariant Sections</link> and
required <link linkend="fdl-cover-texts">Cover
Texts</link> given in the <link
linkend="fdl-document">Document's</link> license notice.
</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>H</title>
<para>
Include an unaltered copy of this License.
</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>I</title>
<para>
Preserve the section entitled <quote>History</quote>, and
its title, and add to it an item stating at least the
title, year, new authors, and publisher of the <link
linkend="fdl-modified">Modified Version </link>as given on
the <link linkend="fdl-title-page">Title Page</link>. If
there is no section entitled <quote>History</quote> in the
<link linkend="fdl-document">Document</link>, create one
stating the title, year, authors, and publisher of the
Document as given on its Title Page, then add an item
describing the Modified Version as stated in the previous
sentence.
</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>J</title>
<para>
Preserve the network location, if any, given in the <link
linkend="fdl-document">Document</link> for public access
to a <link linkend="fdl-transparent">Transparent</link>
copy of the Document, and likewise the network locations
given in the Document for previous versions it was based
on. These may be placed in the <quote>History</quote>
section. You may omit a network location for a work that
was published at least four years before the Document
itself, or if the original publisher of the version it
refers to gives permission.
</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>K</title>
<para>
In any section entitled <quote>Acknowledgements</quote> or
<quote>Dedications</quote>, preserve the section's title,
and preserve in the section all the substance and tone of
each of the contributor acknowledgements and/or
dedications given therein.
</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>L</title>
<para>
Preserve all the <link linkend="fdl-invariant">Invariant
Sections</link> of the <link
linkend="fdl-document">Document</link>, unaltered in their
text and in their titles. Section numbers or the
equivalent are not considered part of the section titles.
</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>M</title>
<para>
Delete any section entitled
<quote>Endorsements</quote>. Such a section may not be
included in the <link linkend="fdl-modified">Modified
Version</link>.
</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>N</title>
<para>
Do not retitle any existing section as
<quote>Endorsements</quote> or to conflict in title with
any <link linkend="fdl-invariant">Invariant
Section</link>.
</para>
</formalpara>
</listitem>
</itemizedlist>
<para>
If the <link linkend="fdl-modified">Modified Version</link>
includes new front-matter sections or appendices that qualify as
<link linkend="fdl-secondary">Secondary Sections</link> and
contain no material copied from the Document, you may at your
option designate some or all of these sections as invariant. To
do this, add their titles to the list of <link
linkend="fdl-invariant">Invariant Sections</link> in the
Modified Version's license notice. These titles must be
distinct from any other section titles.
</para>
<para>
You may add a section entitled <quote>Endorsements</quote>,
provided it contains nothing but endorsements of your <link
linkend="fdl-modified">Modified Version</link> by various
parties--for example, statements of peer review or that the text
has been approved by an organization as the authoritative
definition of a standard.
</para>
<para>
You may add a passage of up to five words as a <link
linkend="fdl-cover-texts">Front-Cover Text</link>, and a passage
of up to 25 words as a <link
linkend="fdl-cover-texts">Back-Cover Text</link>, to the end of
the list of <link linkend="fdl-cover-texts">Cover Texts</link>
in the <link linkend="fdl-modified">Modified Version</link>.
Only one passage of Front-Cover Text and one of Back-Cover Text
may be added by (or through arrangements made by) any one
entity. If the <link linkend="fdl-document">Document</link>
already includes a cover text for the same cover, previously
added by you or by arrangement made by the same entity you are
acting on behalf of, you may not add another; but you may
replace the old one, on explicit permission from the previous
publisher that added the old one.
</para>
<para>
The author(s) and publisher(s) of the <link
linkend="fdl-document">Document</link> do not by this License
give permission to use their names for publicity for or to
assert or imply endorsement of any <link
linkend="fdl-modified">Modified Version </link>.
</para>
</sect1>
<sect1 id="fdl-section5">
<title>5. COMBINING DOCUMENTS</title>
<para>
You may combine the <link linkend="fdl-document">Document</link>
with other documents released under this License, under the
terms defined in <link linkend="fdl-section4">section 4</link>
above for modified versions, provided that you include in the
combination all of the <link linkend="fdl-invariant">Invariant
Sections</link> of all of the original documents, unmodified,
and list them all as Invariant Sections of your combined work in
its license notice.
</para>
<para>
The combined work need only contain one copy of this License,
and multiple identical <link linkend="fdl-invariant">Invariant
Sections</link> may be replaced with a single copy. If there are
multiple Invariant Sections with the same name but different
contents, make the title of each such section unique by adding
at the end of it, in parentheses, the name of the original
author or publisher of that section if known, or else a unique
number. Make the same adjustment to the section titles in the
list of Invariant Sections in the license notice of the combined
work.
</para>
<para>
In the combination, you must combine any sections entitled
<quote>History</quote> in the various original documents,
forming one section entitled <quote>History</quote>; likewise
combine any sections entitled <quote>Acknowledgements</quote>,
and any sections entitled <quote>Dedications</quote>. You must
delete all sections entitled <quote>Endorsements.</quote>
</para>
</sect1>
<sect1 id="fdl-section6">
<title>6. COLLECTIONS OF DOCUMENTS</title>
<para>
You may make a collection consisting of the <link
linkend="fdl-document">Document</link> and other documents
released under this License, and replace the individual copies
of this License in the various documents with a single copy that
is included in the collection, provided that you follow the
rules of this License for verbatim copying of each of the
documents in all other respects.
</para>
<para>
You may extract a single document from such a collection, and
dispbibute it individually under this License, provided you
insert a copy of this License into the extracted document, and
follow this License in all other respects regarding verbatim
copying of that document.
</para>
</sect1>
<sect1 id="fdl-section7">
<title>7. AGGREGATION WITH INDEPENDENT WORKS</title>
<para>
A compilation of the <link
linkend="fdl-document">Document</link> or its derivatives with
other separate and independent documents or works, in or on a
volume of a storage or distribution medium, does not as a whole
count as a <link linkend="fdl-modified">Modified Version</link>
of the Document, provided no compilation copyright is claimed
for the compilation. Such a compilation is called an
<quote>aggregate</quote>, and this License does not apply to the
other self-contained works thus compiled with the Document , on
account of their being thus compiled, if they are not themselves
derivative works of the Document. If the <link
linkend="fdl-cover-texts">Cover Text</link> requirement of <link
linkend="fdl-section3">section 3</link> is applicable to these
copies of the Document, then if the Document is less than one
quarter of the entire aggregate, the Document's Cover Texts may
be placed on covers that surround only the Document within the
aggregate. Otherwise they must appear on covers around the whole
aggregate.
</para>
</sect1>
<sect1 id="fdl-section8">
<title>8. TRANSLATION</title>
<para>
Translation is considered a kind of modification, so you may
distribute translations of the <link
linkend="fdl-document">Document</link> under the terms of <link
linkend="fdl-section4">section 4</link>. Replacing <link
linkend="fdl-invariant"> Invariant Sections</link> with
translations requires special permission from their copyright
holders, but you may include translations of some or all
Invariant Sections in addition to the original versions of these
Invariant Sections. You may include a translation of this
License provided that you also include the original English
version of this License. In case of a disagreement between the
translation and the original English version of this License,
the original English version will prevail.
</para>
</sect1>
<sect1 id="fdl-section9">
<title>9. TERMINATION</title>
<para>
You may not copy, modify, sublicense, or distribute the <link
linkend="fdl-document">Document</link> except as expressly
provided for under this License. Any other attempt to copy,
modify, sublicense or distribute the Document is void, and will
automatically terminate your rights under this License. However,
parties who have received copies, or rights, from you under this
License will not have their licenses terminated so long as such
parties remain in full compliance.
</para>
</sect1>
<sect1 id="fdl-section10">
<title>10. FUTURE REVISIONS OF THIS LICENSE</title>
<para>
The <ulink type="http"
url="http://www.gnu.org/fsf/fsf.html">Free Software
Foundation</ulink> may publish new, revised versions of the GNU
Free Documentation License from time to time. Such new versions
will be similar in spirit to the present version, but may differ
in detail to address new problems or concerns. See <ulink
type="http"
url="http://www.gnu.org/copyleft">http://www.gnu.org/copyleft/</ulink>.
</para>
<para>
Each version of the License is given a distinguishing version
number. If the <link linkend="fdl-document">Document</link>
specifies that a particular numbered version of this License
<quote>or any later version</quote> applies to it, you have the
option of following the terms and conditions either of that
specified version or of any later version that has been
published (not as a draft) by the Free Software Foundation. If
the Document does not specify a version number of this License,
you may choose any version ever published (not as a draft) by
the Free Software Foundation.
</para>
</sect1>
<sect1 id="fdl-using">
<title>Addendum</title>
<para>
To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and
license notices just after the title page:
</para>
<blockquote>
<para>
Copyright &copy; YEAR YOUR NAME.
</para>
<para>
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation
License, Version 1.1 or any later version published by the
Free Software Foundation; with the <link
linkend="fdl-invariant">Invariant Sections</link> being LIST
THEIR TITLES, with the <link
linkend="fdl-cover-texts">Front-Cover Texts</link> being LIST,
and with the <link linkend="fdl-cover-texts">Back-Cover
Texts</link> being LIST. A copy of the license is included in
the section entitled <quote>GNU Free Documentation
License</quote>.
</para>
</blockquote>
<para>
If you have no <link linkend="fdl-invariant">Invariant
Sections</link>, write <quote>with no Invariant Sections</quote>
instead of saying which ones are invariant. If you have no
<link linkend="fdl-cover-texts">Front-Cover Texts</link>, write
<quote>no Front-Cover Texts</quote> instead of
<quote>Front-Cover Texts being LIST</quote>; likewise for <link
linkend="fdl-cover-texts">Back-Cover Texts</link>.
</para>
<para>
If your document contains nontrivial examples of program code,
we recommend releasing these examples in parallel under your
choice of free software license, such as the <ulink type="http"
url="http://www.gnu.org/copyleft/gpl.html"> GNU General Public
License</ulink>, to permit their use in free software.
</para>
</sect1>
</appendix>
kernel/Documentation/DocBook/media/v4l/fieldseq_bt.pdf
BIN
View File
Binary file not shown.
kernel/Documentation/DocBook/media/v4l/fieldseq_tb.pdf
BIN
View File
Binary file not shown.
kernel/Documentation/DocBook/media/v4l/func-close.xml
+62
View File
@@ -0,0 +1,62 @@
<refentry id="func-close">
<refmeta>
<refentrytitle>V4L2 close()</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>v4l2-close</refname>
<refpurpose>Close a V4L2 device</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;unistd.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>close</function></funcdef>
<paramdef>int <parameter>fd</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>fd</parameter></term>
<listitem>
<para>&fd;</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>Closes the device. Any I/O in progress is terminated and
resources associated with the file descriptor are freed. However data
format parameters, current input or output, control values or other
properties remain unchanged.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>The function returns <returnvalue>0</returnvalue> on
success, <returnvalue>-1</returnvalue> on failure and the
<varname>errno</varname> is set appropriately. Possible error
codes:</para>
<variablelist>
<varlistentry>
<term><errorcode>EBADF</errorcode></term>
<listitem>
<para><parameter>fd</parameter> is not a valid open file
descriptor.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/func-ioctl.xml
+71
View File
@@ -0,0 +1,71 @@
<refentry id="func-ioctl">
<refmeta>
<refentrytitle>V4L2 ioctl()</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>v4l2-ioctl</refname>
<refpurpose>Program a V4L2 device</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;sys/ioctl.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>ioctl</function></funcdef>
<paramdef>int <parameter>fd</parameter></paramdef>
<paramdef>int <parameter>request</parameter></paramdef>
<paramdef>void *<parameter>argp</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>fd</parameter></term>
<listitem>
<para>&fd;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>request</parameter></term>
<listitem>
<para>V4L2 ioctl request code as defined in the <filename>videodev2.h</filename> header file, for example
VIDIOC_QUERYCAP.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>argp</parameter></term>
<listitem>
<para>Pointer to a function parameter, usually a structure.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>The <function>ioctl()</function> function is used to program
V4L2 devices. The argument <parameter>fd</parameter> must be an open
file descriptor. An ioctl <parameter>request</parameter> has encoded
in it whether the argument is an input, output or read/write
parameter, and the size of the argument <parameter>argp</parameter> in
bytes. Macros and defines specifying V4L2 ioctl requests are located
in the <filename>videodev2.h</filename> header file.
Applications should use their own copy, not include the version in the
kernel sources on the system they compile on. All V4L2 ioctl requests,
their respective function and parameters are specified in <xref
linkend="user-func" />.</para>
</refsect1>
<refsect1>
&return-value;
<para>When an ioctl that takes an output or read/write parameter fails,
the parameter remains unmodified.</para>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/func-mmap.xml
+183
View File
@@ -0,0 +1,183 @@
<refentry id="func-mmap">
<refmeta>
<refentrytitle>V4L2 mmap()</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>v4l2-mmap</refname>
<refpurpose>Map device memory into application address space</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>
#include &lt;unistd.h&gt;
#include &lt;sys/mman.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>void *<function>mmap</function></funcdef>
<paramdef>void *<parameter>start</parameter></paramdef>
<paramdef>size_t <parameter>length</parameter></paramdef>
<paramdef>int <parameter>prot</parameter></paramdef>
<paramdef>int <parameter>flags</parameter></paramdef>
<paramdef>int <parameter>fd</parameter></paramdef>
<paramdef>off_t <parameter>offset</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>start</parameter></term>
<listitem>
<para>Map the buffer to this address in the
application's address space. When the <constant>MAP_FIXED</constant>
flag is specified, <parameter>start</parameter> must be a multiple of the
pagesize and mmap will fail when the specified address
cannot be used. Use of this option is discouraged; applications should
just specify a <constant>NULL</constant> pointer here.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>length</parameter></term>
<listitem>
<para>Length of the memory area to map. This must be the
same value as returned by the driver in the &v4l2-buffer;
<structfield>length</structfield> field for the
single-planar API, and the same value as returned by the driver
in the &v4l2-plane; <structfield>length</structfield> field for the
multi-planar API.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>prot</parameter></term>
<listitem>
<para>The <parameter>prot</parameter> argument describes the
desired memory protection. Regardless of the device type and the
direction of data exchange it should be set to
<constant>PROT_READ</constant> | <constant>PROT_WRITE</constant>,
permitting read and write access to image buffers. Drivers should
support at least this combination of flags. Note the Linux
<filename>video-buf</filename> kernel module, which is used by the
bttv, saa7134, saa7146, cx88 and vivi driver supports only
<constant>PROT_READ</constant> | <constant>PROT_WRITE</constant>. When
the driver does not support the desired protection the
<function>mmap()</function> function fails.</para>
<para>Note device memory accesses (&eg; the memory on a
graphics card with video capturing hardware) may incur a performance
penalty compared to main memory accesses, or reads may be
significantly slower than writes or vice versa. Other I/O methods may
be more efficient in this case.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>flags</parameter></term>
<listitem>
<para>The <parameter>flags</parameter> parameter
specifies the type of the mapped object, mapping options and whether
modifications made to the mapped copy of the page are private to the
process or are to be shared with other references.</para>
<para><constant>MAP_FIXED</constant> requests that the
driver selects no other address than the one specified. If the
specified address cannot be used, <function>mmap()</function> will fail. If
<constant>MAP_FIXED</constant> is specified,
<parameter>start</parameter> must be a multiple of the pagesize. Use
of this option is discouraged.</para>
<para>One of the <constant>MAP_SHARED</constant> or
<constant>MAP_PRIVATE</constant> flags must be set.
<constant>MAP_SHARED</constant> allows applications to share the
mapped memory with other (&eg; child-) processes. Note the Linux
<filename>video-buf</filename> module which is used by the bttv,
saa7134, saa7146, cx88 and vivi driver supports only
<constant>MAP_SHARED</constant>. <constant>MAP_PRIVATE</constant>
requests copy-on-write semantics. V4L2 applications should not set the
<constant>MAP_PRIVATE</constant>, <constant>MAP_DENYWRITE</constant>,
<constant>MAP_EXECUTABLE</constant> or <constant>MAP_ANON</constant>
flag.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>fd</parameter></term>
<listitem>
<para>&fd;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>offset</parameter></term>
<listitem>
<para>Offset of the buffer in device memory. This must be the
same value as returned by the driver in the &v4l2-buffer;
<structfield>m</structfield> union <structfield>offset</structfield> field for
the single-planar API, and the same value as returned by the driver
in the &v4l2-plane; <structfield>m</structfield> union
<structfield>mem_offset</structfield> field for the multi-planar API.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>The <function>mmap()</function> function asks to map
<parameter>length</parameter> bytes starting at
<parameter>offset</parameter> in the memory of the device specified by
<parameter>fd</parameter> into the application address space,
preferably at address <parameter>start</parameter>. This latter
address is a hint only, and is usually specified as 0.</para>
<para>Suitable length and offset parameters are queried with the
&VIDIOC-QUERYBUF; ioctl. Buffers must be allocated with the
&VIDIOC-REQBUFS; ioctl before they can be queried.</para>
<para>To unmap buffers the &func-munmap; function is used.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>On success <function>mmap()</function> returns a pointer to
the mapped buffer. On error <constant>MAP_FAILED</constant> (-1) is
returned, and the <varname>errno</varname> variable is set
appropriately. Possible error codes are:</para>
<variablelist>
<varlistentry>
<term><errorcode>EBADF</errorcode></term>
<listitem>
<para><parameter>fd</parameter> is not a valid file
descriptor.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EACCES</errorcode></term>
<listitem>
<para><parameter>fd</parameter> is
not open for reading and writing.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EINVAL</errorcode></term>
<listitem>
<para>The <parameter>start</parameter> or
<parameter>length</parameter> or <parameter>offset</parameter> are not
suitable. (E.&nbsp;g. they are too large, or not aligned on a
<constant>PAGESIZE</constant> boundary.)</para>
<para>The <parameter>flags</parameter> or
<parameter>prot</parameter> value is not supported.</para>
<para>No buffers have been allocated with the
&VIDIOC-REQBUFS; ioctl.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>ENOMEM</errorcode></term>
<listitem>
<para>Not enough physical or virtual memory was available to
complete the request.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/func-munmap.xml
+76
View File
@@ -0,0 +1,76 @@
<refentry id="func-munmap">
<refmeta>
<refentrytitle>V4L2 munmap()</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>v4l2-munmap</refname>
<refpurpose>Unmap device memory</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>
#include &lt;unistd.h&gt;
#include &lt;sys/mman.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>munmap</function></funcdef>
<paramdef>void *<parameter>start</parameter></paramdef>
<paramdef>size_t <parameter>length</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>start</parameter></term>
<listitem>
<para>Address of the mapped buffer as returned by the
&func-mmap; function.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>length</parameter></term>
<listitem>
<para>Length of the mapped buffer. This must be the same
value as given to <function>mmap()</function> and returned by the
driver in the &v4l2-buffer; <structfield>length</structfield>
field for the single-planar API and in the &v4l2-plane;
<structfield>length</structfield> field for the multi-planar API.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>Unmaps a previously with the &func-mmap; function mapped
buffer and frees it, if possible. <!-- ? This function (not freeing)
has no impact on I/O in progress, specifically it does not imply
&VIDIOC-STREAMOFF; to terminate I/O. Unmapped buffers can still be
enqueued, dequeued or queried, they are just not accessible by the
application.--></para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>On success <function>munmap()</function> returns 0, on
failure -1 and the <varname>errno</varname> variable is set
appropriately:</para>
<variablelist>
<varlistentry>
<term><errorcode>EINVAL</errorcode></term>
<listitem>
<para>The <parameter>start</parameter> or
<parameter>length</parameter> is incorrect, or no buffers have been
mapped yet.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/func-open.xml
+113
View File
@@ -0,0 +1,113 @@
<refentry id="func-open">
<refmeta>
<refentrytitle>V4L2 open()</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>v4l2-open</refname>
<refpurpose>Open a V4L2 device</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;fcntl.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>open</function></funcdef>
<paramdef>const char *<parameter>device_name</parameter></paramdef>
<paramdef>int <parameter>flags</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>device_name</parameter></term>
<listitem>
<para>Device to be opened.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>flags</parameter></term>
<listitem>
<para>Open flags. Access mode must be
<constant>O_RDWR</constant>. This is just a technicality, input devices
still support only reading and output devices only writing.</para>
<para>When the <constant>O_NONBLOCK</constant> flag is
given, the read() function and the &VIDIOC-DQBUF; ioctl will return
the &EAGAIN; when no data is available or no buffer is in the driver
outgoing queue, otherwise these functions block until data becomes
available. All V4L2 drivers exchanging data with applications must
support the <constant>O_NONBLOCK</constant> flag.</para>
<para>Other flags have no effect.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>To open a V4L2 device applications call
<function>open()</function> with the desired device name. This
function has no side effects; all data format parameters, current
input or output, control values or other properties remain unchanged.
At the first <function>open()</function> call after loading the driver
they will be reset to default values, drivers are never in an
undefined state.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>On success <function>open</function> returns the new file
descriptor. On error -1 is returned, and the <varname>errno</varname>
variable is set appropriately. Possible error codes are:</para>
<variablelist>
<varlistentry>
<term><errorcode>EACCES</errorcode></term>
<listitem>
<para>The caller has no permission to access the
device.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EBUSY</errorcode></term>
<listitem>
<para>The driver does not support multiple opens and the
device is already in use.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>ENXIO</errorcode></term>
<listitem>
<para>No device corresponding to this device special file
exists.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>ENOMEM</errorcode></term>
<listitem>
<para>Not enough kernel memory was available to complete the
request.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EMFILE</errorcode></term>
<listitem>
<para>The process already has the maximum number of
files open.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>ENFILE</errorcode></term>
<listitem>
<para>The limit on the total number of files open on the
system has been reached.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/func-poll.xml
+119
View File
@@ -0,0 +1,119 @@
<refentry id="func-poll">
<refmeta>
<refentrytitle>V4L2 poll()</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>v4l2-poll</refname>
<refpurpose>Wait for some event on a file descriptor</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;sys/poll.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>poll</function></funcdef>
<paramdef>struct pollfd *<parameter>ufds</parameter></paramdef>
<paramdef>unsigned int <parameter>nfds</parameter></paramdef>
<paramdef>int <parameter>timeout</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>With the <function>poll()</function> function applications
can suspend execution until the driver has captured data or is ready
to accept data for output.</para>
<para>When streaming I/O has been negotiated this function waits
until a buffer has been filled or displayed and can be dequeued with
the &VIDIOC-DQBUF; ioctl. When buffers are already in the outgoing
queue of the driver the function returns immediately.</para>
<para>On success <function>poll()</function> returns the number of
file descriptors that have been selected (that is, file descriptors
for which the <structfield>revents</structfield> field of the
respective <structname>pollfd</structname> structure is non-zero).
Capture devices set the <constant>POLLIN</constant> and
<constant>POLLRDNORM</constant> flags in the
<structfield>revents</structfield> field, output devices the
<constant>POLLOUT</constant> and <constant>POLLWRNORM</constant>
flags. When the function timed out it returns a value of zero, on
failure it returns <returnvalue>-1</returnvalue> and the
<varname>errno</varname> variable is set appropriately. When the
application did not call &VIDIOC-QBUF; or &VIDIOC-STREAMON; yet the
<function>poll()</function> function succeeds, but sets the
<constant>POLLERR</constant> flag in the
<structfield>revents</structfield> field.</para>
<para>When use of the <function>read()</function> function has
been negotiated and the driver does not capture yet, the
<function>poll</function> function starts capturing. When that fails
it returns a <constant>POLLERR</constant> as above. Otherwise it waits
until data has been captured and can be read. When the driver captures
continuously (as opposed to, for example, still images) the function
may return immediately.</para>
<para>When use of the <function>write()</function> function has
been negotiated the <function>poll</function> function just waits
until the driver is ready for a non-blocking
<function>write()</function> call.</para>
<para>All drivers implementing the <function>read()</function> or
<function>write()</function> function or streaming I/O must also
support the <function>poll()</function> function.</para>
<para>For more details see the
<function>poll()</function> manual page.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>On success, <function>poll()</function> returns the number
structures which have non-zero <structfield>revents</structfield>
fields, or zero if the call timed out. On error
<returnvalue>-1</returnvalue> is returned, and the
<varname>errno</varname> variable is set appropriately:</para>
<variablelist>
<varlistentry>
<term><errorcode>EBADF</errorcode></term>
<listitem>
<para>One or more of the <parameter>ufds</parameter> members
specify an invalid file descriptor.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EBUSY</errorcode></term>
<listitem>
<para>The driver does not support multiple read or write
streams and the device is already in use.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EFAULT</errorcode></term>
<listitem>
<para><parameter>ufds</parameter> references an inaccessible
memory area.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EINTR</errorcode></term>
<listitem>
<para>The call was interrupted by a signal.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EINVAL</errorcode></term>
<listitem>
<para>The <parameter>nfds</parameter> argument is greater
than <constant>OPEN_MAX</constant>.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/func-read.xml
+181
View File
@@ -0,0 +1,181 @@
<refentry id="func-read">
<refmeta>
<refentrytitle>V4L2 read()</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>v4l2-read</refname>
<refpurpose>Read from a V4L2 device</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;unistd.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>ssize_t <function>read</function></funcdef>
<paramdef>int <parameter>fd</parameter></paramdef>
<paramdef>void *<parameter>buf</parameter></paramdef>
<paramdef>size_t <parameter>count</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>fd</parameter></term>
<listitem>
<para>&fd;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>buf</parameter></term>
<listitem>
<para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>count</parameter></term>
<listitem>
<para></para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para><function>read()</function> attempts to read up to
<parameter>count</parameter> bytes from file descriptor
<parameter>fd</parameter> into the buffer starting at
<parameter>buf</parameter>. The layout of the data in the buffer is
discussed in the respective device interface section, see ##. If <parameter>count</parameter> is zero,
<function>read()</function> returns zero and has no other results. If
<parameter>count</parameter> is greater than
<constant>SSIZE_MAX</constant>, the result is unspecified. Regardless
of the <parameter>count</parameter> value each
<function>read()</function> call will provide at most one frame (two
fields) worth of data.</para>
<para>By default <function>read()</function> blocks until data
becomes available. When the <constant>O_NONBLOCK</constant> flag was
given to the &func-open; function it
returns immediately with an &EAGAIN; when no data is available. The
&func-select; or &func-poll; functions
can always be used to suspend execution until data becomes available. All
drivers supporting the <function>read()</function> function must also
support <function>select()</function> and
<function>poll()</function>.</para>
<para>Drivers can implement read functionality in different
ways, using a single or multiple buffers and discarding the oldest or
newest frames once the internal buffers are filled.</para>
<para><function>read()</function> never returns a "snapshot" of a
buffer being filled. Using a single buffer the driver will stop
capturing when the application starts reading the buffer until the
read is finished. Thus only the period of the vertical blanking
interval is available for reading, or the capture rate must fall below
the nominal frame rate of the video standard.</para>
<para>The behavior of
<function>read()</function> when called during the active picture
period or the vertical blanking separating the top and bottom field
depends on the discarding policy. A driver discarding the oldest
frames keeps capturing into an internal buffer, continuously
overwriting the previously, not read frame, and returns the frame
being received at the time of the <function>read()</function> call as
soon as it is complete.</para>
<para>A driver discarding the newest frames stops capturing until
the next <function>read()</function> call. The frame being received at
<function>read()</function> time is discarded, returning the following
frame instead. Again this implies a reduction of the capture rate to
one half or less of the nominal frame rate. An example of this model
is the video read mode of the bttv driver, initiating a DMA to user
memory when <function>read()</function> is called and returning when
the DMA finished.</para>
<para>In the multiple buffer model drivers maintain a ring of
internal buffers, automatically advancing to the next free buffer.
This allows continuous capturing when the application can empty the
buffers fast enough. Again, the behavior when the driver runs out of
free buffers depends on the discarding policy.</para>
<para>Applications can get and set the number of buffers used
internally by the driver with the &VIDIOC-G-PARM; and &VIDIOC-S-PARM;
ioctls. They are optional, however. The discarding policy is not
reported and cannot be changed. For minimum requirements see <xref
linkend="devices" />.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>On success, the number of bytes read is returned. It is not
an error if this number is smaller than the number of bytes requested,
or the amount of data required for one frame. This may happen for
example because <function>read()</function> was interrupted by a
signal. On error, -1 is returned, and the <varname>errno</varname>
variable is set appropriately. In this case the next read will start
at the beginning of a new frame. Possible error codes are:</para>
<variablelist>
<varlistentry>
<term><errorcode>EAGAIN</errorcode></term>
<listitem>
<para>Non-blocking I/O has been selected using
O_NONBLOCK and no data was immediately available for reading.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EBADF</errorcode></term>
<listitem>
<para><parameter>fd</parameter> is not a valid file
descriptor or is not open for reading, or the process already has the
maximum number of files open.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EBUSY</errorcode></term>
<listitem>
<para>The driver does not support multiple read streams and the
device is already in use.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EFAULT</errorcode></term>
<listitem>
<para><parameter>buf</parameter> references an inaccessible
memory area.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EINTR</errorcode></term>
<listitem>
<para>The call was interrupted by a signal before any
data was read.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EIO</errorcode></term>
<listitem>
<para>I/O error. This indicates some hardware problem or a
failure to communicate with a remote device (USB camera etc.).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EINVAL</errorcode></term>
<listitem>
<para>The <function>read()</function> function is not
supported by this driver, not on this device, or generally not on this
type of device.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/func-select.xml
+130
View File
@@ -0,0 +1,130 @@
<refentry id="func-select">
<refmeta>
<refentrytitle>V4L2 select()</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>v4l2-select</refname>
<refpurpose>Synchronous I/O multiplexing</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>
#include &lt;sys/time.h&gt;
#include &lt;sys/types.h&gt;
#include &lt;unistd.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>select</function></funcdef>
<paramdef>int <parameter>nfds</parameter></paramdef>
<paramdef>fd_set *<parameter>readfds</parameter></paramdef>
<paramdef>fd_set *<parameter>writefds</parameter></paramdef>
<paramdef>fd_set *<parameter>exceptfds</parameter></paramdef>
<paramdef>struct timeval *<parameter>timeout</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>With the <function>select()</function> function applications
can suspend execution until the driver has captured data or is ready
to accept data for output.</para>
<para>When streaming I/O has been negotiated this function waits
until a buffer has been filled or displayed and can be dequeued with
the &VIDIOC-DQBUF; ioctl. When buffers are already in the outgoing
queue of the driver the function returns immediately.</para>
<para>On success <function>select()</function> returns the total
number of bits set in the <structname>fd_set</structname>s. When the
function timed out it returns a value of zero. On failure it returns
<returnvalue>-1</returnvalue> and the <varname>errno</varname>
variable is set appropriately. When the application did not call
&VIDIOC-QBUF; or &VIDIOC-STREAMON; yet the
<function>select()</function> function succeeds, setting the bit of
the file descriptor in <parameter>readfds</parameter> or
<parameter>writefds</parameter>, but subsequent &VIDIOC-DQBUF; calls
will fail.<footnote><para>The Linux kernel implements
<function>select()</function> like the &func-poll; function, but
<function>select()</function> cannot return a
<constant>POLLERR</constant>.</para>
</footnote></para>
<para>When use of the <function>read()</function> function has
been negotiated and the driver does not capture yet, the
<function>select()</function> function starts capturing. When that
fails, <function>select()</function> returns successful and a
subsequent <function>read()</function> call, which also attempts to
start capturing, will return an appropriate error code. When the
driver captures continuously (as opposed to, for example, still
images) and data is already available the
<function>select()</function> function returns immediately.</para>
<para>When use of the <function>write()</function> function has
been negotiated the <function>select()</function> function just waits
until the driver is ready for a non-blocking
<function>write()</function> call.</para>
<para>All drivers implementing the <function>read()</function> or
<function>write()</function> function or streaming I/O must also
support the <function>select()</function> function.</para>
<para>For more details see the <function>select()</function>
manual page.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>On success, <function>select()</function> returns the number
of descriptors contained in the three returned descriptor sets, which
will be zero if the timeout expired. On error
<returnvalue>-1</returnvalue> is returned, and the
<varname>errno</varname> variable is set appropriately; the sets and
<parameter>timeout</parameter> are undefined. Possible error codes
are:</para>
<variablelist>
<varlistentry>
<term><errorcode>EBADF</errorcode></term>
<listitem>
<para>One or more of the file descriptor sets specified a
file descriptor that is not open.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EBUSY</errorcode></term>
<listitem>
<para>The driver does not support multiple read or write
streams and the device is already in use.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EFAULT</errorcode></term>
<listitem>
<para>The <parameter>readfds</parameter>,
<parameter>writefds</parameter>, <parameter>exceptfds</parameter> or
<parameter>timeout</parameter> pointer references an inaccessible memory
area.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EINTR</errorcode></term>
<listitem>
<para>The call was interrupted by a signal.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EINVAL</errorcode></term>
<listitem>
<para>The <parameter>nfds</parameter> argument is less than
zero or greater than <constant>FD_SETSIZE</constant>.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/func-write.xml
+128
View File
@@ -0,0 +1,128 @@
<refentry id="func-write">
<refmeta>
<refentrytitle>V4L2 write()</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>v4l2-write</refname>
<refpurpose>Write to a V4L2 device</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;unistd.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>ssize_t <function>write</function></funcdef>
<paramdef>int <parameter>fd</parameter></paramdef>
<paramdef>void *<parameter>buf</parameter></paramdef>
<paramdef>size_t <parameter>count</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>fd</parameter></term>
<listitem>
<para>&fd;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>buf</parameter></term>
<listitem>
<para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>count</parameter></term>
<listitem>
<para></para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para><function>write()</function> writes up to
<parameter>count</parameter> bytes to the device referenced by the
file descriptor <parameter>fd</parameter> from the buffer starting at
<parameter>buf</parameter>. When the hardware outputs are not active
yet, this function enables them. When <parameter>count</parameter> is
zero, <function>write()</function> returns
<returnvalue>0</returnvalue> without any other effect.</para>
<para>When the application does not provide more data in time, the
previous video frame, raw VBI image, sliced VPS or WSS data is
displayed again. Sliced Teletext or Closed Caption data is not
repeated, the driver inserts a blank line instead.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>On success, the number of bytes written are returned. Zero
indicates nothing was written. On error, <returnvalue>-1</returnvalue>
is returned, and the <varname>errno</varname> variable is set
appropriately. In this case the next write will start at the beginning
of a new frame. Possible error codes are:</para>
<variablelist>
<varlistentry>
<term><errorcode>EAGAIN</errorcode></term>
<listitem>
<para>Non-blocking I/O has been selected using the <link
linkend="func-open"><constant>O_NONBLOCK</constant></link> flag and no
buffer space was available to write the data immediately.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EBADF</errorcode></term>
<listitem>
<para><parameter>fd</parameter> is not a valid file
descriptor or is not open for writing.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EBUSY</errorcode></term>
<listitem>
<para>The driver does not support multiple write streams and the
device is already in use.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EFAULT</errorcode></term>
<listitem>
<para><parameter>buf</parameter> references an inaccessible
memory area.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EINTR</errorcode></term>
<listitem>
<para>The call was interrupted by a signal before any
data was written.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EIO</errorcode></term>
<listitem>
<para>I/O error. This indicates some hardware problem.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EINVAL</errorcode></term>
<listitem>
<para>The <function>write()</function> function is not
supported by this driver, not on this device, or generally not on this
type of device.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/gen-errors.xml
+78
View File
@@ -0,0 +1,78 @@
<title>Generic Error Codes</title>
<table frame="none" pgwide="1" id="gen-errors">
<title>Generic error codes</title>
<tgroup cols="2">
&cs-str;
<tbody valign="top">
<!-- Keep it ordered alphabetically -->
<row>
<entry>EBADF</entry>
<entry>The file descriptor is not a valid.</entry>
</row>
<row>
<entry>EBUSY</entry>
<entry>The ioctl can't be handled because the device is busy. This is
typically return while device is streaming, and an ioctl tried to
change something that would affect the stream, or would require the
usage of a hardware resource that was already allocated. The ioctl
must not be retried without performing another action to fix the
problem first (typically: stop the stream before retrying).</entry>
</row>
<row>
<entry>EFAULT</entry>
<entry>There was a failure while copying data from/to userspace,
probably caused by an invalid pointer reference.</entry>
</row>
<row>
<entry>EINVAL</entry>
<entry>One or more of the ioctl parameters are invalid or out of the
allowed range. This is a widely used error code. See the individual
ioctl requests for specific causes.</entry>
</row>
<row>
<entry>ENODEV</entry>
<entry>Device not found or was removed.</entry>
</row>
<row>
<entry>ENOMEM</entry>
<entry>There's not enough memory to handle the desired operation.</entry>
</row>
<row>
<entry>ENOTTY</entry>
<entry>The ioctl is not supported by the driver, actually meaning that
the required functionality is not available, or the file
descriptor is not for a media device.</entry>
</row>
<row>
<entry>ENOSPC</entry>
<entry>On USB devices, the stream ioctl's can return this error, meaning
that this request would overcommit the usb bandwidth reserved
for periodic transfers (up to 80% of the USB bandwidth).</entry>
</row>
<row>
<entry>ENOSYS or EOPNOTSUPP</entry>
<entry>Function not available for this device (dvb API only. Will likely
be replaced anytime soon by ENOTTY).</entry>
</row>
<row>
<entry>EPERM</entry>
<entry>Permission denied. Can be returned if the device needs write
permission, or some special capabilities is needed
(e. g. root)</entry>
</row>
<row>
<entry>EWOULDBLOCK</entry>
<entry>Operation would block. Used when the ioctl would need to wait
for an event, but the device was opened in non-blocking mode.</entry>
</row>
</tbody>
</tgroup>
</table>
<para>Note 1: ioctls may return other error codes. Since errors may have side
effects such as a driver reset, applications should abort on unexpected errors.
</para>
<para>Note 2: Request-specific error codes are listed in the individual
requests descriptions.</para>
kernel/Documentation/DocBook/media/v4l/io.xml
+1284
View File
File diff suppressed because it is too large Load Diff
kernel/Documentation/DocBook/media/v4l/keytable.c.xml
+172
View File
@@ -0,0 +1,172 @@
<programlisting>
/* keytable.c - This program allows checking/replacing keys at IR
Copyright (C) 2006-2009 Mauro Carvalho Chehab &lt;mchehab@infradead.org&gt;
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, version 2 of the License.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
*/
#include &lt;ctype.h&gt;
#include &lt;errno.h&gt;
#include &lt;fcntl.h&gt;
#include &lt;stdio.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;string.h&gt;
#include &lt;linux/input.h&gt;
#include &lt;sys/ioctl.h&gt;
#include "parse.h"
void prtcode (int *codes)
{
struct parse_key *p;
for (p=keynames;p-&gt;name!=NULL;p++) {
if (p-&gt;value == (unsigned)codes[1]) {
printf("scancode 0x%04x = %s (0x%02x)\n", codes[0], p-&gt;name, codes[1]);
return;
}
}
if (isprint (codes[1]))
printf("scancode %d = '%c' (0x%02x)\n", codes[0], codes[1], codes[1]);
else
printf("scancode %d = 0x%02x\n", codes[0], codes[1]);
}
int parse_code(char *string)
{
struct parse_key *p;
for (p=keynames;p-&gt;name!=NULL;p++) {
if (!strcasecmp(p-&gt;name, string)) {
return p-&gt;value;
}
}
return -1;
}
int main (int argc, char *argv[])
{
int fd;
unsigned int i, j;
int codes[2];
if (argc&lt;2 || argc&gt;4) {
printf ("usage: %s &lt;device&gt; to get table; or\n"
" %s &lt;device&gt; &lt;scancode&gt; &lt;keycode&gt;\n"
" %s &lt;device&gt; &lt;keycode_file&gt;\n",*argv,*argv,*argv);
return -1;
}
if ((fd = open(argv[1], O_RDONLY)) &lt; 0) {
perror("Couldn't open input device");
return(-1);
}
if (argc==4) {
int value;
value=parse_code(argv[3]);
if (value==-1) {
value = strtol(argv[3], NULL, 0);
if (errno)
perror("value");
}
codes [0] = (unsigned) strtol(argv[2], NULL, 0);
codes [1] = (unsigned) value;
if(ioctl(fd, EVIOCSKEYCODE, codes))
perror ("EVIOCSKEYCODE");
if(ioctl(fd, EVIOCGKEYCODE, codes)==0)
prtcode(codes);
return 0;
}
if (argc==3) {
FILE *fin;
int value;
char *scancode, *keycode, s[2048];
fin=fopen(argv[2],"r");
if (fin==NULL) {
perror ("opening keycode file");
return -1;
}
/* Clears old table */
for (j = 0; j &lt; 256; j++) {
for (i = 0; i &lt; 256; i++) {
codes[0] = (j &lt;&lt; 8) | i;
codes[1] = KEY_RESERVED;
ioctl(fd, EVIOCSKEYCODE, codes);
}
}
while (fgets(s,sizeof(s),fin)) {
scancode=strtok(s,"\n\t =:");
if (!scancode) {
perror ("parsing input file scancode");
return -1;
}
if (!strcasecmp(scancode, "scancode")) {
scancode = strtok(NULL,"\n\t =:");
if (!scancode) {
perror ("parsing input file scancode");
return -1;
}
}
keycode=strtok(NULL,"\n\t =:(");
if (!keycode) {
perror ("parsing input file keycode");
return -1;
}
// printf ("parsing %s=%s:", scancode, keycode);
value=parse_code(keycode);
// printf ("\tvalue=%d\n",value);
if (value==-1) {
value = strtol(keycode, NULL, 0);
if (errno)
perror("value");
}
codes [0] = (unsigned) strtol(scancode, NULL, 0);
codes [1] = (unsigned) value;
// printf("\t%04x=%04x\n",codes[0], codes[1]);
if(ioctl(fd, EVIOCSKEYCODE, codes)) {
fprintf(stderr, "Setting scancode 0x%04x with 0x%04x via ",codes[0], codes[1]);
perror ("EVIOCSKEYCODE");
}
if(ioctl(fd, EVIOCGKEYCODE, codes)==0)
prtcode(codes);
}
return 0;
}
/* Get scancode table */
for (j = 0; j &lt; 256; j++) {
for (i = 0; i &lt; 256; i++) {
codes[0] = (j &lt;&lt; 8) | i;
if (!ioctl(fd, EVIOCGKEYCODE, codes) &amp;&amp; codes[1] != KEY_RESERVED)
prtcode(codes);
}
}
return 0;
}
</programlisting>
kernel/Documentation/DocBook/media/v4l/libv4l.xml
+160
View File
@@ -0,0 +1,160 @@
<title>Libv4l Userspace Library</title>
<section id="libv4l-introduction">
<title>Introduction</title>
<para>libv4l is a collection of libraries which adds a thin abstraction
layer on top of video4linux2 devices. The purpose of this (thin) layer
is to make it easy for application writers to support a wide variety of
devices without having to write separate code for different devices in the
same class.</para>
<para>An example of using libv4l is provided by
<link linkend='v4l2grab-example'>v4l2grab</link>.
</para>
<para>libv4l consists of 3 different libraries:</para>
<section>
<title>libv4lconvert</title>
<para>libv4lconvert is a library that converts several
different pixelformats found in V4L2 drivers into a few common RGB and
YUY formats.</para>
<para>It currently accepts the following V4L2 driver formats:
<link linkend="V4L2-PIX-FMT-BGR24"><constant>V4L2_PIX_FMT_BGR24</constant></link>,
<link linkend="V4L2-PIX-FMT-HM12"><constant>V4L2_PIX_FMT_HM12</constant></link>,
<link linkend="V4L2-PIX-FMT-JPEG"><constant>V4L2_PIX_FMT_JPEG</constant></link>,
<link linkend="V4L2-PIX-FMT-MJPEG"><constant>V4L2_PIX_FMT_MJPEG</constant></link>,
<link linkend="V4L2-PIX-FMT-MR97310A"><constant>V4L2_PIX_FMT_MR97310A</constant></link>,
<link linkend="V4L2-PIX-FMT-OV511"><constant>V4L2_PIX_FMT_OV511</constant></link>,
<link linkend="V4L2-PIX-FMT-OV518"><constant>V4L2_PIX_FMT_OV518</constant></link>,
<link linkend="V4L2-PIX-FMT-PAC207"><constant>V4L2_PIX_FMT_PAC207</constant></link>,
<link linkend="V4L2-PIX-FMT-PJPG"><constant>V4L2_PIX_FMT_PJPG</constant></link>,
<link linkend="V4L2-PIX-FMT-RGB24"><constant>V4L2_PIX_FMT_RGB24</constant></link>,
<link linkend="V4L2-PIX-FMT-SBGGR8"><constant>V4L2_PIX_FMT_SBGGR8</constant></link>,
<link linkend="V4L2-PIX-FMT-SGBRG8"><constant>V4L2_PIX_FMT_SGBRG8</constant></link>,
<link linkend="V4L2-PIX-FMT-SGRBG8"><constant>V4L2_PIX_FMT_SGRBG8</constant></link>,
<link linkend="V4L2-PIX-FMT-SN9C10X"><constant>V4L2_PIX_FMT_SN9C10X</constant></link>,
<link linkend="V4L2-PIX-FMT-SN9C20X-I420"><constant>V4L2_PIX_FMT_SN9C20X_I420</constant></link>,
<link linkend="V4L2-PIX-FMT-SPCA501"><constant>V4L2_PIX_FMT_SPCA501</constant></link>,
<link linkend="V4L2-PIX-FMT-SPCA505"><constant>V4L2_PIX_FMT_SPCA505</constant></link>,
<link linkend="V4L2-PIX-FMT-SPCA508"><constant>V4L2_PIX_FMT_SPCA508</constant></link>,
<link linkend="V4L2-PIX-FMT-SPCA561"><constant>V4L2_PIX_FMT_SPCA561</constant></link>,
<link linkend="V4L2-PIX-FMT-SQ905C"><constant>V4L2_PIX_FMT_SQ905C</constant></link>,
<constant>V4L2_PIX_FMT_SRGGB8</constant>,
<link linkend="V4L2-PIX-FMT-UYVY"><constant>V4L2_PIX_FMT_UYVY</constant></link>,
<link linkend="V4L2-PIX-FMT-YUV420"><constant>V4L2_PIX_FMT_YUV420</constant></link>,
<link linkend="V4L2-PIX-FMT-YUYV"><constant>V4L2_PIX_FMT_YUYV</constant></link>,
<link linkend="V4L2-PIX-FMT-YVU420"><constant>V4L2_PIX_FMT_YVU420</constant></link>,
and <link linkend="V4L2-PIX-FMT-YVYU"><constant>V4L2_PIX_FMT_YVYU</constant></link>.
</para>
<para>Later on libv4lconvert was expanded to also be able to do
various video processing functions to improve webcam video quality.
The video processing is split in to 2 parts: libv4lconvert/control and
libv4lconvert/processing.</para>
<para>The control part is used to offer video controls which can
be used to control the video processing functions made available by
libv4lconvert/processing. These controls are stored application wide
(until reboot) by using a persistent shared memory object.</para>
<para>libv4lconvert/processing offers the actual video
processing functionality.</para>
</section>
<section>
<title>libv4l1</title>
<para>This library offers functions that can be used to quickly
make v4l1 applications work with v4l2 devices. These functions work exactly
like the normal open/close/etc, except that libv4l1 does full emulation of
the v4l1 api on top of v4l2 drivers, in case of v4l1 drivers it
will just pass calls through.</para>
<para>Since those functions are emulations of the old V4L1 API,
it shouldn't be used for new applications.</para>
</section>
<section>
<title>libv4l2</title>
<para>This library should be used for all modern V4L2
applications.</para>
<para>It provides handles to call V4L2 open/ioctl/close/poll
methods. Instead of just providing the raw output of the device, it enhances
the calls in the sense that it will use libv4lconvert to provide more video
formats and to enhance the image quality.</para>
<para>In most cases, libv4l2 just passes the calls directly
through to the v4l2 driver, intercepting the calls to
<link linkend='vidioc-g-fmt'><constant>VIDIOC_TRY_FMT</constant></link>,
<link linkend='vidioc-g-fmt'><constant>VIDIOC_G_FMT</constant></link>
<link linkend='vidioc-g-fmt'><constant>VIDIOC_S_FMT</constant></link>
<link linkend='vidioc-enum-framesizes'><constant>VIDIOC_ENUM_FRAMESIZES</constant></link>
and <link linkend='vidioc-enum-frameintervals'><constant>VIDIOC_ENUM_FRAMEINTERVALS</constant></link>
in order to emulate the formats
<link linkend="V4L2-PIX-FMT-BGR24"><constant>V4L2_PIX_FMT_BGR24</constant></link>,
<link linkend="V4L2-PIX-FMT-RGB24"><constant>V4L2_PIX_FMT_RGB24</constant></link>,
<link linkend="V4L2-PIX-FMT-YUV420"><constant>V4L2_PIX_FMT_YUV420</constant></link>,
and <link linkend="V4L2-PIX-FMT-YVU420"><constant>V4L2_PIX_FMT_YVU420</constant></link>,
if they aren't available in the driver.
<link linkend='vidioc-enum-fmt'><constant>VIDIOC_ENUM_FMT</constant></link>
keeps enumerating the hardware supported formats, plus the emulated formats
offered by libv4l at the end.
</para>
<section id="libv4l-ops">
<title>Libv4l device control functions</title>
<para>The common file operation methods are provided by
libv4l.</para>
<para>Those functions operate just like glibc
open/close/dup/ioctl/read/mmap/munmap:</para>
<itemizedlist><listitem>
<para>int v4l2_open(const char *file, int oflag,
...) -
operates like the standard <link linkend='func-open'>open()</link> function.
</para></listitem><listitem>
<para>int v4l2_close(int fd) -
operates like the standard <link linkend='func-close'>close()</link> function.
</para></listitem><listitem>
<para>int v4l2_dup(int fd) -
operates like the standard dup() function, duplicating a file handler.
</para></listitem><listitem>
<para>int v4l2_ioctl (int fd, unsigned long int request, ...) -
operates like the standard <link linkend='func-ioctl'>ioctl()</link> function.
</para></listitem><listitem>
<para>int v4l2_read (int fd, void* buffer, size_t n) -
operates like the standard <link linkend='func-read'>read()</link> function.
</para></listitem><listitem>
<para>void v4l2_mmap(void *start, size_t length, int prot, int flags, int fd, int64_t offset); -
operates like the standard <link linkend='func-mmap'>mmap()</link> function.
</para></listitem><listitem>
<para>int v4l2_munmap(void *_start, size_t length); -
operates like the standard <link linkend='func-munmap'>munmap()</link> function.
</para></listitem>
</itemizedlist>
<para>Those functions provide additional control:</para>
<itemizedlist><listitem>
<para>int v4l2_fd_open(int fd, int v4l2_flags) -
opens an already opened fd for further use through v4l2lib and possibly
modify libv4l2's default behavior through the v4l2_flags argument.
Currently, v4l2_flags can be <constant>V4L2_DISABLE_CONVERSION</constant>,
to disable format conversion.
</para></listitem><listitem>
<para>int v4l2_set_control(int fd, int cid, int value) -
This function takes a value of 0 - 65535, and then scales that range to
the actual range of the given v4l control id, and then if the cid exists
and is not locked sets the cid to the scaled value.
</para></listitem><listitem>
<para>int v4l2_get_control(int fd, int cid) -
This function returns a value of 0 - 65535, scaled to from the actual range
of the given v4l control id. when the cid does not exist, could not be
accessed for some reason, or some error occurred 0 is returned.
</para></listitem>
</itemizedlist>
</section>
</section>
<section>
<title>v4l1compat.so wrapper library</title>
<para>This library intercepts calls to
open/close/ioctl/mmap/mmunmap operations and redirects them to the libv4l
counterparts, by using LD_PRELOAD=/usr/lib/v4l1compat.so. It also
emulates V4L1 calls via V4L2 API.</para>
<para>It allows usage of binary legacy applications that
still don't use libv4l.</para>
</section>
</section>
kernel/Documentation/DocBook/media/v4l/lirc_device_interface.xml
+253
View File
@@ -0,0 +1,253 @@
<section id="lirc_dev">
<title>LIRC Device Interface</title>
<section id="lirc_dev_intro">
<title>Introduction</title>
<para>The LIRC device interface is a bi-directional interface for
transporting raw IR data between userspace and kernelspace. Fundamentally,
it is just a chardev (/dev/lircX, for X = 0, 1, 2, ...), with a number
of standard struct file_operations defined on it. With respect to
transporting raw IR data to and fro, the essential fops are read, write
and ioctl.</para>
<para>Example dmesg output upon a driver registering w/LIRC:</para>
<blockquote>
<para>$ dmesg |grep lirc_dev</para>
<para>lirc_dev: IR Remote Control driver registered, major 248</para>
<para>rc rc0: lirc_dev: driver ir-lirc-codec (mceusb) registered at minor = 0</para>
</blockquote>
<para>What you should see for a chardev:</para>
<blockquote>
<para>$ ls -l /dev/lirc*</para>
<para>crw-rw---- 1 root root 248, 0 Jul 2 22:20 /dev/lirc0</para>
</blockquote>
</section>
<section id="lirc_read">
<title>LIRC read fop</title>
<para>The lircd userspace daemon reads raw IR data from the LIRC chardev. The
exact format of the data depends on what modes a driver supports, and what
mode has been selected. lircd obtains supported modes and sets the active mode
via the ioctl interface, detailed at <xref linkend="lirc_ioctl"/>. The generally
preferred mode is LIRC_MODE_MODE2, in which packets containing an int value
describing an IR signal are read from the chardev.</para>
<para>See also <ulink url="http://www.lirc.org/html/technical.html">http://www.lirc.org/html/technical.html</ulink> for more info.</para>
</section>
<section id="lirc_write">
<title>LIRC write fop</title>
<para>The data written to the chardev is a pulse/space sequence of integer
values. Pulses and spaces are only marked implicitly by their position. The
data must start and end with a pulse, therefore, the data must always include
an uneven number of samples. The write function must block until the data has
been transmitted by the hardware.</para>
</section>
<section id="lirc_ioctl">
<title>LIRC ioctl fop</title>
<para>The LIRC device's ioctl definition is bound by the ioctl function
definition of struct file_operations, leaving us with an unsigned int
for the ioctl command and an unsigned long for the arg. For the purposes
of ioctl portability across 32-bit and 64-bit, these values are capped
to their 32-bit sizes.</para>
<para>The following ioctls can be used to change specific hardware settings.
In general each driver should have a default set of settings. The driver
implementation is expected to re-apply the default settings when the device
is closed by user-space, so that every application opening the device can rely
on working with the default settings initially.</para>
<variablelist>
<varlistentry>
<term>LIRC_GET_FEATURES</term>
<listitem>
<para>Obviously, get the underlying hardware device's features. If a driver
does not announce support of certain features, calling of the corresponding
ioctls is undefined.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LIRC_GET_SEND_MODE</term>
<listitem>
<para>Get supported transmit mode. Only LIRC_MODE_PULSE is supported by lircd.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LIRC_GET_REC_MODE</term>
<listitem>
<para>Get supported receive modes. Only LIRC_MODE_MODE2 and LIRC_MODE_LIRCCODE
are supported by lircd.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LIRC_GET_SEND_CARRIER</term>
<listitem>
<para>Get carrier frequency (in Hz) currently used for transmit.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LIRC_GET_REC_CARRIER</term>
<listitem>
<para>Get carrier frequency (in Hz) currently used for IR reception.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LIRC_{G,S}ET_{SEND,REC}_DUTY_CYCLE</term>
<listitem>
<para>Get/set the duty cycle (from 0 to 100) of the carrier signal. Currently,
no special meaning is defined for 0 or 100, but this could be used to switch
off carrier generation in the future, so these values should be reserved.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LIRC_GET_REC_RESOLUTION</term>
<listitem>
<para>Some receiver have maximum resolution which is defined by internal
sample rate or data format limitations. E.g. it's common that signals can
only be reported in 50 microsecond steps. This integer value is used by
lircd to automatically adjust the aeps tolerance value in the lircd
config file.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LIRC_GET_M{IN,AX}_TIMEOUT</term>
<listitem>
<para>Some devices have internal timers that can be used to detect when
there's no IR activity for a long time. This can help lircd in detecting
that a IR signal is finished and can speed up the decoding process.
Returns an integer value with the minimum/maximum timeout that can be
set. Some devices have a fixed timeout, in that case both ioctls will
return the same value even though the timeout cannot be changed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LIRC_GET_M{IN,AX}_FILTER_{PULSE,SPACE}</term>
<listitem>
<para>Some devices are able to filter out spikes in the incoming signal
using given filter rules. These ioctls return the hardware capabilities
that describe the bounds of the possible filters. Filter settings depend
on the IR protocols that are expected. lircd derives the settings from
all protocols definitions found in its config file.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LIRC_GET_LENGTH</term>
<listitem>
<para>Retrieves the code length in bits (only for LIRC_MODE_LIRCCODE).
Reads on the device must be done in blocks matching the bit count.
The bit could should be rounded up so that it matches full bytes.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LIRC_SET_{SEND,REC}_MODE</term>
<listitem>
<para>Set send/receive mode. Largely obsolete for send, as only
LIRC_MODE_PULSE is supported.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LIRC_SET_{SEND,REC}_CARRIER</term>
<listitem>
<para>Set send/receive carrier (in Hz).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LIRC_SET_TRANSMITTER_MASK</term>
<listitem>
<para>This enables the given set of transmitters. The first transmitter
is encoded by the least significant bit, etc. When an invalid bit mask
is given, i.e. a bit is set, even though the device does not have so many
transitters, then this ioctl returns the number of available transitters
and does nothing otherwise.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LIRC_SET_REC_TIMEOUT</term>
<listitem>
<para>Sets the integer value for IR inactivity timeout (cf.
LIRC_GET_MIN_TIMEOUT and LIRC_GET_MAX_TIMEOUT). A value of 0 (if
supported by the hardware) disables all hardware timeouts and data should
be reported as soon as possible. If the exact value cannot be set, then
the next possible value _greater_ than the given value should be set.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LIRC_SET_REC_TIMEOUT_REPORTS</term>
<listitem>
<para>Enable (1) or disable (0) timeout reports in LIRC_MODE_MODE2. By
default, timeout reports should be turned off.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LIRC_SET_REC_FILTER_{,PULSE,SPACE}</term>
<listitem>
<para>Pulses/spaces shorter than this are filtered out by hardware. If
filters cannot be set independently for pulse/space, the corresponding
ioctls must return an error and LIRC_SET_REC_FILTER shall be used instead.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LIRC_SET_MEASURE_CARRIER_MODE</term>
<listitem>
<para>Enable (1)/disable (0) measure mode. If enabled, from the next key
press on, the driver will send LIRC_MODE2_FREQUENCY packets. By default
this should be turned off.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LIRC_SET_REC_{DUTY_CYCLE,CARRIER}_RANGE</term>
<listitem>
<para>To set a range use LIRC_SET_REC_DUTY_CYCLE_RANGE/LIRC_SET_REC_CARRIER_RANGE
with the lower bound first and later LIRC_SET_REC_DUTY_CYCLE/LIRC_SET_REC_CARRIER
with the upper bound.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LIRC_NOTIFY_DECODE</term>
<listitem>
<para>This ioctl is called by lircd whenever a successful decoding of an
incoming IR signal could be done. This can be used by supporting hardware
to give visual feedback to the user e.g. by flashing a LED.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LIRC_SETUP_{START,END}</term>
<listitem>
<para>Setting of several driver parameters can be optimized by encapsulating
the according ioctl calls with LIRC_SETUP_START/LIRC_SETUP_END. When a
driver receives a LIRC_SETUP_START ioctl it can choose to not commit
further setting changes to the hardware until a LIRC_SETUP_END is received.
But this is open to the driver implementation and every driver must also
handle parameter changes which are not encapsulated by LIRC_SETUP_START
and LIRC_SETUP_END. Drivers can also choose to ignore these ioctls.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LIRC_SET_WIDEBAND_RECEIVER</term>
<listitem>
<para>Some receivers are equipped with special wide band receiver which is intended
to be used to learn output of existing remote.
Calling that ioctl with (1) will enable it, and with (0) disable it.
This might be useful of receivers that have otherwise narrow band receiver
that prevents them to be used with some remotes.
Wide band receiver might also be more precise
On the other hand its disadvantage it usually reduced range of reception.
Note: wide band receiver might be implictly enabled if you enable
carrier reports. In that case it will be disabled as soon as you disable
carrier reports. Trying to disable wide band receiver while carrier
reports are active will do nothing.</para>
</listitem>
</varlistentry>
</variablelist>
<section id="lirc_dev_errors">
&return-value;
</section>
</section>
</section>
kernel/Documentation/DocBook/media/v4l/media-controller.xml
+89
View File
@@ -0,0 +1,89 @@
<partinfo>
<authorgroup>
<author>
<firstname>Laurent</firstname>
<surname>Pinchart</surname>
<affiliation><address><email>laurent.pinchart@ideasonboard.com</email></address></affiliation>
<contrib>Initial version.</contrib>
</author>
</authorgroup>
<copyright>
<year>2010</year>
<holder>Laurent Pinchart</holder>
</copyright>
<revhistory>
<!-- Put document revisions here, newest first. -->
<revision>
<revnumber>1.0.0</revnumber>
<date>2010-11-10</date>
<authorinitials>lp</authorinitials>
<revremark>Initial revision</revremark>
</revision>
</revhistory>
</partinfo>
<title>Media Controller API</title>
<chapter id="media_controller">
<title>Media Controller</title>
<section id="media-controller-intro">
<title>Introduction</title>
<para>Media devices increasingly handle multiple related functions. Many USB
cameras include microphones, video capture hardware can also output video,
or SoC camera interfaces also perform memory-to-memory operations similar to
video codecs.</para>
<para>Independent functions, even when implemented in the same hardware, can
be modelled as separate devices. A USB camera with a microphone will be
presented to userspace applications as V4L2 and ALSA capture devices. The
devices' relationships (when using a webcam, end-users shouldn't have to
manually select the associated USB microphone), while not made available
directly to applications by the drivers, can usually be retrieved from
sysfs.</para>
<para>With more and more advanced SoC devices being introduced, the current
approach will not scale. Device topologies are getting increasingly complex
and can't always be represented by a tree structure. Hardware blocks are
shared between different functions, creating dependencies between seemingly
unrelated devices.</para>
<para>Kernel abstraction APIs such as V4L2 and ALSA provide means for
applications to access hardware parameters. As newer hardware expose an
increasingly high number of those parameters, drivers need to guess what
applications really require based on limited information, thereby
implementing policies that belong to userspace.</para>
<para>The media controller API aims at solving those problems.</para>
</section>
<section id="media-controller-model">
<title>Media device model</title>
<para>Discovering a device internal topology, and configuring it at runtime,
is one of the goals of the media controller API. To achieve this, hardware
devices are modelled as an oriented graph of building blocks called entities
connected through pads.</para>
<para>An entity is a basic media hardware or software building block. It can
correspond to a large variety of logical blocks such as physical hardware
devices (CMOS sensor for instance), logical hardware devices (a building
block in a System-on-Chip image processing pipeline), DMA channels or
physical connectors.</para>
<para>A pad is a connection endpoint through which an entity can interact
with other entities. Data (not restricted to video) produced by an entity
flows from the entity's output to one or more entity inputs. Pads should not
be confused with physical pins at chip boundaries.</para>
<para>A link is a point-to-point oriented connection between two pads,
either on the same entity or on different entities. Data flows from a source
pad to a sink pad.</para>
</section>
</chapter>
<appendix id="media-user-func">
<title>Function Reference</title>
<!-- Keep this alphabetically sorted. -->
&sub-media-func-open;
&sub-media-func-close;
&sub-media-func-ioctl;
<!-- All ioctls go here. -->
&sub-media-ioc-device-info;
&sub-media-ioc-enum-entities;
&sub-media-ioc-enum-links;
&sub-media-ioc-setup-link;
</appendix>
kernel/Documentation/DocBook/media/v4l/media-func-close.xml
+59
View File
@@ -0,0 +1,59 @@
<refentry id="media-func-close">
<refmeta>
<refentrytitle>media close()</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>media-close</refname>
<refpurpose>Close a media device</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;unistd.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>close</function></funcdef>
<paramdef>int <parameter>fd</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>fd</parameter></term>
<listitem>
<para>&fd;</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>Closes the media device. Resources associated with the file descriptor
are freed. The device configuration remain unchanged.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para><function>close</function> returns 0 on success. On error, -1 is
returned, and <varname>errno</varname> is set appropriately. Possible error
codes are:</para>
<variablelist>
<varlistentry>
<term><errorcode>EBADF</errorcode></term>
<listitem>
<para><parameter>fd</parameter> is not a valid open file descriptor.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/media-func-ioctl.xml
+73
View File
@@ -0,0 +1,73 @@
<refentry id="media-func-ioctl">
<refmeta>
<refentrytitle>media ioctl()</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>media-ioctl</refname>
<refpurpose>Control a media device</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;sys/ioctl.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>ioctl</function></funcdef>
<paramdef>int <parameter>fd</parameter></paramdef>
<paramdef>int <parameter>request</parameter></paramdef>
<paramdef>void *<parameter>argp</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>fd</parameter></term>
<listitem>
<para>&fd;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>request</parameter></term>
<listitem>
<para>Media ioctl request code as defined in the media.h header file,
for example MEDIA_IOC_SETUP_LINK.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>argp</parameter></term>
<listitem>
<para>Pointer to a request-specific structure.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>The <function>ioctl()</function> function manipulates media device
parameters. The argument <parameter>fd</parameter> must be an open file
descriptor.</para>
<para>The ioctl <parameter>request</parameter> code specifies the media
function to be called. It has encoded in it whether the argument is an
input, output or read/write parameter, and the size of the argument
<parameter>argp</parameter> in bytes.</para>
<para>Macros and structures definitions specifying media ioctl requests and
their parameters are located in the media.h header file. All media ioctl
requests, their respective function and parameters are specified in
<xref linkend="media-user-func" />.</para>
</refsect1>
<refsect1>
&return-value;
<para>Request-specific error codes are listed in the
individual requests descriptions.</para>
<para>When an ioctl that takes an output or read/write parameter fails,
the parameter remains unmodified.</para>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/media-func-open.xml
+94
View File
@@ -0,0 +1,94 @@
<refentry id="media-func-open">
<refmeta>
<refentrytitle>media open()</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>media-open</refname>
<refpurpose>Open a media device</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;fcntl.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>open</function></funcdef>
<paramdef>const char *<parameter>device_name</parameter></paramdef>
<paramdef>int <parameter>flags</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>device_name</parameter></term>
<listitem>
<para>Device to be opened.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>flags</parameter></term>
<listitem>
<para>Open flags. Access mode must be either <constant>O_RDONLY</constant>
or <constant>O_RDWR</constant>. Other flags have no effect.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>To open a media device applications call <function>open()</function>
with the desired device name. The function has no side effects; the device
configuration remain unchanged.</para>
<para>When the device is opened in read-only mode, attemps to modify its
configuration will result in an error, and <varname>errno</varname> will be
set to <errorcode>EBADF</errorcode>.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para><function>open</function> returns the new file descriptor on success.
On error, -1 is returned, and <varname>errno</varname> is set appropriately.
Possible error codes are:</para>
<variablelist>
<varlistentry>
<term><errorcode>EACCES</errorcode></term>
<listitem>
<para>The requested access to the file is not allowed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EMFILE</errorcode></term>
<listitem>
<para>The process already has the maximum number of files open.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>ENFILE</errorcode></term>
<listitem>
<para>The system limit on the total number of open files has been
reached.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>ENOMEM</errorcode></term>
<listitem>
<para>Insufficient kernel memory was available.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>ENXIO</errorcode></term>
<listitem>
<para>No device corresponding to this device special file exists.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/media-ioc-device-info.xml
+132
View File
@@ -0,0 +1,132 @@
<refentry id="media-ioc-device-info">
<refmeta>
<refentrytitle>ioctl MEDIA_IOC_DEVICE_INFO</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>MEDIA_IOC_DEVICE_INFO</refname>
<refpurpose>Query device information</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ioctl</function></funcdef>
<paramdef>int <parameter>fd</parameter></paramdef>
<paramdef>int <parameter>request</parameter></paramdef>
<paramdef>struct media_device_info *<parameter>argp</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>fd</parameter></term>
<listitem>
<para>File descriptor returned by
<link linkend='media-func-open'><function>open()</function></link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>request</parameter></term>
<listitem>
<para>MEDIA_IOC_DEVICE_INFO</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>argp</parameter></term>
<listitem>
<para></para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>All media devices must support the <constant>MEDIA_IOC_DEVICE_INFO</constant>
ioctl. To query device information, applications call the ioctl with a
pointer to a &media-device-info;. The driver fills the structure and returns
the information to the application.
The ioctl never fails.</para>
<table pgwide="1" frame="none" id="media-device-info">
<title>struct <structname>media_device_info</structname></title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>char</entry>
<entry><structfield>driver</structfield>[16]</entry>
<entry><para>Name of the driver implementing the media API as a
NUL-terminated ASCII string. The driver version is stored in the
<structfield>driver_version</structfield> field.</para>
<para>Driver specific applications can use this information to
verify the driver identity. It is also useful to work around
known bugs, or to identify drivers in error reports.</para></entry>
</row>
<row>
<entry>char</entry>
<entry><structfield>model</structfield>[32]</entry>
<entry>Device model name as a NUL-terminated UTF-8 string. The
device version is stored in the <structfield>device_version</structfield>
field and is not be appended to the model name.</entry>
</row>
<row>
<entry>char</entry>
<entry><structfield>serial</structfield>[40]</entry>
<entry>Serial number as a NUL-terminated ASCII string.</entry>
</row>
<row>
<entry>char</entry>
<entry><structfield>bus_info</structfield>[32]</entry>
<entry>Location of the device in the system as a NUL-terminated
ASCII string. This includes the bus type name (PCI, USB, ...) and a
bus-specific identifier.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>media_version</structfield></entry>
<entry>Media API version, formatted with the
<constant>KERNEL_VERSION()</constant> macro.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>hw_revision</structfield></entry>
<entry>Hardware device revision in a driver-specific format.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>media_version</structfield></entry>
<entry>Media device driver version, formatted with the
<constant>KERNEL_VERSION()</constant> macro. Together with the
<structfield>driver</structfield> field this identifies a particular
driver.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>reserved</structfield>[31]</entry>
<entry>Reserved for future extensions. Drivers and applications must
set this array to zero.</entry>
</row>
</tbody>
</tgroup>
</table>
<para>The <structfield>serial</structfield> and <structfield>bus_info</structfield>
fields can be used to distinguish between multiple instances of otherwise
identical hardware. The serial number takes precedence when provided and can
be assumed to be unique. If the serial number is an empty string, the
<structfield>bus_info</structfield> field can be used instead. The
<structfield>bus_info</structfield> field is guaranteed to be unique, but
can vary across reboots or device unplug/replug.</para>
</refsect1>
<refsect1>
&return-value;
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/media-ioc-enum-entities.xml
+308
View File
@@ -0,0 +1,308 @@
<refentry id="media-ioc-enum-entities">
<refmeta>
<refentrytitle>ioctl MEDIA_IOC_ENUM_ENTITIES</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>MEDIA_IOC_ENUM_ENTITIES</refname>
<refpurpose>Enumerate entities and their properties</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ioctl</function></funcdef>
<paramdef>int <parameter>fd</parameter></paramdef>
<paramdef>int <parameter>request</parameter></paramdef>
<paramdef>struct media_entity_desc *<parameter>argp</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>fd</parameter></term>
<listitem>
<para>File descriptor returned by
<link linkend='media-func-open'><function>open()</function></link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>request</parameter></term>
<listitem>
<para>MEDIA_IOC_ENUM_ENTITIES</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>argp</parameter></term>
<listitem>
<para></para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>To query the attributes of an entity, applications set the id field
of a &media-entity-desc; structure and call the MEDIA_IOC_ENUM_ENTITIES
ioctl with a pointer to this structure. The driver fills the rest of the
structure or returns an &EINVAL; when the id is invalid.</para>
<para>Entities can be enumerated by or'ing the id with the
<constant>MEDIA_ENT_ID_FLAG_NEXT</constant> flag. The driver will return
information about the entity with the smallest id strictly larger than the
requested one ('next entity'), or the &EINVAL; if there is none.</para>
<para>Entity IDs can be non-contiguous. Applications must
<emphasis>not</emphasis> try to enumerate entities by calling
MEDIA_IOC_ENUM_ENTITIES with increasing id's until they get an error.</para>
<para>Two or more entities that share a common non-zero
<structfield>group_id</structfield> value are considered as logically
grouped. Groups are used to report
<itemizedlist>
<listitem><para>ALSA, VBI and video nodes that carry the same media
stream</para></listitem>
<listitem><para>lens and flash controllers associated with a sensor</para></listitem>
</itemizedlist>
</para>
<table pgwide="1" frame="none" id="media-entity-desc">
<title>struct <structname>media_entity_desc</structname></title>
<tgroup cols="5">
<colspec colname="c1" />
<colspec colname="c2" />
<colspec colname="c3" />
<colspec colname="c4" />
<colspec colname="c5" />
<tbody valign="top">
<row>
<entry>__u32</entry>
<entry><structfield>id</structfield></entry>
<entry></entry>
<entry></entry>
<entry>Entity id, set by the application. When the id is or'ed with
<constant>MEDIA_ENT_ID_FLAG_NEXT</constant>, the driver clears the
flag and returns the first entity with a larger id.</entry>
</row>
<row>
<entry>char</entry>
<entry><structfield>name</structfield>[32]</entry>
<entry></entry>
<entry></entry>
<entry>Entity name as an UTF-8 NULL-terminated string.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>type</structfield></entry>
<entry></entry>
<entry></entry>
<entry>Entity type, see <xref linkend="media-entity-type" /> for details.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>revision</structfield></entry>
<entry></entry>
<entry></entry>
<entry>Entity revision in a driver/hardware specific format.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>flags</structfield></entry>
<entry></entry>
<entry></entry>
<entry>Entity flags, see <xref linkend="media-entity-flag" /> for details.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>group_id</structfield></entry>
<entry></entry>
<entry></entry>
<entry>Entity group ID</entry>
</row>
<row>
<entry>__u16</entry>
<entry><structfield>pads</structfield></entry>
<entry></entry>
<entry></entry>
<entry>Number of pads</entry>
</row>
<row>
<entry>__u16</entry>
<entry><structfield>links</structfield></entry>
<entry></entry>
<entry></entry>
<entry>Total number of outbound links. Inbound links are not counted
in this field.</entry>
</row>
<row>
<entry>union</entry>
</row>
<row>
<entry></entry>
<entry>struct</entry>
<entry><structfield>v4l</structfield></entry>
<entry></entry>
<entry>Valid for V4L sub-devices and nodes only.</entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry>__u32</entry>
<entry><structfield>major</structfield></entry>
<entry>V4L device node major number. For V4L sub-devices with no
device node, set by the driver to 0.</entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry>__u32</entry>
<entry><structfield>minor</structfield></entry>
<entry>V4L device node minor number. For V4L sub-devices with no
device node, set by the driver to 0.</entry>
</row>
<row>
<entry></entry>
<entry>struct</entry>
<entry><structfield>fb</structfield></entry>
<entry></entry>
<entry>Valid for frame buffer nodes only.</entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry>__u32</entry>
<entry><structfield>major</structfield></entry>
<entry>Frame buffer device node major number.</entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry>__u32</entry>
<entry><structfield>minor</structfield></entry>
<entry>Frame buffer device node minor number.</entry>
</row>
<row>
<entry></entry>
<entry>struct</entry>
<entry><structfield>alsa</structfield></entry>
<entry></entry>
<entry>Valid for ALSA devices only.</entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry>__u32</entry>
<entry><structfield>card</structfield></entry>
<entry>ALSA card number</entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry>__u32</entry>
<entry><structfield>device</structfield></entry>
<entry>ALSA device number</entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry>__u32</entry>
<entry><structfield>subdevice</structfield></entry>
<entry>ALSA sub-device number</entry>
</row>
<row>
<entry></entry>
<entry>int</entry>
<entry><structfield>dvb</structfield></entry>
<entry></entry>
<entry>DVB card number</entry>
</row>
<row>
<entry></entry>
<entry>__u8</entry>
<entry><structfield>raw</structfield>[180]</entry>
<entry></entry>
<entry></entry>
</row>
</tbody>
</tgroup>
</table>
<table frame="none" pgwide="1" id="media-entity-type">
<title>Media entity types</title>
<tgroup cols="2">
<colspec colname="c1"/>
<colspec colname="c2"/>
<tbody valign="top">
<row>
<entry><constant>MEDIA_ENT_T_DEVNODE</constant></entry>
<entry>Unknown device node</entry>
</row>
<row>
<entry><constant>MEDIA_ENT_T_DEVNODE_V4L</constant></entry>
<entry>V4L video, radio or vbi device node</entry>
</row>
<row>
<entry><constant>MEDIA_ENT_T_DEVNODE_FB</constant></entry>
<entry>Frame buffer device node</entry>
</row>
<row>
<entry><constant>MEDIA_ENT_T_DEVNODE_ALSA</constant></entry>
<entry>ALSA card</entry>
</row>
<row>
<entry><constant>MEDIA_ENT_T_DEVNODE_DVB</constant></entry>
<entry>DVB card</entry>
</row>
<row>
<entry><constant>MEDIA_ENT_T_V4L2_SUBDEV</constant></entry>
<entry>Unknown V4L sub-device</entry>
</row>
<row>
<entry><constant>MEDIA_ENT_T_V4L2_SUBDEV_SENSOR</constant></entry>
<entry>Video sensor</entry>
</row>
<row>
<entry><constant>MEDIA_ENT_T_V4L2_SUBDEV_FLASH</constant></entry>
<entry>Flash controller</entry>
</row>
<row>
<entry><constant>MEDIA_ENT_T_V4L2_SUBDEV_LENS</constant></entry>
<entry>Lens controller</entry>
</row>
</tbody>
</tgroup>
</table>
<table frame="none" pgwide="1" id="media-entity-flag">
<title>Media entity flags</title>
<tgroup cols="2">
<colspec colname="c1"/>
<colspec colname="c2"/>
<tbody valign="top">
<row>
<entry><constant>MEDIA_ENT_FL_DEFAULT</constant></entry>
<entry>Default entity for its type. Used to discover the default
audio, VBI and video devices, the default camera sensor, ...</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1>
&return-value;
<variablelist>
<varlistentry>
<term><errorcode>EINVAL</errorcode></term>
<listitem>
<para>The &media-entity-desc; <structfield>id</structfield> references
a non-existing entity.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/media-ioc-enum-links.xml
+207
View File
@@ -0,0 +1,207 @@
<refentry id="media-ioc-enum-links">
<refmeta>
<refentrytitle>ioctl MEDIA_IOC_ENUM_LINKS</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>MEDIA_IOC_ENUM_LINKS</refname>
<refpurpose>Enumerate all pads and links for a given entity</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ioctl</function></funcdef>
<paramdef>int <parameter>fd</parameter></paramdef>
<paramdef>int <parameter>request</parameter></paramdef>
<paramdef>struct media_links_enum *<parameter>argp</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>fd</parameter></term>
<listitem>
<para>File descriptor returned by
<link linkend='media-func-open'><function>open()</function></link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>request</parameter></term>
<listitem>
<para>MEDIA_IOC_ENUM_LINKS</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>argp</parameter></term>
<listitem>
<para></para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>To enumerate pads and/or links for a given entity, applications set
the entity field of a &media-links-enum; structure and initialize the
&media-pad-desc; and &media-link-desc; structure arrays pointed by the
<structfield>pads</structfield> and <structfield>links</structfield> fields.
They then call the MEDIA_IOC_ENUM_LINKS ioctl with a pointer to this
structure.</para>
<para>If the <structfield>pads</structfield> field is not NULL, the driver
fills the <structfield>pads</structfield> array with information about the
entity's pads. The array must have enough room to store all the entity's
pads. The number of pads can be retrieved with the &MEDIA-IOC-ENUM-ENTITIES;
ioctl.</para>
<para>If the <structfield>links</structfield> field is not NULL, the driver
fills the <structfield>links</structfield> array with information about the
entity's outbound links. The array must have enough room to store all the
entity's outbound links. The number of outbound links can be retrieved with
the &MEDIA-IOC-ENUM-ENTITIES; ioctl.</para>
<para>Only forward links that originate at one of the entity's source pads
are returned during the enumeration process.</para>
<table pgwide="1" frame="none" id="media-links-enum">
<title>struct <structname>media_links_enum</structname></title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>__u32</entry>
<entry><structfield>entity</structfield></entry>
<entry>Entity id, set by the application.</entry>
</row>
<row>
<entry>struct &media-pad-desc;</entry>
<entry>*<structfield>pads</structfield></entry>
<entry>Pointer to a pads array allocated by the application. Ignored
if NULL.</entry>
</row>
<row>
<entry>struct &media-link-desc;</entry>
<entry>*<structfield>links</structfield></entry>
<entry>Pointer to a links array allocated by the application. Ignored
if NULL.</entry>
</row>
</tbody>
</tgroup>
</table>
<table pgwide="1" frame="none" id="media-pad-desc">
<title>struct <structname>media_pad_desc</structname></title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>__u32</entry>
<entry><structfield>entity</structfield></entry>
<entry>ID of the entity this pad belongs to.</entry>
</row>
<row>
<entry>__u16</entry>
<entry><structfield>index</structfield></entry>
<entry>0-based pad index.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>flags</structfield></entry>
<entry>Pad flags, see <xref linkend="media-pad-flag" /> for more details.</entry>
</row>
</tbody>
</tgroup>
</table>
<table frame="none" pgwide="1" id="media-pad-flag">
<title>Media pad flags</title>
<tgroup cols="2">
<colspec colname="c1"/>
<colspec colname="c2"/>
<tbody valign="top">
<row>
<entry><constant>MEDIA_PAD_FL_SINK</constant></entry>
<entry>Input pad, relative to the entity. Input pads sink data and
are targets of links.</entry>
</row>
<row>
<entry><constant>MEDIA_PAD_FL_SOURCE</constant></entry>
<entry>Output pad, relative to the entity. Output pads source data
and are origins of links.</entry>
</row>
</tbody>
</tgroup>
</table>
<table pgwide="1" frame="none" id="media-link-desc">
<title>struct <structname>media_link_desc</structname></title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>struct &media-pad-desc;</entry>
<entry><structfield>source</structfield></entry>
<entry>Pad at the origin of this link.</entry>
</row>
<row>
<entry>struct &media-pad-desc;</entry>
<entry><structfield>sink</structfield></entry>
<entry>Pad at the target of this link.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>flags</structfield></entry>
<entry>Link flags, see <xref linkend="media-link-flag" /> for more details.</entry>
</row>
</tbody>
</tgroup>
</table>
<table frame="none" pgwide="1" id="media-link-flag">
<title>Media link flags</title>
<tgroup cols="2">
<colspec colname="c1"/>
<colspec colname="c2"/>
<tbody valign="top">
<row>
<entry><constant>MEDIA_LNK_FL_ENABLED</constant></entry>
<entry>The link is enabled and can be used to transfer media data.
When two or more links target a sink pad, only one of them can be
enabled at a time.</entry>
</row>
<row>
<entry><constant>MEDIA_LNK_FL_IMMUTABLE</constant></entry>
<entry>The link enabled state can't be modified at runtime. An
immutable link is always enabled.</entry>
</row>
<row>
<entry><constant>MEDIA_LNK_FL_DYNAMIC</constant></entry>
<entry>The link enabled state can be modified during streaming. This
flag is set by drivers and is read-only for applications.</entry>
</row>
</tbody>
</tgroup>
</table>
<para>One and only one of <constant>MEDIA_PAD_FL_SINK</constant> and
<constant>MEDIA_PAD_FL_SOURCE</constant> must be set for every pad.</para>
</refsect1>
<refsect1>
&return-value;
<variablelist>
<varlistentry>
<term><errorcode>EINVAL</errorcode></term>
<listitem>
<para>The &media-links-enum; <structfield>id</structfield> references
a non-existing entity.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/media-ioc-setup-link.xml
+84
View File
@@ -0,0 +1,84 @@
<refentry id="media-ioc-setup-link">
<refmeta>
<refentrytitle>ioctl MEDIA_IOC_SETUP_LINK</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>MEDIA_IOC_SETUP_LINK</refname>
<refpurpose>Modify the properties of a link</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ioctl</function></funcdef>
<paramdef>int <parameter>fd</parameter></paramdef>
<paramdef>int <parameter>request</parameter></paramdef>
<paramdef>struct media_link_desc *<parameter>argp</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>fd</parameter></term>
<listitem>
<para>File descriptor returned by
<link linkend='media-func-open'><function>open()</function></link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>request</parameter></term>
<listitem>
<para>MEDIA_IOC_SETUP_LINK</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>argp</parameter></term>
<listitem>
<para></para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>To change link properties applications fill a &media-link-desc; with
link identification information (source and sink pad) and the new requested
link flags. They then call the MEDIA_IOC_SETUP_LINK ioctl with a pointer to
that structure.</para>
<para>The only configurable property is the <constant>ENABLED</constant>
link flag to enable/disable a link. Links marked with the
<constant>IMMUTABLE</constant> link flag can not be enabled or disabled.
</para>
<para>Link configuration has no side effect on other links. If an enabled
link at the sink pad prevents the link from being enabled, the driver
returns with an &EBUSY;.</para>
<para>Only links marked with the <constant>DYNAMIC</constant> link flag can
be enabled/disabled while streaming media data. Attempting to enable or
disable a streaming non-dynamic link will return an &EBUSY;.</para>
<para>If the specified link can't be found the driver returns with an
&EINVAL;.</para>
</refsect1>
<refsect1>
&return-value;
<variablelist>
<varlistentry>
<term><errorcode>EINVAL</errorcode></term>
<listitem>
<para>The &media-link-desc; references a non-existing link, or the
link is immutable and an attempt to modify its configuration was made.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/pipeline.pdf
BIN
View File
Binary file not shown.
kernel/Documentation/DocBook/media/v4l/pixfmt-grey.xml
+62
View File
@@ -0,0 +1,62 @@
<refentry id="V4L2-PIX-FMT-GREY">
<refmeta>
<refentrytitle>V4L2_PIX_FMT_GREY ('GREY')</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname><constant>V4L2_PIX_FMT_GREY</constant></refname>
<refpurpose>Grey-scale image</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>This is a grey-scale image. It is really a degenerate
Y'CbCr format which simply contains no Cb or Cr data.</para>
<example>
<title><constant>V4L2_PIX_FMT_GREY</constant> 4 &times; 4
pixel image</title>
<formalpara>
<title>Byte Order.</title>
<para>Each cell is one byte.
<informaltable frame="none">
<tgroup cols="5" align="center">
<colspec align="left" colwidth="2*" />
<tbody valign="top">
<row>
<entry>start&nbsp;+&nbsp;0:</entry>
<entry>Y'<subscript>00</subscript></entry>
<entry>Y'<subscript>01</subscript></entry>
<entry>Y'<subscript>02</subscript></entry>
<entry>Y'<subscript>03</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;4:</entry>
<entry>Y'<subscript>10</subscript></entry>
<entry>Y'<subscript>11</subscript></entry>
<entry>Y'<subscript>12</subscript></entry>
<entry>Y'<subscript>13</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;8:</entry>
<entry>Y'<subscript>20</subscript></entry>
<entry>Y'<subscript>21</subscript></entry>
<entry>Y'<subscript>22</subscript></entry>
<entry>Y'<subscript>23</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;12:</entry>
<entry>Y'<subscript>30</subscript></entry>
<entry>Y'<subscript>31</subscript></entry>
<entry>Y'<subscript>32</subscript></entry>
<entry>Y'<subscript>33</subscript></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
</example>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/pixfmt-m420.xml
+139
View File
@@ -0,0 +1,139 @@
<refentry id="V4L2-PIX-FMT-M420">
<refmeta>
<refentrytitle>V4L2_PIX_FMT_M420 ('M420')</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname><constant>V4L2_PIX_FMT_M420</constant></refname>
<refpurpose>Format with &frac12; horizontal and vertical chroma
resolution, also known as YUV 4:2:0. Hybrid plane line-interleaved
layout.</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>M420 is a YUV format with &frac12; horizontal and vertical chroma
subsampling (YUV 4:2:0). Pixels are organized as interleaved luma and
chroma planes. Two lines of luma data are followed by one line of chroma
data.</para>
<para>The luma plane has one byte per pixel. The chroma plane contains
interleaved CbCr pixels subsampled by &frac12; in the horizontal and
vertical directions. Each CbCr pair belongs to four pixels. For example,
Cb<subscript>0</subscript>/Cr<subscript>0</subscript> belongs to
Y'<subscript>00</subscript>, Y'<subscript>01</subscript>,
Y'<subscript>10</subscript>, Y'<subscript>11</subscript>.</para>
<para>All line lengths are identical: if the Y lines include pad bytes
so do the CbCr lines.</para>
<example>
<title><constant>V4L2_PIX_FMT_M420</constant> 4 &times; 4
pixel image</title>
<formalpara>
<title>Byte Order.</title>
<para>Each cell is one byte.
<informaltable frame="none">
<tgroup cols="5" align="center">
<colspec align="left" colwidth="2*" />
<tbody valign="top">
<row>
<entry>start&nbsp;+&nbsp;0:</entry>
<entry>Y'<subscript>00</subscript></entry>
<entry>Y'<subscript>01</subscript></entry>
<entry>Y'<subscript>02</subscript></entry>
<entry>Y'<subscript>03</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;4:</entry>
<entry>Y'<subscript>10</subscript></entry>
<entry>Y'<subscript>11</subscript></entry>
<entry>Y'<subscript>12</subscript></entry>
<entry>Y'<subscript>13</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;8:</entry>
<entry>Cb<subscript>00</subscript></entry>
<entry>Cr<subscript>00</subscript></entry>
<entry>Cb<subscript>01</subscript></entry>
<entry>Cr<subscript>01</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;16:</entry>
<entry>Y'<subscript>20</subscript></entry>
<entry>Y'<subscript>21</subscript></entry>
<entry>Y'<subscript>22</subscript></entry>
<entry>Y'<subscript>23</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;20:</entry>
<entry>Y'<subscript>30</subscript></entry>
<entry>Y'<subscript>31</subscript></entry>
<entry>Y'<subscript>32</subscript></entry>
<entry>Y'<subscript>33</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;24:</entry>
<entry>Cb<subscript>10</subscript></entry>
<entry>Cr<subscript>10</subscript></entry>
<entry>Cb<subscript>11</subscript></entry>
<entry>Cr<subscript>11</subscript></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
<formalpara>
<title>Color Sample Location.</title>
<para>
<informaltable frame="none">
<tgroup cols="7" align="center">
<tbody valign="top">
<row>
<entry></entry>
<entry>0</entry><entry></entry><entry>1</entry><entry></entry>
<entry>2</entry><entry></entry><entry>3</entry>
</row>
<row>
<entry>0</entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry></entry><entry>Y</entry>
</row>
<row>
<entry></entry>
<entry></entry><entry>C</entry><entry></entry><entry></entry>
<entry></entry><entry>C</entry><entry></entry>
</row>
<row>
<entry>1</entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry></entry><entry>Y</entry>
</row>
<row>
<entry></entry>
</row>
<row>
<entry>2</entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry></entry><entry>Y</entry>
</row>
<row>
<entry></entry>
<entry></entry><entry>C</entry><entry></entry><entry></entry>
<entry></entry><entry>C</entry><entry></entry>
</row>
<row>
<entry>3</entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry></entry><entry>Y</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
</example>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/pixfmt-nv12.xml
+143
View File
@@ -0,0 +1,143 @@
<refentry>
<refmeta>
<refentrytitle>V4L2_PIX_FMT_NV12 ('NV12'), V4L2_PIX_FMT_NV21 ('NV21')</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname id="V4L2-PIX-FMT-NV12"><constant>V4L2_PIX_FMT_NV12</constant></refname>
<refname id="V4L2-PIX-FMT-NV21"><constant>V4L2_PIX_FMT_NV21</constant></refname>
<refpurpose>Formats with &frac12; horizontal and vertical
chroma resolution, also known as YUV 4:2:0. One luminance and one
chrominance plane with alternating chroma samples as opposed to
<constant>V4L2_PIX_FMT_YVU420</constant></refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>These are two-plane versions of the YUV 4:2:0 format.
The three components are separated into two sub-images or planes. The
Y plane is first. The Y plane has one byte per pixel. For
<constant>V4L2_PIX_FMT_NV12</constant>, a combined CbCr plane
immediately follows the Y plane in memory. The CbCr plane is the same
width, in bytes, as the Y plane (and of the image), but is half as
tall in pixels. Each CbCr pair belongs to four pixels. For example,
Cb<subscript>0</subscript>/Cr<subscript>0</subscript> belongs to
Y'<subscript>00</subscript>, Y'<subscript>01</subscript>,
Y'<subscript>10</subscript>, Y'<subscript>11</subscript>.
<constant>V4L2_PIX_FMT_NV21</constant> is the same except the Cb and
Cr bytes are swapped, the CrCb plane starts with a Cr byte.</para>
<para>If the Y plane has pad bytes after each row, then the
CbCr plane has as many pad bytes after its rows.</para>
<example>
<title><constant>V4L2_PIX_FMT_NV12</constant> 4 &times; 4
pixel image</title>
<formalpara>
<title>Byte Order.</title>
<para>Each cell is one byte.
<informaltable frame="none">
<tgroup cols="5" align="center">
<colspec align="left" colwidth="2*" />
<tbody valign="top">
<row>
<entry>start&nbsp;+&nbsp;0:</entry>
<entry>Y'<subscript>00</subscript></entry>
<entry>Y'<subscript>01</subscript></entry>
<entry>Y'<subscript>02</subscript></entry>
<entry>Y'<subscript>03</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;4:</entry>
<entry>Y'<subscript>10</subscript></entry>
<entry>Y'<subscript>11</subscript></entry>
<entry>Y'<subscript>12</subscript></entry>
<entry>Y'<subscript>13</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;8:</entry>
<entry>Y'<subscript>20</subscript></entry>
<entry>Y'<subscript>21</subscript></entry>
<entry>Y'<subscript>22</subscript></entry>
<entry>Y'<subscript>23</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;12:</entry>
<entry>Y'<subscript>30</subscript></entry>
<entry>Y'<subscript>31</subscript></entry>
<entry>Y'<subscript>32</subscript></entry>
<entry>Y'<subscript>33</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;16:</entry>
<entry>Cb<subscript>00</subscript></entry>
<entry>Cr<subscript>00</subscript></entry>
<entry>Cb<subscript>01</subscript></entry>
<entry>Cr<subscript>01</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;20:</entry>
<entry>Cb<subscript>10</subscript></entry>
<entry>Cr<subscript>10</subscript></entry>
<entry>Cb<subscript>11</subscript></entry>
<entry>Cr<subscript>11</subscript></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
<formalpara>
<title>Color Sample Location.</title>
<para>
<informaltable frame="none">
<tgroup cols="7" align="center">
<tbody valign="top">
<row>
<entry></entry>
<entry>0</entry><entry></entry><entry>1</entry><entry></entry>
<entry>2</entry><entry></entry><entry>3</entry>
</row>
<row>
<entry>0</entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry></entry><entry>Y</entry>
</row>
<row>
<entry></entry>
<entry></entry><entry>C</entry><entry></entry><entry></entry>
<entry></entry><entry>C</entry><entry></entry>
</row>
<row>
<entry>1</entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry></entry><entry>Y</entry>
</row>
<row>
<entry></entry>
</row>
<row>
<entry>2</entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry></entry><entry>Y</entry>
</row>
<row>
<entry></entry>
<entry></entry><entry>C</entry><entry></entry><entry></entry>
<entry></entry><entry>C</entry><entry></entry>
</row>
<row>
<entry>3</entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry></entry><entry>Y</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
</example>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/pixfmt-nv12m.xml
+146
View File
@@ -0,0 +1,146 @@
<refentry id="V4L2-PIX-FMT-NV12M">
<refmeta>
<refentrytitle>V4L2_PIX_FMT_NV12M ('NM12')</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname> <constant>V4L2_PIX_FMT_NV12M</constant></refname>
<refpurpose>Variation of <constant>V4L2_PIX_FMT_NV12</constant> with planes
non contiguous in memory. </refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>This is a multi-planar, two-plane version of the YUV 4:2:0 format.
The three components are separated into two sub-images or planes.
<constant>V4L2_PIX_FMT_NV12M</constant> differs from <constant>V4L2_PIX_FMT_NV12
</constant> in that the two planes are non-contiguous in memory, i.e. the chroma
plane do not necessarily immediately follows the luma plane.
The luminance data occupies the first plane. The Y plane has one byte per pixel.
In the second plane there is a chrominance data with alternating chroma samples.
The CbCr plane is the same width, in bytes, as the Y plane (and of the image),
but is half as tall in pixels. Each CbCr pair belongs to four pixels. For example,
Cb<subscript>0</subscript>/Cr<subscript>0</subscript> belongs to
Y'<subscript>00</subscript>, Y'<subscript>01</subscript>,
Y'<subscript>10</subscript>, Y'<subscript>11</subscript>. </para>
<para><constant>V4L2_PIX_FMT_NV12M</constant> is intended to be
used only in drivers and applications that support the multi-planar API,
described in <xref linkend="planar-apis"/>. </para>
<para>If the Y plane has pad bytes after each row, then the
CbCr plane has as many pad bytes after its rows.</para>
<example>
<title><constant>V4L2_PIX_FMT_NV12M</constant> 4 &times; 4 pixel image</title>
<formalpara>
<title>Byte Order.</title>
<para>Each cell is one byte.
<informaltable frame="none">
<tgroup cols="5" align="center">
<colspec align="left" colwidth="2*" />
<tbody valign="top">
<row>
<entry>start0&nbsp;+&nbsp;0:</entry>
<entry>Y'<subscript>00</subscript></entry>
<entry>Y'<subscript>01</subscript></entry>
<entry>Y'<subscript>02</subscript></entry>
<entry>Y'<subscript>03</subscript></entry>
</row>
<row>
<entry>start0&nbsp;+&nbsp;4:</entry>
<entry>Y'<subscript>10</subscript></entry>
<entry>Y'<subscript>11</subscript></entry>
<entry>Y'<subscript>12</subscript></entry>
<entry>Y'<subscript>13</subscript></entry>
</row>
<row>
<entry>start0&nbsp;+&nbsp;8:</entry>
<entry>Y'<subscript>20</subscript></entry>
<entry>Y'<subscript>21</subscript></entry>
<entry>Y'<subscript>22</subscript></entry>
<entry>Y'<subscript>23</subscript></entry>
</row>
<row>
<entry>start0&nbsp;+&nbsp;12:</entry>
<entry>Y'<subscript>30</subscript></entry>
<entry>Y'<subscript>31</subscript></entry>
<entry>Y'<subscript>32</subscript></entry>
<entry>Y'<subscript>33</subscript></entry>
</row>
<row>
<entry></entry>
</row>
<row>
<entry>start1&nbsp;+&nbsp;0:</entry>
<entry>Cb<subscript>00</subscript></entry>
<entry>Cr<subscript>00</subscript></entry>
<entry>Cb<subscript>01</subscript></entry>
<entry>Cr<subscript>01</subscript></entry>
</row>
<row>
<entry>start1&nbsp;+&nbsp;4:</entry>
<entry>Cb<subscript>10</subscript></entry>
<entry>Cr<subscript>10</subscript></entry>
<entry>Cb<subscript>11</subscript></entry>
<entry>Cr<subscript>11</subscript></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
<formalpara>
<title>Color Sample Location.</title>
<para>
<informaltable frame="none">
<tgroup cols="7" align="center">
<tbody valign="top">
<row>
<entry></entry>
<entry>0</entry><entry></entry><entry>1</entry><entry></entry>
<entry>2</entry><entry></entry><entry>3</entry>
</row>
<row>
<entry>0</entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry></entry><entry>Y</entry>
</row>
<row>
<entry></entry>
<entry></entry><entry>C</entry><entry></entry><entry></entry>
<entry></entry><entry>C</entry><entry></entry>
</row>
<row>
<entry>1</entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry></entry><entry>Y</entry>
</row>
<row>
<entry></entry>
</row>
<row>
<entry>2</entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry></entry><entry>Y</entry>
</row>
<row>
<entry></entry>
<entry></entry><entry>C</entry><entry></entry><entry></entry>
<entry></entry><entry>C</entry><entry></entry>
</row>
<row>
<entry>3</entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry></entry><entry>Y</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
</example>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/pixfmt-nv12mt.xml
+66
View File
@@ -0,0 +1,66 @@
<refentry>
<refmeta>
<refentrytitle>V4L2_PIX_FMT_NV12MT ('TM12')</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname id="V4L2-PIX-FMT-NV12MT"><constant>V4L2_PIX_FMT_NV12MT
</constant></refname>
<refpurpose>Formats with &frac12; horizontal and vertical
chroma resolution. This format has two planes - one for luminance and one for
chrominance. Chroma samples are interleaved. The difference to
<constant>V4L2_PIX_FMT_NV12</constant> is the memory layout. Pixels are
grouped in macroblocks of 64x32 size. The order of macroblocks in memory is
also not standard.
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>This is the two-plane versions of the YUV 4:2:0 format where data
is grouped into 64x32 macroblocks. The three components are separated into two
sub-images or planes. The Y plane has one byte per pixel and pixels are grouped
into 64x32 macroblocks. The CbCr plane has the same width, in bytes, as the Y
plane (and the image), but is half as tall in pixels. The chroma plane is also
grouped into 64x32 macroblocks.</para>
<para>Width of the buffer has to be aligned to the multiple of 128, and
height alignment is 32. Every four adjactent buffers - two horizontally and two
vertically are grouped together and are located in memory in Z or flipped Z
order. </para>
<para>Layout of macroblocks in memory is presented in the following
figure.</para>
<para><figure id="nv12mt">
<title><constant>V4L2_PIX_FMT_NV12MT</constant> macroblock Z shape
memory layout</title>
<mediaobject>
<imageobject>
<imagedata fileref="nv12mt.gif" format="GIF" />
</imageobject>
</mediaobject>
</figure>
The requirement that width is multiple of 128 is implemented because,
the Z shape cannot be cut in half horizontally. In case the vertical resolution
of macroblocks is odd then the last row of macroblocks is arranged in a linear
order. </para>
<para>In case of chroma the layout is identical. Cb and Cr samples are
interleaved. Height of the buffer is aligned to 32.
</para>
<example>
<title>Memory layout of macroblocks in <constant>V4L2_PIX_FMT_NV12
</constant> format pixel image - extreme case</title>
<para>
<figure id="nv12mt_ex">
<title>Example <constant>V4L2_PIX_FMT_NV12MT</constant> memory
layout of macroblocks</title>
<mediaobject>
<imageobject>
<imagedata fileref="nv12mt_example.gif" format="GIF" />
</imageobject>
</mediaobject>
</figure>
Memory layout of macroblocks of <constant>V4L2_PIX_FMT_NV12MT
</constant> format in most extreme case.
</para>
</example>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/pixfmt-nv16.xml
+166
View File
@@ -0,0 +1,166 @@
<refentry>
<refmeta>
<refentrytitle>V4L2_PIX_FMT_NV16 ('NV16'), V4L2_PIX_FMT_NV61 ('NV61')</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname id="V4L2-PIX-FMT-NV16"><constant>V4L2_PIX_FMT_NV16</constant></refname>
<refname id="V4L2-PIX-FMT-NV61"><constant>V4L2_PIX_FMT_NV61</constant></refname>
<refpurpose>Formats with &frac12; horizontal
chroma resolution, also known as YUV 4:2:2. One luminance and one
chrominance plane with alternating chroma samples as opposed to
<constant>V4L2_PIX_FMT_YVU420</constant></refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>These are two-plane versions of the YUV 4:2:2 format.
The three components are separated into two sub-images or planes. The
Y plane is first. The Y plane has one byte per pixel. For
<constant>V4L2_PIX_FMT_NV16</constant>, a combined CbCr plane
immediately follows the Y plane in memory. The CbCr plane is the same
width and height, in bytes, as the Y plane (and of the image).
Each CbCr pair belongs to two pixels. For example,
Cb<subscript>0</subscript>/Cr<subscript>0</subscript> belongs to
Y'<subscript>00</subscript>, Y'<subscript>01</subscript>.
<constant>V4L2_PIX_FMT_NV61</constant> is the same except the Cb and
Cr bytes are swapped, the CrCb plane starts with a Cr byte.</para>
<para>If the Y plane has pad bytes after each row, then the
CbCr plane has as many pad bytes after its rows.</para>
<example>
<title><constant>V4L2_PIX_FMT_NV16</constant> 4 &times; 4
pixel image</title>
<formalpara>
<title>Byte Order.</title>
<para>Each cell is one byte.
<informaltable frame="none">
<tgroup cols="5" align="center">
<colspec align="left" colwidth="2*" />
<tbody valign="top">
<row>
<entry>start&nbsp;+&nbsp;0:</entry>
<entry>Y'<subscript>00</subscript></entry>
<entry>Y'<subscript>01</subscript></entry>
<entry>Y'<subscript>02</subscript></entry>
<entry>Y'<subscript>03</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;4:</entry>
<entry>Y'<subscript>10</subscript></entry>
<entry>Y'<subscript>11</subscript></entry>
<entry>Y'<subscript>12</subscript></entry>
<entry>Y'<subscript>13</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;8:</entry>
<entry>Y'<subscript>20</subscript></entry>
<entry>Y'<subscript>21</subscript></entry>
<entry>Y'<subscript>22</subscript></entry>
<entry>Y'<subscript>23</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;12:</entry>
<entry>Y'<subscript>30</subscript></entry>
<entry>Y'<subscript>31</subscript></entry>
<entry>Y'<subscript>32</subscript></entry>
<entry>Y'<subscript>33</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;16:</entry>
<entry>Cb<subscript>00</subscript></entry>
<entry>Cr<subscript>00</subscript></entry>
<entry>Cb<subscript>01</subscript></entry>
<entry>Cr<subscript>01</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;20:</entry>
<entry>Cb<subscript>10</subscript></entry>
<entry>Cr<subscript>10</subscript></entry>
<entry>Cb<subscript>11</subscript></entry>
<entry>Cr<subscript>11</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;24:</entry>
<entry>Cb<subscript>20</subscript></entry>
<entry>Cr<subscript>20</subscript></entry>
<entry>Cb<subscript>21</subscript></entry>
<entry>Cr<subscript>21</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;28:</entry>
<entry>Cb<subscript>30</subscript></entry>
<entry>Cr<subscript>30</subscript></entry>
<entry>Cb<subscript>31</subscript></entry>
<entry>Cr<subscript>31</subscript></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
<formalpara>
<title>Color Sample Location.</title>
<para>
<informaltable frame="none">
<tgroup cols="7" align="center">
<tbody valign="top">
<row>
<entry></entry>
<entry>0</entry><entry></entry><entry>1</entry><entry></entry>
<entry>2</entry><entry></entry><entry>3</entry>
</row>
<row>
<entry>0</entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry></entry><entry>Y</entry>
</row>
<row>
<entry></entry>
<entry></entry><entry>C</entry><entry></entry><entry></entry>
<entry></entry><entry>C</entry><entry></entry>
</row>
<row>
<entry>1</entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry></entry><entry>Y</entry>
</row>
<row>
<entry></entry>
<entry></entry><entry>C</entry><entry></entry><entry></entry>
<entry></entry><entry>C</entry><entry></entry>
</row>
<row>
<entry></entry>
</row>
<row>
<entry>2</entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry></entry><entry>Y</entry>
</row>
<row>
<entry></entry>
<entry></entry><entry>C</entry><entry></entry><entry></entry>
<entry></entry><entry>C</entry><entry></entry>
</row>
<row>
<entry>3</entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry></entry><entry>Y</entry>
</row>
<row>
<entry></entry>
<entry></entry><entry>C</entry><entry></entry><entry></entry>
<entry></entry><entry>C</entry><entry></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
</example>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/pixfmt-nv24.xml
+121
View File
@@ -0,0 +1,121 @@
<refentry>
<refmeta>
<refentrytitle>V4L2_PIX_FMT_NV24 ('NV24'), V4L2_PIX_FMT_NV42 ('NV42')</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname id="V4L2-PIX-FMT-NV24"><constant>V4L2_PIX_FMT_NV24</constant></refname>
<refname id="V4L2-PIX-FMT-NV42"><constant>V4L2_PIX_FMT_NV42</constant></refname>
<refpurpose>Formats with full horizontal and vertical
chroma resolutions, also known as YUV 4:4:4. One luminance and one
chrominance plane with alternating chroma samples as opposed to
<constant>V4L2_PIX_FMT_YVU420</constant></refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>These are two-plane versions of the YUV 4:4:4 format. The three
components are separated into two sub-images or planes. The Y plane is
first, with each Y sample stored in one byte per pixel. For
<constant>V4L2_PIX_FMT_NV24</constant>, a combined CbCr plane
immediately follows the Y plane in memory. The CbCr plane has the same
width and height, in pixels, as the Y plane (and the image). Each line
contains one CbCr pair per pixel, with each Cb and Cr sample stored in
one byte. <constant>V4L2_PIX_FMT_NV42</constant> is the same except that
the Cb and Cr samples are swapped, the CrCb plane starts with a Cr
sample.</para>
<para>If the Y plane has pad bytes after each row, then the CbCr plane
has twice as many pad bytes after its rows.</para>
<example>
<title><constant>V4L2_PIX_FMT_NV24</constant> 4 &times; 4
pixel image</title>
<formalpara>
<title>Byte Order.</title>
<para>Each cell is one byte.
<informaltable frame="none">
<tgroup cols="9" align="center">
<colspec align="left" colwidth="2*" />
<tbody valign="top">
<row>
<entry>start&nbsp;+&nbsp;0:</entry>
<entry>Y'<subscript>00</subscript></entry>
<entry>Y'<subscript>01</subscript></entry>
<entry>Y'<subscript>02</subscript></entry>
<entry>Y'<subscript>03</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;4:</entry>
<entry>Y'<subscript>10</subscript></entry>
<entry>Y'<subscript>11</subscript></entry>
<entry>Y'<subscript>12</subscript></entry>
<entry>Y'<subscript>13</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;8:</entry>
<entry>Y'<subscript>20</subscript></entry>
<entry>Y'<subscript>21</subscript></entry>
<entry>Y'<subscript>22</subscript></entry>
<entry>Y'<subscript>23</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;12:</entry>
<entry>Y'<subscript>30</subscript></entry>
<entry>Y'<subscript>31</subscript></entry>
<entry>Y'<subscript>32</subscript></entry>
<entry>Y'<subscript>33</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;16:</entry>
<entry>Cb<subscript>00</subscript></entry>
<entry>Cr<subscript>00</subscript></entry>
<entry>Cb<subscript>01</subscript></entry>
<entry>Cr<subscript>01</subscript></entry>
<entry>Cb<subscript>02</subscript></entry>
<entry>Cr<subscript>02</subscript></entry>
<entry>Cb<subscript>03</subscript></entry>
<entry>Cr<subscript>03</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;24:</entry>
<entry>Cb<subscript>10</subscript></entry>
<entry>Cr<subscript>10</subscript></entry>
<entry>Cb<subscript>11</subscript></entry>
<entry>Cr<subscript>11</subscript></entry>
<entry>Cb<subscript>12</subscript></entry>
<entry>Cr<subscript>12</subscript></entry>
<entry>Cb<subscript>13</subscript></entry>
<entry>Cr<subscript>13</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;32:</entry>
<entry>Cb<subscript>20</subscript></entry>
<entry>Cr<subscript>20</subscript></entry>
<entry>Cb<subscript>21</subscript></entry>
<entry>Cr<subscript>21</subscript></entry>
<entry>Cb<subscript>22</subscript></entry>
<entry>Cr<subscript>22</subscript></entry>
<entry>Cb<subscript>23</subscript></entry>
<entry>Cr<subscript>23</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;40:</entry>
<entry>Cb<subscript>30</subscript></entry>
<entry>Cr<subscript>30</subscript></entry>
<entry>Cb<subscript>31</subscript></entry>
<entry>Cr<subscript>31</subscript></entry>
<entry>Cb<subscript>32</subscript></entry>
<entry>Cr<subscript>32</subscript></entry>
<entry>Cb<subscript>33</subscript></entry>
<entry>Cr<subscript>33</subscript></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
</example>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml
+935
View File
@@ -0,0 +1,935 @@
<refentry id="packed-rgb">
<refmeta>
<refentrytitle>Packed RGB formats</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>Packed RGB formats</refname>
<refpurpose>Packed RGB formats</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>These formats are designed to match the pixel formats of
typical PC graphics frame buffers. They occupy 8, 16, 24 or 32 bits
per pixel. These are all packed-pixel formats, meaning all the data
for a pixel lie next to each other in memory.</para>
<para>When one of these formats is used, drivers shall report the
colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para>
<table pgwide="1" frame="none" id="rgb-formats">
<title>Packed RGB Image Formats</title>
<tgroup cols="37" align="center">
<colspec colname="id" align="left" />
<colspec colname="fourcc" />
<colspec colname="bit" />
<colspec colnum="4" colname="b07" align="center" />
<colspec colnum="5" colname="b06" align="center" />
<colspec colnum="6" colname="b05" align="center" />
<colspec colnum="7" colname="b04" align="center" />
<colspec colnum="8" colname="b03" align="center" />
<colspec colnum="9" colname="b02" align="center" />
<colspec colnum="10" colname="b01" align="center" />
<colspec colnum="11" colname="b00" align="center" />
<colspec colnum="13" colname="b17" align="center" />
<colspec colnum="14" colname="b16" align="center" />
<colspec colnum="15" colname="b15" align="center" />
<colspec colnum="16" colname="b14" align="center" />
<colspec colnum="17" colname="b13" align="center" />
<colspec colnum="18" colname="b12" align="center" />
<colspec colnum="19" colname="b11" align="center" />
<colspec colnum="20" colname="b10" align="center" />
<colspec colnum="22" colname="b27" align="center" />
<colspec colnum="23" colname="b26" align="center" />
<colspec colnum="24" colname="b25" align="center" />
<colspec colnum="25" colname="b24" align="center" />
<colspec colnum="26" colname="b23" align="center" />
<colspec colnum="27" colname="b22" align="center" />
<colspec colnum="28" colname="b21" align="center" />
<colspec colnum="29" colname="b20" align="center" />
<colspec colnum="31" colname="b37" align="center" />
<colspec colnum="32" colname="b36" align="center" />
<colspec colnum="33" colname="b35" align="center" />
<colspec colnum="34" colname="b34" align="center" />
<colspec colnum="35" colname="b33" align="center" />
<colspec colnum="36" colname="b32" align="center" />
<colspec colnum="37" colname="b31" align="center" />
<colspec colnum="38" colname="b30" align="center" />
<spanspec namest="b07" nameend="b00" spanname="b0" />
<spanspec namest="b17" nameend="b10" spanname="b1" />
<spanspec namest="b27" nameend="b20" spanname="b2" />
<spanspec namest="b37" nameend="b30" spanname="b3" />
<thead>
<row>
<entry>Identifier</entry>
<entry>Code</entry>
<entry>&nbsp;</entry>
<entry spanname="b0">Byte&nbsp;0 in memory</entry>
<entry spanname="b1">Byte&nbsp;1</entry>
<entry spanname="b2">Byte&nbsp;2</entry>
<entry spanname="b3">Byte&nbsp;3</entry>
</row>
<row>
<entry>&nbsp;</entry>
<entry>&nbsp;</entry>
<entry>Bit</entry>
<entry>7</entry>
<entry>6</entry>
<entry>5</entry>
<entry>4</entry>
<entry>3</entry>
<entry>2</entry>
<entry>1</entry>
<entry>0</entry>
<entry>&nbsp;</entry>
<entry>7</entry>
<entry>6</entry>
<entry>5</entry>
<entry>4</entry>
<entry>3</entry>
<entry>2</entry>
<entry>1</entry>
<entry>0</entry>
<entry>&nbsp;</entry>
<entry>7</entry>
<entry>6</entry>
<entry>5</entry>
<entry>4</entry>
<entry>3</entry>
<entry>2</entry>
<entry>1</entry>
<entry>0</entry>
<entry>&nbsp;</entry>
<entry>7</entry>
<entry>6</entry>
<entry>5</entry>
<entry>4</entry>
<entry>3</entry>
<entry>2</entry>
<entry>1</entry>
<entry>0</entry>
</row>
</thead>
<tbody valign="top">
<row id="V4L2-PIX-FMT-RGB332">
<entry><constant>V4L2_PIX_FMT_RGB332</constant></entry>
<entry>'RGB1'</entry>
<entry></entry>
<entry>b<subscript>1</subscript></entry>
<entry>b<subscript>0</subscript></entry>
<entry>g<subscript>2</subscript></entry>
<entry>g<subscript>1</subscript></entry>
<entry>g<subscript>0</subscript></entry>
<entry>r<subscript>2</subscript></entry>
<entry>r<subscript>1</subscript></entry>
<entry>r<subscript>0</subscript></entry>
</row>
<row id="V4L2-PIX-FMT-RGB444">
<entry><constant>V4L2_PIX_FMT_RGB444</constant></entry>
<entry>'R444'</entry>
<entry></entry>
<entry>g<subscript>3</subscript></entry>
<entry>g<subscript>2</subscript></entry>
<entry>g<subscript>1</subscript></entry>
<entry>g<subscript>0</subscript></entry>
<entry>b<subscript>3</subscript></entry>
<entry>b<subscript>2</subscript></entry>
<entry>b<subscript>1</subscript></entry>
<entry>b<subscript>0</subscript></entry>
<entry></entry>
<entry>a<subscript>3</subscript></entry>
<entry>a<subscript>2</subscript></entry>
<entry>a<subscript>1</subscript></entry>
<entry>a<subscript>0</subscript></entry>
<entry>r<subscript>3</subscript></entry>
<entry>r<subscript>2</subscript></entry>
<entry>r<subscript>1</subscript></entry>
<entry>r<subscript>0</subscript></entry>
</row>
<row id="V4L2-PIX-FMT-RGB555">
<entry><constant>V4L2_PIX_FMT_RGB555</constant></entry>
<entry>'RGBO'</entry>
<entry></entry>
<entry>g<subscript>2</subscript></entry>
<entry>g<subscript>1</subscript></entry>
<entry>g<subscript>0</subscript></entry>
<entry>r<subscript>4</subscript></entry>
<entry>r<subscript>3</subscript></entry>
<entry>r<subscript>2</subscript></entry>
<entry>r<subscript>1</subscript></entry>
<entry>r<subscript>0</subscript></entry>
<entry></entry>
<entry>a</entry>
<entry>b<subscript>4</subscript></entry>
<entry>b<subscript>3</subscript></entry>
<entry>b<subscript>2</subscript></entry>
<entry>b<subscript>1</subscript></entry>
<entry>b<subscript>0</subscript></entry>
<entry>g<subscript>4</subscript></entry>
<entry>g<subscript>3</subscript></entry>
</row>
<row id="V4L2-PIX-FMT-RGB565">
<entry><constant>V4L2_PIX_FMT_RGB565</constant></entry>
<entry>'RGBP'</entry>
<entry></entry>
<entry>g<subscript>2</subscript></entry>
<entry>g<subscript>1</subscript></entry>
<entry>g<subscript>0</subscript></entry>
<entry>r<subscript>4</subscript></entry>
<entry>r<subscript>3</subscript></entry>
<entry>r<subscript>2</subscript></entry>
<entry>r<subscript>1</subscript></entry>
<entry>r<subscript>0</subscript></entry>
<entry></entry>
<entry>b<subscript>4</subscript></entry>
<entry>b<subscript>3</subscript></entry>
<entry>b<subscript>2</subscript></entry>
<entry>b<subscript>1</subscript></entry>
<entry>b<subscript>0</subscript></entry>
<entry>g<subscript>5</subscript></entry>
<entry>g<subscript>4</subscript></entry>
<entry>g<subscript>3</subscript></entry>
</row>
<row id="V4L2-PIX-FMT-RGB555X">
<entry><constant>V4L2_PIX_FMT_RGB555X</constant></entry>
<entry>'RGBQ'</entry>
<entry></entry>
<entry>a</entry>
<entry>b<subscript>4</subscript></entry>
<entry>b<subscript>3</subscript></entry>
<entry>b<subscript>2</subscript></entry>
<entry>b<subscript>1</subscript></entry>
<entry>b<subscript>0</subscript></entry>
<entry>g<subscript>4</subscript></entry>
<entry>g<subscript>3</subscript></entry>
<entry></entry>
<entry>g<subscript>2</subscript></entry>
<entry>g<subscript>1</subscript></entry>
<entry>g<subscript>0</subscript></entry>
<entry>r<subscript>4</subscript></entry>
<entry>r<subscript>3</subscript></entry>
<entry>r<subscript>2</subscript></entry>
<entry>r<subscript>1</subscript></entry>
<entry>r<subscript>0</subscript></entry>
</row>
<row id="V4L2-PIX-FMT-RGB565X">
<entry><constant>V4L2_PIX_FMT_RGB565X</constant></entry>
<entry>'RGBR'</entry>
<entry></entry>
<entry>b<subscript>4</subscript></entry>
<entry>b<subscript>3</subscript></entry>
<entry>b<subscript>2</subscript></entry>
<entry>b<subscript>1</subscript></entry>
<entry>b<subscript>0</subscript></entry>
<entry>g<subscript>5</subscript></entry>
<entry>g<subscript>4</subscript></entry>
<entry>g<subscript>3</subscript></entry>
<entry></entry>
<entry>g<subscript>2</subscript></entry>
<entry>g<subscript>1</subscript></entry>
<entry>g<subscript>0</subscript></entry>
<entry>r<subscript>4</subscript></entry>
<entry>r<subscript>3</subscript></entry>
<entry>r<subscript>2</subscript></entry>
<entry>r<subscript>1</subscript></entry>
<entry>r<subscript>0</subscript></entry>
</row>
<row id="V4L2-PIX-FMT-BGR666">
<entry><constant>V4L2_PIX_FMT_BGR666</constant></entry>
<entry>'BGRH'</entry>
<entry></entry>
<entry>b<subscript>5</subscript></entry>
<entry>b<subscript>4</subscript></entry>
<entry>b<subscript>3</subscript></entry>
<entry>b<subscript>2</subscript></entry>
<entry>b<subscript>1</subscript></entry>
<entry>b<subscript>0</subscript></entry>
<entry>g<subscript>5</subscript></entry>
<entry>g<subscript>4</subscript></entry>
<entry></entry>
<entry>g<subscript>3</subscript></entry>
<entry>g<subscript>2</subscript></entry>
<entry>g<subscript>1</subscript></entry>
<entry>g<subscript>0</subscript></entry>
<entry>r<subscript>5</subscript></entry>
<entry>r<subscript>4</subscript></entry>
<entry>r<subscript>3</subscript></entry>
<entry>r<subscript>2</subscript></entry>
<entry></entry>
<entry>r<subscript>1</subscript></entry>
<entry>r<subscript>0</subscript></entry>
<entry></entry>
<entry></entry>
<entry></entry>
<entry></entry>
<entry></entry>
<entry></entry>
<entry></entry>
<entry></entry>
<entry></entry>
<entry></entry>
<entry></entry>
<entry></entry>
<entry></entry>
<entry></entry>
</row>
<row id="V4L2-PIX-FMT-BGR24">
<entry><constant>V4L2_PIX_FMT_BGR24</constant></entry>
<entry>'BGR3'</entry>
<entry></entry>
<entry>b<subscript>7</subscript></entry>
<entry>b<subscript>6</subscript></entry>
<entry>b<subscript>5</subscript></entry>
<entry>b<subscript>4</subscript></entry>
<entry>b<subscript>3</subscript></entry>
<entry>b<subscript>2</subscript></entry>
<entry>b<subscript>1</subscript></entry>
<entry>b<subscript>0</subscript></entry>
<entry></entry>
<entry>g<subscript>7</subscript></entry>
<entry>g<subscript>6</subscript></entry>
<entry>g<subscript>5</subscript></entry>
<entry>g<subscript>4</subscript></entry>
<entry>g<subscript>3</subscript></entry>
<entry>g<subscript>2</subscript></entry>
<entry>g<subscript>1</subscript></entry>
<entry>g<subscript>0</subscript></entry>
<entry></entry>
<entry>r<subscript>7</subscript></entry>
<entry>r<subscript>6</subscript></entry>
<entry>r<subscript>5</subscript></entry>
<entry>r<subscript>4</subscript></entry>
<entry>r<subscript>3</subscript></entry>
<entry>r<subscript>2</subscript></entry>
<entry>r<subscript>1</subscript></entry>
<entry>r<subscript>0</subscript></entry>
</row>
<row id="V4L2-PIX-FMT-RGB24">
<entry><constant>V4L2_PIX_FMT_RGB24</constant></entry>
<entry>'RGB3'</entry>
<entry></entry>
<entry>r<subscript>7</subscript></entry>
<entry>r<subscript>6</subscript></entry>
<entry>r<subscript>5</subscript></entry>
<entry>r<subscript>4</subscript></entry>
<entry>r<subscript>3</subscript></entry>
<entry>r<subscript>2</subscript></entry>
<entry>r<subscript>1</subscript></entry>
<entry>r<subscript>0</subscript></entry>
<entry></entry>
<entry>g<subscript>7</subscript></entry>
<entry>g<subscript>6</subscript></entry>
<entry>g<subscript>5</subscript></entry>
<entry>g<subscript>4</subscript></entry>
<entry>g<subscript>3</subscript></entry>
<entry>g<subscript>2</subscript></entry>
<entry>g<subscript>1</subscript></entry>
<entry>g<subscript>0</subscript></entry>
<entry></entry>
<entry>b<subscript>7</subscript></entry>
<entry>b<subscript>6</subscript></entry>
<entry>b<subscript>5</subscript></entry>
<entry>b<subscript>4</subscript></entry>
<entry>b<subscript>3</subscript></entry>
<entry>b<subscript>2</subscript></entry>
<entry>b<subscript>1</subscript></entry>
<entry>b<subscript>0</subscript></entry>
</row>
<row id="V4L2-PIX-FMT-BGR32">
<entry><constant>V4L2_PIX_FMT_BGR32</constant></entry>
<entry>'BGR4'</entry>
<entry></entry>
<entry>b<subscript>7</subscript></entry>
<entry>b<subscript>6</subscript></entry>
<entry>b<subscript>5</subscript></entry>
<entry>b<subscript>4</subscript></entry>
<entry>b<subscript>3</subscript></entry>
<entry>b<subscript>2</subscript></entry>
<entry>b<subscript>1</subscript></entry>
<entry>b<subscript>0</subscript></entry>
<entry></entry>
<entry>g<subscript>7</subscript></entry>
<entry>g<subscript>6</subscript></entry>
<entry>g<subscript>5</subscript></entry>
<entry>g<subscript>4</subscript></entry>
<entry>g<subscript>3</subscript></entry>
<entry>g<subscript>2</subscript></entry>
<entry>g<subscript>1</subscript></entry>
<entry>g<subscript>0</subscript></entry>
<entry></entry>
<entry>r<subscript>7</subscript></entry>
<entry>r<subscript>6</subscript></entry>
<entry>r<subscript>5</subscript></entry>
<entry>r<subscript>4</subscript></entry>
<entry>r<subscript>3</subscript></entry>
<entry>r<subscript>2</subscript></entry>
<entry>r<subscript>1</subscript></entry>
<entry>r<subscript>0</subscript></entry>
<entry></entry>
<entry>a<subscript>7</subscript></entry>
<entry>a<subscript>6</subscript></entry>
<entry>a<subscript>5</subscript></entry>
<entry>a<subscript>4</subscript></entry>
<entry>a<subscript>3</subscript></entry>
<entry>a<subscript>2</subscript></entry>
<entry>a<subscript>1</subscript></entry>
<entry>a<subscript>0</subscript></entry>
</row>
<row id="V4L2-PIX-FMT-RGB32">
<entry><constant>V4L2_PIX_FMT_RGB32</constant></entry>
<entry>'RGB4'</entry>
<entry></entry>
<entry>r<subscript>7</subscript></entry>
<entry>r<subscript>6</subscript></entry>
<entry>r<subscript>5</subscript></entry>
<entry>r<subscript>4</subscript></entry>
<entry>r<subscript>3</subscript></entry>
<entry>r<subscript>2</subscript></entry>
<entry>r<subscript>1</subscript></entry>
<entry>r<subscript>0</subscript></entry>
<entry></entry>
<entry>g<subscript>7</subscript></entry>
<entry>g<subscript>6</subscript></entry>
<entry>g<subscript>5</subscript></entry>
<entry>g<subscript>4</subscript></entry>
<entry>g<subscript>3</subscript></entry>
<entry>g<subscript>2</subscript></entry>
<entry>g<subscript>1</subscript></entry>
<entry>g<subscript>0</subscript></entry>
<entry></entry>
<entry>b<subscript>7</subscript></entry>
<entry>b<subscript>6</subscript></entry>
<entry>b<subscript>5</subscript></entry>
<entry>b<subscript>4</subscript></entry>
<entry>b<subscript>3</subscript></entry>
<entry>b<subscript>2</subscript></entry>
<entry>b<subscript>1</subscript></entry>
<entry>b<subscript>0</subscript></entry>
<entry></entry>
<entry>a<subscript>7</subscript></entry>
<entry>a<subscript>6</subscript></entry>
<entry>a<subscript>5</subscript></entry>
<entry>a<subscript>4</subscript></entry>
<entry>a<subscript>3</subscript></entry>
<entry>a<subscript>2</subscript></entry>
<entry>a<subscript>1</subscript></entry>
<entry>a<subscript>0</subscript></entry>
</row>
</tbody>
</tgroup>
</table>
<para>Bit 7 is the most significant bit. The value of a = alpha
bits is undefined when reading from the driver, ignored when writing
to the driver, except when alpha blending has been negotiated for a
<link linkend="overlay">Video Overlay</link> or <link linkend="osd">
Video Output Overlay</link> or when alpha component has been configured
for a <link linkend="capture">Video Capture</link> by means of <link
linkend="v4l2-alpha-component"> <constant>V4L2_CID_ALPHA_COMPONENT
</constant> </link> control.</para>
<example>
<title><constant>V4L2_PIX_FMT_BGR24</constant> 4 &times; 4 pixel
image</title>
<formalpara>
<title>Byte Order.</title>
<para>Each cell is one byte.
<informaltable frame="none">
<tgroup cols="13" align="center">
<colspec align="left" colwidth="2*" />
<tbody valign="top">
<row>
<entry>start&nbsp;+&nbsp;0:</entry>
<entry>B<subscript>00</subscript></entry>
<entry>G<subscript>00</subscript></entry>
<entry>R<subscript>00</subscript></entry>
<entry>B<subscript>01</subscript></entry>
<entry>G<subscript>01</subscript></entry>
<entry>R<subscript>01</subscript></entry>
<entry>B<subscript>02</subscript></entry>
<entry>G<subscript>02</subscript></entry>
<entry>R<subscript>02</subscript></entry>
<entry>B<subscript>03</subscript></entry>
<entry>G<subscript>03</subscript></entry>
<entry>R<subscript>03</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;12:</entry>
<entry>B<subscript>10</subscript></entry>
<entry>G<subscript>10</subscript></entry>
<entry>R<subscript>10</subscript></entry>
<entry>B<subscript>11</subscript></entry>
<entry>G<subscript>11</subscript></entry>
<entry>R<subscript>11</subscript></entry>
<entry>B<subscript>12</subscript></entry>
<entry>G<subscript>12</subscript></entry>
<entry>R<subscript>12</subscript></entry>
<entry>B<subscript>13</subscript></entry>
<entry>G<subscript>13</subscript></entry>
<entry>R<subscript>13</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;24:</entry>
<entry>B<subscript>20</subscript></entry>
<entry>G<subscript>20</subscript></entry>
<entry>R<subscript>20</subscript></entry>
<entry>B<subscript>21</subscript></entry>
<entry>G<subscript>21</subscript></entry>
<entry>R<subscript>21</subscript></entry>
<entry>B<subscript>22</subscript></entry>
<entry>G<subscript>22</subscript></entry>
<entry>R<subscript>22</subscript></entry>
<entry>B<subscript>23</subscript></entry>
<entry>G<subscript>23</subscript></entry>
<entry>R<subscript>23</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;36:</entry>
<entry>B<subscript>30</subscript></entry>
<entry>G<subscript>30</subscript></entry>
<entry>R<subscript>30</subscript></entry>
<entry>B<subscript>31</subscript></entry>
<entry>G<subscript>31</subscript></entry>
<entry>R<subscript>31</subscript></entry>
<entry>B<subscript>32</subscript></entry>
<entry>G<subscript>32</subscript></entry>
<entry>R<subscript>32</subscript></entry>
<entry>B<subscript>33</subscript></entry>
<entry>G<subscript>33</subscript></entry>
<entry>R<subscript>33</subscript></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
</example>
<important>
<para>Drivers may interpret these formats differently.</para>
</important>
<para>Some RGB formats above are uncommon and were probably
defined in error. Drivers may interpret them as in <xref
linkend="rgb-formats-corrected" />.</para>
<table pgwide="1" frame="none" id="rgb-formats-corrected">
<title>Packed RGB Image Formats (corrected)</title>
<tgroup cols="37" align="center">
<colspec colname="id" align="left" />
<colspec colname="fourcc" />
<colspec colname="bit" />
<colspec colnum="4" colname="b07" align="center" />
<colspec colnum="5" colname="b06" align="center" />
<colspec colnum="6" colname="b05" align="center" />
<colspec colnum="7" colname="b04" align="center" />
<colspec colnum="8" colname="b03" align="center" />
<colspec colnum="9" colname="b02" align="center" />
<colspec colnum="10" colname="b01" align="center" />
<colspec colnum="11" colname="b00" align="center" />
<colspec colnum="13" colname="b17" align="center" />
<colspec colnum="14" colname="b16" align="center" />
<colspec colnum="15" colname="b15" align="center" />
<colspec colnum="16" colname="b14" align="center" />
<colspec colnum="17" colname="b13" align="center" />
<colspec colnum="18" colname="b12" align="center" />
<colspec colnum="19" colname="b11" align="center" />
<colspec colnum="20" colname="b10" align="center" />
<colspec colnum="22" colname="b27" align="center" />
<colspec colnum="23" colname="b26" align="center" />
<colspec colnum="24" colname="b25" align="center" />
<colspec colnum="25" colname="b24" align="center" />
<colspec colnum="26" colname="b23" align="center" />
<colspec colnum="27" colname="b22" align="center" />
<colspec colnum="28" colname="b21" align="center" />
<colspec colnum="29" colname="b20" align="center" />
<colspec colnum="31" colname="b37" align="center" />
<colspec colnum="32" colname="b36" align="center" />
<colspec colnum="33" colname="b35" align="center" />
<colspec colnum="34" colname="b34" align="center" />
<colspec colnum="35" colname="b33" align="center" />
<colspec colnum="36" colname="b32" align="center" />
<colspec colnum="37" colname="b31" align="center" />
<colspec colnum="38" colname="b30" align="center" />
<spanspec namest="b07" nameend="b00" spanname="b0" />
<spanspec namest="b17" nameend="b10" spanname="b1" />
<spanspec namest="b27" nameend="b20" spanname="b2" />
<spanspec namest="b37" nameend="b30" spanname="b3" />
<thead>
<row>
<entry>Identifier</entry>
<entry>Code</entry>
<entry>&nbsp;</entry>
<entry spanname="b0">Byte&nbsp;0 in memory</entry>
<entry spanname="b1">Byte&nbsp;1</entry>
<entry spanname="b2">Byte&nbsp;2</entry>
<entry spanname="b3">Byte&nbsp;3</entry>
</row>
<row>
<entry>&nbsp;</entry>
<entry>&nbsp;</entry>
<entry>Bit</entry>
<entry>7</entry>
<entry>6</entry>
<entry>5</entry>
<entry>4</entry>
<entry>3</entry>
<entry>2</entry>
<entry>1</entry>
<entry>0</entry>
<entry>&nbsp;</entry>
<entry>7</entry>
<entry>6</entry>
<entry>5</entry>
<entry>4</entry>
<entry>3</entry>
<entry>2</entry>
<entry>1</entry>
<entry>0</entry>
<entry>&nbsp;</entry>
<entry>7</entry>
<entry>6</entry>
<entry>5</entry>
<entry>4</entry>
<entry>3</entry>
<entry>2</entry>
<entry>1</entry>
<entry>0</entry>
<entry>&nbsp;</entry>
<entry>7</entry>
<entry>6</entry>
<entry>5</entry>
<entry>4</entry>
<entry>3</entry>
<entry>2</entry>
<entry>1</entry>
<entry>0</entry>
</row>
</thead>
<tbody valign="top">
<row><!-- id="V4L2-PIX-FMT-RGB332" -->
<entry><constant>V4L2_PIX_FMT_RGB332</constant></entry>
<entry>'RGB1'</entry>
<entry></entry>
<entry>r<subscript>2</subscript></entry>
<entry>r<subscript>1</subscript></entry>
<entry>r<subscript>0</subscript></entry>
<entry>g<subscript>2</subscript></entry>
<entry>g<subscript>1</subscript></entry>
<entry>g<subscript>0</subscript></entry>
<entry>b<subscript>1</subscript></entry>
<entry>b<subscript>0</subscript></entry>
</row>
<row><!-- id="V4L2-PIX-FMT-RGB444" -->
<entry><constant>V4L2_PIX_FMT_RGB444</constant></entry>
<entry>'R444'</entry>
<entry></entry>
<entry>g<subscript>3</subscript></entry>
<entry>g<subscript>2</subscript></entry>
<entry>g<subscript>1</subscript></entry>
<entry>g<subscript>0</subscript></entry>
<entry>b<subscript>3</subscript></entry>
<entry>b<subscript>2</subscript></entry>
<entry>b<subscript>1</subscript></entry>
<entry>b<subscript>0</subscript></entry>
<entry></entry>
<entry>a<subscript>3</subscript></entry>
<entry>a<subscript>2</subscript></entry>
<entry>a<subscript>1</subscript></entry>
<entry>a<subscript>0</subscript></entry>
<entry>r<subscript>3</subscript></entry>
<entry>r<subscript>2</subscript></entry>
<entry>r<subscript>1</subscript></entry>
<entry>r<subscript>0</subscript></entry>
</row>
<row><!-- id="V4L2-PIX-FMT-RGB555" -->
<entry><constant>V4L2_PIX_FMT_RGB555</constant></entry>
<entry>'RGBO'</entry>
<entry></entry>
<entry>g<subscript>2</subscript></entry>
<entry>g<subscript>1</subscript></entry>
<entry>g<subscript>0</subscript></entry>
<entry>b<subscript>4</subscript></entry>
<entry>b<subscript>3</subscript></entry>
<entry>b<subscript>2</subscript></entry>
<entry>b<subscript>1</subscript></entry>
<entry>b<subscript>0</subscript></entry>
<entry></entry>
<entry>a</entry>
<entry>r<subscript>4</subscript></entry>
<entry>r<subscript>3</subscript></entry>
<entry>r<subscript>2</subscript></entry>
<entry>r<subscript>1</subscript></entry>
<entry>r<subscript>0</subscript></entry>
<entry>g<subscript>4</subscript></entry>
<entry>g<subscript>3</subscript></entry>
</row>
<row><!-- id="V4L2-PIX-FMT-RGB565" -->
<entry><constant>V4L2_PIX_FMT_RGB565</constant></entry>
<entry>'RGBP'</entry>
<entry></entry>
<entry>g<subscript>2</subscript></entry>
<entry>g<subscript>1</subscript></entry>
<entry>g<subscript>0</subscript></entry>
<entry>b<subscript>4</subscript></entry>
<entry>b<subscript>3</subscript></entry>
<entry>b<subscript>2</subscript></entry>
<entry>b<subscript>1</subscript></entry>
<entry>b<subscript>0</subscript></entry>
<entry></entry>
<entry>r<subscript>4</subscript></entry>
<entry>r<subscript>3</subscript></entry>
<entry>r<subscript>2</subscript></entry>
<entry>r<subscript>1</subscript></entry>
<entry>r<subscript>0</subscript></entry>
<entry>g<subscript>5</subscript></entry>
<entry>g<subscript>4</subscript></entry>
<entry>g<subscript>3</subscript></entry>
</row>
<row><!-- id="V4L2-PIX-FMT-RGB555X" -->
<entry><constant>V4L2_PIX_FMT_RGB555X</constant></entry>
<entry>'RGBQ'</entry>
<entry></entry>
<entry>a</entry>
<entry>r<subscript>4</subscript></entry>
<entry>r<subscript>3</subscript></entry>
<entry>r<subscript>2</subscript></entry>
<entry>r<subscript>1</subscript></entry>
<entry>r<subscript>0</subscript></entry>
<entry>g<subscript>4</subscript></entry>
<entry>g<subscript>3</subscript></entry>
<entry></entry>
<entry>g<subscript>2</subscript></entry>
<entry>g<subscript>1</subscript></entry>
<entry>g<subscript>0</subscript></entry>
<entry>b<subscript>4</subscript></entry>
<entry>b<subscript>3</subscript></entry>
<entry>b<subscript>2</subscript></entry>
<entry>b<subscript>1</subscript></entry>
<entry>b<subscript>0</subscript></entry>
</row>
<row><!-- id="V4L2-PIX-FMT-RGB565X" -->
<entry><constant>V4L2_PIX_FMT_RGB565X</constant></entry>
<entry>'RGBR'</entry>
<entry></entry>
<entry>r<subscript>4</subscript></entry>
<entry>r<subscript>3</subscript></entry>
<entry>r<subscript>2</subscript></entry>
<entry>r<subscript>1</subscript></entry>
<entry>r<subscript>0</subscript></entry>
<entry>g<subscript>5</subscript></entry>
<entry>g<subscript>4</subscript></entry>
<entry>g<subscript>3</subscript></entry>
<entry></entry>
<entry>g<subscript>2</subscript></entry>
<entry>g<subscript>1</subscript></entry>
<entry>g<subscript>0</subscript></entry>
<entry>b<subscript>4</subscript></entry>
<entry>b<subscript>3</subscript></entry>
<entry>b<subscript>2</subscript></entry>
<entry>b<subscript>1</subscript></entry>
<entry>b<subscript>0</subscript></entry>
</row>
<row><!-- id="V4L2-PIX-FMT-BGR666" -->
<entry><constant>V4L2_PIX_FMT_BGR666</constant></entry>
<entry>'BGRH'</entry>
<entry></entry>
<entry>b<subscript>5</subscript></entry>
<entry>b<subscript>4</subscript></entry>
<entry>b<subscript>3</subscript></entry>
<entry>b<subscript>2</subscript></entry>
<entry>b<subscript>1</subscript></entry>
<entry>b<subscript>0</subscript></entry>
<entry>g<subscript>5</subscript></entry>
<entry>g<subscript>4</subscript></entry>
<entry></entry>
<entry>g<subscript>3</subscript></entry>
<entry>g<subscript>2</subscript></entry>
<entry>g<subscript>1</subscript></entry>
<entry>g<subscript>0</subscript></entry>
<entry>r<subscript>5</subscript></entry>
<entry>r<subscript>4</subscript></entry>
<entry>r<subscript>3</subscript></entry>
<entry>r<subscript>2</subscript></entry>
<entry></entry>
<entry>r<subscript>1</subscript></entry>
<entry>r<subscript>0</subscript></entry>
<entry></entry>
<entry></entry>
<entry></entry>
<entry></entry>
<entry></entry>
<entry></entry>
<entry></entry>
<entry></entry>
<entry></entry>
<entry></entry>
<entry></entry>
<entry></entry>
<entry></entry>
<entry></entry>
</row>
<row><!-- id="V4L2-PIX-FMT-BGR24" -->
<entry><constant>V4L2_PIX_FMT_BGR24</constant></entry>
<entry>'BGR3'</entry>
<entry></entry>
<entry>b<subscript>7</subscript></entry>
<entry>b<subscript>6</subscript></entry>
<entry>b<subscript>5</subscript></entry>
<entry>b<subscript>4</subscript></entry>
<entry>b<subscript>3</subscript></entry>
<entry>b<subscript>2</subscript></entry>
<entry>b<subscript>1</subscript></entry>
<entry>b<subscript>0</subscript></entry>
<entry></entry>
<entry>g<subscript>7</subscript></entry>
<entry>g<subscript>6</subscript></entry>
<entry>g<subscript>5</subscript></entry>
<entry>g<subscript>4</subscript></entry>
<entry>g<subscript>3</subscript></entry>
<entry>g<subscript>2</subscript></entry>
<entry>g<subscript>1</subscript></entry>
<entry>g<subscript>0</subscript></entry>
<entry></entry>
<entry>r<subscript>7</subscript></entry>
<entry>r<subscript>6</subscript></entry>
<entry>r<subscript>5</subscript></entry>
<entry>r<subscript>4</subscript></entry>
<entry>r<subscript>3</subscript></entry>
<entry>r<subscript>2</subscript></entry>
<entry>r<subscript>1</subscript></entry>
<entry>r<subscript>0</subscript></entry>
</row>
<row><!-- id="V4L2-PIX-FMT-RGB24" -->
<entry><constant>V4L2_PIX_FMT_RGB24</constant></entry>
<entry>'RGB3'</entry>
<entry></entry>
<entry>r<subscript>7</subscript></entry>
<entry>r<subscript>6</subscript></entry>
<entry>r<subscript>5</subscript></entry>
<entry>r<subscript>4</subscript></entry>
<entry>r<subscript>3</subscript></entry>
<entry>r<subscript>2</subscript></entry>
<entry>r<subscript>1</subscript></entry>
<entry>r<subscript>0</subscript></entry>
<entry></entry>
<entry>g<subscript>7</subscript></entry>
<entry>g<subscript>6</subscript></entry>
<entry>g<subscript>5</subscript></entry>
<entry>g<subscript>4</subscript></entry>
<entry>g<subscript>3</subscript></entry>
<entry>g<subscript>2</subscript></entry>
<entry>g<subscript>1</subscript></entry>
<entry>g<subscript>0</subscript></entry>
<entry></entry>
<entry>b<subscript>7</subscript></entry>
<entry>b<subscript>6</subscript></entry>
<entry>b<subscript>5</subscript></entry>
<entry>b<subscript>4</subscript></entry>
<entry>b<subscript>3</subscript></entry>
<entry>b<subscript>2</subscript></entry>
<entry>b<subscript>1</subscript></entry>
<entry>b<subscript>0</subscript></entry>
</row>
<row><!-- id="V4L2-PIX-FMT-BGR32" -->
<entry><constant>V4L2_PIX_FMT_BGR32</constant></entry>
<entry>'BGR4'</entry>
<entry></entry>
<entry>b<subscript>7</subscript></entry>
<entry>b<subscript>6</subscript></entry>
<entry>b<subscript>5</subscript></entry>
<entry>b<subscript>4</subscript></entry>
<entry>b<subscript>3</subscript></entry>
<entry>b<subscript>2</subscript></entry>
<entry>b<subscript>1</subscript></entry>
<entry>b<subscript>0</subscript></entry>
<entry></entry>
<entry>g<subscript>7</subscript></entry>
<entry>g<subscript>6</subscript></entry>
<entry>g<subscript>5</subscript></entry>
<entry>g<subscript>4</subscript></entry>
<entry>g<subscript>3</subscript></entry>
<entry>g<subscript>2</subscript></entry>
<entry>g<subscript>1</subscript></entry>
<entry>g<subscript>0</subscript></entry>
<entry></entry>
<entry>r<subscript>7</subscript></entry>
<entry>r<subscript>6</subscript></entry>
<entry>r<subscript>5</subscript></entry>
<entry>r<subscript>4</subscript></entry>
<entry>r<subscript>3</subscript></entry>
<entry>r<subscript>2</subscript></entry>
<entry>r<subscript>1</subscript></entry>
<entry>r<subscript>0</subscript></entry>
<entry></entry>
<entry>a<subscript>7</subscript></entry>
<entry>a<subscript>6</subscript></entry>
<entry>a<subscript>5</subscript></entry>
<entry>a<subscript>4</subscript></entry>
<entry>a<subscript>3</subscript></entry>
<entry>a<subscript>2</subscript></entry>
<entry>a<subscript>1</subscript></entry>
<entry>a<subscript>0</subscript></entry>
</row>
<row><!-- id="V4L2-PIX-FMT-RGB32" -->
<entry><constant>V4L2_PIX_FMT_RGB32</constant></entry>
<entry>'RGB4'</entry>
<entry></entry>
<entry>a<subscript>7</subscript></entry>
<entry>a<subscript>6</subscript></entry>
<entry>a<subscript>5</subscript></entry>
<entry>a<subscript>4</subscript></entry>
<entry>a<subscript>3</subscript></entry>
<entry>a<subscript>2</subscript></entry>
<entry>a<subscript>1</subscript></entry>
<entry>a<subscript>0</subscript></entry>
<entry></entry>
<entry>r<subscript>7</subscript></entry>
<entry>r<subscript>6</subscript></entry>
<entry>r<subscript>5</subscript></entry>
<entry>r<subscript>4</subscript></entry>
<entry>r<subscript>3</subscript></entry>
<entry>r<subscript>2</subscript></entry>
<entry>r<subscript>1</subscript></entry>
<entry>r<subscript>0</subscript></entry>
<entry></entry>
<entry>g<subscript>7</subscript></entry>
<entry>g<subscript>6</subscript></entry>
<entry>g<subscript>5</subscript></entry>
<entry>g<subscript>4</subscript></entry>
<entry>g<subscript>3</subscript></entry>
<entry>g<subscript>2</subscript></entry>
<entry>g<subscript>1</subscript></entry>
<entry>g<subscript>0</subscript></entry>
<entry></entry>
<entry>b<subscript>7</subscript></entry>
<entry>b<subscript>6</subscript></entry>
<entry>b<subscript>5</subscript></entry>
<entry>b<subscript>4</subscript></entry>
<entry>b<subscript>3</subscript></entry>
<entry>b<subscript>2</subscript></entry>
<entry>b<subscript>1</subscript></entry>
<entry>b<subscript>0</subscript></entry>
</row>
</tbody>
</tgroup>
</table>
<para>A test utility to determine which RGB formats a driver
actually supports is available from the LinuxTV v4l-dvb repository.
See &v4l-dvb; for access instructions.</para>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/pixfmt-packed-yuv.xml
+236
View File
@@ -0,0 +1,236 @@
<refentry id="packed-yuv">
<refmeta>
<refentrytitle>Packed YUV formats</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>Packed YUV formats</refname>
<refpurpose>Packed YUV formats</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>Similar to the packed RGB formats these formats store
the Y, Cb and Cr component of each pixel in one 16 or 32 bit
word.</para>
<table pgwide="1" frame="none">
<title>Packed YUV Image Formats</title>
<tgroup cols="37" align="center">
<colspec colname="id" align="left" />
<colspec colname="fourcc" />
<colspec colname="bit" />
<colspec colnum="4" colname="b07" align="center" />
<colspec colnum="5" colname="b06" align="center" />
<colspec colnum="6" colname="b05" align="center" />
<colspec colnum="7" colname="b04" align="center" />
<colspec colnum="8" colname="b03" align="center" />
<colspec colnum="9" colname="b02" align="center" />
<colspec colnum="10" colname="b01" align="center" />
<colspec colnum="11" colname="b00" align="center" />
<colspec colnum="13" colname="b17" align="center" />
<colspec colnum="14" colname="b16" align="center" />
<colspec colnum="15" colname="b15" align="center" />
<colspec colnum="16" colname="b14" align="center" />
<colspec colnum="17" colname="b13" align="center" />
<colspec colnum="18" colname="b12" align="center" />
<colspec colnum="19" colname="b11" align="center" />
<colspec colnum="20" colname="b10" align="center" />
<colspec colnum="22" colname="b27" align="center" />
<colspec colnum="23" colname="b26" align="center" />
<colspec colnum="24" colname="b25" align="center" />
<colspec colnum="25" colname="b24" align="center" />
<colspec colnum="26" colname="b23" align="center" />
<colspec colnum="27" colname="b22" align="center" />
<colspec colnum="28" colname="b21" align="center" />
<colspec colnum="29" colname="b20" align="center" />
<colspec colnum="31" colname="b37" align="center" />
<colspec colnum="32" colname="b36" align="center" />
<colspec colnum="33" colname="b35" align="center" />
<colspec colnum="34" colname="b34" align="center" />
<colspec colnum="35" colname="b33" align="center" />
<colspec colnum="36" colname="b32" align="center" />
<colspec colnum="37" colname="b31" align="center" />
<colspec colnum="38" colname="b30" align="center" />
<spanspec namest="b07" nameend="b00" spanname="b0" />
<spanspec namest="b17" nameend="b10" spanname="b1" />
<spanspec namest="b27" nameend="b20" spanname="b2" />
<spanspec namest="b37" nameend="b30" spanname="b3" />
<thead>
<row>
<entry>Identifier</entry>
<entry>Code</entry>
<entry>&nbsp;</entry>
<entry spanname="b0">Byte&nbsp;0 in memory</entry>
<entry spanname="b1">Byte&nbsp;1</entry>
<entry spanname="b2">Byte&nbsp;2</entry>
<entry spanname="b3">Byte&nbsp;3</entry>
</row>
<row>
<entry>&nbsp;</entry>
<entry>&nbsp;</entry>
<entry>Bit</entry>
<entry>7</entry>
<entry>6</entry>
<entry>5</entry>
<entry>4</entry>
<entry>3</entry>
<entry>2</entry>
<entry>1</entry>
<entry>0</entry>
<entry>&nbsp;</entry>
<entry>7</entry>
<entry>6</entry>
<entry>5</entry>
<entry>4</entry>
<entry>3</entry>
<entry>2</entry>
<entry>1</entry>
<entry>0</entry>
<entry>&nbsp;</entry>
<entry>7</entry>
<entry>6</entry>
<entry>5</entry>
<entry>4</entry>
<entry>3</entry>
<entry>2</entry>
<entry>1</entry>
<entry>0</entry>
<entry>&nbsp;</entry>
<entry>7</entry>
<entry>6</entry>
<entry>5</entry>
<entry>4</entry>
<entry>3</entry>
<entry>2</entry>
<entry>1</entry>
<entry>0</entry>
</row>
</thead>
<tbody valign="top">
<row id="V4L2-PIX-FMT-YUV444">
<entry><constant>V4L2_PIX_FMT_YUV444</constant></entry>
<entry>'Y444'</entry>
<entry></entry>
<entry>Cb<subscript>3</subscript></entry>
<entry>Cb<subscript>2</subscript></entry>
<entry>Cb<subscript>1</subscript></entry>
<entry>Cb<subscript>0</subscript></entry>
<entry>Cr<subscript>3</subscript></entry>
<entry>Cr<subscript>2</subscript></entry>
<entry>Cr<subscript>1</subscript></entry>
<entry>Cr<subscript>0</subscript></entry>
<entry></entry>
<entry>a<subscript>3</subscript></entry>
<entry>a<subscript>2</subscript></entry>
<entry>a<subscript>1</subscript></entry>
<entry>a<subscript>0</subscript></entry>
<entry>Y'<subscript>3</subscript></entry>
<entry>Y'<subscript>2</subscript></entry>
<entry>Y'<subscript>1</subscript></entry>
<entry>Y'<subscript>0</subscript></entry>
</row>
<row id="V4L2-PIX-FMT-YUV555">
<entry><constant>V4L2_PIX_FMT_YUV555</constant></entry>
<entry>'YUVO'</entry>
<entry></entry>
<entry>Cb<subscript>2</subscript></entry>
<entry>Cb<subscript>1</subscript></entry>
<entry>Cb<subscript>0</subscript></entry>
<entry>Cr<subscript>4</subscript></entry>
<entry>Cr<subscript>3</subscript></entry>
<entry>Cr<subscript>2</subscript></entry>
<entry>Cr<subscript>1</subscript></entry>
<entry>Cr<subscript>0</subscript></entry>
<entry></entry>
<entry>a</entry>
<entry>Y'<subscript>4</subscript></entry>
<entry>Y'<subscript>3</subscript></entry>
<entry>Y'<subscript>2</subscript></entry>
<entry>Y'<subscript>1</subscript></entry>
<entry>Y'<subscript>0</subscript></entry>
<entry>Cb<subscript>4</subscript></entry>
<entry>Cb<subscript>3</subscript></entry>
</row>
<row id="V4L2-PIX-FMT-YUV565">
<entry><constant>V4L2_PIX_FMT_YUV565</constant></entry>
<entry>'YUVP'</entry>
<entry></entry>
<entry>Cb<subscript>2</subscript></entry>
<entry>Cb<subscript>1</subscript></entry>
<entry>Cb<subscript>0</subscript></entry>
<entry>Cr<subscript>4</subscript></entry>
<entry>Cr<subscript>3</subscript></entry>
<entry>Cr<subscript>2</subscript></entry>
<entry>Cr<subscript>1</subscript></entry>
<entry>Cr<subscript>0</subscript></entry>
<entry></entry>
<entry>Y'<subscript>4</subscript></entry>
<entry>Y'<subscript>3</subscript></entry>
<entry>Y'<subscript>2</subscript></entry>
<entry>Y'<subscript>1</subscript></entry>
<entry>Y'<subscript>0</subscript></entry>
<entry>Cb<subscript>5</subscript></entry>
<entry>Cb<subscript>4</subscript></entry>
<entry>Cb<subscript>3</subscript></entry>
</row>
<row id="V4L2-PIX-FMT-YUV32">
<entry><constant>V4L2_PIX_FMT_YUV32</constant></entry>
<entry>'YUV4'</entry>
<entry></entry>
<entry>a<subscript>7</subscript></entry>
<entry>a<subscript>6</subscript></entry>
<entry>a<subscript>5</subscript></entry>
<entry>a<subscript>4</subscript></entry>
<entry>a<subscript>3</subscript></entry>
<entry>a<subscript>2</subscript></entry>
<entry>a<subscript>1</subscript></entry>
<entry>a<subscript>0</subscript></entry>
<entry></entry>
<entry>Y'<subscript>7</subscript></entry>
<entry>Y'<subscript>6</subscript></entry>
<entry>Y'<subscript>5</subscript></entry>
<entry>Y'<subscript>4</subscript></entry>
<entry>Y'<subscript>3</subscript></entry>
<entry>Y'<subscript>2</subscript></entry>
<entry>Y'<subscript>1</subscript></entry>
<entry>Y'<subscript>0</subscript></entry>
<entry></entry>
<entry>Cb<subscript>7</subscript></entry>
<entry>Cb<subscript>6</subscript></entry>
<entry>Cb<subscript>5</subscript></entry>
<entry>Cb<subscript>4</subscript></entry>
<entry>Cb<subscript>3</subscript></entry>
<entry>Cb<subscript>2</subscript></entry>
<entry>Cb<subscript>1</subscript></entry>
<entry>Cb<subscript>0</subscript></entry>
<entry></entry>
<entry>Cr<subscript>7</subscript></entry>
<entry>Cr<subscript>6</subscript></entry>
<entry>Cr<subscript>5</subscript></entry>
<entry>Cr<subscript>4</subscript></entry>
<entry>Cr<subscript>3</subscript></entry>
<entry>Cr<subscript>2</subscript></entry>
<entry>Cr<subscript>1</subscript></entry>
<entry>Cr<subscript>0</subscript></entry>
</row>
</tbody>
</tgroup>
</table>
<para>Bit 7 is the most significant bit. The value of a = alpha
bits is undefined when reading from the driver, ignored when writing
to the driver, except when alpha blending has been negotiated for a
<link linkend="overlay">Video Overlay</link> or <link
linkend="osd">Video Output Overlay</link>.</para>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/pixfmt-sbggr16.xml
+83
View File
@@ -0,0 +1,83 @@
<refentry id="V4L2-PIX-FMT-SBGGR16">
<refmeta>
<refentrytitle>V4L2_PIX_FMT_SBGGR16 ('BYR2')</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname><constant>V4L2_PIX_FMT_SBGGR16</constant></refname>
<refpurpose>Bayer RGB format</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>This format is similar to <link
linkend="V4L2-PIX-FMT-SBGGR8">
<constant>V4L2_PIX_FMT_SBGGR8</constant></link>, except each pixel has
a depth of 16 bits. The least significant byte is stored at lower
memory addresses (little-endian). Note the actual sampling precision
may be lower than 16 bits, for example 10 bits per pixel with values
in range 0 to 1023.</para>
<example>
<title><constant>V4L2_PIX_FMT_SBGGR16</constant> 4 &times; 4
pixel image</title>
<formalpara>
<title>Byte Order.</title>
<para>Each cell is one byte.
<informaltable frame="none">
<tgroup cols="5" align="center">
<colspec align="left" colwidth="2*" />
<tbody valign="top">
<row>
<entry>start&nbsp;+&nbsp;0:</entry>
<entry>B<subscript>00low</subscript></entry>
<entry>B<subscript>00high</subscript></entry>
<entry>G<subscript>01low</subscript></entry>
<entry>G<subscript>01high</subscript></entry>
<entry>B<subscript>02low</subscript></entry>
<entry>B<subscript>02high</subscript></entry>
<entry>G<subscript>03low</subscript></entry>
<entry>G<subscript>03high</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;8:</entry>
<entry>G<subscript>10low</subscript></entry>
<entry>G<subscript>10high</subscript></entry>
<entry>R<subscript>11low</subscript></entry>
<entry>R<subscript>11high</subscript></entry>
<entry>G<subscript>12low</subscript></entry>
<entry>G<subscript>12high</subscript></entry>
<entry>R<subscript>13low</subscript></entry>
<entry>R<subscript>13high</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;16:</entry>
<entry>B<subscript>20low</subscript></entry>
<entry>B<subscript>20high</subscript></entry>
<entry>G<subscript>21low</subscript></entry>
<entry>G<subscript>21high</subscript></entry>
<entry>B<subscript>22low</subscript></entry>
<entry>B<subscript>22high</subscript></entry>
<entry>G<subscript>23low</subscript></entry>
<entry>G<subscript>23high</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;24:</entry>
<entry>G<subscript>30low</subscript></entry>
<entry>G<subscript>30high</subscript></entry>
<entry>R<subscript>31low</subscript></entry>
<entry>R<subscript>31high</subscript></entry>
<entry>G<subscript>32low</subscript></entry>
<entry>G<subscript>32high</subscript></entry>
<entry>R<subscript>33low</subscript></entry>
<entry>R<subscript>33high</subscript></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
</example>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/pixfmt-sbggr8.xml
+67
View File
@@ -0,0 +1,67 @@
<refentry id="V4L2-PIX-FMT-SBGGR8">
<refmeta>
<refentrytitle>V4L2_PIX_FMT_SBGGR8 ('BA81')</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname><constant>V4L2_PIX_FMT_SBGGR8</constant></refname>
<refpurpose>Bayer RGB format</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>This is commonly the native format of digital cameras,
reflecting the arrangement of sensors on the CCD device. Only one red,
green or blue value is given for each pixel. Missing components must
be interpolated from neighbouring pixels. From left to right the first
row consists of a blue and green value, the second row of a green and
red value. This scheme repeats to the right and down for every two
columns and rows.</para>
<example>
<title><constant>V4L2_PIX_FMT_SBGGR8</constant> 4 &times; 4
pixel image</title>
<formalpara>
<title>Byte Order.</title>
<para>Each cell is one byte.
<informaltable frame="none">
<tgroup cols="5" align="center">
<colspec align="left" colwidth="2*" />
<tbody valign="top">
<row>
<entry>start&nbsp;+&nbsp;0:</entry>
<entry>B<subscript>00</subscript></entry>
<entry>G<subscript>01</subscript></entry>
<entry>B<subscript>02</subscript></entry>
<entry>G<subscript>03</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;4:</entry>
<entry>G<subscript>10</subscript></entry>
<entry>R<subscript>11</subscript></entry>
<entry>G<subscript>12</subscript></entry>
<entry>R<subscript>13</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;8:</entry>
<entry>B<subscript>20</subscript></entry>
<entry>G<subscript>21</subscript></entry>
<entry>B<subscript>22</subscript></entry>
<entry>G<subscript>23</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;12:</entry>
<entry>G<subscript>30</subscript></entry>
<entry>R<subscript>31</subscript></entry>
<entry>G<subscript>32</subscript></entry>
<entry>R<subscript>33</subscript></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
</example>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/pixfmt-sgbrg8.xml
+67
View File
@@ -0,0 +1,67 @@
<refentry id="V4L2-PIX-FMT-SGBRG8">
<refmeta>
<refentrytitle>V4L2_PIX_FMT_SGBRG8 ('GBRG')</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname><constant>V4L2_PIX_FMT_SGBRG8</constant></refname>
<refpurpose>Bayer RGB format</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>This is commonly the native format of digital cameras,
reflecting the arrangement of sensors on the CCD device. Only one red,
green or blue value is given for each pixel. Missing components must
be interpolated from neighbouring pixels. From left to right the first
row consists of a green and blue value, the second row of a red and
green value. This scheme repeats to the right and down for every two
columns and rows.</para>
<example>
<title><constant>V4L2_PIX_FMT_SGBRG8</constant> 4 &times; 4
pixel image</title>
<formalpara>
<title>Byte Order.</title>
<para>Each cell is one byte.
<informaltable frame="none">
<tgroup cols="5" align="center">
<colspec align="left" colwidth="2*" />
<tbody valign="top">
<row>
<entry>start&nbsp;+&nbsp;0:</entry>
<entry>G<subscript>00</subscript></entry>
<entry>B<subscript>01</subscript></entry>
<entry>G<subscript>02</subscript></entry>
<entry>B<subscript>03</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;4:</entry>
<entry>R<subscript>10</subscript></entry>
<entry>G<subscript>11</subscript></entry>
<entry>R<subscript>12</subscript></entry>
<entry>G<subscript>13</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;8:</entry>
<entry>G<subscript>20</subscript></entry>
<entry>B<subscript>21</subscript></entry>
<entry>G<subscript>22</subscript></entry>
<entry>B<subscript>23</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;12:</entry>
<entry>R<subscript>30</subscript></entry>
<entry>G<subscript>31</subscript></entry>
<entry>R<subscript>32</subscript></entry>
<entry>G<subscript>33</subscript></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
</example>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/pixfmt-sgrbg8.xml
+67
View File
@@ -0,0 +1,67 @@
<refentry id="V4L2-PIX-FMT-SGRBG8">
<refmeta>
<refentrytitle>V4L2_PIX_FMT_SGRBG8 ('GRBG')</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname><constant>V4L2_PIX_FMT_SGRBG8</constant></refname>
<refpurpose>Bayer RGB format</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>This is commonly the native format of digital cameras,
reflecting the arrangement of sensors on the CCD device. Only one red,
green or blue value is given for each pixel. Missing components must
be interpolated from neighbouring pixels. From left to right the first
row consists of a green and blue value, the second row of a red and
green value. This scheme repeats to the right and down for every two
columns and rows.</para>
<example>
<title><constant>V4L2_PIX_FMT_SGRBG8</constant> 4 &times;
4 pixel image</title>
<formalpara>
<title>Byte Order.</title>
<para>Each cell is one byte.
<informaltable frame="none">
<tgroup cols="5" align="center">
<colspec align="left" colwidth="2*" />
<tbody valign="top">
<row>
<entry>start&nbsp;+&nbsp;0:</entry>
<entry>G<subscript>00</subscript></entry>
<entry>R<subscript>01</subscript></entry>
<entry>G<subscript>02</subscript></entry>
<entry>R<subscript>03</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;4:</entry>
<entry>R<subscript>10</subscript></entry>
<entry>B<subscript>11</subscript></entry>
<entry>R<subscript>12</subscript></entry>
<entry>B<subscript>13</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;8:</entry>
<entry>G<subscript>20</subscript></entry>
<entry>R<subscript>21</subscript></entry>
<entry>G<subscript>22</subscript></entry>
<entry>R<subscript>23</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;12:</entry>
<entry>R<subscript>30</subscript></entry>
<entry>B<subscript>31</subscript></entry>
<entry>R<subscript>32</subscript></entry>
<entry>B<subscript>33</subscript></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
</example>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/pixfmt-srggb10.xml
+90
View File
@@ -0,0 +1,90 @@
<refentry>
<refmeta>
<refentrytitle>V4L2_PIX_FMT_SRGGB10 ('RG10'),
V4L2_PIX_FMT_SGRBG10 ('BA10'),
V4L2_PIX_FMT_SGBRG10 ('GB10'),
V4L2_PIX_FMT_SBGGR10 ('BG10'),
</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname id="V4L2-PIX-FMT-SRGGB10"><constant>V4L2_PIX_FMT_SRGGB10</constant></refname>
<refname id="V4L2-PIX-FMT-SGRBG10"><constant>V4L2_PIX_FMT_SGRBG10</constant></refname>
<refname id="V4L2-PIX-FMT-SGBRG10"><constant>V4L2_PIX_FMT_SGBRG10</constant></refname>
<refname id="V4L2-PIX-FMT-SBGGR10"><constant>V4L2_PIX_FMT_SBGGR10</constant></refname>
<refpurpose>10-bit Bayer formats expanded to 16 bits</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>The following four pixel formats are raw sRGB / Bayer formats with
10 bits per colour. Each colour component is stored in a 16-bit word, with 6
unused high bits filled with zeros. Each n-pixel row contains n/2 green samples
and n/2 blue or red samples, with alternating red and blue rows. Bytes are
stored in memory in little endian order. They are conventionally described
as GRGR... BGBG..., RGRG... GBGB..., etc. Below is an example of one of these
formats</para>
<example>
<title><constant>V4L2_PIX_FMT_SBGGR10</constant> 4 &times; 4
pixel image</title>
<formalpara>
<title>Byte Order.</title>
<para>Each cell is one byte, high 6 bits in high bytes are 0.
<informaltable frame="none">
<tgroup cols="5" align="center">
<colspec align="left" colwidth="2*" />
<tbody valign="top">
<row>
<entry>start&nbsp;+&nbsp;0:</entry>
<entry>B<subscript>00low</subscript></entry>
<entry>B<subscript>00high</subscript></entry>
<entry>G<subscript>01low</subscript></entry>
<entry>G<subscript>01high</subscript></entry>
<entry>B<subscript>02low</subscript></entry>
<entry>B<subscript>02high</subscript></entry>
<entry>G<subscript>03low</subscript></entry>
<entry>G<subscript>03high</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;8:</entry>
<entry>G<subscript>10low</subscript></entry>
<entry>G<subscript>10high</subscript></entry>
<entry>R<subscript>11low</subscript></entry>
<entry>R<subscript>11high</subscript></entry>
<entry>G<subscript>12low</subscript></entry>
<entry>G<subscript>12high</subscript></entry>
<entry>R<subscript>13low</subscript></entry>
<entry>R<subscript>13high</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;16:</entry>
<entry>B<subscript>20low</subscript></entry>
<entry>B<subscript>20high</subscript></entry>
<entry>G<subscript>21low</subscript></entry>
<entry>G<subscript>21high</subscript></entry>
<entry>B<subscript>22low</subscript></entry>
<entry>B<subscript>22high</subscript></entry>
<entry>G<subscript>23low</subscript></entry>
<entry>G<subscript>23high</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;24:</entry>
<entry>G<subscript>30low</subscript></entry>
<entry>G<subscript>30high</subscript></entry>
<entry>R<subscript>31low</subscript></entry>
<entry>R<subscript>31high</subscript></entry>
<entry>G<subscript>32low</subscript></entry>
<entry>G<subscript>32high</subscript></entry>
<entry>R<subscript>33low</subscript></entry>
<entry>R<subscript>33high</subscript></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
</example>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/pixfmt-srggb12.xml
+90
View File
@@ -0,0 +1,90 @@
<refentry>
<refmeta>
<refentrytitle>V4L2_PIX_FMT_SRGGB12 ('RG12'),
V4L2_PIX_FMT_SGRBG12 ('BA12'),
V4L2_PIX_FMT_SGBRG12 ('GB12'),
V4L2_PIX_FMT_SBGGR12 ('BG12'),
</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname id="V4L2-PIX-FMT-SRGGB12"><constant>V4L2_PIX_FMT_SRGGB12</constant></refname>
<refname id="V4L2-PIX-FMT-SGRBG12"><constant>V4L2_PIX_FMT_SGRBG12</constant></refname>
<refname id="V4L2-PIX-FMT-SGBRG12"><constant>V4L2_PIX_FMT_SGBRG12</constant></refname>
<refname id="V4L2-PIX-FMT-SBGGR12"><constant>V4L2_PIX_FMT_SBGGR12</constant></refname>
<refpurpose>12-bit Bayer formats expanded to 16 bits</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>The following four pixel formats are raw sRGB / Bayer formats with
12 bits per colour. Each colour component is stored in a 16-bit word, with 6
unused high bits filled with zeros. Each n-pixel row contains n/2 green samples
and n/2 blue or red samples, with alternating red and blue rows. Bytes are
stored in memory in little endian order. They are conventionally described
as GRGR... BGBG..., RGRG... GBGB..., etc. Below is an example of one of these
formats</para>
<example>
<title><constant>V4L2_PIX_FMT_SBGGR12</constant> 4 &times; 4
pixel image</title>
<formalpara>
<title>Byte Order.</title>
<para>Each cell is one byte, high 6 bits in high bytes are 0.
<informaltable frame="none">
<tgroup cols="5" align="center">
<colspec align="left" colwidth="2*" />
<tbody valign="top">
<row>
<entry>start&nbsp;+&nbsp;0:</entry>
<entry>B<subscript>00low</subscript></entry>
<entry>B<subscript>00high</subscript></entry>
<entry>G<subscript>01low</subscript></entry>
<entry>G<subscript>01high</subscript></entry>
<entry>B<subscript>02low</subscript></entry>
<entry>B<subscript>02high</subscript></entry>
<entry>G<subscript>03low</subscript></entry>
<entry>G<subscript>03high</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;8:</entry>
<entry>G<subscript>10low</subscript></entry>
<entry>G<subscript>10high</subscript></entry>
<entry>R<subscript>11low</subscript></entry>
<entry>R<subscript>11high</subscript></entry>
<entry>G<subscript>12low</subscript></entry>
<entry>G<subscript>12high</subscript></entry>
<entry>R<subscript>13low</subscript></entry>
<entry>R<subscript>13high</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;16:</entry>
<entry>B<subscript>20low</subscript></entry>
<entry>B<subscript>20high</subscript></entry>
<entry>G<subscript>21low</subscript></entry>
<entry>G<subscript>21high</subscript></entry>
<entry>B<subscript>22low</subscript></entry>
<entry>B<subscript>22high</subscript></entry>
<entry>G<subscript>23low</subscript></entry>
<entry>G<subscript>23high</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;24:</entry>
<entry>G<subscript>30low</subscript></entry>
<entry>G<subscript>30high</subscript></entry>
<entry>R<subscript>31low</subscript></entry>
<entry>R<subscript>31high</subscript></entry>
<entry>G<subscript>32low</subscript></entry>
<entry>G<subscript>32high</subscript></entry>
<entry>R<subscript>33low</subscript></entry>
<entry>R<subscript>33high</subscript></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
</example>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/pixfmt-srggb8.xml
+67
View File
@@ -0,0 +1,67 @@
<refentry id="V4L2-PIX-FMT-SRGGB8">
<refmeta>
<refentrytitle>V4L2_PIX_FMT_SRGGB8 ('RGGB')</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname><constant>V4L2_PIX_FMT_SRGGB8</constant></refname>
<refpurpose>Bayer RGB format</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>This is commonly the native format of digital cameras,
reflecting the arrangement of sensors on the CCD device. Only one red,
green or blue value is given for each pixel. Missing components must
be interpolated from neighbouring pixels. From left to right the first
row consists of a red and green value, the second row of a green and
blue value. This scheme repeats to the right and down for every two
columns and rows.</para>
<example>
<title><constant>V4L2_PIX_FMT_SRGGB8</constant> 4 &times; 4
pixel image</title>
<formalpara>
<title>Byte Order.</title>
<para>Each cell is one byte.
<informaltable frame="none">
<tgroup cols="5" align="center">
<colspec align="left" colwidth="2*" />
<tbody valign="top">
<row>
<entry>start&nbsp;+&nbsp;0:</entry>
<entry>R<subscript>00</subscript></entry>
<entry>G<subscript>01</subscript></entry>
<entry>R<subscript>02</subscript></entry>
<entry>G<subscript>03</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;4:</entry>
<entry>G<subscript>10</subscript></entry>
<entry>B<subscript>11</subscript></entry>
<entry>G<subscript>12</subscript></entry>
<entry>B<subscript>13</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;8:</entry>
<entry>R<subscript>20</subscript></entry>
<entry>G<subscript>21</subscript></entry>
<entry>R<subscript>22</subscript></entry>
<entry>G<subscript>23</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;12:</entry>
<entry>G<subscript>30</subscript></entry>
<entry>B<subscript>31</subscript></entry>
<entry>G<subscript>32</subscript></entry>
<entry>B<subscript>33</subscript></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
</example>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/pixfmt-uyvy.xml
+120
View File
@@ -0,0 +1,120 @@
<refentry id="V4L2-PIX-FMT-UYVY">
<refmeta>
<refentrytitle>V4L2_PIX_FMT_UYVY ('UYVY')</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname><constant>V4L2_PIX_FMT_UYVY</constant></refname>
<refpurpose>Variation of
<constant>V4L2_PIX_FMT_YUYV</constant> with different order of samples
in memory</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>In this format each four bytes is two pixels. Each four
bytes is two Y's, a Cb and a Cr. Each Y goes to one of the pixels, and
the Cb and Cr belong to both pixels. As you can see, the Cr and Cb
components have half the horizontal resolution of the Y
component.</para>
<example>
<title><constant>V4L2_PIX_FMT_UYVY</constant> 4 &times; 4
pixel image</title>
<formalpara>
<title>Byte Order.</title>
<para>Each cell is one byte.
<informaltable frame="none">
<tgroup cols="9" align="center">
<colspec align="left" colwidth="2*" />
<tbody valign="top">
<row>
<entry>start&nbsp;+&nbsp;0:</entry>
<entry>Cb<subscript>00</subscript></entry>
<entry>Y'<subscript>00</subscript></entry>
<entry>Cr<subscript>00</subscript></entry>
<entry>Y'<subscript>01</subscript></entry>
<entry>Cb<subscript>01</subscript></entry>
<entry>Y'<subscript>02</subscript></entry>
<entry>Cr<subscript>01</subscript></entry>
<entry>Y'<subscript>03</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;8:</entry>
<entry>Cb<subscript>10</subscript></entry>
<entry>Y'<subscript>10</subscript></entry>
<entry>Cr<subscript>10</subscript></entry>
<entry>Y'<subscript>11</subscript></entry>
<entry>Cb<subscript>11</subscript></entry>
<entry>Y'<subscript>12</subscript></entry>
<entry>Cr<subscript>11</subscript></entry>
<entry>Y'<subscript>13</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;16:</entry>
<entry>Cb<subscript>20</subscript></entry>
<entry>Y'<subscript>20</subscript></entry>
<entry>Cr<subscript>20</subscript></entry>
<entry>Y'<subscript>21</subscript></entry>
<entry>Cb<subscript>21</subscript></entry>
<entry>Y'<subscript>22</subscript></entry>
<entry>Cr<subscript>21</subscript></entry>
<entry>Y'<subscript>23</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;24:</entry>
<entry>Cb<subscript>30</subscript></entry>
<entry>Y'<subscript>30</subscript></entry>
<entry>Cr<subscript>30</subscript></entry>
<entry>Y'<subscript>31</subscript></entry>
<entry>Cb<subscript>31</subscript></entry>
<entry>Y'<subscript>32</subscript></entry>
<entry>Cr<subscript>31</subscript></entry>
<entry>Y'<subscript>33</subscript></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
<formalpara>
<title>Color Sample Location.</title>
<para>
<informaltable frame="none">
<tgroup cols="7" align="center">
<tbody valign="top">
<row>
<entry></entry>
<entry>0</entry><entry></entry><entry>1</entry><entry></entry>
<entry>2</entry><entry></entry><entry>3</entry>
</row>
<row>
<entry>0</entry>
<entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry>C</entry><entry>Y</entry>
</row>
<row>
<entry>1</entry>
<entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry>C</entry><entry>Y</entry>
</row>
<row>
<entry>2</entry>
<entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry>C</entry><entry>Y</entry>
</row>
<row>
<entry>3</entry>
<entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry>C</entry><entry>Y</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
</example>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/pixfmt-vyuy.xml
+120
View File
@@ -0,0 +1,120 @@
<refentry id="V4L2-PIX-FMT-VYUY">
<refmeta>
<refentrytitle>V4L2_PIX_FMT_VYUY ('VYUY')</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname><constant>V4L2_PIX_FMT_VYUY</constant></refname>
<refpurpose>Variation of
<constant>V4L2_PIX_FMT_YUYV</constant> with different order of samples
in memory</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>In this format each four bytes is two pixels. Each four
bytes is two Y's, a Cb and a Cr. Each Y goes to one of the pixels, and
the Cb and Cr belong to both pixels. As you can see, the Cr and Cb
components have half the horizontal resolution of the Y
component.</para>
<example>
<title><constant>V4L2_PIX_FMT_VYUY</constant> 4 &times; 4
pixel image</title>
<formalpara>
<title>Byte Order.</title>
<para>Each cell is one byte.
<informaltable frame="none">
<tgroup cols="9" align="center">
<colspec align="left" colwidth="2*" />
<tbody valign="top">
<row>
<entry>start&nbsp;+&nbsp;0:</entry>
<entry>Cr<subscript>00</subscript></entry>
<entry>Y'<subscript>00</subscript></entry>
<entry>Cb<subscript>00</subscript></entry>
<entry>Y'<subscript>01</subscript></entry>
<entry>Cr<subscript>01</subscript></entry>
<entry>Y'<subscript>02</subscript></entry>
<entry>Cb<subscript>01</subscript></entry>
<entry>Y'<subscript>03</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;8:</entry>
<entry>Cr<subscript>10</subscript></entry>
<entry>Y'<subscript>10</subscript></entry>
<entry>Cb<subscript>10</subscript></entry>
<entry>Y'<subscript>11</subscript></entry>
<entry>Cr<subscript>11</subscript></entry>
<entry>Y'<subscript>12</subscript></entry>
<entry>Cb<subscript>11</subscript></entry>
<entry>Y'<subscript>13</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;16:</entry>
<entry>Cr<subscript>20</subscript></entry>
<entry>Y'<subscript>20</subscript></entry>
<entry>Cb<subscript>20</subscript></entry>
<entry>Y'<subscript>21</subscript></entry>
<entry>Cr<subscript>21</subscript></entry>
<entry>Y'<subscript>22</subscript></entry>
<entry>Cb<subscript>21</subscript></entry>
<entry>Y'<subscript>23</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;24:</entry>
<entry>Cr<subscript>30</subscript></entry>
<entry>Y'<subscript>30</subscript></entry>
<entry>Cb<subscript>30</subscript></entry>
<entry>Y'<subscript>31</subscript></entry>
<entry>Cr<subscript>31</subscript></entry>
<entry>Y'<subscript>32</subscript></entry>
<entry>Cb<subscript>31</subscript></entry>
<entry>Y'<subscript>33</subscript></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
<formalpara>
<title>Color Sample Location.</title>
<para>
<informaltable frame="none">
<tgroup cols="7" align="center">
<tbody valign="top">
<row>
<entry></entry>
<entry>0</entry><entry></entry><entry>1</entry><entry></entry>
<entry>2</entry><entry></entry><entry>3</entry>
</row>
<row>
<entry>0</entry>
<entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry>C</entry><entry>Y</entry>
</row>
<row>
<entry>1</entry>
<entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry>C</entry><entry>Y</entry>
</row>
<row>
<entry>2</entry>
<entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry>C</entry><entry>Y</entry>
</row>
<row>
<entry>3</entry>
<entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry>C</entry><entry>Y</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
</example>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/pixfmt-y10.xml
+79
View File
@@ -0,0 +1,79 @@
<refentry id="V4L2-PIX-FMT-Y10">
<refmeta>
<refentrytitle>V4L2_PIX_FMT_Y10 ('Y10 ')</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname><constant>V4L2_PIX_FMT_Y10</constant></refname>
<refpurpose>Grey-scale image</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>This is a grey-scale image with a depth of 10 bits per pixel. Pixels
are stored in 16-bit words with unused high bits padded with 0. The least
significant byte is stored at lower memory addresses (little-endian).</para>
<example>
<title><constant>V4L2_PIX_FMT_Y10</constant> 4 &times; 4
pixel image</title>
<formalpara>
<title>Byte Order.</title>
<para>Each cell is one byte.
<informaltable frame="none">
<tgroup cols="9" align="center">
<colspec align="left" colwidth="2*" />
<tbody valign="top">
<row>
<entry>start&nbsp;+&nbsp;0:</entry>
<entry>Y'<subscript>00low</subscript></entry>
<entry>Y'<subscript>00high</subscript></entry>
<entry>Y'<subscript>01low</subscript></entry>
<entry>Y'<subscript>01high</subscript></entry>
<entry>Y'<subscript>02low</subscript></entry>
<entry>Y'<subscript>02high</subscript></entry>
<entry>Y'<subscript>03low</subscript></entry>
<entry>Y'<subscript>03high</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;8:</entry>
<entry>Y'<subscript>10low</subscript></entry>
<entry>Y'<subscript>10high</subscript></entry>
<entry>Y'<subscript>11low</subscript></entry>
<entry>Y'<subscript>11high</subscript></entry>
<entry>Y'<subscript>12low</subscript></entry>
<entry>Y'<subscript>12high</subscript></entry>
<entry>Y'<subscript>13low</subscript></entry>
<entry>Y'<subscript>13high</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;16:</entry>
<entry>Y'<subscript>20low</subscript></entry>
<entry>Y'<subscript>20high</subscript></entry>
<entry>Y'<subscript>21low</subscript></entry>
<entry>Y'<subscript>21high</subscript></entry>
<entry>Y'<subscript>22low</subscript></entry>
<entry>Y'<subscript>22high</subscript></entry>
<entry>Y'<subscript>23low</subscript></entry>
<entry>Y'<subscript>23high</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;24:</entry>
<entry>Y'<subscript>30low</subscript></entry>
<entry>Y'<subscript>30high</subscript></entry>
<entry>Y'<subscript>31low</subscript></entry>
<entry>Y'<subscript>31high</subscript></entry>
<entry>Y'<subscript>32low</subscript></entry>
<entry>Y'<subscript>32high</subscript></entry>
<entry>Y'<subscript>33low</subscript></entry>
<entry>Y'<subscript>33high</subscript></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
</example>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/pixfmt-y10b.xml
+43
View File
@@ -0,0 +1,43 @@
<refentry id="V4L2-PIX-FMT-Y10BPACK">
<refmeta>
<refentrytitle>V4L2_PIX_FMT_Y10BPACK ('Y10B')</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname><constant>V4L2_PIX_FMT_Y10BPACK</constant></refname>
<refpurpose>Grey-scale image as a bit-packed array</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>This is a packed grey-scale image format with a depth of 10 bits per
pixel. Pixels are stored in a bit-packed array of 10bit bits per pixel,
with no padding between them and with the most significant bits coming
first from the left.</para>
<example>
<title><constant>V4L2_PIX_FMT_Y10BPACK</constant> 4 pixel data stream taking 5 bytes</title>
<formalpara>
<title>Bit-packed representation</title>
<para>pixels cross the byte boundary and have a ratio of 5 bytes for each 4
pixels.
<informaltable frame="all">
<tgroup cols="5" align="center">
<colspec align="left" colwidth="2*" />
<tbody valign="top">
<row>
<entry>Y'<subscript>00[9:2]</subscript></entry>
<entry>Y'<subscript>00[1:0]</subscript>Y'<subscript>01[9:4]</subscript></entry>
<entry>Y'<subscript>01[3:0]</subscript>Y'<subscript>02[9:6]</subscript></entry>
<entry>Y'<subscript>02[5:0]</subscript>Y'<subscript>03[9:8]</subscript></entry>
<entry>Y'<subscript>03[7:0]</subscript></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
</example>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/pixfmt-y12.xml
+79
View File
@@ -0,0 +1,79 @@
<refentry id="V4L2-PIX-FMT-Y12">
<refmeta>
<refentrytitle>V4L2_PIX_FMT_Y12 ('Y12 ')</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname><constant>V4L2_PIX_FMT_Y12</constant></refname>
<refpurpose>Grey-scale image</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>This is a grey-scale image with a depth of 12 bits per pixel. Pixels
are stored in 16-bit words with unused high bits padded with 0. The least
significant byte is stored at lower memory addresses (little-endian).</para>
<example>
<title><constant>V4L2_PIX_FMT_Y12</constant> 4 &times; 4
pixel image</title>
<formalpara>
<title>Byte Order.</title>
<para>Each cell is one byte.
<informaltable frame="none">
<tgroup cols="9" align="center">
<colspec align="left" colwidth="2*" />
<tbody valign="top">
<row>
<entry>start&nbsp;+&nbsp;0:</entry>
<entry>Y'<subscript>00low</subscript></entry>
<entry>Y'<subscript>00high</subscript></entry>
<entry>Y'<subscript>01low</subscript></entry>
<entry>Y'<subscript>01high</subscript></entry>
<entry>Y'<subscript>02low</subscript></entry>
<entry>Y'<subscript>02high</subscript></entry>
<entry>Y'<subscript>03low</subscript></entry>
<entry>Y'<subscript>03high</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;8:</entry>
<entry>Y'<subscript>10low</subscript></entry>
<entry>Y'<subscript>10high</subscript></entry>
<entry>Y'<subscript>11low</subscript></entry>
<entry>Y'<subscript>11high</subscript></entry>
<entry>Y'<subscript>12low</subscript></entry>
<entry>Y'<subscript>12high</subscript></entry>
<entry>Y'<subscript>13low</subscript></entry>
<entry>Y'<subscript>13high</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;16:</entry>
<entry>Y'<subscript>20low</subscript></entry>
<entry>Y'<subscript>20high</subscript></entry>
<entry>Y'<subscript>21low</subscript></entry>
<entry>Y'<subscript>21high</subscript></entry>
<entry>Y'<subscript>22low</subscript></entry>
<entry>Y'<subscript>22high</subscript></entry>
<entry>Y'<subscript>23low</subscript></entry>
<entry>Y'<subscript>23high</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;24:</entry>
<entry>Y'<subscript>30low</subscript></entry>
<entry>Y'<subscript>30high</subscript></entry>
<entry>Y'<subscript>31low</subscript></entry>
<entry>Y'<subscript>31high</subscript></entry>
<entry>Y'<subscript>32low</subscript></entry>
<entry>Y'<subscript>32high</subscript></entry>
<entry>Y'<subscript>33low</subscript></entry>
<entry>Y'<subscript>33high</subscript></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
</example>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/pixfmt-y16.xml
+81
View File
@@ -0,0 +1,81 @@
<refentry id="V4L2-PIX-FMT-Y16">
<refmeta>
<refentrytitle>V4L2_PIX_FMT_Y16 ('Y16 ')</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname><constant>V4L2_PIX_FMT_Y16</constant></refname>
<refpurpose>Grey-scale image</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>This is a grey-scale image with a depth of 16 bits per
pixel. The least significant byte is stored at lower memory addresses
(little-endian). Note the actual sampling precision may be lower than
16 bits, for example 10 bits per pixel with values in range 0 to
1023.</para>
<example>
<title><constant>V4L2_PIX_FMT_Y16</constant> 4 &times; 4
pixel image</title>
<formalpara>
<title>Byte Order.</title>
<para>Each cell is one byte.
<informaltable frame="none">
<tgroup cols="9" align="center">
<colspec align="left" colwidth="2*" />
<tbody valign="top">
<row>
<entry>start&nbsp;+&nbsp;0:</entry>
<entry>Y'<subscript>00low</subscript></entry>
<entry>Y'<subscript>00high</subscript></entry>
<entry>Y'<subscript>01low</subscript></entry>
<entry>Y'<subscript>01high</subscript></entry>
<entry>Y'<subscript>02low</subscript></entry>
<entry>Y'<subscript>02high</subscript></entry>
<entry>Y'<subscript>03low</subscript></entry>
<entry>Y'<subscript>03high</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;8:</entry>
<entry>Y'<subscript>10low</subscript></entry>
<entry>Y'<subscript>10high</subscript></entry>
<entry>Y'<subscript>11low</subscript></entry>
<entry>Y'<subscript>11high</subscript></entry>
<entry>Y'<subscript>12low</subscript></entry>
<entry>Y'<subscript>12high</subscript></entry>
<entry>Y'<subscript>13low</subscript></entry>
<entry>Y'<subscript>13high</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;16:</entry>
<entry>Y'<subscript>20low</subscript></entry>
<entry>Y'<subscript>20high</subscript></entry>
<entry>Y'<subscript>21low</subscript></entry>
<entry>Y'<subscript>21high</subscript></entry>
<entry>Y'<subscript>22low</subscript></entry>
<entry>Y'<subscript>22high</subscript></entry>
<entry>Y'<subscript>23low</subscript></entry>
<entry>Y'<subscript>23high</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;24:</entry>
<entry>Y'<subscript>30low</subscript></entry>
<entry>Y'<subscript>30high</subscript></entry>
<entry>Y'<subscript>31low</subscript></entry>
<entry>Y'<subscript>31high</subscript></entry>
<entry>Y'<subscript>32low</subscript></entry>
<entry>Y'<subscript>32high</subscript></entry>
<entry>Y'<subscript>33low</subscript></entry>
<entry>Y'<subscript>33high</subscript></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
</example>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/pixfmt-y41p.xml
+149
View File
@@ -0,0 +1,149 @@
<refentry id="V4L2-PIX-FMT-Y41P">
<refmeta>
<refentrytitle>V4L2_PIX_FMT_Y41P ('Y41P')</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname><constant>V4L2_PIX_FMT_Y41P</constant></refname>
<refpurpose>Format with &frac14; horizontal chroma
resolution, also known as YUV 4:1:1</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>In this format each 12 bytes is eight pixels. In the
twelve bytes are two CbCr pairs and eight Y's. The first CbCr pair
goes with the first four Y's, and the second CbCr pair goes with the
other four Y's. The Cb and Cr components have one fourth the
horizontal resolution of the Y component.</para>
<para>Do not confuse this format with <link
linkend="V4L2-PIX-FMT-YUV411P"><constant>V4L2_PIX_FMT_YUV411P</constant></link>.
Y41P is derived from "YUV 4:1:1 <emphasis>packed</emphasis>", while
YUV411P stands for "YUV 4:1:1 <emphasis>planar</emphasis>".</para>
<example>
<title><constant>V4L2_PIX_FMT_Y41P</constant> 8 &times; 4
pixel image</title>
<formalpara>
<title>Byte Order</title>
<para>Each cell is one byte.
<informaltable frame="none">
<tgroup cols="13" align="center">
<colspec align="left" colwidth="2*" />
<tbody valign="top">
<row>
<entry>start&nbsp;+&nbsp;0:</entry>
<entry>Cb<subscript>00</subscript></entry>
<entry>Y'<subscript>00</subscript></entry>
<entry>Cr<subscript>00</subscript></entry>
<entry>Y'<subscript>01</subscript></entry>
<entry>Cb<subscript>01</subscript></entry>
<entry>Y'<subscript>02</subscript></entry>
<entry>Cr<subscript>01</subscript></entry>
<entry>Y'<subscript>03</subscript></entry>
<entry>Y'<subscript>04</subscript></entry>
<entry>Y'<subscript>05</subscript></entry>
<entry>Y'<subscript>06</subscript></entry>
<entry>Y'<subscript>07</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;12:</entry>
<entry>Cb<subscript>10</subscript></entry>
<entry>Y'<subscript>10</subscript></entry>
<entry>Cr<subscript>10</subscript></entry>
<entry>Y'<subscript>11</subscript></entry>
<entry>Cb<subscript>11</subscript></entry>
<entry>Y'<subscript>12</subscript></entry>
<entry>Cr<subscript>11</subscript></entry>
<entry>Y'<subscript>13</subscript></entry>
<entry>Y'<subscript>14</subscript></entry>
<entry>Y'<subscript>15</subscript></entry>
<entry>Y'<subscript>16</subscript></entry>
<entry>Y'<subscript>17</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;24:</entry>
<entry>Cb<subscript>20</subscript></entry>
<entry>Y'<subscript>20</subscript></entry>
<entry>Cr<subscript>20</subscript></entry>
<entry>Y'<subscript>21</subscript></entry>
<entry>Cb<subscript>21</subscript></entry>
<entry>Y'<subscript>22</subscript></entry>
<entry>Cr<subscript>21</subscript></entry>
<entry>Y'<subscript>23</subscript></entry>
<entry>Y'<subscript>24</subscript></entry>
<entry>Y'<subscript>25</subscript></entry>
<entry>Y'<subscript>26</subscript></entry>
<entry>Y'<subscript>27</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;36:</entry>
<entry>Cb<subscript>30</subscript></entry>
<entry>Y'<subscript>30</subscript></entry>
<entry>Cr<subscript>30</subscript></entry>
<entry>Y'<subscript>31</subscript></entry>
<entry>Cb<subscript>31</subscript></entry>
<entry>Y'<subscript>32</subscript></entry>
<entry>Cr<subscript>31</subscript></entry>
<entry>Y'<subscript>33</subscript></entry>
<entry>Y'<subscript>34</subscript></entry>
<entry>Y'<subscript>35</subscript></entry>
<entry>Y'<subscript>36</subscript></entry>
<entry>Y'<subscript>37</subscript></entry>
</row>
</tbody>
</tgroup>
</informaltable></para>
</formalpara>
<formalpara>
<title>Color Sample Location.</title>
<para>
<informaltable frame="none">
<tgroup cols="15" align="center">
<tbody valign="top">
<row>
<entry></entry>
<entry>0</entry><entry></entry><entry>1</entry><entry></entry>
<entry>2</entry><entry></entry><entry>3</entry><entry></entry>
<entry>4</entry><entry></entry><entry>5</entry><entry></entry>
<entry>6</entry><entry></entry><entry>7</entry>
</row>
<row>
<entry>0</entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry>
<entry>Y</entry><entry></entry><entry>Y</entry>
</row>
<row>
<entry>1</entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry>
<entry>Y</entry><entry></entry><entry>Y</entry>
</row>
<row>
<entry>2</entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry>
<entry>Y</entry><entry></entry><entry>Y</entry>
</row>
<row>
<entry>3</entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry>
<entry>Y</entry><entry></entry><entry>Y</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
</example>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/pixfmt-yuv410.xml
+133
View File
@@ -0,0 +1,133 @@
<refentry>
<refmeta>
<refentrytitle>V4L2_PIX_FMT_YVU410 ('YVU9'), V4L2_PIX_FMT_YUV410 ('YUV9')</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname id="V4L2-PIX-FMT-YVU410"><constant>V4L2_PIX_FMT_YVU410</constant></refname>
<refname id="V4L2-PIX-FMT-YUV410"><constant>V4L2_PIX_FMT_YUV410</constant></refname>
<refpurpose>Planar formats with &frac14; horizontal and
vertical chroma resolution, also known as YUV 4:1:0</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>These are planar formats, as opposed to a packed format.
The three components are separated into three sub-images or planes.
The Y plane is first. The Y plane has one byte per pixel. For
<constant>V4L2_PIX_FMT_YVU410</constant>, the Cr plane immediately
follows the Y plane in memory. The Cr plane is &frac14; the width and
&frac14; the height of the Y plane (and of the image). Each Cr belongs
to 16 pixels, a four-by-four square of the image. Following the Cr
plane is the Cb plane, just like the Cr plane.
<constant>V4L2_PIX_FMT_YUV410</constant> is the same, except the Cb
plane comes first, then the Cr plane.</para>
<para>If the Y plane has pad bytes after each row, then the Cr
and Cb planes have &frac14; as many pad bytes after their rows. In
other words, four Cx rows (including padding) are exactly as long as
one Y row (including padding).</para>
<example>
<title><constant>V4L2_PIX_FMT_YVU410</constant> 4 &times; 4
pixel image</title>
<formalpara>
<title>Byte Order.</title>
<para>Each cell is one byte.
<informaltable frame="none">
<tgroup cols="5" align="center">
<colspec align="left" colwidth="2*" />
<tbody valign="top">
<row>
<entry>start&nbsp;+&nbsp;0:</entry>
<entry>Y'<subscript>00</subscript></entry>
<entry>Y'<subscript>01</subscript></entry>
<entry>Y'<subscript>02</subscript></entry>
<entry>Y'<subscript>03</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;4:</entry>
<entry>Y'<subscript>10</subscript></entry>
<entry>Y'<subscript>11</subscript></entry>
<entry>Y'<subscript>12</subscript></entry>
<entry>Y'<subscript>13</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;8:</entry>
<entry>Y'<subscript>20</subscript></entry>
<entry>Y'<subscript>21</subscript></entry>
<entry>Y'<subscript>22</subscript></entry>
<entry>Y'<subscript>23</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;12:</entry>
<entry>Y'<subscript>30</subscript></entry>
<entry>Y'<subscript>31</subscript></entry>
<entry>Y'<subscript>32</subscript></entry>
<entry>Y'<subscript>33</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;16:</entry>
<entry>Cr<subscript>00</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;17:</entry>
<entry>Cb<subscript>00</subscript></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
<formalpara>
<title>Color Sample Location.</title>
<para>
<informaltable frame="none">
<tgroup cols="7" align="center">
<tbody valign="top">
<row>
<entry></entry>
<entry>0</entry><entry></entry><entry>1</entry><entry></entry>
<entry>2</entry><entry></entry><entry>3</entry>
</row>
<row>
<entry>0</entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry></entry><entry>Y</entry>
</row>
<row>
<entry></entry>
</row>
<row>
<entry>1</entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry></entry><entry>Y</entry>
</row>
<row>
<entry></entry>
<entry></entry><entry></entry><entry></entry><entry>C</entry>
<entry></entry><entry></entry><entry></entry>
</row>
<row>
<entry>2</entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry></entry><entry>Y</entry>
</row>
<row>
<entry></entry>
</row>
<row>
<entry>3</entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry></entry><entry>Y</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
</example>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/pixfmt-yuv411p.xml
+147
View File
@@ -0,0 +1,147 @@
<refentry id="V4L2-PIX-FMT-YUV411P">
<refmeta>
<refentrytitle>V4L2_PIX_FMT_YUV411P ('411P')</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname><constant>V4L2_PIX_FMT_YUV411P</constant></refname>
<refpurpose>Format with &frac14; horizontal chroma resolution,
also known as YUV 4:1:1. Planar layout as opposed to
<constant>V4L2_PIX_FMT_Y41P</constant></refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>This format is not commonly used. This is a planar
format similar to the 4:2:2 planar format except with half as many
chroma. The three components are separated into three sub-images or
planes. The Y plane is first. The Y plane has one byte per pixel. The
Cb plane immediately follows the Y plane in memory. The Cb plane is
&frac14; the width of the Y plane (and of the image). Each Cb belongs
to 4 pixels all on the same row. For example,
Cb<subscript>0</subscript> belongs to Y'<subscript>00</subscript>,
Y'<subscript>01</subscript>, Y'<subscript>02</subscript> and
Y'<subscript>03</subscript>. Following the Cb plane is the Cr plane,
just like the Cb plane.</para>
<para>If the Y plane has pad bytes after each row, then the Cr
and Cb planes have &frac14; as many pad bytes after their rows. In
other words, four C x rows (including padding) is exactly as long as
one Y row (including padding).</para>
<example>
<title><constant>V4L2_PIX_FMT_YUV411P</constant> 4 &times; 4
pixel image</title>
<formalpara>
<title>Byte Order.</title>
<para>Each cell is one byte.
<informaltable frame="none">
<tgroup cols="5" align="center">
<colspec align="left" colwidth="2*" />
<tbody valign="top">
<row>
<entry>start&nbsp;+&nbsp;0:</entry>
<entry>Y'<subscript>00</subscript></entry>
<entry>Y'<subscript>01</subscript></entry>
<entry>Y'<subscript>02</subscript></entry>
<entry>Y'<subscript>03</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;4:</entry>
<entry>Y'<subscript>10</subscript></entry>
<entry>Y'<subscript>11</subscript></entry>
<entry>Y'<subscript>12</subscript></entry>
<entry>Y'<subscript>13</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;8:</entry>
<entry>Y'<subscript>20</subscript></entry>
<entry>Y'<subscript>21</subscript></entry>
<entry>Y'<subscript>22</subscript></entry>
<entry>Y'<subscript>23</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;12:</entry>
<entry>Y'<subscript>30</subscript></entry>
<entry>Y'<subscript>31</subscript></entry>
<entry>Y'<subscript>32</subscript></entry>
<entry>Y'<subscript>33</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;16:</entry>
<entry>Cb<subscript>00</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;17:</entry>
<entry>Cb<subscript>10</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;18:</entry>
<entry>Cb<subscript>20</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;19:</entry>
<entry>Cb<subscript>30</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;20:</entry>
<entry>Cr<subscript>00</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;21:</entry>
<entry>Cr<subscript>10</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;22:</entry>
<entry>Cr<subscript>20</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;23:</entry>
<entry>Cr<subscript>30</subscript></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
<formalpara>
<title>Color Sample Location.</title>
<para>
<informaltable frame="none">
<tgroup cols="7" align="center">
<tbody valign="top">
<row>
<entry></entry>
<entry>0</entry><entry></entry><entry>1</entry><entry></entry>
<entry>2</entry><entry></entry><entry>3</entry>
</row>
<row>
<entry>0</entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry>
<entry>Y</entry><entry></entry><entry>Y</entry>
</row>
<row>
<entry>1</entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry>
<entry>Y</entry><entry></entry><entry>Y</entry>
</row>
<row>
<entry>2</entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry>
<entry>Y</entry><entry></entry><entry>Y</entry>
</row>
<row>
<entry>3</entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry>
<entry>Y</entry><entry></entry><entry>Y</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
</example>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/pixfmt-yuv420.xml
+149
View File
@@ -0,0 +1,149 @@
<refentry>
<refmeta>
<refentrytitle>V4L2_PIX_FMT_YVU420 ('YV12'), V4L2_PIX_FMT_YUV420 ('YU12')</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname id="V4L2-PIX-FMT-YVU420"><constant>V4L2_PIX_FMT_YVU420</constant></refname>
<refname id="V4L2-PIX-FMT-YUV420"><constant>V4L2_PIX_FMT_YUV420</constant></refname>
<refpurpose>Planar formats with &frac12; horizontal and
vertical chroma resolution, also known as YUV 4:2:0</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>These are planar formats, as opposed to a packed format.
The three components are separated into three sub- images or planes.
The Y plane is first. The Y plane has one byte per pixel. For
<constant>V4L2_PIX_FMT_YVU420</constant>, the Cr plane immediately
follows the Y plane in memory. The Cr plane is half the width and half
the height of the Y plane (and of the image). Each Cr belongs to four
pixels, a two-by-two square of the image. For example,
Cr<subscript>0</subscript> belongs to Y'<subscript>00</subscript>,
Y'<subscript>01</subscript>, Y'<subscript>10</subscript>, and
Y'<subscript>11</subscript>. Following the Cr plane is the Cb plane,
just like the Cr plane. <constant>V4L2_PIX_FMT_YUV420</constant> is
the same except the Cb plane comes first, then the Cr plane.</para>
<para>If the Y plane has pad bytes after each row, then the Cr
and Cb planes have half as many pad bytes after their rows. In other
words, two Cx rows (including padding) is exactly as long as one Y row
(including padding).</para>
<example>
<title><constant>V4L2_PIX_FMT_YVU420</constant> 4 &times; 4
pixel image</title>
<formalpara>
<title>Byte Order.</title>
<para>Each cell is one byte.
<informaltable frame="none">
<tgroup cols="5" align="center">
<colspec align="left" colwidth="2*" />
<tbody valign="top">
<row>
<entry>start&nbsp;+&nbsp;0:</entry>
<entry>Y'<subscript>00</subscript></entry>
<entry>Y'<subscript>01</subscript></entry>
<entry>Y'<subscript>02</subscript></entry>
<entry>Y'<subscript>03</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;4:</entry>
<entry>Y'<subscript>10</subscript></entry>
<entry>Y'<subscript>11</subscript></entry>
<entry>Y'<subscript>12</subscript></entry>
<entry>Y'<subscript>13</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;8:</entry>
<entry>Y'<subscript>20</subscript></entry>
<entry>Y'<subscript>21</subscript></entry>
<entry>Y'<subscript>22</subscript></entry>
<entry>Y'<subscript>23</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;12:</entry>
<entry>Y'<subscript>30</subscript></entry>
<entry>Y'<subscript>31</subscript></entry>
<entry>Y'<subscript>32</subscript></entry>
<entry>Y'<subscript>33</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;16:</entry>
<entry>Cr<subscript>00</subscript></entry>
<entry>Cr<subscript>01</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;18:</entry>
<entry>Cr<subscript>10</subscript></entry>
<entry>Cr<subscript>11</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;20:</entry>
<entry>Cb<subscript>00</subscript></entry>
<entry>Cb<subscript>01</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;22:</entry>
<entry>Cb<subscript>10</subscript></entry>
<entry>Cb<subscript>11</subscript></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
<formalpara>
<title>Color Sample Location.</title>
<para>
<informaltable frame="none">
<tgroup cols="7" align="center">
<tbody valign="top">
<row>
<entry></entry>
<entry>0</entry><entry></entry><entry>1</entry><entry></entry>
<entry>2</entry><entry></entry><entry>3</entry>
</row>
<row>
<entry>0</entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry></entry><entry>Y</entry>
</row>
<row>
<entry></entry>
<entry></entry><entry>C</entry><entry></entry><entry></entry>
<entry></entry><entry>C</entry><entry></entry>
</row>
<row>
<entry>1</entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry></entry><entry>Y</entry>
</row>
<row>
<entry></entry>
</row>
<row>
<entry>2</entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry></entry><entry>Y</entry>
</row>
<row>
<entry></entry>
<entry></entry><entry>C</entry><entry></entry><entry></entry>
<entry></entry><entry>C</entry><entry></entry>
</row>
<row>
<entry>3</entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry></entry><entry>Y</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
</example>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/pixfmt-yuv420m.xml
+154
View File
@@ -0,0 +1,154 @@
<refentry id="V4L2-PIX-FMT-YUV420M">
<refmeta>
<refentrytitle>V4L2_PIX_FMT_YUV420M ('YM12')</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname> <constant>V4L2_PIX_FMT_YUV420M</constant></refname>
<refpurpose>Variation of <constant>V4L2_PIX_FMT_YUV420</constant>
with planes non contiguous in memory. </refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>This is a multi-planar format, as opposed to a packed format.
The three components are separated into three sub- images or planes.
The Y plane is first. The Y plane has one byte per pixel. The Cb data
constitutes the second plane which is half the width and half
the height of the Y plane (and of the image). Each Cb belongs to four
pixels, a two-by-two square of the image. For example,
Cb<subscript>0</subscript> belongs to Y'<subscript>00</subscript>,
Y'<subscript>01</subscript>, Y'<subscript>10</subscript>, and
Y'<subscript>11</subscript>. The Cr data, just like the Cb plane, is
in the third plane. </para>
<para>If the Y plane has pad bytes after each row, then the Cb
and Cr planes have half as many pad bytes after their rows. In other
words, two Cx rows (including padding) is exactly as long as one Y row
(including padding).</para>
<para><constant>V4L2_PIX_FMT_NV12M</constant> is intended to be
used only in drivers and applications that support the multi-planar API,
described in <xref linkend="planar-apis"/>. </para>
<example>
<title><constant>V4L2_PIX_FMT_YVU420M</constant> 4 &times; 4
pixel image</title>
<formalpara>
<title>Byte Order.</title>
<para>Each cell is one byte.
<informaltable frame="none">
<tgroup cols="5" align="center">
<colspec align="left" colwidth="2*" />
<tbody valign="top">
<row>
<entry>start0&nbsp;+&nbsp;0:</entry>
<entry>Y'<subscript>00</subscript></entry>
<entry>Y'<subscript>01</subscript></entry>
<entry>Y'<subscript>02</subscript></entry>
<entry>Y'<subscript>03</subscript></entry>
</row>
<row>
<entry>start0&nbsp;+&nbsp;4:</entry>
<entry>Y'<subscript>10</subscript></entry>
<entry>Y'<subscript>11</subscript></entry>
<entry>Y'<subscript>12</subscript></entry>
<entry>Y'<subscript>13</subscript></entry>
</row>
<row>
<entry>start0&nbsp;+&nbsp;8:</entry>
<entry>Y'<subscript>20</subscript></entry>
<entry>Y'<subscript>21</subscript></entry>
<entry>Y'<subscript>22</subscript></entry>
<entry>Y'<subscript>23</subscript></entry>
</row>
<row>
<entry>start0&nbsp;+&nbsp;12:</entry>
<entry>Y'<subscript>30</subscript></entry>
<entry>Y'<subscript>31</subscript></entry>
<entry>Y'<subscript>32</subscript></entry>
<entry>Y'<subscript>33</subscript></entry>
</row>
<row><entry></entry></row>
<row>
<entry>start1&nbsp;+&nbsp;0:</entry>
<entry>Cb<subscript>00</subscript></entry>
<entry>Cb<subscript>01</subscript></entry>
</row>
<row>
<entry>start1&nbsp;+&nbsp;2:</entry>
<entry>Cb<subscript>10</subscript></entry>
<entry>Cb<subscript>11</subscript></entry>
</row>
<row><entry></entry></row>
<row>
<entry>start2&nbsp;+&nbsp;0:</entry>
<entry>Cr<subscript>00</subscript></entry>
<entry>Cr<subscript>01</subscript></entry>
</row>
<row>
<entry>start2&nbsp;+&nbsp;2:</entry>
<entry>Cr<subscript>10</subscript></entry>
<entry>Cr<subscript>11</subscript></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
<formalpara>
<title>Color Sample Location.</title>
<para>
<informaltable frame="none">
<tgroup cols="7" align="center">
<tbody valign="top">
<row>
<entry></entry>
<entry>0</entry><entry></entry><entry>1</entry><entry></entry>
<entry>2</entry><entry></entry><entry>3</entry>
</row>
<row>
<entry>0</entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry></entry><entry>Y</entry>
</row>
<row>
<entry></entry>
<entry></entry><entry>C</entry><entry></entry><entry></entry>
<entry></entry><entry>C</entry><entry></entry>
</row>
<row>
<entry>1</entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry></entry><entry>Y</entry>
</row>
<row>
<entry></entry>
</row>
<row>
<entry>2</entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry></entry><entry>Y</entry>
</row>
<row>
<entry></entry>
<entry></entry><entry>C</entry><entry></entry><entry></entry>
<entry></entry><entry>C</entry><entry></entry>
</row>
<row>
<entry>3</entry>
<entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry></entry><entry>Y</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
</example>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/pixfmt-yuv422p.xml
+153
View File
@@ -0,0 +1,153 @@
<refentry id="V4L2-PIX-FMT-YUV422P">
<refmeta>
<refentrytitle>V4L2_PIX_FMT_YUV422P ('422P')</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname><constant>V4L2_PIX_FMT_YUV422P</constant></refname>
<refpurpose>Format with &frac12; horizontal chroma resolution,
also known as YUV 4:2:2. Planar layout as opposed to
<constant>V4L2_PIX_FMT_YUYV</constant></refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>This format is not commonly used. This is a planar
version of the YUYV format. The three components are separated into
three sub-images or planes. The Y plane is first. The Y plane has one
byte per pixel. The Cb plane immediately follows the Y plane in
memory. The Cb plane is half the width of the Y plane (and of the
image). Each Cb belongs to two pixels. For example,
Cb<subscript>0</subscript> belongs to Y'<subscript>00</subscript>,
Y'<subscript>01</subscript>. Following the Cb plane is the Cr plane,
just like the Cb plane.</para>
<para>If the Y plane has pad bytes after each row, then the Cr
and Cb planes have half as many pad bytes after their rows. In other
words, two Cx rows (including padding) is exactly as long as one Y row
(including padding).</para>
<example>
<title><constant>V4L2_PIX_FMT_YUV422P</constant> 4 &times; 4
pixel image</title>
<formalpara>
<title>Byte Order.</title>
<para>Each cell is one byte.
<informaltable frame="none">
<tgroup cols="5" align="center">
<colspec align="left" colwidth="2*" />
<tbody valign="top">
<row>
<entry>start&nbsp;+&nbsp;0:</entry>
<entry>Y'<subscript>00</subscript></entry>
<entry>Y'<subscript>01</subscript></entry>
<entry>Y'<subscript>02</subscript></entry>
<entry>Y'<subscript>03</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;4:</entry>
<entry>Y'<subscript>10</subscript></entry>
<entry>Y'<subscript>11</subscript></entry>
<entry>Y'<subscript>12</subscript></entry>
<entry>Y'<subscript>13</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;8:</entry>
<entry>Y'<subscript>20</subscript></entry>
<entry>Y'<subscript>21</subscript></entry>
<entry>Y'<subscript>22</subscript></entry>
<entry>Y'<subscript>23</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;12:</entry>
<entry>Y'<subscript>30</subscript></entry>
<entry>Y'<subscript>31</subscript></entry>
<entry>Y'<subscript>32</subscript></entry>
<entry>Y'<subscript>33</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;16:</entry>
<entry>Cb<subscript>00</subscript></entry>
<entry>Cb<subscript>01</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;18:</entry>
<entry>Cb<subscript>10</subscript></entry>
<entry>Cb<subscript>11</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;20:</entry>
<entry>Cb<subscript>20</subscript></entry>
<entry>Cb<subscript>21</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;22:</entry>
<entry>Cb<subscript>30</subscript></entry>
<entry>Cb<subscript>31</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;24:</entry>
<entry>Cr<subscript>00</subscript></entry>
<entry>Cr<subscript>01</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;26:</entry>
<entry>Cr<subscript>10</subscript></entry>
<entry>Cr<subscript>11</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;28:</entry>
<entry>Cr<subscript>20</subscript></entry>
<entry>Cr<subscript>21</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;30:</entry>
<entry>Cr<subscript>30</subscript></entry>
<entry>Cr<subscript>31</subscript></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
<formalpara>
<title>Color Sample Location.</title>
<para>
<informaltable frame="none">
<tgroup cols="7" align="center">
<tbody valign="top">
<row>
<entry></entry>
<entry>0</entry><entry></entry><entry>1</entry><entry></entry>
<entry>2</entry><entry></entry><entry>3</entry>
</row>
<row>
<entry>0</entry>
<entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry>C</entry><entry>Y</entry>
</row>
<row>
<entry>1</entry>
<entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry>C</entry><entry>Y</entry>
</row>
<row>
<entry>2</entry>
<entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry>C</entry><entry>Y</entry>
</row>
<row>
<entry>3</entry>
<entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry>C</entry><entry>Y</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
</example>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/pixfmt-yuyv.xml
+120
View File
@@ -0,0 +1,120 @@
<refentry id="V4L2-PIX-FMT-YUYV">
<refmeta>
<refentrytitle>V4L2_PIX_FMT_YUYV ('YUYV')</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname><constant>V4L2_PIX_FMT_YUYV</constant></refname>
<refpurpose>Packed format with &frac12; horizontal chroma
resolution, also known as YUV 4:2:2</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>In this format each four bytes is two pixels. Each four
bytes is two Y's, a Cb and a Cr. Each Y goes to one of the pixels, and
the Cb and Cr belong to both pixels. As you can see, the Cr and Cb
components have half the horizontal resolution of the Y component.
<constant>V4L2_PIX_FMT_YUYV </constant> is known in the Windows
environment as YUY2.</para>
<example>
<title><constant>V4L2_PIX_FMT_YUYV</constant> 4 &times; 4
pixel image</title>
<formalpara>
<title>Byte Order.</title>
<para>Each cell is one byte.
<informaltable frame="none">
<tgroup cols="9" align="center">
<colspec align="left" colwidth="2*" />
<tbody valign="top">
<row>
<entry>start&nbsp;+&nbsp;0:</entry>
<entry>Y'<subscript>00</subscript></entry>
<entry>Cb<subscript>00</subscript></entry>
<entry>Y'<subscript>01</subscript></entry>
<entry>Cr<subscript>00</subscript></entry>
<entry>Y'<subscript>02</subscript></entry>
<entry>Cb<subscript>01</subscript></entry>
<entry>Y'<subscript>03</subscript></entry>
<entry>Cr<subscript>01</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;8:</entry>
<entry>Y'<subscript>10</subscript></entry>
<entry>Cb<subscript>10</subscript></entry>
<entry>Y'<subscript>11</subscript></entry>
<entry>Cr<subscript>10</subscript></entry>
<entry>Y'<subscript>12</subscript></entry>
<entry>Cb<subscript>11</subscript></entry>
<entry>Y'<subscript>13</subscript></entry>
<entry>Cr<subscript>11</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;16:</entry>
<entry>Y'<subscript>20</subscript></entry>
<entry>Cb<subscript>20</subscript></entry>
<entry>Y'<subscript>21</subscript></entry>
<entry>Cr<subscript>20</subscript></entry>
<entry>Y'<subscript>22</subscript></entry>
<entry>Cb<subscript>21</subscript></entry>
<entry>Y'<subscript>23</subscript></entry>
<entry>Cr<subscript>21</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;24:</entry>
<entry>Y'<subscript>30</subscript></entry>
<entry>Cb<subscript>30</subscript></entry>
<entry>Y'<subscript>31</subscript></entry>
<entry>Cr<subscript>30</subscript></entry>
<entry>Y'<subscript>32</subscript></entry>
<entry>Cb<subscript>31</subscript></entry>
<entry>Y'<subscript>33</subscript></entry>
<entry>Cr<subscript>31</subscript></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
<formalpara>
<title>Color Sample Location.</title>
<para>
<informaltable frame="none">
<tgroup cols="7" align="center">
<tbody valign="top">
<row>
<entry></entry>
<entry>0</entry><entry></entry><entry>1</entry><entry></entry>
<entry>2</entry><entry></entry><entry>3</entry>
</row>
<row>
<entry>0</entry>
<entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry>C</entry><entry>Y</entry>
</row>
<row>
<entry>1</entry>
<entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry>C</entry><entry>Y</entry>
</row>
<row>
<entry>2</entry>
<entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry>C</entry><entry>Y</entry>
</row>
<row>
<entry>3</entry>
<entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry>C</entry><entry>Y</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
</example>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/pixfmt-yvyu.xml
+120
View File
@@ -0,0 +1,120 @@
<refentry id="V4L2-PIX-FMT-YVYU">
<refmeta>
<refentrytitle>V4L2_PIX_FMT_YVYU ('YVYU')</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname><constant>V4L2_PIX_FMT_YVYU</constant></refname>
<refpurpose>Variation of
<constant>V4L2_PIX_FMT_YUYV</constant> with different order of samples
in memory</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>In this format each four bytes is two pixels. Each four
bytes is two Y's, a Cb and a Cr. Each Y goes to one of the pixels, and
the Cb and Cr belong to both pixels. As you can see, the Cr and Cb
components have half the horizontal resolution of the Y
component.</para>
<example>
<title><constant>V4L2_PIX_FMT_YVYU</constant> 4 &times; 4
pixel image</title>
<formalpara>
<title>Byte Order.</title>
<para>Each cell is one byte.
<informaltable frame="none">
<tgroup cols="9" align="center">
<colspec align="left" colwidth="2*" />
<tbody valign="top">
<row>
<entry>start&nbsp;+&nbsp;0:</entry>
<entry>Y'<subscript>00</subscript></entry>
<entry>Cr<subscript>00</subscript></entry>
<entry>Y'<subscript>01</subscript></entry>
<entry>Cb<subscript>00</subscript></entry>
<entry>Y'<subscript>02</subscript></entry>
<entry>Cr<subscript>01</subscript></entry>
<entry>Y'<subscript>03</subscript></entry>
<entry>Cb<subscript>01</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;8:</entry>
<entry>Y'<subscript>10</subscript></entry>
<entry>Cr<subscript>10</subscript></entry>
<entry>Y'<subscript>11</subscript></entry>
<entry>Cb<subscript>10</subscript></entry>
<entry>Y'<subscript>12</subscript></entry>
<entry>Cr<subscript>11</subscript></entry>
<entry>Y'<subscript>13</subscript></entry>
<entry>Cb<subscript>11</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;16:</entry>
<entry>Y'<subscript>20</subscript></entry>
<entry>Cr<subscript>20</subscript></entry>
<entry>Y'<subscript>21</subscript></entry>
<entry>Cb<subscript>20</subscript></entry>
<entry>Y'<subscript>22</subscript></entry>
<entry>Cr<subscript>21</subscript></entry>
<entry>Y'<subscript>23</subscript></entry>
<entry>Cb<subscript>21</subscript></entry>
</row>
<row>
<entry>start&nbsp;+&nbsp;24:</entry>
<entry>Y'<subscript>30</subscript></entry>
<entry>Cr<subscript>30</subscript></entry>
<entry>Y'<subscript>31</subscript></entry>
<entry>Cb<subscript>30</subscript></entry>
<entry>Y'<subscript>32</subscript></entry>
<entry>Cr<subscript>31</subscript></entry>
<entry>Y'<subscript>33</subscript></entry>
<entry>Cb<subscript>31</subscript></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
<formalpara>
<title>Color Sample Location.</title>
<para>
<informaltable frame="none">
<tgroup cols="7" align="center">
<tbody valign="top">
<row>
<entry></entry>
<entry>0</entry><entry></entry><entry>1</entry><entry></entry>
<entry>2</entry><entry></entry><entry>3</entry>
</row>
<row>
<entry>0</entry>
<entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry>C</entry><entry>Y</entry>
</row>
<row>
<entry>1</entry>
<entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry>C</entry><entry>Y</entry>
</row>
<row>
<entry>2</entry>
<entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry>C</entry><entry>Y</entry>
</row>
<row>
<entry>3</entry>
<entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
<entry>Y</entry><entry>C</entry><entry>Y</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
</example>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/pixfmt.xml
+1005
View File
File diff suppressed because it is too large Load Diff
kernel/Documentation/DocBook/media/v4l/planar-apis.xml
+62
View File
@@ -0,0 +1,62 @@
<section id="planar-apis">
<title>Single- and multi-planar APIs</title>
<para>Some devices require data for each input or output video frame
to be placed in discontiguous memory buffers. In such cases, one
video frame has to be addressed using more than one memory address, i.e. one
pointer per "plane". A plane is a sub-buffer of the current frame. For
examples of such formats see <xref linkend="pixfmt" />.</para>
<para>Initially, V4L2 API did not support multi-planar buffers and a set of
extensions has been introduced to handle them. Those extensions constitute
what is being referred to as the "multi-planar API".</para>
<para>Some of the V4L2 API calls and structures are interpreted differently,
depending on whether single- or multi-planar API is being used. An application
can choose whether to use one or the other by passing a corresponding buffer
type to its ioctl calls. Multi-planar versions of buffer types are suffixed
with an `_MPLANE' string. For a list of available multi-planar buffer types
see &v4l2-buf-type;.
</para>
<section>
<title>Multi-planar formats</title>
<para>Multi-planar API introduces new multi-planar formats. Those formats
use a separate set of FourCC codes. It is important to distinguish between
the multi-planar API and a multi-planar format. Multi-planar API calls can
handle all single-planar formats as well (as long as they are passed in
multi-planar API structures), while the single-planar API cannot
handle multi-planar formats.</para>
</section>
<section>
<title>Calls that distinguish between single and multi-planar APIs</title>
<variablelist>
<varlistentry>
<term>&VIDIOC-QUERYCAP;</term>
<listitem><para>Two additional multi-planar capabilities are added. They can
be set together with non-multi-planar ones for devices that handle
both single- and multi-planar formats.</para></listitem>
</varlistentry>
<varlistentry>
<term>&VIDIOC-G-FMT;, &VIDIOC-S-FMT;, &VIDIOC-TRY-FMT;</term>
<listitem><para>New structures for describing multi-planar formats are added:
&v4l2-pix-format-mplane; and &v4l2-plane-pix-format;. Drivers may
define new multi-planar formats, which have distinct FourCC codes from
the existing single-planar ones.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&VIDIOC-QBUF;, &VIDIOC-DQBUF;, &VIDIOC-QUERYBUF;</term>
<listitem><para>A new &v4l2-plane; structure for describing planes is added.
Arrays of this structure are passed in the new
<structfield>m.planes</structfield> field of &v4l2-buffer;.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&VIDIOC-REQBUFS;</term>
<listitem><para>Will allocate multi-planar buffers as requested.</para></listitem>
</varlistentry>
</variablelist>
</section>
</section>
kernel/Documentation/DocBook/media/v4l/remote_controllers.xml
+177
View File
@@ -0,0 +1,177 @@
<title>Remote Controllers</title>
<section id="Remote_controllers_Intro">
<title>Introduction</title>
<para>Currently, most analog and digital devices have a Infrared input for remote controllers. Each
manufacturer has their own type of control. It is not rare for the same manufacturer to ship different
types of controls, depending on the device.</para>
<para>Unfortunately, for several years, there was no effort to create uniform IR keycodes for
different devices. This caused the same IR keyname to be mapped completely differently on
different IR devices. This resulted that the same IR keyname to be mapped completely different on
different IR's. Due to that, V4L2 API now specifies a standard for mapping Media keys on IR.</para>
<para>This standard should be used by both V4L/DVB drivers and userspace applications</para>
<para>The modules register the remote as keyboard within the linux input layer. This means that the IR key strokes will look like normal keyboard key strokes (if CONFIG_INPUT_KEYBOARD is enabled). Using the event devices (CONFIG_INPUT_EVDEV) it is possible for applications to access the remote via /dev/input/event devices.</para>
<table pgwide="1" frame="none" id="rc_standard_keymap">
<title>IR default keymapping</title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>Key code</entry>
<entry>Meaning</entry>
<entry>Key examples on IR</entry>
</row>
<row><entry><emphasis role="bold">Numeric keys</emphasis></entry></row>
<row><entry><constant>KEY_0</constant></entry><entry>Keyboard digit 0</entry><entry>0</entry></row>
<row><entry><constant>KEY_1</constant></entry><entry>Keyboard digit 1</entry><entry>1</entry></row>
<row><entry><constant>KEY_2</constant></entry><entry>Keyboard digit 2</entry><entry>2</entry></row>
<row><entry><constant>KEY_3</constant></entry><entry>Keyboard digit 3</entry><entry>3</entry></row>
<row><entry><constant>KEY_4</constant></entry><entry>Keyboard digit 4</entry><entry>4</entry></row>
<row><entry><constant>KEY_5</constant></entry><entry>Keyboard digit 5</entry><entry>5</entry></row>
<row><entry><constant>KEY_6</constant></entry><entry>Keyboard digit 6</entry><entry>6</entry></row>
<row><entry><constant>KEY_7</constant></entry><entry>Keyboard digit 7</entry><entry>7</entry></row>
<row><entry><constant>KEY_8</constant></entry><entry>Keyboard digit 8</entry><entry>8</entry></row>
<row><entry><constant>KEY_9</constant></entry><entry>Keyboard digit 9</entry><entry>9</entry></row>
<row><entry><emphasis role="bold">Movie play control</emphasis></entry></row>
<row><entry><constant>KEY_FORWARD</constant></entry><entry>Instantly advance in time</entry><entry>&gt;&gt; / FORWARD</entry></row>
<row><entry><constant>KEY_BACK</constant></entry><entry>Instantly go back in time</entry><entry>&lt;&lt;&lt; / BACK</entry></row>
<row><entry><constant>KEY_FASTFORWARD</constant></entry><entry>Play movie faster</entry><entry>&gt;&gt;&gt; / FORWARD</entry></row>
<row><entry><constant>KEY_REWIND</constant></entry><entry>Play movie back</entry><entry>REWIND / BACKWARD</entry></row>
<row><entry><constant>KEY_NEXT</constant></entry><entry>Select next chapter / sub-chapter / interval</entry><entry>NEXT / SKIP</entry></row>
<row><entry><constant>KEY_PREVIOUS</constant></entry><entry>Select previous chapter / sub-chapter / interval</entry><entry>&lt;&lt; / PREV / PREVIOUS</entry></row>
<row><entry><constant>KEY_AGAIN</constant></entry><entry>Repeat the video or a video interval</entry><entry>REPEAT / LOOP / RECALL</entry></row>
<row><entry><constant>KEY_PAUSE</constant></entry><entry>Pause sroweam</entry><entry>PAUSE / FREEZE</entry></row>
<row><entry><constant>KEY_PLAY</constant></entry><entry>Play movie at the normal timeshift</entry><entry>NORMAL TIMESHIFT / LIVE / &gt;</entry></row>
<row><entry><constant>KEY_PLAYPAUSE</constant></entry><entry>Alternate between play and pause</entry><entry>PLAY / PAUSE</entry></row>
<row><entry><constant>KEY_STOP</constant></entry><entry>Stop sroweam</entry><entry>STOP</entry></row>
<row><entry><constant>KEY_RECORD</constant></entry><entry>Start/stop recording sroweam</entry><entry>CAPTURE / REC / RECORD/PAUSE</entry></row>
<row><entry><constant>KEY_CAMERA</constant></entry><entry>Take a picture of the image</entry><entry>CAMERA ICON / CAPTURE / SNAPSHOT</entry></row>
<row><entry><constant>KEY_SHUFFLE</constant></entry><entry>Enable shuffle mode</entry><entry>SHUFFLE</entry></row>
<row><entry><constant>KEY_TIME</constant></entry><entry>Activate time shift mode</entry><entry>TIME SHIFT</entry></row>
<row><entry><constant>KEY_TITLE</constant></entry><entry>Allow changing the chapter</entry><entry>CHAPTER</entry></row>
<row><entry><constant>KEY_SUBTITLE</constant></entry><entry>Allow changing the subtitle</entry><entry>SUBTITLE</entry></row>
<row><entry><emphasis role="bold">Image control</emphasis></entry></row>
<row><entry><constant>KEY_BRIGHTNESSDOWN</constant></entry><entry>Decrease Brightness</entry><entry>BRIGHTNESS DECREASE</entry></row>
<row><entry><constant>KEY_BRIGHTNESSUP</constant></entry><entry>Increase Brightness</entry><entry>BRIGHTNESS INCREASE</entry></row>
<row><entry><constant>KEY_ANGLE</constant></entry><entry>Switch video camera angle (on videos with more than one angle stored)</entry><entry>ANGLE / SWAP</entry></row>
<row><entry><constant>KEY_EPG</constant></entry><entry>Open the Elecrowonic Play Guide (EPG)</entry><entry>EPG / GUIDE</entry></row>
<row><entry><constant>KEY_TEXT</constant></entry><entry>Activate/change closed caption mode</entry><entry>CLOSED CAPTION/TELETEXT / DVD TEXT / TELETEXT / TTX</entry></row>
<row><entry><emphasis role="bold">Audio control</emphasis></entry></row>
<row><entry><constant>KEY_AUDIO</constant></entry><entry>Change audio source</entry><entry>AUDIO SOURCE / AUDIO / MUSIC</entry></row>
<row><entry><constant>KEY_MUTE</constant></entry><entry>Mute/unmute audio</entry><entry>MUTE / DEMUTE / UNMUTE</entry></row>
<row><entry><constant>KEY_VOLUMEDOWN</constant></entry><entry>Decrease volume</entry><entry>VOLUME- / VOLUME DOWN</entry></row>
<row><entry><constant>KEY_VOLUMEUP</constant></entry><entry>Increase volume</entry><entry>VOLUME+ / VOLUME UP</entry></row>
<row><entry><constant>KEY_MODE</constant></entry><entry>Change sound mode</entry><entry>MONO/STEREO</entry></row>
<row><entry><constant>KEY_LANGUAGE</constant></entry><entry>Select Language</entry><entry>1ST / 2ND LANGUAGE / DVD LANG / MTS/SAP / MTS SEL</entry></row>
<row><entry><emphasis role="bold">Channel control</emphasis></entry></row>
<row><entry><constant>KEY_CHANNEL</constant></entry><entry>Go to the next favorite channel</entry><entry>ALT / CHANNEL / CH SURFING / SURF / FAV</entry></row>
<row><entry><constant>KEY_CHANNELDOWN</constant></entry><entry>Decrease channel sequencially</entry><entry>CHANNEL - / CHANNEL DOWN / DOWN</entry></row>
<row><entry><constant>KEY_CHANNELUP</constant></entry><entry>Increase channel sequencially</entry><entry>CHANNEL + / CHANNEL UP / UP</entry></row>
<row><entry><constant>KEY_DIGITS</constant></entry><entry>Use more than one digit for channel</entry><entry>PLUS / 100/ 1xx / xxx / -/-- / Single Double Triple Digit</entry></row>
<row><entry><constant>KEY_SEARCH</constant></entry><entry>Start channel autoscan</entry><entry>SCAN / AUTOSCAN</entry></row>
<row><entry><emphasis role="bold">Colored keys</emphasis></entry></row>
<row><entry><constant>KEY_BLUE</constant></entry><entry>IR Blue key</entry><entry>BLUE</entry></row>
<row><entry><constant>KEY_GREEN</constant></entry><entry>IR Green Key</entry><entry>GREEN</entry></row>
<row><entry><constant>KEY_RED</constant></entry><entry>IR Red key</entry><entry>RED</entry></row>
<row><entry><constant>KEY_YELLOW</constant></entry><entry>IR Yellow key</entry><entry> YELLOW</entry></row>
<row><entry><emphasis role="bold">Media selection</emphasis></entry></row>
<row><entry><constant>KEY_CD</constant></entry><entry>Change input source to Compact Disc</entry><entry>CD</entry></row>
<row><entry><constant>KEY_DVD</constant></entry><entry>Change input to DVD</entry><entry>DVD / DVD MENU</entry></row>
<row><entry><constant>KEY_EJECTCLOSECD</constant></entry><entry>Open/close the CD/DVD player</entry><entry>-&gt; ) / CLOSE / OPEN</entry></row>
<row><entry><constant>KEY_MEDIA</constant></entry><entry>Turn on/off Media application</entry><entry>PC/TV / TURN ON/OFF APP</entry></row>
<row><entry><constant>KEY_PC</constant></entry><entry>Selects from TV to PC</entry><entry>PC</entry></row>
<row><entry><constant>KEY_RADIO</constant></entry><entry>Put into AM/FM radio mode</entry><entry>RADIO / TV/FM / TV/RADIO / FM / FM/RADIO</entry></row>
<row><entry><constant>KEY_TV</constant></entry><entry>Select tv mode</entry><entry>TV / LIVE TV</entry></row>
<row><entry><constant>KEY_TV2</constant></entry><entry>Select Cable mode</entry><entry>AIR/CBL</entry></row>
<row><entry><constant>KEY_VCR</constant></entry><entry>Select VCR mode</entry><entry>VCR MODE / DTR</entry></row>
<row><entry><constant>KEY_VIDEO</constant></entry><entry>Alternate between input modes</entry><entry>SOURCE / SELECT / DISPLAY / SWITCH INPUTS / VIDEO</entry></row>
<row><entry><emphasis role="bold">Power control</emphasis></entry></row>
<row><entry><constant>KEY_POWER</constant></entry><entry>Turn on/off computer</entry><entry>SYSTEM POWER / COMPUTER POWER</entry></row>
<row><entry><constant>KEY_POWER2</constant></entry><entry>Turn on/off application</entry><entry>TV ON/OFF / POWER</entry></row>
<row><entry><constant>KEY_SLEEP</constant></entry><entry>Activate sleep timer</entry><entry>SLEEP / SLEEP TIMER</entry></row>
<row><entry><constant>KEY_SUSPEND</constant></entry><entry>Put computer into suspend mode</entry><entry>STANDBY / SUSPEND</entry></row>
<row><entry><emphasis role="bold">Window control</emphasis></entry></row>
<row><entry><constant>KEY_CLEAR</constant></entry><entry>Stop sroweam and return to default input video/audio</entry><entry>CLEAR / RESET / BOSS KEY</entry></row>
<row><entry><constant>KEY_CYCLEWINDOWS</constant></entry><entry>Minimize windows and move to the next one</entry><entry>ALT-TAB / MINIMIZE / DESKTOP</entry></row>
<row><entry><constant>KEY_FAVORITES</constant></entry><entry>Open the favorites sroweam window</entry><entry>TV WALL / Favorites</entry></row>
<row><entry><constant>KEY_MENU</constant></entry><entry>Call application menu</entry><entry>2ND CONTROLS (USA: MENU) / DVD/MENU / SHOW/HIDE CTRL</entry></row>
<row><entry><constant>KEY_NEW</constant></entry><entry>Open/Close Picture in Picture</entry><entry>PIP</entry></row>
<row><entry><constant>KEY_OK</constant></entry><entry>Send a confirmation code to application</entry><entry>OK / ENTER / RETURN</entry></row>
<row><entry><constant>KEY_SCREEN</constant></entry><entry>Select screen aspect ratio</entry><entry>4:3 16:9 SELECT</entry></row>
<row><entry><constant>KEY_ZOOM</constant></entry><entry>Put device into zoom/full screen mode</entry><entry>ZOOM / FULL SCREEN / ZOOM+ / HIDE PANNEL / SWITCH</entry></row>
<row><entry><emphasis role="bold">Navigation keys</emphasis></entry></row>
<row><entry><constant>KEY_ESC</constant></entry><entry>Cancel current operation</entry><entry>CANCEL / BACK</entry></row>
<row><entry><constant>KEY_HELP</constant></entry><entry>Open a Help window</entry><entry>HELP</entry></row>
<row><entry><constant>KEY_HOMEPAGE</constant></entry><entry>Navigate to Homepage</entry><entry>HOME</entry></row>
<row><entry><constant>KEY_INFO</constant></entry><entry>Open On Screen Display</entry><entry>DISPLAY INFORMATION / OSD</entry></row>
<row><entry><constant>KEY_WWW</constant></entry><entry>Open the default browser</entry><entry>WEB</entry></row>
<row><entry><constant>KEY_UP</constant></entry><entry>Up key</entry><entry>UP</entry></row>
<row><entry><constant>KEY_DOWN</constant></entry><entry>Down key</entry><entry>DOWN</entry></row>
<row><entry><constant>KEY_LEFT</constant></entry><entry>Left key</entry><entry>LEFT</entry></row>
<row><entry><constant>KEY_RIGHT</constant></entry><entry>Right key</entry><entry>RIGHT</entry></row>
<row><entry><emphasis role="bold">Miscellaneous keys</emphasis></entry></row>
<row><entry><constant>KEY_DOT</constant></entry><entry>Return a dot</entry><entry>.</entry></row>
<row><entry><constant>KEY_FN</constant></entry><entry>Select a function</entry><entry>FUNCTION</entry></row>
</tbody>
</tgroup>
</table>
<para>It should be noticed that, sometimes, there some fundamental missing keys at some cheaper IR's. Due to that, it is recommended to:</para>
<table pgwide="1" frame="none" id="rc_keymap_notes">
<title>Notes</title>
<tgroup cols="1">
&cs-str;
<tbody valign="top">
<row>
<entry>On simpler IR's, without separate channel keys, you need to map UP as <constant>KEY_CHANNELUP</constant></entry>
</row><row>
<entry>On simpler IR's, without separate channel keys, you need to map DOWN as <constant>KEY_CHANNELDOWN</constant></entry>
</row><row>
<entry>On simpler IR's, without separate volume keys, you need to map LEFT as <constant>KEY_VOLUMEDOWN</constant></entry>
</row><row>
<entry>On simpler IR's, without separate volume keys, you need to map RIGHT as <constant>KEY_VOLUMEUP</constant></entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section id="Remote_controllers_table_change">
<title>Changing default Remote Controller mappings</title>
<para>The event interface provides two ioctls to be used against
the /dev/input/event device, to allow changing the default
keymapping.</para>
<para>This program demonstrates how to replace the keymap tables.</para>
&sub-keytable-c;
</section>
&sub-lirc_device_interface;
kernel/Documentation/DocBook/media/v4l/selection-api.xml
+325
View File
@@ -0,0 +1,325 @@
<section id="selection-api">
<title>Experimental API for cropping, composing and scaling</title>
<note>
<title>Experimental</title>
<para>This is an <link linkend="experimental">experimental</link>
interface and may change in the future.</para>
</note>
<section>
<title>Introduction</title>
<para>Some video capture devices can sample a subsection of a picture and
shrink or enlarge it to an image of arbitrary size. Next, the devices can
insert the image into larger one. Some video output devices can crop part of an
input image, scale it up or down and insert it at an arbitrary scan line and
horizontal offset into a video signal. We call these abilities cropping,
scaling and composing.</para>
<para>On a video <emphasis>capture</emphasis> device the source is a video
signal, and the cropping target determine the area actually sampled. The sink
is an image stored in a memory buffer. The composing area specifies which part
of the buffer is actually written to by the hardware. </para>
<para>On a video <emphasis>output</emphasis> device the source is an image in a
memory buffer, and the cropping target is a part of an image to be shown on a
display. The sink is the display or the graphics screen. The application may
select the part of display where the image should be displayed. The size and
position of such a window is controlled by the compose target.</para>
<para>Rectangles for all cropping and composing targets are defined even if the
device does supports neither cropping nor composing. Their size and position
will be fixed in such a case. If the device does not support scaling then the
cropping and composing rectangles have the same size.</para>
</section>
<section>
<title>Selection targets</title>
<figure id="sel-targets-capture">
<title>Cropping and composing targets</title>
<mediaobject>
<imageobject>
<imagedata fileref="selection.png" format="PNG" />
</imageobject>
<textobject>
<phrase>Targets used by a cropping, composing and scaling
process</phrase>
</textobject>
</mediaobject>
</figure>
For complete list of the available selection targets see table <xref
linkend="v4l2-sel-target"/>
</section>
<section>
<title>Configuration</title>
<para>Applications can use the <link linkend="vidioc-g-selection">selection
API</link> to select an area in a video signal or a buffer, and to query for
default settings and hardware limits.</para>
<para>Video hardware can have various cropping, composing and scaling
limitations. It may only scale up or down, support only discrete scaling
factors, or have different scaling abilities in the horizontal and vertical
directions. Also it may not support scaling at all. At the same time the
cropping/composing rectangles may have to be aligned, and both the source and
the sink may have arbitrary upper and lower size limits. Therefore, as usual,
drivers are expected to adjust the requested parameters and return the actual
values selected. An application can control the rounding behaviour using <link
linkend="v4l2-sel-flags"> constraint flags </link>.</para>
<section>
<title>Configuration of video capture</title>
<para>See figure <xref linkend="sel-targets-capture" /> for examples of the
selection targets available for a video capture device. It is recommended to
configure the cropping targets before to the composing targets.</para>
<para>The range of coordinates of the top left corner, width and height of
areas that can be sampled is given by the <constant> V4L2_SEL_TGT_CROP_BOUNDS
</constant> target. It is recommended for the driver developers to put the
top/left corner at position <constant> (0,0) </constant>. The rectangle's
coordinates are expressed in pixels.</para>
<para>The top left corner, width and height of the source rectangle, that is
the area actually sampled, is given by the <constant> V4L2_SEL_TGT_CROP_ACTIVE
</constant> target. It uses the same coordinate system as <constant>
V4L2_SEL_TGT_CROP_BOUNDS </constant>. The active cropping area must lie
completely inside the capture boundaries. The driver may further adjust the
requested size and/or position according to hardware limitations.</para>
<para>Each capture device has a default source rectangle, given by the
<constant> V4L2_SEL_TGT_CROP_DEFAULT </constant> target. This rectangle shall
over what the driver writer considers the complete picture. Drivers shall set
the active crop rectangle to the default when the driver is first loaded, but
not later.</para>
<para>The composing targets refer to a memory buffer. The limits of composing
coordinates are obtained using <constant> V4L2_SEL_TGT_COMPOSE_BOUNDS
</constant>. All coordinates are expressed in pixels. The rectangle's top/left
corner must be located at position <constant> (0,0) </constant>. The width and
height are equal to the image size set by <constant> VIDIOC_S_FMT </constant>.
</para>
<para>The part of a buffer into which the image is inserted by the hardware is
controlled by the <constant> V4L2_SEL_TGT_COMPOSE_ACTIVE </constant> target.
The rectangle's coordinates are also expressed in the same coordinate system as
the bounds rectangle. The composing rectangle must lie completely inside bounds
rectangle. The driver must adjust the composing rectangle to fit to the
bounding limits. Moreover, the driver can perform other adjustments according
to hardware limitations. The application can control rounding behaviour using
<link linkend="v4l2-sel-flags"> constraint flags </link>.</para>
<para>For capture devices the default composing rectangle is queried using
<constant> V4L2_SEL_TGT_COMPOSE_DEFAULT </constant>. It is usually equal to the
bounding rectangle.</para>
<para>The part of a buffer that is modified by the hardware is given by
<constant> V4L2_SEL_TGT_COMPOSE_PADDED </constant>. It contains all pixels
defined using <constant> V4L2_SEL_TGT_COMPOSE_ACTIVE </constant> plus all
padding data modified by hardware during insertion process. All pixels outside
this rectangle <emphasis>must not</emphasis> be changed by the hardware. The
content of pixels that lie inside the padded area but outside active area is
undefined. The application can use the padded and active rectangles to detect
where the rubbish pixels are located and remove them if needed.</para>
</section>
<section>
<title>Configuration of video output</title>
<para>For output devices targets and ioctls are used similarly to the video
capture case. The <emphasis> composing </emphasis> rectangle refers to the
insertion of an image into a video signal. The cropping rectangles refer to a
memory buffer. It is recommended to configure the composing targets before to
the cropping targets.</para>
<para>The cropping targets refer to the memory buffer that contains an image to
be inserted into a video signal or graphical screen. The limits of cropping
coordinates are obtained using <constant> V4L2_SEL_TGT_CROP_BOUNDS </constant>.
All coordinates are expressed in pixels. The top/left corner is always point
<constant> (0,0) </constant>. The width and height is equal to the image size
specified using <constant> VIDIOC_S_FMT </constant> ioctl.</para>
<para>The top left corner, width and height of the source rectangle, that is
the area from which image date are processed by the hardware, is given by the
<constant> V4L2_SEL_TGT_CROP_ACTIVE </constant>. Its coordinates are expressed
in in the same coordinate system as the bounds rectangle. The active cropping
area must lie completely inside the crop boundaries and the driver may further
adjust the requested size and/or position according to hardware
limitations.</para>
<para>For output devices the default cropping rectangle is queried using
<constant> V4L2_SEL_TGT_CROP_DEFAULT </constant>. It is usually equal to the
bounding rectangle.</para>
<para>The part of a video signal or graphics display where the image is
inserted by the hardware is controlled by <constant>
V4L2_SEL_TGT_COMPOSE_ACTIVE </constant> target. The rectangle's coordinates
are expressed in pixels. The composing rectangle must lie completely inside the
bounds rectangle. The driver must adjust the area to fit to the bounding
limits. Moreover, the driver can perform other adjustments according to
hardware limitations. </para>
<para>The device has a default composing rectangle, given by the <constant>
V4L2_SEL_TGT_COMPOSE_DEFAULT </constant> target. This rectangle shall cover what
the driver writer considers the complete picture. It is recommended for the
driver developers to put the top/left corner at position <constant> (0,0)
</constant>. Drivers shall set the active composing rectangle to the default
one when the driver is first loaded.</para>
<para>The devices may introduce additional content to video signal other than
an image from memory buffers. It includes borders around an image. However,
such a padded area is driver-dependent feature not covered by this document.
Driver developers are encouraged to keep padded rectangle equal to active one.
The padded target is accessed by the <constant> V4L2_SEL_TGT_COMPOSE_PADDED
</constant> identifier. It must contain all pixels from the <constant>
V4L2_SEL_TGT_COMPOSE_ACTIVE </constant> target.</para>
</section>
<section>
<title>Scaling control</title>
<para>An application can detect if scaling is performed by comparing the width
and the height of rectangles obtained using <constant> V4L2_SEL_TGT_CROP_ACTIVE
</constant> and <constant> V4L2_SEL_TGT_COMPOSE_ACTIVE </constant> targets. If
these are not equal then the scaling is applied. The application can compute
the scaling ratios using these values.</para>
</section>
</section>
<section>
<title>Comparison with old cropping API</title>
<para>The selection API was introduced to cope with deficiencies of previous
<link linkend="crop"> API </link>, that was designed to control simple capture
devices. Later the cropping API was adopted by video output drivers. The ioctls
are used to select a part of the display were the video signal is inserted. It
should be considered as an API abuse because the described operation is
actually the composing. The selection API makes a clear distinction between
composing and cropping operations by setting the appropriate targets. The V4L2
API lacks any support for composing to and cropping from an image inside a
memory buffer. The application could configure a capture device to fill only a
part of an image by abusing V4L2 API. Cropping a smaller image from a larger
one is achieved by setting the field <structfield>
&v4l2-pix-format;::bytesperline </structfield>. Introducing an image offsets
could be done by modifying field <structfield> &v4l2-buffer;::m:userptr
</structfield> before calling <constant> VIDIOC_QBUF </constant>. Those
operations should be avoided because they are not portable (endianness), and do
not work for macroblock and Bayer formats and mmap buffers. The selection API
deals with configuration of buffer cropping/composing in a clear, intuitive and
portable way. Next, with the selection API the concepts of the padded target
and constraints flags are introduced. Finally, <structname> &v4l2-crop;
</structname> and <structname> &v4l2-cropcap; </structname> have no reserved
fields. Therefore there is no way to extend their functionality. The new
<structname> &v4l2-selection; </structname> provides a lot of place for future
extensions. Driver developers are encouraged to implement only selection API.
The former cropping API would be simulated using the new one. </para>
</section>
<section>
<title>Examples</title>
<example>
<title>Resetting the cropping parameters</title>
<para>(A video capture device is assumed; change <constant>
V4L2_BUF_TYPE_VIDEO_CAPTURE </constant> for other devices; change target to
<constant> V4L2_SEL_TGT_COMPOSE_* </constant> family to configure composing
area)</para>
<programlisting>
&v4l2-selection; sel = {
.type = V4L2_BUF_TYPE_VIDEO_CAPTURE,
.target = V4L2_SEL_TGT_CROP_DEFAULT,
};
ret = ioctl(fd, &VIDIOC-G-SELECTION;, &amp;sel);
if (ret)
exit(-1);
sel.target = V4L2_SEL_TGT_CROP_ACTIVE;
ret = ioctl(fd, &VIDIOC-S-SELECTION;, &amp;sel);
if (ret)
exit(-1);
</programlisting>
</example>
<example>
<title>Simple downscaling</title>
<para>Setting a composing area on output of size of <emphasis> at most
</emphasis> half of limit placed at a center of a display.</para>
<programlisting>
&v4l2-selection; sel = {
.type = V4L2_BUF_TYPE_VIDEO_OUTPUT,
.target = V4L2_SEL_TGT_COMPOSE_BOUNDS,
};
struct v4l2_rect r;
ret = ioctl(fd, &VIDIOC-G-SELECTION;, &amp;sel);
if (ret)
exit(-1);
/* setting smaller compose rectangle */
r.width = sel.r.width / 2;
r.height = sel.r.height / 2;
r.left = sel.r.width / 4;
r.top = sel.r.height / 4;
sel.r = r;
sel.target = V4L2_SEL_TGT_COMPOSE_ACTIVE;
sel.flags = V4L2_SEL_FLAG_LE;
ret = ioctl(fd, &VIDIOC-S-SELECTION;, &amp;sel);
if (ret)
exit(-1);
</programlisting>
</example>
<example>
<title>Querying for scaling factors</title>
<para>A video output device is assumed; change <constant>
V4L2_BUF_TYPE_VIDEO_OUTPUT </constant> for other devices</para>
<programlisting>
&v4l2-selection; compose = {
.type = V4L2_BUF_TYPE_VIDEO_OUTPUT,
.target = V4L2_SEL_TGT_COMPOSE_ACTIVE,
};
&v4l2-selection; crop = {
.type = V4L2_BUF_TYPE_VIDEO_OUTPUT,
.target = V4L2_SEL_TGT_CROP_ACTIVE,
};
double hscale, vscale;
ret = ioctl(fd, &VIDIOC-G-SELECTION;, &amp;compose);
if (ret)
exit(-1);
ret = ioctl(fd, &VIDIOC-G-SELECTION;, &amp;crop);
if (ret)
exit(-1);
/* computing scaling factors */
hscale = (double)compose.r.width / crop.r.width;
vscale = (double)compose.r.height / crop.r.height;
</programlisting>
</example>
</section>
</section>
kernel/Documentation/DocBook/media/v4l/subdev-formats.xml
+2569
View File
File diff suppressed because it is too large Load Diff
kernel/Documentation/DocBook/media/v4l/v4l2.xml
+575
View File
@@ -0,0 +1,575 @@
<partinfo>
<authorgroup>
<author>
<firstname>Michael</firstname>
<surname>Schimek</surname>
<othername role="mi">H</othername>
<affiliation>
<address>
<email>mschimek@gmx.at</email>
</address>
</affiliation>
</author>
<author>
<firstname>Bill</firstname>
<surname>Dirks</surname>
<!-- Commented until Bill opts in to be spammed.
<affiliation>
<address>
<email>bill@thedirks.org</email>
</address>
</affiliation> -->
<contrib>Original author of the V4L2 API and
documentation.</contrib>
</author>
<author>
<firstname>Hans</firstname>
<surname>Verkuil</surname>
<contrib>Designed and documented the VIDIOC_LOG_STATUS ioctl,
the extended control ioctls and major parts of the sliced VBI
API.</contrib>
<affiliation>
<address>
<email>hverkuil@xs4all.nl</email>
</address>
</affiliation>
</author>
<author>
<firstname>Martin</firstname>
<surname>Rubli</surname>
<!--
<affiliation>
<address>
<email>martin_rubli@logitech.com</email>
</address>
</affiliation> -->
<contrib>Designed and documented the VIDIOC_ENUM_FRAMESIZES
and VIDIOC_ENUM_FRAMEINTERVALS ioctls.</contrib>
</author>
<author>
<firstname>Andy</firstname>
<surname>Walls</surname>
<contrib>Documented the fielded V4L2_MPEG_STREAM_VBI_FMT_IVTV
MPEG stream embedded, sliced VBI data format in this specification.
</contrib>
<affiliation>
<address>
<email>awalls@md.metrocast.net</email>
</address>
</affiliation>
</author>
<author>
<firstname>Mauro</firstname>
<surname>Carvalho Chehab</surname>
<contrib>Documented libv4l, designed and added v4l2grab example,
Remote Controller chapter.</contrib>
<affiliation>
<address>
<email>mchehab@redhat.com</email>
</address>
</affiliation>
</author>
<author>
<firstname>Muralidharan</firstname>
<surname>Karicheri</surname>
<contrib>Documented the Digital Video timings API.</contrib>
<affiliation>
<address>
<email>m-karicheri2@ti.com</email>
</address>
</affiliation>
</author>
<author>
<firstname>Pawel</firstname>
<surname>Osciak</surname>
<contrib>Designed and documented the multi-planar API.</contrib>
<affiliation>
<address>
<email>pawel AT osciak.com</email>
</address>
</affiliation>
</author>
</authorgroup>
<copyright>
<year>1999</year>
<year>2000</year>
<year>2001</year>
<year>2002</year>
<year>2003</year>
<year>2004</year>
<year>2005</year>
<year>2006</year>
<year>2007</year>
<year>2008</year>
<year>2009</year>
<year>2010</year>
<year>2011</year>
<holder>Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin
Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab,
Pawel Osciak</holder>
</copyright>
<legalnotice>
<para>Except when explicitly stated as GPL, programming examples within
this part can be used and distributed without restrictions.</para>
</legalnotice>
<revhistory>
<!-- Put document revisions here, newest first. -->
<!-- API revisions (changes and additions of defines, enums,
structs, ioctls) must be noted in more detail in the history chapter
(compat.xml), along with the possible impact on existing drivers and
applications. -->
<revision>
<revnumber>3.4</revnumber>
<date>2012-01-25</date>
<authorinitials>sn</authorinitials>
<revremark>Added <link linkend="jpeg-controls">JPEG compression
control class.</link>
</revremark>
</revision>
<revision>
<revnumber>3.3</revnumber>
<date>2012-01-11</date>
<authorinitials>hv</authorinitials>
<revremark>Added device_caps field to struct v4l2_capabilities.</revremark>
</revision>
<revision>
<revnumber>3.2</revnumber>
<date>2011-08-26</date>
<authorinitials>hv</authorinitials>
<revremark>Added V4L2_CTRL_FLAG_VOLATILE.</revremark>
</revision>
<revision>
<revnumber>3.1</revnumber>
<date>2011-06-27</date>
<authorinitials>mcc, po, hv</authorinitials>
<revremark>Documented that VIDIOC_QUERYCAP now returns a per-subsystem version instead of a per-driver one.
Standardize an error code for invalid ioctl.
Added V4L2_CTRL_TYPE_BITMASK.</revremark>
</revision>
<revision>
<revnumber>2.6.39</revnumber>
<date>2011-03-01</date>
<authorinitials>mcc, po</authorinitials>
<revremark>Removed VIDIOC_*_OLD from videodev2.h header and update it to reflect latest changes. Added the <link linkend="planar-apis">multi-planar API</link>.</revremark>
</revision>
<revision>
<revnumber>2.6.37</revnumber>
<date>2010-08-06</date>
<authorinitials>hv</authorinitials>
<revremark>Removed obsolete vtx (videotext) API.</revremark>
</revision>
<revision>
<revnumber>2.6.33</revnumber>
<date>2009-12-03</date>
<authorinitials>mk</authorinitials>
<revremark>Added documentation for the Digital Video timings API.</revremark>
</revision>
<revision>
<revnumber>2.6.32</revnumber>
<date>2009-08-31</date>
<authorinitials>mcc</authorinitials>
<revremark>Now, revisions will match the kernel version where
the V4L2 API changes will be used by the Linux Kernel.
Also added Remote Controller chapter.</revremark>
</revision>
<revision>
<revnumber>0.29</revnumber>
<date>2009-08-26</date>
<authorinitials>ev</authorinitials>
<revremark>Added documentation for string controls and for FM Transmitter controls.</revremark>
</revision>
<revision>
<revnumber>0.28</revnumber>
<date>2009-08-26</date>
<authorinitials>gl</authorinitials>
<revremark>Added V4L2_CID_BAND_STOP_FILTER documentation.</revremark>
</revision>
<revision>
<revnumber>0.27</revnumber>
<date>2009-08-15</date>
<authorinitials>mcc</authorinitials>
<revremark>Added libv4l and Remote Controller documentation;
added v4l2grab and keytable application examples.</revremark>
</revision>
<revision>
<revnumber>0.26</revnumber>
<date>2009-07-23</date>
<authorinitials>hv</authorinitials>
<revremark>Finalized the RDS capture API. Added modulator and RDS encoder
capabilities. Added support for string controls.</revremark>
</revision>
<revision>
<revnumber>0.25</revnumber>
<date>2009-01-18</date>
<authorinitials>hv</authorinitials>
<revremark>Added pixel formats VYUY, NV16 and NV61, and changed
the debug ioctls VIDIOC_DBG_G/S_REGISTER and VIDIOC_DBG_G_CHIP_IDENT.
Added camera controls V4L2_CID_ZOOM_ABSOLUTE, V4L2_CID_ZOOM_RELATIVE,
V4L2_CID_ZOOM_CONTINUOUS and V4L2_CID_PRIVACY.</revremark>
</revision>
<revision>
<revnumber>0.24</revnumber>
<date>2008-03-04</date>
<authorinitials>mhs</authorinitials>
<revremark>Added pixel formats Y16 and SBGGR16, new controls
and a camera controls class. Removed VIDIOC_G/S_MPEGCOMP.</revremark>
</revision>
<revision>
<revnumber>0.23</revnumber>
<date>2007-08-30</date>
<authorinitials>mhs</authorinitials>
<revremark>Fixed a typo in VIDIOC_DBG_G/S_REGISTER.
Clarified the byte order of packed pixel formats.</revremark>
</revision>
<revision>
<revnumber>0.22</revnumber>
<date>2007-08-29</date>
<authorinitials>mhs</authorinitials>
<revremark>Added the Video Output Overlay interface, new MPEG
controls, V4L2_FIELD_INTERLACED_TB and V4L2_FIELD_INTERLACED_BT,
VIDIOC_DBG_G/S_REGISTER, VIDIOC_(TRY_)ENCODER_CMD,
VIDIOC_G_CHIP_IDENT, VIDIOC_G_ENC_INDEX, new pixel formats.
Clarifications in the cropping chapter, about RGB pixel formats, the
mmap(), poll(), select(), read() and write() functions. Typographical
fixes.</revremark>
</revision>
<revision>
<revnumber>0.21</revnumber>
<date>2006-12-19</date>
<authorinitials>mhs</authorinitials>
<revremark>Fixed a link in the VIDIOC_G_EXT_CTRLS section.</revremark>
</revision>
<revision>
<revnumber>0.20</revnumber>
<date>2006-11-24</date>
<authorinitials>mhs</authorinitials>
<revremark>Clarified the purpose of the audioset field in
struct v4l2_input and v4l2_output.</revremark>
</revision>
<revision>
<revnumber>0.19</revnumber>
<date>2006-10-19</date>
<authorinitials>mhs</authorinitials>
<revremark>Documented V4L2_PIX_FMT_RGB444.</revremark>
</revision>
<revision>
<revnumber>0.18</revnumber>
<date>2006-10-18</date>
<authorinitials>mhs</authorinitials>
<revremark>Added the description of extended controls by Hans
Verkuil. Linked V4L2_PIX_FMT_MPEG to V4L2_CID_MPEG_STREAM_TYPE.</revremark>
</revision>
<revision>
<revnumber>0.17</revnumber>
<date>2006-10-12</date>
<authorinitials>mhs</authorinitials>
<revremark>Corrected V4L2_PIX_FMT_HM12 description.</revremark>
</revision>
<revision>
<revnumber>0.16</revnumber>
<date>2006-10-08</date>
<authorinitials>mhs</authorinitials>
<revremark>VIDIOC_ENUM_FRAMESIZES and
VIDIOC_ENUM_FRAMEINTERVALS are now part of the API.</revremark>
</revision>
<revision>
<revnumber>0.15</revnumber>
<date>2006-09-23</date>
<authorinitials>mhs</authorinitials>
<revremark>Cleaned up the bibliography, added BT.653 and
BT.1119. capture.c/start_capturing() for user pointer I/O did not
initialize the buffer index. Documented the V4L MPEG and MJPEG
VID_TYPEs and V4L2_PIX_FMT_SBGGR8. Updated the list of reserved pixel
formats. See the history chapter for API changes.</revremark>
</revision>
<revision>
<revnumber>0.14</revnumber>
<date>2006-09-14</date>
<authorinitials>mr</authorinitials>
<revremark>Added VIDIOC_ENUM_FRAMESIZES and
VIDIOC_ENUM_FRAMEINTERVALS proposal for frame format enumeration of
digital devices.</revremark>
</revision>
<revision>
<revnumber>0.13</revnumber>
<date>2006-04-07</date>
<authorinitials>mhs</authorinitials>
<revremark>Corrected the description of struct v4l2_window
clips. New V4L2_STD_ and V4L2_TUNER_MODE_LANG1_LANG2
defines.</revremark>
</revision>
<revision>
<revnumber>0.12</revnumber>
<date>2006-02-03</date>
<authorinitials>mhs</authorinitials>
<revremark>Corrected the description of struct
v4l2_captureparm and v4l2_outputparm.</revremark>
</revision>
<revision>
<revnumber>0.11</revnumber>
<date>2006-01-27</date>
<authorinitials>mhs</authorinitials>
<revremark>Improved the description of struct
v4l2_tuner.</revremark>
</revision>
<revision>
<revnumber>0.10</revnumber>
<date>2006-01-10</date>
<authorinitials>mhs</authorinitials>
<revremark>VIDIOC_G_INPUT and VIDIOC_S_PARM
clarifications.</revremark>
</revision>
<revision>
<revnumber>0.9</revnumber>
<date>2005-11-27</date>
<authorinitials>mhs</authorinitials>
<revremark>Improved the 525 line numbering diagram. Hans
Verkuil and I rewrote the sliced VBI section. He also contributed a
VIDIOC_LOG_STATUS page. Fixed VIDIOC_S_STD call in the video standard
selection example. Various updates.</revremark>
</revision>
<revision>
<revnumber>0.8</revnumber>
<date>2004-10-04</date>
<authorinitials>mhs</authorinitials>
<revremark>Somehow a piece of junk slipped into the capture
example, removed.</revremark>
</revision>
<revision>
<revnumber>0.7</revnumber>
<date>2004-09-19</date>
<authorinitials>mhs</authorinitials>
<revremark>Fixed video standard selection, control
enumeration, downscaling and aspect example. Added read and user
pointer i/o to video capture example.</revremark>
</revision>
<revision>
<revnumber>0.6</revnumber>
<date>2004-08-01</date>
<authorinitials>mhs</authorinitials>
<revremark>v4l2_buffer changes, added video capture example,
various corrections.</revremark>
</revision>
<revision>
<revnumber>0.5</revnumber>
<date>2003-11-05</date>
<authorinitials>mhs</authorinitials>
<revremark>Pixel format erratum.</revremark>
</revision>
<revision>
<revnumber>0.4</revnumber>
<date>2003-09-17</date>
<authorinitials>mhs</authorinitials>
<revremark>Corrected source and Makefile to generate a PDF.
SGML fixes. Added latest API changes. Closed gaps in the history
chapter.</revremark>
</revision>
<revision>
<revnumber>0.3</revnumber>
<date>2003-02-05</date>
<authorinitials>mhs</authorinitials>
<revremark>Another draft, more corrections.</revremark>
</revision>
<revision>
<revnumber>0.2</revnumber>
<date>2003-01-15</date>
<authorinitials>mhs</authorinitials>
<revremark>Second draft, with corrections pointed out by Gerd
Knorr.</revremark>
</revision>
<revision>
<revnumber>0.1</revnumber>
<date>2002-12-01</date>
<authorinitials>mhs</authorinitials>
<revremark>First draft, based on documentation by Bill Dirks
and discussions on the V4L mailing list.</revremark>
</revision>
</revhistory>
</partinfo>
<title>Video for Linux Two API Specification</title>
<subtitle>Revision 3.3</subtitle>
<chapter id="common">
&sub-common;
</chapter>
<chapter id="pixfmt">
&sub-pixfmt;
</chapter>
<chapter id="io">
&sub-io;
</chapter>
<chapter id="devices">
<title>Interfaces</title>
<section id="capture"> &sub-dev-capture; </section>
<section id="overlay"> &sub-dev-overlay; </section>
<section id="output"> &sub-dev-output; </section>
<section id="osd"> &sub-dev-osd; </section>
<section id="codec"> &sub-dev-codec; </section>
<section id="effect"> &sub-dev-effect; </section>
<section id="raw-vbi"> &sub-dev-raw-vbi; </section>
<section id="sliced"> &sub-dev-sliced-vbi; </section>
<section id="ttx"> &sub-dev-teletext; </section>
<section id="radio"> &sub-dev-radio; </section>
<section id="rds"> &sub-dev-rds; </section>
<section id="event"> &sub-dev-event; </section>
<section id="subdev"> &sub-dev-subdev; </section>
</chapter>
<chapter id="driver">
&sub-driver;
</chapter>
<chapter id="libv4l">
&sub-libv4l;
</chapter>
<chapter id="compat">
&sub-compat;
</chapter>
<appendix id="user-func">
<title>Function Reference</title>
<!-- Keep this alphabetically sorted. -->
&sub-close;
&sub-ioctl;
<!-- All ioctls go here. -->
&sub-create-bufs;
&sub-cropcap;
&sub-dbg-g-chip-ident;
&sub-dbg-g-register;
&sub-decoder-cmd;
&sub-dqevent;
&sub-encoder-cmd;
&sub-enumaudio;
&sub-enumaudioout;
&sub-enum-dv-presets;
&sub-enum-fmt;
&sub-enum-framesizes;
&sub-enum-frameintervals;
&sub-enuminput;
&sub-enumoutput;
&sub-enumstd;
&sub-g-audio;
&sub-g-audioout;
&sub-g-crop;
&sub-g-ctrl;
&sub-g-dv-preset;
&sub-g-dv-timings;
&sub-g-enc-index;
&sub-g-ext-ctrls;
&sub-g-fbuf;
&sub-g-fmt;
&sub-g-frequency;
&sub-g-input;
&sub-g-jpegcomp;
&sub-g-modulator;
&sub-g-output;
&sub-g-parm;
&sub-g-priority;
&sub-g-selection;
&sub-g-sliced-vbi-cap;
&sub-g-std;
&sub-g-tuner;
&sub-log-status;
&sub-overlay;
&sub-qbuf;
&sub-querybuf;
&sub-querycap;
&sub-queryctrl;
&sub-query-dv-preset;
&sub-querystd;
&sub-prepare-buf;
&sub-reqbufs;
&sub-s-hw-freq-seek;
&sub-streamon;
&sub-subdev-enum-frame-interval;
&sub-subdev-enum-frame-size;
&sub-subdev-enum-mbus-code;
&sub-subdev-g-crop;
&sub-subdev-g-fmt;
&sub-subdev-g-frame-interval;
&sub-subscribe-event;
<!-- End of ioctls. -->
&sub-mmap;
&sub-munmap;
&sub-open;
&sub-poll;
&sub-read;
&sub-select;
&sub-write;
</appendix>
<appendix id="videodev">
<title>Video For Linux Two Header File</title>
&sub-videodev2-h;
</appendix>
<appendix id="capture-example">
<title>Video Capture Example</title>
&sub-capture-c;
</appendix>
<appendix id="v4l2grab-example">
<title>Video Grabber example using libv4l</title>
<para>This program demonstrates how to grab V4L2 images in ppm format by
using libv4l handlers. The advantage is that this grabber can potentially work
with any V4L2 driver.</para>
&sub-v4l2grab-c;
</appendix>
&sub-media-indices;
&sub-biblio;
kernel/Documentation/DocBook/media/v4l/v4l2grab.c.xml
+164
View File
@@ -0,0 +1,164 @@
<programlisting>
/* V4L2 video picture grabber
Copyright (C) 2009 Mauro Carvalho Chehab &lt;mchehab@infradead.org&gt;
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation version 2 of the License.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
*/
#include &lt;stdio.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;string.h&gt;
#include &lt;fcntl.h&gt;
#include &lt;errno.h&gt;
#include &lt;sys/ioctl.h&gt;
#include &lt;sys/types.h&gt;
#include &lt;sys/time.h&gt;
#include &lt;sys/mman.h&gt;
#include &lt;linux/videodev2.h&gt;
#include "../libv4l/include/libv4l2.h"
#define CLEAR(x) memset(&amp;(x), 0, sizeof(x))
struct buffer {
void *start;
size_t length;
};
static void xioctl(int fh, int request, void *arg)
{
int r;
do {
r = v4l2_ioctl(fh, request, arg);
} while (r == -1 &amp;&amp; ((errno == EINTR) || (errno == EAGAIN)));
if (r == -1) {
fprintf(stderr, "error %d, %s\n", errno, strerror(errno));
exit(EXIT_FAILURE);
}
}
int main(int argc, char **argv)
{
struct <link linkend="v4l2-format">v4l2_format</link> fmt;
struct <link linkend="v4l2-buffer">v4l2_buffer</link> buf;
struct <link linkend="v4l2-requestbuffers">v4l2_requestbuffers</link> req;
enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type;
fd_set fds;
struct timeval tv;
int r, fd = -1;
unsigned int i, n_buffers;
char *dev_name = "/dev/video0";
char out_name[256];
FILE *fout;
struct buffer *buffers;
fd = v4l2_open(dev_name, O_RDWR | O_NONBLOCK, 0);
if (fd &lt; 0) {
perror("Cannot open device");
exit(EXIT_FAILURE);
}
CLEAR(fmt);
fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
fmt.fmt.pix.width = 640;
fmt.fmt.pix.height = 480;
fmt.fmt.pix.pixelformat = V4L2_PIX_FMT_RGB24;
fmt.fmt.pix.field = V4L2_FIELD_INTERLACED;
xioctl(fd, VIDIOC_S_FMT, &amp;fmt);
if (fmt.fmt.pix.pixelformat != V4L2_PIX_FMT_RGB24) {
printf("Libv4l didn't accept RGB24 format. Can't proceed.\n");
exit(EXIT_FAILURE);
}
if ((fmt.fmt.pix.width != 640) || (fmt.fmt.pix.height != 480))
printf("Warning: driver is sending image at %dx%d\n",
fmt.fmt.pix.width, fmt.fmt.pix.height);
CLEAR(req);
req.count = 2;
req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
req.memory = V4L2_MEMORY_MMAP;
xioctl(fd, VIDIOC_REQBUFS, &amp;req);
buffers = calloc(req.count, sizeof(*buffers));
for (n_buffers = 0; n_buffers &lt; req.count; ++n_buffers) {
CLEAR(buf);
buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
buf.memory = V4L2_MEMORY_MMAP;
buf.index = n_buffers;
xioctl(fd, VIDIOC_QUERYBUF, &amp;buf);
buffers[n_buffers].length = buf.length;
buffers[n_buffers].start = v4l2_mmap(NULL, buf.length,
PROT_READ | PROT_WRITE, MAP_SHARED,
fd, buf.m.offset);
if (MAP_FAILED == buffers[n_buffers].start) {
perror("mmap");
exit(EXIT_FAILURE);
}
}
for (i = 0; i &lt; n_buffers; ++i) {
CLEAR(buf);
buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
buf.memory = V4L2_MEMORY_MMAP;
buf.index = i;
xioctl(fd, VIDIOC_QBUF, &amp;buf);
}
type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
xioctl(fd, VIDIOC_STREAMON, &amp;type);
for (i = 0; i &lt; 20; i++) {
do {
FD_ZERO(&amp;fds);
FD_SET(fd, &amp;fds);
/* Timeout. */
tv.tv_sec = 2;
tv.tv_usec = 0;
r = select(fd + 1, &amp;fds, NULL, NULL, &amp;tv);
} while ((r == -1 &amp;&amp; (errno = EINTR)));
if (r == -1) {
perror("select");
return errno;
}
CLEAR(buf);
buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
buf.memory = V4L2_MEMORY_MMAP;
xioctl(fd, VIDIOC_DQBUF, &amp;buf);
sprintf(out_name, "out%03d.ppm", i);
fout = fopen(out_name, "w");
if (!fout) {
perror("Cannot open image");
exit(EXIT_FAILURE);
}
fprintf(fout, "P6\n%d %d 255\n",
fmt.fmt.pix.width, fmt.fmt.pix.height);
fwrite(buffers[buf.index].start, buf.bytesused, 1, fout);
fclose(fout);
xioctl(fd, VIDIOC_QBUF, &amp;buf);
}
type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
xioctl(fd, VIDIOC_STREAMOFF, &amp;type);
for (i = 0; i &lt; n_buffers; ++i)
v4l2_munmap(buffers[i].start, buffers[i].length);
v4l2_close(fd);
return 0;
}
</programlisting>
kernel/Documentation/DocBook/media/v4l/vbi_525.pdf
BIN
View File
Binary file not shown.
kernel/Documentation/DocBook/media/v4l/vbi_625.pdf
BIN
View File
Binary file not shown.
kernel/Documentation/DocBook/media/v4l/vbi_hsync.pdf
BIN
View File
Binary file not shown.
kernel/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml
+139
View File
@@ -0,0 +1,139 @@
<refentry id="vidioc-create-bufs">
<refmeta>
<refentrytitle>ioctl VIDIOC_CREATE_BUFS</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>VIDIOC_CREATE_BUFS</refname>
<refpurpose>Create buffers for Memory Mapped or User Pointer I/O</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ioctl</function></funcdef>
<paramdef>int <parameter>fd</parameter></paramdef>
<paramdef>int <parameter>request</parameter></paramdef>
<paramdef>struct v4l2_create_buffers *<parameter>argp</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>fd</parameter></term>
<listitem>
<para>&fd;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>request</parameter></term>
<listitem>
<para>VIDIOC_CREATE_BUFS</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>argp</parameter></term>
<listitem>
<para></para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>This ioctl is used to create buffers for <link linkend="mmap">memory
mapped</link> or <link linkend="userp">user pointer</link>
I/O. It can be used as an alternative or in addition to the
<constant>VIDIOC_REQBUFS</constant> ioctl, when a tighter control over buffers
is required. This ioctl can be called multiple times to create buffers of
different sizes.</para>
<para>To allocate device buffers applications initialize relevant fields of
the <structname>v4l2_create_buffers</structname> structure. They set the
<structfield>type</structfield> field in the
<structname>v4l2_format</structname> structure, embedded in this
structure, to the respective stream or buffer type.
<structfield>count</structfield> must be set to the number of required buffers.
<structfield>memory</structfield> specifies the required I/O method. The
<structfield>format</structfield> field shall typically be filled in using
either the <constant>VIDIOC_TRY_FMT</constant> or
<constant>VIDIOC_G_FMT</constant> ioctl(). Additionally, applications can adjust
<structfield>sizeimage</structfield> fields to fit their specific needs. The
<structfield>reserved</structfield> array must be zeroed.</para>
<para>When the ioctl is called with a pointer to this structure the driver
will attempt to allocate up to the requested number of buffers and store the
actual number allocated and the starting index in the
<structfield>count</structfield> and the <structfield>index</structfield> fields
respectively. On return <structfield>count</structfield> can be smaller than
the number requested. The driver may also increase buffer sizes if required,
however, it will not update <structfield>sizeimage</structfield> field values.
The user has to use <constant>VIDIOC_QUERYBUF</constant> to retrieve that
information.</para>
<table pgwide="1" frame="none" id="v4l2-create-buffers">
<title>struct <structname>v4l2_create_buffers</structname></title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>__u32</entry>
<entry><structfield>index</structfield></entry>
<entry>The starting buffer index, returned by the driver.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>count</structfield></entry>
<entry>The number of buffers requested or granted.</entry>
</row>
<row>
<entry>&v4l2-memory;</entry>
<entry><structfield>memory</structfield></entry>
<entry>Applications set this field to
<constant>V4L2_MEMORY_MMAP</constant> or
<constant>V4L2_MEMORY_USERPTR</constant>.</entry>
</row>
<row>
<entry>&v4l2-format;</entry>
<entry><structfield>format</structfield></entry>
<entry>Filled in by the application, preserved by the driver.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>reserved</structfield>[8]</entry>
<entry>A place holder for future extensions.</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1>
&return-value;
<variablelist>
<varlistentry>
<term><errorcode>ENOMEM</errorcode></term>
<listitem>
<para>No memory to allocate buffers for <link linkend="mmap">memory
mapped</link> I/O.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EINVAL</errorcode></term>
<listitem>
<para>The buffer type (<structfield>type</structfield> field) or the
requested I/O method (<structfield>memory</structfield>) is not
supported.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/vidioc-cropcap.xml
+165
View File
@@ -0,0 +1,165 @@
<refentry id="vidioc-cropcap">
<refmeta>
<refentrytitle>ioctl VIDIOC_CROPCAP</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>VIDIOC_CROPCAP</refname>
<refpurpose>Information about the video cropping and scaling abilities</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ioctl</function></funcdef>
<paramdef>int <parameter>fd</parameter></paramdef>
<paramdef>int <parameter>request</parameter></paramdef>
<paramdef>struct v4l2_cropcap
*<parameter>argp</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>fd</parameter></term>
<listitem>
<para>&fd;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>request</parameter></term>
<listitem>
<para>VIDIOC_CROPCAP</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>argp</parameter></term>
<listitem>
<para></para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>Applications use this function to query the cropping
limits, the pixel aspect of images and to calculate scale factors.
They set the <structfield>type</structfield> field of a v4l2_cropcap
structure to the respective buffer (stream) type and call the
<constant>VIDIOC_CROPCAP</constant> ioctl with a pointer to this
structure. Drivers fill the rest of the structure. The results are
constant except when switching the video standard. Remember this
switch can occur implicit when switching the video input or
output.</para>
<table pgwide="1" frame="none" id="v4l2-cropcap">
<title>struct <structname>v4l2_cropcap</structname></title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>&v4l2-buf-type;</entry>
<entry><structfield>type</structfield></entry>
<entry>Type of the data stream, set by the application.
Only these types are valid here:
<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>,
<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>,
<constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>, and custom (driver
defined) types with code <constant>V4L2_BUF_TYPE_PRIVATE</constant>
and higher.</entry>
</row>
<row>
<entry>struct <link linkend="v4l2-rect-crop">v4l2_rect</link></entry>
<entry><structfield>bounds</structfield></entry>
<entry>Defines the window within capturing or output is
possible, this may exclude for example the horizontal and vertical
blanking areas. The cropping rectangle cannot exceed these limits.
Width and height are defined in pixels, the driver writer is free to
choose origin and units of the coordinate system in the analog
domain.</entry>
</row>
<row>
<entry>struct <link linkend="v4l2-rect-crop">v4l2_rect</link></entry>
<entry><structfield>defrect</structfield></entry>
<entry>Default cropping rectangle, it shall cover the
"whole picture". Assuming pixel aspect 1/1 this could be for example a
640&nbsp;&times;&nbsp;480 rectangle for NTSC, a
768&nbsp;&times;&nbsp;576 rectangle for PAL and SECAM centered over
the active picture area. The same co-ordinate system as for
<structfield>bounds</structfield> is used.</entry>
</row>
<row>
<entry>&v4l2-fract;</entry>
<entry><structfield>pixelaspect</structfield></entry>
<entry><para>This is the pixel aspect (y / x) when no
scaling is applied, the ratio of the actual sampling
frequency and the frequency required to get square
pixels.</para><para>When cropping coordinates refer to square pixels,
the driver sets <structfield>pixelaspect</structfield> to 1/1. Other
common values are 54/59 for PAL and SECAM, 11/10 for NTSC sampled
according to [<xref linkend="itu601" />].</para></entry>
</row>
</tbody>
</tgroup>
</table>
<!-- NB this table is duplicated in the overlay chapter. -->
<table pgwide="1" frame="none" id="v4l2-rect-crop">
<title>struct <structname>v4l2_rect</structname></title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>__s32</entry>
<entry><structfield>left</structfield></entry>
<entry>Horizontal offset of the top, left corner of the
rectangle, in pixels.</entry>
</row>
<row>
<entry>__s32</entry>
<entry><structfield>top</structfield></entry>
<entry>Vertical offset of the top, left corner of the
rectangle, in pixels.</entry>
</row>
<row>
<entry>__s32</entry>
<entry><structfield>width</structfield></entry>
<entry>Width of the rectangle, in pixels.</entry>
</row>
<row>
<entry>__s32</entry>
<entry><structfield>height</structfield></entry>
<entry>Height of the rectangle, in pixels. Width
and height cannot be negative, the fields are signed for
hysterical reasons. <!-- video4linux-list@redhat.com
on 22 Oct 2002 subject "Re:[V4L][patches!] Re:v4l2/kernel-2.5" -->
</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1>
&return-value;
<variablelist>
<varlistentry>
<term><errorcode>EINVAL</errorcode></term>
<listitem>
<para>The &v4l2-cropcap; <structfield>type</structfield> is
invalid. This is not permitted for video capture, output and overlay devices,
which must support <constant>VIDIOC_CROPCAP</constant>.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/vidioc-dbg-g-chip-ident.xml
+266
View File
@@ -0,0 +1,266 @@
<refentry id="vidioc-dbg-g-chip-ident">
<refmeta>
<refentrytitle>ioctl VIDIOC_DBG_G_CHIP_IDENT</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>VIDIOC_DBG_G_CHIP_IDENT</refname>
<refpurpose>Identify the chips on a TV card</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ioctl</function></funcdef>
<paramdef>int <parameter>fd</parameter></paramdef>
<paramdef>int <parameter>request</parameter></paramdef>
<paramdef>struct v4l2_dbg_chip_ident
*<parameter>argp</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>fd</parameter></term>
<listitem>
<para>&fd;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>request</parameter></term>
<listitem>
<para>VIDIOC_DBG_G_CHIP_IDENT</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>argp</parameter></term>
<listitem>
<para></para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<note>
<title>Experimental</title>
<para>This is an <link
linkend="experimental">experimental</link> interface and may change in
the future.</para>
</note>
<para>For driver debugging purposes this ioctl allows test
applications to query the driver about the chips present on the TV
card. Regular applications must not use it. When you found a chip
specific bug, please contact the linux-media mailing list (&v4l-ml;)
so it can be fixed.</para>
<para>To query the driver applications must initialize the
<structfield>match.type</structfield> and
<structfield>match.addr</structfield> or <structfield>match.name</structfield>
fields of a &v4l2-dbg-chip-ident;
and call <constant>VIDIOC_DBG_G_CHIP_IDENT</constant> with a pointer to
this structure. On success the driver stores information about the
selected chip in the <structfield>ident</structfield> and
<structfield>revision</structfield> fields. On failure the structure
remains unchanged.</para>
<para>When <structfield>match.type</structfield> is
<constant>V4L2_CHIP_MATCH_HOST</constant>,
<structfield>match.addr</structfield> selects the nth non-&i2c; chip
on the TV card. You can enumerate all chips by starting at zero and
incrementing <structfield>match.addr</structfield> by one until
<constant>VIDIOC_DBG_G_CHIP_IDENT</constant> fails with an &EINVAL;.
The number zero always selects the host chip, &eg; the chip connected
to the PCI or USB bus.</para>
<para>When <structfield>match.type</structfield> is
<constant>V4L2_CHIP_MATCH_I2C_DRIVER</constant>,
<structfield>match.name</structfield> contains the I2C driver name.
For instance
<constant>"saa7127"</constant> will match any chip
supported by the saa7127 driver, regardless of its &i2c; bus address.
When multiple chips supported by the same driver are present, the
ioctl will return <constant>V4L2_IDENT_AMBIGUOUS</constant> in the
<structfield>ident</structfield> field.</para>
<para>When <structfield>match.type</structfield> is
<constant>V4L2_CHIP_MATCH_I2C_ADDR</constant>,
<structfield>match.addr</structfield> selects a chip by its 7 bit
&i2c; bus address.</para>
<para>When <structfield>match.type</structfield> is
<constant>V4L2_CHIP_MATCH_AC97</constant>,
<structfield>match.addr</structfield> selects the nth AC97 chip
on the TV card. You can enumerate all chips by starting at zero and
incrementing <structfield>match.addr</structfield> by one until
<constant>VIDIOC_DBG_G_CHIP_IDENT</constant> fails with an &EINVAL;.</para>
<para>On success, the <structfield>ident</structfield> field will
contain a chip ID from the Linux
<filename>media/v4l2-chip-ident.h</filename> header file, and the
<structfield>revision</structfield> field will contain a driver
specific value, or zero if no particular revision is associated with
this chip.</para>
<para>When the driver could not identify the selected chip,
<structfield>ident</structfield> will contain
<constant>V4L2_IDENT_UNKNOWN</constant>. When no chip matched
the ioctl will succeed but the
<structfield>ident</structfield> field will contain
<constant>V4L2_IDENT_NONE</constant>. If multiple chips matched,
<structfield>ident</structfield> will contain
<constant>V4L2_IDENT_AMBIGUOUS</constant>. In all these cases the
<structfield>revision</structfield> field remains unchanged.</para>
<para>This ioctl is optional, not all drivers may support it. It
was introduced in Linux 2.6.21, but the API was changed to the
one described here in 2.6.29.</para>
<para>We recommended the <application>v4l2-dbg</application>
utility over calling this ioctl directly. It is available from the
LinuxTV v4l-dvb repository; see <ulink
url="http://linuxtv.org/repo/">http://linuxtv.org/repo/</ulink> for
access instructions.</para>
<!-- Note for convenience vidioc-dbg-g-register.sgml
contains a duplicate of this table. -->
<table pgwide="1" frame="none" id="ident-v4l2-dbg-match">
<title>struct <structname>v4l2_dbg_match</structname></title>
<tgroup cols="4">
&cs-ustr;
<tbody valign="top">
<row>
<entry>__u32</entry>
<entry><structfield>type</structfield></entry>
<entry>See <xref linkend="ident-chip-match-types" /> for a list of
possible types.</entry>
</row>
<row>
<entry>union</entry>
<entry>(anonymous)</entry>
</row>
<row>
<entry></entry>
<entry>__u32</entry>
<entry><structfield>addr</structfield></entry>
<entry>Match a chip by this number, interpreted according
to the <structfield>type</structfield> field.</entry>
</row>
<row>
<entry></entry>
<entry>char</entry>
<entry><structfield>name[32]</structfield></entry>
<entry>Match a chip by this name, interpreted according
to the <structfield>type</structfield> field.</entry>
</row>
</tbody>
</tgroup>
</table>
<table pgwide="1" frame="none" id="v4l2-dbg-chip-ident">
<title>struct <structname>v4l2_dbg_chip_ident</structname></title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>struct v4l2_dbg_match</entry>
<entry><structfield>match</structfield></entry>
<entry>How to match the chip, see <xref linkend="ident-v4l2-dbg-match" />.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>ident</structfield></entry>
<entry>A chip identifier as defined in the Linux
<filename>media/v4l2-chip-ident.h</filename> header file, or one of
the values from <xref linkend="chip-ids" />.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>revision</structfield></entry>
<entry>A chip revision, chip and driver specific.</entry>
</row>
</tbody>
</tgroup>
</table>
<!-- Note for convenience vidioc-dbg-g-register.sgml
contains a duplicate of this table. -->
<table pgwide="1" frame="none" id="ident-chip-match-types">
<title>Chip Match Types</title>
<tgroup cols="3">
&cs-def;
<tbody valign="top">
<row>
<entry><constant>V4L2_CHIP_MATCH_HOST</constant></entry>
<entry>0</entry>
<entry>Match the nth chip on the card, zero for the
host chip. Does not match &i2c; chips.</entry>
</row>
<row>
<entry><constant>V4L2_CHIP_MATCH_I2C_DRIVER</constant></entry>
<entry>1</entry>
<entry>Match an &i2c; chip by its driver name.</entry>
</row>
<row>
<entry><constant>V4L2_CHIP_MATCH_I2C_ADDR</constant></entry>
<entry>2</entry>
<entry>Match a chip by its 7 bit &i2c; bus address.</entry>
</row>
<row>
<entry><constant>V4L2_CHIP_MATCH_AC97</constant></entry>
<entry>3</entry>
<entry>Match the nth anciliary AC97 chip.</entry>
</row>
</tbody>
</tgroup>
</table>
<!-- This is an anonymous enum in media/v4l2-chip-ident.h. -->
<table pgwide="1" frame="none" id="chip-ids">
<title>Chip Identifiers</title>
<tgroup cols="3">
&cs-def;
<tbody valign="top">
<row>
<entry><constant>V4L2_IDENT_NONE</constant></entry>
<entry>0</entry>
<entry>No chip matched.</entry>
</row>
<row>
<entry><constant>V4L2_IDENT_AMBIGUOUS</constant></entry>
<entry>1</entry>
<entry>Multiple chips matched.</entry>
</row>
<row>
<entry><constant>V4L2_IDENT_UNKNOWN</constant></entry>
<entry>2</entry>
<entry>A chip is present at this address, but the driver
could not identify it.</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1>
&return-value;
<variablelist>
<varlistentry>
<term><errorcode>EINVAL</errorcode></term>
<listitem>
<para>The <structfield>match_type</structfield> is invalid.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/vidioc-dbg-g-register.xml
+258
View File
@@ -0,0 +1,258 @@
<refentry id="vidioc-dbg-g-register">
<refmeta>
<refentrytitle>ioctl VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>VIDIOC_DBG_G_REGISTER</refname>
<refname>VIDIOC_DBG_S_REGISTER</refname>
<refpurpose>Read or write hardware registers</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ioctl</function></funcdef>
<paramdef>int <parameter>fd</parameter></paramdef>
<paramdef>int <parameter>request</parameter></paramdef>
<paramdef>struct v4l2_dbg_register *<parameter>argp</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ioctl</function></funcdef>
<paramdef>int <parameter>fd</parameter></paramdef>
<paramdef>int <parameter>request</parameter></paramdef>
<paramdef>const struct v4l2_dbg_register
*<parameter>argp</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>fd</parameter></term>
<listitem>
<para>&fd;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>request</parameter></term>
<listitem>
<para>VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>argp</parameter></term>
<listitem>
<para></para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<note>
<title>Experimental</title>
<para>This is an <link linkend="experimental">experimental</link>
interface and may change in the future.</para>
</note>
<para>For driver debugging purposes these ioctls allow test
applications to access hardware registers directly. Regular
applications must not use them.</para>
<para>Since writing or even reading registers can jeopardize the
system security, its stability and damage the hardware, both ioctls
require superuser privileges. Additionally the Linux kernel must be
compiled with the <constant>CONFIG_VIDEO_ADV_DEBUG</constant> option
to enable these ioctls.</para>
<para>To write a register applications must initialize all fields
of a &v4l2-dbg-register; and call
<constant>VIDIOC_DBG_S_REGISTER</constant> with a pointer to this
structure. The <structfield>match.type</structfield> and
<structfield>match.addr</structfield> or <structfield>match.name</structfield>
fields select a chip on the TV
card, the <structfield>reg</structfield> field specifies a register
number and the <structfield>val</structfield> field the value to be
written into the register.</para>
<para>To read a register applications must initialize the
<structfield>match.type</structfield>,
<structfield>match.chip</structfield> or <structfield>match.name</structfield> and
<structfield>reg</structfield> fields, and call
<constant>VIDIOC_DBG_G_REGISTER</constant> with a pointer to this
structure. On success the driver stores the register value in the
<structfield>val</structfield> field. On failure the structure remains
unchanged.</para>
<para>When <structfield>match.type</structfield> is
<constant>V4L2_CHIP_MATCH_HOST</constant>,
<structfield>match.addr</structfield> selects the nth non-&i2c; chip
on the TV card. The number zero always selects the host chip, &eg; the
chip connected to the PCI or USB bus. You can find out which chips are
present with the &VIDIOC-DBG-G-CHIP-IDENT; ioctl.</para>
<para>When <structfield>match.type</structfield> is
<constant>V4L2_CHIP_MATCH_I2C_DRIVER</constant>,
<structfield>match.name</structfield> contains the I2C driver name.
For instance
<constant>"saa7127"</constant> will match any chip
supported by the saa7127 driver, regardless of its &i2c; bus address.
When multiple chips supported by the same driver are present, the
effect of these ioctls is undefined. Again with the
&VIDIOC-DBG-G-CHIP-IDENT; ioctl you can find out which &i2c; chips are
present.</para>
<para>When <structfield>match.type</structfield> is
<constant>V4L2_CHIP_MATCH_I2C_ADDR</constant>,
<structfield>match.addr</structfield> selects a chip by its 7 bit &i2c;
bus address.</para>
<para>When <structfield>match.type</structfield> is
<constant>V4L2_CHIP_MATCH_AC97</constant>,
<structfield>match.addr</structfield> selects the nth AC97 chip
on the TV card.</para>
<note>
<title>Success not guaranteed</title>
<para>Due to a flaw in the Linux &i2c; bus driver these ioctls may
return successfully without actually reading or writing a register. To
catch the most likely failure we recommend a &VIDIOC-DBG-G-CHIP-IDENT;
call confirming the presence of the selected &i2c; chip.</para>
</note>
<para>These ioctls are optional, not all drivers may support them.
However when a driver supports these ioctls it must also support
&VIDIOC-DBG-G-CHIP-IDENT;. Conversely it may support
<constant>VIDIOC_DBG_G_CHIP_IDENT</constant> but not these ioctls.</para>
<para><constant>VIDIOC_DBG_G_REGISTER</constant> and
<constant>VIDIOC_DBG_S_REGISTER</constant> were introduced in Linux
2.6.21, but their API was changed to the one described here in kernel 2.6.29.</para>
<para>We recommended the <application>v4l2-dbg</application>
utility over calling these ioctls directly. It is available from the
LinuxTV v4l-dvb repository; see <ulink
url="http://linuxtv.org/repo/">http://linuxtv.org/repo/</ulink> for
access instructions.</para>
<!-- Note for convenience vidioc-dbg-g-chip-ident.sgml
contains a duplicate of this table. -->
<table pgwide="1" frame="none" id="v4l2-dbg-match">
<title>struct <structname>v4l2_dbg_match</structname></title>
<tgroup cols="4">
&cs-ustr;
<tbody valign="top">
<row>
<entry>__u32</entry>
<entry><structfield>type</structfield></entry>
<entry>See <xref linkend="ident-chip-match-types" /> for a list of
possible types.</entry>
</row>
<row>
<entry>union</entry>
<entry>(anonymous)</entry>
</row>
<row>
<entry></entry>
<entry>__u32</entry>
<entry><structfield>addr</structfield></entry>
<entry>Match a chip by this number, interpreted according
to the <structfield>type</structfield> field.</entry>
</row>
<row>
<entry></entry>
<entry>char</entry>
<entry><structfield>name[32]</structfield></entry>
<entry>Match a chip by this name, interpreted according
to the <structfield>type</structfield> field.</entry>
</row>
</tbody>
</tgroup>
</table>
<table pgwide="1" frame="none" id="v4l2-dbg-register">
<title>struct <structname>v4l2_dbg_register</structname></title>
<tgroup cols="4">
<colspec colname="c1" />
<colspec colname="c2" />
<colspec colname="c4" />
<tbody valign="top">
<row>
<entry>struct v4l2_dbg_match</entry>
<entry><structfield>match</structfield></entry>
<entry>How to match the chip, see <xref linkend="v4l2-dbg-match" />.</entry>
</row>
<row>
<entry>__u64</entry>
<entry><structfield>reg</structfield></entry>
<entry>A register number.</entry>
</row>
<row>
<entry>__u64</entry>
<entry><structfield>val</structfield></entry>
<entry>The value read from, or to be written into the
register.</entry>
</row>
</tbody>
</tgroup>
</table>
<!-- Note for convenience vidioc-dbg-g-chip-ident.sgml
contains a duplicate of this table. -->
<table pgwide="1" frame="none" id="chip-match-types">
<title>Chip Match Types</title>
<tgroup cols="3">
&cs-def;
<tbody valign="top">
<row>
<entry><constant>V4L2_CHIP_MATCH_HOST</constant></entry>
<entry>0</entry>
<entry>Match the nth chip on the card, zero for the
host chip. Does not match &i2c; chips.</entry>
</row>
<row>
<entry><constant>V4L2_CHIP_MATCH_I2C_DRIVER</constant></entry>
<entry>1</entry>
<entry>Match an &i2c; chip by its driver name.</entry>
</row>
<row>
<entry><constant>V4L2_CHIP_MATCH_I2C_ADDR</constant></entry>
<entry>2</entry>
<entry>Match a chip by its 7 bit &i2c; bus address.</entry>
</row>
<row>
<entry><constant>V4L2_CHIP_MATCH_AC97</constant></entry>
<entry>3</entry>
<entry>Match the nth anciliary AC97 chip.</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1>
&return-value;
<variablelist>
<varlistentry>
<term><errorcode>EPERM</errorcode></term>
<listitem>
<para>Insufficient permissions. Root privileges are required
to execute these ioctls.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/vidioc-decoder-cmd.xml
+256
View File
@@ -0,0 +1,256 @@
<refentry id="vidioc-decoder-cmd">
<refmeta>
<refentrytitle>ioctl VIDIOC_DECODER_CMD, VIDIOC_TRY_DECODER_CMD</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>VIDIOC_DECODER_CMD</refname>
<refname>VIDIOC_TRY_DECODER_CMD</refname>
<refpurpose>Execute an decoder command</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ioctl</function></funcdef>
<paramdef>int <parameter>fd</parameter></paramdef>
<paramdef>int <parameter>request</parameter></paramdef>
<paramdef>struct v4l2_decoder_cmd *<parameter>argp</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>fd</parameter></term>
<listitem>
<para>&fd;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>request</parameter></term>
<listitem>
<para>VIDIOC_DECODER_CMD, VIDIOC_TRY_DECODER_CMD</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>argp</parameter></term>
<listitem>
<para></para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<note>
<title>Experimental</title>
<para>This is an <link linkend="experimental">experimental</link>
interface and may change in the future.</para>
</note>
<para>These ioctls control an audio/video (usually MPEG-) decoder.
<constant>VIDIOC_DECODER_CMD</constant> sends a command to the
decoder, <constant>VIDIOC_TRY_DECODER_CMD</constant> can be used to
try a command without actually executing it. To send a command applications
must initialize all fields of a &v4l2-decoder-cmd; and call
<constant>VIDIOC_DECODER_CMD</constant> or <constant>VIDIOC_TRY_DECODER_CMD</constant>
with a pointer to this structure.</para>
<para>The <structfield>cmd</structfield> field must contain the
command code. Some commands use the <structfield>flags</structfield> field for
additional information.
</para>
<para>A <function>write</function>() or &VIDIOC-STREAMON; call sends an implicit
START command to the decoder if it has not been started yet.
</para>
<para>A <function>close</function>() or &VIDIOC-STREAMOFF; call of a streaming
file descriptor sends an implicit immediate STOP command to the decoder, and all
buffered data is discarded.</para>
<para>These ioctls are optional, not all drivers may support
them. They were introduced in Linux 3.3.</para>
<table pgwide="1" frame="none" id="v4l2-decoder-cmd">
<title>struct <structname>v4l2_decoder_cmd</structname></title>
<tgroup cols="5">
&cs-str;
<tbody valign="top">
<row>
<entry>__u32</entry>
<entry><structfield>cmd</structfield></entry>
<entry></entry>
<entry></entry>
<entry>The decoder command, see <xref linkend="decoder-cmds" />.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>flags</structfield></entry>
<entry></entry>
<entry></entry>
<entry>Flags to go with the command. If no flags are defined for
this command, drivers and applications must set this field to zero.</entry>
</row>
<row>
<entry>union</entry>
<entry>(anonymous)</entry>
<entry></entry>
<entry></entry>
<entry></entry>
</row>
<row>
<entry></entry>
<entry>struct</entry>
<entry><structfield>start</structfield></entry>
<entry></entry>
<entry>Structure containing additional data for the
<constant>V4L2_DEC_CMD_START</constant> command.</entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry>__s32</entry>
<entry><structfield>speed</structfield></entry>
<entry>Playback speed and direction. The playback speed is defined as
<structfield>speed</structfield>/1000 of the normal speed. So 1000 is normal playback.
Negative numbers denote reverse playback, so -1000 does reverse playback at normal
speed. Speeds -1, 0 and 1 have special meanings: speed 0 is shorthand for 1000
(normal playback). A speed of 1 steps just one frame forward, a speed of -1 steps
just one frame back.
</entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry>__u32</entry>
<entry><structfield>format</structfield></entry>
<entry>Format restrictions. This field is set by the driver, not the
application. Possible values are <constant>V4L2_DEC_START_FMT_NONE</constant> if
there are no format restrictions or <constant>V4L2_DEC_START_FMT_GOP</constant>
if the decoder operates on full GOPs (<wordasword>Group Of Pictures</wordasword>).
This is usually the case for reverse playback: the decoder needs full GOPs, which
it can then play in reverse order. So to implement reverse playback the application
must feed the decoder the last GOP in the video file, then the GOP before that, etc. etc.
</entry>
</row>
<row>
<entry></entry>
<entry>struct</entry>
<entry><structfield>stop</structfield></entry>
<entry></entry>
<entry>Structure containing additional data for the
<constant>V4L2_DEC_CMD_STOP</constant> command.</entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry>__u64</entry>
<entry><structfield>pts</structfield></entry>
<entry>Stop playback at this <structfield>pts</structfield> or immediately
if the playback is already past that timestamp. Leave to 0 if you want to stop after the
last frame was decoded.
</entry>
</row>
<row>
<entry></entry>
<entry>struct</entry>
<entry><structfield>raw</structfield></entry>
<entry></entry>
<entry></entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry>__u32</entry>
<entry><structfield>data</structfield>[16]</entry>
<entry>Reserved for future extensions. Drivers and
applications must set the array to zero.</entry>
</row>
</tbody>
</tgroup>
</table>
<table pgwide="1" frame="none" id="decoder-cmds">
<title>Decoder Commands</title>
<tgroup cols="3">
&cs-def;
<tbody valign="top">
<row>
<entry><constant>V4L2_DEC_CMD_START</constant></entry>
<entry>0</entry>
<entry>Start the decoder. When the decoder is already
running or paused, this command will just change the playback speed.
That means that calling <constant>V4L2_DEC_CMD_START</constant> when
the decoder was paused will <emphasis>not</emphasis> resume the decoder.
You have to explicitly call <constant>V4L2_DEC_CMD_RESUME</constant> for that.
This command has one flag:
<constant>V4L2_DEC_CMD_START_MUTE_AUDIO</constant>. If set, then audio will
be muted when playing back at a non-standard speed.
</entry>
</row>
<row>
<entry><constant>V4L2_DEC_CMD_STOP</constant></entry>
<entry>1</entry>
<entry>Stop the decoder. When the decoder is already stopped,
this command does nothing. This command has two flags:
if <constant>V4L2_DEC_CMD_STOP_TO_BLACK</constant> is set, then the decoder will
set the picture to black after it stopped decoding. Otherwise the last image will
repeat. If <constant>V4L2_DEC_CMD_STOP_IMMEDIATELY</constant> is set, then the decoder
stops immediately (ignoring the <structfield>pts</structfield> value), otherwise it
will keep decoding until timestamp >= pts or until the last of the pending data from
its internal buffers was decoded.
</entry>
</row>
<row>
<entry><constant>V4L2_DEC_CMD_PAUSE</constant></entry>
<entry>2</entry>
<entry>Pause the decoder. When the decoder has not been
started yet, the driver will return an &EPERM;. When the decoder is
already paused, this command does nothing. This command has one flag:
if <constant>V4L2_DEC_CMD_PAUSE_TO_BLACK</constant> is set, then set the
decoder output to black when paused.
</entry>
</row>
<row>
<entry><constant>V4L2_DEC_CMD_RESUME</constant></entry>
<entry>3</entry>
<entry>Resume decoding after a PAUSE command. When the
decoder has not been started yet, the driver will return an &EPERM;.
When the decoder is already running, this command does nothing. No
flags are defined for this command.</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1>
&return-value;
<variablelist>
<varlistentry>
<term><errorcode>EINVAL</errorcode></term>
<listitem>
<para>The <structfield>cmd</structfield> field is invalid.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EPERM</errorcode></term>
<listitem>
<para>The application sent a PAUSE or RESUME command when
the decoder was not running.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/vidioc-dqevent.xml
+271
View File
@@ -0,0 +1,271 @@
<refentry id="vidioc-dqevent">
<refmeta>
<refentrytitle>ioctl VIDIOC_DQEVENT</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>VIDIOC_DQEVENT</refname>
<refpurpose>Dequeue event</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ioctl</function></funcdef>
<paramdef>int <parameter>fd</parameter></paramdef>
<paramdef>int <parameter>request</parameter></paramdef>
<paramdef>struct v4l2_event
*<parameter>argp</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>fd</parameter></term>
<listitem>
<para>&fd;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>request</parameter></term>
<listitem>
<para>VIDIOC_DQEVENT</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>argp</parameter></term>
<listitem>
<para></para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>Dequeue an event from a video device. No input is required
for this ioctl. All the fields of the &v4l2-event; structure are
filled by the driver. The file handle will also receive exceptions
which the application may get by e.g. using the select system
call.</para>
<table frame="none" pgwide="1" id="v4l2-event">
<title>struct <structname>v4l2_event</structname></title>
<tgroup cols="4">
&cs-str;
<tbody valign="top">
<row>
<entry>__u32</entry>
<entry><structfield>type</structfield></entry>
<entry></entry>
<entry>Type of the event.</entry>
</row>
<row>
<entry>union</entry>
<entry><structfield>u</structfield></entry>
<entry></entry>
<entry></entry>
</row>
<row>
<entry></entry>
<entry>&v4l2-event-vsync;</entry>
<entry><structfield>vsync</structfield></entry>
<entry>Event data for event V4L2_EVENT_VSYNC.
</entry>
</row>
<row>
<entry></entry>
<entry>&v4l2-event-ctrl;</entry>
<entry><structfield>ctrl</structfield></entry>
<entry>Event data for event V4L2_EVENT_CTRL.
</entry>
</row>
<row>
<entry></entry>
<entry>&v4l2-event-frame-sync;</entry>
<entry><structfield>frame</structfield></entry>
<entry>Event data for event V4L2_EVENT_FRAME_SYNC.</entry>
</row>
<row>
<entry></entry>
<entry>__u8</entry>
<entry><structfield>data</structfield>[64]</entry>
<entry>Event data. Defined by the event type. The union
should be used to define easily accessible type for
events.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>pending</structfield></entry>
<entry></entry>
<entry>Number of pending events excluding this one.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>sequence</structfield></entry>
<entry></entry>
<entry>Event sequence number. The sequence number is
incremented for every subscribed event that takes place.
If sequence numbers are not contiguous it means that
events have been lost.
</entry>
</row>
<row>
<entry>struct timespec</entry>
<entry><structfield>timestamp</structfield></entry>
<entry></entry>
<entry>Event timestamp.</entry>
</row>
<row>
<entry>u32</entry>
<entry><structfield>id</structfield></entry>
<entry></entry>
<entry>The ID associated with the event source. If the event does not
have an associated ID (this depends on the event type), then this
is 0.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>reserved</structfield>[8]</entry>
<entry></entry>
<entry>Reserved for future extensions. Drivers must set
the array to zero.</entry>
</row>
</tbody>
</tgroup>
</table>
<table frame="none" pgwide="1" id="v4l2-event-vsync">
<title>struct <structname>v4l2_event_vsync</structname></title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>__u8</entry>
<entry><structfield>field</structfield></entry>
<entry>The upcoming field. See &v4l2-field;.</entry>
</row>
</tbody>
</tgroup>
</table>
<table frame="none" pgwide="1" id="v4l2-event-ctrl">
<title>struct <structname>v4l2_event_ctrl</structname></title>
<tgroup cols="4">
&cs-str;
<tbody valign="top">
<row>
<entry>__u32</entry>
<entry><structfield>changes</structfield></entry>
<entry></entry>
<entry>A bitmask that tells what has changed. See <xref linkend="changes-flags" />.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>type</structfield></entry>
<entry></entry>
<entry>The type of the control. See &v4l2-ctrl-type;.</entry>
</row>
<row>
<entry>union (anonymous)</entry>
<entry></entry>
<entry></entry>
<entry></entry>
</row>
<row>
<entry></entry>
<entry>__s32</entry>
<entry><structfield>value</structfield></entry>
<entry>The 32-bit value of the control for 32-bit control types.
This is 0 for string controls since the value of a string
cannot be passed using &VIDIOC-DQEVENT;.</entry>
</row>
<row>
<entry></entry>
<entry>__s64</entry>
<entry><structfield>value64</structfield></entry>
<entry>The 64-bit value of the control for 64-bit control types.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>flags</structfield></entry>
<entry></entry>
<entry>The control flags. See <xref linkend="control-flags" />.</entry>
</row>
<row>
<entry>__s32</entry>
<entry><structfield>minimum</structfield></entry>
<entry></entry>
<entry>The minimum value of the control. See &v4l2-queryctrl;.</entry>
</row>
<row>
<entry>__s32</entry>
<entry><structfield>maximum</structfield></entry>
<entry></entry>
<entry>The maximum value of the control. See &v4l2-queryctrl;.</entry>
</row>
<row>
<entry>__s32</entry>
<entry><structfield>step</structfield></entry>
<entry></entry>
<entry>The step value of the control. See &v4l2-queryctrl;.</entry>
</row>
<row>
<entry>__s32</entry>
<entry><structfield>default_value</structfield></entry>
<entry></entry>
<entry>The default value value of the control. See &v4l2-queryctrl;.</entry>
</row>
</tbody>
</tgroup>
</table>
<table frame="none" pgwide="1" id="v4l2-event-frame-sync">
<title>struct <structname>v4l2_event_frame_sync</structname></title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>__u32</entry>
<entry><structfield>frame_sequence</structfield></entry>
<entry>
The sequence number of the frame being received.
</entry>
</row>
</tbody>
</tgroup>
</table>
<table pgwide="1" frame="none" id="changes-flags">
<title>Changes</title>
<tgroup cols="3">
&cs-def;
<tbody valign="top">
<row>
<entry><constant>V4L2_EVENT_CTRL_CH_VALUE</constant></entry>
<entry>0x0001</entry>
<entry>This control event was triggered because the value of the control
changed. Special case: if a button control is pressed, then this
event is sent as well, even though there is not explicit value
associated with a button control.</entry>
</row>
<row>
<entry><constant>V4L2_EVENT_CTRL_CH_FLAGS</constant></entry>
<entry>0x0002</entry>
<entry>This control event was triggered because the control flags
changed.</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1>
&return-value;
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/vidioc-encoder-cmd.xml
+196
View File
@@ -0,0 +1,196 @@
<refentry id="vidioc-encoder-cmd">
<refmeta>
<refentrytitle>ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>VIDIOC_ENCODER_CMD</refname>
<refname>VIDIOC_TRY_ENCODER_CMD</refname>
<refpurpose>Execute an encoder command</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ioctl</function></funcdef>
<paramdef>int <parameter>fd</parameter></paramdef>
<paramdef>int <parameter>request</parameter></paramdef>
<paramdef>struct v4l2_encoder_cmd *<parameter>argp</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>fd</parameter></term>
<listitem>
<para>&fd;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>request</parameter></term>
<listitem>
<para>VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>argp</parameter></term>
<listitem>
<para></para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<note>
<title>Experimental</title>
<para>This is an <link linkend="experimental">experimental</link>
interface and may change in the future.</para>
</note>
<para>These ioctls control an audio/video (usually MPEG-) encoder.
<constant>VIDIOC_ENCODER_CMD</constant> sends a command to the
encoder, <constant>VIDIOC_TRY_ENCODER_CMD</constant> can be used to
try a command without actually executing it.</para>
<para>To send a command applications must initialize all fields of a
&v4l2-encoder-cmd; and call
<constant>VIDIOC_ENCODER_CMD</constant> or
<constant>VIDIOC_TRY_ENCODER_CMD</constant> with a pointer to this
structure.</para>
<para>The <structfield>cmd</structfield> field must contain the
command code. The <structfield>flags</structfield> field is currently
only used by the STOP command and contains one bit: If the
<constant>V4L2_ENC_CMD_STOP_AT_GOP_END</constant> flag is set,
encoding will continue until the end of the current <wordasword>Group
Of Pictures</wordasword>, otherwise it will stop immediately.</para>
<para>A <function>read</function>() or &VIDIOC-STREAMON; call sends an implicit
START command to the encoder if it has not been started yet. After a STOP command,
<function>read</function>() calls will read the remaining data
buffered by the driver. When the buffer is empty,
<function>read</function>() will return zero and the next
<function>read</function>() call will restart the encoder.</para>
<para>A <function>close</function>() or &VIDIOC-STREAMOFF; call of a streaming
file descriptor sends an implicit immediate STOP to the encoder, and all buffered
data is discarded.</para>
<para>These ioctls are optional, not all drivers may support
them. They were introduced in Linux 2.6.21.</para>
<table pgwide="1" frame="none" id="v4l2-encoder-cmd">
<title>struct <structname>v4l2_encoder_cmd</structname></title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>__u32</entry>
<entry><structfield>cmd</structfield></entry>
<entry>The encoder command, see <xref linkend="encoder-cmds" />.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>flags</structfield></entry>
<entry>Flags to go with the command, see <xref
linkend="encoder-flags" />. If no flags are defined for
this command, drivers and applications must set this field to
zero.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>data</structfield>[8]</entry>
<entry>Reserved for future extensions. Drivers and
applications must set the array to zero.</entry>
</row>
</tbody>
</tgroup>
</table>
<table pgwide="1" frame="none" id="encoder-cmds">
<title>Encoder Commands</title>
<tgroup cols="3">
&cs-def;
<tbody valign="top">
<row>
<entry><constant>V4L2_ENC_CMD_START</constant></entry>
<entry>0</entry>
<entry>Start the encoder. When the encoder is already
running or paused, this command does nothing. No flags are defined for
this command.</entry>
</row>
<row>
<entry><constant>V4L2_ENC_CMD_STOP</constant></entry>
<entry>1</entry>
<entry>Stop the encoder. When the
<constant>V4L2_ENC_CMD_STOP_AT_GOP_END</constant> flag is set,
encoding will continue until the end of the current <wordasword>Group
Of Pictures</wordasword>, otherwise encoding will stop immediately.
When the encoder is already stopped, this command does
nothing.</entry>
</row>
<row>
<entry><constant>V4L2_ENC_CMD_PAUSE</constant></entry>
<entry>2</entry>
<entry>Pause the encoder. When the encoder has not been
started yet, the driver will return an &EPERM;. When the encoder is
already paused, this command does nothing. No flags are defined for
this command.</entry>
</row>
<row>
<entry><constant>V4L2_ENC_CMD_RESUME</constant></entry>
<entry>3</entry>
<entry>Resume encoding after a PAUSE command. When the
encoder has not been started yet, the driver will return an &EPERM;.
When the encoder is already running, this command does nothing. No
flags are defined for this command.</entry>
</row>
</tbody>
</tgroup>
</table>
<table pgwide="1" frame="none" id="encoder-flags">
<title>Encoder Command Flags</title>
<tgroup cols="3">
&cs-def;
<tbody valign="top">
<row>
<entry><constant>V4L2_ENC_CMD_STOP_AT_GOP_END</constant></entry>
<entry>0x0001</entry>
<entry>Stop encoding at the end of the current <wordasword>Group Of
Pictures</wordasword>, rather than immediately.</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1>
&return-value;
<variablelist>
<varlistentry>
<term><errorcode>EINVAL</errorcode></term>
<listitem>
<para>The <structfield>cmd</structfield> field is invalid.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EPERM</errorcode></term>
<listitem>
<para>The application sent a PAUSE or RESUME command when
the encoder was not running.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/vidioc-enum-dv-presets.xml
+230
View File
@@ -0,0 +1,230 @@
<refentry id="vidioc-enum-dv-presets">
<refmeta>
<refentrytitle>ioctl VIDIOC_ENUM_DV_PRESETS</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>VIDIOC_ENUM_DV_PRESETS</refname>
<refpurpose>Enumerate supported Digital Video presets</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ioctl</function></funcdef>
<paramdef>int <parameter>fd</parameter></paramdef>
<paramdef>int <parameter>request</parameter></paramdef>
<paramdef>struct v4l2_dv_enum_preset *<parameter>argp</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>fd</parameter></term>
<listitem>
<para>&fd;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>request</parameter></term>
<listitem>
<para>VIDIOC_ENUM_DV_PRESETS</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>argp</parameter></term>
<listitem>
<para></para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>To query the attributes of a DV preset, applications initialize the
<structfield>index</structfield> field and zero the reserved array of &v4l2-dv-enum-preset;
and call the <constant>VIDIOC_ENUM_DV_PRESETS</constant> ioctl with a pointer to this
structure. Drivers fill the rest of the structure or return an
&EINVAL; when the index is out of bounds. To enumerate all DV Presets supported,
applications shall begin at index zero, incrementing by one until the
driver returns <errorcode>EINVAL</errorcode>. Drivers may enumerate a
different set of DV presets after switching the video input or
output.</para>
<table pgwide="1" frame="none" id="v4l2-dv-enum-preset">
<title>struct <structname>v4l2_dv_enum_presets</structname></title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>__u32</entry>
<entry><structfield>index</structfield></entry>
<entry>Number of the DV preset, set by the
application.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>preset</structfield></entry>
<entry>This field identifies one of the DV preset values listed in <xref linkend="v4l2-dv-presets-vals"/>.</entry>
</row>
<row>
<entry>__u8</entry>
<entry><structfield>name</structfield>[24]</entry>
<entry>Name of the preset, a NUL-terminated ASCII string, for example: "720P-60", "1080I-60". This information is
intended for the user.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>width</structfield></entry>
<entry>Width of the active video in pixels for the DV preset.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>height</structfield></entry>
<entry>Height of the active video in lines for the DV preset.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>reserved</structfield>[4]</entry>
<entry>Reserved for future extensions. Drivers must set the array to zero.</entry>
</row>
</tbody>
</tgroup>
</table>
<table pgwide="1" frame="none" id="v4l2-dv-presets-vals">
<title>struct <structname>DV Presets</structname></title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>Preset</entry>
<entry>Preset value</entry>
<entry>Description</entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry></entry>
</row>
<row>
<entry>V4L2_DV_INVALID</entry>
<entry>0</entry>
<entry>Invalid preset value.</entry>
</row>
<row>
<entry>V4L2_DV_480P59_94</entry>
<entry>1</entry>
<entry>720x480 progressive video at 59.94 fps as per BT.1362.</entry>
</row>
<row>
<entry>V4L2_DV_576P50</entry>
<entry>2</entry>
<entry>720x576 progressive video at 50 fps as per BT.1362.</entry>
</row>
<row>
<entry>V4L2_DV_720P24</entry>
<entry>3</entry>
<entry>1280x720 progressive video at 24 fps as per SMPTE 296M.</entry>
</row>
<row>
<entry>V4L2_DV_720P25</entry>
<entry>4</entry>
<entry>1280x720 progressive video at 25 fps as per SMPTE 296M.</entry>
</row>
<row>
<entry>V4L2_DV_720P30</entry>
<entry>5</entry>
<entry>1280x720 progressive video at 30 fps as per SMPTE 296M.</entry>
</row>
<row>
<entry>V4L2_DV_720P50</entry>
<entry>6</entry>
<entry>1280x720 progressive video at 50 fps as per SMPTE 296M.</entry>
</row>
<row>
<entry>V4L2_DV_720P59_94</entry>
<entry>7</entry>
<entry>1280x720 progressive video at 59.94 fps as per SMPTE 274M.</entry>
</row>
<row>
<entry>V4L2_DV_720P60</entry>
<entry>8</entry>
<entry>1280x720 progressive video at 60 fps as per SMPTE 274M/296M.</entry>
</row>
<row>
<entry>V4L2_DV_1080I29_97</entry>
<entry>9</entry>
<entry>1920x1080 interlaced video at 29.97 fps as per BT.1120/SMPTE 274M.</entry>
</row>
<row>
<entry>V4L2_DV_1080I30</entry>
<entry>10</entry>
<entry>1920x1080 interlaced video at 30 fps as per BT.1120/SMPTE 274M.</entry>
</row>
<row>
<entry>V4L2_DV_1080I25</entry>
<entry>11</entry>
<entry>1920x1080 interlaced video at 25 fps as per BT.1120.</entry>
</row>
<row>
<entry>V4L2_DV_1080I50</entry>
<entry>12</entry>
<entry>1920x1080 interlaced video at 50 fps as per SMPTE 296M.</entry>
</row>
<row>
<entry>V4L2_DV_1080I60</entry>
<entry>13</entry>
<entry>1920x1080 interlaced video at 60 fps as per SMPTE 296M.</entry>
</row>
<row>
<entry>V4L2_DV_1080P24</entry>
<entry>14</entry>
<entry>1920x1080 progressive video at 24 fps as per SMPTE 296M.</entry>
</row>
<row>
<entry>V4L2_DV_1080P25</entry>
<entry>15</entry>
<entry>1920x1080 progressive video at 25 fps as per SMPTE 296M.</entry>
</row>
<row>
<entry>V4L2_DV_1080P30</entry>
<entry>16</entry>
<entry>1920x1080 progressive video at 30 fps as per SMPTE 296M.</entry>
</row>
<row>
<entry>V4L2_DV_1080P50</entry>
<entry>17</entry>
<entry>1920x1080 progressive video at 50 fps as per BT.1120.</entry>
</row>
<row>
<entry>V4L2_DV_1080P60</entry>
<entry>18</entry>
<entry>1920x1080 progressive video at 60 fps as per BT.1120.</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1>
&return-value;
<variablelist>
<varlistentry>
<term><errorcode>EINVAL</errorcode></term>
<listitem>
<para>The &v4l2-dv-enum-preset; <structfield>index</structfield>
is out of bounds.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/vidioc-enum-fmt.xml
+158
View File
@@ -0,0 +1,158 @@
<refentry id="vidioc-enum-fmt">
<refmeta>
<refentrytitle>ioctl VIDIOC_ENUM_FMT</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>VIDIOC_ENUM_FMT</refname>
<refpurpose>Enumerate image formats</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ioctl</function></funcdef>
<paramdef>int <parameter>fd</parameter></paramdef>
<paramdef>int <parameter>request</parameter></paramdef>
<paramdef>struct v4l2_fmtdesc
*<parameter>argp</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>fd</parameter></term>
<listitem>
<para>&fd;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>request</parameter></term>
<listitem>
<para>VIDIOC_ENUM_FMT</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>argp</parameter></term>
<listitem>
<para></para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>To enumerate image formats applications initialize the
<structfield>type</structfield> and <structfield>index</structfield>
field of &v4l2-fmtdesc; and call the
<constant>VIDIOC_ENUM_FMT</constant> ioctl with a pointer to this
structure. Drivers fill the rest of the structure or return an
&EINVAL;. All formats are enumerable by beginning at index zero and
incrementing by one until <errorcode>EINVAL</errorcode> is
returned.</para>
<table pgwide="1" frame="none" id="v4l2-fmtdesc">
<title>struct <structname>v4l2_fmtdesc</structname></title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>__u32</entry>
<entry><structfield>index</structfield></entry>
<entry>Number of the format in the enumeration, set by
the application. This is in no way related to the <structfield>
pixelformat</structfield> field.</entry>
</row>
<row>
<entry>&v4l2-buf-type;</entry>
<entry><structfield>type</structfield></entry>
<entry>Type of the data stream, set by the application.
Only these types are valid here:
<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>,
<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant>,
<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>,
<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>,
<constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>, and custom (driver
defined) types with code <constant>V4L2_BUF_TYPE_PRIVATE</constant>
and higher.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>flags</structfield></entry>
<entry>See <xref linkend="fmtdesc-flags" /></entry>
</row>
<row>
<entry>__u8</entry>
<entry><structfield>description</structfield>[32]</entry>
<entry>Description of the format, a NUL-terminated ASCII
string. This information is intended for the user, for example: "YUV
4:2:2".</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>pixelformat</structfield></entry>
<entry>The image format identifier. This is a
four character code as computed by the v4l2_fourcc()
macro:</entry>
</row>
<row>
<entry spanname="hspan"><para><programlisting id="v4l2-fourcc">
#define v4l2_fourcc(a,b,c,d) (((__u32)(a)&lt;&lt;0)|((__u32)(b)&lt;&lt;8)|((__u32)(c)&lt;&lt;16)|((__u32)(d)&lt;&lt;24))
</programlisting></para><para>Several image formats are already
defined by this specification in <xref linkend="pixfmt" />. Note these
codes are not the same as those used in the Windows world.</para></entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>reserved</structfield>[4]</entry>
<entry>Reserved for future extensions. Drivers must set
the array to zero.</entry>
</row>
</tbody>
</tgroup>
</table>
<table pgwide="1" frame="none" id="fmtdesc-flags">
<title>Image Format Description Flags</title>
<tgroup cols="3">
&cs-def;
<tbody valign="top">
<row>
<entry><constant>V4L2_FMT_FLAG_COMPRESSED</constant></entry>
<entry>0x0001</entry>
<entry>This is a compressed format.</entry>
</row>
<row>
<entry><constant>V4L2_FMT_FLAG_EMULATED</constant></entry>
<entry>0x0002</entry>
<entry>This format is not native to the device but emulated
through software (usually libv4l2), where possible try to use a native format
instead for better performance.</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1>
&return-value;
<variablelist>
<varlistentry>
<term><errorcode>EINVAL</errorcode></term>
<listitem>
<para>The &v4l2-fmtdesc; <structfield>type</structfield>
is not supported or the <structfield>index</structfield> is out of
bounds.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/vidioc-enum-frameintervals.xml
+259
View File
@@ -0,0 +1,259 @@
<refentry id="vidioc-enum-frameintervals">
<refmeta>
<refentrytitle>ioctl VIDIOC_ENUM_FRAMEINTERVALS</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>VIDIOC_ENUM_FRAMEINTERVALS</refname>
<refpurpose>Enumerate frame intervals</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ioctl</function></funcdef>
<paramdef>int <parameter>fd</parameter></paramdef>
<paramdef>int <parameter>request</parameter></paramdef>
<paramdef>struct v4l2_frmivalenum *<parameter>argp</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>fd</parameter></term>
<listitem>
<para>&fd;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>request</parameter></term>
<listitem>
<para>VIDIOC_ENUM_FRAMEINTERVALS</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>argp</parameter></term>
<listitem>
<para>Pointer to a &v4l2-frmivalenum; structure that
contains a pixel format and size and receives a frame interval.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>This ioctl allows applications to enumerate all frame
intervals that the device supports for the given pixel format and
frame size.</para>
<para>The supported pixel formats and frame sizes can be obtained
by using the &VIDIOC-ENUM-FMT; and &VIDIOC-ENUM-FRAMESIZES;
functions.</para>
<para>The return value and the content of the
<structfield>v4l2_frmivalenum.type</structfield> field depend on the
type of frame intervals the device supports. Here are the semantics of
the function for the different cases:</para>
<itemizedlist>
<listitem>
<para><emphasis role="bold">Discrete:</emphasis> The function
returns success if the given index value (zero-based) is valid. The
application should increase the index by one for each call until
<constant>EINVAL</constant> is returned. The `v4l2_frmivalenum.type`
field is set to `V4L2_FRMIVAL_TYPE_DISCRETE` by the driver. Of the
union only the `discrete` member is valid.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Step-wise:</emphasis> The function
returns success if the given index value is zero and
<constant>EINVAL</constant> for any other index value. The
<structfield>v4l2_frmivalenum.type</structfield> field is set to
<constant>V4L2_FRMIVAL_TYPE_STEPWISE</constant> by the driver. Of the
union only the <structfield>stepwise</structfield> member is
valid.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Continuous:</emphasis> This is a
special case of the step-wise type above. The function returns success
if the given index value is zero and <constant>EINVAL</constant> for
any other index value. The
<structfield>v4l2_frmivalenum.type</structfield> field is set to
<constant>V4L2_FRMIVAL_TYPE_CONTINUOUS</constant> by the driver. Of
the union only the <structfield>stepwise</structfield> member is valid
and the <structfield>step</structfield> value is set to 1.</para>
</listitem>
</itemizedlist>
<para>When the application calls the function with index zero, it
must check the <structfield>type</structfield> field to determine the
type of frame interval enumeration the device supports. Only for the
<constant>V4L2_FRMIVAL_TYPE_DISCRETE</constant> type does it make
sense to increase the index value to receive more frame
intervals.</para>
<para>Note that the order in which the frame intervals are
returned has no special meaning. In particular does it not say
anything about potential default frame intervals.</para>
<para>Applications can assume that the enumeration data does not
change without any interaction from the application itself. This means
that the enumeration data is consistent if the application does not
perform any other ioctl calls while it runs the frame interval
enumeration.</para>
</refsect1>
<refsect1>
<title>Notes</title>
<itemizedlist>
<listitem>
<para><emphasis role="bold">Frame intervals and frame
rates:</emphasis> The V4L2 API uses frame intervals instead of frame
rates. Given the frame interval the frame rate can be computed as
follows:<screen>frame_rate = 1 / frame_interval</screen></para>
</listitem>
</itemizedlist>
</refsect1>
<refsect1>
<title>Structs</title>
<para>In the structs below, <emphasis>IN</emphasis> denotes a
value that has to be filled in by the application,
<emphasis>OUT</emphasis> denotes values that the driver fills in. The
application should zero out all members except for the
<emphasis>IN</emphasis> fields.</para>
<table pgwide="1" frame="none" id="v4l2-frmival-stepwise">
<title>struct <structname>v4l2_frmival_stepwise</structname></title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>&v4l2-fract;</entry>
<entry><structfield>min</structfield></entry>
<entry>Minimum frame interval [s].</entry>
</row>
<row>
<entry>&v4l2-fract;</entry>
<entry><structfield>max</structfield></entry>
<entry>Maximum frame interval [s].</entry>
</row>
<row>
<entry>&v4l2-fract;</entry>
<entry><structfield>step</structfield></entry>
<entry>Frame interval step size [s].</entry>
</row>
</tbody>
</tgroup>
</table>
<table pgwide="1" frame="none" id="v4l2-frmivalenum">
<title>struct <structname>v4l2_frmivalenum</structname></title>
<tgroup cols="4">
<colspec colname="c1" />
<colspec colname="c2" />
<colspec colname="c3" />
<colspec colname="c4" />
<tbody valign="top">
<row>
<entry>__u32</entry>
<entry><structfield>index</structfield></entry>
<entry></entry>
<entry>IN: Index of the given frame interval in the
enumeration.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>pixel_format</structfield></entry>
<entry></entry>
<entry>IN: Pixel format for which the frame intervals are
enumerated.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>width</structfield></entry>
<entry></entry>
<entry>IN: Frame width for which the frame intervals are
enumerated.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>height</structfield></entry>
<entry></entry>
<entry>IN: Frame height for which the frame intervals are
enumerated.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>type</structfield></entry>
<entry></entry>
<entry>OUT: Frame interval type the device supports.</entry>
</row>
<row>
<entry>union</entry>
<entry></entry>
<entry></entry>
<entry>OUT: Frame interval with the given index.</entry>
</row>
<row>
<entry></entry>
<entry>&v4l2-fract;</entry>
<entry><structfield>discrete</structfield></entry>
<entry>Frame interval [s].</entry>
</row>
<row>
<entry></entry>
<entry>&v4l2-frmival-stepwise;</entry>
<entry><structfield>stepwise</structfield></entry>
<entry></entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>reserved[2]</structfield></entry>
<entry></entry>
<entry>Reserved space for future use.</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1>
<title>Enums</title>
<table pgwide="1" frame="none" id="v4l2-frmivaltypes">
<title>enum <structname>v4l2_frmivaltypes</structname></title>
<tgroup cols="3">
&cs-def;
<tbody valign="top">
<row>
<entry><constant>V4L2_FRMIVAL_TYPE_DISCRETE</constant></entry>
<entry>1</entry>
<entry>Discrete frame interval.</entry>
</row>
<row>
<entry><constant>V4L2_FRMIVAL_TYPE_CONTINUOUS</constant></entry>
<entry>2</entry>
<entry>Continuous frame interval.</entry>
</row>
<row>
<entry><constant>V4L2_FRMIVAL_TYPE_STEPWISE</constant></entry>
<entry>3</entry>
<entry>Step-wise defined frame interval.</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1>
&return-value;
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/vidioc-enum-framesizes.xml
+271
View File
@@ -0,0 +1,271 @@
<refentry id="vidioc-enum-framesizes">
<refmeta>
<refentrytitle>ioctl VIDIOC_ENUM_FRAMESIZES</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>VIDIOC_ENUM_FRAMESIZES</refname>
<refpurpose>Enumerate frame sizes</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ioctl</function></funcdef>
<paramdef>int <parameter>fd</parameter></paramdef>
<paramdef>int <parameter>request</parameter></paramdef>
<paramdef>struct v4l2_frmsizeenum *<parameter>argp</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>fd</parameter></term>
<listitem>
<para>&fd;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>request</parameter></term>
<listitem>
<para>VIDIOC_ENUM_FRAMESIZES</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>argp</parameter></term>
<listitem>
<para>Pointer to a &v4l2-frmsizeenum; that contains an index
and pixel format and receives a frame width and height.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<note>
<title>Experimental</title>
<para>This is an <link linkend="experimental">experimental</link>
interface and may change in the future.</para>
</note>
<para>This ioctl allows applications to enumerate all frame sizes
(&ie; width and height in pixels) that the device supports for the
given pixel format.</para>
<para>The supported pixel formats can be obtained by using the
&VIDIOC-ENUM-FMT; function.</para>
<para>The return value and the content of the
<structfield>v4l2_frmsizeenum.type</structfield> field depend on the
type of frame sizes the device supports. Here are the semantics of the
function for the different cases:</para>
<itemizedlist>
<listitem>
<para><emphasis role="bold">Discrete:</emphasis> The function
returns success if the given index value (zero-based) is valid. The
application should increase the index by one for each call until
<constant>EINVAL</constant> is returned. The
<structfield>v4l2_frmsizeenum.type</structfield> field is set to
<constant>V4L2_FRMSIZE_TYPE_DISCRETE</constant> by the driver. Of the
union only the <structfield>discrete</structfield> member is
valid.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Step-wise:</emphasis> The function
returns success if the given index value is zero and
<constant>EINVAL</constant> for any other index value. The
<structfield>v4l2_frmsizeenum.type</structfield> field is set to
<constant>V4L2_FRMSIZE_TYPE_STEPWISE</constant> by the driver. Of the
union only the <structfield>stepwise</structfield> member is
valid.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Continuous:</emphasis> This is a
special case of the step-wise type above. The function returns success
if the given index value is zero and <constant>EINVAL</constant> for
any other index value. The
<structfield>v4l2_frmsizeenum.type</structfield> field is set to
<constant>V4L2_FRMSIZE_TYPE_CONTINUOUS</constant> by the driver. Of
the union only the <structfield>stepwise</structfield> member is valid
and the <structfield>step_width</structfield> and
<structfield>step_height</structfield> values are set to 1.</para>
</listitem>
</itemizedlist>
<para>When the application calls the function with index zero, it
must check the <structfield>type</structfield> field to determine the
type of frame size enumeration the device supports. Only for the
<constant>V4L2_FRMSIZE_TYPE_DISCRETE</constant> type does it make
sense to increase the index value to receive more frame sizes.</para>
<para>Note that the order in which the frame sizes are returned
has no special meaning. In particular does it not say anything about
potential default format sizes.</para>
<para>Applications can assume that the enumeration data does not
change without any interaction from the application itself. This means
that the enumeration data is consistent if the application does not
perform any other ioctl calls while it runs the frame size
enumeration.</para>
</refsect1>
<refsect1>
<title>Structs</title>
<para>In the structs below, <emphasis>IN</emphasis> denotes a
value that has to be filled in by the application,
<emphasis>OUT</emphasis> denotes values that the driver fills in. The
application should zero out all members except for the
<emphasis>IN</emphasis> fields.</para>
<table pgwide="1" frame="none" id="v4l2-frmsize-discrete">
<title>struct <structname>v4l2_frmsize_discrete</structname></title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>__u32</entry>
<entry><structfield>width</structfield></entry>
<entry>Width of the frame [pixel].</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>height</structfield></entry>
<entry>Height of the frame [pixel].</entry>
</row>
</tbody>
</tgroup>
</table>
<table pgwide="1" frame="none" id="v4l2-frmsize-stepwise">
<title>struct <structname>v4l2_frmsize_stepwise</structname></title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>__u32</entry>
<entry><structfield>min_width</structfield></entry>
<entry>Minimum frame width [pixel].</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>max_width</structfield></entry>
<entry>Maximum frame width [pixel].</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>step_width</structfield></entry>
<entry>Frame width step size [pixel].</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>min_height</structfield></entry>
<entry>Minimum frame height [pixel].</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>max_height</structfield></entry>
<entry>Maximum frame height [pixel].</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>step_height</structfield></entry>
<entry>Frame height step size [pixel].</entry>
</row>
</tbody>
</tgroup>
</table>
<table pgwide="1" frame="none" id="v4l2-frmsizeenum">
<title>struct <structname>v4l2_frmsizeenum</structname></title>
<tgroup cols="4">
<colspec colname="c1" />
<colspec colname="c2" />
<colspec colname="c3" />
<colspec colname="c4" />
<tbody valign="top">
<row>
<entry>__u32</entry>
<entry><structfield>index</structfield></entry>
<entry></entry>
<entry>IN: Index of the given frame size in the enumeration.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>pixel_format</structfield></entry>
<entry></entry>
<entry>IN: Pixel format for which the frame sizes are enumerated.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>type</structfield></entry>
<entry></entry>
<entry>OUT: Frame size type the device supports.</entry>
</row>
<row>
<entry>union</entry>
<entry></entry>
<entry></entry>
<entry>OUT: Frame size with the given index.</entry>
</row>
<row>
<entry></entry>
<entry>&v4l2-frmsize-discrete;</entry>
<entry><structfield>discrete</structfield></entry>
<entry></entry>
</row>
<row>
<entry></entry>
<entry>&v4l2-frmsize-stepwise;</entry>
<entry><structfield>stepwise</structfield></entry>
<entry></entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>reserved[2]</structfield></entry>
<entry></entry>
<entry>Reserved space for future use.</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1>
<title>Enums</title>
<table pgwide="1" frame="none" id="v4l2-frmsizetypes">
<title>enum <structname>v4l2_frmsizetypes</structname></title>
<tgroup cols="3">
&cs-def;
<tbody valign="top">
<row>
<entry><constant>V4L2_FRMSIZE_TYPE_DISCRETE</constant></entry>
<entry>1</entry>
<entry>Discrete frame size.</entry>
</row>
<row>
<entry><constant>V4L2_FRMSIZE_TYPE_CONTINUOUS</constant></entry>
<entry>2</entry>
<entry>Continuous frame size.</entry>
</row>
<row>
<entry><constant>V4L2_FRMSIZE_TYPE_STEPWISE</constant></entry>
<entry>3</entry>
<entry>Step-wise defined frame size.</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1>
&return-value;
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/vidioc-enumaudio.xml
+76
View File
@@ -0,0 +1,76 @@
<refentry id="vidioc-enumaudio">
<refmeta>
<refentrytitle>ioctl VIDIOC_ENUMAUDIO</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>VIDIOC_ENUMAUDIO</refname>
<refpurpose>Enumerate audio inputs</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ioctl</function></funcdef>
<paramdef>int <parameter>fd</parameter></paramdef>
<paramdef>int <parameter>request</parameter></paramdef>
<paramdef>struct v4l2_audio *<parameter>argp</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>fd</parameter></term>
<listitem>
<para>&fd;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>request</parameter></term>
<listitem>
<para>VIDIOC_ENUMAUDIO</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>argp</parameter></term>
<listitem>
<para></para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>To query the attributes of an audio input applications
initialize the <structfield>index</structfield> field and zero out the
<structfield>reserved</structfield> array of a &v4l2-audio;
and call the <constant>VIDIOC_ENUMAUDIO</constant> ioctl with a pointer
to this structure. Drivers fill the rest of the structure or return an
&EINVAL; when the index is out of bounds. To enumerate all audio
inputs applications shall begin at index zero, incrementing by one
until the driver returns <errorcode>EINVAL</errorcode>.</para>
<para>See <xref linkend="vidioc-g-audio" /> for a description of
&v4l2-audio;.</para>
</refsect1>
<refsect1>
&return-value;
<variablelist>
<varlistentry>
<term><errorcode>EINVAL</errorcode></term>
<listitem>
<para>The number of the audio input is out of bounds.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/vidioc-enumaudioout.xml
+79
View File
@@ -0,0 +1,79 @@
<refentry id="vidioc-enumaudioout">
<refmeta>
<refentrytitle>ioctl VIDIOC_ENUMAUDOUT</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>VIDIOC_ENUMAUDOUT</refname>
<refpurpose>Enumerate audio outputs</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ioctl</function></funcdef>
<paramdef>int <parameter>fd</parameter></paramdef>
<paramdef>int <parameter>request</parameter></paramdef>
<paramdef>struct v4l2_audioout *<parameter>argp</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>fd</parameter></term>
<listitem>
<para>&fd;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>request</parameter></term>
<listitem>
<para>VIDIOC_ENUMAUDOUT</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>argp</parameter></term>
<listitem>
<para></para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>To query the attributes of an audio output applications
initialize the <structfield>index</structfield> field and zero out the
<structfield>reserved</structfield> array of a &v4l2-audioout; and
call the <constant>VIDIOC_G_AUDOUT</constant> ioctl with a pointer
to this structure. Drivers fill the rest of the structure or return an
&EINVAL; when the index is out of bounds. To enumerate all audio
outputs applications shall begin at index zero, incrementing by one
until the driver returns <errorcode>EINVAL</errorcode>.</para>
<para>Note connectors on a TV card to loop back the received audio
signal to a sound card are not audio outputs in this sense.</para>
<para>See <xref linkend="vidioc-g-audioout" /> for a description of
&v4l2-audioout;.</para>
</refsect1>
<refsect1>
&return-value;
<variablelist>
<varlistentry>
<term><errorcode>EINVAL</errorcode></term>
<listitem>
<para>The number of the audio output is out of bounds.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
kernel/Documentation/DocBook/media/v4l/vidioc-enuminput.xml
+313
View File
@@ -0,0 +1,313 @@
<refentry id="vidioc-enuminput">
<refmeta>
<refentrytitle>ioctl VIDIOC_ENUMINPUT</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>VIDIOC_ENUMINPUT</refname>
<refpurpose>Enumerate video inputs</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ioctl</function></funcdef>
<paramdef>int <parameter>fd</parameter></paramdef>
<paramdef>int <parameter>request</parameter></paramdef>
<paramdef>struct v4l2_input
*<parameter>argp</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>fd</parameter></term>
<listitem>
<para>&fd;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>request</parameter></term>
<listitem>
<para>VIDIOC_ENUMINPUT</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>argp</parameter></term>
<listitem>
<para></para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>To query the attributes of a video input applications
initialize the <structfield>index</structfield> field of &v4l2-input;
and call the <constant>VIDIOC_ENUMINPUT</constant> ioctl with a
pointer to this structure. Drivers fill the rest of the structure or
return an &EINVAL; when the index is out of bounds. To enumerate all
inputs applications shall begin at index zero, incrementing by one
until the driver returns <errorcode>EINVAL</errorcode>.</para>
<table frame="none" pgwide="1" id="v4l2-input">
<title>struct <structname>v4l2_input</structname></title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>__u32</entry>
<entry><structfield>index</structfield></entry>
<entry>Identifies the input, set by the
application.</entry>
</row>
<row>
<entry>__u8</entry>
<entry><structfield>name</structfield>[32]</entry>
<entry>Name of the video input, a NUL-terminated ASCII
string, for example: "Vin (Composite 2)". This information is intended
for the user, preferably the connector label on the device itself.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>type</structfield></entry>
<entry>Type of the input, see <xref
linkend="input-type" />.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>audioset</structfield></entry>
<entry><para>Drivers can enumerate up to 32 video and
audio inputs. This field shows which audio inputs were selectable as
audio source if this was the currently selected video input. It is a
bit mask. The LSB corresponds to audio input 0, the MSB to input 31.
Any number of bits can be set, or none.</para><para>When the driver
does not enumerate audio inputs no bits must be set. Applications
shall not interpret this as lack of audio support. Some drivers
automatically select audio sources and do not enumerate them since
there is no choice anyway.</para><para>For details on audio inputs and
how to select the current input see <xref
linkend="audio" />.</para></entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>tuner</structfield></entry>
<entry>Capture devices can have zero or more tuners (RF
demodulators). When the <structfield>type</structfield> is set to
<constant>V4L2_INPUT_TYPE_TUNER</constant> this is an RF connector and
this field identifies the tuner. It corresponds to
&v4l2-tuner; field <structfield>index</structfield>. For details on
tuners see <xref linkend="tuner" />.</entry>
</row>
<row>
<entry>&v4l2-std-id;</entry>
<entry><structfield>std</structfield></entry>
<entry>Every video input supports one or more different
video standards. This field is a set of all supported standards. For
details on video standards and how to switch see <xref
linkend="standard" />.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>status</structfield></entry>
<entry>This field provides status information about the
input. See <xref linkend="input-status" /> for flags.
With the exception of the sensor orientation bits <structfield>status</structfield> is only valid when this is the
current input.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>capabilities</structfield></entry>
<entry>This field provides capabilities for the
input. See <xref linkend="input-capabilities" /> for flags.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>reserved</structfield>[3]</entry>
<entry>Reserved for future extensions. Drivers must set
the array to zero.</entry>
</row>
</tbody>
</tgroup>
</table>
<table frame="none" pgwide="1" id="input-type">
<title>Input Types</title>
<tgroup cols="3">
&cs-def;
<tbody valign="top">
<row>
<entry><constant>V4L2_INPUT_TYPE_TUNER</constant></entry>
<entry>1</entry>
<entry>This input uses a tuner (RF demodulator).</entry>
</row>
<row>
<entry><constant>V4L2_INPUT_TYPE_CAMERA</constant></entry>
<entry>2</entry>
<entry>Analog baseband input, for example CVBS /
Composite Video, S-Video, RGB.</entry>
</row>
</tbody>
</tgroup>
</table>
<!-- Status flags based on proposal by Mark McClelland,
video4linux-list@redhat.com on 18 Oct 2002, subject "Re: [V4L] Re:
v4l2 api". "Why are some of them inverted? So that the driver doesn't
have to lie about the status in cases where it can't tell one way or
the other. Plus, a status of zero would generally mean that everything
is OK." -->
<table frame="none" pgwide="1" id="input-status">
<title>Input Status Flags</title>
<tgroup cols="3">
<colspec colname="c1" />
<colspec colname="c2" align="center" />
<colspec colname="c3" />
<spanspec namest="c1" nameend="c3" spanname="hspan"
align="left" />
<tbody valign="top">
<row>
<entry spanname="hspan">General</entry>
</row>
<row>
<entry><constant>V4L2_IN_ST_NO_POWER</constant></entry>
<entry>0x00000001</entry>
<entry>Attached device is off.</entry>
</row>
<row>
<entry><constant>V4L2_IN_ST_NO_SIGNAL</constant></entry>
<entry>0x00000002</entry>
<entry></entry>
</row>
<row>
<entry><constant>V4L2_IN_ST_NO_COLOR</constant></entry>
<entry>0x00000004</entry>
<entry>The hardware supports color decoding, but does not
detect color modulation in the signal.</entry>
</row>
<row>
<entry spanname="hspan">Sensor Orientation</entry>
</row>
<row>
<entry><constant>V4L2_IN_ST_HFLIP</constant></entry>
<entry>0x00000010</entry>
<entry>The input is connected to a device that produces a signal
that is flipped horizontally and does not correct this before passing the
signal to userspace.</entry>
</row>
<row>
<entry><constant>V4L2_IN_ST_VFLIP</constant></entry>
<entry>0x00000020</entry>
<entry>The input is connected to a device that produces a signal
that is flipped vertically and does not correct this before passing the
signal to userspace. Note that a 180 degree rotation is the same as HFLIP | VFLIP</entry>
</row>
<row>
<entry spanname="hspan">Analog Video</entry>
</row>
<row>
<entry><constant>V4L2_IN_ST_NO_H_LOCK</constant></entry>
<entry>0x00000100</entry>
<entry>No horizontal sync lock.</entry>
</row>
<row>
<entry><constant>V4L2_IN_ST_COLOR_KILL</constant></entry>
<entry>0x00000200</entry>
<entry>A color killer circuit automatically disables color
decoding when it detects no color modulation. When this flag is set
the color killer is enabled <emphasis>and</emphasis> has shut off
color decoding.</entry>
</row>
<row>
<entry spanname="hspan">Digital Video</entry>
</row>
<row>
<entry><constant>V4L2_IN_ST_NO_SYNC</constant></entry>
<entry>0x00010000</entry>
<entry>No synchronization lock.</entry>
</row>
<row>
<entry><constant>V4L2_IN_ST_NO_EQU</constant></entry>
<entry>0x00020000</entry>
<entry>No equalizer lock.</entry>
</row>
<row>
<entry><constant>V4L2_IN_ST_NO_CARRIER</constant></entry>
<entry>0x00040000</entry>
<entry>Carrier recovery failed.</entry>
</row>
<row>
<entry spanname="hspan">VCR and Set-Top Box</entry>
</row>
<row>
<entry><constant>V4L2_IN_ST_MACROVISION</constant></entry>
<entry>0x01000000</entry>
<entry>Macrovision is an analog copy prevention system
mangling the video signal to confuse video recorders. When this
flag is set Macrovision has been detected.</entry>
</row>
<row>
<entry><constant>V4L2_IN_ST_NO_ACCESS</constant></entry>
<entry>0x02000000</entry>
<entry>Conditional access denied.</entry>
</row>
<row>
<entry><constant>V4L2_IN_ST_VTR</constant></entry>
<entry>0x04000000</entry>
<entry>VTR time constant. [?]</entry>
</row>
</tbody>
</tgroup>
</table>
<!-- Capability flags based on video timings RFC by Muralidharan
Karicheri, titled RFC (v1.2): V4L - Support for video timings at the
input/output interface to linux-media@vger.kernel.org on 19 Oct 2009.
-->
<table frame="none" pgwide="1" id="input-capabilities">
<title>Input capabilities</title>
<tgroup cols="3">
&cs-def;
<tbody valign="top">
<row>
<entry><constant>V4L2_IN_CAP_PRESETS</constant></entry>
<entry>0x00000001</entry>
<entry>This input supports setting DV presets by using VIDIOC_S_DV_PRESET.</entry>
</row>
<row>
<entry><constant>V4L2_IN_CAP_CUSTOM_TIMINGS</constant></entry>
<entry>0x00000002</entry>
<entry>This input supports setting custom video timings by using VIDIOC_S_DV_TIMINGS.</entry>
</row>
<row>
<entry><constant>V4L2_IN_CAP_STD</constant></entry>
<entry>0x00000004</entry>
<entry>This input supports setting the TV standard by using VIDIOC_S_STD.</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1>
&return-value;
<variablelist>
<varlistentry>
<term><errorcode>EINVAL</errorcode></term>
<listitem>
<para>The &v4l2-input; <structfield>index</structfield> is
out of bounds.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>

Some files were not shown because too many files have changed in this diff Show More