openkylin
/
linux
mirror of https://gitee.com/openkylin/linux.git
9
0
Fork 0
Code Issues Projects Releases Wiki Activity

V4L/DVB (12761): DocBook: add media API specs 

The V4L and DVB API's are there for a long time. however, up to now,
no efforts were done to merge them to kernel DocBook.

This patch adds the current versions of the specs as an unique compendium.

Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
This commit is contained in:
Mauro Carvalho Chehab 2009-09-13 22:16:04 -03:00
parent f4e96deb45
commit 8e080c2e6c
122 changed files with 36715 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Documentation/DocBook/Makefile
View File

@ -14,7 +14,7 @@ DOCBOOKS := z8530book.xml mcabook.xml device-drivers.xml \
genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \
mac80211.xml debugobjects.xml sh.xml regulator.xml \
alsa-driver-api.xml writing-an-alsa-driver.xml \
tracepoint.xml
tracepoint.xml media.xml
###
# The build process is as follows (targets):

1473
Documentation/DocBook/dvb/audio.xml Normal file
View File

File diff suppressed because it is too large Load Diff

221
Documentation/DocBook/dvb/ca.xml Normal file
View File

@ -0,0 +1,221 @@
<title>DVB CA Device</title>
<para>The DVB CA device controls the conditional access hardware. It can be accessed through
<emphasis role="tt">/dev/dvb/adapter0/ca0</emphasis>. Data types and and ioctl definitions can be accessed by
including <emphasis role="tt">linux/dvb/ca.h</emphasis> in your application.
</para>
<section id="ca_data_types">
<title>CA Data Types</title>
<section id="ca_slot_info_t">
<title>ca_slot_info_t</title>
<programlisting>
/&#x22C6; slot interface types and info &#x22C6;/
typedef struct ca_slot_info_s {
int num; /&#x22C6; slot number &#x22C6;/
int type; /&#x22C6; CA interface this slot supports &#x22C6;/
#define CA_CI 1 /&#x22C6; CI high level interface &#x22C6;/
#define CA_CI_LINK 2 /&#x22C6; CI link layer level interface &#x22C6;/
#define CA_CI_PHYS 4 /&#x22C6; CI physical layer level interface &#x22C6;/
#define CA_SC 128 /&#x22C6; simple smart card interface &#x22C6;/
unsigned int flags;
#define CA_CI_MODULE_PRESENT 1 /&#x22C6; module (or card) inserted &#x22C6;/
#define CA_CI_MODULE_READY 2
} ca_slot_info_t;
</programlisting>
</section>
<section id="ca_descr_info_t">
<title>ca_descr_info_t</title>
<programlisting>
typedef struct ca_descr_info_s {
unsigned int num; /&#x22C6; number of available descramblers (keys) &#x22C6;/
unsigned int type; /&#x22C6; type of supported scrambling system &#x22C6;/
#define CA_ECD 1
#define CA_NDS 2
#define CA_DSS 4
} ca_descr_info_t;
</programlisting>
</section>
<section id="ca_cap_t">
<title>ca_cap_t</title>
<programlisting>
typedef struct ca_cap_s {
unsigned int slot_num; /&#x22C6; total number of CA card and module slots &#x22C6;/
unsigned int slot_type; /&#x22C6; OR of all supported types &#x22C6;/
unsigned int descr_num; /&#x22C6; total number of descrambler slots (keys) &#x22C6;/
unsigned int descr_type;/&#x22C6; OR of all supported types &#x22C6;/
} ca_cap_t;
</programlisting>
</section>
<section id="ca_msg_t">
<title>ca_msg_t</title>
<programlisting>
/&#x22C6; a message to/from a CI-CAM &#x22C6;/
typedef struct ca_msg_s {
unsigned int index;
unsigned int type;
unsigned int length;
unsigned char msg[256];
} ca_msg_t;
</programlisting>
</section>
<section id="ca_descr_t">
<title>ca_descr_t</title>
<programlisting>
typedef struct ca_descr_s {
unsigned int index;
unsigned int parity;
unsigned char cw[8];
} ca_descr_t;
</programlisting>
</section></section>
<section id="ca_function_calls">
<title>CA Function Calls</title>
<section id="ca_fopen">
<title>open()</title>
<para>DESCRIPTION
</para>
<informaltable><tgroup cols="1"><tbody><row><entry
align="char">
<para>This system call opens a named ca device (e.g. /dev/ost/ca) for subsequent use.</para>
<para>When an open() call has succeeded, the device will be ready for use.
The significance of blocking or non-blocking mode is described in the
documentation for functions where there is a difference. It does not affect the
semantics of the open() call itself. A device opened in blocking mode can later
be put into non-blocking mode (and vice versa) using the F_SETFL command
of the fcntl system call. This is a standard system call, documented in the Linux
manual page for fcntl. Only one user can open the CA Device in O_RDWR
mode. All other attempts to open the device in this mode will fail, and an error
code will be returned.</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>SYNOPSIS
</para>
<informaltable><tgroup cols="1"><tbody><row><entry
align="char">
<para>int open(const char &#x22C6;deviceName, int flags);</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>PARAMETERS
</para>
<informaltable><tgroup cols="2"><tbody><row><entry
align="char">
<para>const char
*deviceName</para>
</entry><entry
align="char">
<para>Name of specific video device.</para>
</entry>
</row><row><entry
align="char">
<para>int flags</para>
</entry><entry
align="char">
<para>A bit-wise OR of the following flags:</para>
</entry>
</row><row><entry
align="char">
</entry><entry
align="char">
<para>O_RDONLY read-only access</para>
</entry>
</row><row><entry
align="char">
</entry><entry
align="char">
<para>O_RDWR read/write access</para>
</entry>
</row><row><entry
align="char">
</entry><entry
align="char">
<para>O_NONBLOCK open in non-blocking mode</para>
</entry>
</row><row><entry
align="char">
</entry><entry
align="char">
<para>(blocking mode is the default)</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>ERRORS
</para>
<informaltable><tgroup cols="2"><tbody><row><entry
align="char">
<para>ENODEV</para>
</entry><entry
align="char">
<para>Device driver not loaded/available.</para>
</entry>
</row><row><entry
align="char">
<para>EINTERNAL</para>
</entry><entry
align="char">
<para>Internal error.</para>
</entry>
</row><row><entry
align="char">
<para>EBUSY</para>
</entry><entry
align="char">
<para>Device or resource busy.</para>
</entry>
</row><row><entry
align="char">
<para>EINVAL</para>
</entry><entry
align="char">
<para>Invalid argument.</para>
</entry>
</row></tbody></tgroup></informaltable>
</section>
<section id="ca_fclose">
<title>close()</title>
<para>DESCRIPTION
</para>
<informaltable><tgroup cols="1"><tbody><row><entry
align="char">
<para>This system call closes a previously opened audio device.</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>SYNOPSIS
</para>
<informaltable><tgroup cols="1"><tbody><row><entry
align="char">
<para>int close(int fd);</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>PARAMETERS
</para>
<informaltable><tgroup cols="2"><tbody><row><entry
align="char">
<para>int fd</para>
</entry><entry
align="char">
<para>File descriptor returned by a previous call to open().</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>ERRORS
</para>
<informaltable><tgroup cols="2"><tbody><row><entry
align="char">
<para>EBADF</para>
</entry><entry
align="char">
<para>fd is not a valid open file descriptor.</para>
</entry>
</row></tbody></tgroup></informaltable>
</section>
</section>

973
Documentation/DocBook/dvb/demux.xml Normal file
View File

@ -0,0 +1,973 @@
<title>DVB Demux Device</title>
<para>The DVB demux device controls the filters of the DVB hardware/software. It can be
accessed through <emphasis role="tt">/dev/adapter0/demux0</emphasis>. Data types and and ioctl definitions can be
accessed by including <emphasis role="tt">linux/dvb/dmx.h</emphasis> in your application.
</para>
<section id="dmx_types">
<title>Demux Data Types</title>
<section id="dmx_output_t">
<title>dmx_output_t</title>
<programlisting>
typedef enum
{
DMX_OUT_DECODER,
DMX_OUT_TAP,
DMX_OUT_TS_TAP
} dmx_output_t;
</programlisting>
<para><emphasis role="tt">DMX_OUT_TAP</emphasis> delivers the stream output to the demux device on which the ioctl is
called.
</para>
<para><emphasis role="tt">DMX_OUT_TS_TAP</emphasis> routes output to the logical DVR device <emphasis role="tt">/dev/dvb/adapter0/dvr0</emphasis>,
which delivers a TS multiplexed from all filters for which <emphasis role="tt">DMX_OUT_TS_TAP</emphasis> was
specified.
</para>
</section>
<section id="dmx_input_t">
<title>dmx_input_t</title>
<programlisting>
typedef enum
{
DMX_IN_FRONTEND,
DMX_IN_DVR
} dmx_input_t;
</programlisting>
</section>
<section id="dmx_pes_type_t">
<title>dmx_pes_type_t</title>
<programlisting>
typedef enum
{
DMX_PES_AUDIO,
DMX_PES_VIDEO,
DMX_PES_TELETEXT,
DMX_PES_SUBTITLE,
DMX_PES_PCR,
DMX_PES_OTHER
} dmx_pes_type_t;
</programlisting>
</section>
<section id="dmx_event_t">
<title>dmx_event_t</title>
<programlisting>
typedef enum
{
DMX_SCRAMBLING_EV,
DMX_FRONTEND_EV
} dmx_event_t;
</programlisting>
</section>
<section id="dmx_scrambling_status_t">
<title>dmx_scrambling_status_t</title>
<programlisting>
typedef enum
{
DMX_SCRAMBLING_OFF,
DMX_SCRAMBLING_ON
} dmx_scrambling_status_t;
</programlisting>
</section>
<section id="dmx_filter">
<title>struct dmx_filter</title>
<programlisting>
typedef struct dmx_filter
{
uint8_t filter[DMX_FILTER_SIZE];
uint8_t mask[DMX_FILTER_SIZE];
} dmx_filter_t;
</programlisting>
</section>
<section id="dmx_sct_filter_params">
<title>struct dmx_sct_filter_params</title>
<programlisting>
struct dmx_sct_filter_params
{
uint16_t pid;
dmx_filter_t filter;
uint32_t timeout;
uint32_t flags;
#define DMX_CHECK_CRC 1
#define DMX_ONESHOT 2
#define DMX_IMMEDIATE_START 4
};
</programlisting>
</section>
<section id="dmx_pes_filter_params">
<title>struct dmx_pes_filter_params</title>
<programlisting>
struct dmx_pes_filter_params
{
uint16_t pid;
dmx_input_t input;
dmx_output_t output;
dmx_pes_type_t pes_type;
uint32_t flags;
};
</programlisting>
</section>
<section id="dmx_event">
<title>struct dmx_event</title>
<programlisting>
struct dmx_event
{
dmx_event_t event;
time_t timeStamp;
union
{
dmx_scrambling_status_t scrambling;
} u;
};
</programlisting>
</section>
<section id="dmx_stc">
<title>struct dmx_stc</title>
<programlisting>
struct dmx_stc {
unsigned int num; /&#x22C6; input : which STC? 0..N &#x22C6;/
unsigned int base; /&#x22C6; output: divisor for stc to get 90 kHz clock &#x22C6;/
uint64_t stc; /&#x22C6; output: stc in 'base'&#x22C6;90 kHz units &#x22C6;/
};
</programlisting>
</section>
</section>
<section id="dmx_fcalls">
<title>Demux Function Calls</title>
<section id="dmx_fopen">
<title>open()</title>
<para>DESCRIPTION
</para>
<informaltable><tgroup cols="1"><tbody><row><entry
align="char">
<para>This system call, used with a device name of /dev/dvb/adapter0/demux0,
allocates a new filter and returns a handle which can be used for subsequent
control of that filter. This call has to be made for each filter to be used, i.e. every
returned file descriptor is a reference to a single filter. /dev/dvb/adapter0/dvr0
is a logical device to be used for retrieving Transport Streams for digital
video recording. When reading from this device a transport stream containing
the packets from all PES filters set in the corresponding demux device
(/dev/dvb/adapter0/demux0) having the output set to DMX_OUT_TS_TAP. A
recorded Transport Stream is replayed by writing to this device. </para>
<para>The significance of blocking or non-blocking mode is described in the
documentation for functions where there is a difference. It does not affect the
semantics of the open() call itself. A device opened in blocking mode can later
be put into non-blocking mode (and vice versa) using the F_SETFL command
of the fcntl system call.</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>SYNOPSIS
</para>
<informaltable><tgroup cols="1"><tbody><row><entry
align="char">
<para>int open(const char &#x22C6;deviceName, int flags);</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>PARAMETERS
</para>
<informaltable><tgroup cols="2"><tbody><row><entry
align="char">
<para>const char
*deviceName</para>
</entry><entry
align="char">
<para>Name of demux device.</para>
</entry>
</row><row><entry
align="char">
<para>int flags</para>
</entry><entry
align="char">
<para>A bit-wise OR of the following flags:</para>
</entry>
</row><row><entry
align="char">
</entry><entry
align="char">
<para>O_RDWR read/write access</para>
</entry>
</row><row><entry
align="char">
</entry><entry
align="char">
<para>O_NONBLOCK open in non-blocking mode</para>
</entry>
</row><row><entry
align="char">
</entry><entry
align="char">
<para>(blocking mode is the default)</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>ERRORS
</para>
<informaltable><tgroup cols="2"><tbody><row><entry
align="char">
<para>ENODEV</para>
</entry><entry
align="char">
<para>Device driver not loaded/available.</para>
</entry>
</row><row><entry
align="char">
<para>EINVAL</para>
</entry><entry
align="char">
<para>Invalid argument.</para>
</entry>
</row><row><entry
align="char">
<para>EMFILE</para>
</entry><entry
align="char">
<para>&#8220;Too many open files&#8221;, i.e. no more filters available.</para>
</entry>
</row><row><entry
align="char">
<para>ENOMEM</para>
</entry><entry
align="char">
<para>The driver failed to allocate enough memory.</para>
</entry>
</row></tbody></tgroup></informaltable>
</section>
<section id="dmx_fclose">
<title>close()</title>
<para>DESCRIPTION
</para>
<informaltable><tgroup cols="1"><tbody><row><entry
align="char">
<para>This system call deactivates and deallocates a filter that was previously
allocated via the open() call.</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>SYNOPSIS
</para>
<informaltable><tgroup cols="1"><tbody><row><entry
align="char">
<para>int close(int fd);</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>PARAMETERS
</para>
<informaltable><tgroup cols="2"><tbody><row><entry
align="char">
<para>int fd</para>
</entry><entry
align="char">
<para>File descriptor returned by a previous call to open().</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>ERRORS
</para>
<informaltable><tgroup cols="2"><tbody><row><entry
align="char">
<para>EBADF</para>
</entry><entry
align="char">
<para>fd is not a valid open file descriptor.</para>
</entry>
</row></tbody></tgroup></informaltable>
</section>
<section id="dmx_fread">
<title>read()</title>
<para>DESCRIPTION
</para>
<informaltable><tgroup cols="1"><tbody><row><entry
align="char">
<para>This system call returns filtered data, which might be section or PES data. The
filtered data is transferred from the driver&#8217;s internal circular buffer to buf. The
maximum amount of data to be transferred is implied by count.</para>
</entry>
</row><row><entry
align="char">
<para>When returning section data the driver always tries to return a complete single
section (even though buf would provide buffer space for more data). If the size
of the buffer is smaller than the section as much as possible will be returned,
and the remaining data will be provided in subsequent calls.</para>
</entry>
</row><row><entry
align="char">
<para>The size of the internal buffer is 2 * 4096 bytes (the size of two maximum
sized sections) by default. The size of this buffer may be changed by using the
DMX_SET_BUFFER_SIZE function. If the buffer is not large enough, or if
the read operations are not performed fast enough, this may result in a buffer
overflow error. In this case EOVERFLOW will be returned, and the circular
buffer will be emptied. This call is blocking if there is no data to return, i.e. the
process will be put to sleep waiting for data, unless the O_NONBLOCK flag
is specified.</para>
</entry>
</row><row><entry
align="char">
<para>Note that in order to be able to read, the filtering process has to be started
by defining either a section or a PES filter by means of the ioctl functions,
and then starting the filtering process via the DMX_START ioctl function
or by setting the DMX_IMMEDIATE_START flag. If the reading is done
from a logical DVR demux device, the data will constitute a Transport Stream
including the packets from all PES filters in the corresponding demux device
/dev/dvb/adapter0/demux0 having the output set to DMX_OUT_TS_TAP.</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>SYNOPSIS
</para>
<informaltable><tgroup cols="1"><tbody><row><entry
align="char">
<para>size_t read(int fd, void &#x22C6;buf, size_t count);</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>PARAMETERS
</para>
<informaltable><tgroup cols="2"><tbody><row><entry
align="char">
<para>int fd</para>
</entry><entry
align="char">
<para>File descriptor returned by a previous call to open().</para>
</entry>
</row><row><entry
align="char">
<para>void *buf</para>
</entry><entry
align="char">
<para>Pointer to the buffer to be used for returned filtered data.</para>
</entry>
</row><row><entry
align="char">
<para>size_t count</para>
</entry><entry
align="char">
<para>Size of buf.</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>ERRORS
</para>
<informaltable><tgroup cols="2"><tbody><row><entry
align="char">
<para>EWOULDBLOCK</para>
</entry><entry
align="char">
<para>No data to return and O_NONBLOCK was specified.</para>
</entry>
</row><row><entry
align="char">
<para>EBADF</para>
</entry><entry
align="char">
<para>fd is not a valid open file descriptor.</para>
</entry>
</row><row><entry
align="char">
<para>ECRC</para>
</entry><entry
align="char">
<para>Last section had a CRC error - no data returned. The
buffer is flushed.</para>
</entry>
</row><row><entry
align="char">
<para>EOVERFLOW</para>
</entry><entry
align="char">
</entry>
</row><row><entry
align="char">
</entry><entry
align="char">
<para>The filtered data was not read from the buffer in due
time, resulting in non-read data being lost. The buffer is
flushed.</para>
</entry>
</row><row><entry
align="char">
<para>ETIMEDOUT</para>
</entry><entry
align="char">
<para>The section was not loaded within the stated timeout
period. See ioctl DMX_SET_FILTER for how to set a
timeout.</para>
</entry>
</row><row><entry
align="char">
<para>EFAULT</para>
</entry><entry
align="char">
<para>The driver failed to write to the callers buffer due to an
invalid *buf pointer.</para>
</entry>
</row></tbody></tgroup></informaltable>
</section>
<section id="dmx_fwrite">
<title>write()</title>
<para>DESCRIPTION
</para>
<informaltable><tgroup cols="1"><tbody><row><entry
align="char">
<para>This system call is only provided by the logical device /dev/dvb/adapter0/dvr0,
associated with the physical demux device that provides the actual DVR
functionality. It is used for replay of a digitally recorded Transport Stream.
Matching filters have to be defined in the corresponding physical demux
device, /dev/dvb/adapter0/demux0. The amount of data to be transferred is
implied by count.</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>SYNOPSIS
</para>
<informaltable><tgroup cols="1"><tbody><row><entry
align="char">
<para>ssize_t write(int fd, const void &#x22C6;buf, size_t
count);</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>PARAMETERS
</para>
<informaltable><tgroup cols="2"><tbody><row><entry
align="char">
<para>int fd</para>
</entry><entry
align="char">
<para>File descriptor returned by a previous call to open().</para>
</entry>
</row><row><entry
align="char">
<para>void *buf</para>
</entry><entry
align="char">
<para>Pointer to the buffer containing the Transport Stream.</para>
</entry>
</row><row><entry
align="char">
<para>size_t count</para>
</entry><entry
align="char">
<para>Size of buf.</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>ERRORS
</para>
<informaltable><tgroup cols="2"><tbody><row><entry
align="char">
<para>EWOULDBLOCK</para>
</entry><entry
align="char">
<para>No data was written. This
might happen if O_NONBLOCK was specified and there
is no more buffer space available (if O_NONBLOCK is
not specified the function will block until buffer space is
available).</para>
</entry>
</row><row><entry
align="char">
<para>EBUSY</para>
</entry><entry
align="char">
<para>This error code indicates that there are conflicting
requests. The corresponding demux device is setup to
receive data from the front- end. Make sure that these
filters are stopped and that the filters with input set to
DMX_IN_DVR are started.</para>
</entry>
</row><row><entry
align="char">
<para>EBADF</para>
</entry><entry
align="char">
<para>fd is not a valid open file descriptor.</para>
</entry>
</row></tbody></tgroup></informaltable>
</section>
<section id="dmx_start">
<title>DMX_START</title>
<para>DESCRIPTION
</para>
<informaltable><tgroup cols="1"><tbody><row><entry
align="char">
<para>This ioctl call is used to start the actual filtering operation defined via the ioctl
calls DMX_SET_FILTER or DMX_SET_PES_FILTER.</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>SYNOPSIS
</para>
<informaltable><tgroup cols="1"><tbody><row><entry
align="char">
<para>int ioctl( int fd, int request = DMX_START);</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>PARAMETERS
</para>
<informaltable><tgroup cols="2"><tbody><row><entry
align="char">
<para>int fd</para>
</entry><entry
align="char">
<para>File descriptor returned by a previous call to open().</para>
</entry>
</row><row><entry
align="char">
<para>int request</para>
</entry><entry
align="char">
<para>Equals DMX_START for this command.</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>ERRORS
</para>
<informaltable><tgroup cols="2"><tbody><row><entry
align="char">
<para>EBADF</para>
</entry><entry
align="char">
<para>fd is not a valid file descriptor.</para>
</entry>
</row><row><entry
align="char">
<para>EINVAL</para>
</entry><entry
align="char">
<para>Invalid argument, i.e. no filtering parameters provided via
the DMX_SET_FILTER or DMX_SET_PES_FILTER
functions.</para>
</entry>
</row><row><entry
align="char">
<para>EBUSY</para>
</entry><entry
align="char">
<para>This error code indicates that there are conflicting
requests. There are active filters filtering data from
another input source. Make sure that these filters are
stopped before starting this filter.</para>
</entry>
</row></tbody></tgroup></informaltable>
</section>
<section id="dmx_stop">
<title>DMX_STOP</title>
<para>DESCRIPTION
</para>
<informaltable><tgroup cols="1"><tbody><row><entry
align="char">
<para>This ioctl call is used to stop the actual filtering operation defined via the
ioctl calls DMX_SET_FILTER or DMX_SET_PES_FILTER and started via
the DMX_START command.</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>SYNOPSIS
</para>
<informaltable><tgroup cols="1"><tbody><row><entry
align="char">
<para>int ioctl( int fd, int request = DMX_STOP);</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>PARAMETERS
</para>
<informaltable><tgroup cols="2"><tbody><row><entry
align="char">
<para>int fd</para>
</entry><entry
align="char">
<para>File descriptor returned by a previous call to open().</para>
</entry>
</row><row><entry
align="char">
<para>int request</para>
</entry><entry
align="char">
<para>Equals DMX_STOP for this command.</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>ERRORS
</para>
<informaltable><tgroup cols="2"><tbody><row><entry
align="char">
<para>EBADF</para>
</entry><entry
align="char">
<para>fd is not a valid file descriptor.</para>
</entry>
</row></tbody></tgroup></informaltable>
</section>
<section id="dmx_set_filter">
<title>DMX_SET_FILTER</title>
<para>DESCRIPTION
</para>
<informaltable><tgroup cols="1"><tbody><row><entry
align="char">
<para>This ioctl call sets up a filter according to the filter and mask parameters
provided. A timeout may be defined stating number of seconds to wait for a
section to be loaded. A value of 0 means that no timeout should be applied.
Finally there is a flag field where it is possible to state whether a section should
be CRC-checked, whether the filter should be a &#8221;one-shot&#8221; filter, i.e. if the
filtering operation should be stopped after the first section is received, and
whether the filtering operation should be started immediately (without waiting
for a DMX_START ioctl call). If a filter was previously set-up, this filter will
be canceled, and the receive buffer will be flushed.</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>SYNOPSIS
</para>
<informaltable><tgroup cols="1"><tbody><row><entry
align="char">
<para>int ioctl( int fd, int request = DMX_SET_FILTER,
struct dmx_sct_filter_params &#x22C6;params);</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>PARAMETERS
</para>
<informaltable><tgroup cols="2"><tbody><row><entry
align="char">
<para>int fd</para>
</entry><entry
align="char">
<para>File descriptor returned by a previous call to open().</para>
</entry>
</row><row><entry
align="char">
<para>int request</para>
</entry><entry
align="char">
<para>Equals DMX_SET_FILTER for this command.</para>
</entry>
</row><row><entry
align="char">
<para>struct
dmx_sct_filter_params
*params</para>
</entry><entry
align="char">
<para>Pointer to structure containing filter parameters.</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>ERRORS
</para>
<informaltable><tgroup cols="2"><tbody><row><entry
align="char">
<para>EBADF</para>
</entry><entry
align="char">
<para>fd is not a valid file descriptor.</para>
</entry>
</row><row><entry
align="char">
<para>EINVAL</para>
</entry><entry
align="char">
<para>Invalid argument.</para>
</entry>
</row></tbody></tgroup></informaltable>
</section>
<section id="dmx_set_pes_filter">
<title>DMX_SET_PES_FILTER</title>
<para>DESCRIPTION
</para>
<informaltable><tgroup cols="1"><tbody><row><entry
align="char">
<para>This ioctl call sets up a PES filter according to the parameters provided. By a
PES filter is meant a filter that is based just on the packet identifier (PID), i.e.
no PES header or payload filtering capability is supported.</para>
</entry>
</row><row><entry
align="char">
<para>The transport stream destination for the filtered output may be set. Also the
PES type may be stated in order to be able to e.g. direct a video stream directly
to the video decoder. Finally there is a flag field where it is possible to state
whether the filtering operation should be started immediately (without waiting
for a DMX_START ioctl call). If a filter was previously set-up, this filter will
be cancelled, and the receive buffer will be flushed.</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>SYNOPSIS
</para>
<informaltable><tgroup cols="1"><tbody><row><entry
align="char">
<para>int ioctl( int fd, int request = DMX_SET_PES_FILTER,
struct dmx_pes_filter_params &#x22C6;params);</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>PARAMETERS
</para>
<informaltable><tgroup cols="2"><tbody><row><entry
align="char">
<para>int fd</para>
</entry><entry
align="char">
<para>File descriptor returned by a previous call to open().</para>
</entry>
</row><row><entry
align="char">
<para>int request</para>
</entry><entry
align="char">
<para>Equals DMX_SET_PES_FILTER for this command.</para>
</entry>
</row><row><entry
align="char">
<para>struct
dmx_pes_filter_params
*params</para>
</entry><entry
align="char">
<para>Pointer to structure containing filter parameters.</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>ERRORS
</para>
<informaltable><tgroup cols="2"><tbody><row><entry
align="char">
<para>EBADF</para>
</entry><entry
align="char">
<para>fd is not a valid file descriptor.</para>
</entry>
</row><row><entry
align="char">
<para>EINVAL</para>
</entry><entry
align="char">
<para>Invalid argument.</para>
</entry>
</row><row><entry
align="char">
<para>EBUSY</para>
</entry><entry
align="char">
<para>This error code indicates that there are conflicting
requests. There are active filters filtering data from
another input source. Make sure that these filters are
stopped before starting this filter.</para>
</entry>
</row></tbody></tgroup></informaltable>
</section>
<section id="dms_set_buffer_size">
<title>DMX_SET_BUFFER_SIZE</title>
<para>DESCRIPTION
</para>
<informaltable><tgroup cols="1"><tbody><row><entry
align="char">
<para>This ioctl call is used to set the size of the circular buffer used for filtered data.
The default size is two maximum sized sections, i.e. if this function is not called
a buffer size of 2 * 4096 bytes will be used.</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>SYNOPSIS
</para>
<informaltable><tgroup cols="1"><tbody><row><entry
align="char">
<para>int ioctl( int fd, int request =
DMX_SET_BUFFER_SIZE, unsigned long size);</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>PARAMETERS
</para>
<informaltable><tgroup cols="2"><tbody><row><entry
align="char">
<para>int fd</para>
</entry><entry
align="char">
<para>File descriptor returned by a previous call to open().</para>
</entry>
</row><row><entry
align="char">
<para>int request</para>
</entry><entry
align="char">
<para>Equals DMX_SET_BUFFER_SIZE for this command.</para>
</entry>
</row><row><entry
align="char">
<para>unsigned long size</para>
</entry><entry
align="char">
<para>Size of circular buffer.</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>ERRORS
</para>
<informaltable><tgroup cols="2"><tbody><row><entry
align="char">
<para>EBADF</para>
</entry><entry
align="char">
<para>fd is not a valid file descriptor.</para>
</entry>
</row><row><entry
align="char">
<para>ENOMEM</para>
</entry><entry
align="char">
<para>The driver was not able to allocate a buffer of the
requested size.</para>
</entry>
</row></tbody></tgroup></informaltable>
</section>
<section id="dmx_get_event">
<title>DMX_GET_EVENT</title>
<para>DESCRIPTION
</para>
<informaltable><tgroup cols="1"><tbody><row><entry
align="char">
<para>This ioctl call returns an event if available. If an event is not available,
the behavior depends on whether the device is in blocking or non-blocking
mode. In the latter case, the call fails immediately with errno set to
EWOULDBLOCK. In the former case, the call blocks until an event becomes
available.</para>
</entry>
</row><row><entry
align="char">
<para>The standard Linux poll() and/or select() system calls can be used with the
device file descriptor to watch for new events. For select(), the file descriptor
should be included in the exceptfds argument, and for poll(), POLLPRI should
be specified as the wake-up condition. Only the latest event for each filter is
saved.</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>SYNOPSIS
</para>
<informaltable><tgroup cols="1"><tbody><row><entry
align="char">
<para>int ioctl( int fd, int request = DMX_GET_EVENT,
struct dmx_event &#x22C6;ev);</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>PARAMETERS
</para>
<informaltable><tgroup cols="2"><tbody><row><entry
align="char">
<para>int fd</para>
</entry><entry
align="char">
<para>File descriptor returned by a previous call to open().</para>
</entry>
</row><row><entry
align="char">
<para>int request</para>
</entry><entry
align="char">
<para>Equals DMX_GET_EVENT for this command.</para>
</entry>
</row><row><entry
align="char">
<para>struct dmx_event *ev</para>
</entry><entry
align="char">
<para>Pointer to the location where the event is to be stored.</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>ERRORS
</para>
<informaltable><tgroup cols="2"><tbody><row><entry
align="char">
<para>EBADF</para>
</entry><entry
align="char">
<para>fd is not a valid file descriptor.</para>
</entry>
</row><row><entry
align="char">
<para>EFAULT</para>
</entry><entry
align="char">
<para>ev points to an invalid address.</para>
</entry>
</row><row><entry
align="char">
<para>EWOULDBLOCK</para>
</entry><entry
align="char">
<para>There is no event pending, and the device is in
non-blocking mode.</para>
</entry>
</row></tbody></tgroup></informaltable>
</section>
<section id="dmx_get_stc">
<title>DMX_GET_STC</title>
<para>DESCRIPTION
</para>
<informaltable><tgroup cols="1"><tbody><row><entry
align="char">
<para>This ioctl call returns the current value of the system time counter (which is driven
by a PES filter of type DMX_PES_PCR). Some hardware supports more than one
STC, so you must specify which one by setting the num field of stc before the ioctl
(range 0...n). The result is returned in form of a ratio with a 64 bit numerator
and a 32 bit denominator, so the real 90kHz STC value is stc-&#x003E;stc /
stc-&#x003E;base
.</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>SYNOPSIS
</para>
<informaltable><tgroup cols="1"><tbody><row><entry
align="char">
<para>int ioctl( int fd, int request = DMX_GET_STC, struct
dmx_stc &#x22C6;stc);</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>PARAMETERS
</para>
<informaltable><tgroup cols="2"><tbody><row><entry
align="char">
<para>int fd</para>
</entry><entry
align="char">
<para>File descriptor returned by a previous call to open().</para>
</entry>
</row><row><entry
align="char">
<para>int request</para>
</entry><entry
align="char">
<para>Equals DMX_GET_STC for this command.</para>
</entry>
</row><row><entry
align="char">
<para>struct dmx_stc *stc</para>
</entry><entry
align="char">
<para>Pointer to the location where the stc is to be stored.</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>ERRORS
</para>
<informaltable><tgroup cols="2"><tbody><row><entry
align="char">
<para>EBADF</para>
</entry><entry
align="char">
<para>fd is not a valid file descriptor.</para>
</entry>
</row><row><entry
align="char">
<para>EFAULT</para>
</entry><entry
align="char">
<para>stc points to an invalid address.</para>
</entry>
</row><row><entry
align="char">
<para>EINVAL</para>
</entry><entry
align="char">
<para>Invalid stc number.</para>
</entry>
</row></tbody></tgroup></informaltable>
</section></section>

79
Documentation/DocBook/dvb/dvbapi.xml Normal file
View File

@ -0,0 +1,79 @@
<partinfo>
<authorgroup>
<author>
<firstname>Ralph</firstname>
<surname>Metzler</surname>
<othername role="mi">J. K.</othername>
<affiliation><address><email>rjkm@metzlerbros.de</email></address></affiliation>
</author>
<author>
<firstname>Marcus</firstname>
<surname>Metzler</surname>
<othername role="mi">O. C.</othername>
<affiliation><address><email>rjkm@metzlerbros.de</email></address></affiliation>
</author>
<author>
<firstname>Mauro</firstname>
<surname>Chehab</surname>
<othername role="mi">Carvalho</othername>
<affiliation><address><email>mchehab@redhat.com</email></address></affiliation>
<contrib>Ported document to Docbook XML.</contrib>
</author>
</authorgroup>
<copyright>
<year>2002</year>
<year>2003</year>
<year>2009</year>
<holder>Convergence GmbH</holder>
</copyright>
<revhistory>
<!-- Put document revisions here, newest first. -->
<revision>
<revnumber>2.0.0</revnumber>
<date>2009-09-06</date>
<authorinitials>mcc</authorinitials>
<revremark>Conversion from LaTex to DocBook XML. The
contents is the same as the original LaTex version.</revremark>
</revision>
<revision>
<revnumber>1.0.0</revnumber>
<date>2003-07-24</date>
<authorinitials>rjkm</authorinitials>
<revremark>Initial revision on LaTEX.</revremark>
</revision>
</revhistory>
</partinfo>
<title>LINUX DVB API</title>
<subtitle>Version 3</subtitle>
<!-- ADD THE CHAPTERS HERE -->
<chapter id="dvb_introdution">
&sub-intro;
</chapter>
<chapter id="dvb_frontend">
&sub-frontend;
</chapter>
<chapter id="dvb_demux">
&sub-demux;
</chapter>
<chapter id="dvb_video">
&sub-video;
</chapter>
<chapter id="dvb_audio">
&sub-audio;
</chapter>
<chapter id="dvb_ca">
&sub-ca;
</chapter>
<chapter id="dvb_net">
&sub-net;
</chapter>
<chapter id="dvb_kdapi">
&sub-kdapi;
</chapter>
<chapter id="dvb_examples">
&sub-examples;
</chapter>
<!-- END OF CHAPTERS -->

BIN
Documentation/DocBook/dvb/dvbstb.pdf Normal file
View File

Binary file not shown.

BIN
Documentation/DocBook/dvb/dvbstb.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 22 KiB

365
Documentation/DocBook/dvb/examples.xml Normal file
View File

@ -0,0 +1,365 @@
<title>Examples</title>
<para>In this section we would like to present some examples for using the DVB API.
</para>
<para>Maintainer note: This section is out of date. Please refer to the sample programs packaged
with the driver distribution from <emphasis role="tt">http://linuxtv.org/</emphasis>.
</para>
<section id="tuning">
<title>Tuning</title>
<para>We will start with a generic tuning subroutine that uses the frontend and SEC, as well as
the demux devices. The example is given for QPSK tuners, but can easily be adjusted for
QAM.
</para>
<programlisting>
#include &#x003C;sys/ioctl.h&#x003E;
#include &#x003C;stdio.h&#x003E;
#include &#x003C;stdint.h&#x003E;
#include &#x003C;sys/types.h&#x003E;
#include &#x003C;sys/stat.h&#x003E;
#include &#x003C;fcntl.h&#x003E;
#include &#x003C;time.h&#x003E;
#include &#x003C;unistd.h&#x003E;
#include &#x003C;linux/dvb/dmx.h&#x003E;
#include &#x003C;linux/dvb/frontend.h&#x003E;
#include &#x003C;linux/dvb/sec.h&#x003E;
#include &#x003C;sys/poll.h&#x003E;
#define DMX "/dev/dvb/adapter0/demux1"
#define FRONT "/dev/dvb/adapter0/frontend1"
#define SEC "/dev/dvb/adapter0/sec1"
/&#x22C6; routine for checking if we have a signal and other status information&#x22C6;/
int FEReadStatus(int fd, fe_status_t &#x22C6;stat)
{
int ans;
if ( (ans = ioctl(fd,FE_READ_STATUS,stat) &#x003C; 0)){
perror("FE READ STATUS: ");
return -1;
}
if (&#x22C6;stat &amp; FE_HAS_POWER)
printf("FE HAS POWER\n");
if (&#x22C6;stat &amp; FE_HAS_SIGNAL)
printf("FE HAS SIGNAL\n");
if (&#x22C6;stat &amp; FE_SPECTRUM_INV)
printf("SPEKTRUM INV\n");
return 0;
}
/&#x22C6; tune qpsk &#x22C6;/
/&#x22C6; freq: frequency of transponder &#x22C6;/
/&#x22C6; vpid, apid, tpid: PIDs of video, audio and teletext TS packets &#x22C6;/
/&#x22C6; diseqc: DiSEqC address of the used LNB &#x22C6;/
/&#x22C6; pol: Polarisation &#x22C6;/
/&#x22C6; srate: Symbol Rate &#x22C6;/
/&#x22C6; fec. FEC &#x22C6;/
/&#x22C6; lnb_lof1: local frequency of lower LNB band &#x22C6;/
/&#x22C6; lnb_lof2: local frequency of upper LNB band &#x22C6;/
/&#x22C6; lnb_slof: switch frequency of LNB &#x22C6;/
int set_qpsk_channel(int freq, int vpid, int apid, int tpid,
int diseqc, int pol, int srate, int fec, int lnb_lof1,
int lnb_lof2, int lnb_slof)
{
struct secCommand scmd;
struct secCmdSequence scmds;
struct dmx_pes_filter_params pesFilterParams;
FrontendParameters frp;
struct pollfd pfd[1];
FrontendEvent event;
int demux1, demux2, demux3, front;
frequency = (uint32_t) freq;
symbolrate = (uint32_t) srate;
if((front = open(FRONT,O_RDWR)) &#x003C; 0){
perror("FRONTEND DEVICE: ");
return -1;
}
if((sec = open(SEC,O_RDWR)) &#x003C; 0){
perror("SEC DEVICE: ");
return -1;
}
if (demux1 &#x003C; 0){
if ((demux1=open(DMX, O_RDWR|O_NONBLOCK))
&#x003C; 0){
perror("DEMUX DEVICE: ");
return -1;
}
}
if (demux2 &#x003C; 0){
if ((demux2=open(DMX, O_RDWR|O_NONBLOCK))
&#x003C; 0){
perror("DEMUX DEVICE: ");
return -1;
}
}
if (demux3 &#x003C; 0){
if ((demux3=open(DMX, O_RDWR|O_NONBLOCK))
&#x003C; 0){
perror("DEMUX DEVICE: ");
return -1;
}
}
if (freq &#x003C; lnb_slof) {
frp.Frequency = (freq - lnb_lof1);
scmds.continuousTone = SEC_TONE_OFF;
} else {
frp.Frequency = (freq - lnb_lof2);
scmds.continuousTone = SEC_TONE_ON;
}
frp.Inversion = INVERSION_AUTO;
if (pol) scmds.voltage = SEC_VOLTAGE_18;
else scmds.voltage = SEC_VOLTAGE_13;
scmd.type=0;
scmd.u.diseqc.addr=0x10;
scmd.u.diseqc.cmd=0x38;
scmd.u.diseqc.numParams=1;
scmd.u.diseqc.params[0] = 0xF0 | ((diseqc &#x22C6; 4) &amp; 0x0F) |
(scmds.continuousTone == SEC_TONE_ON ? 1 : 0) |
(scmds.voltage==SEC_VOLTAGE_18 ? 2 : 0);
scmds.miniCommand=SEC_MINI_NONE;
scmds.numCommands=1;
scmds.commands=&amp;scmd;
if (ioctl(sec, SEC_SEND_SEQUENCE, &amp;scmds) &#x003C; 0){
perror("SEC SEND: ");
return -1;
}
if (ioctl(sec, SEC_SEND_SEQUENCE, &amp;scmds) &#x003C; 0){
perror("SEC SEND: ");
return -1;
}
frp.u.qpsk.SymbolRate = srate;
frp.u.qpsk.FEC_inner = fec;
if (ioctl(front, FE_SET_FRONTEND, &amp;frp) &#x003C; 0){
perror("QPSK TUNE: ");
return -1;
}
pfd[0].fd = front;
pfd[0].events = POLLIN;
if (poll(pfd,1,3000)){
if (pfd[0].revents &amp; POLLIN){
printf("Getting QPSK event\n");
if ( ioctl(front, FE_GET_EVENT, &amp;event)
== -EOVERFLOW){
perror("qpsk get event");
return -1;
}
printf("Received ");
switch(event.type){
case FE_UNEXPECTED_EV:
printf("unexpected event\n");
return -1;
case FE_FAILURE_EV:
printf("failure event\n");
return -1;
case FE_COMPLETION_EV:
printf("completion event\n");
}
}
}
pesFilterParams.pid = vpid;
pesFilterParams.input = DMX_IN_FRONTEND;
pesFilterParams.output = DMX_OUT_DECODER;
pesFilterParams.pes_type = DMX_PES_VIDEO;
pesFilterParams.flags = DMX_IMMEDIATE_START;
if (ioctl(demux1, DMX_SET_PES_FILTER, &amp;pesFilterParams) &#x003C; 0){
perror("set_vpid");
return -1;
}
pesFilterParams.pid = apid;
pesFilterParams.input = DMX_IN_FRONTEND;
pesFilterParams.output = DMX_OUT_DECODER;
pesFilterParams.pes_type = DMX_PES_AUDIO;
pesFilterParams.flags = DMX_IMMEDIATE_START;
if (ioctl(demux2, DMX_SET_PES_FILTER, &amp;pesFilterParams) &#x003C; 0){
perror("set_apid");
return -1;
}
pesFilterParams.pid = tpid;
pesFilterParams.input = DMX_IN_FRONTEND;
pesFilterParams.output = DMX_OUT_DECODER;
pesFilterParams.pes_type = DMX_PES_TELETEXT;
pesFilterParams.flags = DMX_IMMEDIATE_START;
if (ioctl(demux3, DMX_SET_PES_FILTER, &amp;pesFilterParams) &#x003C; 0){
perror("set_tpid");
return -1;
}
return has_signal(fds);
}
</programlisting>
<para>The program assumes that you are using a universal LNB and a standard DiSEqC
switch with up to 4 addresses. Of course, you could build in some more checking if
tuning was successful and maybe try to repeat the tuning process. Depending on the
external hardware, i.e. LNB and DiSEqC switch, and weather conditions this may be
necessary.
</para>
</section>
<section id="the_dvr_device">
<title>The DVR device</title>
<para>The following program code shows how to use the DVR device for recording.
</para>
<programlisting>
#include &#x003C;sys/ioctl.h&#x003E;
#include &#x003C;stdio.h&#x003E;
#include &#x003C;stdint.h&#x003E;
#include &#x003C;sys/types.h&#x003E;
#include &#x003C;sys/stat.h&#x003E;
#include &#x003C;fcntl.h&#x003E;
#include &#x003C;time.h&#x003E;
#include &#x003C;unistd.h&#x003E;
#include &#x003C;linux/dvb/dmx.h&#x003E;
#include &#x003C;linux/dvb/video.h&#x003E;
#include &#x003C;sys/poll.h&#x003E;
#define DVR "/dev/dvb/adapter0/dvr1"
#define AUDIO "/dev/dvb/adapter0/audio1"
#define VIDEO "/dev/dvb/adapter0/video1"
#define BUFFY (188&#x22C6;20)
#define MAX_LENGTH (1024&#x22C6;1024&#x22C6;5) /&#x22C6; record 5MB &#x22C6;/
/&#x22C6; switch the demuxes to recording, assuming the transponder is tuned &#x22C6;/
/&#x22C6; demux1, demux2: file descriptor of video and audio filters &#x22C6;/
/&#x22C6; vpid, apid: PIDs of video and audio channels &#x22C6;/
int switch_to_record(int demux1, int demux2, uint16_t vpid, uint16_t apid)
{
struct dmx_pes_filter_params pesFilterParams;
if (demux1 &#x003C; 0){
if ((demux1=open(DMX, O_RDWR|O_NONBLOCK))
&#x003C; 0){
perror("DEMUX DEVICE: ");
return -1;
}
}
if (demux2 &#x003C; 0){
if ((demux2=open(DMX, O_RDWR|O_NONBLOCK))
&#x003C; 0){
perror("DEMUX DEVICE: ");
return -1;
}
}
pesFilterParams.pid = vpid;
pesFilterParams.input = DMX_IN_FRONTEND;
pesFilterParams.output = DMX_OUT_TS_TAP;
pesFilterParams.pes_type = DMX_PES_VIDEO;
pesFilterParams.flags = DMX_IMMEDIATE_START;
if (ioctl(demux1, DMX_SET_PES_FILTER, &amp;pesFilterParams) &#x003C; 0){
perror("DEMUX DEVICE");
return -1;
}
pesFilterParams.pid = apid;
pesFilterParams.input = DMX_IN_FRONTEND;
pesFilterParams.output = DMX_OUT_TS_TAP;
pesFilterParams.pes_type = DMX_PES_AUDIO;
pesFilterParams.flags = DMX_IMMEDIATE_START;
if (ioctl(demux2, DMX_SET_PES_FILTER, &amp;pesFilterParams) &#x003C; 0){
perror("DEMUX DEVICE");
return -1;
}
return 0;
}
/&#x22C6; start recording MAX_LENGTH , assuming the transponder is tuned &#x22C6;/
/&#x22C6; demux1, demux2: file descriptor of video and audio filters &#x22C6;/
/&#x22C6; vpid, apid: PIDs of video and audio channels &#x22C6;/
int record_dvr(int demux1, int demux2, uint16_t vpid, uint16_t apid)
{
int i;
int len;
int written;
uint8_t buf[BUFFY];
uint64_t length;
struct pollfd pfd[1];
int dvr, dvr_out;
/&#x22C6; open dvr device &#x22C6;/
if ((dvr = open(DVR, O_RDONLY|O_NONBLOCK)) &#x003C; 0){
perror("DVR DEVICE");
return -1;
}
/&#x22C6; switch video and audio demuxes to dvr &#x22C6;/
printf ("Switching dvr on\n");
i = switch_to_record(demux1, demux2, vpid, apid);
printf("finished: ");
printf("Recording %2.0f MB of test file in TS format\n",
MAX_LENGTH/(1024.0&#x22C6;1024.0));
length = 0;
/&#x22C6; open output file &#x22C6;/
if ((dvr_out = open(DVR_FILE,O_WRONLY|O_CREAT
|O_TRUNC, S_IRUSR|S_IWUSR
|S_IRGRP|S_IWGRP|S_IROTH|
S_IWOTH)) &#x003C; 0){
perror("Can't open file for dvr test");
return -1;
}
pfd[0].fd = dvr;
pfd[0].events = POLLIN;
/&#x22C6; poll for dvr data and write to file &#x22C6;/
while (length &#x003C; MAX_LENGTH ) {
if (poll(pfd,1,1)){
if (pfd[0].revents &amp; POLLIN){
len = read(dvr, buf, BUFFY);
if (len &#x003C; 0){
perror("recording");
return -1;
}
if (len &#x003E; 0){
written = 0;
while (written &#x003C; len)
written +=
write (dvr_out,
buf, len);
length += len;
printf("written %2.0f MB\r",
length/1024./1024.);
}
}
}
}
return 0;
}
</programlisting>
</section>

1765
Documentation/DocBook/dvb/frontend.xml Normal file
View File

File diff suppressed because it is too large Load Diff

191
Documentation/DocBook/dvb/intro.xml Normal file
View File

@ -0,0 +1,191 @@
<title>Introduction</title>
<section id="requisites">
<title>What you need to know</title>
<para>The reader of this document is required to have some knowledge in
the area of digital video broadcasting (DVB) and should be familiar with
part I of the MPEG2 specification ISO/IEC 13818 (aka ITU-T H.222), i.e
you should know what a program/transport stream (PS/TS) is and what is
meant by a packetized elementary stream (PES) or an I-frame.</para>
<para>Various DVB standards documents are available from
<emphasis role="tt">http://www.dvb.org/</emphasis> and/or
<emphasis role="tt">http://www.etsi.org/</emphasis>.</para>
<para>It is also necessary to know how to access unix/linux devices and
how to use ioctl calls. This also includes the knowledge of C or C++.
</para>
</section>
<section id="history">
<title>History</title>
<para>The first API for DVB cards we used at Convergence in late 1999
was an extension of the Video4Linux API which was primarily developed
for frame grabber cards. As such it was not really well suited to be
used for DVB cards and their new features like recording MPEG streams
and filtering several section and PES data streams at the same time.
</para>
<para>In early 2000, we were approached by Nokia with a proposal for a
new standard Linux DVB API. As a commitment to the development of
terminals based on open standards, Nokia and Convergence made it
available to all Linux developers and published it on <emphasis
role="tt">http://www.linuxtv.org/</emphasis> in September 2000.
Convergence is the maintainer of the Linux DVB API. Together with the
LinuxTV community (i.e. you, the reader of this document), the Linux DVB
API will be constantly reviewed and improved. With the Linux driver for
the Siemens/Hauppauge DVB PCI card Convergence provides a first
implementation of the Linux DVB API.</para>
</section>
<section id="overview">
<title>Overview</title>
<figure id="stb_components">
<title>Components of a DVB card/STB</title>
<mediaobject>
<imageobject>
<imagedata fileref="dvbstb.pdf" format="PS" />
</imageobject>
<imageobject>
<imagedata fileref="dvbstb.png" format="PNG" />
</imageobject>
</mediaobject>
</figure>
<para>A DVB PCI card or DVB set-top-box (STB) usually consists of the
following main hardware components: </para>
<itemizedlist>
<listitem>
<para>Frontend consisting of tuner and DVB demodulator</para>
<para>Here the raw signal reaches the DVB hardware from a satellite dish
or antenna or directly from cable. The frontend down-converts and
demodulates this signal into an MPEG transport stream (TS). In case of a
satellite frontend, this includes a facility for satellite equipment
control (SEC), which allows control of LNB polarization, multi feed
switches or dish rotors.</para>
</listitem>
<listitem>
<para>Conditional Access (CA) hardware like CI adapters and smartcard slots
</para>
<para>The complete TS is passed through the CA hardware. Programs to
which the user has access (controlled by the smart card) are decoded in
real time and re-inserted into the TS.</para>
</listitem>
<listitem>
<para>Demultiplexer which filters the incoming DVB stream</para>
<para>The demultiplexer splits the TS into its components like audio and
video streams. Besides usually several of such audio and video streams
it also contains data streams with information about the programs
offered in this or other streams of the same provider.</para>
</listitem>
<listitem>
<para>MPEG2 audio and video decoder</para>
<para>The main targets of the demultiplexer are the MPEG2 audio and
video decoders. After decoding they pass on the uncompressed audio and
video to the computer screen or (through a PAL/NTSC encoder) to a TV
set.</para>
</listitem>
</itemizedlist>
<para><xref linkend="stb_components" /> shows a crude schematic of the control and data flow
between those components.</para>
<para>On a DVB PCI card not all of these have to be present since some
functionality can be provided by the main CPU of the PC (e.g. MPEG
picture and sound decoding) or is not needed (e.g. for data-only uses
like &#8220;internet over satellite&#8221;). Also not every card or STB
provides conditional access hardware.</para>
</section>
<section id="dvb_devices">
<title>Linux DVB Devices</title>
<para>The Linux DVB API lets you control these hardware components
through currently six Unix-style character devices for video, audio,
frontend, demux, CA and IP-over-DVB networking. The video and audio
devices control the MPEG2 decoder hardware, the frontend device the
tuner and the DVB demodulator. The demux device gives you control over
the PES and section filters of the hardware. If the hardware does not
support filtering these filters can be implemented in software. Finally,
the CA device controls all the conditional access capabilities of the
hardware. It can depend on the individual security requirements of the
platform, if and how many of the CA functions are made available to the
application through this device.</para>
<para>All devices can be found in the <emphasis role="tt">/dev</emphasis>
tree under <emphasis role="tt">/dev/dvb</emphasis>. The individual devices
are called:</para>
<itemizedlist>
<listitem>
<para><emphasis role="tt">/dev/dvb/adapterN/audioM</emphasis>,</para>
</listitem>
<listitem>
<para><emphasis role="tt">/dev/dvb/adapterN/videoM</emphasis>,</para>
</listitem>
<listitem>
<para><emphasis role="tt">/dev/dvb/adapterN/frontendM</emphasis>,</para>
</listitem>
<listitem>
<para><emphasis role="tt">/dev/dvb/adapterN/netM</emphasis>,</para>
</listitem>
<listitem>
<para><emphasis role="tt">/dev/dvb/adapterN/demuxM</emphasis>,</para>
</listitem>
<listitem>
<para><emphasis role="tt">/dev/dvb/adapterN/caM</emphasis>,</para></listitem></itemizedlist>
<para>where N enumerates the DVB PCI cards in a system starting
from&#x00A0;0, and M enumerates the devices of each type within each
adapter, starting from&#x00A0;0, too. We will omit the &#8220;<emphasis
role="tt">/dev/dvb/adapterN/</emphasis>&#8221; in the further dicussion
of these devices. The naming scheme for the devices is the same wheter
devfs is used or not.</para>
<para>More details about the data structures and function calls of all
the devices are described in the following chapters.</para>
</section>
<section id="include_files">
<title>API include files</title>
<para>For each of the DVB devices a corresponding include file exists.
The DVB API include files should be included in application sources with
a partial path like:</para>
<programlisting>
#include &#x003C;linux/dvb/frontend.h&#x003E;
</programlisting>
<para>To enable applications to support different API version, an
additional include file <emphasis
role="tt">linux/dvb/version.h</emphasis> exists, which defines the
constant <emphasis role="tt">DVB_API_VERSION</emphasis>. This document
describes <emphasis role="tt">DVB_API_VERSION&#x00A0;3</emphasis>.
</para>
</section>

2309
Documentation/DocBook/dvb/kdapi.xml Normal file
View File

File diff suppressed because it is too large Load Diff

12
Documentation/DocBook/dvb/net.xml Normal file
View File

@ -0,0 +1,12 @@
<title>DVB Network API</title>
<para>The DVB net device enables feeding of MPE (multi protocol encapsulation) packets
received via DVB into the Linux network protocol stack, e.g. for internet via satellite
applications. It can be accessed through <emphasis role="tt">/dev/dvb/adapter0/net0</emphasis>. Data types and
and ioctl definitions can be accessed by including <emphasis role="tt">linux/dvb/net.h</emphasis> in your
application.
</para>
<section id="dvb_net_types">
<title>DVB Net Data Types</title>
<para>To be written&#x2026;
</para>
</section>

1971
Documentation/DocBook/dvb/video.xml Normal file
View File

File diff suppressed because it is too large Load Diff

363
Documentation/DocBook/media-entities.xml Normal file
View File

@ -0,0 +1,363 @@
<!-- Generated file! Do not edit. -->
<!-- Functions -->
<!ENTITY func-close "<link linkend='func-close'><function>close()</function></link>">
<!ENTITY func-ioctl "<link linkend='func-ioctl'><function>ioctl()</function></link>">
<!ENTITY func-mmap "<link linkend='func-mmap'><function>mmap()</function></link>">
<!ENTITY func-munmap "<link linkend='func-munmap'><function>munmap()</function></link>">
<!ENTITY func-open "<link linkend='func-open'><function>open()</function></link>">
<!ENTITY func-poll "<link linkend='func-poll'><function>poll()</function></link>">
<!ENTITY func-read "<link linkend='func-read'><function>read()</function></link>">
<!ENTITY func-select "<link linkend='func-select'><function>select()</function></link>">
<!ENTITY func-write "<link linkend='func-write'><function>write()</function></link>">
<!-- Ioctls -->
<!ENTITY VIDIOC-CROPCAP "<link linkend='vidioc-cropcap'><constant>VIDIOC_CROPCAP</constant></link>">
<!ENTITY VIDIOC-DBG-G-CHIP-IDENT "<link linkend='vidioc-dbg-g-chip-ident'><constant>VIDIOC_DBG_G_CHIP_IDENT</constant></link>">
<!ENTITY VIDIOC-DBG-G-REGISTER "<link linkend='vidioc-dbg-g-register'><constant>VIDIOC_DBG_G_REGISTER</constant></link>">
<!ENTITY VIDIOC-DBG-S-REGISTER "<link linkend='vidioc-dbg-g-register'><constant>VIDIOC_DBG_S_REGISTER</constant></link>">
<!ENTITY VIDIOC-DQBUF "<link linkend='vidioc-qbuf'><constant>VIDIOC_DQBUF</constant></link>">
<!ENTITY VIDIOC-ENCODER-CMD "<link linkend='vidioc-encoder-cmd'><constant>VIDIOC_ENCODER_CMD</constant></link>">
<!ENTITY VIDIOC-ENUMAUDIO "<link linkend='vidioc-enumaudio'><constant>VIDIOC_ENUMAUDIO</constant></link>">
<!ENTITY VIDIOC-ENUMAUDOUT "<link linkend='vidioc-enumaudioout'><constant>VIDIOC_ENUMAUDOUT</constant></link>">
<!ENTITY VIDIOC-ENUMINPUT "<link linkend='vidioc-enuminput'><constant>VIDIOC_ENUMINPUT</constant></link>">
<!ENTITY VIDIOC-ENUMOUTPUT "<link linkend='vidioc-enumoutput'><constant>VIDIOC_ENUMOUTPUT</constant></link>">
<!ENTITY VIDIOC-ENUMSTD "<link linkend='vidioc-enumstd'><constant>VIDIOC_ENUMSTD</constant></link>">
<!ENTITY VIDIOC-ENUM-FMT "<link linkend='vidioc-enum-fmt'><constant>VIDIOC_ENUM_FMT</constant></link>">
<!ENTITY VIDIOC-ENUM-FRAMEINTERVALS "<link linkend='vidioc-enum-frameintervals'><constant>VIDIOC_ENUM_FRAMEINTERVALS</constant></link>">
<!ENTITY VIDIOC-ENUM-FRAMESIZES "<link linkend='vidioc-enum-framesizes'><constant>VIDIOC_ENUM_FRAMESIZES</constant></link>">
<!ENTITY VIDIOC-G-AUDIO "<link linkend='vidioc-g-audio'><constant>VIDIOC_G_AUDIO</constant></link>">
<!ENTITY VIDIOC-G-AUDOUT "<link linkend='vidioc-g-audioout'><constant>VIDIOC_G_AUDOUT</constant></link>">
<!ENTITY VIDIOC-G-CROP "<link linkend='vidioc-g-crop'><constant>VIDIOC_G_CROP</constant></link>">
<!ENTITY VIDIOC-G-CTRL "<link linkend='vidioc-g-ctrl'><constant>VIDIOC_G_CTRL</constant></link>">
<!ENTITY VIDIOC-G-ENC-INDEX "<link linkend='vidioc-g-enc-index'><constant>VIDIOC_G_ENC_INDEX</constant></link>">
<!ENTITY VIDIOC-G-EXT-CTRLS "<link linkend='vidioc-g-ext-ctrls'><constant>VIDIOC_G_EXT_CTRLS</constant></link>">
<!ENTITY VIDIOC-G-FBUF "<link linkend='vidioc-g-fbuf'><constant>VIDIOC_G_FBUF</constant></link>">
<!ENTITY VIDIOC-G-FMT "<link linkend='vidioc-g-fmt'><constant>VIDIOC_G_FMT</constant></link>">
<!ENTITY VIDIOC-G-FREQUENCY "<link linkend='vidioc-g-frequency'><constant>VIDIOC_G_FREQUENCY</constant></link>">
<!ENTITY VIDIOC-G-INPUT "<link linkend='vidioc-g-input'><constant>VIDIOC_G_INPUT</constant></link>">
<!ENTITY VIDIOC-G-JPEGCOMP "<link linkend='vidioc-g-jpegcomp'><constant>VIDIOC_G_JPEGCOMP</constant></link>">
<!ENTITY VIDIOC-G-MPEGCOMP "<link linkend=''><constant>VIDIOC_G_MPEGCOMP</constant></link>">
<!ENTITY VIDIOC-G-MODULATOR "<link linkend='vidioc-g-modulator'><constant>VIDIOC_G_MODULATOR</constant></link>">
<!ENTITY VIDIOC-G-OUTPUT "<link linkend='vidioc-g-output'><constant>VIDIOC_G_OUTPUT</constant></link>">
<!ENTITY VIDIOC-G-PARM "<link linkend='vidioc-g-parm'><constant>VIDIOC_G_PARM</constant></link>">
<!ENTITY VIDIOC-G-PRIORITY "<link linkend='vidioc-g-priority'><constant>VIDIOC_G_PRIORITY</constant></link>">
<!ENTITY VIDIOC-G-SLICED-VBI-CAP "<link linkend='vidioc-g-sliced-vbi-cap'><constant>VIDIOC_G_SLICED_VBI_CAP</constant></link>">
<!ENTITY VIDIOC-G-STD "<link linkend='vidioc-g-std'><constant>VIDIOC_G_STD</constant></link>">
<!ENTITY VIDIOC-G-TUNER "<link linkend='vidioc-g-tuner'><constant>VIDIOC_G_TUNER</constant></link>">
<!ENTITY VIDIOC-LOG-STATUS "<link linkend='vidioc-log-status'><constant>VIDIOC_LOG_STATUS</constant></link>">
<!ENTITY VIDIOC-OVERLAY "<link linkend='vidioc-overlay'><constant>VIDIOC_OVERLAY</constant></link>">
<!ENTITY VIDIOC-QBUF "<link linkend='vidioc-qbuf'><constant>VIDIOC_QBUF</constant></link>">
<!ENTITY VIDIOC-QUERYBUF "<link linkend='vidioc-querybuf'><constant>VIDIOC_QUERYBUF</constant></link>">
<!ENTITY VIDIOC-QUERYCAP "<link linkend='vidioc-querycap'><constant>VIDIOC_QUERYCAP</constant></link>">
<!ENTITY VIDIOC-QUERYCTRL "<link linkend='vidioc-queryctrl'><constant>VIDIOC_QUERYCTRL</constant></link>">
<!ENTITY VIDIOC-QUERYMENU "<link linkend='vidioc-queryctrl'><constant>VIDIOC_QUERYMENU</constant></link>">
<!ENTITY VIDIOC-QUERYSTD "<link linkend='vidioc-querystd'><constant>VIDIOC_QUERYSTD</constant></link>">
<!ENTITY VIDIOC-REQBUFS "<link linkend='vidioc-reqbufs'><constant>VIDIOC_REQBUFS</constant></link>">
<!ENTITY VIDIOC-STREAMOFF "<link linkend='vidioc-streamon'><constant>VIDIOC_STREAMOFF</constant></link>">
<!ENTITY VIDIOC-STREAMON "<link linkend='vidioc-streamon'><constant>VIDIOC_STREAMON</constant></link>">
<!ENTITY VIDIOC-S-AUDIO "<link linkend='vidioc-g-audio'><constant>VIDIOC_S_AUDIO</constant></link>">
<!ENTITY VIDIOC-S-AUDOUT "<link linkend='vidioc-g-audioout'><constant>VIDIOC_S_AUDOUT</constant></link>">
<!ENTITY VIDIOC-S-CROP "<link linkend='vidioc-g-crop'><constant>VIDIOC_S_CROP</constant></link>">
<!ENTITY VIDIOC-S-CTRL "<link linkend='vidioc-g-ctrl'><constant>VIDIOC_S_CTRL</constant></link>">
<!ENTITY VIDIOC-S-EXT-CTRLS "<link linkend='vidioc-g-ext-ctrls'><constant>VIDIOC_S_EXT_CTRLS</constant></link>">
<!ENTITY VIDIOC-S-FBUF "<link linkend='vidioc-g-fbuf'><constant>VIDIOC_S_FBUF</constant></link>">
<!ENTITY VIDIOC-S-FMT "<link linkend='vidioc-g-fmt'><constant>VIDIOC_S_FMT</constant></link>">
<!ENTITY VIDIOC-S-FREQUENCY "<link linkend='vidioc-g-frequency'><constant>VIDIOC_S_FREQUENCY</constant></link>">
<!ENTITY VIDIOC-S-HW-FREQ-SEEK "<link linkend='vidioc-s-hw-freq-seek'><constant>VIDIOC_S_HW_FREQ_SEEK</constant></link>">
<!ENTITY VIDIOC-S-INPUT "<link linkend='vidioc-g-input'><constant>VIDIOC_S_INPUT</constant></link>">
<!ENTITY VIDIOC-S-JPEGCOMP "<link linkend='vidioc-g-jpegcomp'><constant>VIDIOC_S_JPEGCOMP</constant></link>">
<!ENTITY VIDIOC-S-MPEGCOMP "<link linkend=''><constant>VIDIOC_S_MPEGCOMP</constant></link>">
<!ENTITY VIDIOC-S-MODULATOR "<link linkend='vidioc-g-modulator'><constant>VIDIOC_S_MODULATOR</constant></link>">
<!ENTITY VIDIOC-S-OUTPUT "<link linkend='vidioc-g-output'><constant>VIDIOC_S_OUTPUT</constant></link>">
<!ENTITY VIDIOC-S-PARM "<link linkend='vidioc-g-parm'><constant>VIDIOC_S_PARM</constant></link>">
<!ENTITY VIDIOC-S-PRIORITY "<link linkend='vidioc-g-priority'><constant>VIDIOC_S_PRIORITY</constant></link>">
<!ENTITY VIDIOC-S-STD "<link linkend='vidioc-g-std'><constant>VIDIOC_S_STD</constant></link>">
<!ENTITY VIDIOC-S-TUNER "<link linkend='vidioc-g-tuner'><constant>VIDIOC_S_TUNER</constant></link>">
<!ENTITY VIDIOC-TRY-ENCODER-CMD "<link linkend='vidioc-encoder-cmd'><constant>VIDIOC_TRY_ENCODER_CMD</constant></link>">
<!ENTITY VIDIOC-TRY-EXT-CTRLS "<link linkend='vidioc-g-ext-ctrls'><constant>VIDIOC_TRY_EXT_CTRLS</constant></link>">
<!ENTITY VIDIOC-TRY-FMT "<link linkend='vidioc-g-fmt'><constant>VIDIOC_TRY_FMT</constant></link>">
<!-- Types -->
<!ENTITY v4l2-std-id "<link linkend='v4l2-std-id'>v4l2_std_id</link>">
<!-- Enums -->
<!ENTITY v4l2-buf-type "enum&nbsp;<link linkend='v4l2-buf-type'>v4l2_buf_type</link>">
<!ENTITY v4l2-colorspace "enum&nbsp;<link linkend='v4l2-colorspace'>v4l2_colorspace</link>">
<!ENTITY v4l2-ctrl-type "enum&nbsp;<link linkend='v4l2-ctrl-type'>v4l2_ctrl_type</link>">
<!ENTITY v4l2-exposure-auto-type "enum&nbsp;<link linkend='v4l2-exposure-auto-type'>v4l2_exposure_auto_type</link>">
<!ENTITY v4l2-field "enum&nbsp;<link linkend='v4l2-field'>v4l2_field</link>">
<!ENTITY v4l2-frmivaltypes "enum&nbsp;<link linkend='v4l2-frmivaltypes'>v4l2_frmivaltypes</link>">
<!ENTITY v4l2-frmsizetypes "enum&nbsp;<link linkend='v4l2-frmsizetypes'>v4l2_frmsizetypes</link>">
<!ENTITY v4l2-memory "enum&nbsp;<link linkend='v4l2-memory'>v4l2_memory</link>">
<!ENTITY v4l2-mpeg-audio-ac3-bitrate "enum&nbsp;<link linkend='v4l2-mpeg-audio-ac3-bitrate'>v4l2_mpeg_audio_ac3_bitrate</link>">
<!ENTITY v4l2-mpeg-audio-crc "enum&nbsp;<link linkend='v4l2-mpeg-audio-crc'>v4l2_mpeg_audio_crc</link>">
<!ENTITY v4l2-mpeg-audio-emphasis "enum&nbsp;<link linkend='v4l2-mpeg-audio-emphasis'>v4l2_mpeg_audio_emphasis</link>">
<!ENTITY v4l2-mpeg-audio-encoding "enum&nbsp;<link linkend='v4l2-mpeg-audio-encoding'>v4l2_mpeg_audio_encoding</link>">
<!ENTITY v4l2-mpeg-audio-l1-bitrate "enum&nbsp;<link linkend='v4l2-mpeg-audio-l1-bitrate'>v4l2_mpeg_audio_l1_bitrate</link>">
<!ENTITY v4l2-mpeg-audio-l2-bitrate "enum&nbsp;<link linkend='v4l2-mpeg-audio-l2-bitrate'>v4l2_mpeg_audio_l2_bitrate</link>">
<!ENTITY v4l2-mpeg-audio-l3-bitrate "enum&nbsp;<link linkend='v4l2-mpeg-audio-l3-bitrate'>v4l2_mpeg_audio_l3_bitrate</link>">
<!ENTITY v4l2-mpeg-audio-mode "enum&nbsp;<link linkend='v4l2-mpeg-audio-mode'>v4l2_mpeg_audio_mode</link>">
<!ENTITY v4l2-mpeg-audio-mode-extension "enum&nbsp;<link linkend='v4l2-mpeg-audio-mode-extension'>v4l2_mpeg_audio_mode_extension</link>">
<!ENTITY v4l2-mpeg-audio-sampling-freq "enum&nbsp;<link linkend='v4l2-mpeg-audio-sampling-freq'>v4l2_mpeg_audio_sampling_freq</link>">
<!ENTITY chroma-spatial-filter-type "enum&nbsp;<link linkend='chroma-spatial-filter-type'>v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type</link>">
<!ENTITY luma-spatial-filter-type "enum&nbsp;<link linkend='luma-spatial-filter-type'>v4l2_mpeg_cx2341x_video_luma_spatial_filter_type</link>">
<!ENTITY v4l2-mpeg-cx2341x-video-median-filter-type "enum&nbsp;<link linkend='v4l2-mpeg-cx2341x-video-median-filter-type'>v4l2_mpeg_cx2341x_video_median_filter_type</link>">
<!ENTITY v4l2-mpeg-cx2341x-video-spatial-filter-mode "enum&nbsp;<link linkend='v4l2-mpeg-cx2341x-video-spatial-filter-mode'>v4l2_mpeg_cx2341x_video_spatial_filter_mode</link>">
<!ENTITY v4l2-mpeg-cx2341x-video-temporal-filter-mode "enum&nbsp;<link linkend='v4l2-mpeg-cx2341x-video-temporal-filter-mode'>v4l2_mpeg_cx2341x_video_temporal_filter_mode</link>">
<!ENTITY v4l2-mpeg-stream-type "enum&nbsp;<link linkend='v4l2-mpeg-stream-type'>v4l2_mpeg_stream_type</link>">
<!ENTITY v4l2-mpeg-stream-vbi-fmt "enum&nbsp;<link linkend='v4l2-mpeg-stream-vbi-fmt'>v4l2_mpeg_stream_vbi_fmt</link>">
<!ENTITY v4l2-mpeg-video-aspect "enum&nbsp;<link linkend='v4l2-mpeg-video-aspect'>v4l2_mpeg_video_aspect</link>">
<!ENTITY v4l2-mpeg-video-bitrate-mode "enum&nbsp;<link linkend='v4l2-mpeg-video-bitrate-mode'>v4l2_mpeg_video_bitrate_mode</link>">
<!ENTITY v4l2-mpeg-video-encoding "enum&nbsp;<link linkend='v4l2-mpeg-video-encoding'>v4l2_mpeg_video_encoding</link>">
<!ENTITY v4l2-power-line-frequency "enum&nbsp;<link linkend='v4l2-power-line-frequency'>v4l2_power_line_frequency</link>">
<!ENTITY v4l2-priority "enum&nbsp;<link linkend='v4l2-priority'>v4l2_priority</link>">
<!ENTITY v4l2-tuner-type "enum&nbsp;<link linkend='v4l2-tuner-type'>v4l2_tuner_type</link>">
<!ENTITY v4l2-preemphasis "enum&nbsp;<link linkend='v4l2-preemphasis'>v4l2_preemphasis</link>">
<!-- Structures -->
<!ENTITY v4l2-audio "struct&nbsp;<link linkend='v4l2-audio'>v4l2_audio</link>">
<!ENTITY v4l2-audioout "struct&nbsp;<link linkend='v4l2-audioout'>v4l2_audioout</link>">
<!ENTITY v4l2-buffer "struct&nbsp;<link linkend='v4l2-buffer'>v4l2_buffer</link>">
<!ENTITY v4l2-capability "struct&nbsp;<link linkend='v4l2-capability'>v4l2_capability</link>">
<!ENTITY v4l2-captureparm "struct&nbsp;<link linkend='v4l2-captureparm'>v4l2_captureparm</link>">
<!ENTITY v4l2-clip "struct&nbsp;<link linkend='v4l2-clip'>v4l2_clip</link>">
<!ENTITY v4l2-control "struct&nbsp;<link linkend='v4l2-control'>v4l2_control</link>">
<!ENTITY v4l2-crop "struct&nbsp;<link linkend='v4l2-crop'>v4l2_crop</link>">
<!ENTITY v4l2-cropcap "struct&nbsp;<link linkend='v4l2-cropcap'>v4l2_cropcap</link>">
<!ENTITY v4l2-dbg-chip-ident "struct&nbsp;<link linkend='v4l2-dbg-chip-ident'>v4l2_dbg_chip_ident</link>">
<!ENTITY v4l2-dbg-match "struct&nbsp;<link linkend='v4l2-dbg-match'>v4l2_dbg_match</link>">
<!ENTITY v4l2-dbg-register "struct&nbsp;<link linkend='v4l2-dbg-register'>v4l2_dbg_register</link>">
<!ENTITY v4l2-enc-idx "struct&nbsp;<link linkend='v4l2-enc-idx'>v4l2_enc_idx</link>">
<!ENTITY v4l2-enc-idx-entry "struct&nbsp;<link linkend='v4l2-enc-idx-entry'>v4l2_enc_idx_entry</link>">
<!ENTITY v4l2-encoder-cmd "struct&nbsp;<link linkend='v4l2-encoder-cmd'>v4l2_encoder_cmd</link>">
<!ENTITY v4l2-ext-control "struct&nbsp;<link linkend='v4l2-ext-control'>v4l2_ext_control</link>">
<!ENTITY v4l2-ext-controls "struct&nbsp;<link linkend='v4l2-ext-controls'>v4l2_ext_controls</link>">
<!ENTITY v4l2-fmtdesc "struct&nbsp;<link linkend='v4l2-fmtdesc'>v4l2_fmtdesc</link>">
<!ENTITY v4l2-format "struct&nbsp;<link linkend='v4l2-format'>v4l2_format</link>">
<!ENTITY v4l2-fract "struct&nbsp;<link linkend='v4l2-fract'>v4l2_fract</link>">
<!ENTITY v4l2-framebuffer "struct&nbsp;<link linkend='v4l2-framebuffer'>v4l2_framebuffer</link>">
<!ENTITY v4l2-frequency "struct&nbsp;<link linkend='v4l2-frequency'>v4l2_frequency</link>">
<!ENTITY v4l2-frmival-stepwise "struct&nbsp;<link linkend='v4l2-frmival-stepwise'>v4l2_frmival_stepwise</link>">
<!ENTITY v4l2-frmivalenum "struct&nbsp;<link linkend='v4l2-frmivalenum'>v4l2_frmivalenum</link>">
<!ENTITY v4l2-frmsize-discrete "struct&nbsp;<link linkend='v4l2-frmsize-discrete'>v4l2_frmsize_discrete</link>">
<!ENTITY v4l2-frmsize-stepwise "struct&nbsp;<link linkend='v4l2-frmsize-stepwise'>v4l2_frmsize_stepwise</link>">
<!ENTITY v4l2-frmsizeenum "struct&nbsp;<link linkend='v4l2-frmsizeenum'>v4l2_frmsizeenum</link>">
<!ENTITY v4l2-hw-freq-seek "struct&nbsp;<link linkend='v4l2-hw-freq-seek'>v4l2_hw_freq_seek</link>">
<!ENTITY v4l2-input "struct&nbsp;<link linkend='v4l2-input'>v4l2_input</link>">
<!ENTITY v4l2-jpegcompression "struct&nbsp;<link linkend='v4l2-jpegcompression'>v4l2_jpegcompression</link>">
<!ENTITY v4l2-modulator "struct&nbsp;<link linkend='v4l2-modulator'>v4l2_modulator</link>">
<!ENTITY v4l2-mpeg-vbi-fmt-ivtv "struct&nbsp;<link linkend='v4l2-mpeg-vbi-fmt-ivtv'>v4l2_mpeg_vbi_fmt_ivtv</link>">
<!ENTITY v4l2-output "struct&nbsp;<link linkend='v4l2-output'>v4l2_output</link>">
<!ENTITY v4l2-outputparm "struct&nbsp;<link linkend='v4l2-outputparm'>v4l2_outputparm</link>">
<!ENTITY v4l2-pix-format "struct&nbsp;<link linkend='v4l2-pix-format'>v4l2_pix_format</link>">
<!ENTITY v4l2-queryctrl "struct&nbsp;<link linkend='v4l2-queryctrl'>v4l2_queryctrl</link>">
<!ENTITY v4l2-querymenu "struct&nbsp;<link linkend='v4l2-querymenu'>v4l2_querymenu</link>">
<!ENTITY v4l2-rect "struct&nbsp;<link linkend='v4l2-rect'>v4l2_rect</link>">
<!ENTITY v4l2-requestbuffers "struct&nbsp;<link linkend='v4l2-requestbuffers'>v4l2_requestbuffers</link>">
<!ENTITY v4l2-sliced-vbi-cap "struct&nbsp;<link linkend='v4l2-sliced-vbi-cap'>v4l2_sliced_vbi_cap</link>">
<!ENTITY v4l2-sliced-vbi-data "struct&nbsp;<link linkend='v4l2-sliced-vbi-data'>v4l2_sliced_vbi_data</link>">
<!ENTITY v4l2-sliced-vbi-format "struct&nbsp;<link linkend='v4l2-sliced-vbi-format'>v4l2_sliced_vbi_format</link>">
<!ENTITY v4l2-standard "struct&nbsp;<link linkend='v4l2-standard'>v4l2_standard</link>">
<!ENTITY v4l2-streamparm "struct&nbsp;<link linkend='v4l2-streamparm'>v4l2_streamparm</link>">
<!ENTITY v4l2-timecode "struct&nbsp;<link linkend='v4l2-timecode'>v4l2_timecode</link>">
<!ENTITY v4l2-tuner "struct&nbsp;<link linkend='v4l2-tuner'>v4l2_tuner</link>">
<!ENTITY v4l2-vbi-format "struct&nbsp;<link linkend='v4l2-vbi-format'>v4l2_vbi_format</link>">
<!ENTITY v4l2-window "struct&nbsp;<link linkend='v4l2-window'>v4l2_window</link>">
<!-- Error Codes -->
<!ENTITY EACCES "<errorcode>EACCES</errorcode> error code">
<!ENTITY EAGAIN "<errorcode>EAGAIN</errorcode> error code">
<!ENTITY EBADF "<errorcode>EBADF</errorcode> error code">
<!ENTITY EBUSY "<errorcode>EBUSY</errorcode> error code">
<!ENTITY EFAULT "<errorcode>EFAULT</errorcode> error code">
<!ENTITY EIO "<errorcode>EIO</errorcode> error code">
<!ENTITY EINTR "<errorcode>EINTR</errorcode> error code">
<!ENTITY EINVAL "<errorcode>EINVAL</errorcode> error code">
<!ENTITY ENFILE "<errorcode>ENFILE</errorcode> error code">
<!ENTITY ENOMEM "<errorcode>ENOMEM</errorcode> error code">
<!ENTITY ENOSPC "<errorcode>ENOSPC</errorcode> error code">
<!ENTITY ENOTTY "<errorcode>ENOTTY</errorcode> error code">
<!ENTITY ENXIO "<errorcode>ENXIO</errorcode> error code">
<!ENTITY EMFILE "<errorcode>EMFILE</errorcode> error code">
<!ENTITY EPERM "<errorcode>EPERM</errorcode> error code">
<!ENTITY ERANGE "<errorcode>ERANGE</errorcode> error code">
<!-- Subsections -->
<!ENTITY sub-biblio SYSTEM "v4l/biblio.xml">
<!ENTITY sub-common SYSTEM "v4l/common.xml">
<!ENTITY sub-compat SYSTEM "v4l/compat.xml">
<!ENTITY sub-controls SYSTEM "v4l/controls.xml">
<!ENTITY sub-dev-capture SYSTEM "v4l/dev-capture.xml">
<!ENTITY sub-dev-codec SYSTEM "v4l/dev-codec.xml">
<!ENTITY sub-dev-effect SYSTEM "v4l/dev-effect.xml">
<!ENTITY sub-dev-osd SYSTEM "v4l/dev-osd.xml">
<!ENTITY sub-dev-output SYSTEM "v4l/dev-output.xml">
<!ENTITY sub-dev-overlay SYSTEM "v4l/dev-overlay.xml">
<!ENTITY sub-dev-radio SYSTEM "v4l/dev-radio.xml">
<!ENTITY sub-dev-raw-vbi SYSTEM "v4l/dev-raw-vbi.xml">
<!ENTITY sub-dev-rds SYSTEM "v4l/dev-rds.xml">
<!ENTITY sub-dev-sliced-vbi SYSTEM "v4l/dev-sliced-vbi.xml">
<!ENTITY sub-dev-teletext SYSTEM "v4l/dev-teletext.xml">
<!ENTITY sub-driver SYSTEM "v4l/driver.xml">
<!ENTITY sub-libv4l SYSTEM "v4l/libv4l.xml">
<!ENTITY sub-remote_controllers SYSTEM "v4l/remote_controllers.xml">
<!ENTITY sub-fdl-appendix SYSTEM "v4l/fdl-appendix.xml">
<!ENTITY sub-func-close SYSTEM "v4l/func-close.xml">
<!ENTITY sub-func-ioctl SYSTEM "v4l/func-ioctl.xml">
<!ENTITY sub-func-mmap SYSTEM "v4l/func-mmap.xml">
<!ENTITY sub-func-munmap SYSTEM "v4l/func-munmap.xml">
<!ENTITY sub-func-open SYSTEM "v4l/func-open.xml">
<!ENTITY sub-func-poll SYSTEM "v4l/func-poll.xml">
<!ENTITY sub-func-read SYSTEM "v4l/func-read.xml">
<!ENTITY sub-func-select SYSTEM "v4l/func-select.xml">
<!ENTITY sub-func-write SYSTEM "v4l/func-write.xml">
<!ENTITY sub-io SYSTEM "v4l/io.xml">
<!ENTITY sub-pixfmt-grey SYSTEM "v4l/pixfmt-grey.xml">
<!ENTITY sub-pixfmt-nv12 SYSTEM "v4l/pixfmt-nv12.xml">
<!ENTITY sub-pixfmt-nv16 SYSTEM "v4l/pixfmt-nv16.xml">
<!ENTITY sub-pixfmt-packed-rgb SYSTEM "v4l/pixfmt-packed-rgb.xml">
<!ENTITY sub-pixfmt-packed-yuv SYSTEM "v4l/pixfmt-packed-yuv.xml">
<!ENTITY sub-pixfmt-sbggr16 SYSTEM "v4l/pixfmt-sbggr16.xml">
<!ENTITY sub-pixfmt-sbggr8 SYSTEM "v4l/pixfmt-sbggr8.xml">
<!ENTITY sub-pixfmt-sgbrg8 SYSTEM "v4l/pixfmt-sgbrg8.xml">
<!ENTITY sub-pixfmt-sgrbg8 SYSTEM "v4l/pixfmt-sgrbg8.xml">
<!ENTITY sub-pixfmt-uyvy SYSTEM "v4l/pixfmt-uyvy.xml">
<!ENTITY sub-pixfmt-vyuy SYSTEM "v4l/pixfmt-vyuy.xml">
<!ENTITY sub-pixfmt-y16 SYSTEM "v4l/pixfmt-y16.xml">
<!ENTITY sub-pixfmt-y41p SYSTEM "v4l/pixfmt-y41p.xml">
<!ENTITY sub-pixfmt-yuv410 SYSTEM "v4l/pixfmt-yuv410.xml">
<!ENTITY sub-pixfmt-yuv411p SYSTEM "v4l/pixfmt-yuv411p.xml">
<!ENTITY sub-pixfmt-yuv420 SYSTEM "v4l/pixfmt-yuv420.xml">
<!ENTITY sub-pixfmt-yuv422p SYSTEM "v4l/pixfmt-yuv422p.xml">
<!ENTITY sub-pixfmt-yuyv SYSTEM "v4l/pixfmt-yuyv.xml">
<!ENTITY sub-pixfmt-yvyu SYSTEM "v4l/pixfmt-yvyu.xml">
<!ENTITY sub-pixfmt SYSTEM "v4l/pixfmt.xml">
<!ENTITY sub-vidioc-cropcap SYSTEM "v4l/vidioc-cropcap.xml">
<!ENTITY sub-vidioc-dbg-g-register SYSTEM "v4l/vidioc-dbg-g-register.xml">
<!ENTITY sub-vidioc-encoder-cmd SYSTEM "v4l/vidioc-encoder-cmd.xml">
<!ENTITY sub-vidioc-enum-fmt SYSTEM "v4l/vidioc-enum-fmt.xml">
<!ENTITY sub-vidioc-enum-frameintervals SYSTEM "v4l/vidioc-enum-frameintervals.xml">
<!ENTITY sub-vidioc-enum-framesizes SYSTEM "v4l/vidioc-enum-framesizes.xml">
<!ENTITY sub-vidioc-enumaudio SYSTEM "v4l/vidioc-enumaudio.xml">
<!ENTITY sub-vidioc-enumaudioout SYSTEM "v4l/vidioc-enumaudioout.xml">
<!ENTITY sub-vidioc-enuminput SYSTEM "v4l/vidioc-enuminput.xml">
<!ENTITY sub-vidioc-enumoutput SYSTEM "v4l/vidioc-enumoutput.xml">
<!ENTITY sub-vidioc-enumstd SYSTEM "v4l/vidioc-enumstd.xml">
<!ENTITY sub-vidioc-g-audio SYSTEM "v4l/vidioc-g-audio.xml">
<!ENTITY sub-vidioc-g-audioout SYSTEM "v4l/vidioc-g-audioout.xml">
<!ENTITY sub-vidioc-dbg-g-chip-ident SYSTEM "v4l/vidioc-dbg-g-chip-ident.xml">
<!ENTITY sub-vidioc-g-crop SYSTEM "v4l/vidioc-g-crop.xml">
<!ENTITY sub-vidioc-g-ctrl SYSTEM "v4l/vidioc-g-ctrl.xml">
<!ENTITY sub-vidioc-g-enc-index SYSTEM "v4l/vidioc-g-enc-index.xml">
<!ENTITY sub-vidioc-g-ext-ctrls SYSTEM "v4l/vidioc-g-ext-ctrls.xml">
<!ENTITY sub-vidioc-g-fbuf SYSTEM "v4l/vidioc-g-fbuf.xml">
<!ENTITY sub-vidioc-g-fmt SYSTEM "v4l/vidioc-g-fmt.xml">
<!ENTITY sub-vidioc-g-frequency SYSTEM "v4l/vidioc-g-frequency.xml">
<!ENTITY sub-vidioc-g-input SYSTEM "v4l/vidioc-g-input.xml">
<!ENTITY sub-vidioc-g-jpegcomp SYSTEM "v4l/vidioc-g-jpegcomp.xml">
<!ENTITY sub-vidioc-g-modulator SYSTEM "v4l/vidioc-g-modulator.xml">
<!ENTITY sub-vidioc-g-output SYSTEM "v4l/vidioc-g-output.xml">
<!ENTITY sub-vidioc-g-parm SYSTEM "v4l/vidioc-g-parm.xml">
<!ENTITY sub-vidioc-g-priority SYSTEM "v4l/vidioc-g-priority.xml">
<!ENTITY sub-vidioc-g-sliced-vbi-cap SYSTEM "v4l/vidioc-g-sliced-vbi-cap.xml">
<!ENTITY sub-vidioc-g-std SYSTEM "v4l/vidioc-g-std.xml">
<!ENTITY sub-vidioc-g-tuner SYSTEM "v4l/vidioc-g-tuner.xml">
<!ENTITY sub-vidioc-log-status SYSTEM "v4l/vidioc-log-status.xml">
<!ENTITY sub-vidioc-overlay SYSTEM "v4l/vidioc-overlay.xml">
<!ENTITY sub-vidioc-qbuf SYSTEM "v4l/vidioc-qbuf.xml">
<!ENTITY sub-vidioc-querybuf SYSTEM "v4l/vidioc-querybuf.xml">
<!ENTITY sub-vidioc-querycap SYSTEM "v4l/vidioc-querycap.xml">
<!ENTITY sub-vidioc-queryctrl SYSTEM "v4l/vidioc-queryctrl.xml">
<!ENTITY sub-vidioc-querystd SYSTEM "v4l/vidioc-querystd.xml">
<!ENTITY sub-vidioc-reqbufs SYSTEM "v4l/vidioc-reqbufs.xml">
<!ENTITY sub-vidioc-s-hw-freq-seek SYSTEM "v4l/vidioc-s-hw-freq-seek.xml">
<!ENTITY sub-vidioc-streamon SYSTEM "v4l/vidioc-streamon.xml">
<!ENTITY sub-capture-c SYSTEM "v4l/capture.c.xml">
<!ENTITY sub-keytable-c SYSTEM "v4l/keytable.c.xml">
<!ENTITY sub-v4l2grab-c SYSTEM "v4l/v4l2grab.c.xml">
<!ENTITY sub-videodev2-h SYSTEM "v4l/videodev2.h.xml">
<!ENTITY sub-v4l2 SYSTEM "v4l/v4l2.xml">
<!ENTITY sub-intro SYSTEM "dvb/intro.xml">
<!ENTITY sub-frontend SYSTEM "dvb/frontend.xml">
<!ENTITY sub-demux SYSTEM "dvb/demux.xml">
<!ENTITY sub-video SYSTEM "dvb/video.xml">
<!ENTITY sub-audio SYSTEM "dvb/audio.xml">
<!ENTITY sub-ca SYSTEM "dvb/ca.xml">
<!ENTITY sub-net SYSTEM "dvb/net.xml">
<!ENTITY sub-kdapi SYSTEM "dvb/kdapi.xml">
<!ENTITY sub-examples SYSTEM "dvb/examples.xml">
<!ENTITY sub-dvbapi SYSTEM "dvb/dvbapi.xml">
<!ENTITY sub-media SYSTEM "media.xml">
<!ENTITY sub-media-entities SYSTEM "media-entities.xml">
<!ENTITY sub-media-indices SYSTEM "media-indices.xml">
<!-- Function Reference -->
<!ENTITY sub-close SYSTEM "v4l/func-close.xml">
<!ENTITY sub-ioctl SYSTEM "v4l/func-ioctl.xml">
<!ENTITY sub-mmap SYSTEM "v4l/func-mmap.xml">
<!ENTITY sub-munmap SYSTEM "v4l/func-munmap.xml">
<!ENTITY sub-open SYSTEM "v4l/func-open.xml">
<!ENTITY sub-poll SYSTEM "v4l/func-poll.xml">
<!ENTITY sub-read SYSTEM "v4l/func-read.xml">
<!ENTITY sub-select SYSTEM "v4l/func-select.xml">
<!ENTITY sub-write SYSTEM "v4l/func-write.xml">
<!ENTITY sub-grey SYSTEM "v4l/pixfmt-grey.xml">
<!ENTITY sub-nv12 SYSTEM "v4l/pixfmt-nv12.xml">
<!ENTITY sub-nv16 SYSTEM "v4l/pixfmt-nv16.xml">
<!ENTITY sub-packed-rgb SYSTEM "v4l/pixfmt-packed-rgb.xml">
<!ENTITY sub-packed-yuv SYSTEM "v4l/pixfmt-packed-yuv.xml">
<!ENTITY sub-sbggr16 SYSTEM "v4l/pixfmt-sbggr16.xml">
<!ENTITY sub-sbggr8 SYSTEM "v4l/pixfmt-sbggr8.xml">
<!ENTITY sub-sgbrg8 SYSTEM "v4l/pixfmt-sgbrg8.xml">
<!ENTITY sub-sgrbg8 SYSTEM "v4l/pixfmt-sgrbg8.xml">
<!ENTITY sub-uyvy SYSTEM "v4l/pixfmt-uyvy.xml">
<!ENTITY sub-vyuy SYSTEM "v4l/pixfmt-vyuy.xml">
<!ENTITY sub-y16 SYSTEM "v4l/pixfmt-y16.xml">
<!ENTITY sub-y41p SYSTEM "v4l/pixfmt-y41p.xml">
<!ENTITY sub-yuv410 SYSTEM "v4l/pixfmt-yuv410.xml">
<!ENTITY sub-yuv411p SYSTEM "v4l/pixfmt-yuv411p.xml">
<!ENTITY sub-yuv420 SYSTEM "v4l/pixfmt-yuv420.xml">
<!ENTITY sub-yuv422p SYSTEM "v4l/pixfmt-yuv422p.xml">
<!ENTITY sub-yuyv SYSTEM "v4l/pixfmt-yuyv.xml">
<!ENTITY sub-yvyu SYSTEM "v4l/pixfmt-yvyu.xml">
<!ENTITY sub-cropcap SYSTEM "v4l/vidioc-cropcap.xml">
<!ENTITY sub-dbg-g-register SYSTEM "v4l/vidioc-dbg-g-register.xml">
<!ENTITY sub-encoder-cmd SYSTEM "v4l/vidioc-encoder-cmd.xml">
<!ENTITY sub-enum-fmt SYSTEM "v4l/vidioc-enum-fmt.xml">
<!ENTITY sub-enum-frameintervals SYSTEM "v4l/vidioc-enum-frameintervals.xml">
<!ENTITY sub-enum-framesizes SYSTEM "v4l/vidioc-enum-framesizes.xml">
<!ENTITY sub-enumaudio SYSTEM "v4l/vidioc-enumaudio.xml">
<!ENTITY sub-enumaudioout SYSTEM "v4l/vidioc-enumaudioout.xml">
<!ENTITY sub-enuminput SYSTEM "v4l/vidioc-enuminput.xml">
<!ENTITY sub-enumoutput SYSTEM "v4l/vidioc-enumoutput.xml">
<!ENTITY sub-enumstd SYSTEM "v4l/vidioc-enumstd.xml">
<!ENTITY sub-g-audio SYSTEM "v4l/vidioc-g-audio.xml">
<!ENTITY sub-g-audioout SYSTEM "v4l/vidioc-g-audioout.xml">
<!ENTITY sub-dbg-g-chip-ident SYSTEM "v4l/vidioc-dbg-g-chip-ident.xml">
<!ENTITY sub-g-crop SYSTEM "v4l/vidioc-g-crop.xml">
<!ENTITY sub-g-ctrl SYSTEM "v4l/vidioc-g-ctrl.xml">
<!ENTITY sub-g-enc-index SYSTEM "v4l/vidioc-g-enc-index.xml">
<!ENTITY sub-g-ext-ctrls SYSTEM "v4l/vidioc-g-ext-ctrls.xml">
<!ENTITY sub-g-fbuf SYSTEM "v4l/vidioc-g-fbuf.xml">
<!ENTITY sub-g-fmt SYSTEM "v4l/vidioc-g-fmt.xml">
<!ENTITY sub-g-frequency SYSTEM "v4l/vidioc-g-frequency.xml">
<!ENTITY sub-g-input SYSTEM "v4l/vidioc-g-input.xml">
<!ENTITY sub-g-jpegcomp SYSTEM "v4l/vidioc-g-jpegcomp.xml">
<!ENTITY sub-g-modulator SYSTEM "v4l/vidioc-g-modulator.xml">
<!ENTITY sub-g-output SYSTEM "v4l/vidioc-g-output.xml">
<!ENTITY sub-g-parm SYSTEM "v4l/vidioc-g-parm.xml">
<!ENTITY sub-g-priority SYSTEM "v4l/vidioc-g-priority.xml">
<!ENTITY sub-g-sliced-vbi-cap SYSTEM "v4l/vidioc-g-sliced-vbi-cap.xml">
<!ENTITY sub-g-std SYSTEM "v4l/vidioc-g-std.xml">
<!ENTITY sub-g-tuner SYSTEM "v4l/vidioc-g-tuner.xml">
<!ENTITY sub-log-status SYSTEM "v4l/vidioc-log-status.xml">
<!ENTITY sub-overlay SYSTEM "v4l/vidioc-overlay.xml">
<!ENTITY sub-qbuf SYSTEM "v4l/vidioc-qbuf.xml">
<!ENTITY sub-querybuf SYSTEM "v4l/vidioc-querybuf.xml">
<!ENTITY sub-querycap SYSTEM "v4l/vidioc-querycap.xml">
<!ENTITY sub-queryctrl SYSTEM "v4l/vidioc-queryctrl.xml">
<!ENTITY sub-querystd SYSTEM "v4l/vidioc-querystd.xml">
<!ENTITY sub-reqbufs SYSTEM "v4l/vidioc-reqbufs.xml">
<!ENTITY sub-s-hw-freq-seek SYSTEM "v4l/vidioc-s-hw-freq-seek.xml">
<!ENTITY sub-streamon SYSTEM "v4l/vidioc-streamon.xml">

85
Documentation/DocBook/media-indices.xml Normal file
View File

@ -0,0 +1,85 @@
<!-- Generated file! Do not edit. -->
<index><title>List of Types</title>
<indexentry><primaryie><link linkend='v4l2-std-id'>v4l2_std_id</link></primaryie></indexentry>
<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-buf-type'>v4l2_buf_type</link></primaryie></indexentry>
<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-colorspace'>v4l2_colorspace</link></primaryie></indexentry>
<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-ctrl-type'>v4l2_ctrl_type</link></primaryie></indexentry>
<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-exposure-auto-type'>v4l2_exposure_auto_type</link></primaryie></indexentry>
<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-field'>v4l2_field</link></primaryie></indexentry>
<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-frmivaltypes'>v4l2_frmivaltypes</link></primaryie></indexentry>
<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-frmsizetypes'>v4l2_frmsizetypes</link></primaryie></indexentry>
<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-memory'>v4l2_memory</link></primaryie></indexentry>
<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-mpeg-audio-ac3-bitrate'>v4l2_mpeg_audio_ac3_bitrate</link></primaryie></indexentry>
<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-mpeg-audio-crc'>v4l2_mpeg_audio_crc</link></primaryie></indexentry>
<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-mpeg-audio-emphasis'>v4l2_mpeg_audio_emphasis</link></primaryie></indexentry>
<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-mpeg-audio-encoding'>v4l2_mpeg_audio_encoding</link></primaryie></indexentry>
<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-mpeg-audio-l1-bitrate'>v4l2_mpeg_audio_l1_bitrate</link></primaryie></indexentry>
<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-mpeg-audio-l2-bitrate'>v4l2_mpeg_audio_l2_bitrate</link></primaryie></indexentry>
<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-mpeg-audio-l3-bitrate'>v4l2_mpeg_audio_l3_bitrate</link></primaryie></indexentry>
<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-mpeg-audio-mode'>v4l2_mpeg_audio_mode</link></primaryie></indexentry>
<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-mpeg-audio-mode-extension'>v4l2_mpeg_audio_mode_extension</link></primaryie></indexentry>
<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-mpeg-audio-sampling-freq'>v4l2_mpeg_audio_sampling_freq</link></primaryie></indexentry>
<indexentry><primaryie>enum&nbsp;<link linkend='chroma-spatial-filter-type'>v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type</link></primaryie></indexentry>
<indexentry><primaryie>enum&nbsp;<link linkend='luma-spatial-filter-type'>v4l2_mpeg_cx2341x_video_luma_spatial_filter_type</link></primaryie></indexentry>
<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-mpeg-cx2341x-video-median-filter-type'>v4l2_mpeg_cx2341x_video_median_filter_type</link></primaryie></indexentry>
<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-mpeg-cx2341x-video-spatial-filter-mode'>v4l2_mpeg_cx2341x_video_spatial_filter_mode</link></primaryie></indexentry>
<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-mpeg-cx2341x-video-temporal-filter-mode'>v4l2_mpeg_cx2341x_video_temporal_filter_mode</link></primaryie></indexentry>
<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-mpeg-stream-type'>v4l2_mpeg_stream_type</link></primaryie></indexentry>
<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-mpeg-stream-vbi-fmt'>v4l2_mpeg_stream_vbi_fmt</link></primaryie></indexentry>
<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-mpeg-video-aspect'>v4l2_mpeg_video_aspect</link></primaryie></indexentry>
<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-mpeg-video-bitrate-mode'>v4l2_mpeg_video_bitrate_mode</link></primaryie></indexentry>
<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-mpeg-video-encoding'>v4l2_mpeg_video_encoding</link></primaryie></indexentry>
<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-power-line-frequency'>v4l2_power_line_frequency</link></primaryie></indexentry>
<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-priority'>v4l2_priority</link></primaryie></indexentry>
<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-tuner-type'>v4l2_tuner_type</link></primaryie></indexentry>
<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-preemphasis'>v4l2_preemphasis</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-audio'>v4l2_audio</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-audioout'>v4l2_audioout</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-buffer'>v4l2_buffer</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-capability'>v4l2_capability</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-captureparm'>v4l2_captureparm</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-clip'>v4l2_clip</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-control'>v4l2_control</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-crop'>v4l2_crop</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-cropcap'>v4l2_cropcap</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-dbg-chip-ident'>v4l2_dbg_chip_ident</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-dbg-match'>v4l2_dbg_match</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-dbg-register'>v4l2_dbg_register</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-enc-idx'>v4l2_enc_idx</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-enc-idx-entry'>v4l2_enc_idx_entry</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-encoder-cmd'>v4l2_encoder_cmd</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-ext-control'>v4l2_ext_control</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-ext-controls'>v4l2_ext_controls</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-fmtdesc'>v4l2_fmtdesc</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-format'>v4l2_format</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-fract'>v4l2_fract</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-framebuffer'>v4l2_framebuffer</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-frequency'>v4l2_frequency</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-frmival-stepwise'>v4l2_frmival_stepwise</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-frmivalenum'>v4l2_frmivalenum</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-frmsize-discrete'>v4l2_frmsize_discrete</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-frmsize-stepwise'>v4l2_frmsize_stepwise</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-frmsizeenum'>v4l2_frmsizeenum</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-hw-freq-seek'>v4l2_hw_freq_seek</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-input'>v4l2_input</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-jpegcompression'>v4l2_jpegcompression</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-modulator'>v4l2_modulator</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-mpeg-vbi-fmt-ivtv'>v4l2_mpeg_vbi_fmt_ivtv</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-output'>v4l2_output</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-outputparm'>v4l2_outputparm</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-pix-format'>v4l2_pix_format</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-queryctrl'>v4l2_queryctrl</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-querymenu'>v4l2_querymenu</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-rect'>v4l2_rect</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-requestbuffers'>v4l2_requestbuffers</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-sliced-vbi-cap'>v4l2_sliced_vbi_cap</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-sliced-vbi-data'>v4l2_sliced_vbi_data</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-sliced-vbi-format'>v4l2_sliced_vbi_format</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-standard'>v4l2_standard</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-streamparm'>v4l2_streamparm</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-timecode'>v4l2_timecode</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-tuner'>v4l2_tuner</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-vbi-format'>v4l2_vbi_format</link></primaryie></indexentry>
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-window'>v4l2_window</link></primaryie></indexentry>
</index>

112
Documentation/DocBook/media.xml Normal file
View File

@ -0,0 +1,112 @@
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY % media-entities SYSTEM "./media-entities.xml"> %media-entities;
<!ENTITY media-indices SYSTEM "./media-indices.sgml">
<!ENTITY eg "e.&nbsp;g.">
<!ENTITY ie "i.&nbsp;e.">
<!ENTITY fd "File descriptor returned by <link linkend='func-open'><function>open()</function></link>.">
<!ENTITY i2c "I<superscript>2</superscript>C">
<!ENTITY return-value "<title>Return Value</title><para>On success <returnvalue>0</returnvalue> is returned, on error <returnvalue>-1</returnvalue> and the <varname>errno</varname> variable is set appropriately:</para>">
<!ENTITY manvol "<manvolnum>2</manvolnum>">
<!-- Table templates: structs, structs w/union, defines. -->
<!ENTITY cs-str "<colspec colname='c1' colwidth='1*' /><colspec colname='c2' colwidth='1*' /><colspec colname='c3' colwidth='2*' /><spanspec spanname='hspan' namest='c1' nameend='c3' />">
<!ENTITY cs-ustr "<colspec colname='c1' colwidth='1*' /><colspec colname='c2' colwidth='1*' /><colspec colname='c3' colwidth='1*' /><colspec colname='c4' colwidth='2*' /><spanspec spanname='hspan' namest='c1' nameend='c4' />">
<!ENTITY cs-def "<colspec colname='c1' colwidth='3*' /><colspec colname='c2' colwidth='1*' /><colspec colname='c3' colwidth='4*' /><spanspec spanname='hspan' namest='c1' nameend='c3' />">
<!-- Video for Linux mailing list address. -->
<!ENTITY v4l-ml "<ulink url='http://www.linuxtv.org/lists.php'>http://www.linuxtv.org/lists.php</ulink>">
<!-- LinuxTV v4l-dvb repository. -->
<!ENTITY v4l-dvb "<ulink url='http://linuxtv.org/repo/'>http://linuxtv.org/repo/</ulink>">
]>
<book id="media_api">
<bookinfo>
<title>LINUX MEDIA INFRASTRUCTURE API</title>
<copyright>
<year>2009</year>
<holder>LinuxTV Developers</holder>
</copyright>
<legalnotice>
<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. A copy of the license is included in the chapter entitled
"GNU Free Documentation License"</para>
</legalnotice>
</bookinfo>
<toc></toc> <!-- autogenerated -->
<preface>
<title>Introduction</title>
<para>This document covers the Linux Kernel to Userspace API's used by
video and radio straming devices, including video cameras,
analog and digital TV receiver cards, AM/FM receiver cards,
streaming capture devices.</para>
<para>It is divided into three parts.</para>
<para>The first part covers radio, capture,
cameras and analog TV devices.</para>
<para>The second part covers the
API used for digital TV and Internet reception via one of the
several digital tv standards. While it is called as DVB API,
in fact it covers several different video standards including
DVB-T, DVB-S, DVB-C and ATSC. The API is currently being updated
to documment support also for DVB-S2, ISDB-T and ISDB-S.</para>
<para>The third part covers other API's used by all media infrastructure devices</para>
<para>For additional information and for the latest development code,
see: <ulink url="http://linuxtv.org">http://linuxtv.org</ulink>.</para>
<para>For discussing improvements, reporting troubles, sending new drivers, etc, please mail to: <ulink url="http://vger.kernel.org/vger-lists.html#linux-media">Linux Media Mailing List (LMML).</ulink>.</para>
</preface>
<part id="v4l2spec">
&sub-v4l2;
</part>
<part id="dvbapi">
&sub-dvbapi;
</part>
<part id="v4ldvb_common">
<partinfo>
<authorgroup>
<author>
<firstname>Mauro</firstname>
<surname>Chehab</surname>
<othername role="mi">Carvalho</othername>
<affiliation><address><email>mchehab@redhat.com</email></address></affiliation>
<contrib>Initial version.</contrib>
</author>
</authorgroup>
<copyright>
<year>2009</year>
<holder>Mauro Carvalho Chehab</holder>
</copyright>
<revhistory>
<!-- Put document revisions here, newest first. -->
<revision>
<revnumber>1.0.0</revnumber>
<date>2009-09-06</date>
<authorinitials>mcc</authorinitials>
<revremark>Initial revision</revremark>
</revision>
</revhistory>
</partinfo>
<title>Other API's used by media infrastructure drivers</title>
<chapter id="remote_controllers">
&sub-remote_controllers;
</chapter>
</part>
&sub-fdl-appendix;
</book>

188
Documentation/DocBook/v4l/biblio.xml Normal file
View File

@ -0,0 +1,188 @@
<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="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>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

659
Documentation/DocBook/v4l/capture.c.xml Normal file
View File

@ -0,0 +1,659 @@
<programlisting>
/*
* V4L2 video capture example
*
* This program can be used and distributed without restrictions.
*
* This program were got from V4L2 API, Draft 0.20
* available at: http://v4l2spec.bytesex.org/
*/
#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>

1169
Documentation/DocBook/v4l/common.xml Normal file
View File

File diff suppressed because it is too large Load Diff

2457
Documentation/DocBook/v4l/compat.xml Normal file
View File

File diff suppressed because it is too large Load Diff

2049
Documentation/DocBook/v4l/controls.xml Normal file
View File

File diff suppressed because it is too large Load Diff

BIN
Documentation/DocBook/v4l/crop.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 5.8 KiB

BIN
Documentation/DocBook/v4l/crop.pdf Normal file
View File

Binary file not shown.

115
Documentation/DocBook/v4l/dev-capture.xml Normal file
View File

@ -0,0 +1,115 @@
<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> 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> and call the
&VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill
the &v4l2-pix-format; <structfield>pix</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; 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>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

26
Documentation/DocBook/v4l/dev-codec.xml Normal file
View File

@ -0,0 +1,26 @@
<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>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

25
Documentation/DocBook/v4l/dev-effect.xml Normal file
View File

@ -0,0 +1,25 @@
<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>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

164
Documentation/DocBook/v4l/dev-osd.xml Normal file
View File

@ -0,0 +1,164 @@
<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>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

111
Documentation/DocBook/v4l/dev-output.xml Normal file
View File

@ -0,0 +1,111 @@
<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> 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> and call the
&VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill
the &v4l2-pix-format; <structfield>pix</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; 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>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

379
Documentation/DocBook/v4l/dev-overlay.xml Normal file
View File

@ -0,0 +1,379 @@
<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>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

57
Documentation/DocBook/v4l/dev-radio.xml Normal file
View File

@ -0,0 +1,57 @@
<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>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

347
Documentation/DocBook/v4l/dev-raw-vbi.xml Normal file
View File

@ -0,0 +1,347 @@
<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>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

168
Documentation/DocBook/v4l/dev-rds.xml Normal file
View File

@ -0,0 +1,168 @@
<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 decoding 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 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;.
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;.</para>
</section>
<section>
<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,
as follows:</para>
<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="3">
<colspec colname="c1" colwidth="1*" />
<colspec colname="c2" colwidth="1*" />
<colspec colname="c3" colwidth="5*" />
<tbody valign="top">
<row>
<entry>V4L2_RDS_BLOCK_MSK</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>0</entry>
<entry>Block A.</entry>
</row>
<row>
<entry>V4L2_RDS_BLOCK_B</entry>
<entry>1</entry>
<entry>Block B.</entry>
</row>
<row>
<entry>V4L2_RDS_BLOCK_C</entry>
<entry>2</entry>
<entry>Block C.</entry>
</row>
<row>
<entry>V4L2_RDS_BLOCK_D</entry>
<entry>3</entry>
<entry>Block D.</entry>
</row>
<row>
<entry>V4L2_RDS_BLOCK_C_ALT</entry>
<entry>4</entry>
<entry>Block C'.</entry>
</row>
<row>
<entry>V4L2_RDS_BLOCK_INVALID</entry>
<entry>7</entry>
<entry>An invalid block.</entry>
</row>
<row>
<entry>V4L2_RDS_BLOCK_CORRECTED</entry>
<entry>0x40</entry>
<entry>A bit error was detected but corrected.</entry>
</row>
<row>
<entry>V4L2_RDS_BLOCK_ERROR</entry>
<entry>0x80</entry>
<entry>An incorrectable error occurred.</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

708
Documentation/DocBook/v4l/dev-sliced-vbi.xml Normal file
View File

@ -0,0 +1,708 @@
<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>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

40
Documentation/DocBook/v4l/dev-teletext.xml Normal file
View File

@ -0,0 +1,40 @@
<title>Teletext Interface</title>
<para>This interface aims 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 can be found on older
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 is defined in
the kernel header file <filename>linux/videotext.h</filename>, the
specification is available from <ulink url="http://home.pages.de/~videotext/">
http://home.pages.de/~videotext/</ulink>. (Videotext is the name of
the German public television Teletext service.) Conventional character
device file names are <filename>/dev/vtx</filename> and
<filename>/dev/vttuner</filename>, with device number 83, 0 and 83, 16
respectively. A similar interface exists for the Philips SAA5249
Teletext decoder [specification?] with character device file names
<filename>/dev/tlkN</filename>, device number 102, N.</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. For reference the V4L Teletext API specification is
reproduced here in full: "Teletext interfaces talk the existing VTX
API." Teletext devices with major number 83 and 102 will be removed in
Linux 2.6.</para>
<para>There are no plans to replace the Teletext API or to integrate
it into V4L2. Please write to the linux-media mailing list: &v4l-ml;
when the need arises.</para>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

208
Documentation/DocBook/v4l/driver.xml Normal file
View File

@ -0,0 +1,208 @@
<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>
-->
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

671
Documentation/DocBook/v4l/fdl-appendix.xml Normal file
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://developer.gnome.org/projects/gdp
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>

BIN
Documentation/DocBook/v4l/fieldseq_bt.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 25 KiB

BIN
Documentation/DocBook/v4l/fieldseq_bt.pdf Normal file
View File

Binary file not shown.

BIN
Documentation/DocBook/v4l/fieldseq_tb.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 25 KiB

BIN
Documentation/DocBook/v4l/fieldseq_tb.pdf Normal file
View File

Binary file not shown.

70
Documentation/DocBook/v4l/func-close.xml Normal file
View File

@ -0,0 +1,70 @@
<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>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

146
Documentation/DocBook/v4l/func-ioctl.xml Normal file
View File

@ -0,0 +1,146 @@
<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 <link
linkend="videodev">videodev.h</link> 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 <link linkend="videodev">videodev.h</link> 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>
<title>Return Value</title>
<para>On success the <function>ioctl()</function> function returns
<returnvalue>0</returnvalue> and does not reset the
<varname>errno</varname> variable. On failure
<returnvalue>-1</returnvalue> is returned, when the ioctl takes an
output or read/write parameter it remains unmodified, and the
<varname>errno</varname> variable is set appropriately. See below for
possible error codes. Generic errors like <errorcode>EBADF</errorcode>
or <errorcode>EFAULT</errorcode> are not listed in the sections
discussing individual ioctl requests.</para>
<para>Note ioctls may return undefined error codes. Since errors
may have side effects such as a driver reset applications should
abort on unexpected errors.</para>
<variablelist>
<varlistentry>
<term><errorcode>EBADF</errorcode></term>
<listitem>
<para><parameter>fd</parameter> is not a valid open file
descriptor.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EBUSY</errorcode></term>
<listitem>
<para>The property cannot be changed right now. Typically
this error code is returned when I/O is in progress or the driver
supports multiple opens and another process locked the property.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EFAULT</errorcode></term>
<listitem>
<para><parameter>argp</parameter> references an inaccessible
memory area.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>ENOTTY</errorcode></term>
<listitem>
<para><parameter>fd</parameter> is not associated with a
character special device.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EINVAL</errorcode></term>
<listitem>
<para>The <parameter>request</parameter> or the data pointed
to by <parameter>argp</parameter> is not valid. This is a very common
error code, see the individual ioctl requests listed in <xref
linkend="user-func" /> for actual causes.</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>
<varlistentry>
<term><errorcode>ERANGE</errorcode></term>
<listitem>
<para>The application attempted to set a control with the
&VIDIOC-S-CTRL; ioctl to a value which is out of bounds.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

185
Documentation/DocBook/v4l/func-mmap.xml Normal file
View File

@ -0,0 +1,185 @@
<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.</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.</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>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

83
Documentation/DocBook/v4l/func-munmap.xml Normal file
View File

@ -0,0 +1,83 @@
<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.</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>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

121
Documentation/DocBook/v4l/func-open.xml Normal file
View File

@ -0,0 +1,121 @@
<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>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

127
Documentation/DocBook/v4l/func-poll.xml Normal file
View File

@ -0,0 +1,127 @@
<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>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

189
Documentation/DocBook/v4l/func-read.xml Normal file
View File

@ -0,0 +1,189 @@
<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>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

138
Documentation/DocBook/v4l/func-select.xml Normal file
View File

@ -0,0 +1,138 @@
<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>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

136
Documentation/DocBook/v4l/func-write.xml Normal file
View File

@ -0,0 +1,136 @@
<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>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

1073
Documentation/DocBook/v4l/io.xml Normal file
View File

File diff suppressed because it is too large Load Diff

172
Documentation/DocBook/v4l/keytable.c.xml Normal file
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>

167
Documentation/DocBook/v4l/libv4l.xml Normal file
View File

@ -0,0 +1,167 @@
<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 occured 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>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

70
Documentation/DocBook/v4l/pixfmt-grey.xml Normal file
View File

@ -0,0 +1,70 @@
<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>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "pixfmt.sgml"
indent-tabs-mode: nil
End:
-->

151
Documentation/DocBook/v4l/pixfmt-nv12.xml Normal file
View File

@ -0,0 +1,151 @@
<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>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "pixfmt.sgml"
indent-tabs-mode: nil
End:
-->

174
Documentation/DocBook/v4l/pixfmt-nv16.xml Normal file
View File

@ -0,0 +1,174 @@
<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>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "pixfmt.sgml"
indent-tabs-mode: nil
End:
-->

862
Documentation/DocBook/v4l/pixfmt-packed-rgb.xml Normal file
View File

@ -0,0 +1,862 @@
<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-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>.</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-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>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "pixfmt.sgml"
indent-tabs-mode: nil
End:
-->

244
Documentation/DocBook/v4l/pixfmt-packed-yuv.xml Normal file
View File

@ -0,0 +1,244 @@
<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>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "pixfmt.sgml"
indent-tabs-mode: nil
End:
-->

91
Documentation/DocBook/v4l/pixfmt-sbggr16.xml Normal file
View File

@ -0,0 +1,91 @@
<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>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "pixfmt.sgml"
indent-tabs-mode: nil
End:
-->

75
Documentation/DocBook/v4l/pixfmt-sbggr8.xml Normal file
View File

@ -0,0 +1,75 @@
<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>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "pixfmt.sgml"
indent-tabs-mode: nil
End:
-->

75
Documentation/DocBook/v4l/pixfmt-sgbrg8.xml Normal file
View File

@ -0,0 +1,75 @@
<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>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "pixfmt.sgml"
indent-tabs-mode: nil
End:
-->

75
Documentation/DocBook/v4l/pixfmt-sgrbg8.xml Normal file
View File

@ -0,0 +1,75 @@
<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>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "pixfmt.sgml"
indent-tabs-mode: nil
End:
-->

128
Documentation/DocBook/v4l/pixfmt-uyvy.xml Normal file
View File

@ -0,0 +1,128 @@
<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>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "pixfmt.sgml"
indent-tabs-mode: nil
End:
-->

128
Documentation/DocBook/v4l/pixfmt-vyuy.xml Normal file
View File

@ -0,0 +1,128 @@
<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>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "pixfmt.sgml"
indent-tabs-mode: nil
End:
-->

89
Documentation/DocBook/v4l/pixfmt-y16.xml Normal file
View File

@ -0,0 +1,89 @@
<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>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "pixfmt.sgml"
indent-tabs-mode: nil
End:
-->

157
Documentation/DocBook/v4l/pixfmt-y41p.xml Normal file
View File

@ -0,0 +1,157 @@
<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>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "pixfmt.sgml"
indent-tabs-mode: nil
End:
-->

141
Documentation/DocBook/v4l/pixfmt-yuv410.xml Normal file
View File

@ -0,0 +1,141 @@
<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>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "pixfmt.sgml"
indent-tabs-mode: nil
End:
-->

155
Documentation/DocBook/v4l/pixfmt-yuv411p.xml Normal file
View File

@ -0,0 +1,155 @@
<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>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

157
Documentation/DocBook/v4l/pixfmt-yuv420.xml Normal file
View File

@ -0,0 +1,157 @@
<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>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "pixfmt.sgml"
indent-tabs-mode: nil
End:
-->

161
Documentation/DocBook/v4l/pixfmt-yuv422p.xml Normal file
View File

@ -0,0 +1,161 @@
<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>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "pixfmt.sgml"
indent-tabs-mode: nil
End:
-->

128
Documentation/DocBook/v4l/pixfmt-yuyv.xml Normal file
View File

@ -0,0 +1,128 @@
<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>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "pixfmt.sgml"
indent-tabs-mode: nil
End:
-->

128
Documentation/DocBook/v4l/pixfmt-yvyu.xml Normal file
View File

@ -0,0 +1,128 @@
<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>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "pixfmt.sgml"
indent-tabs-mode: nil
End:
-->

796
Documentation/DocBook/v4l/pixfmt.xml Normal file
View File

@ -0,0 +1,796 @@
<title>Image Formats</title>
<para>The V4L2 API was primarily designed for devices exchanging
image data with applications. The
<structname>v4l2_pix_format</structname> structure defines the format
and layout of an image in memory. Image formats are negotiated with
the &VIDIOC-S-FMT; ioctl. (The explanations here focus on video
capturing and output, for overlay frame buffer formats see also
&VIDIOC-G-FBUF;.)</para>
<table pgwide="1" frame="none" id="v4l2-pix-format">
<title>struct <structname>v4l2_pix_format</structname></title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>__u32</entry>
<entry><structfield>width</structfield></entry>
<entry>Image width in pixels.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>height</structfield></entry>
<entry>Image height in pixels.</entry>
</row>
<row>
<entry spanname="hspan">Applications set these fields to
request an image size, drivers return the closest possible values. In
case of planar formats the <structfield>width</structfield> and
<structfield>height</structfield> applies to the largest plane. To
avoid ambiguities drivers must return values rounded up to a multiple
of the scale factor of any smaller planes. For example when the image
format is YUV 4:2:0, <structfield>width</structfield> and
<structfield>height</structfield> must be multiples of two.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>pixelformat</structfield></entry>
<entry>The pixel format or type of compression, set by the
application. This is a little endian <link
linkend="v4l2-fourcc">four character code</link>. V4L2 defines
standard RGB formats in <xref linkend="rgb-formats" />, YUV formats in <xref
linkend="yuv-formats" />, and reserved codes in <xref
linkend="reserved-formats" /></entry>
</row>
<row>
<entry>&v4l2-field;</entry>
<entry><structfield>field</structfield></entry>
<entry>Video images are typically interlaced. Applications
can request to capture or output only the top or bottom field, or both
fields interlaced or sequentially stored in one buffer or alternating
in separate buffers. Drivers return the actual field order selected.
For details see <xref linkend="field-order" />.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>bytesperline</structfield></entry>
<entry>Distance in bytes between the leftmost pixels in two
adjacent lines.</entry>
</row>
<row>
<entry spanname="hspan"><para>Both applications and drivers
can set this field to request padding bytes at the end of each line.
Drivers however may ignore the value requested by the application,
returning <structfield>width</structfield> times bytes per pixel or a
larger value required by the hardware. That implies applications can
just set this field to zero to get a reasonable
default.</para><para>Video hardware may access padding bytes,
therefore they must reside in accessible memory. Consider cases where
padding bytes after the last line of an image cross a system page
boundary. Input devices may write padding bytes, the value is
undefined. Output devices ignore the contents of padding
bytes.</para><para>When the image format is planar the
<structfield>bytesperline</structfield> value applies to the largest
plane and is divided by the same factor as the
<structfield>width</structfield> field for any smaller planes. For
example the Cb and Cr planes of a YUV 4:2:0 image have half as many
padding bytes following each line as the Y plane. To avoid ambiguities
drivers must return a <structfield>bytesperline</structfield> value
rounded up to a multiple of the scale factor.</para></entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>sizeimage</structfield></entry>
<entry>Size in bytes of the buffer to hold a complete image,
set by the driver. Usually this is
<structfield>bytesperline</structfield> times
<structfield>height</structfield>. When the image consists of variable
length compressed data this is the maximum number of bytes required to
hold an image.</entry>
</row>
<row>
<entry>&v4l2-colorspace;</entry>
<entry><structfield>colorspace</structfield></entry>
<entry>This information supplements the
<structfield>pixelformat</structfield> and must be set by the driver,
see <xref linkend="colorspaces" />.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>priv</structfield></entry>
<entry>Reserved for custom (driver defined) additional
information about formats. When not used drivers and applications must
set this field to zero.</entry>
</row>
</tbody>
</tgroup>
</table>
<section>
<title>Standard Image Formats</title>
<para>In order to exchange images between drivers and
applications, it is necessary to have standard image data formats
which both sides will interpret the same way. V4L2 includes several
such formats, and this section is intended to be an unambiguous
specification of the standard image data formats in V4L2.</para>
<para>V4L2 drivers are not limited to these formats, however.
Driver-specific formats are possible. In that case the application may
depend on a codec to convert images to one of the standard formats
when needed. But the data can still be stored and retrieved in the
proprietary format. For example, a device may support a proprietary
compressed format. Applications can still capture and save the data in
the compressed format, saving much disk space, and later use a codec
to convert the images to the X Windows screen format when the video is
to be displayed.</para>
<para>Even so, ultimately, some standard formats are needed, so
the V4L2 specification would not be complete without well-defined
standard formats.</para>
<para>The V4L2 standard formats are mainly uncompressed formats. The
pixels are always arranged in memory from left to right, and from top
to bottom. The first byte of data in the image buffer is always for
the leftmost pixel of the topmost row. Following that is the pixel
immediately to its right, and so on until the end of the top row of
pixels. Following the rightmost pixel of the row there may be zero or
more bytes of padding to guarantee that each row of pixel data has a
certain alignment. Following the pad bytes, if any, is data for the
leftmost pixel of the second row from the top, and so on. The last row
has just as many pad bytes after it as the other rows.</para>
<para>In V4L2 each format has an identifier which looks like
<constant>PIX_FMT_XXX</constant>, defined in the <link
linkend="videodev">videodev.h</link> header file. These identifiers
represent <link linkend="v4l2-fourcc">four character codes</link>
which are also listed below, however they are not the same as those
used in the Windows world.</para>
</section>
<section id="colorspaces">
<title>Colorspaces</title>
<para>[intro]</para>
<!-- See proposal by Billy Biggs, video4linux-list@redhat.com
on 11 Oct 2002, subject: "Re: [V4L] Re: v4l2 api", and
http://vektor.theorem.ca/graphics/ycbcr/ and
http://www.inforamp.net/~poynton/notes/colour_and_gamma/index.html -->
<para>
<variablelist>
<varlistentry>
<term>Gamma Correction</term>
<listitem>
<para>[to do]</para>
<para>E'<subscript>R</subscript> = f(R)</para>
<para>E'<subscript>G</subscript> = f(G)</para>
<para>E'<subscript>B</subscript> = f(B)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Construction of luminance and color-difference
signals</term>
<listitem>
<para>[to do]</para>
<para>E'<subscript>Y</subscript> =
Coeff<subscript>R</subscript> E'<subscript>R</subscript>
+ Coeff<subscript>G</subscript> E'<subscript>G</subscript>
+ Coeff<subscript>B</subscript> E'<subscript>B</subscript></para>
<para>(E'<subscript>R</subscript> - E'<subscript>Y</subscript>) = E'<subscript>R</subscript>
- Coeff<subscript>R</subscript> E'<subscript>R</subscript>
- Coeff<subscript>G</subscript> E'<subscript>G</subscript>
- Coeff<subscript>B</subscript> E'<subscript>B</subscript></para>
<para>(E'<subscript>B</subscript> - E'<subscript>Y</subscript>) = E'<subscript>B</subscript>
- Coeff<subscript>R</subscript> E'<subscript>R</subscript>
- Coeff<subscript>G</subscript> E'<subscript>G</subscript>
- Coeff<subscript>B</subscript> E'<subscript>B</subscript></para>
</listitem>
</varlistentry>
<varlistentry>
<term>Re-normalized color-difference signals</term>
<listitem>
<para>The color-difference signals are scaled back to unity
range [-0.5;+0.5]:</para>
<para>K<subscript>B</subscript> = 0.5 / (1 - Coeff<subscript>B</subscript>)</para>
<para>K<subscript>R</subscript> = 0.5 / (1 - Coeff<subscript>R</subscript>)</para>
<para>P<subscript>B</subscript> =
K<subscript>B</subscript> (E'<subscript>B</subscript> - E'<subscript>Y</subscript>) =
0.5 (Coeff<subscript>R</subscript> / Coeff<subscript>B</subscript>) E'<subscript>R</subscript>
+ 0.5 (Coeff<subscript>G</subscript> / Coeff<subscript>B</subscript>) E'<subscript>G</subscript>
+ 0.5 E'<subscript>B</subscript></para>
<para>P<subscript>R</subscript> =
K<subscript>R</subscript> (E'<subscript>R</subscript> - E'<subscript>Y</subscript>) =
0.5 E'<subscript>R</subscript>
+ 0.5 (Coeff<subscript>G</subscript> / Coeff<subscript>R</subscript>) E'<subscript>G</subscript>
+ 0.5 (Coeff<subscript>B</subscript> / Coeff<subscript>R</subscript>) E'<subscript>B</subscript></para>
</listitem>
</varlistentry>
<varlistentry>
<term>Quantization</term>
<listitem>
<para>[to do]</para>
<para>Y' = (Lum. Levels - 1) &middot; E'<subscript>Y</subscript> + Lum. Offset</para>
<para>C<subscript>B</subscript> = (Chrom. Levels - 1)
&middot; P<subscript>B</subscript> + Chrom. Offset</para>
<para>C<subscript>R</subscript> = (Chrom. Levels - 1)
&middot; P<subscript>R</subscript> + Chrom. Offset</para>
<para>Rounding to the nearest integer and clamping to the range
[0;255] finally yields the digital color components Y'CbCr
stored in YUV images.</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<example>
<title>ITU-R Rec. BT.601 color conversion</title>
<para>Forward Transformation</para>
<programlisting>
int ER, EG, EB; /* gamma corrected RGB input [0;255] */
int Y1, Cb, Cr; /* output [0;255] */
double r, g, b; /* temporaries */
double y1, pb, pr;
int
clamp (double x)
{
int r = x; /* round to nearest */
if (r &lt; 0) return 0;
else if (r &gt; 255) return 255;
else return r;
}
r = ER / 255.0;
g = EG / 255.0;
b = EB / 255.0;
y1 = 0.299 * r + 0.587 * g + 0.114 * b;
pb = -0.169 * r - 0.331 * g + 0.5 * b;
pr = 0.5 * r - 0.419 * g - 0.081 * b;
Y1 = clamp (219 * y1 + 16);
Cb = clamp (224 * pb + 128);
Cr = clamp (224 * pr + 128);
/* or shorter */
y1 = 0.299 * ER + 0.587 * EG + 0.114 * EB;
Y1 = clamp ( (219 / 255.0) * y1 + 16);
Cb = clamp (((224 / 255.0) / (2 - 2 * 0.114)) * (EB - y1) + 128);
Cr = clamp (((224 / 255.0) / (2 - 2 * 0.299)) * (ER - y1) + 128);
</programlisting>
<para>Inverse Transformation</para>
<programlisting>
int Y1, Cb, Cr; /* gamma pre-corrected input [0;255] */
int ER, EG, EB; /* output [0;255] */
double r, g, b; /* temporaries */
double y1, pb, pr;
int
clamp (double x)
{
int r = x; /* round to nearest */
if (r &lt; 0) return 0;
else if (r &gt; 255) return 255;
else return r;
}
y1 = (255 / 219.0) * (Y1 - 16);
pb = (255 / 224.0) * (Cb - 128);
pr = (255 / 224.0) * (Cr - 128);
r = 1.0 * y1 + 0 * pb + 1.402 * pr;
g = 1.0 * y1 - 0.344 * pb - 0.714 * pr;
b = 1.0 * y1 + 1.772 * pb + 0 * pr;
ER = clamp (r * 255); /* [ok? one should prob. limit y1,pb,pr] */
EG = clamp (g * 255);
EB = clamp (b * 255);
</programlisting>
</example>
<table pgwide="1" id="v4l2-colorspace" orient="land">
<title>enum v4l2_colorspace</title>
<tgroup cols="11" align="center">
<colspec align="left" />
<colspec align="center" />
<colspec align="left" />
<colspec colname="cr" />
<colspec colname="cg" />
<colspec colname="cb" />
<colspec colname="wp" />
<colspec colname="gc" />
<colspec colname="lum" />
<colspec colname="qy" />
<colspec colname="qc" />
<spanspec namest="cr" nameend="cb" spanname="chrom" />
<spanspec namest="qy" nameend="qc" spanname="quant" />
<spanspec namest="lum" nameend="qc" spanname="spam" />
<thead>
<row>
<entry morerows="1">Identifier</entry>
<entry morerows="1">Value</entry>
<entry morerows="1">Description</entry>
<entry spanname="chrom">Chromaticities<footnote>
<para>The coordinates of the color primaries are
given in the CIE system (1931)</para>
</footnote></entry>
<entry morerows="1">White Point</entry>
<entry morerows="1">Gamma Correction</entry>
<entry morerows="1">Luminance E'<subscript>Y</subscript></entry>
<entry spanname="quant">Quantization</entry>
</row>
<row>
<entry>Red</entry>
<entry>Green</entry>
<entry>Blue</entry>
<entry>Y'</entry>
<entry>Cb, Cr</entry>
</row>
</thead>
<tbody valign="top">
<row>
<entry><constant>V4L2_COLORSPACE_SMPTE170M</constant></entry>
<entry>1</entry>
<entry>NTSC/PAL according to <xref linkend="smpte170m" />,
<xref linkend="itu601" /></entry>
<entry>x&nbsp;=&nbsp;0.630, y&nbsp;=&nbsp;0.340</entry>
<entry>x&nbsp;=&nbsp;0.310, y&nbsp;=&nbsp;0.595</entry>
<entry>x&nbsp;=&nbsp;0.155, y&nbsp;=&nbsp;0.070</entry>
<entry>x&nbsp;=&nbsp;0.3127, y&nbsp;=&nbsp;0.3290,
Illuminant D<subscript>65</subscript></entry>
<entry>E' = 4.5&nbsp;I&nbsp;for&nbsp;I&nbsp;&le;0.018,
1.099&nbsp;I<superscript>0.45</superscript>&nbsp;-&nbsp;0.099&nbsp;for&nbsp;0.018&nbsp;&lt;&nbsp;I</entry>
<entry>0.299&nbsp;E'<subscript>R</subscript>
+&nbsp;0.587&nbsp;E'<subscript>G</subscript>
+&nbsp;0.114&nbsp;E'<subscript>B</subscript></entry>
<entry>219&nbsp;E'<subscript>Y</subscript>&nbsp;+&nbsp;16</entry>
<entry>224&nbsp;P<subscript>B,R</subscript>&nbsp;+&nbsp;128</entry>
</row>
<row>
<entry><constant>V4L2_COLORSPACE_SMPTE240M</constant></entry>
<entry>2</entry>
<entry>1125-Line (US) HDTV, see <xref
linkend="smpte240m" /></entry>
<entry>x&nbsp;=&nbsp;0.630, y&nbsp;=&nbsp;0.340</entry>
<entry>x&nbsp;=&nbsp;0.310, y&nbsp;=&nbsp;0.595</entry>
<entry>x&nbsp;=&nbsp;0.155, y&nbsp;=&nbsp;0.070</entry>
<entry>x&nbsp;=&nbsp;0.3127, y&nbsp;=&nbsp;0.3290,
Illuminant D<subscript>65</subscript></entry>
<entry>E' = 4&nbsp;I&nbsp;for&nbsp;I&nbsp;&le;0.0228,
1.1115&nbsp;I<superscript>0.45</superscript>&nbsp;-&nbsp;0.1115&nbsp;for&nbsp;0.0228&nbsp;&lt;&nbsp;I</entry>
<entry>0.212&nbsp;E'<subscript>R</subscript>
+&nbsp;0.701&nbsp;E'<subscript>G</subscript>
+&nbsp;0.087&nbsp;E'<subscript>B</subscript></entry>
<entry>219&nbsp;E'<subscript>Y</subscript>&nbsp;+&nbsp;16</entry>
<entry>224&nbsp;P<subscript>B,R</subscript>&nbsp;+&nbsp;128</entry>
</row>
<row>
<entry><constant>V4L2_COLORSPACE_REC709</constant></entry>
<entry>3</entry>
<entry>HDTV and modern devices, see <xref
linkend="itu709" /></entry>
<entry>x&nbsp;=&nbsp;0.640, y&nbsp;=&nbsp;0.330</entry>
<entry>x&nbsp;=&nbsp;0.300, y&nbsp;=&nbsp;0.600</entry>
<entry>x&nbsp;=&nbsp;0.150, y&nbsp;=&nbsp;0.060</entry>
<entry>x&nbsp;=&nbsp;0.3127, y&nbsp;=&nbsp;0.3290,
Illuminant D<subscript>65</subscript></entry>
<entry>E' = 4.5&nbsp;I&nbsp;for&nbsp;I&nbsp;&le;0.018,
1.099&nbsp;I<superscript>0.45</superscript>&nbsp;-&nbsp;0.099&nbsp;for&nbsp;0.018&nbsp;&lt;&nbsp;I</entry>
<entry>0.2125&nbsp;E'<subscript>R</subscript>
+&nbsp;0.7154&nbsp;E'<subscript>G</subscript>
+&nbsp;0.0721&nbsp;E'<subscript>B</subscript></entry>
<entry>219&nbsp;E'<subscript>Y</subscript>&nbsp;+&nbsp;16</entry>
<entry>224&nbsp;P<subscript>B,R</subscript>&nbsp;+&nbsp;128</entry>
</row>
<row>
<entry><constant>V4L2_COLORSPACE_BT878</constant></entry>
<entry>4</entry>
<entry>Broken Bt878 extents<footnote>
<para>The ubiquitous Bt878 video capture chip
quantizes E'<subscript>Y</subscript> to 238 levels, yielding a range
of Y' = 16 &hellip; 253, unlike Rec. 601 Y' = 16 &hellip;
235. This is not a typo in the Bt878 documentation, it has been
implemented in silicon. The chroma extents are unclear.</para>
</footnote>, <xref linkend="itu601" /></entry>
<entry>?</entry>
<entry>?</entry>
<entry>?</entry>
<entry>?</entry>
<entry>?</entry>
<entry>0.299&nbsp;E'<subscript>R</subscript>
+&nbsp;0.587&nbsp;E'<subscript>G</subscript>
+&nbsp;0.114&nbsp;E'<subscript>B</subscript></entry>
<entry><emphasis>237</emphasis>&nbsp;E'<subscript>Y</subscript>&nbsp;+&nbsp;16</entry>
<entry>224&nbsp;P<subscript>B,R</subscript>&nbsp;+&nbsp;128 (probably)</entry>
</row>
<row>
<entry><constant>V4L2_COLORSPACE_470_SYSTEM_M</constant></entry>
<entry>5</entry>
<entry>M/NTSC<footnote>
<para>No identifier exists for M/PAL which uses
the chromaticities of M/NTSC, the remaining parameters are equal to B and
G/PAL.</para>
</footnote> according to <xref linkend="itu470" />, <xref
linkend="itu601" /></entry>
<entry>x&nbsp;=&nbsp;0.67, y&nbsp;=&nbsp;0.33</entry>
<entry>x&nbsp;=&nbsp;0.21, y&nbsp;=&nbsp;0.71</entry>
<entry>x&nbsp;=&nbsp;0.14, y&nbsp;=&nbsp;0.08</entry>
<entry>x&nbsp;=&nbsp;0.310, y&nbsp;=&nbsp;0.316, Illuminant C</entry>
<entry>?</entry>
<entry>0.299&nbsp;E'<subscript>R</subscript>
+&nbsp;0.587&nbsp;E'<subscript>G</subscript>
+&nbsp;0.114&nbsp;E'<subscript>B</subscript></entry>
<entry>219&nbsp;E'<subscript>Y</subscript>&nbsp;+&nbsp;16</entry>
<entry>224&nbsp;P<subscript>B,R</subscript>&nbsp;+&nbsp;128</entry>
</row>
<row>
<entry><constant>V4L2_COLORSPACE_470_SYSTEM_BG</constant></entry>
<entry>6</entry>
<entry>625-line PAL and SECAM systems according to <xref
linkend="itu470" />, <xref linkend="itu601" /></entry>
<entry>x&nbsp;=&nbsp;0.64, y&nbsp;=&nbsp;0.33</entry>
<entry>x&nbsp;=&nbsp;0.29, y&nbsp;=&nbsp;0.60</entry>
<entry>x&nbsp;=&nbsp;0.15, y&nbsp;=&nbsp;0.06</entry>
<entry>x&nbsp;=&nbsp;0.313, y&nbsp;=&nbsp;0.329,
Illuminant D<subscript>65</subscript></entry>
<entry>?</entry>
<entry>0.299&nbsp;E'<subscript>R</subscript>
+&nbsp;0.587&nbsp;E'<subscript>G</subscript>
+&nbsp;0.114&nbsp;E'<subscript>B</subscript></entry>
<entry>219&nbsp;E'<subscript>Y</subscript>&nbsp;+&nbsp;16</entry>
<entry>224&nbsp;P<subscript>B,R</subscript>&nbsp;+&nbsp;128</entry>
</row>
<row>
<entry><constant>V4L2_COLORSPACE_JPEG</constant></entry>
<entry>7</entry>
<entry>JPEG Y'CbCr, see <xref linkend="jfif" />, <xref linkend="itu601" /></entry>
<entry>?</entry>
<entry>?</entry>
<entry>?</entry>
<entry>?</entry>
<entry>?</entry>
<entry>0.299&nbsp;E'<subscript>R</subscript>
+&nbsp;0.587&nbsp;E'<subscript>G</subscript>
+&nbsp;0.114&nbsp;E'<subscript>B</subscript></entry>
<entry>256&nbsp;E'<subscript>Y</subscript>&nbsp;+&nbsp;16<footnote>
<para>Note JFIF quantizes
Y'P<subscript>B</subscript>P<subscript>R</subscript> in range [0;+1] and
[-0.5;+0.5] to <emphasis>257</emphasis> levels, however Y'CbCr signals
are still clamped to [0;255].</para>
</footnote></entry>
<entry>256&nbsp;P<subscript>B,R</subscript>&nbsp;+&nbsp;128</entry>
</row>
<row>
<entry><constant>V4L2_COLORSPACE_SRGB</constant></entry>
<entry>8</entry>
<entry>[?]</entry>
<entry>x&nbsp;=&nbsp;0.640, y&nbsp;=&nbsp;0.330</entry>
<entry>x&nbsp;=&nbsp;0.300, y&nbsp;=&nbsp;0.600</entry>
<entry>x&nbsp;=&nbsp;0.150, y&nbsp;=&nbsp;0.060</entry>
<entry>x&nbsp;=&nbsp;0.3127, y&nbsp;=&nbsp;0.3290,
Illuminant D<subscript>65</subscript></entry>
<entry>E' = 4.5&nbsp;I&nbsp;for&nbsp;I&nbsp;&le;0.018,
1.099&nbsp;I<superscript>0.45</superscript>&nbsp;-&nbsp;0.099&nbsp;for&nbsp;0.018&nbsp;&lt;&nbsp;I</entry>
<entry spanname="spam">n/a</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section id="pixfmt-indexed">
<title>Indexed Format</title>
<para>In this format each pixel is represented by an 8 bit index
into a 256 entry ARGB palette. It is intended for <link
linkend="osd">Video Output Overlays</link> only. There are no ioctls to
access the palette, this must be done with ioctls of the Linux framebuffer API.</para>
<table pgwide="0" frame="none">
<title>Indexed Image Format</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" />
<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</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>
</row>
</thead>
<tbody valign="top">
<row id="V4L2-PIX-FMT-PAL8">
<entry><constant>V4L2_PIX_FMT_PAL8</constant></entry>
<entry>'PAL8'</entry>
<entry></entry>
<entry>i<subscript>7</subscript></entry>
<entry>i<subscript>6</subscript></entry>
<entry>i<subscript>5</subscript></entry>
<entry>i<subscript>4</subscript></entry>
<entry>i<subscript>3</subscript></entry>
<entry>i<subscript>2</subscript></entry>
<entry>i<subscript>1</subscript></entry>
<entry>i<subscript>0</subscript></entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section id="pixfmt-rgb">
<title>RGB Formats</title>
&sub-packed-rgb;
&sub-sbggr8;
&sub-sgbrg8;
&sub-sgrbg8;
&sub-sbggr16;
</section>
<section id="yuv-formats">
<title>YUV Formats</title>
<para>YUV is the format native to TV broadcast and composite video
signals. It separates the brightness information (Y) from the color
information (U and V or Cb and Cr). The color information consists of
red and blue <emphasis>color difference</emphasis> signals, this way
the green component can be reconstructed by subtracting from the
brightness component. See <xref linkend="colorspaces" /> for conversion
examples. YUV was chosen because early television would only transmit
brightness information. To add color in a way compatible with existing
receivers a new signal carrier was added to transmit the color
difference signals. Secondary in the YUV format the U and V components
usually have lower resolution than the Y component. This is an analog
video compression technique taking advantage of a property of the
human visual system, being more sensitive to brightness
information.</para>
&sub-packed-yuv;
&sub-grey;
&sub-y16;
&sub-yuyv;
&sub-uyvy;
&sub-yvyu;
&sub-vyuy;
&sub-y41p;
&sub-yuv420;
&sub-yuv410;
&sub-yuv422p;
&sub-yuv411p;
&sub-nv12;
&sub-nv16;
</section>
<section>
<title>Compressed Formats</title>
<table pgwide="1" frame="none" id="compressed-formats">
<title>Compressed Image Formats</title>
<tgroup cols="3" align="left">
&cs-def;
<thead>
<row>
<entry>Identifier</entry>
<entry>Code</entry>
<entry>Details</entry>
</row>
</thead>
<tbody valign="top">
<row id="V4L2-PIX-FMT-JPEG">
<entry><constant>V4L2_PIX_FMT_JPEG</constant></entry>
<entry>'JPEG'</entry>
<entry>TBD. See also &VIDIOC-G-JPEGCOMP;,
&VIDIOC-S-JPEGCOMP;.</entry>
</row>
<row id="V4L2-PIX-FMT-MPEG">
<entry><constant>V4L2_PIX_FMT_MPEG</constant></entry>
<entry>'MPEG'</entry>
<entry>MPEG stream. The actual format is determined by
extended control <constant>V4L2_CID_MPEG_STREAM_TYPE</constant>, see
<xref linkend="mpeg-control-id" />.</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section id="pixfmt-reserved">
<title>Reserved Format Identifiers</title>
<para>These formats are not defined by this specification, they
are just listed for reference and to avoid naming conflicts. If you
want to register your own format, send an e-mail to the linux-media mailing
list &v4l-ml; for inclusion in the <filename>videodev2.h</filename>
file. If you want to share your format with other developers add a
link to your documentation and send a copy to the linux-media mailing list
for inclusion in this section. If you think your format should be listed
in a standard format section please make a proposal on the linux-media mailing
list.</para>
<table pgwide="1" frame="none" id="reserved-formats">
<title>Reserved Image Formats</title>
<tgroup cols="3" align="left">
&cs-def;
<thead>
<row>
<entry>Identifier</entry>
<entry>Code</entry>
<entry>Details</entry>
</row>
</thead>
<tbody valign="top">
<row id="V4L2-PIX-FMT-DV">
<entry><constant>V4L2_PIX_FMT_DV</constant></entry>
<entry>'dvsd'</entry>
<entry>unknown</entry>
</row>
<row id="V4L2-PIX-FMT-ET61X251">
<entry><constant>V4L2_PIX_FMT_ET61X251</constant></entry>
<entry>'E625'</entry>
<entry>Compressed format of the ET61X251 driver.</entry>
</row>
<row id="V4L2-PIX-FMT-HI240">
<entry><constant>V4L2_PIX_FMT_HI240</constant></entry>
<entry>'HI24'</entry>
<entry><para>8 bit RGB format used by the BTTV driver.</para></entry>
</row>
<row id="V4L2-PIX-FMT-HM12">
<entry><constant>V4L2_PIX_FMT_HM12</constant></entry>
<entry>'HM12'</entry>
<entry><para>YUV 4:2:0 format used by the
IVTV driver, <ulink url="http://www.ivtvdriver.org/">
http://www.ivtvdriver.org/</ulink></para><para>The format is documented in the
kernel sources in the file <filename>Documentation/video4linux/cx2341x/README.hm12</filename>
</para></entry>
</row>
<row id="V4L2-PIX-FMT-SPCA501">
<entry><constant>V4L2_PIX_FMT_SPCA501</constant></entry>
<entry>'S501'</entry>
<entry>YUYV per line used by the gspca driver.</entry>
</row>
<row id="V4L2-PIX-FMT-SPCA505">
<entry><constant>V4L2_PIX_FMT_SPCA505</constant></entry>
<entry>'S505'</entry>
<entry>YYUV per line used by the gspca driver.</entry>
</row>
<row id="V4L2-PIX-FMT-SPCA508">
<entry><constant>V4L2_PIX_FMT_SPCA508</constant></entry>
<entry>'S508'</entry>
<entry>YUVY per line used by the gspca driver.</entry>
</row>
<row id="V4L2-PIX-FMT-SPCA561">
<entry><constant>V4L2_PIX_FMT_SPCA561</constant></entry>
<entry>'S561'</entry>
<entry>Compressed GBRG Bayer format used by the gspca driver.</entry>
</row>
<row id="V4L2-PIX-FMT-SGRBG10">
<entry><constant>V4L2_PIX_FMT_SGRBG10</constant></entry>
<entry>'DA10'</entry>
<entry>10 bit raw Bayer, expanded to 16 bits.</entry>
</row>
<row id="V4L2-PIX-FMT-SGRBG10DPCM8">
<entry><constant>V4L2_PIX_FMT_SGRBG10DPCM8</constant></entry>
<entry>'DB10'</entry>
<entry>10 bit raw Bayer DPCM compressed to 8 bits.</entry>
</row>
<row id="V4L2-PIX-FMT-PAC207">
<entry><constant>V4L2_PIX_FMT_PAC207</constant></entry>
<entry>'P207'</entry>
<entry>Compressed BGGR Bayer format used by the gspca driver.</entry>
</row>
<row id="V4L2-PIX-FMT-MR97310A">
<entry><constant>V4L2_PIX_FMT_MR97310A</constant></entry>
<entry>'M310'</entry>
<entry>Compressed BGGR Bayer format used by the gspca driver.</entry>
</row>
<row id="V4L2-PIX-FMT-OV511">
<entry><constant>V4L2_PIX_FMT_OV511</constant></entry>
<entry>'O511'</entry>
<entry>OV511 JPEG format used by the gspca driver.</entry>
</row>
<row id="V4L2-PIX-FMT-OV518">
<entry><constant>V4L2_PIX_FMT_OV518</constant></entry>
<entry>'O518'</entry>
<entry>OV518 JPEG format used by the gspca driver.</entry>
</row>
<row id="V4L2-PIX-FMT-PJPG">
<entry><constant>V4L2_PIX_FMT_PJPG</constant></entry>
<entry>'PJPG'</entry>
<entry>Pixart 73xx JPEG format used by the gspca driver.</entry>
</row>
<row id="V4L2-PIX-FMT-SQ905C">
<entry><constant>V4L2_PIX_FMT_SQ905C</constant></entry>
<entry>'905C'</entry>
<entry>Compressed RGGB bayer format used by the gspca driver.</entry>
</row>
<row id="V4L2-PIX-FMT-MJPEG">
<entry><constant>V4L2_PIX_FMT_MJPEG</constant></entry>
<entry>'MJPG'</entry>
<entry>Compressed format used by the Zoran driver</entry>
</row>
<row id="V4L2-PIX-FMT-PWC1">
<entry><constant>V4L2_PIX_FMT_PWC1</constant></entry>
<entry>'PWC1'</entry>
<entry>Compressed format of the PWC driver.</entry>
</row>
<row id="V4L2-PIX-FMT-PWC2">
<entry><constant>V4L2_PIX_FMT_PWC2</constant></entry>
<entry>'PWC2'</entry>
<entry>Compressed format of the PWC driver.</entry>
</row>
<row id="V4L2-PIX-FMT-SN9C10X">
<entry><constant>V4L2_PIX_FMT_SN9C10X</constant></entry>
<entry>'S910'</entry>
<entry>Compressed format of the SN9C102 driver.</entry>
</row>
<row id="V4L2-PIX-FMT-SN9C20X-I420">
<entry><constant>V4L2_PIX_FMT_SN9C20X_I420</constant></entry>
<entry>'S920'</entry>
<entry>YUV 4:2:0 format of the gspca sn9c20x driver.</entry>
</row>
<row id="V4L2-PIX-FMT-WNVA">
<entry><constant>V4L2_PIX_FMT_WNVA</constant></entry>
<entry>'WNVA'</entry>
<entry><para>Used by the Winnov Videum driver, <ulink
url="http://www.thedirks.org/winnov/">
http://www.thedirks.org/winnov/</ulink></para></entry>
</row>
<row id="V4L2-PIX-FMT-YYUV">
<entry><constant>V4L2_PIX_FMT_YYUV</constant></entry>
<entry>'YYUV'</entry>
<entry>unknown</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

170
Documentation/DocBook/v4l/remote_controllers.xml Normal file
View File

@ -0,0 +1,170 @@
<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 that the same manufacturer to ship different types of controls, depending on the device.</para>
<para>Unfortunately, during several years, there weren't any effort to uniform the IR keycodes under different boards. 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">Miscelaneous 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>

481
Documentation/DocBook/v4l/v4l2.xml Normal file
View File

@ -0,0 +1,481 @@
<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@radix.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>
</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>
<holder>Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin
Rubli, Andy Walls, Mauro Carvalho Chehab</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.sgml), along with the possible impact on existing drivers and
applications. -->
<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 2.6.32</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>
</chapter>
<chapter id="driver">
&sub-driver;
</chapter>
<chapter id="libv4l">
&sub-libv4l;
</chapter>
<chapter id="compat">
&sub-compat;
</chapter>
<appendix id="function_ref">
<title>Function Reference</title>
<reference id="user-func">
<!-- Keep this alphabetically sorted. -->
&sub-close;
&sub-ioctl;
<!-- All ioctls go here. -->
&sub-cropcap;
&sub-dbg-g-chip-ident;
&sub-dbg-g-register;
&sub-encoder-cmd;
&sub-enumaudio;
&sub-enumaudioout;
&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-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-sliced-vbi-cap;
&sub-g-std;
&sub-g-tuner;
&sub-log-status;
&sub-overlay;
&sub-qbuf;
&sub-querybuf;
&sub-querycap;
&sub-queryctrl;
&sub-querystd;
&sub-reqbufs;
&sub-s-hw-freq-seek;
&sub-streamon;
<!-- End of ioctls. -->
&sub-mmap;
&sub-munmap;
&sub-open;
&sub-poll;
&sub-read;
&sub-select;
&sub-write;
</reference>
</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;

164
Documentation/DocBook/v4l/v4l2grab.c.xml Normal file
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>

BIN
Documentation/DocBook/v4l/vbi_525.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.6 KiB

BIN
Documentation/DocBook/v4l/vbi_525.pdf Normal file
View File

Binary file not shown.

BIN
Documentation/DocBook/v4l/vbi_625.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 5.0 KiB

BIN
Documentation/DocBook/v4l/vbi_625.pdf Normal file
View File

Binary file not shown.

BIN
Documentation/DocBook/v4l/vbi_hsync.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.3 KiB

BIN
Documentation/DocBook/v4l/vbi_hsync.pdf Normal file
View File

Binary file not shown.

1639
Documentation/DocBook/v4l/videodev2.h.xml Normal file
View File

File diff suppressed because it is too large Load Diff

174
Documentation/DocBook/v4l/vidioc-cropcap.xml Normal file
View File

@ -0,0 +1,174 @@
<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 or the ioctl is not supported. This is not permitted for
video capture, output and overlay devices, which must support
<constant>VIDIOC_CROPCAP</constant>.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

275
Documentation/DocBook/v4l/vidioc-dbg-g-chip-ident.xml Normal file
View File

@ -0,0 +1,275 @@
<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 driver does not support this ioctl, or the
<structfield>match_type</structfield> is invalid.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

275
Documentation/DocBook/v4l/vidioc-dbg-g-register.xml Normal file
View File

@ -0,0 +1,275 @@
<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>EINVAL</errorcode></term>
<listitem>
<para>The driver does not support this ioctl, or the kernel
was not compiled with the <constant>CONFIG_VIDEO_ADV_DEBUG</constant>
option, or the <structfield>match_type</structfield> is invalid, or the
selected chip or register does not exist.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EPERM</errorcode></term>
<listitem>
<para>Insufficient permissions. Root privileges are required
to execute these ioctls.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

204
Documentation/DocBook/v4l/vidioc-encoder-cmd.xml Normal file
View File

@ -0,0 +1,204 @@
<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>() call sends a 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>() call sends an 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 driver does not support this ioctl, or 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>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

164
Documentation/DocBook/v4l/vidioc-enum-fmt.xml Normal file
View File

@ -0,0 +1,164 @@
<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_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>__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>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

270
Documentation/DocBook/v4l/vidioc-enum-frameintervals.xml Normal file
View File

@ -0,0 +1,270 @@
<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;
<para>See the description section above for a list of return
values that <varname>errno</varname> can have.</para>
</refsect1>
</refentry>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

282
Documentation/DocBook/v4l/vidioc-enum-framesizes.xml Normal file
View File

@ -0,0 +1,282 @@
<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;
<para>See the description section above for a list of return
values that <varname>errno</varname> can have.</para>
</refsect1>
</refentry>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

86
Documentation/DocBook/v4l/vidioc-enumaudio.xml Normal file
View File

@ -0,0 +1,86 @@
<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, or
there are no audio inputs at all and this ioctl is not
supported.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

89
Documentation/DocBook/v4l/vidioc-enumaudioout.xml Normal file
View File

@ -0,0 +1,89 @@
<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, or
there are no audio outputs at all and this ioctl is not
supported.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

287
Documentation/DocBook/v4l/vidioc-enuminput.xml Normal file
View File

@ -0,0 +1,287 @@
<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>reserved</structfield>[4]</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>
</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>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

172
Documentation/DocBook/v4l/vidioc-enumoutput.xml Normal file
View File

@ -0,0 +1,172 @@
<refentry id="vidioc-enumoutput">
<refmeta>
<refentrytitle>ioctl VIDIOC_ENUMOUTPUT</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>VIDIOC_ENUMOUTPUT</refname>
<refpurpose>Enumerate video 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_output *<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_ENUMOUTPUT</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 outputs applications
initialize the <structfield>index</structfield> field of &v4l2-output;
and call the <constant>VIDIOC_ENUMOUTPUT</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
outputs applications shall begin at index zero, incrementing by one
until the driver returns <errorcode>EINVAL</errorcode>.</para>
<table frame="none" pgwide="1" id="v4l2-output">
<title>struct <structname>v4l2_output</structname></title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>__u32</entry>
<entry><structfield>index</structfield></entry>
<entry>Identifies the output, set by the
application.</entry>
</row>
<row>
<entry>__u8</entry>
<entry><structfield>name</structfield>[32]</entry>
<entry>Name of the video output, a NUL-terminated ASCII
string, for example: "Vout". 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 output, see <xref
linkend="output-type" />.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>audioset</structfield></entry>
<entry><para>Drivers can enumerate up to 32 video and
audio outputs. This field shows which audio outputs were
selectable as the current output if this was the currently selected
video output. It is a bit mask. The LSB corresponds to audio output 0,
the MSB to output 31. Any number of bits can be set, or
none.</para><para>When the driver does not enumerate audio outputs no
bits must be set. Applications shall not interpret this as lack of
audio support. Drivers may automatically select audio outputs without
enumerating them.</para><para>For details on audio outputs and how to
select the current output see <xref linkend="audio" />.</para></entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>modulator</structfield></entry>
<entry>Output devices can have zero or more RF modulators.
When the <structfield>type</structfield> is
<constant>V4L2_OUTPUT_TYPE_MODULATOR</constant> this is an RF
connector and this field identifies the modulator. It corresponds to
&v4l2-modulator; field <structfield>index</structfield>. For details
on modulators see <xref linkend="tuner" />.</entry>
</row>
<row>
<entry>&v4l2-std-id;</entry>
<entry><structfield>std</structfield></entry>
<entry>Every video output 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>reserved</structfield>[4]</entry>
<entry>Reserved for future extensions. Drivers must set
the array to zero.</entry>
</row>
</tbody>
</tgroup>
</table>
<table frame="none" pgwide="1" id="output-type">
<title>Output Type</title>
<tgroup cols="3">
&cs-def;
<tbody valign="top">
<row>
<entry><constant>V4L2_OUTPUT_TYPE_MODULATOR</constant></entry>
<entry>1</entry>
<entry>This output is an analog TV modulator.</entry>
</row>
<row>
<entry><constant>V4L2_OUTPUT_TYPE_ANALOG</constant></entry>
<entry>2</entry>
<entry>Analog baseband output, for example Composite /
CVBS, S-Video, RGB.</entry>
</row>
<row>
<entry><constant>V4L2_OUTPUT_TYPE_ANALOGVGAOVERLAY</constant></entry>
<entry>3</entry>
<entry>[?]</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1>
&return-value;
<variablelist>
<varlistentry>
<term><errorcode>EINVAL</errorcode></term>
<listitem>
<para>The &v4l2-output; <structfield>index</structfield>
is out of bounds.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

391
Documentation/DocBook/v4l/vidioc-enumstd.xml Normal file
View File

@ -0,0 +1,391 @@
<refentry id="vidioc-enumstd">
<refmeta>
<refentrytitle>ioctl VIDIOC_ENUMSTD</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>VIDIOC_ENUMSTD</refname>
<refpurpose>Enumerate supported video standards</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_standard *<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_ENUMSTD</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 standard,
especially a custom (driver defined) one, applications initialize the
<structfield>index</structfield> field of &v4l2-standard; and call the
<constant>VIDIOC_ENUMSTD</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 standards
applications shall begin at index zero, incrementing by one until the
driver returns <errorcode>EINVAL</errorcode>. Drivers may enumerate a
different set of standards after switching the video input or
output.<footnote>
<para>The supported standards may overlap and we need an
unambiguous set to find the current standard returned by
<constant>VIDIOC_G_STD</constant>.</para>
</footnote></para>
<table pgwide="1" frame="none" id="v4l2-standard">
<title>struct <structname>v4l2_standard</structname></title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>__u32</entry>
<entry><structfield>index</structfield></entry>
<entry>Number of the video standard, set by the
application.</entry>
</row>
<row>
<entry>&v4l2-std-id;</entry>
<entry><structfield>id</structfield></entry>
<entry>The bits in this field identify the standard as
one of the common standards listed in <xref linkend="v4l2-std-id" />,
or if bits 32 to 63 are set as custom standards. Multiple bits can be
set if the hardware does not distinguish between these standards,
however separate indices do not indicate the opposite. The
<structfield>id</structfield> must be unique. No other enumerated
<structname>v4l2_standard</structname> structure, for this input or
output anyway, can contain the same set of bits.</entry>
</row>
<row>
<entry>__u8</entry>
<entry><structfield>name</structfield>[24]</entry>
<entry>Name of the standard, a NUL-terminated ASCII
string, for example: "PAL-B/G", "NTSC Japan". This information is
intended for the user.</entry>
</row>
<row>
<entry>&v4l2-fract;</entry>
<entry><structfield>frameperiod</structfield></entry>
<entry>The frame period (not field period) is numerator
/ denominator. For example M/NTSC has a frame period of 1001 /
30000 seconds.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>framelines</structfield></entry>
<entry>Total lines per frame including blanking,
e.&nbsp;g. 625 for B/PAL.</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-fract">
<title>struct <structname>v4l2_fract</structname></title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>__u32</entry>
<entry><structfield>numerator</structfield></entry>
<entry></entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>denominator</structfield></entry>
<entry></entry>
</row>
</tbody>
</tgroup>
</table>
<table pgwide="1" frame="none" id="v4l2-std-id">
<title>typedef <structname>v4l2_std_id</structname></title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>__u64</entry>
<entry><structfield>v4l2_std_id</structfield></entry>
<entry>This type is a set, each bit representing another
video standard as listed below and in <xref
linkend="video-standards" />. The 32 most significant bits are reserved
for custom (driver defined) video standards.</entry>
</row>
</tbody>
</tgroup>
</table>
<para><programlisting>
#define V4L2_STD_PAL_B ((v4l2_std_id)0x00000001)
#define V4L2_STD_PAL_B1 ((v4l2_std_id)0x00000002)
#define V4L2_STD_PAL_G ((v4l2_std_id)0x00000004)
#define V4L2_STD_PAL_H ((v4l2_std_id)0x00000008)
#define V4L2_STD_PAL_I ((v4l2_std_id)0x00000010)
#define V4L2_STD_PAL_D ((v4l2_std_id)0x00000020)
#define V4L2_STD_PAL_D1 ((v4l2_std_id)0x00000040)
#define V4L2_STD_PAL_K ((v4l2_std_id)0x00000080)
#define V4L2_STD_PAL_M ((v4l2_std_id)0x00000100)
#define V4L2_STD_PAL_N ((v4l2_std_id)0x00000200)
#define V4L2_STD_PAL_Nc ((v4l2_std_id)0x00000400)
#define V4L2_STD_PAL_60 ((v4l2_std_id)0x00000800)
</programlisting></para><para><constant>V4L2_STD_PAL_60</constant> is
a hybrid standard with 525 lines, 60 Hz refresh rate, and PAL color
modulation with a 4.43 MHz color subcarrier. Some PAL video recorders
can play back NTSC tapes in this mode for display on a 50/60 Hz agnostic
PAL TV.</para><para><programlisting>
#define V4L2_STD_NTSC_M ((v4l2_std_id)0x00001000)
#define V4L2_STD_NTSC_M_JP ((v4l2_std_id)0x00002000)
#define V4L2_STD_NTSC_443 ((v4l2_std_id)0x00004000)
</programlisting></para><para><constant>V4L2_STD_NTSC_443</constant>
is a hybrid standard with 525 lines, 60 Hz refresh rate, and NTSC
color modulation with a 4.43 MHz color
subcarrier.</para><para><programlisting>
#define V4L2_STD_NTSC_M_KR ((v4l2_std_id)0x00008000)
#define V4L2_STD_SECAM_B ((v4l2_std_id)0x00010000)
#define V4L2_STD_SECAM_D ((v4l2_std_id)0x00020000)
#define V4L2_STD_SECAM_G ((v4l2_std_id)0x00040000)
#define V4L2_STD_SECAM_H ((v4l2_std_id)0x00080000)
#define V4L2_STD_SECAM_K ((v4l2_std_id)0x00100000)
#define V4L2_STD_SECAM_K1 ((v4l2_std_id)0x00200000)
#define V4L2_STD_SECAM_L ((v4l2_std_id)0x00400000)
#define V4L2_STD_SECAM_LC ((v4l2_std_id)0x00800000)
/* ATSC/HDTV */
#define V4L2_STD_ATSC_8_VSB ((v4l2_std_id)0x01000000)
#define V4L2_STD_ATSC_16_VSB ((v4l2_std_id)0x02000000)
</programlisting></para><para><!-- ATSC proposal by Mark McClelland,
video4linux-list@redhat.com on 17 Oct 2002
--><constant>V4L2_STD_ATSC_8_VSB</constant> and
<constant>V4L2_STD_ATSC_16_VSB</constant> are U.S. terrestrial digital
TV standards. Presently the V4L2 API does not support digital TV. See
also the Linux DVB API at <ulink
url="http://linuxtv.org">http://linuxtv.org</ulink>.</para>
<para><programlisting>
#define V4L2_STD_PAL_BG (V4L2_STD_PAL_B |\
V4L2_STD_PAL_B1 |\
V4L2_STD_PAL_G)
#define V4L2_STD_B (V4L2_STD_PAL_B |\
V4L2_STD_PAL_B1 |\
V4L2_STD_SECAM_B)
#define V4L2_STD_GH (V4L2_STD_PAL_G |\
V4L2_STD_PAL_H |\
V4L2_STD_SECAM_G |\
V4L2_STD_SECAM_H)
#define V4L2_STD_PAL_DK (V4L2_STD_PAL_D |\
V4L2_STD_PAL_D1 |\
V4L2_STD_PAL_K)
#define V4L2_STD_PAL (V4L2_STD_PAL_BG |\
V4L2_STD_PAL_DK |\
V4L2_STD_PAL_H |\
V4L2_STD_PAL_I)
#define V4L2_STD_NTSC (V4L2_STD_NTSC_M |\
V4L2_STD_NTSC_M_JP |\
V4L2_STD_NTSC_M_KR)
#define V4L2_STD_MN (V4L2_STD_PAL_M |\
V4L2_STD_PAL_N |\
V4L2_STD_PAL_Nc |\
V4L2_STD_NTSC)
#define V4L2_STD_SECAM_DK (V4L2_STD_SECAM_D |\
V4L2_STD_SECAM_K |\
V4L2_STD_SECAM_K1)
#define V4L2_STD_DK (V4L2_STD_PAL_DK |\
V4L2_STD_SECAM_DK)
#define V4L2_STD_SECAM (V4L2_STD_SECAM_B |\
V4L2_STD_SECAM_G |\
V4L2_STD_SECAM_H |\
V4L2_STD_SECAM_DK |\
V4L2_STD_SECAM_L |\
V4L2_STD_SECAM_LC)
#define V4L2_STD_525_60 (V4L2_STD_PAL_M |\
V4L2_STD_PAL_60 |\
V4L2_STD_NTSC |\
V4L2_STD_NTSC_443)
#define V4L2_STD_625_50 (V4L2_STD_PAL |\
V4L2_STD_PAL_N |\
V4L2_STD_PAL_Nc |\
V4L2_STD_SECAM)
#define V4L2_STD_UNKNOWN 0
#define V4L2_STD_ALL (V4L2_STD_525_60 |\
V4L2_STD_625_50)
</programlisting></para>
<table pgwide="1" id="video-standards" orient="land">
<title>Video Standards (based on [<xref linkend="itu470" />])</title>
<tgroup cols="12" colsep="1" rowsep="1" align="center">
<colspec colname="c1" align="left" />
<colspec colname="c2" />
<colspec colname="c3" />
<colspec colname="c4" />
<colspec colname="c5" />
<colspec colnum="7" colname="c7" />
<colspec colnum="9" colname="c9" />
<colspec colnum="12" colname="c12" />
<spanspec namest="c2" nameend="c3" spanname="m" align="center" />
<spanspec namest="c4" nameend="c12" spanname="x" align="center" />
<spanspec namest="c5" nameend="c7" spanname="b" align="center" />
<spanspec namest="c9" nameend="c12" spanname="s" align="center" />
<thead>
<row>
<entry>Characteristics</entry>
<entry><para>M/NTSC<footnote><para>Japan uses a standard
similar to M/NTSC
(V4L2_STD_NTSC_M_JP).</para></footnote></para></entry>
<entry>M/PAL</entry>
<entry><para>N/PAL<footnote><para> The values in
brackets apply to the combination N/PAL a.k.a.
N<subscript>C</subscript> used in Argentina
(V4L2_STD_PAL_Nc).</para></footnote></para></entry>
<entry align="center">B, B1, G/PAL</entry>
<entry align="center">D, D1, K/PAL</entry>
<entry align="center">H/PAL</entry>
<entry align="center">I/PAL</entry>
<entry align="center">B, G/SECAM</entry>
<entry align="center">D, K/SECAM</entry>
<entry align="center">K1/SECAM</entry>
<entry align="center">L/SECAM</entry>
</row>
</thead>
<tbody valign="top">
<row>
<entry>Frame lines</entry>
<entry spanname="m">525</entry>
<entry spanname="x">625</entry>
</row>
<row>
<entry>Frame period (s)</entry>
<entry spanname="m">1001/30000</entry>
<entry spanname="x">1/25</entry>
</row>
<row>
<entry>Chrominance sub-carrier frequency (Hz)</entry>
<entry>3579545 &plusmn;&nbsp;10</entry>
<entry>3579611.49 &plusmn;&nbsp;10</entry>
<entry>4433618.75 &plusmn;&nbsp;5 (3582056.25
&plusmn;&nbsp;5)</entry>
<entry spanname="b">4433618.75 &plusmn;&nbsp;5</entry>
<entry>4433618.75 &plusmn;&nbsp;1</entry>
<entry spanname="s">f<subscript>OR</subscript>&nbsp;=
4406250 &plusmn;&nbsp;2000, f<subscript>OB</subscript>&nbsp;= 4250000
&plusmn;&nbsp;2000</entry>
</row>
<row>
<entry>Nominal radio-frequency channel bandwidth
(MHz)</entry>
<entry>6</entry>
<entry>6</entry>
<entry>6</entry>
<entry>B: 7; B1, G: 8</entry>
<entry>8</entry>
<entry>8</entry>
<entry>8</entry>
<entry>8</entry>
<entry>8</entry>
<entry>8</entry>
<entry>8</entry>
</row>
<row>
<entry>Sound carrier relative to vision carrier
(MHz)</entry>
<entry>+&nbsp;4.5</entry>
<entry>+&nbsp;4.5</entry>
<entry>+&nbsp;4.5</entry>
<entry><para>+&nbsp;5.5 &plusmn;&nbsp;0.001
<footnote><para>In the Federal Republic of Germany, Austria, Italy,
the Netherlands, Slovakia and Switzerland a system of two sound
carriers is used, the frequency of the second carrier being
242.1875&nbsp;kHz above the frequency of the first sound carrier. For
stereophonic sound transmissions a similar system is used in
Australia.</para></footnote> <footnote><para>New Zealand uses a sound
carrier displaced 5.4996 &plusmn;&nbsp;0.0005 MHz from the vision
carrier.</para></footnote> <footnote><para>In Denmark, Finland, New
Zealand, Sweden and Spain a system of two sound carriers is used. In
Iceland, Norway and Poland the same system is being introduced. The
second carrier is 5.85&nbsp;MHz above the vision carrier and is DQPSK
modulated with 728&nbsp;kbit/s sound and data multiplex. (NICAM
system)</para></footnote> <footnote><para>In the United Kingdom, a
system of two sound carriers is used. The second sound carrier is
6.552&nbsp;MHz above the vision carrier and is DQPSK modulated with a
728&nbsp;kbit/s sound and data multiplex able to carry two sound
channels. (NICAM system)</para></footnote></para></entry>
<entry>+&nbsp;6.5 &plusmn;&nbsp;0.001</entry>
<entry>+&nbsp;5.5</entry>
<entry>+&nbsp;5.9996 &plusmn;&nbsp;0.0005</entry>
<entry>+&nbsp;5.5 &plusmn;&nbsp;0.001</entry>
<entry>+&nbsp;6.5 &plusmn;&nbsp;0.001</entry>
<entry>+&nbsp;6.5</entry>
<entry><para>+&nbsp;6.5 <footnote><para>In France, a
digital carrier 5.85 MHz away from the vision carrier may be used in
addition to the main sound carrier. It is modulated in differentially
encoded QPSK with a 728 kbit/s sound and data multiplexer capable of
carrying two sound channels. (NICAM
system)</para></footnote></para></entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1>
&return-value;
<variablelist>
<varlistentry>
<term><errorcode>EINVAL</errorcode></term>
<listitem>
<para>The &v4l2-standard; <structfield>index</structfield>
is out of bounds.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

188
Documentation/DocBook/v4l/vidioc-g-audio.xml Normal file
View File

@ -0,0 +1,188 @@
<refentry id="vidioc-g-audio">
<refmeta>
<refentrytitle>ioctl VIDIOC_G_AUDIO, VIDIOC_S_AUDIO</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>VIDIOC_G_AUDIO</refname>
<refname>VIDIOC_S_AUDIO</refname>
<refpurpose>Query or select the current audio input and its
attributes</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>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ioctl</function></funcdef>
<paramdef>int <parameter>fd</parameter></paramdef>
<paramdef>int <parameter>request</parameter></paramdef>
<paramdef>const 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_G_AUDIO, VIDIOC_S_AUDIO</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>argp</parameter></term>
<listitem>
<para></para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>To query the current audio input applications zero out the
<structfield>reserved</structfield> array of a &v4l2-audio;
and call the <constant>VIDIOC_G_AUDIO</constant> ioctl with a pointer
to this structure. Drivers fill the rest of the structure or return an
&EINVAL; when the device has no audio inputs, or none which combine
with the current video input.</para>
<para>Audio inputs have one writable property, the audio mode. To
select the current audio input <emphasis>and</emphasis> change the
audio mode, applications initialize the
<structfield>index</structfield> and <structfield>mode</structfield>
fields, and the
<structfield>reserved</structfield> array of a
<structname>v4l2_audio</structname> structure and call the
<constant>VIDIOC_S_AUDIO</constant> ioctl. Drivers may switch to a
different audio mode if the request cannot be satisfied. However, this
is a write-only ioctl, it does not return the actual new audio
mode.</para>
<table pgwide="1" frame="none" id="v4l2-audio">
<title>struct <structname>v4l2_audio</structname></title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>__u32</entry>
<entry><structfield>index</structfield></entry>
<entry>Identifies the audio input, set by the
driver or application.</entry>
</row>
<row>
<entry>__u8</entry>
<entry><structfield>name</structfield>[32]</entry>
<entry>Name of the audio input, a NUL-terminated ASCII
string, for example: "Line In". This information is intended for the
user, preferably the connector label on the device itself.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>capability</structfield></entry>
<entry>Audio capability flags, see <xref
linkend="audio-capability" />.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>mode</structfield></entry>
<entry>Audio mode flags set by drivers and applications (on
<constant>VIDIOC_S_AUDIO</constant> ioctl), see <xref linkend="audio-mode" />.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>reserved</structfield>[2]</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="audio-capability">
<title>Audio Capability Flags</title>
<tgroup cols="3">
&cs-def;
<tbody valign="top">
<row>
<entry><constant>V4L2_AUDCAP_STEREO</constant></entry>
<entry>0x00001</entry>
<entry>This is a stereo input. The flag is intended to
automatically disable stereo recording etc. when the signal is always
monaural. The API provides no means to detect if stereo is
<emphasis>received</emphasis>, unless the audio input belongs to a
tuner.</entry>
</row>
<row>
<entry><constant>V4L2_AUDCAP_AVL</constant></entry>
<entry>0x00002</entry>
<entry>Automatic Volume Level mode is supported.</entry>
</row>
</tbody>
</tgroup>
</table>
<table pgwide="1" frame="none" id="audio-mode">
<title>Audio Mode Flags</title>
<tgroup cols="3">
&cs-def;
<tbody valign="top">
<row>
<entry><constant>V4L2_AUDMODE_AVL</constant></entry>
<entry>0x00001</entry>
<entry>AVL mode is on.</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1>
&return-value;
<variablelist>
<varlistentry>
<term><errorcode>EINVAL</errorcode></term>
<listitem>
<para>No audio inputs combine with the current video input,
or the number of the selected audio input is out of bounds or it does
not combine, or there are no audio inputs at all and the ioctl is not
supported.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EBUSY</errorcode></term>
<listitem>
<para>I/O is in progress, the input cannot be
switched.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

154
Documentation/DocBook/v4l/vidioc-g-audioout.xml Normal file
View File

@ -0,0 +1,154 @@
<refentry id="vidioc-g-audioout">
<refmeta>
<refentrytitle>ioctl VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>VIDIOC_G_AUDOUT</refname>
<refname>VIDIOC_S_AUDOUT</refname>
<refpurpose>Query or select the current audio output</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>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ioctl</function></funcdef>
<paramdef>int <parameter>fd</parameter></paramdef>
<paramdef>int <parameter>request</parameter></paramdef>
<paramdef>const 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_G_AUDOUT, VIDIOC_S_AUDOUT</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>argp</parameter></term>
<listitem>
<para></para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>To query the current audio output applications 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 device has no audio inputs, or none which combine
with the current video output.</para>
<para>Audio outputs have no writable properties. Nevertheless, to
select the current audio output applications can initialize the
<structfield>index</structfield> field and
<structfield>reserved</structfield> array (which in the future may
contain writable properties) of a
<structname>v4l2_audioout</structname> structure and call the
<constant>VIDIOC_S_AUDOUT</constant> ioctl. Drivers switch to the
requested output or return the &EINVAL; when the index is out of
bounds. This is a write-only ioctl, it does not return the current
audio output attributes as <constant>VIDIOC_G_AUDOUT</constant>
does.</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>
<table pgwide="1" frame="none" id="v4l2-audioout">
<title>struct <structname>v4l2_audioout</structname></title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>__u32</entry>
<entry><structfield>index</structfield></entry>
<entry>Identifies the audio output, set by the
driver or application.</entry>
</row>
<row>
<entry>__u8</entry>
<entry><structfield>name</structfield>[32]</entry>
<entry>Name of the audio output, a NUL-terminated ASCII
string, for example: "Line Out". This information is intended for the
user, preferably the connector label on the device itself.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>capability</structfield></entry>
<entry>Audio capability flags, none defined yet. Drivers
must set this field to zero.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>mode</structfield></entry>
<entry>Audio mode, none defined yet. Drivers and
applications (on <constant>VIDIOC_S_AUDOUT</constant>) must set this
field to zero.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>reserved</structfield>[2]</entry>
<entry>Reserved for future extensions. Drivers and
applications must set the array to zero.</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1>
&return-value;
<variablelist>
<varlistentry>
<term><errorcode>EINVAL</errorcode></term>
<listitem>
<para>No audio outputs combine with the current video
output, or the number of the selected audio output is out of bounds or
it does not combine, or there are no audio outputs at all and the
ioctl is not supported.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EBUSY</errorcode></term>
<listitem>
<para>I/O is in progress, the output cannot be
switched.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

143
Documentation/DocBook/v4l/vidioc-g-crop.xml Normal file
View File

@ -0,0 +1,143 @@
<refentry id="vidioc-g-crop">
<refmeta>
<refentrytitle>ioctl VIDIOC_G_CROP, VIDIOC_S_CROP</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>VIDIOC_G_CROP</refname>
<refname>VIDIOC_S_CROP</refname>
<refpurpose>Get or set the current cropping rectangle</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_crop *<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_crop *<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_G_CROP, VIDIOC_S_CROP</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>argp</parameter></term>
<listitem>
<para></para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>To query the cropping rectangle size and position
applications set the <structfield>type</structfield> field of a
<structname>v4l2_crop</structname> structure to the respective buffer
(stream) type and call the <constant>VIDIOC_G_CROP</constant> ioctl
with a pointer to this structure. The driver fills the rest of the
structure or returns the &EINVAL; if cropping is not supported.</para>
<para>To change the cropping rectangle applications initialize the
<structfield>type</structfield> and &v4l2-rect; substructure named
<structfield>c</structfield> of a v4l2_crop structure and call the
<constant>VIDIOC_S_CROP</constant> ioctl with a pointer to this
structure.</para>
<para>The driver first adjusts the requested dimensions against
hardware limits, &ie; the bounds given by the capture/output window,
and it rounds to the closest possible values of horizontal and
vertical offset, width and height. In particular the driver must round
the vertical offset of the cropping rectangle to frame lines modulo
two, such that the field order cannot be confused.</para>
<para>Second the driver adjusts the image size (the opposite
rectangle of the scaling process, source or target depending on the
data direction) to the closest size possible while maintaining the
current horizontal and vertical scaling factor.</para>
<para>Finally the driver programs the hardware with the actual
cropping and image parameters. <constant>VIDIOC_S_CROP</constant> is a
write-only ioctl, it does not return the actual parameters. To query
them applications must call <constant>VIDIOC_G_CROP</constant> and
&VIDIOC-G-FMT;. When the parameters are unsuitable the application may
modify the cropping or image parameters and repeat the cycle until
satisfactory parameters have been negotiated.</para>
<para>When cropping is not supported then no parameters are
changed and <constant>VIDIOC_S_CROP</constant> returns the
&EINVAL;.</para>
<table pgwide="1" frame="none" id="v4l2-crop">
<title>struct <structname>v4l2_crop</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>&v4l2-rect;</entry>
<entry><structfield>c</structfield></entry>
<entry>Cropping rectangle. The same co-ordinate system as
for &v4l2-cropcap; <structfield>bounds</structfield> is used.</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1>
&return-value;
<variablelist>
<varlistentry>
<term><errorcode>EINVAL</errorcode></term>
<listitem>
<para>Cropping is not supported.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

130
Documentation/DocBook/v4l/vidioc-g-ctrl.xml Normal file
View File

@ -0,0 +1,130 @@
<refentry id="vidioc-g-ctrl">
<refmeta>
<refentrytitle>ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>VIDIOC_G_CTRL</refname>
<refname>VIDIOC_S_CTRL</refname>
<refpurpose>Get or set the value of a control</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_control
*<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_G_CTRL, VIDIOC_S_CTRL</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>argp</parameter></term>
<listitem>
<para></para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>To get the current value of a control applications
initialize the <structfield>id</structfield> field of a struct
<structname>v4l2_control</structname> and call the
<constant>VIDIOC_G_CTRL</constant> ioctl with a pointer to this
structure. To change the value of a control applications initialize
the <structfield>id</structfield> and <structfield>value</structfield>
fields of a struct <structname>v4l2_control</structname> and call the
<constant>VIDIOC_S_CTRL</constant> ioctl.</para>
<para>When the <structfield>id</structfield> is invalid drivers
return an &EINVAL;. When the <structfield>value</structfield> is out
of bounds drivers can choose to take the closest valid value or return
an &ERANGE;, whatever seems more appropriate. However,
<constant>VIDIOC_S_CTRL</constant> is a write-only ioctl, it does not
return the actual new value.</para>
<para>These ioctls work only with user controls. For other
control classes the &VIDIOC-G-EXT-CTRLS;, &VIDIOC-S-EXT-CTRLS; or
&VIDIOC-TRY-EXT-CTRLS; must be used.</para>
<table pgwide="1" frame="none" id="v4l2-control">
<title>struct <structname>v4l2_control</structname></title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>__u32</entry>
<entry><structfield>id</structfield></entry>
<entry>Identifies the control, set by the
application.</entry>
</row>
<row>
<entry>__s32</entry>
<entry><structfield>value</structfield></entry>
<entry>New value or current value.</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1>
&return-value;
<variablelist>
<varlistentry>
<term><errorcode>EINVAL</errorcode></term>
<listitem>
<para>The &v4l2-control; <structfield>id</structfield> is
invalid.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>ERANGE</errorcode></term>
<listitem>
<para>The &v4l2-control; <structfield>value</structfield>
is out of bounds.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EBUSY</errorcode></term>
<listitem>
<para>The control is temporarily not changeable, possibly
because another applications took over control of the device function
this control belongs to.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

213
Documentation/DocBook/v4l/vidioc-g-enc-index.xml Normal file
View File

@ -0,0 +1,213 @@
<refentry id="vidioc-g-enc-index">
<refmeta>
<refentrytitle>ioctl VIDIOC_G_ENC_INDEX</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>VIDIOC_G_ENC_INDEX</refname>
<refpurpose>Get meta data about a compressed video stream</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_enc_idx *<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_G_ENC_INDEX</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>The <constant>VIDIOC_G_ENC_INDEX</constant> ioctl provides
meta data about a compressed video stream the same or another
application currently reads from the driver, which is useful for
random access into the stream without decoding it.</para>
<para>To read the data applications must call
<constant>VIDIOC_G_ENC_INDEX</constant> with a pointer to a
&v4l2-enc-idx;. On success the driver fills the
<structfield>entry</structfield> array, stores the number of elements
written in the <structfield>entries</structfield> field, and
initializes the <structfield>entries_cap</structfield> field.</para>
<para>Each element of the <structfield>entry</structfield> array
contains meta data about one picture. A
<constant>VIDIOC_G_ENC_INDEX</constant> call reads up to
<constant>V4L2_ENC_IDX_ENTRIES</constant> entries from a driver
buffer, which can hold up to <structfield>entries_cap</structfield>
entries. This number can be lower or higher than
<constant>V4L2_ENC_IDX_ENTRIES</constant>, but not zero. When the
application fails to read the meta data in time the oldest entries
will be lost. When the buffer is empty or no capturing/encoding is in
progress, <structfield>entries</structfield> will be zero.</para>
<para>Currently this ioctl is only defined for MPEG-2 program
streams and video elementary streams.</para>
<table pgwide="1" frame="none" id="v4l2-enc-idx">
<title>struct <structname>v4l2_enc_idx</structname></title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>__u32</entry>
<entry><structfield>entries</structfield></entry>
<entry>The number of entries the driver stored in the
<structfield>entry</structfield> array.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>entries_cap</structfield></entry>
<entry>The number of entries the driver can
buffer. Must be greater than zero.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>reserved</structfield>[4]</entry>
<entry spanname="hspan">Reserved for future extensions.
Drivers must set the array to zero.</entry>
</row>
<row>
<entry>&v4l2-enc-idx-entry;</entry>
<entry><structfield>entry</structfield>[<constant>V4L2_ENC_IDX_ENTRIES</constant>]</entry>
<entry>Meta data about a compressed video stream. Each
element of the array corresponds to one picture, sorted in ascending
order by their <structfield>offset</structfield>.</entry>
</row>
</tbody>
</tgroup>
</table>
<table pgwide="1" frame="none" id="v4l2-enc-idx-entry">
<title>struct <structname>v4l2_enc_idx_entry</structname></title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>__u64</entry>
<entry><structfield>offset</structfield></entry>
<entry>The offset in bytes from the beginning of the
compressed video stream to the beginning of this picture, that is a
<wordasword>PES packet header</wordasword> as defined in <xref
linkend="mpeg2part1" /> or a <wordasword>picture
header</wordasword> as defined in <xref linkend="mpeg2part2" />. When
the encoder is stopped, the driver resets the offset to zero.</entry>
</row>
<row>
<entry>__u64</entry>
<entry><structfield>pts</structfield></entry>
<entry>The 33 bit <wordasword>Presentation Time
Stamp</wordasword> of this picture as defined in <xref
linkend="mpeg2part1" />.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>length</structfield></entry>
<entry>The length of this picture in bytes.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>flags</structfield></entry>
<entry>Flags containing the coding type of this picture, see <xref
linkend="enc-idx-flags" />.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>reserved</structfield>[2]</entry>
<entry>Reserved for future extensions.
Drivers must set the array to zero.</entry>
</row>
</tbody>
</tgroup>
</table>
<table pgwide="1" frame="none" id="enc-idx-flags">
<title>Index Entry Flags</title>
<tgroup cols="3">
&cs-def;
<tbody valign="top">
<row>
<entry><constant>V4L2_ENC_IDX_FRAME_I</constant></entry>
<entry>0x00</entry>
<entry>This is an Intra-coded picture.</entry>
</row>
<row>
<entry><constant>V4L2_ENC_IDX_FRAME_P</constant></entry>
<entry>0x01</entry>
<entry>This is a Predictive-coded picture.</entry>
</row>
<row>
<entry><constant>V4L2_ENC_IDX_FRAME_B</constant></entry>
<entry>0x02</entry>
<entry>This is a Bidirectionally predictive-coded
picture.</entry>
</row>
<row>
<entry><constant>V4L2_ENC_IDX_FRAME_MASK</constant></entry>
<entry>0x0F</entry>
<entry><wordasword>AND</wordasword> the flags field with
this mask to obtain the picture coding type.</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1>
&return-value;
<variablelist>
<varlistentry>
<term><errorcode>EINVAL</errorcode></term>
<listitem>
<para>The driver does not support this ioctl.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

307
Documentation/DocBook/v4l/vidioc-g-ext-ctrls.xml Normal file
View File

@ -0,0 +1,307 @@
<refentry id="vidioc-g-ext-ctrls">
<refmeta>
<refentrytitle>ioctl VIDIOC_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS,
VIDIOC_TRY_EXT_CTRLS</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>VIDIOC_G_EXT_CTRLS</refname>
<refname>VIDIOC_S_EXT_CTRLS</refname>
<refname>VIDIOC_TRY_EXT_CTRLS</refname>
<refpurpose>Get or set the value of several controls, try control
values</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_ext_controls
*<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_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS,
VIDIOC_TRY_EXT_CTRLS</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>argp</parameter></term>
<listitem>
<para></para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>These ioctls allow the caller to get or set multiple
controls atomically. Control IDs are grouped into control classes (see
<xref linkend="ctrl-class" />) and all controls in the control array
must belong to the same control class.</para>
<para>Applications must always fill in the
<structfield>count</structfield>,
<structfield>ctrl_class</structfield>,
<structfield>controls</structfield> and
<structfield>reserved</structfield> fields of &v4l2-ext-controls;, and
initialize the &v4l2-ext-control; array pointed to by the
<structfield>controls</structfield> fields.</para>
<para>To get the current value of a set of controls applications
initialize the <structfield>id</structfield>,
<structfield>size</structfield> and <structfield>reserved2</structfield> fields
of each &v4l2-ext-control; and call the
<constant>VIDIOC_G_EXT_CTRLS</constant> ioctl. String controls controls
must also set the <structfield>string</structfield> field.</para>
<para>If the <structfield>size</structfield> is too small to
receive the control result (only relevant for pointer-type controls
like strings), then the driver will set <structfield>size</structfield>
to a valid value and return an &ENOSPC;. You should re-allocate the
string memory to this new size and try again. It is possible that the
same issue occurs again if the string has grown in the meantime. It is
recommended to call &VIDIOC-QUERYCTRL; first and use
<structfield>maximum</structfield>+1 as the new <structfield>size</structfield>
value. It is guaranteed that that is sufficient memory.
</para>
<para>To change the value of a set of controls applications
initialize the <structfield>id</structfield>, <structfield>size</structfield>,
<structfield>reserved2</structfield> and
<structfield>value/string</structfield> fields of each &v4l2-ext-control; and
call the <constant>VIDIOC_S_EXT_CTRLS</constant> ioctl. The controls
will only be set if <emphasis>all</emphasis> control values are
valid.</para>
<para>To check if a set of controls have correct values applications
initialize the <structfield>id</structfield>, <structfield>size</structfield>,
<structfield>reserved2</structfield> and
<structfield>value/string</structfield> fields of each &v4l2-ext-control; and
call the <constant>VIDIOC_TRY_EXT_CTRLS</constant> ioctl. It is up to
the driver whether wrong values are automatically adjusted to a valid
value or if an error is returned.</para>
<para>When the <structfield>id</structfield> or
<structfield>ctrl_class</structfield> is invalid drivers return an
&EINVAL;. When the value is out of bounds drivers can choose to take
the closest valid value or return an &ERANGE;, whatever seems more
appropriate. In the first case the new value is set in
&v4l2-ext-control;.</para>
<para>The driver will only set/get these controls if all control
values are correct. This prevents the situation where only some of the
controls were set/get. Only low-level errors (&eg; a failed i2c
command) can still cause this situation.</para>
<table pgwide="1" frame="none" id="v4l2-ext-control">
<title>struct <structname>v4l2_ext_control</structname></title>
<tgroup cols="4">
&cs-ustr;
<tbody valign="top">
<row>
<entry>__u32</entry>
<entry><structfield>id</structfield></entry>
<entry></entry>
<entry>Identifies the control, set by the
application.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>size</structfield></entry>
<entry></entry>
<entry>The total size in bytes of the payload of this
control. This is normally 0, but for pointer controls this should be
set to the size of the memory containing the payload, or that will
receive the payload. If <constant>VIDIOC_G_EXT_CTRLS</constant> finds
that this value is less than is required to store
the payload result, then it is set to a value large enough to store the
payload result and ENOSPC is returned. Note that for string controls
this <structfield>size</structfield> field should not be confused with the length of the string.
This field refers to the size of the memory that contains the string.
The actual <emphasis>length</emphasis> of the string may well be much smaller.
</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>reserved2</structfield>[1]</entry>
<entry></entry>
<entry>Reserved for future extensions. Drivers and
applications must set the array to zero.</entry>
</row>
<row>
<entry>union</entry>
<entry>(anonymous)</entry>
</row>
<row>
<entry></entry>
<entry>__s32</entry>
<entry><structfield>value</structfield></entry>
<entry>New value or current value.</entry>
</row>
<row>
<entry></entry>
<entry>__s64</entry>
<entry><structfield>value64</structfield></entry>
<entry>New value or current value.</entry>
</row>
<row>
<entry></entry>
<entry>char *</entry>
<entry><structfield>string</structfield></entry>
<entry>A pointer to a string.</entry>
</row>
</tbody>
</tgroup>
</table>
<table pgwide="1" frame="none" id="v4l2-ext-controls">
<title>struct <structname>v4l2_ext_controls</structname></title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>__u32</entry>
<entry><structfield>ctrl_class</structfield></entry>
<entry>The control class to which all controls belong, see
<xref linkend="ctrl-class" />.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>count</structfield></entry>
<entry>The number of controls in the controls array. May
also be zero.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>error_idx</structfield></entry>
<entry>Set by the driver in case of an error. It is the
index of the control causing the error or equal to 'count' when the
error is not associated with a particular control. Undefined when the
ioctl returns 0 (success).</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>reserved</structfield>[2]</entry>
<entry>Reserved for future extensions. Drivers and
applications must set the array to zero.</entry>
</row>
<row>
<entry>&v4l2-ext-control; *</entry>
<entry><structfield>controls</structfield></entry>
<entry>Pointer to an array of
<structfield>count</structfield> v4l2_ext_control structures. Ignored
if <structfield>count</structfield> equals zero.</entry>
</row>
</tbody>
</tgroup>
</table>
<table pgwide="1" frame="none" id="ctrl-class">
<title>Control classes</title>
<tgroup cols="3">
&cs-def;
<tbody valign="top">
<row>
<entry><constant>V4L2_CTRL_CLASS_USER</constant></entry>
<entry>0x980000</entry>
<entry>The class containing user controls. These controls
are described in <xref linkend="control" />. All controls that can be set
using the &VIDIOC-S-CTRL; and &VIDIOC-G-CTRL; ioctl belong to this
class.</entry>
</row>
<row>
<entry><constant>V4L2_CTRL_CLASS_MPEG</constant></entry>
<entry>0x990000</entry>
<entry>The class containing MPEG compression controls.
These controls are described in <xref
linkend="mpeg-controls" />.</entry>
</row>
<row>
<entry><constant>V4L2_CTRL_CLASS_CAMERA</constant></entry>
<entry>0x9a0000</entry>
<entry>The class containing camera controls.
These controls are described in <xref
linkend="camera-controls" />.</entry>
</row>
<row>
<entry><constant>V4L2_CTRL_CLASS_FM_TX</constant></entry>
<entry>0x9b0000</entry>
<entry>The class containing FM Transmitter (FM TX) controls.
These controls are described in <xref
linkend="fm-tx-controls" />.</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1>
&return-value;
<variablelist>
<varlistentry>
<term><errorcode>EINVAL</errorcode></term>
<listitem>
<para>The &v4l2-ext-control; <structfield>id</structfield>
is invalid or the &v4l2-ext-controls;
<structfield>ctrl_class</structfield> is invalid. This error code is
also returned by the <constant>VIDIOC_S_EXT_CTRLS</constant> and
<constant>VIDIOC_TRY_EXT_CTRLS</constant> ioctls if two or more
control values are in conflict.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>ERANGE</errorcode></term>
<listitem>
<para>The &v4l2-ext-control; <structfield>value</structfield>
is out of bounds.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EBUSY</errorcode></term>
<listitem>
<para>The control is temporarily not changeable, possibly
because another applications took over control of the device function
this control belongs to.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>ENOSPC</errorcode></term>
<listitem>
<para>The space reserved for the control's payload is insufficient.
The field <structfield>size</structfield> is set to a value that is enough
to store the payload and this error code is returned.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->

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