<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML
><HEAD
><TITLE
>Video for Linux Two API Specification</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"></HEAD
><BODY
CLASS="BOOK"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="BOOK"
><A
NAME="INDEX"
></A
><DIV
CLASS="TITLEPAGE"
><H1
CLASS="TITLE"
><A
NAME="AEN2"
>Video for Linux Two API Specification</A
></H1
><H2
CLASS="SUBTITLE"
>Draft 0.8</H2
><H3
CLASS="AUTHOR"
><A
NAME="AEN6"
></A
>Michael H Schimek</H3
><DIV
CLASS="AFFILIATION"
><DIV
CLASS="ADDRESS"
><P
CLASS="ADDRESS"
> <CODE
CLASS="EMAIL"
><<A
HREF="mailto:mschimek@gmx.at"
>mschimek@gmx.at</A
>></CODE
><br>
</P
></DIV
></DIV
><H3
CLASS="AUTHOR"
><A
NAME="AEN13"
></A
>Bill Dirks</H3
><P
CLASS="COPYRIGHT"
>Copyright © 1999, 2000, 2001, 2002, 2003, 2004 Bill Dirks, Michael H. Schimek</P
><DIV
CLASS="LEGALNOTICE"
><P
></P
><A
NAME="AEN25"
></A
><P
>This document is copyrighted © 1999-2004 by Bill
Dirks and Michael H. Schimek.</P
><P
>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 no Invariant Sections, with no Front-Cover Texts, and
with no Back-Cover Texts. A copy of the license is included in the
appendix entitled "GNU Free Documentation License".</P
><P
>Programming examples can be used without
restriction.</P
><P
></P
></DIV
><HR></DIV
><DIV
CLASS="TOC"
><DL
><DT
><B
>Table of Contents</B
></DT
><DT
><A
HREF="#AEN71"
>Introduction</A
></DT
><DT
>1. <A
HREF="#COMMON"
>Common API Elements</A
></DT
><DD
><DL
><DT
>1.1. <A
HREF="#OPEN"
>Opening and Closing Devices</A
></DT
><DD
><DL
><DT
>1.1.1. <A
HREF="#AEN100"
>Device Naming</A
></DT
><DT
>1.1.2. <A
HREF="#RELATED"
>Related Devices</A
></DT
><DT
>1.1.3. <A
HREF="#AEN153"
>Multiple Opens</A
></DT
><DT
>1.1.4. <A
HREF="#AEN170"
>Shared Data Streams</A
></DT
><DT
>1.1.5. <A
HREF="#AEN173"
>Functions</A
></DT
></DL
></DD
><DT
>1.2. <A
HREF="#QUERYCAP"
>Querying Capabilities</A
></DT
><DT
>1.3. <A
HREF="#APP-PRI"
>Application Priority</A
></DT
><DT
>1.4. <A
HREF="#VIDEO"
>Video Inputs and Outputs</A
></DT
><DT
>1.5. <A
HREF="#AUDIO"
>Audio Inputs and Outputs</A
></DT
><DT
>1.6. <A
HREF="#TUNER"
>Tuners and Modulators</A
></DT
><DD
><DL
><DT
>1.6.1. <A
HREF="#AEN296"
>Tuners</A
></DT
><DT
>1.6.2. <A
HREF="#AEN318"
>Modulators</A
></DT
><DT
>1.6.3. <A
HREF="#AEN337"
>Radio Frequency</A
></DT
><DT
>1.6.4. <A
HREF="#AEN345"
>Satellite Receivers</A
></DT
></DL
></DD
><DT
>1.7. <A
HREF="#STANDARD"
>Video Standards</A
></DT
><DT
>1.8. <A
HREF="#CONTROL"
>Controls</A
></DT
><DT
>1.9. <A
HREF="#FORMAT"
>Data Formats</A
></DT
><DD
><DL
><DT
>1.9.1. <A
HREF="#AEN656"
>Data Format Negotiation</A
></DT
><DT
>1.9.2. <A
HREF="#AEN689"
>Image Format Enumeration</A
></DT
></DL
></DD
><DT
>1.10. <A
HREF="#CROP"
>Cropping and Scaling</A
></DT
><DT
>1.11. <A
HREF="#STREAMING-PAR"
>Streaming Parameters</A
></DT
></DL
></DD
><DT
>2. <A
HREF="#PIXFMT"
>Image Formats</A
></DT
><DD
><DL
><DT
>2.1. <A
HREF="#AEN880"
>Standard Image Formats</A
></DT
><DT
>2.2. <A
HREF="#COLORSPACES"
>Colorspaces</A
></DT
><DT
>2.3. <A
HREF="#PIXFMT-RGB"
>RGB Formats</A
></DT
><DT
>2.4. <A
HREF="#YUV-FORMATS"
>YUV Formats</A
></DT
><DD
><DL
><DT
><A
HREF="#PIXFMT-GREY"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_GREY</CODE
></A
> -- Grey-scale image.</DT
><DT
><A
HREF="#PIXFMT-YUYV"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YUYV</CODE
></A
> -- Packed format with ½ horizontal chroma
resolution, also known as YUV 4:2:2.</DT
><DT
><A
HREF="#PIXFMT-UYVY"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_UYVY</CODE
></A
> -- Variation of
<CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YUYV</CODE
> with different order of samples
in memory.</DT
><DT
><A
HREF="#PIXFMT-Y41P"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_Y41P</CODE
></A
> -- Packed format with ¼ horizontal chroma
resolution, also known as YUV 4:1:1.</DT
><DT
><A
HREF="#PIXFMT-YVU420"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YVU420</CODE
>,
<CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YUV420</CODE
></A
> -- Planar formats with ½ horizontal and
vertical chroma resolution, also known as YUV 4:2:0.</DT
><DT
><A
HREF="#PIXFMT-YVU410"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YVU410</CODE
>,
<CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YUV410</CODE
></A
> -- Planar formats with ¼ horizontal and
vertical chroma resolution, also known as YUV 4:1:0.</DT
><DT
><A
HREF="#PIXFMT-YUV422P"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YUV422P</CODE
></A
> -- Format with ½ horizontal chroma resolution,
also known as YUV 4:2:2. Planar layout as opposed to
<CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YUYV</CODE
>.</DT
><DT
><A
HREF="#PIXFMT-YUV411P"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YUV411P</CODE
></A
> -- Format with ¼ horizontal chroma resolution,
also known as YUV 4:1:1. Planar layout as opposed to
<CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_Y41P</CODE
>.</DT
><DT
><A
HREF="#AEN3002"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_NV12</CODE
>,
<CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_NV21</CODE
></A
> -- Formats with ½ 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
<CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YVU420</CODE
>.</DT
></DL
></DD
><DT
>2.5. <A
HREF="#AEN3167"
>Compressed Formats</A
></DT
><DT
>2.6. <A
HREF="#PIXFMT-RESERVED"
>Reserved Format Identifiers</A
></DT
></DL
></DD
><DT
>3. <A
HREF="#IO"
>Input/Output</A
></DT
><DD
><DL
><DT
>3.1. <A
HREF="#RW"
>Read/Write</A
></DT
><DT
>3.2. <A
HREF="#MMAP"
>Streaming I/O (Memory Mapping)</A
></DT
><DT
>3.3. <A
HREF="#USERP"
>Streaming I/O (User Pointers)</A
></DT
><DT
>3.4. <A
HREF="#ASYNC"
>Asynchronous I/O</A
></DT
><DT
>3.5. <A
HREF="#BUFFER"
>Buffers</A
></DT
><DD
><DL
><DT
>3.5.1. <A
HREF="#AEN3738"
>Timecodes</A
></DT
></DL
></DD
><DT
>3.6. <A
HREF="#FIELD-ORDER"
>Field Order</A
></DT
></DL
></DD
><DT
>4. <A
HREF="#DEVICES"
>Device Types</A
></DT
><DD
><DL
><DT
>4.1. <A
HREF="#CAPTURE"
>Video Capture Interface</A
></DT
><DD
><DL
><DT
>4.1.1. <A
HREF="#AEN3960"
>Querying Capabilities</A
></DT
><DT
>4.1.2. <A
HREF="#AEN3972"
>Supplemental Functions</A
></DT
><DT
>4.1.3. <A
HREF="#AEN3982"
>Image Format Negotiation</A
></DT
><DT
>4.1.4. <A
HREF="#AEN4024"
>Reading Images</A
></DT
></DL
></DD
><DT
>4.2. <A
HREF="#OVERLAY"
>Video Overlay Interface</A
></DT
><DD
><DL
><DT
>4.2.1. <A
HREF="#AEN4048"
>Querying Capabilities</A
></DT
><DT
>4.2.2. <A
HREF="#AEN4056"
>Supplemental Functions</A
></DT
><DT
>4.2.3. <A
HREF="#AEN4066"
>Setup</A
></DT
><DT
>4.2.4. <A
HREF="#AEN4092"
>Overlay Window</A
></DT
><DT
>4.2.5. <A
HREF="#AEN4266"
>Enabling Overlay</A
></DT
></DL
></DD
><DT
>4.3. <A
HREF="#OUTPUT"
>Video Output Interface</A
></DT
><DD
><DL
><DT
>4.3.1. <A
HREF="#AEN4279"
>Querying Capabilities</A
></DT
><DT
>4.3.2. <A
HREF="#AEN4289"
>Supplemental Functions</A
></DT
><DT
>4.3.3. <A
HREF="#AEN4299"
>Image Format Negotiation</A
></DT
><DT
>4.3.4. <A
HREF="#AEN4341"
>Writing Images</A
></DT
></DL
></DD
><DT
>4.4. <A
HREF="#CODEC"
>Codec Interface</A
></DT
><DT
>4.5. <A
HREF="#EFFECT"
>Effect Devices Interface</A
></DT
><DT
>4.6. <A
HREF="#RAW-VBI"
>Raw VBI Data Interface</A
></DT
><DD
><DL
><DT
>4.6.1. <A
HREF="#AEN4383"
>Querying Capabilities</A
></DT
><DT
>4.6.2. <A
HREF="#AEN4392"
>Supplemental Functions</A
></DT
><DT
>4.6.3. <A
HREF="#AEN4399"
>Raw VBI Format Negotiation</A
></DT
><DT
>4.6.4. <A
HREF="#AEN4571"
>Reading and writing VBI images</A
></DT
></DL
></DD
><DT
>4.7. <A
HREF="#SLICED"
>Sliced VBI Data Interface</A
></DT
><DD
><DL
><DT
>4.7.1. <A
HREF="#AEN4599"
>Querying Capabilities</A
></DT
><DT
>4.7.2. <A
HREF="#AEN4608"
>Supplemental Functions</A
></DT
><DT
>4.7.3. <A
HREF="#AEN4615"
>Sliced VBI Format Negotiation</A
></DT
><DT
>4.7.4. <A
HREF="#AEN4760"
>Reading and writing sliced VBI data</A
></DT
></DL
></DD
><DT
>4.8. <A
HREF="#TTX"
>Teletext Interface</A
></DT
><DT
>4.9. <A
HREF="#RADIO"
>Radio Interface</A
></DT
><DD
><DL
><DT
>4.9.1. <A
HREF="#AEN4799"
>Querying Capabilities</A
></DT
><DT
>4.9.2. <A
HREF="#AEN4808"
>Supplemental Functions</A
></DT
><DT
>4.9.3. <A
HREF="#AEN4814"
>Programming</A
></DT
></DL
></DD
><DT
>4.10. <A
HREF="#RDS"
>RDS Interface</A
></DT
></DL
></DD
><DT
>I. <A
HREF="#USER-FUNC"
>Function Reference</A
></DT
><DD
><DL
><DT
><A
HREF="#FUNC-CLOSE"
>close</A
> -- Close a V4L2 device</DT
><DT
><A
HREF="#FUNC-IOCTL"
>ioctl</A
> -- Program a V4L2 device</DT
><DT
><A
HREF="#VIDIOC-CROPCAP"
>ioctl VIDIOC_CROPCAP</A
> -- Information about the video cropping and scaling abilities.</DT
><DT
><A
HREF="#VIDIOC-ENUMAUDIO"
>ioctl VIDIOC_ENUMAUDIO</A
> -- Enumerate audio inputs</DT
><DT
><A
HREF="#VIDIOC-ENUMAUDIOOUT"
>ioctl VIDIOC_ENUMAUDOUT</A
> -- Enumerate audio outputs</DT
><DT
><A
HREF="#VIDIOC-ENUM-FMT"
>ioctl VIDIOC_ENUM_FMT</A
> -- Enumerate image formats</DT
><DT
><A
HREF="#VIDIOC-ENUMINPUT"
>ioctl VIDIOC_ENUMINPUT</A
> -- Enumerate video inputs</DT
><DT
><A
HREF="#VIDIOC-ENUMOUTPUT"
>ioctl VIDIOC_ENUMOUTPUT</A
> -- Enumerate video outputs</DT
><DT
><A
HREF="#VIDIOC-ENUMSTD"
>ioctl VIDIOC_ENUMSTD</A
> -- Enumerate supported video standards</DT
><DT
><A
HREF="#VIDIOC-G-AUDIO"
>ioctl VIDIOC_G_AUDIO, VIDIOC_S_AUDIO</A
> -- Query or select the current audio input and its
attributes</DT
><DT
><A
HREF="#VIDIOC-G-AUDIOOUT"
>ioctl VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT</A
> -- Query or select the current audio output</DT
><DT
><A
HREF="#VIDIOC-G-COMP"
>ioctl VIDIOC_G_COMP, VIDIOC_S_COMP</A
> -- Get or set compression parameters</DT
><DT
><A
HREF="#VIDIOC-G-CROP"
>ioctl VIDIOC_G_CROP, VIDIOC_S_CROP</A
> -- Get or set the current cropping rectangle</DT
><DT
><A
HREF="#VIDIOC-G-CTRL"
>ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL</A
> -- Get or set the value of a control</DT
><DT
><A
HREF="#VIDIOC-G-FBUF"
>ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF</A
> -- Get or set frame buffer overlay parameters.</DT
><DT
><A
HREF="#VIDIOC-G-FMT"
>ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT</A
> -- Get or set the data format, try a format.</DT
><DT
><A
HREF="#VIDIOC-G-FREQUENCY"
>ioctl VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY</A
> -- Get or set tuner or modulator radio
frequency</DT
><DT
><A
HREF="#VIDIOC-G-INPUT"
>ioctl VIDIOC_G_INPUT, VIDIOC_S_INPUT</A
> -- Query or select the current video input</DT
><DT
><A
HREF="#VIDIOC-G-JPEGCOMP"
>ioctl VIDIOC_G_JPEGCOMP, VIDIOC_S_JPEGCOMP</A
> -- </DT
><DT
><A
HREF="#VIDIOC-G-MODULATOR"
>ioctl VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR</A
> -- Get or set modulator attributes</DT
><DT
><A
HREF="#VIDIOC-G-OUTPUT"
>ioctl VIDIOC_G_OUTPUT, VIDIOC_S_OUTPUT</A
> -- Query or select the current video output</DT
><DT
><A
HREF="#VIDIOC-G-PARM"
>ioctl VIDIOC_G_PARM, VIDIOC_S_PARM</A
> -- Get or set streaming parameters</DT
><DT
><A
HREF="#VIDIOC-G-PRIORITY"
>ioctl VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY</A
> -- Query or request the access priority associated with a
file descriptor</DT
><DT
><A
HREF="#VIDIOC-G-STD"
>ioctl VIDIOC_G_STD, VIDIOC_S_STD</A
> -- Query or select the video standard of the current input</DT
><DT
><A
HREF="#VIDIOC-G-TUNER"
>ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER</A
> -- Get or set tuner attributes</DT
><DT
><A
HREF="#VIDIOC-OVERLAY"
>ioctl VIDIOC_OVERLAY</A
> -- Start or stop video overlay</DT
><DT
><A
HREF="#VIDIOC-QBUF"
>ioctl VIDIOC_QBUF, VIDIOC_DQBUF</A
> -- Exchange a buffer with the driver</DT
><DT
><A
HREF="#VIDIOC-QUERYBUF"
>ioctl VIDIOC_QUERYBUF</A
> -- Query the status of a buffer</DT
><DT
><A
HREF="#VIDIOC-QUERYCAP"
>ioctl VIDIOC_QUERYCAP</A
> -- Query device capabilities</DT
><DT
><A
HREF="#VIDIOC-QUERYCTRL"
>ioctl VIDIOC_QUERYCTRL, VIDIOC_QUERYMENU</A
> -- Enumerate controls and menu control items</DT
><DT
><A
HREF="#VIDIOC-QUERYSTD"
>ioctl VIDIOC_QUERYSTD</A
> -- Sense the video standard received by the current input</DT
><DT
><A
HREF="#VIDIOC-REQBUFS"
>ioctl VIDIOC_REQBUFS</A
> -- Initiate Memory Mapping or User Pointer I/O</DT
><DT
><A
HREF="#VIDIOC-STREAMON"
>ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF</A
> -- Start or stop streaming I/O.</DT
><DT
><A
HREF="#FUNC-MMAP"
>mmap</A
> -- Map device memory into application address space</DT
><DT
><A
HREF="#FUNC-MUNMAP"
>munmap</A
> -- Unmap device memory</DT
><DT
><A
HREF="#FUNC-OPEN"
>open</A
> -- Open a V4L2 device</DT
><DT
><A
HREF="#FUNC-POLL"
>poll</A
> -- Wait for some event on a file descriptor</DT
><DT
><A
HREF="#FUNC-READ"
>read</A
> -- Read from a V4L2 device</DT
><DT
><A
HREF="#FUNC-SELECT"
>select</A
> -- Synchronous I/O multiplexing</DT
><DT
><A
HREF="#FUNC-WRITE"
>write</A
> -- Write to a V4L2 device</DT
></DL
></DD
><DT
>5. <A
HREF="#DRIVER"
>Driver Interface</A
></DT
><DD
><DL
><DT
>5.1. <A
HREF="#FOO"
>to do</A
></DT
><DD
><DL
><DT
>5.1.1. <A
HREF="#AEN9774"
>to do</A
></DT
></DL
></DD
></DL
></DD
><DT
>6. <A
HREF="#COMPAT"
>History</A
></DT
><DD
><DL
><DT
>6.1. <A
HREF="#DIFF-V4L"
>Differences between V4L and V4L2</A
></DT
><DD
><DL
><DT
>6.1.1. <A
HREF="#AEN9783"
>Opening and Closing Devices</A
></DT
><DT
>6.1.2. <A
HREF="#AEN9847"
>Querying Capabilities</A
></DT
><DT
>6.1.3. <A
HREF="#AEN9977"
>Video Sources</A
></DT
><DT
>6.1.4. <A
HREF="#AEN10033"
>Tuning</A
></DT
><DT
>6.1.5. <A
HREF="#V4L-IMAGE-PROPERTIES"
>Image Properties</A
></DT
><DT
>6.1.6. <A
HREF="#AEN10276"
>Audio</A
></DT
><DT
>6.1.7. <A
HREF="#AEN10361"
>Frame Buffer Overlay</A
></DT
><DT
>6.1.8. <A
HREF="#AEN10425"
>Cropping</A
></DT
><DT
>6.1.9. <A
HREF="#AEN10458"
>Reading Images, Memory Mapping</A
></DT
><DT
>6.1.10. <A
HREF="#AEN10541"
>Reading Raw VBI Data</A
></DT
><DT
>6.1.11. <A
HREF="#AEN10594"
>Miscellaneous</A
></DT
></DL
></DD
><DT
>6.2. <A
HREF="#HIST-V4L2"
>History of the V4L2 API</A
></DT
><DD
><DL
><DT
>6.2.1. <A
HREF="#AEN10604"
>Early Versions</A
></DT
><DT
>6.2.2. <A
HREF="#AEN10618"
>V4L2 Version 0.16 1999-01-31</A
></DT
><DT
>6.2.3. <A
HREF="#AEN10621"
>V4L2 Version 0.18 1999-03-16</A
></DT
><DT
>6.2.4. <A
HREF="#AEN10624"
>V4L2 Version 0.19 1999-06-05</A
></DT
><DT
>6.2.5. <A
HREF="#AEN10633"
>V4L2 Version 0.20 1999-09-10</A
></DT
><DT
>6.2.6. <A
HREF="#AEN10672"
>V4L2 Version 0.20 incremental changes</A
></DT
><DT
>6.2.7. <A
HREF="#AEN10694"
>V4L2 Version 0.20 2000-11-23</A
></DT
><DT
>6.2.8. <A
HREF="#AEN10709"
>V4L2 Version 0.20 2002-07-25</A
></DT
><DT
>6.2.9. <A
HREF="#AEN10712"
>V4L2 in Linux 2.5.46, 2002-10</A
></DT
><DT
>6.2.10. <A
HREF="#AEN11094"
>V4L2 2003-06-19</A
></DT
><DT
>6.2.11. <A
HREF="#AEN11136"
>V4L2 2003-11-05</A
></DT
><DT
>6.2.12. <A
HREF="#AEN11178"
>V4L2 in Linux 2.6.6, 2004-05-09</A
></DT
><DT
>6.2.13. <A
HREF="#AEN11186"
>V4L2 in Linux 2.6.8</A
></DT
><DT
>6.2.14. <A
HREF="#AEN11196"
>V4L2 spec erratum 2004-08-01</A
></DT
></DL
></DD
><DT
>6.3. <A
HREF="#OTHER"
>Relation of V4L2 to other Linux multimedia APIs</A
></DT
><DD
><DL
><DT
>6.3.1. <A
HREF="#XVIDEO"
>X Video Extension</A
></DT
><DT
>6.3.2. <A
HREF="#AEN11233"
>Digital Video</A
></DT
><DT
>6.3.3. <A
HREF="#AEN11237"
>Audio Interfaces</A
></DT
></DL
></DD
></DL
></DD
><DT
>A. <A
HREF="#VIDEODEV"
>Video For Linux Two Header File</A
></DT
><DT
>B. <A
HREF="#CAPTURE-EXAMPLE"
>Video Capture Example</A
></DT
><DT
>C. <A
HREF="#FDL"
>GNU Free Documentation License</A
></DT
><DD
><DL
><DT
>C.1. <A
HREF="#FDL-PREAMBLE"
>0. PREAMBLE</A
></DT
><DT
>C.2. <A
HREF="#FDL-SECTION1"
>1. APPLICABILITY AND DEFINITIONS</A
></DT
><DT
>C.3. <A
HREF="#FDL-SECTION2"
>2. VERBATIM COPYING</A
></DT
><DT
>C.4. <A
HREF="#FDL-SECTION3"
>3. COPYING IN QUANTITY</A
></DT
><DT
>C.5. <A
HREF="#FDL-SECTION4"
>4. MODIFICATIONS</A
></DT
><DT
>C.6. <A
HREF="#FDL-SECTION5"
>5. COMBINING DOCUMENTS</A
></DT
><DT
>C.7. <A
HREF="#FDL-SECTION6"
>6. COLLECTIONS OF DOCUMENTS</A
></DT
><DT
>C.8. <A
HREF="#FDL-SECTION7"
>7. AGGREGATION WITH INDEPENDENT WORKS</A
></DT
><DT
>C.9. <A
HREF="#FDL-SECTION8"
>8. TRANSLATION</A
></DT
><DT
>C.10. <A
HREF="#FDL-SECTION9"
>9. TERMINATION</A
></DT
><DT
>C.11. <A
HREF="#FDL-SECTION10"
>10. FUTURE REVISIONS OF THIS LICENSE</A
></DT
><DT
>C.12. <A
HREF="#FDL-USING"
>Addendum</A
></DT
></DL
></DD
><DT
><A
HREF="#AEN11623"
>Bibliography</A
></DT
></DL
></DIV
><DIV
CLASS="LOT"
><DL
CLASS="LOT"
><DT
><B
>List of Tables</B
></DT
><DT
>1-1. <A
HREF="#CONTROL-ID"
>Control IDs</A
></DT
><DT
>2-1. <A
HREF="#V4L2-PIX-FORMAT"
>struct <CODE
CLASS="STRUCTNAME"
>v4l2_pix_format</CODE
></A
></DT
><DT
>2-2. <A
HREF="#V4L2-COLORSPACE"
>enum v4l2_colorspace</A
></DT
><DT
>2-3. <A
HREF="#RGB-FORMATS"
>Packed RGB Image Formats</A
></DT
><DT
>2-4. <A
HREF="#RESERVED-FORMATS"
>Reserved Image Formats</A
></DT
><DT
>3-1. <A
HREF="#V4L2-BUFFER"
>struct <CODE
CLASS="STRUCTNAME"
>v4l2_buffer</CODE
></A
></DT
><DT
>3-2. <A
HREF="#V4L2-BUF-TYPE"
>enum v4l2_buf_type</A
></DT
><DT
>3-3. <A
HREF="#BUFFER-FLAGS"
>Buffer Flags</A
></DT
><DT
>3-4. <A
HREF="#V4L2-MEMORY"
>enum v4l2_memory</A
></DT
><DT
>3-5. <A
HREF="#V4L2-TIMECODE"
>struct <CODE
CLASS="STRUCTNAME"
>v4l2_timecode</CODE
></A
></DT
><DT
>3-6. <A
HREF="#TIMECODE-TYPE"
>Timecode Types</A
></DT
><DT
>3-7. <A
HREF="#TIMECODE-FLAGS"
>Timecode Flags</A
></DT
><DT
>3-8. <A
HREF="#V4L2-FIELD"
>enum v4l2_field</A
></DT
><DT
>4-1. <A
HREF="#V4L2-WINDOW"
>struct <CODE
CLASS="STRUCTNAME"
>v4l2_window</CODE
></A
></DT
><DT
>4-2. <A
HREF="#V4L2-CLIP"
>struct <CODE
CLASS="STRUCTNAME"
>v4l2_clip</CODE
><A
NAME="AEN4216"
HREF="#FTN.AEN4216"
><SPAN
CLASS="footnote"
>[22]</SPAN
></A
></A
></DT
><DT
>4-3. <A
HREF="#V4L2-RECT"
>struct <CODE
CLASS="STRUCTNAME"
>v4l2_rect</CODE
></A
></DT
><DT
>4-4. <A
HREF="#V4L2-VBI-FORMAT"
>struct <CODE
CLASS="STRUCTNAME"
>v4l2_vbi_format</CODE
></A
></DT
><DT
>4-5. <A
HREF="#VBIFMT-FLAGS"
>Raw VBI Format Flags</A
></DT
><DT
>4-6. <A
HREF="#V4L2-SLICED-VBI-FORMAT"
>struct <CODE
CLASS="STRUCTNAME"
>v4l2_sliced_vbi_format</CODE
></A
></DT
><DT
>4-7. <A
HREF="#V4L2-SLICED-DATA"
>struct <CODE
CLASS="STRUCTNAME"
>v4l2_sliced_data</CODE
></A
></DT
><DT
>4-8. <A
HREF="#SLICED-VBI-TYPES"
>Sliced VBI data formats</A
></DT
><DT
>1. <A
HREF="#V4L2-CROPCAP"
>struct <CODE
CLASS="STRUCTNAME"
>v4l2_cropcap</CODE
></A
></DT
><DT
>2. <A
HREF="#V4L2-RECT-CROP"
>struct <CODE
CLASS="STRUCTNAME"
>v4l2_rect</CODE
></A
></DT
><DT
>1. <A
HREF="#V4L2-FMTDESC"
>struct <CODE
CLASS="STRUCTNAME"
>v4l2_fmtdesc</CODE
></A
></DT
><DT
>2. <A
HREF="#FMTDESC-FLAGS"
>Image Format Description Flags</A
></DT
><DT
>1. <A
HREF="#V4L2-INPUT"
>struct <CODE
CLASS="STRUCTNAME"
>v4l2_input</CODE
></A
></DT
><DT
>2. <A
HREF="#INPUT-TYPE"
>Input Types</A
></DT
><DT
>3. <A
HREF="#INPUT-STATUS"
>Input Status Flags</A
></DT
><DT
>1. <A
HREF="#V4L2-OUTPUT"
>struct <CODE
CLASS="STRUCTNAME"
>v4l2_output</CODE
></A
></DT
><DT
>2. <A
HREF="#OUTPUT-TYPE"
>Output Type</A
></DT
><DT
>1. <A
HREF="#V4L2-STANDARD"
>struct <CODE
CLASS="STRUCTNAME"
>v4l2_standard</CODE
></A
></DT
><DT
>2. <A
HREF="#V4L2-FRACT"
>struct <CODE
CLASS="STRUCTNAME"
>v4l2_fract</CODE
></A
></DT
><DT
>3. <A
HREF="#V4L2-STD-ID"
>typedef <CODE
CLASS="STRUCTNAME"
>v4l2_std_id</CODE
></A
></DT
><DT
>4. <A
HREF="#VIDEO-STANDARDS"
>Video Standards (based on [<A
HREF="#ITU470"
><ABBR
CLASS="ABBREV"
>ITU470</ABBR
></A
>])</A
></DT
><DT
>1. <A
HREF="#V4L2-AUDIO"
>struct <CODE
CLASS="STRUCTNAME"
>v4l2_audio</CODE
></A
></DT
><DT
>2. <A
HREF="#AUDIO-CAPABILITY"
>Audio Capability Flags</A
></DT
><DT
>3. <A
HREF="#AUDIO-MODE"
>Audio Modes</A
></DT
><DT
>1. <A
HREF="#V4L2-AUDIOOUT"
>struct <CODE
CLASS="STRUCTNAME"
>v4l2_audioout</CODE
></A
></DT
><DT
>1. <A
HREF="#V4L2-COMPRESSION"
>struct <CODE
CLASS="STRUCTNAME"
>v4l2_compression</CODE
></A
></DT
><DT
>1. <A
HREF="#V4L2-CROP"
>struct <CODE
CLASS="STRUCTNAME"
>v4l2_crop</CODE
></A
></DT
><DT
>1. <A
HREF="#V4L2-CONTROL"
>struct <CODE
CLASS="STRUCTNAME"
>v4l2_control</CODE
></A
></DT
><DT
>1. <A
HREF="#V4L2-FRAMEBUFFER"
>struct <CODE
CLASS="STRUCTNAME"
>v4l2_framebuffer</CODE
></A
></DT
><DT
>2. <A
HREF="#FRAMEBUFFER-CAP"
>Frame Buffer Capability Flags</A
></DT
><DT
>3. <A
HREF="#FRAMEBUFFER-FLAGS"
>Frame Buffer Flags</A
></DT
><DT
>1. <A
HREF="#V4L2-FORMAT"
>struct <CODE
CLASS="STRUCTNAME"
>v4l2_format</CODE
></A
></DT
><DT
>1. <A
HREF="#V4L2-FREQUENCY"
>struct <CODE
CLASS="STRUCTNAME"
>v4l2_frequency</CODE
></A
></DT
><DT
>1. <A
HREF="#V4L2-JPEGCOMPRESSION"
>struct <CODE
CLASS="STRUCTNAME"
>v4l2_jpegcompression</CODE
></A
></DT
><DT
>2. <A
HREF="#JPEG-MARKERS"
>JPEG Markers Flags</A
></DT
><DT
>1. <A
HREF="#V4L2-MODULATOR"
>struct <CODE
CLASS="STRUCTNAME"
>v4l2_modulator</CODE
></A
></DT
><DT
>2. <A
HREF="#MODULATOR-TXSUBCHANS"
>Modulator Audio Transmission Flags</A
></DT
><DT
>1. <A
HREF="#V4L2-STREAMPARM"
>struct <CODE
CLASS="STRUCTNAME"
>v4l2_streamparm</CODE
></A
></DT
><DT
>2. <A
HREF="#V4L2-CAPTUREPARM"
>struct <CODE
CLASS="STRUCTNAME"
>v4l2_captureparm</CODE
></A
></DT
><DT
>3. <A
HREF="#V4L2-OUTPUTPARM"
>struct <CODE
CLASS="STRUCTNAME"
>v4l2_outputparm</CODE
></A
></DT
><DT
>4. <A
HREF="#PARM-CAPS"
>Streaming Parameters Capabilites</A
></DT
><DT
>5. <A
HREF="#PARM-FLAGS"
>Capture Parameters Flags</A
></DT
><DT
>1. <A
HREF="#V4L2-PRIORITY"
>enum v4l2_priority</A
></DT
><DT
>1. <A
HREF="#V4L2-TUNER"
>struct <CODE
CLASS="STRUCTNAME"
>v4l2_tuner</CODE
></A
></DT
><DT
>2. <A
HREF="#V4L2-TUNER-TYPE"
>enum v4l2_tuner_type</A
></DT
><DT
>3. <A
HREF="#TUNER-CAPABILITY"
>Tuner and Modulator Capability Flags</A
></DT
><DT
>4. <A
HREF="#TUNER-RXSUBCHANS"
>Tuner Audio Reception Flags</A
></DT
><DT
>5. <A
HREF="#TUNER-AUDMODE"
>Tuner Audio Modes</A
></DT
><DT
>6. <A
HREF="#TUNER-MATRIX"
>Tuner Audio Matrix</A
></DT
><DT
>1. <A
HREF="#V4L2-CAPABILITY"
>struct <CODE
CLASS="STRUCTNAME"
>v4l2_capability</CODE
></A
></DT
><DT
>2. <A
HREF="#DEVICE-CAPABILITIES"
>Device Capabilities Flags</A
></DT
><DT
>1. <A
HREF="#V4L2-QUERYCTRL"
>struct <CODE
CLASS="STRUCTNAME"
>v4l2_queryctrl</CODE
></A
></DT
><DT
>2. <A
HREF="#V4L2-QUERYMENU"
>struct <CODE
CLASS="STRUCTNAME"
>v4l2_querymenu</CODE
></A
></DT
><DT
>3. <A
HREF="#V4L2-CTRL-TYPE"
>enum v4l2_ctrl_type</A
></DT
><DT
>4. <A
HREF="#CONTROL-FLAGS"
>Control Flags</A
></DT
><DT
>1. <A
HREF="#V4L2-REQUESTBUFFERS"
>struct <CODE
CLASS="STRUCTNAME"
>v4l2_requestbuffers</CODE
></A
></DT
><DT
>6-1. <A
HREF="#V4L-DEV"
>V4L Device Types, Names and Numbers</A
></DT
></DL
></DIV
><DIV
CLASS="LOT"
><DL
CLASS="LOT"
><DT
><B
>List of Figures</B
></DT
><DT
>1-1. <A
HREF="#CROP-SCALE"
>Cropping and Scaling</A
></DT
><DT
>3-1. <A
HREF="#FIELDSEQ-TB"
>Field Order, Top Field First Transmitted</A
></DT
><DT
>3-2. <A
HREF="#FIELDSEQ-BT"
>Field Order, Bottom Field First Transmitted</A
></DT
><DT
>4-1. <A
HREF="#VBI-HSYNC"
>Line synchronization</A
></DT
><DT
>4-2. <A
HREF="#VBI-525"
>ITU-R 525 line numbering (M/NTSC and M/PAL)</A
></DT
><DT
>4-3. <A
HREF="#VBI-625"
>ITU-R 625 line numbering</A
></DT
></DL
></DIV
><DIV
CLASS="LOT"
><DL
CLASS="LOT"
><DT
><B
>List of Examples</B
></DT
><DT
>1-1. <A
HREF="#AEN228"
>Information about the current video input</A
></DT
><DT
>1-2. <A
HREF="#AEN236"
>Switching to the first video input</A
></DT
><DT
>1-3. <A
HREF="#AEN282"
>Information about the current audio input</A
></DT
><DT
>1-4. <A
HREF="#AEN288"
>Switching to the first audio input</A
></DT
><DT
>1-5. <A
HREF="#AEN410"
>Information about the current video standard</A
></DT
><DT
>1-6. <A
HREF="#AEN419"
>Listing the video standards supported by the current
input</A
></DT
><DT
>1-7. <A
HREF="#AEN430"
>Selecting a new video standard</A
></DT
><DT
>1-8. <A
HREF="#AEN630"
>Enumerating all controls</A
></DT
><DT
>1-9. <A
HREF="#AEN641"
>Changing controls</A
></DT
><DT
>1-10. <A
HREF="#AEN747"
>Resetting the cropping parameters</A
></DT
><DT
>1-11. <A
HREF="#AEN757"
>Simple downscaling</A
></DT
><DT
>1-12. <A
HREF="#AEN765"
>Current scaling factor and pixel aspect</A
></DT
><DT
>2-1. <A
HREF="#AEN984"
>ITU-R Rec. BT.601 color conversion</A
></DT
><DT
>2-2. <A
HREF="#AEN1675"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_BGR24</CODE
> 4 × 4 pixel
image</A
></DT
><DT
>2-1. <A
HREF="#AEN1819"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_GREY</CODE
> 4 × 4
pixel image</A
></DT
><DT
>2-1. <A
HREF="#AEN1881"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YUYV</CODE
> 4 × 4
pixel image</A
></DT
><DT
>2-1. <A
HREF="#AEN2026"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_UYVY</CODE
> 4 × 4
pixel image</A
></DT
><DT
>2-1. <A
HREF="#AEN2175"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_Y41P</CODE
> 8 × 4
pixel image</A
></DT
><DT
>2-1. <A
HREF="#AEN2402"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YVU420</CODE
> 4 × 4
pixel image</A
></DT
><DT
>2-1. <A
HREF="#AEN2564"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YVU410</CODE
> 4 × 4
pixel image</A
></DT
><DT
>2-1. <A
HREF="#AEN2702"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YUV422P</CODE
> 4 × 4
pixel image</A
></DT
><DT
>2-1. <A
HREF="#AEN2869"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YUV411P</CODE
> 4 × 4
pixel image</A
></DT
><DT
>2-1. <A
HREF="#AEN3026"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_NV12</CODE
> 4 × 4
pixel image</A
></DT
><DT
>3-1. <A
HREF="#AEN3316"
>Mapping buffers</A
></DT
><DT
>3-2. <A
HREF="#AEN3392"
>Initiating streaming I/O with user pointers</A
></DT
></DL
></DIV
><DIV
CLASS="PREFACE"
><HR><H1
><A
NAME="AEN71"
></A
>Introduction</H1
><P
>[to do]</P
><P
>If you have questions or ideas regarding the API, please try
the Video4Linux mailing list: <A
HREF="https://listman.redhat.com/mailman/listinfo/video4linux-list"
TARGET="_top"
>https://listman.redhat.com/mailman/listinfo/video4linux-list</A
></P
><P
>For documentation related requests contact the maintainer at
<A
HREF="mailto:mschimek@gmx.at"
TARGET="_top"
>mschimek@gmx.at</A
>.</P
><P
>The latest version of this document and the DocBook SGML
sources is currently hosted at <A
HREF="http://bytesex.org"
TARGET="_top"
>http://bytesex.org</A
>, site of the V4L
and V4L2 source code maintainer Gerd Knorr.</P
></DIV
><DIV
CLASS="CHAPTER"
><HR><H1
><A
NAME="COMMON"
></A
>Chapter 1. Common API Elements</H1
><P
>Programming a V4L2 device consists of these
steps:</P
><P
></P
><UL
><LI
><P
>Opening the device</P
></LI
><LI
><P
>Changing device properties, selecting a video and audio
input, video standard, picture brightness a. o.</P
></LI
><LI
><P
>Negotiating a data format</P
></LI
><LI
><P
>Negotiating an input/output method</P
></LI
><LI
><P
>The actual input/output loop</P
></LI
><LI
><P
>Closing the device</P
></LI
></UL
><P
>In practice most steps are optional and can be executed out of
order. It depends on the V4L2 device type, you can read about the
details in <A
HREF="#DEVICES"
>Chapter 4</A
>. In this chapter we will discuss
the basic concepts applicable to all devices.</P
><DIV
CLASS="SECTION"
><HR><H2
CLASS="SECTION"
><A
NAME="OPEN"
>1.1. Opening and Closing Devices</A
></H2
><DIV
CLASS="SECTION"
><H3
CLASS="SECTION"
><A
NAME="AEN100"
>1.1.1. Device Naming</A
></H3
><P
>V4L2 drivers are implemented as kernel modules, loaded
manually by the system administrator or automatically when a device is
first opened. The driver modules plug into the "videodev" kernel
module. It provides helper functions and a common application
interface as specified in this document.</P
><P
>Each driver thus loaded registers one or more device nodes
with major number 81 and a minor number between 0 and 255. Assigning
minor numbers to V4L2 devices is entirely up to the system administrator,
this is primarily intended to solve conflicts between devices.<A
NAME="AEN104"
HREF="#FTN.AEN104"
><SPAN
CLASS="footnote"
>[1]</SPAN
></A
> The module options to select minor numbers are named
after the device special file with a "_nr" suffix. For example "video_nr"
for <TT
CLASS="FILENAME"
>/dev/video</TT
> video capture devices. The number is
an offset to the base minor number associated with the device type.
<A
NAME="AEN107"
HREF="#FTN.AEN107"
><SPAN
CLASS="footnote"
>[2]</SPAN
></A
> When the driver supports multiple devices of the same
type more than one minor number can be assigned, separated by commas:
<DIV
CLASS="INFORMALEXAMPLE"
><P
></P
><A
NAME="AEN109"
></A
><PRE
CLASS="SCREEN"
>> insmod mydriver.o video_nr=0,1 radio_nr=0,1</PRE
><P
></P
></DIV
></P
><P
>In <TT
CLASS="FILENAME"
>/etc/modules.conf</TT
> this may be
written as: <DIV
CLASS="INFORMALEXAMPLE"
><P
></P
><A
NAME="AEN113"
></A
><PRE
CLASS="SCREEN"
>alias char-major-81-0 mydriver
alias char-major-81-1 mydriver
alias char-major-81-64 mydriver <A
NAME="ALIAS"
><IMG
SRC="/usr/share/sgml/docbook/stylesheet/dsssl/modular/images/callouts1.gif"
HSPACE="0"
VSPACE="0"
BORDER="0"
ALT="(1)"></A
>
options mydriver video_nr=0,1 radio_nr=0,1 <A
NAME="OPTIONS"
><IMG
SRC="/usr/share/sgml/docbook/stylesheet/dsssl/modular/images/callouts2.gif"
HSPACE="0"
VSPACE="0"
BORDER="0"
ALT="(2)"></A
>
</PRE
><DIV
CLASS="CALLOUTLIST"
><DL
COMPACT="COMPACT"
><DT
><A
HREF="#ALIAS"
><IMG
SRC="/usr/share/sgml/docbook/stylesheet/dsssl/modular/images/callouts1.gif"
HSPACE="0"
VSPACE="0"
BORDER="0"
ALT="(1)"></A
></DT
><DD
>When an application attempts to open a device
special file with major number 81 and minor number 0, 1, or 64, load
"mydriver" (and the "videodev" module it depends upon).</DD
><DT
><A
HREF="#OPTIONS"
><IMG
SRC="/usr/share/sgml/docbook/stylesheet/dsssl/modular/images/callouts2.gif"
HSPACE="0"
VSPACE="0"
BORDER="0"
ALT="(2)"></A
></DT
><DD
>Register the first two video capture devices with
minor number 0 and 1 (base number is 0), the first two radio device
with minor number 64 and 65 (base 64).</DD
></DL
></DIV
><P
></P
></DIV
> When no minor number is given as module
option the driver supplies a default. <A
HREF="#DEVICES"
>Chapter 4</A
>
recommends the base minor numbers to be used for the various device
types. Obviously minor numbers must be unique. When the number is
already in use the <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>offending device</I
></SPAN
> will not be
registered. </P
><P
>By convention system administrators create various
character device special files with these major and minor numbers in
the <TT
CLASS="FILENAME"
>/dev</TT
> directory. The names recomended for the
different V4L2 device types are listed in <A
HREF="#DEVICES"
>Chapter 4</A
>.</P
><P
>The creation of character special files (with
<SPAN
CLASS="APPLICATION"
>mknod</SPAN
>) is a privileged operation and
devices cannot be opened by major and minor number. That means
applications cannot <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>reliable</I
></SPAN
> scan for loaded or
installed drivers. The user must enter a device name, or the
application can try the conventional device names.</P
><P
>Under the device filesystem (devfs) the minor number
options are ignored. V4L2 drivers (or by proxy the "videodev" module)
automatically create the required device files in the
<TT
CLASS="FILENAME"
>/dev/v4l</TT
> directory using the conventional device
names above.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="RELATED"
>1.1.2. Related Devices</A
></H3
><P
>Devices can support several related functions. For example
video capturing, video overlay and VBI capturing are related because
these functions share, amongst other, the same video input and tuner
frequency. V4L and earlier versions of V4L2 used the same device name
and minor number for video capturing and overlay, but different ones
for VBI. Experience showed this approach has several problems<A
NAME="AEN135"
HREF="#FTN.AEN135"
><SPAN
CLASS="footnote"
>[3]</SPAN
></A
>, and to make things worse the V4L videodev module
used to prohibit multiple opens of a device.</P
><P
>As a remedy the present version of the V4L2 API relaxed the
concept of device types with specific names and minor numbers. For
compatibility with old applications drivers must still register different
minor numbers to assign a default function to the device. But if related
functions are supported by the driver they must be available under all
registered minor numbers. The desired function can be selected after
opening the device as described in <A
HREF="#DEVICES"
>Chapter 4</A
>.</P
><P
>Imagine a driver supporting video capturing, video
overlay, raw VBI capturing, and FM radio reception. It registers three
devices with minor number 0, 64 and 224 (this numbering scheme is
inherited from the V4L API). Regardless if
<TT
CLASS="FILENAME"
>/dev/video</TT
> (81, 0) or
<TT
CLASS="FILENAME"
>/dev/vbi</TT
> (81, 224) is opened the application can
select any one of the video capturing, overlay or VBI capturing
functions. Without programming (e. g. reading from the device
with <SPAN
CLASS="APPLICATION"
>dd</SPAN
> or <SPAN
CLASS="APPLICATION"
>cat</SPAN
>)
<TT
CLASS="FILENAME"
>/dev/video</TT
> captures video images, while
<TT
CLASS="FILENAME"
>/dev/vbi</TT
> captures raw VBI data.
<TT
CLASS="FILENAME"
>/dev/radio</TT
> (81, 64) is invariable a radio device,
unrelated to the video functions. Being unrelated does not imply the
devices can be used at the same time, however. The
<CODE
CLASS="FUNCTION"
>open()</CODE
> function may very well return an
<SPAN
CLASS="ERRORCODE"
>EBUSY</SPAN
> error code.</P
><P
>Besides video input or output the hardware may also
support audio sampling or playback. If so, these functions are
implemented as OSS or ALSA PCM devices and eventually OSS or ALSA
audio mixer. The V4L2 API makes no provisions yet to find these
related devices. If you have an idea please write to the Video4Linux
mailing list: <A
HREF="https://listman.redhat.com/mailman/listinfo/video4linux-list"
TARGET="_top"
>https://listman.redhat.com/mailman/listinfo/video4linux-list</A
>.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN153"
>1.1.3. Multiple Opens</A
></H3
><P
>In general, V4L2 devices can be opened more than once.
When this is supported by the driver, users can for example start a
"panel" application to change controls like brightness or audio
volume, while another application captures video and audio. In other words, panel
applications are comparable to an OSS or ALSA audio mixer application.
When a device supports multiple functions like capturing and overlay
<SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>simultaneously</I
></SPAN
>, multiple opens allow concurrent
use of the device by forked processes or specialized applications.</P
><P
>Multiple opens are optional, although drivers should
permit at least concurrent accesses without data exchange, i. e.
panel applications. This implies <CODE
CLASS="FUNCTION"
>open()</CODE
> can
return an <SPAN
CLASS="ERRORCODE"
>EBUSY</SPAN
> error code when the device is already in use, as well as
<CODE
CLASS="FUNCTION"
>ioctl()</CODE
> functions initiating data exchange
(namely the <A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
></A
> ioctl), and the <CODE
CLASS="FUNCTION"
>read()</CODE
>
and <CODE
CLASS="FUNCTION"
>write()</CODE
> functions.</P
><P
>Mere opening a V4L2 device does not grant exclusive
access.<A
NAME="AEN166"
HREF="#FTN.AEN166"
><SPAN
CLASS="footnote"
>[4]</SPAN
></A
> Initiating data exchange however assigns the right
to read or write the requested type of data, and to change related
properties, to this file descriptor. Applications can request
additional access privileges using the priority mechanism described in
<A
HREF="#APP-PRI"
>Section 1.3</A
>.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN170"
>1.1.4. Shared Data Streams</A
></H3
><P
>V4L2 drivers should not support multiple applications
reading or writing the same data stream on a device by copying
buffers, time multiplexing or similar means. This is better handled by
a proxy application in user space. When the driver supports stream
sharing anyway it must be implemented transparently. The V4L2 API does
not specify how conflicts are solved. </P
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN173"
>1.1.5. Functions</A
></H3
><P
>To open and close V4L2 devices applications use the <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
> and <A
HREF="#FUNC-CLOSE"
><CODE
CLASS="FUNCTION"
>close()</CODE
></A
> function,
respectively. Devices are programmed using the <A
HREF="#FUNC-IOCTL"
><CODE
CLASS="FUNCTION"
>ioctl()</CODE
></A
> function as
explained in the following sections.</P
></DIV
></DIV
><DIV
CLASS="SECTION"
><HR><H2
CLASS="SECTION"
><A
NAME="QUERYCAP"
>1.2. Querying Capabilities</A
></H2
><P
>Because V4L2 covers a wide variety of devices not all
aspects of the API are equally applicable to all types of devices.
Furthermore devices of the same type have different capabilities and
this specification permits the omission of a few complicated and less
important parts of the API.</P
><P
>The <A
HREF="#VIDIOC-QUERYCAP"
><CODE
CLASS="CONSTANT"
>VIDIOC_QUERYCAP</CODE
></A
> ioctl is available to check if the kernel
device is compatible with this specification, and to query the <A
HREF="#DEVICES"
>functions</A
> and <A
HREF="#IO"
>I/O
methods</A
> supported by the device. Other features can be queried
by calling the respective ioctl, for example <A
HREF="#VIDIOC-ENUMINPUT"
><CODE
CLASS="CONSTANT"
>VIDIOC_ENUMINPUT</CODE
></A
>
to learn about the number, types and names of video connectors on the
device. Although abstraction is a major objective of this API, the
ioctl also allows driver specific applications to reliable identify
the driver.</P
><P
>All V4L2 drivers must support
<CODE
CLASS="CONSTANT"
>VIDIOC_QUERYCAP</CODE
>. Applications should always call
this ioctl after opening the device.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H2
CLASS="SECTION"
><A
NAME="APP-PRI"
>1.3. Application Priority</A
></H2
><P
>When multiple applications share a device it may be
desirable to assign them different priorities. Contrary to the
traditional "rm -rf /" school of thought a video recording application
could for example block other applications from changing video
controls or switching the current TV channel. Another objective is to
permit low priority applications working in background, which can be
preempted by user controlled applications and automatically regain
control of the device at a later time.</P
><P
>Since these features cannot be implemented entirely in user
space V4L2 defines the <A
HREF="#VIDIOC-G-PRIORITY"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_PRIORITY</CODE
></A
> and <A
HREF="#VIDIOC-G-PRIORITY"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_PRIORITY</CODE
></A
>
ioctls to request and query the access priority associate with a file
descriptor. Opening a device assigns a medium priority, compatible
with earlier versions of V4L2 and drivers not supporting these ioctls.
Applications requiring a different priority will usually call
<CODE
CLASS="CONSTANT"
>VIDIOC_S_PRIORITY</CODE
> after verifying the device with
the <A
HREF="#VIDIOC-QUERYCAP"
><CODE
CLASS="CONSTANT"
>VIDIOC_QUERYCAP</CODE
></A
> ioctl.</P
><P
>Ioctls changing driver properties, such as <A
HREF="#VIDIOC-G-INPUT"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_INPUT</CODE
></A
>,
return an <SPAN
CLASS="ERRORCODE"
>EBUSY</SPAN
> error code after another application obtained higher priority.
An event mechanism to notify applications about asynchronous property
changes has been proposed but not added yet.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H2
CLASS="SECTION"
><A
NAME="VIDEO"
>1.4. Video Inputs and Outputs</A
></H2
><P
>Video inputs and outputs are physical connectors of a
device. These can be for example RF connectors (antenna/cable), CVBS
a.k.a. Composite Video, S-Video or RGB connectors. Only video and VBI
capture devices have inputs, output devices have outputs, at least one
each. Radio devices have no video inputs or outputs.</P
><P
>To learn about the number and attributes of the
available inputs and outputs applications can enumerate them with the
<A
HREF="#VIDIOC-ENUMINPUT"
><CODE
CLASS="CONSTANT"
>VIDIOC_ENUMINPUT</CODE
></A
> and <A
HREF="#VIDIOC-ENUMOUTPUT"
><CODE
CLASS="CONSTANT"
>VIDIOC_ENUMOUTPUT</CODE
></A
> ioctl, respectively. The
struct <A
HREF="#V4L2-INPUT"
>v4l2_input</A
> returned by the <CODE
CLASS="CONSTANT"
>VIDIOC_ENUMINPUT</CODE
>
ioctl also contains signal status information applicable when the
current video input is queried.</P
><P
>The <A
HREF="#VIDIOC-G-INPUT"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_INPUT</CODE
></A
> and <A
HREF="#VIDIOC-G-OUTPUT"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_OUTPUT</CODE
></A
> ioctl return the
index of the current video input or output. To select a different
input or output applications call the <A
HREF="#VIDIOC-G-INPUT"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_INPUT</CODE
></A
> and
<A
HREF="#VIDIOC-G-OUTPUT"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_OUTPUT</CODE
></A
> ioctl. Drivers must implement all the input ioctls
when the device has one or more inputs, all the output ioctls when the
device has one or more outputs.</P
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN228"
></A
><P
><B
>Example 1-1. Information about the current video input</B
></P
><PRE
CLASS="PROGRAMLISTING"
>struct <A
HREF="#V4L2-INPUT"
>v4l2_input</A
> input;
int index;
if (-1 == ioctl (fd, <A
HREF="#VIDIOC-G-INPUT"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_INPUT</CODE
></A
>, &index)) {
perror ("VIDIOC_G_INPUT");
exit (EXIT_FAILURE);
}
memset (&input, 0, sizeof (input));
input.index = index;
if (-1 == ioctl (fd, <A
HREF="#VIDIOC-ENUMINPUT"
><CODE
CLASS="CONSTANT"
>VIDIOC_ENUMINPUT</CODE
></A
>, &input)) {
perror ("VIDIOC_ENUMINPUT");
exit (EXIT_FAILURE);
}
printf ("Current input: %s\n", input.name);
</PRE
></DIV
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN236"
></A
><P
><B
>Example 1-2. Switching to the first video input</B
></P
><PRE
CLASS="PROGRAMLISTING"
>int index;
index = 0;
if (-1 == ioctl (fd, <A
HREF="#VIDIOC-G-INPUT"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_INPUT</CODE
></A
>, &index)) {
perror ("VIDIOC_S_INPUT");
exit (EXIT_FAILURE);
}
</PRE
></DIV
></DIV
><DIV
CLASS="SECTION"
><HR><H2
CLASS="SECTION"
><A
NAME="AUDIO"
>1.5. Audio Inputs and Outputs</A
></H2
><P
>Audio inputs and outputs are physical connectors of a
device. Video capture devices have inputs, output devices have
outputs, zero or more each. Radio devices have no audio inputs or
outputs. They have exactly one tuner which in fact
<SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>is</I
></SPAN
> an audio source, but this API associates
tuners with video inputs or outputs only, and radio devices have
none of these.<A
NAME="AEN245"
HREF="#FTN.AEN245"
><SPAN
CLASS="footnote"
>[5]</SPAN
></A
> A connector on a TV card to loop back the received
audio signal to a sound card is not considered an audio output.</P
><P
>Audio and video inputs and outputs are associated. Selecting
a video source also selects an audio source. This is most evident when
the video and audio source is a tuner. Further audio connectors can
combine with more than one video input or output. Assumed two
composite video inputs and two audio inputs exist, there may be up to
four valid combinations. The relation of video and audio connectors
is defined in the <CODE
CLASS="STRUCTFIELD"
>audioset</CODE
> field of the
respective struct <A
HREF="#V4L2-INPUT"
>v4l2_input</A
> or struct <A
HREF="#V4L2-OUTPUT"
>v4l2_output</A
>, where each bit represents
the index number, starting at zero, of one audio input or output.</P
><P
>To learn about the number and attributes of the
available inputs and outputs applications can enumerate them with the
<A
HREF="#VIDIOC-ENUMAUDIO"
><CODE
CLASS="CONSTANT"
>VIDIOC_ENUMAUDIO</CODE
></A
> and <A
HREF="#VIDIOC-ENUMAUDIOOUT"
><CODE
CLASS="CONSTANT"
>VIDIOC_ENUMAUDOUT</CODE
></A
> ioctl, respectively. The
struct <A
HREF="#V4L2-AUDIO"
>v4l2_audio</A
> returned by the <CODE
CLASS="CONSTANT"
>VIDIOC_ENUMAUDIO</CODE
> ioctl
also contains signal status information applicable when the current
audio input is queried.</P
><P
>The <A
HREF="#VIDIOC-G-AUDIO"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_AUDIO</CODE
></A
> and <A
HREF="#VIDIOC-G-AUDIOOUT"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_AUDOUT</CODE
></A
> ioctl report
the current audio input and output, respectively. Note that, unlike
<A
HREF="#VIDIOC-G-INPUT"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_INPUT</CODE
></A
> and <A
HREF="#VIDIOC-G-OUTPUT"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_OUTPUT</CODE
></A
> these ioctls return a structure
as <CODE
CLASS="CONSTANT"
>VIDIOC_ENUMAUDIO</CODE
> and
<CODE
CLASS="CONSTANT"
>VIDIOC_ENUMAUDOUT</CODE
> do, not just an index.</P
><P
>To select an audio input and change its properties
applications call the <A
HREF="#VIDIOC-G-AUDIO"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_AUDIO</CODE
></A
> ioctl. To select an audio
output (which presently has no changeable properties) applications
call the <A
HREF="#VIDIOC-G-AUDIOOUT"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_AUDOUT</CODE
></A
> ioctl.</P
><P
>Drivers must implement all input ioctls when the device
has one or more inputs, all output ioctls when the device has one
or more outputs. When the device has any audio inputs or outputs the
driver must set the <CODE
CLASS="CONSTANT"
>V4L2_CAP_AUDIO</CODE
> flag in the
struct <A
HREF="#V4L2-CAPABILITY"
>v4l2_capability</A
> returned by the <A
HREF="#VIDIOC-QUERYCAP"
><CODE
CLASS="CONSTANT"
>VIDIOC_QUERYCAP</CODE
></A
> ioctl.</P
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN282"
></A
><P
><B
>Example 1-3. Information about the current audio input</B
></P
><PRE
CLASS="PROGRAMLISTING"
>struct <A
HREF="#V4L2-AUDIO"
>v4l2_audio</A
> audio;
memset (&audio, 0, sizeof (audio));
if (-1 == ioctl (fd, <A
HREF="#VIDIOC-G-AUDIO"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_AUDIO</CODE
></A
>, &audio)) {
perror ("VIDIOC_G_AUDIO");
exit (EXIT_FAILURE);
}
printf ("Current input: %s\n", audio.name);
</PRE
></DIV
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN288"
></A
><P
><B
>Example 1-4. Switching to the first audio input</B
></P
><PRE
CLASS="PROGRAMLISTING"
>struct <A
HREF="#V4L2-AUDIO"
>v4l2_audio</A
> audio;
memset (&audio, 0, sizeof (audio)); /* clear audio.mode, audio.reserved */
audio.index = 0;
if (-1 == ioctl (fd, <A
HREF="#VIDIOC-G-AUDIO"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_AUDIO</CODE
></A
>, &audio)) {
perror ("VIDIOC_S_AUDIO");
exit (EXIT_FAILURE);
}
</PRE
></DIV
></DIV
><DIV
CLASS="SECTION"
><HR><H2
CLASS="SECTION"
><A
NAME="TUNER"
>1.6. Tuners and Modulators</A
></H2
><DIV
CLASS="SECTION"
><H3
CLASS="SECTION"
><A
NAME="AEN296"
>1.6.1. Tuners</A
></H3
><P
>Video input devices can have one or more tuners
demodulating a RF signal. Each tuner is associated with one or more
video inputs, depending on the number of RF connectors on the tuner.
The <CODE
CLASS="STRUCTFIELD"
>type</CODE
> field of the respective
struct <A
HREF="#V4L2-INPUT"
>v4l2_input</A
> returned by the <A
HREF="#VIDIOC-ENUMINPUT"
><CODE
CLASS="CONSTANT"
>VIDIOC_ENUMINPUT</CODE
></A
> ioctl is set to
<CODE
CLASS="CONSTANT"
>V4L2_INPUT_TYPE_TUNER</CODE
> and its
<CODE
CLASS="STRUCTFIELD"
>tuner</CODE
> field contains the index number of
the tuner.</P
><P
>Radio devices have exactly one tuner with index zero, no
video inputs.</P
><P
>To query and change tuner properties applications use the
<A
HREF="#VIDIOC-G-TUNER"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_TUNER</CODE
></A
> and <A
HREF="#VIDIOC-G-TUNER"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_TUNER</CODE
></A
> ioctl, respectively. The
struct <A
HREF="#V4L2-TUNER"
>v4l2_tuner</A
> returned by <CODE
CLASS="CONSTANT"
>VIDIOC_G_TUNER</CODE
> also
contains signal status information applicable when the tuner of the
current video input, or a radio tuner is queried. Note that
<CODE
CLASS="CONSTANT"
>VIDIOC_S_TUNER</CODE
> does not switch the current tuner,
when there is more than one at all. The tuner is solely determined by
the current video input. Drivers must support both ioctls and set the
<CODE
CLASS="CONSTANT"
>V4L2_CAP_TUNER</CODE
> flag in the struct <A
HREF="#V4L2-CAPABILITY"
>v4l2_capability</A
>
returned by the <A
HREF="#VIDIOC-QUERYCAP"
><CODE
CLASS="CONSTANT"
>VIDIOC_QUERYCAP</CODE
></A
> ioctl when the device has one or
more tuners.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN318"
>1.6.2. Modulators</A
></H3
><P
>Video output devices can have one or more modulators, uh,
modulating a video signal for radiation or connection to the antenna
input of a TV set or video recorder. Each modulator is associated with
one or more video outputs, depending on the number of RF connectors on
the modulator. The <CODE
CLASS="STRUCTFIELD"
>type</CODE
> field of the
respective struct <A
HREF="#V4L2-OUTPUT"
>v4l2_output</A
> returned by the <A
HREF="#VIDIOC-ENUMOUTPUT"
><CODE
CLASS="CONSTANT"
>VIDIOC_ENUMOUTPUT</CODE
></A
> is set to
<CODE
CLASS="CONSTANT"
>V4L2_OUTPUT_TYPE_MODULATOR</CODE
> and its
<CODE
CLASS="STRUCTFIELD"
>modulator</CODE
> field contains the index number
of the modulator. This specification does not define radio output
devices.</P
><P
>To query and change modulator properties applications use
the <A
HREF="#VIDIOC-G-MODULATOR"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_MODULATOR</CODE
></A
> and <A
HREF="#VIDIOC-G-MODULATOR"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_MODULATOR</CODE
></A
> ioctl. Note that
<CODE
CLASS="CONSTANT"
>VIDIOC_S_MODULATOR</CODE
> does not switch the current
modulator, when there is more than one at all. The modulator is solely
determined by the current video output. Drivers must support both
ioctls and set the <CODE
CLASS="CONSTANT"
>V4L2_CAP_TUNER</CODE
> (sic) flag in
the struct <A
HREF="#V4L2-CAPABILITY"
>v4l2_capability</A
> returned by the <A
HREF="#VIDIOC-QUERYCAP"
><CODE
CLASS="CONSTANT"
>VIDIOC_QUERYCAP</CODE
></A
> ioctl when the
device has one or more modulators.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN337"
>1.6.3. Radio Frequency</A
></H3
><P
>To get and set the tuner or modulator radio frequency
applications use the <A
HREF="#VIDIOC-G-FREQUENCY"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_FREQUENCY</CODE
></A
> and <A
HREF="#VIDIOC-G-FREQUENCY"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_FREQUENCY</CODE
></A
>
ioctl which both take a pointer to a struct <A
HREF="#V4L2-FREQUENCY"
>v4l2_frequency</A
>. These ioctls
are used for TV and radio devices alike. Drivers must support both
ioctls when the tuner or modulator ioctls are supported, or
when the device is a radio device.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN345"
>1.6.4. Satellite Receivers</A
></H3
><P
>To be discussed. See also
proposals by Peter Schlaf, video4linux-list@redhat.com on 23 Oct 2002,
subject: "Re: [V4L] Re: v4l2 api".</P
></DIV
></DIV
><DIV
CLASS="SECTION"
><HR><H2
CLASS="SECTION"
><A
NAME="STANDARD"
>1.7. Video Standards</A
></H2
><P
>Video devices typically support one or more different video
standards or variations of standards. Each video input and output may
support another set of standards. This set is reported by the
<CODE
CLASS="STRUCTFIELD"
>std</CODE
> field of struct <A
HREF="#V4L2-INPUT"
>v4l2_input</A
> and
struct <A
HREF="#V4L2-OUTPUT"
>v4l2_output</A
> returned by the <A
HREF="#VIDIOC-ENUMINPUT"
><CODE
CLASS="CONSTANT"
>VIDIOC_ENUMINPUT</CODE
></A
> and
<A
HREF="#VIDIOC-ENUMOUTPUT"
><CODE
CLASS="CONSTANT"
>VIDIOC_ENUMOUTPUT</CODE
></A
> ioctl, respectively.</P
><P
>V4L2 defines one bit for each analog video standard
currently in use worldwide, and sets aside bits for driver defined
standards, e. g. hybrid standards to watch NTSC video tapes on PAL TVs
and vice versa. Applications can use the predefined bits to select a
particular standard, although presenting the user a menu of supported
standards is preferred. To enumerate and query the attributes of the
supported standards applications use the <A
HREF="#VIDIOC-ENUMSTD"
><CODE
CLASS="CONSTANT"
>VIDIOC_ENUMSTD</CODE
></A
> ioctl.</P
><P
>Many of the defined standards are actually just variations
of a few major standards. The hardware may in fact not distinguish
between them, or do so internal and switch automatically. Therefore
enumerated standards also contain sets of one or more standard
bits.</P
><P
>Assume a hypothetic tuner capable of demodulating B/PAL,
G/PAL and I/PAL signals. The first enumerated standard is a set of B
and G/PAL, switched automatically depending on the selected radio
frequency in UHF or VHF band. Enumeration gives a "PAL-B/G" or "PAL-I"
choice. Similar a Composite input may collapse standards, enumerating
"PAL-B/G/H/I", "NTSC-M" and "SECAM-D/K".<A
NAME="AEN363"
HREF="#FTN.AEN363"
><SPAN
CLASS="footnote"
>[6]</SPAN
></A
></P
><P
>To query and select the standard used by the current video
input or output applications call the <A
HREF="#VIDIOC-G-STD"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_STD</CODE
></A
> and
<A
HREF="#VIDIOC-G-STD"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_STD</CODE
></A
> ioctl, respectively. The <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>received</I
></SPAN
>
standard can be sensed with the <A
HREF="#VIDIOC-QUERYSTD"
><CODE
CLASS="CONSTANT"
>VIDIOC_QUERYSTD</CODE
></A
> ioctl. Note parameter of all these ioctls is a pointer to a <A
HREF="#V4L2-STD-ID"
>v4l2_std_id</A
> type (a standard set), <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>not</I
></SPAN
> an index into the standard enumeration.<A
NAME="AEN375"
HREF="#FTN.AEN375"
><SPAN
CLASS="footnote"
>[7]</SPAN
></A
> Drivers must implement all video standard ioctls
when the device has one or more video inputs or outputs.</P
><P
>Special rules apply to USB cameras where the notion of video
standards makes little sense. More generally any capture device,
output devices accordingly, which is <P
></P
><UL
><LI
><P
>incapable of capturing fields or frames at the nominal
rate of the video standard, or</P
></LI
><LI
><P
>where <A
HREF="#BUFFER"
>timestamps</A
> refer
to the instant the field or frame was received by the driver, not the
capture time, or</P
></LI
><LI
><P
>where <A
HREF="#BUFFER"
>sequence numbers</A
>
refer to the frames received by the driver, not the captured
frames.</P
></LI
></UL
> Here the driver shall set the
<CODE
CLASS="STRUCTFIELD"
>std</CODE
> field of struct <A
HREF="#V4L2-INPUT"
>v4l2_input</A
> and struct <A
HREF="#V4L2-OUTPUT"
>v4l2_output</A
>
to zero, the <CODE
CLASS="CONSTANT"
>VIDIOC_G_STD</CODE
>,
<CODE
CLASS="CONSTANT"
>VIDIOC_S_STD</CODE
>,
<CODE
CLASS="CONSTANT"
>VIDIOC_QUERYSTD</CODE
> and
<CODE
CLASS="CONSTANT"
>VIDIOC_ENUMSTD</CODE
> ioctls shall return the
<SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code.<A
NAME="AEN407"
HREF="#FTN.AEN407"
><SPAN
CLASS="footnote"
>[8]</SPAN
></A
></P
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN410"
></A
><P
><B
>Example 1-5. Information about the current video standard</B
></P
><PRE
CLASS="PROGRAMLISTING"
><A
HREF="#V4L2-STD-ID"
>v4l2_std_id</A
> std;
struct <A
HREF="#V4L2-STANDARD"
>v4l2_standard</A
> standard;
if (-1 == ioctl (fd, <A
HREF="#VIDIOC-G-STD"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_STD</CODE
></A
>, &std)) {
/* Note when VIDIOC_ENUMSTD always returns EINVAL this
is no video device or it falls under the USB exception,
and VIDIOC_G_STD returning EINVAL is no error. */
perror ("VIDIOC_G_STD");
exit (EXIT_FAILURE);
}
memset (&standard, 0, sizeof (standard));
standard.index = 0;
while (0 == ioctl (fd, <A
HREF="#VIDIOC-ENUMSTD"
><CODE
CLASS="CONSTANT"
>VIDIOC_ENUMSTD</CODE
></A
>, &standard)) {
if (standard.id & std) {
printf ("Current video standard: %s\n", standard.name);
exit (EXIT_SUCCESS);
}
standard.index++;
}
/* EINVAL indicates the end of the enumeration, which cannot be
empty unless this device falls under the USB exception. */
if (errno == EINVAL || standard.index == 0) {
perror ("VIDIOC_ENUMSTD");
exit (EXIT_FAILURE);
}
</PRE
></DIV
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN419"
></A
><P
><B
>Example 1-6. Listing the video standards supported by the current
input</B
></P
><PRE
CLASS="PROGRAMLISTING"
>struct <A
HREF="#V4L2-INPUT"
>v4l2_input</A
> input;
struct <A
HREF="#V4L2-STANDARD"
>v4l2_standard</A
> standard;
memset (&input, 0, sizeof (input));
if (-1 == ioctl (fd, <A
HREF="#VIDIOC-G-INPUT"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_INPUT</CODE
></A
>, &input.index)) {
perror ("VIDIOC_G_INPUT");
exit (EXIT_FAILURE);
}
if (-1 == ioctl (fd, <A
HREF="#VIDIOC-ENUMINPUT"
><CODE
CLASS="CONSTANT"
>VIDIOC_ENUMINPUT</CODE
></A
>, &input)) {
perror ("VIDIOC_ENUM_INPUT");
exit (EXIT_FAILURE);
}
printf ("Current input %s supports:\n", input.name);
memset (&standard, 0, sizeof (standard));
standard.index = 0;
while (0 == ioctl (fd, <A
HREF="#VIDIOC-ENUMSTD"
><CODE
CLASS="CONSTANT"
>VIDIOC_ENUMSTD</CODE
></A
>, &standard)) {
if (standard.id & input.std)
printf ("%s\n", standard.name);
standard.index++;
}
/* EINVAL indicates the end of the enumeration, which cannot be
empty unless this device falls under the USB exception. */
if (errno != EINVAL || standard.index == 0) {
perror ("VIDIOC_ENUMSTD");
exit (EXIT_FAILURE);
}
</PRE
></DIV
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN430"
></A
><P
><B
>Example 1-7. Selecting a new video standard</B
></P
><PRE
CLASS="PROGRAMLISTING"
>struct <A
HREF="#V4L2-INPUT"
>v4l2_input</A
> input;
memset (&input, 0, sizeof (input));
if (-1 == ioctl (fd, <A
HREF="#VIDIOC-G-INPUT"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_INPUT</CODE
></A
>, &input.index)) {
perror ("VIDIOC_G_INPUT");
exit (EXIT_FAILURE);
}
if (-1 == ioctl (fd, <A
HREF="#VIDIOC-ENUMINPUT"
><CODE
CLASS="CONSTANT"
>VIDIOC_ENUMINPUT</CODE
></A
>, &input)) {
perror ("VIDIOC_ENUM_INPUT");
exit (EXIT_FAILURE);
}
if (0 == (input.std & V4L2_STD_PAL_BG)) {
fprintf (stderr, "Oops. B/G PAL is not supported.\n");
exit (EXIT_FAILURE);
}
/* Note this is also supposed to work when only B
<SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>or</I
></SPAN
> G/PAL is supported. */
if (-1 == ioctl (fd, <A
HREF="#VIDIOC-G-STD"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_STD</CODE
></A
>, V4L2_STD_PAL_BG)) {
perror ("VIDIOC_S_STD");
exit (EXIT_FAILURE);
}
</PRE
></DIV
></DIV
><DIV
CLASS="SECTION"
><HR><H2
CLASS="SECTION"
><A
NAME="CONTROL"
>1.8. Controls</A
></H2
><P
>Devices typically have a number of user-settable controls
such as brightness, saturation and so on, which would be presented to
the user on a graphical user interface. But, different devices
will have different controls available, and furthermore, the range of
possible values, and the default value will vary from device to
device. The control ioctls provide the information and a mechanism to
create a nice user interface for these controls that will work
correctly with any device.</P
><P
>All controls are accessed using an ID value. V4L2 defines
several IDs for specific purposes. Drivers can also implement their
own custom controls using <CODE
CLASS="CONSTANT"
>V4L2_CID_PRIVATE_BASE</CODE
>
and higher values. The pre-defined control IDs have the prefix
<CODE
CLASS="CONSTANT"
>V4L2_CID_</CODE
>, and are listed in <A
HREF="#CONTROL-ID"
>Table 1-1</A
>. The ID is used when querying the attributes of
a control, and when getting or setting the current value.</P
><P
>Generally applications should present controls to the user
without assumptions about their purpose. Each control comes with a
name string the user is supposed to understand. When the purpose is
non-intuitive the driver writer should provide a user manual, a user
interface plug-in or a driver specific panel application. Predefined
IDs were introduced to change a few controls programmatically, for
example to mute a device during a channel switch.</P
><P
>Drivers may enumerate different controls after switching the
current video input or output, tuner or modulator, or audio input or
output. Different in the sense of other bounds, another default and
current value, step size or other menu items. A control with a certain
<SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>custom</I
></SPAN
> ID can also change name and type.<A
NAME="AEN451"
HREF="#FTN.AEN451"
><SPAN
CLASS="footnote"
>[9]</SPAN
></A
> Control values are stored globally, they do not
change when switching except to stay within the reported bounds. They
also do not change e. g. when the device is opened or closed, when the
tuner radio frequency is changed or generally never without
application request. Since V4L2 specifies no event mechanism, panel
applications intended to cooperate with other panel applications (be
they built into a larger application, as a TV viewer) may need to
regularly poll control values to update their user
interface.<A
NAME="AEN454"
HREF="#FTN.AEN454"
><SPAN
CLASS="footnote"
>[10]</SPAN
></A
></P
><DIV
CLASS="TABLE"
><A
NAME="CONTROL-ID"
></A
><P
><B
>Table 1-1. Control IDs</B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="38%"
TITLE="C1"><COL
WIDTH="12%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><THEAD
><TR
><TH
>ID</TH
><TH
>Type</TH
><TH
>Description</TH
></TR
></THEAD
><TBODY
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CID_BASE</CODE
></TD
><TD
> </TD
><TD
>First predefined ID, equal to
<CODE
CLASS="CONSTANT"
>V4L2_CID_BRIGHTNESS</CODE
>.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CID_BRIGHTNESS</CODE
></TD
><TD
>integer</TD
><TD
>Picture brightness, or more precisely, the black
level. Will not turn up the intelligence of the program
you're watching.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CID_CONTRAST</CODE
></TD
><TD
>integer</TD
><TD
>Picture contrast or luma gain.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CID_SATURATION</CODE
></TD
><TD
>integer</TD
><TD
>Picture color saturation or chroma gain.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CID_HUE</CODE
></TD
><TD
>integer</TD
><TD
>Hue or color balance.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CID_AUDIO_VOLUME</CODE
></TD
><TD
>integer</TD
><TD
>Overall audio volume. Note some drivers also
provide an OSS or ALSA mixer interface.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CID_AUDIO_BALANCE</CODE
></TD
><TD
>integer</TD
><TD
>Audio stereo balance. Minimum corresponds to all
the way left, maximum to right.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CID_AUDIO_BASS</CODE
></TD
><TD
>integer</TD
><TD
>Audio bass adjustment.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CID_AUDIO_TREBLE</CODE
></TD
><TD
>integer</TD
><TD
>Audio treble adjustment.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CID_AUDIO_MUTE</CODE
></TD
><TD
>boolean</TD
><TD
>Mute audio, i. e. set the volume to zero, however
without affecting <CODE
CLASS="CONSTANT"
>V4L2_CID_AUDIO_VOLUME</CODE
>. Like
ALSA drivers, V4L2 drivers must mute at load time to avoid excessive
noise. Actually the entire device should be reset to a low power
consumption state.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CID_AUDIO_LOUDNESS</CODE
></TD
><TD
>boolean</TD
><TD
>Loudness mode (bass boost).</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CID_BLACK_LEVEL</CODE
></TD
><TD
>integer</TD
><TD
>Another name for brightness (not a synonym of
<CODE
CLASS="CONSTANT"
>V4L2_CID_BRIGHTNESS</CODE
>). [?]</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CID_AUTO_WHITE_BALANCE</CODE
></TD
><TD
>boolean</TD
><TD
>Automatic white balance (cameras).</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CID_DO_WHITE_BALANCE</CODE
></TD
><TD
>button</TD
><TD
>This is an action control. When set (the value is
ignored), the device will do a white balance and then hold the current
setting. Contrast this with the boolean
<CODE
CLASS="CONSTANT"
>V4L2_CID_AUTO_WHITE_BALANCE</CODE
>, which, when
activated, keeps adjusting the white balance.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CID_RED_BALANCE</CODE
></TD
><TD
>integer</TD
><TD
>Red chroma balance.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CID_BLUE_BALANCE</CODE
></TD
><TD
>integer</TD
><TD
>Blue chroma balance.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CID_GAMMA</CODE
></TD
><TD
>integer</TD
><TD
>Gamma adjust.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CID_WHITENESS</CODE
></TD
><TD
>integer</TD
><TD
>Whiteness for grey-scale devices. This is a synonym
for <CODE
CLASS="CONSTANT"
>V4L2_CID_GAMMA</CODE
>.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CID_EXPOSURE</CODE
></TD
><TD
>integer</TD
><TD
>Exposure (cameras). [Unit?]</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CID_AUTOGAIN</CODE
></TD
><TD
>boolean</TD
><TD
>Automatic gain/exposure control.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CID_GAIN</CODE
></TD
><TD
>integer</TD
><TD
>Gain control.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CID_HFLIP</CODE
></TD
><TD
>boolean</TD
><TD
>Mirror the picture horizontally.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CID_VFLIP</CODE
></TD
><TD
>boolean</TD
><TD
>Mirror the picture vertically.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CID_HCENTER</CODE
></TD
><TD
>integer</TD
><TD
>Horizontal image centering.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CID_VCENTER</CODE
></TD
><TD
>integer</TD
><TD
>Vertical image centering. Centering is intended to
<SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>physically</I
></SPAN
> adjust cameras. For image cropping see
<A
HREF="#CROP"
>Section 1.10</A
>, for clipping <A
HREF="#OVERLAY"
>Section 4.2</A
>.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CID_LASTP1</CODE
></TD
><TD
> </TD
><TD
>End of the predefined control IDs
(currently <CODE
CLASS="CONSTANT"
>V4L2_CID_VCENTER</CODE
> + 1).</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CID_PRIVATE_BASE</CODE
></TD
><TD
> </TD
><TD
>ID of the first custom (driver specific) control.
Applications depending on particular custom controls should check the
driver name and version, see <A
HREF="#QUERYCAP"
>Section 1.2</A
>.</TD
></TR
></TBODY
></TABLE
></DIV
><P
>Applications can enumerate the available controls with the
<A
HREF="#VIDIOC-QUERYCTRL"
><CODE
CLASS="CONSTANT"
>VIDIOC_QUERYCTRL</CODE
></A
> and <A
HREF="#VIDIOC-QUERYCTRL"
><CODE
CLASS="CONSTANT"
>VIDIOC_QUERYMENU</CODE
></A
> ioctls, get and set a
control value with the <A
HREF="#VIDIOC-G-CTRL"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_CTRL</CODE
></A
> and <A
HREF="#VIDIOC-G-CTRL"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_CTRL</CODE
></A
> ioctls.
Drivers must implement <CODE
CLASS="CONSTANT"
>VIDIOC_QUERYCTRL</CODE
>,
<CODE
CLASS="CONSTANT"
>VIDIOC_G_CTRL</CODE
> and
<CODE
CLASS="CONSTANT"
>VIDIOC_S_CTRL</CODE
> when the device has one or more
controls, <CODE
CLASS="CONSTANT"
>VIDIOC_QUERYMENU</CODE
> when it has one or
more menu type controls.</P
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN630"
></A
><P
><B
>Example 1-8. Enumerating all controls</B
></P
><PRE
CLASS="PROGRAMLISTING"
>struct <A
HREF="#V4L2-QUERYCTRL"
>v4l2_queryctrl</A
> queryctrl;
struct <A
HREF="#V4L2-QUERYMENU"
>v4l2_querymenu</A
> querymenu;
static void
enumerate_menu (void)
{
printf (" Menu items:\n");
memset (&querymenu, 0, sizeof (querymenu));
querymenu.id = queryctrl.id;
for (querymenu.index = queryctrl.minimum;
querymenu.index <= queryctrl.maximum;
querymenu.index++) {
if (0 == ioctl (fd, <A
HREF="#VIDIOC-QUERYCTRL"
><CODE
CLASS="CONSTANT"
>VIDIOC_QUERYMENU</CODE
></A
>, &querymenu)) {
printf (" %s\n", querymenu.name);
} else {
perror ("VIDIOC_QUERYMENU");
exit (EXIT_FAILURE);
}
}
}
memset (&queryctrl, 0, sizeof (queryctrl));
for (queryctrl.id = V4L2_CID_BASE;
queryctrl.id < V4L2_CID_LASTP1;
queryctrl.id++) {
if (0 == ioctl (fd, <A
HREF="#VIDIOC-QUERYCTRL"
><CODE
CLASS="CONSTANT"
>VIDIOC_QUERYCTRL</CODE
></A
>, &queryctrl)) {
if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)
continue;
printf ("Control %s\n", queryctrl.name);
if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
enumerate_menu ();
} else {
if (errno == EINVAL)
continue;
perror ("VIDIOC_QUERYCTRL");
exit (EXIT_FAILURE);
}
}
for (queryctrl.id = V4L2_CID_PRIVATE_BASE;;
queryctrl.id++) {
if (0 == ioctl (fd, <A
HREF="#VIDIOC-QUERYCTRL"
><CODE
CLASS="CONSTANT"
>VIDIOC_QUERYCTRL</CODE
></A
>, &queryctrl)) {
if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)
continue;
printf ("Control %s\n", queryctrl.name);
if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
enumerate_menu ();
} else {
if (errno == EINVAL)
break;
perror ("VIDIOC_QUERYCTRL");
exit (EXIT_FAILURE);
}
}
</PRE
></DIV
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN641"
></A
><P
><B
>Example 1-9. Changing controls</B
></P
><PRE
CLASS="PROGRAMLISTING"
>struct <A
HREF="#V4L2-QUERYCTRL"
>v4l2_queryctrl</A
> queryctrl;
struct <A
HREF="#V4L2-CONTROL"
>v4l2_control</A
> control;
memset (&queryctrl, 0, sizeof (queryctrl));
queryctrl.id = V4L2_CID_BRIGHTNESS;
if (-1 == ioctl (fd, <A
HREF="#VIDIOC-QUERYCTRL"
><CODE
CLASS="CONSTANT"
>VIDIOC_QUERYCTRL</CODE
></A
>, &queryctrl)) {
if (errno != EINVAL) {
perror ("VIDIOC_QUERYCTRL");
exit (EXIT_FAILURE);
} else {
printf ("V4L2_CID_BRIGHTNESS is not supported\n");
}
} else if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) {
printf ("V4L2_CID_BRIGHTNESS is not supported\n");
} else {
memset (&control, 0, sizeof (control));
control.id = V4L2_CID_BRIGHTNESS;
control.value = queryctrl.default_value;
if (-1 == ioctl (fd, <A
HREF="#VIDIOC-G-CTRL"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_CTRL</CODE
></A
>, &control)) {
perror ("VIDIOC_S_CTRL");
exit (EXIT_FAILURE);
}
}
memset (&control, 0, sizeof (control));
control.id = V4L2_CID_CONTRAST;
if (0 == ioctl (fd, <A
HREF="#VIDIOC-G-CTRL"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_CTRL</CODE
></A
>, &control)) {
control.value += 1;
/* The driver may clamp the value or return ERANGE, ignored here */
if (-1 == ioctl (fd, <A
HREF="#VIDIOC-G-CTRL"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_CTRL</CODE
></A
>, &control)
&& errno != ERANGE) {
perror ("VIDIOC_S_CTRL");
exit (EXIT_FAILURE);
}
/* Ignore if V4L2_CID_CONTRAST is unsupported */
} else if (errno != EINVAL) {
perror ("VIDIOC_G_CTRL");
exit (EXIT_FAILURE);
}
control.id = V4L2_CID_AUDIO_MUTE;
control.value = TRUE; /* silence */
/* Errors ignored */
ioctl (fd, VIDIOC_S_CTRL, &control);
</PRE
></DIV
></DIV
><DIV
CLASS="SECTION"
><HR><H2
CLASS="SECTION"
><A
NAME="FORMAT"
>1.9. Data Formats</A
></H2
><DIV
CLASS="SECTION"
><H3
CLASS="SECTION"
><A
NAME="AEN656"
>1.9.1. Data Format Negotiation</A
></H3
><P
>Different devices exchange different kinds of data with
applications, for example video images, raw or sliced VBI data, RDS
datagrams. Even within one kind many different formats are possible,
in particular an abundance of image formats. Although drivers must
provide a default and the selection persists across closing and
reopening a device, applications should always negotiate a data format
before engaging in data exchange. Negotiation means the application
asks for a particular format and the driver selects and reports the
best the hardware can do to satisfy the request. Of course
applications can also just query the current selection.</P
><P
>A single mechanism exists to negotiate all data formats
using the aggregate struct <A
HREF="#V4L2-FORMAT"
>v4l2_format</A
> and the <A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_FMT</CODE
></A
> and
<A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
></A
> ioctls. Additionally the <A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_TRY_FMT</CODE
></A
> ioctl can be
used to examine what the hardware <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>could</I
></SPAN
> do,
without actually selecting a new data format. The data formats
supported by the V4L2 API are covered in the respective device section
in <A
HREF="#DEVICES"
>Chapter 4</A
>. For a closer look at image formats see
<A
HREF="#PIXFMT"
>Chapter 2</A
>.</P
><P
>The <CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
> ioctl is a major
turning-point in the initialization sequence. Prior to this point
multiple panel applications can access the same device concurrently to
select the current input, change controls or modify other properties.
The first <CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
> assigns a logical stream
(video data, VBI data etc.) exclusively to one file descriptor.</P
><P
>Exclusive means no other application, more precisely no
other file descriptor, can grab this stream or change device
properties inconsistent with the negotiated parameters. A video
standard change for example, when the new standard uses a different
number of scan lines, can invalidate the selected image format.
Therefore only the file descriptor owning the stream can make
invalidating changes. Accordingly multiple file descriptors which
grabbed different logical streams prevent each other from interfering
with their settings. When for example video overlay is about to start
or already in progress, simultaneous video capturing may be restricted
to the same cropping and image size.</P
><P
>When applications omit the
<CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
> ioctl its locking side effects are
implied by the next step, the selection of an I/O method with the
<A
HREF="#VIDIOC-REQBUFS"
><CODE
CLASS="CONSTANT"
>VIDIOC_REQBUFS</CODE
></A
> ioctl or implicit with the first <A
HREF="#FUNC-READ"
><CODE
CLASS="FUNCTION"
>read()</CODE
></A
> or
<A
HREF="#FUNC-WRITE"
><CODE
CLASS="FUNCTION"
>write()</CODE
></A
> call.</P
><P
>Generally only one logical stream can be assigned to a
file descriptor, the exception being drivers permitting simultaneous
video capturing and overlay using the same file descriptor for
compatibility with V4L and earlier versions of V4L2. Switching the
logical stream or returning into "panel mode" is possible by closing
and reopening the device. Drivers <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>may</I
></SPAN
> support a
switch using <CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
>.</P
><P
>All drivers exchanging data with
applications must support the <CODE
CLASS="CONSTANT"
>VIDIOC_G_FMT</CODE
> and
<CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
> ioctl. Implementation of the
<CODE
CLASS="CONSTANT"
>VIDIOC_TRY_FMT</CODE
> is highly recommended but
optional.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN689"
>1.9.2. Image Format Enumeration</A
></H3
><P
>Apart of the generic format negotiation functions
a special ioctl to enumerate all image formats supported by video
capture, overlay or output devices is available.<A
NAME="AEN692"
HREF="#FTN.AEN692"
><SPAN
CLASS="footnote"
>[11]</SPAN
></A
></P
><P
>The <A
HREF="#VIDIOC-ENUM-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_ENUM_FMT</CODE
></A
> ioctl must be supported
by all drivers exchanging image data with applications.</P
><DIV
CLASS="IMPORTANT"
><BLOCKQUOTE
CLASS="IMPORTANT"
><P
><B
>Important: </B
>Drivers are not supposed to convert image formats in
kernel space. They must enumerate only formats directly supported by
the hardware. If necessary driver writers should publish an example
conversion routine or library for integration into applications.</P
></BLOCKQUOTE
></DIV
></DIV
></DIV
><DIV
CLASS="SECTION"
><HR><H2
CLASS="SECTION"
><A
NAME="CROP"
>1.10. Cropping and Scaling</A
></H2
><P
>Some video capture devices can take a subsection of the
complete picture and shrink or enlarge to an image of arbitrary size.
We call these abilities cropping and scaling. Not quite correct
"cropping" shall also refer to the inverse process, output devices
showing an image in only a region of the picture, and/or scaled
from a source image of different size.</P
><P
>To crop and scale this API defines a source and target
rectangle. On a video capture and overlay device the source is the
received video picture, the target is the captured or overlaid image.
On a video output device the source is the image passed by the
application and the target is the generated video picture. The
remainder of this section refers only to video capture drivers, the
definitions apply to output drivers accordingly.</P
><DIV
CLASS="FIGURE"
><A
NAME="CROP-SCALE"
></A
><P
><B
>Figure 1-1. Cropping and Scaling</B
></P
><DIV
CLASS="MEDIAOBJECT"
><P
><IMG
SRC="crop.gif"></P
></DIV
></DIV
><P
>It is assumed the driver can capture a subsection of the
picture within an arbitrary capture window. Its bounds are defined by
struct <A
HREF="#V4L2-CROPCAP"
>v4l2_cropcap</A
>, giving the coordinates of the top, left corner and
width and height of the window in pixels. Origin and units of the
coordinate system in the analog domain are arbitrarily chosen by the
driver writer.<A
NAME="AEN714"
HREF="#FTN.AEN714"
><SPAN
CLASS="footnote"
>[12]</SPAN
></A
></P
><P
>The source rectangle is defined by struct <A
HREF="#V4L2-CROP"
>v4l2_crop</A
>, giving the
coordinates of its top, left corner, width and height using the same
coordinate system as struct <A
HREF="#V4L2-CROPCAP"
>v4l2_cropcap</A
>. The source rectangle must lie
completely within the capture window. Further each driver defines a
default source rectangle. The center of this rectangle shall align
with the center of the active picture area of the video signal, and
cover what the driver writer considers the complete picture. The
source rectangle is set to the default when the driver is first
loaded, but not later.</P
><P
>The target rectangle is given either by the
<CODE
CLASS="STRUCTFIELD"
>width</CODE
> and <CODE
CLASS="STRUCTFIELD"
>height</CODE
>
fields of struct <A
HREF="#V4L2-PIX-FORMAT"
>v4l2_pix_format</A
> or the <CODE
CLASS="STRUCTFIELD"
>width</CODE
>
and <CODE
CLASS="STRUCTFIELD"
>height</CODE
> fields of the struct <A
HREF="#V4L2-RECT"
>v4l2_rect</A
>
<CODE
CLASS="STRUCTFIELD"
>w</CODE
> substructure of struct <A
HREF="#V4L2-WINDOW"
>v4l2_window</A
>.</P
><P
>In principle cropping and scaling always happens. When the
device supports scaling but not cropping, applications will be unable
to change the cropping rectangle. It remains at the defaults all the
time. When the device supports cropping but not scaling, changing the
image size will also affect the cropping size in order to maintain a
constant scaling factor. The position of the cropping rectangle is
only adjusted to move the rectangle completely inside the capture
window.</P
><P
>When cropping and scaling is supported applications can
change both the source and target rectangle. Various hardware
limitations must be expected, for example discrete scaling factors,
different scaling abilities in horizontal and vertical direction,
limitations of the image size or the cropping alignment. Therefore as
usual drivers adjust the requested parameters against hardware
capabilities and return the actual values selected. An important
difference, because two rectangles are defined, is that the last
rectangle changed shall take priority, and the driver may also adjust
the opposite rectangle.</P
><P
>Suppose scaling is restricted to a factor 1:1 or 2:1 in
either direction and the image size must be a multiple of
16 × 16 pixels. The cropping rectangle be set to the
upper limit, 640 × 400 pixels at offset 0, 0. Let
a video capture application request an image size of
300 × 225 pixels, assuming video will be scaled down
from the "full picture" accordingly. The driver will set the image
size to the closest possible values 304 × 224, then
choose the cropping rectangle closest to the requested size, that is
608 × 224 (224 × 2:1 would exceed the
limit 400). The offset 0, 0 is still valid, thus unmodified.
Given the default cropping rectangle reported by
<CODE
CLASS="CONSTANT"
>VIDIOC_CROPCAP</CODE
> the application can easily propose
another offset to center the cropping rectangle. Now the application may
insist on covering an area using an aspect closer to the original
request. Sheepish it asks for a cropping rectangle of
608 × 456 pixels. The present scaling factors limit
cropping to 640 × 384, so the driver returns the
cropping size 608 × 384 and accordingly adjusts
the image size to 304 × 192.</P
><P
>Eventually some crop or scale parameters are locked, for
example when the driver supports simultaneous video capturing and
overlay, another application already started overlay and the cropping
parameters cannot be changed anymore. Also <A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_TRY_FMT</CODE
></A
> cannot
change the cropping rectangle. In these cases the driver has to
approach the closest values possible without adjusting the opposite
rectangle.</P
><P
>The struct <A
HREF="#V4L2-CROPCAP"
>v4l2_cropcap</A
>, which also reports the pixel aspect ratio,
can be obtained with the <A
HREF="#VIDIOC-CROPCAP"
><CODE
CLASS="CONSTANT"
>VIDIOC_CROPCAP</CODE
></A
> ioctl. To get or set the
current cropping rectangle applications call the <A
HREF="#VIDIOC-G-CROP"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_CROP</CODE
></A
> or
<A
HREF="#VIDIOC-G-CROP"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_CROP</CODE
></A
> ioctl, respectively. All video capture and output
devices must support the <CODE
CLASS="CONSTANT"
>VIDIOC_CROPCAP</CODE
> ioctl.
The <CODE
CLASS="CONSTANT"
>VIDIOC_G_CROP</CODE
> and
<CODE
CLASS="CONSTANT"
>VIDIOC_S_CROP</CODE
> ioctls only when the cropping
rectangle can be changed.</P
><P
>Note as usual the cropping parameters remain unchanged
across closing and reopening a device. Applications should ensure the
parameters are suitable before starting I/O.</P
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN747"
></A
><P
><B
>Example 1-10. Resetting the cropping parameters</B
></P
><P
>(A video capture device is assumed.)</P
><PRE
CLASS="PROGRAMLISTING"
>struct <A
HREF="#V4L2-CROPCAP"
>v4l2_cropcap</A
> cropcap;
struct <A
HREF="#V4L2-CROP"
>v4l2_crop</A
> crop;
memset (&cropcap, 0, sizeof (cropcap));
cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
if (-1 == ioctl (fd, <A
HREF="#VIDIOC-CROPCAP"
><CODE
CLASS="CONSTANT"
>VIDIOC_CROPCAP</CODE
></A
>, &cropcap)) {
perror ("VIDIOC_CROPCAP");
exit (EXIT_FAILURE);
}
memset (&crop, 0, sizeof (crop));
crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
crop.c = cropcap.defrect;
/* Ignore if cropping is not supported (EINVAL) */
if (-1 == ioctl (fd, <A
HREF="#VIDIOC-G-CROP"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_CROP</CODE
></A
>, &crop)
&& errno != EINVAL) {
perror ("VIDIOC_S_CROP");
exit (EXIT_FAILURE);
}
</PRE
></DIV
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN757"
></A
><P
><B
>Example 1-11. Simple downscaling</B
></P
><P
>(A video capture device is assumed.)</P
><PRE
CLASS="PROGRAMLISTING"
>struct <A
HREF="#V4L2-CROPCAP"
>v4l2_cropcap</A
> cropcap;
struct <A
HREF="#V4L2-FORMAT"
>v4l2_format</A
> format;
reset_cropping_parameters ();
/* Scale down to 1/4 size of full picture */
memset (&format, 0, sizeof (format)); /* defaults */
format.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
format.fmt.pix.width = cropcap.defrect.width >> 1;
format.fmt.pix.height = cropcap.defrect.height >> 1;
format.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV;
if (-1 == ioctl (fd, <A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
></A
>, &format)) {
perror ("VIDIOC_S_FORMAT");
exit (EXIT_FAILURE);
}
/* We could check now what we got, the exact scaling factor
or if the driver can scale at all. At mere 2:1 the cropping
rectangle was probably not changed. */
</PRE
></DIV
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN765"
></A
><P
><B
>Example 1-12. Current scaling factor and pixel aspect</B
></P
><P
>(A video capture device is assumed.)</P
><PRE
CLASS="PROGRAMLISTING"
>struct <A
HREF="#V4L2-CROPCAP"
>v4l2_cropcap</A
> cropcap;
struct <A
HREF="#V4L2-CROP"
>v4l2_crop</A
> crop;
struct <A
HREF="#V4L2-FORMAT"
>v4l2_format</A
> format;
double hscale, vscale;
double aspect;
int dwidth, dheight;
memset (&cropcap, 0, sizeof (cropcap));
cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
if (-1 == ioctl (fd, <A
HREF="#VIDIOC-CROPCAP"
><CODE
CLASS="CONSTANT"
>VIDIOC_CROPCAP</CODE
></A
>, &cropcap)) {
perror ("VIDIOC_CROPCAP");
exit (EXIT_FAILURE);
}
memset (&crop, 0, sizeof (crop));
crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
if (-1 == ioctl (fd, <A
HREF="#VIDIOC-G-CROP"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_CROP</CODE
></A
>, &crop)) {
if (errno != EINVAL) {
perror ("VIDIOC_G_CROP");
exit (EXIT_FAILURE);
}
/* Cropping not supported */
crop.c = cropcap.defrect;
}
memset (&format, 0, sizeof (format));
format.fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
if (-1 == ioctl (fd, <A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_FMT</CODE
></A
>, &format)) {
perror ("VIDIOC_G_FMT");
exit (EXIT_FAILURE);
}
hscale = format.fmt.pix.width / (double) crop.c.width;
vscale = format.fmt.pix.height / (double) crop.c.height;
aspect = cropcap.pixelaspect.numerator /
(double) cropcap.pixelaspect.denominator;
aspect = aspect * hscale / vscale;
/* Aspect corrected display size */
dwidth = format.fmt.pix.width / aspect;
dheight = format.fmt.pix.height;
</PRE
></DIV
></DIV
><DIV
CLASS="SECTION"
><HR><H2
CLASS="SECTION"
><A
NAME="STREAMING-PAR"
>1.11. Streaming Parameters</A
></H2
><P
>Streaming parameters are intended to optimize the video
capture process as well as I/O. Presently applications can request a
high quality capture mode with the <A
HREF="#VIDIOC-G-PARM"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_PARM</CODE
></A
> ioctl.</P
><P
>The current video standard determines a nominal number of
frames per second. If less than this number of frames is to be
captured or output, applications can request frame skipping or
duplicating on the driver side. This is espcially useful when using
the <CODE
CLASS="FUNCTION"
>read()</CODE
> or <CODE
CLASS="FUNCTION"
>write()</CODE
>, which
are not augmented by timestamps or sequence counters, and to avoid
uneccessary data copying.</P
><P
>Finally these ioctls can be used to determine the number of
buffers used internally by a driver in read/write mode. For
implications see the section discussing the <A
HREF="#FUNC-READ"
><CODE
CLASS="FUNCTION"
>read()</CODE
></A
>
function.</P
><P
>To get and set the streaming parameters applications call
the <A
HREF="#VIDIOC-G-PARM"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_PARM</CODE
></A
> and <A
HREF="#VIDIOC-G-PARM"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_PARM</CODE
></A
> ioctl, respectively. They take
a pointer to a struct <A
HREF="#V4L2-STREAMPARM"
>v4l2_streamparm</A
>, which contains a union holding
separate parameters for input and output devices.</P
><P
>These ioctls are optional, drivers need not implement
them. If so, they return the <SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code.</P
></DIV
></DIV
><DIV
CLASS="CHAPTER"
><HR><H1
><A
NAME="PIXFMT"
></A
>Chapter 2. Image Formats</H1
><P
>The V4L2 API was primarily designed for devices exchanging
image data with applications. The
<CODE
CLASS="STRUCTNAME"
>v4l2_pix_format</CODE
> structure defines the format
and layout of an image in memory. Image formats are negotiated with
the <A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
></A
> ioctl. (The explanations here focus on video
capturing and output, for overlay frame buffer formats see also
<A
HREF="#VIDIOC-G-FBUF"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_FBUF</CODE
></A
>.)</P
><DIV
CLASS="TABLE"
><A
NAME="V4L2-PIX-FORMAT"
></A
><P
><B
>Table 2-1. struct <CODE
CLASS="STRUCTNAME"
>v4l2_pix_format</CODE
></B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="25%"
TITLE="C1"><COL
WIDTH="25%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>width</CODE
></TD
><TD
>Image width in pixels.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>height</CODE
></TD
><TD
>Image height in pixels.</TD
></TR
><TR
><TD
COLSPAN="3"
>Applications set these fields to
request an image size, drivers return the closest possible values. In
case of planar formats the <CODE
CLASS="STRUCTFIELD"
>width</CODE
> and
<CODE
CLASS="STRUCTFIELD"
>height</CODE
> 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, <CODE
CLASS="STRUCTFIELD"
>width</CODE
> and
<CODE
CLASS="STRUCTFIELD"
>height</CODE
> must be multiples of two.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>pixelformat</CODE
></TD
><TD
>The pixel format or type of compression, set by the
application. This is a little endian <A
HREF="#V4L2-FOURCC"
>four character code</A
>. V4L2 defines
standard RGB formats in <A
HREF="#RGB-FORMATS"
>Table 2-3</A
>, YUV formats in <A
HREF="#YUV-FORMATS"
>Section 2.4</A
>, and reserved codes in <A
HREF="#RESERVED-FORMATS"
>Table 2-4</A
></TD
></TR
><TR
><TD
>enum <A
HREF="#V4L2-FIELD"
>v4l2_field</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>field</CODE
></TD
><TD
>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 <A
HREF="#FIELD-ORDER"
>Section 3.6</A
>.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>bytesperline</CODE
></TD
><TD
>Distance in bytes between the leftmost pixels in two
adjacent lines.</TD
></TR
><TR
><TD
COLSPAN="3"
><P
>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 <CODE
CLASS="STRUCTFIELD"
>width</CODE
> 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.</P
><P
>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.</P
><P
>When the image format is planar the
<CODE
CLASS="STRUCTFIELD"
>bytesperline</CODE
> value applies to the largest
plane and is divided by the same factor as the
<CODE
CLASS="STRUCTFIELD"
>width</CODE
> 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 <CODE
CLASS="STRUCTFIELD"
>bytesperline</CODE
> value
rounded up to a multiple of the scale factor.</P
></TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>sizeimage</CODE
></TD
><TD
>Size in bytes of the buffer to hold a complete image,
set by the driver. Usually this is
<CODE
CLASS="STRUCTFIELD"
>bytesperline</CODE
> times
<CODE
CLASS="STRUCTFIELD"
>height</CODE
>. When the image consists of variable
length compressed data this is the maximum number of bytes required to
hold an image.</TD
></TR
><TR
><TD
>enum <A
HREF="#V4L2-COLORSPACE"
>v4l2_colorspace</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>colorspace</CODE
></TD
><TD
>This information supplements the
<CODE
CLASS="STRUCTFIELD"
>pixelformat</CODE
> and must be set by the driver,
see <A
HREF="#COLORSPACES"
>Section 2.2</A
>.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>priv</CODE
></TD
><TD
>Reserved for custom (driver defined) additional
information about formats. When not used drivers and applications must
set this field to zero.</TD
></TR
></TBODY
></TABLE
></DIV
><DIV
CLASS="SECTION"
><HR><H2
CLASS="SECTION"
><A
NAME="AEN880"
>2.1. Standard Image Formats</A
></H2
><P
>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.</P
><P
>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.</P
><P
>Even so, ultimately, some standard formats are needed, so
the V4L2 specification would not be complete without well-defined
standard formats.</P
><P
>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.</P
><P
>In V4L2 each format has an identifier which looks like
<CODE
CLASS="CONSTANT"
>PIX_FMT_XXX</CODE
>, defined in the <A
HREF="#VIDEODEV"
>videodev.h</A
> header file. These identifiers
represent <A
HREF="#V4L2-FOURCC"
>four character codes</A
>
which are also listed below, however they are not the same as those
used in the Windows world.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H2
CLASS="SECTION"
><A
NAME="COLORSPACES"
>2.2. Colorspaces</A
></H2
><P
>[intro]</P
><P
> <P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Gamma Correction</DT
><DD
><P
>[to do]</P
><P
>E'<SUB
>R</SUB
> = f(R)</P
><P
>E'<SUB
>G</SUB
> = f(G)</P
><P
>E'<SUB
>B</SUB
> = f(B)</P
></DD
><DT
>Construction of luminance and color-difference
signals</DT
><DD
><P
>[to do]</P
><P
>E'<SUB
>Y</SUB
> =
Coeff<SUB
>R</SUB
> E'<SUB
>R</SUB
>
+ Coeff<SUB
>G</SUB
> E'<SUB
>G</SUB
>
+ Coeff<SUB
>B</SUB
> E'<SUB
>B</SUB
></P
><P
>(E'<SUB
>R</SUB
> - E'<SUB
>Y</SUB
>) = E'<SUB
>R</SUB
>
- Coeff<SUB
>R</SUB
> E'<SUB
>R</SUB
>
- Coeff<SUB
>G</SUB
> E'<SUB
>G</SUB
>
- Coeff<SUB
>B</SUB
> E'<SUB
>B</SUB
></P
><P
>(E'<SUB
>B</SUB
> - E'<SUB
>Y</SUB
>) = E'<SUB
>B</SUB
>
- Coeff<SUB
>R</SUB
> E'<SUB
>R</SUB
>
- Coeff<SUB
>G</SUB
> E'<SUB
>G</SUB
>
- Coeff<SUB
>B</SUB
> E'<SUB
>B</SUB
></P
></DD
><DT
>Re-normalized color-difference signals</DT
><DD
><P
>The color-difference signals are scaled back to unity
range [-0.5;+0.5]:</P
><P
>K<SUB
>B</SUB
> = 0.5 / (1 - Coeff<SUB
>B</SUB
>)</P
><P
>K<SUB
>R</SUB
> = 0.5 / (1 - Coeff<SUB
>R</SUB
>)</P
><P
>P<SUB
>B</SUB
> =
K<SUB
>B</SUB
> (E'<SUB
>B</SUB
> - E'<SUB
>Y</SUB
>) =
0.5 (Coeff<SUB
>R</SUB
> / Coeff<SUB
>B</SUB
>) E'<SUB
>R</SUB
>
+ 0.5 (Coeff<SUB
>G</SUB
> / Coeff<SUB
>B</SUB
>) E'<SUB
>G</SUB
>
+ 0.5 E'<SUB
>B</SUB
></P
><P
>P<SUB
>R</SUB
> =
K<SUB
>R</SUB
> (E'<SUB
>R</SUB
> - E'<SUB
>Y</SUB
>) =
0.5 E'<SUB
>R</SUB
>
+ 0.5 (Coeff<SUB
>G</SUB
> / Coeff<SUB
>R</SUB
>) E'<SUB
>G</SUB
>
+ 0.5 (Coeff<SUB
>B</SUB
> / Coeff<SUB
>R</SUB
>) E'<SUB
>B</SUB
></P
></DD
><DT
>Quantization</DT
><DD
><P
>[to do]</P
><P
>Y' = (Lum. Levels - 1) · E'<SUB
>Y</SUB
> + Lum. Offset</P
><P
>C<SUB
>B</SUB
> = (Chrom. Levels - 1)
· P<SUB
>B</SUB
> + Chrom. Offset</P
><P
>C<SUB
>R</SUB
> = (Chrom. Levels - 1)
· P<SUB
>R</SUB
> + Chrom. Offset</P
><P
>Rounding to the nearest integer and clamping to the range
[0;255] finally yields the digital color components Y'CbCr
stored in YUV images.</P
></DD
></DL
></DIV
>
</P
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN984"
></A
><P
><B
>Example 2-1. ITU-R Rec. BT.601 color conversion</B
></P
><P
>Forward Transformation</P
><PRE
CLASS="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 < 0) return 0;
else if (r > 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);
</PRE
><P
>Inverse Transformation</P
><PRE
CLASS="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 < 0) return 0;
else if (r > 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);
</PRE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="V4L2-COLORSPACE"
></A
><P
><B
>Table 2-2. enum v4l2_colorspace</B
></P
><TABLE
BORDER="1"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="9%"
ALIGN="LEFT"><COL
WIDTH="9%"
ALIGN="CENTER"><COL
WIDTH="9%"
ALIGN="LEFT"><COL
WIDTH="9%"
TITLE="CR"><COL
WIDTH="9%"
TITLE="CG"><COL
WIDTH="9%"
TITLE="CB"><COL
WIDTH="9%"
TITLE="WP"><COL
WIDTH="9%"
TITLE="GC"><COL
WIDTH="9%"
TITLE="LUM"><COL
WIDTH="9%"
TITLE="QY"><COL
WIDTH="9%"
TITLE="QC"><THEAD
><TR
><TH
ROWSPAN="2"
>Identifier</TH
><TH
ROWSPAN="2"
>Value</TH
><TH
ROWSPAN="2"
>Description</TH
><TH
COLSPAN="3"
>Chromaticities<A
NAME="AEN1013"
HREF="#FTN.AEN1013"
><SPAN
CLASS="footnote"
>[a]</SPAN
></A
></TH
><TH
ROWSPAN="2"
>White Point</TH
><TH
ROWSPAN="2"
>Gamma Correction</TH
><TH
ROWSPAN="2"
>Luminance E'<SUB
>Y</SUB
></TH
><TH
COLSPAN="2"
>Quantization</TH
></TR
><TR
><TH
>Red</TH
><TH
>Green</TH
><TH
>Blue</TH
><TH
>Y'</TH
><TH
>Cb, Cr</TH
></TR
></THEAD
><TBODY
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_COLORSPACE_SMPTE170M</CODE
></TD
><TD
>1</TD
><TD
>NTSC/PAL according to <A
HREF="#SMPTE170M"
><ABBR
CLASS="ABBREV"
>SMPTE170M</ABBR
></A
>,
<A
HREF="#ITU601"
><ABBR
CLASS="ABBREV"
>ITU601</ABBR
></A
></TD
><TD
>x = 0.630, y = 0.340</TD
><TD
>x = 0.310, y = 0.595</TD
><TD
>x = 0.155, y = 0.070</TD
><TD
>x = 0.3127, y = 0.3290,
Illuminant D<SUB
>65</SUB
></TD
><TD
>E' = 4.5 I for I ≤0.018,
1.099 I<SUP
>0.45</SUP
> - 0.099 for 0.018 < I</TD
><TD
>0.299 E'<SUB
>R</SUB
>
+ 0.587 E'<SUB
>G</SUB
>
+ 0.114 E'<SUB
>B</SUB
></TD
><TD
>219 E'<SUB
>Y</SUB
> + 16</TD
><TD
>224 P<SUB
>B,R</SUB
> + 128</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_COLORSPACE_SMPTE240M</CODE
></TD
><TD
>2</TD
><TD
>1125-Line (US) HDTV, see <A
HREF="#SMPTE240M"
><ABBR
CLASS="ABBREV"
>SMPTE240M</ABBR
></A
></TD
><TD
>x = 0.630, y = 0.340</TD
><TD
>x = 0.310, y = 0.595</TD
><TD
>x = 0.155, y = 0.070</TD
><TD
>x = 0.3127, y = 0.3290,
Illuminant D<SUB
>65</SUB
></TD
><TD
>E' = 4 I for I ≤0.0228,
1.1115 I<SUP
>0.45</SUP
> - 0.1115 for 0.0228 < I</TD
><TD
>0.212 E'<SUB
>R</SUB
>
+ 0.701 E'<SUB
>G</SUB
>
+ 0.087 E'<SUB
>B</SUB
></TD
><TD
>219 E'<SUB
>Y</SUB
> + 16</TD
><TD
>224 P<SUB
>B,R</SUB
> + 128</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_COLORSPACE_REC709</CODE
></TD
><TD
>3</TD
><TD
>HDTV and modern devices, see <A
HREF="#ITU709"
><ABBR
CLASS="ABBREV"
>ITU709</ABBR
></A
></TD
><TD
>x = 0.640, y = 0.330</TD
><TD
>x = 0.300, y = 0.600</TD
><TD
>x = 0.150, y = 0.060</TD
><TD
>x = 0.3127, y = 0.3290,
Illuminant D<SUB
>65</SUB
></TD
><TD
>E' = 4.5 I for I ≤0.018,
1.099 I<SUP
>0.45</SUP
> - 0.099 for 0.018 < I</TD
><TD
>0.2125 E'<SUB
>R</SUB
>
+ 0.7154 E'<SUB
>G</SUB
>
+ 0.0721 E'<SUB
>B</SUB
></TD
><TD
>219 E'<SUB
>Y</SUB
> + 16</TD
><TD
>224 P<SUB
>B,R</SUB
> + 128</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_COLORSPACE_BT878</CODE
></TD
><TD
>4</TD
><TD
>Broken Bt878 extents<A
NAME="AEN1096"
HREF="#FTN.AEN1096"
><SPAN
CLASS="footnote"
>[b]</SPAN
></A
>, <A
HREF="#ITU601"
><ABBR
CLASS="ABBREV"
>ITU601</ABBR
></A
></TD
><TD
>?</TD
><TD
>?</TD
><TD
>?</TD
><TD
>?</TD
><TD
>?</TD
><TD
>0.299 E'<SUB
>R</SUB
>
+ 0.587 E'<SUB
>G</SUB
>
+ 0.114 E'<SUB
>B</SUB
></TD
><TD
><SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>237</I
></SPAN
> E'<SUB
>Y</SUB
> + 16</TD
><TD
>224 P<SUB
>B,R</SUB
> + 128 (probably)</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_COLORSPACE_470_SYSTEM_M</CODE
></TD
><TD
>5</TD
><TD
>M/NTSC<A
NAME="AEN1119"
HREF="#FTN.AEN1119"
><SPAN
CLASS="footnote"
>[c]</SPAN
></A
> according to <A
HREF="#ITU470"
><ABBR
CLASS="ABBREV"
>ITU470</ABBR
></A
>, <A
HREF="#ITU601"
><ABBR
CLASS="ABBREV"
>ITU601</ABBR
></A
></TD
><TD
>x = 0.67, y = 0.33</TD
><TD
>x = 0.21, y = 0.71</TD
><TD
>x = 0.14, y = 0.08</TD
><TD
>x = 0.310, y = 0.316, Illuminant C</TD
><TD
>?</TD
><TD
>0.299 E'<SUB
>R</SUB
>
+ 0.587 E'<SUB
>G</SUB
>
+ 0.114 E'<SUB
>B</SUB
></TD
><TD
>219 E'<SUB
>Y</SUB
> + 16</TD
><TD
>224 P<SUB
>B,R</SUB
> + 128</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_COLORSPACE_470_SYSTEM_BG</CODE
></TD
><TD
>6</TD
><TD
>625-line PAL and SECAM systems according to <A
HREF="#ITU470"
><ABBR
CLASS="ABBREV"
>ITU470</ABBR
></A
>, <A
HREF="#ITU601"
><ABBR
CLASS="ABBREV"
>ITU601</ABBR
></A
></TD
><TD
>x = 0.64, y = 0.33</TD
><TD
>x = 0.29, y = 0.60</TD
><TD
>x = 0.15, y = 0.06</TD
><TD
>x = 0.313, y = 0.329,
Illuminant D<SUB
>65</SUB
></TD
><TD
>?</TD
><TD
>0.299 E'<SUB
>R</SUB
>
+ 0.587 E'<SUB
>G</SUB
>
+ 0.114 E'<SUB
>B</SUB
></TD
><TD
>219 E'<SUB
>Y</SUB
> + 16</TD
><TD
>224 P<SUB
>B,R</SUB
> + 128</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_COLORSPACE_JPEG</CODE
></TD
><TD
>7</TD
><TD
>JPEG Y'CbCr, see <A
HREF="#JFIF"
><ABBR
CLASS="ABBREV"
>JFIF</ABBR
></A
>, <A
HREF="#ITU601"
><ABBR
CLASS="ABBREV"
>ITU601</ABBR
></A
></TD
><TD
>?</TD
><TD
>?</TD
><TD
>?</TD
><TD
>?</TD
><TD
>?</TD
><TD
>0.299 E'<SUB
>R</SUB
>
+ 0.587 E'<SUB
>G</SUB
>
+ 0.114 E'<SUB
>B</SUB
></TD
><TD
>256 E'<SUB
>Y</SUB
> + 16<A
NAME="AEN1175"
HREF="#FTN.AEN1175"
><SPAN
CLASS="footnote"
>[d]</SPAN
></A
></TD
><TD
>256 P<SUB
>B,R</SUB
> + 128</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_COLORSPACE_SRGB</CODE
></TD
><TD
>8</TD
><TD
>[?]</TD
><TD
>x = 0.640, y = 0.330</TD
><TD
>x = 0.300, y = 0.600</TD
><TD
>x = 0.150, y = 0.060</TD
><TD
>x = 0.3127, y = 0.3290,
Illuminant D<SUB
>65</SUB
></TD
><TD
>E' = 4.5 I for I ≤0.018,
1.099 I<SUP
>0.45</SUP
> - 0.099 for 0.018 < I</TD
><TD
COLSPAN="3"
>n/a</TD
></TR
></TBODY
><TR
><TD
COLSPAN="11"
>Notes:<BR><A
NAME="FTN.AEN1013"
>a. </A
>The coordinates of the color primaries are
given in the CIE system (1931)<BR><A
NAME="FTN.AEN1096"
>b. </A
>The ubiquitous Bt878 video capture chip
quantizes E'<SUB
>Y</SUB
> to 238 levels, yielding a range
of Y' = 16 … 253, unlike Rec. 601 Y' = 16 …
235. This is not a typo in the Bt878 documentation, it has been
implemented in silicon. The chroma extents are unclear.<BR><A
NAME="FTN.AEN1119"
>c. </A
>No identifier exists for M/PAL which uses
the chromaticities of M/NTSC, the remaining parameters are equal to B and
G/PAL.<BR><A
NAME="FTN.AEN1175"
>d. </A
>Note JFIF quantizes
Y'P<SUB
>B</SUB
>P<SUB
>R</SUB
> in range [0;+1] and
[-0.5;+0.5] to <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>257</I
></SPAN
> levels, however Y'CbCr signals
are still clamped to [0;255].<BR></TD
></TR
></TABLE
></DIV
></DIV
><DIV
CLASS="SECTION"
><HR><H2
CLASS="SECTION"
><A
NAME="PIXFMT-RGB"
>2.3. RGB Formats</A
></H2
><P
>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.</P
><P
>When one of these formats is used, drivers shall report the
colorspace <CODE
CLASS="CONSTANT"
>V4L2_COLORSPACE_SRGB</CODE
>.</P
><DIV
CLASS="TABLE"
><A
NAME="RGB-FORMATS"
></A
><P
><B
>Table 2-3. Packed RGB Image Formats</B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="9%"
ALIGN="LEFT"
TITLE="ID"><COL
WIDTH="9%"
TITLE="FOURCC"><COL
WIDTH="9%"
TITLE="BIT"><COL
WIDTH="9%"
TITLE="B07"><COL><COL><COL><COL><COL><COL><COL
WIDTH="9%"
TITLE="B00"><COL><COL
WIDTH="9%"
TITLE="B17"><COL><COL><COL><COL><COL><COL><COL
WIDTH="9%"
TITLE="B10"><COL><COL
WIDTH="9%"
TITLE="B27"><COL><COL><COL><COL><COL><COL><COL
WIDTH="9%"
TITLE="B20"><COL><COL
WIDTH="9%"
TITLE="B37"><COL><COL><COL><COL><COL><COL><THEAD
><TR
><TH
ROWSPAN="2"
>Identifier</TH
><TH
ROWSPAN="2"
>Code</TH
><TH
> </TH
><TH
COLSPAN="8"
>Byte 0</TH
><TH
> </TH
><TH
COLSPAN="8"
>Byte 1</TH
><TH
> </TH
><TH
COLSPAN="8"
>Byte 2</TH
><TH
> </TH
><TH
COLSPAN="8"
>Byte 3</TH
></TR
><TR
><TH
>Bit</TH
><TH
>7</TH
><TH
>6</TH
><TH
>5</TH
><TH
>4</TH
><TH
>3</TH
><TH
>2</TH
><TH
>1</TH
><TH
>0</TH
><TH
> </TH
><TH
>7</TH
><TH
>6</TH
><TH
>5</TH
><TH
>4</TH
><TH
>3</TH
><TH
>2</TH
><TH
>1</TH
><TH
>0</TH
><TH
> </TH
><TH
>7</TH
><TH
>6</TH
><TH
>5</TH
><TH
>4</TH
><TH
>3</TH
><TH
>2</TH
><TH
>1</TH
><TH
>0</TH
><TH
> </TH
><TH
>7</TH
><TH
>6</TH
><TH
>5</TH
><TH
>4</TH
><TH
>3</TH
><TH
>2</TH
><TH
>1</TH
><TH
>0</TH
></TR
></THEAD
><TBODY
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_RGB332</CODE
></TD
><TD
>'RGB1'</TD
><TD
> </TD
><TD
>b<SUB
>1</SUB
></TD
><TD
>b<SUB
>0</SUB
></TD
><TD
>g<SUB
>2</SUB
></TD
><TD
>g<SUB
>1</SUB
></TD
><TD
>g<SUB
>0</SUB
></TD
><TD
>r<SUB
>2</SUB
></TD
><TD
>r<SUB
>1</SUB
></TD
><TD
>r<SUB
>0</SUB
></TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_RGB555</CODE
></TD
><TD
>'RGBO'</TD
><TD
> </TD
><TD
>g<SUB
>2</SUB
></TD
><TD
>g<SUB
>1</SUB
></TD
><TD
>g<SUB
>0</SUB
></TD
><TD
>r<SUB
>4</SUB
></TD
><TD
>r<SUB
>3</SUB
></TD
><TD
>r<SUB
>2</SUB
></TD
><TD
>r<SUB
>1</SUB
></TD
><TD
>r<SUB
>0</SUB
></TD
><TD
> </TD
><TD
>?</TD
><TD
>b<SUB
>4</SUB
></TD
><TD
>b<SUB
>3</SUB
></TD
><TD
>b<SUB
>2</SUB
></TD
><TD
>b<SUB
>1</SUB
></TD
><TD
>b<SUB
>0</SUB
></TD
><TD
>g<SUB
>4</SUB
></TD
><TD
>g<SUB
>3</SUB
></TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_RGB565</CODE
></TD
><TD
>'RGBP'</TD
><TD
> </TD
><TD
>g<SUB
>2</SUB
></TD
><TD
>g<SUB
>1</SUB
></TD
><TD
>g<SUB
>0</SUB
></TD
><TD
>r<SUB
>4</SUB
></TD
><TD
>r<SUB
>3</SUB
></TD
><TD
>r<SUB
>2</SUB
></TD
><TD
>r<SUB
>1</SUB
></TD
><TD
>r<SUB
>0</SUB
></TD
><TD
> </TD
><TD
>b<SUB
>4</SUB
></TD
><TD
>b<SUB
>3</SUB
></TD
><TD
>b<SUB
>2</SUB
></TD
><TD
>b<SUB
>1</SUB
></TD
><TD
>b<SUB
>0</SUB
></TD
><TD
>g<SUB
>5</SUB
></TD
><TD
>g<SUB
>4</SUB
></TD
><TD
>g<SUB
>3</SUB
></TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_RGB555X</CODE
></TD
><TD
>'RGBQ'</TD
><TD
> </TD
><TD
>?</TD
><TD
>b<SUB
>4</SUB
></TD
><TD
>b<SUB
>3</SUB
></TD
><TD
>b<SUB
>2</SUB
></TD
><TD
>b<SUB
>1</SUB
></TD
><TD
>b<SUB
>0</SUB
></TD
><TD
>g<SUB
>4</SUB
></TD
><TD
>g<SUB
>3</SUB
></TD
><TD
> </TD
><TD
>g<SUB
>2</SUB
></TD
><TD
>g<SUB
>1</SUB
></TD
><TD
>g<SUB
>0</SUB
></TD
><TD
>r<SUB
>4</SUB
></TD
><TD
>r<SUB
>3</SUB
></TD
><TD
>r<SUB
>2</SUB
></TD
><TD
>r<SUB
>1</SUB
></TD
><TD
>r<SUB
>0</SUB
></TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_RGB565X</CODE
></TD
><TD
>'RGBR'</TD
><TD
> </TD
><TD
>b<SUB
>4</SUB
></TD
><TD
>b<SUB
>3</SUB
></TD
><TD
>b<SUB
>2</SUB
></TD
><TD
>b<SUB
>1</SUB
></TD
><TD
>b<SUB
>0</SUB
></TD
><TD
>g<SUB
>5</SUB
></TD
><TD
>g<SUB
>4</SUB
></TD
><TD
>g<SUB
>3</SUB
></TD
><TD
> </TD
><TD
>g<SUB
>2</SUB
></TD
><TD
>g<SUB
>1</SUB
></TD
><TD
>g<SUB
>0</SUB
></TD
><TD
>r<SUB
>4</SUB
></TD
><TD
>r<SUB
>3</SUB
></TD
><TD
>r<SUB
>2</SUB
></TD
><TD
>r<SUB
>1</SUB
></TD
><TD
>r<SUB
>0</SUB
></TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_BGR24</CODE
></TD
><TD
>'BGR3'</TD
><TD
> </TD
><TD
>b<SUB
>7</SUB
></TD
><TD
>b<SUB
>6</SUB
></TD
><TD
>b<SUB
>5</SUB
></TD
><TD
>b<SUB
>4</SUB
></TD
><TD
>b<SUB
>3</SUB
></TD
><TD
>b<SUB
>2</SUB
></TD
><TD
>b<SUB
>1</SUB
></TD
><TD
>b<SUB
>0</SUB
></TD
><TD
> </TD
><TD
>g<SUB
>7</SUB
></TD
><TD
>g<SUB
>6</SUB
></TD
><TD
>g<SUB
>5</SUB
></TD
><TD
>g<SUB
>4</SUB
></TD
><TD
>g<SUB
>3</SUB
></TD
><TD
>g<SUB
>2</SUB
></TD
><TD
>g<SUB
>1</SUB
></TD
><TD
>g<SUB
>0</SUB
></TD
><TD
> </TD
><TD
>r<SUB
>7</SUB
></TD
><TD
>r<SUB
>6</SUB
></TD
><TD
>r<SUB
>5</SUB
></TD
><TD
>r<SUB
>4</SUB
></TD
><TD
>r<SUB
>3</SUB
></TD
><TD
>r<SUB
>2</SUB
></TD
><TD
>r<SUB
>1</SUB
></TD
><TD
>r<SUB
>0</SUB
></TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_RGB24</CODE
></TD
><TD
>'RGB3'</TD
><TD
> </TD
><TD
>r<SUB
>7</SUB
></TD
><TD
>r<SUB
>6</SUB
></TD
><TD
>r<SUB
>5</SUB
></TD
><TD
>r<SUB
>4</SUB
></TD
><TD
>r<SUB
>3</SUB
></TD
><TD
>r<SUB
>2</SUB
></TD
><TD
>r<SUB
>1</SUB
></TD
><TD
>r<SUB
>0</SUB
></TD
><TD
> </TD
><TD
>g<SUB
>7</SUB
></TD
><TD
>g<SUB
>6</SUB
></TD
><TD
>g<SUB
>5</SUB
></TD
><TD
>g<SUB
>4</SUB
></TD
><TD
>g<SUB
>3</SUB
></TD
><TD
>g<SUB
>2</SUB
></TD
><TD
>g<SUB
>1</SUB
></TD
><TD
>g<SUB
>0</SUB
></TD
><TD
> </TD
><TD
>b<SUB
>7</SUB
></TD
><TD
>b<SUB
>6</SUB
></TD
><TD
>b<SUB
>5</SUB
></TD
><TD
>b<SUB
>4</SUB
></TD
><TD
>b<SUB
>3</SUB
></TD
><TD
>b<SUB
>2</SUB
></TD
><TD
>b<SUB
>1</SUB
></TD
><TD
>b<SUB
>0</SUB
></TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_BGR32</CODE
></TD
><TD
>'BGR4'</TD
><TD
> </TD
><TD
>b<SUB
>7</SUB
></TD
><TD
>b<SUB
>6</SUB
></TD
><TD
>b<SUB
>5</SUB
></TD
><TD
>b<SUB
>4</SUB
></TD
><TD
>b<SUB
>3</SUB
></TD
><TD
>b<SUB
>2</SUB
></TD
><TD
>b<SUB
>1</SUB
></TD
><TD
>b<SUB
>0</SUB
></TD
><TD
> </TD
><TD
>g<SUB
>7</SUB
></TD
><TD
>g<SUB
>6</SUB
></TD
><TD
>g<SUB
>5</SUB
></TD
><TD
>g<SUB
>4</SUB
></TD
><TD
>g<SUB
>3</SUB
></TD
><TD
>g<SUB
>2</SUB
></TD
><TD
>g<SUB
>1</SUB
></TD
><TD
>g<SUB
>0</SUB
></TD
><TD
> </TD
><TD
>r<SUB
>7</SUB
></TD
><TD
>r<SUB
>6</SUB
></TD
><TD
>r<SUB
>5</SUB
></TD
><TD
>r<SUB
>4</SUB
></TD
><TD
>r<SUB
>3</SUB
></TD
><TD
>r<SUB
>2</SUB
></TD
><TD
>r<SUB
>1</SUB
></TD
><TD
>r<SUB
>0</SUB
></TD
><TD
> </TD
><TD
>?</TD
><TD
>?</TD
><TD
>?</TD
><TD
>?</TD
><TD
>?</TD
><TD
>?</TD
><TD
>?</TD
><TD
>?</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_RGB32</CODE
></TD
><TD
>'RGB4'</TD
><TD
> </TD
><TD
>r<SUB
>7</SUB
></TD
><TD
>r<SUB
>6</SUB
></TD
><TD
>r<SUB
>5</SUB
></TD
><TD
>r<SUB
>4</SUB
></TD
><TD
>r<SUB
>3</SUB
></TD
><TD
>r<SUB
>2</SUB
></TD
><TD
>r<SUB
>1</SUB
></TD
><TD
>r<SUB
>0</SUB
></TD
><TD
> </TD
><TD
>g<SUB
>7</SUB
></TD
><TD
>g<SUB
>6</SUB
></TD
><TD
>g<SUB
>5</SUB
></TD
><TD
>g<SUB
>4</SUB
></TD
><TD
>g<SUB
>3</SUB
></TD
><TD
>g<SUB
>2</SUB
></TD
><TD
>g<SUB
>1</SUB
></TD
><TD
>g<SUB
>0</SUB
></TD
><TD
> </TD
><TD
>b<SUB
>7</SUB
></TD
><TD
>b<SUB
>6</SUB
></TD
><TD
>b<SUB
>5</SUB
></TD
><TD
>b<SUB
>4</SUB
></TD
><TD
>b<SUB
>3</SUB
></TD
><TD
>b<SUB
>2</SUB
></TD
><TD
>b<SUB
>1</SUB
></TD
><TD
>b<SUB
>0</SUB
></TD
><TD
> </TD
><TD
>?</TD
><TD
>?</TD
><TD
>?</TD
><TD
>?</TD
><TD
>?</TD
><TD
>?</TD
><TD
>?</TD
><TD
>?</TD
></TR
></TBODY
></TABLE
></DIV
><P
>Bit 7 is the most significant bit. ? = undefined bit,
ignored on output, random value on input.</P
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN1675"
></A
><P
><B
>Example 2-2. <CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_BGR24</CODE
> 4 × 4 pixel
image</B
></P
><DIV
CLASS="FORMALPARA"
><P
><B
>Byte Order. </B
>Each cell is one byte.
<DIV
CLASS="INFORMALTABLE"
><P
></P
><A
NAME="AEN1681"
></A
><TABLE
BORDER="0"
FRAME="void"
CLASS="CALSTABLE"
><COL
WIDTH="2*"
ALIGN="LEFT"><COL><COL><COL><COL><COL><COL><COL><COL><COL><COL><COL><COL><TBODY
><TR
><TD
>start + 0:</TD
><TD
>B<SUB
>00</SUB
></TD
><TD
>G<SUB
>00</SUB
></TD
><TD
>R<SUB
>00</SUB
></TD
><TD
>B<SUB
>01</SUB
></TD
><TD
>G<SUB
>01</SUB
></TD
><TD
>R<SUB
>01</SUB
></TD
><TD
>B<SUB
>02</SUB
></TD
><TD
>G<SUB
>02</SUB
></TD
><TD
>R<SUB
>02</SUB
></TD
><TD
>B<SUB
>03</SUB
></TD
><TD
>G<SUB
>03</SUB
></TD
><TD
>R<SUB
>03</SUB
></TD
></TR
><TR
><TD
>start + 12:</TD
><TD
>B<SUB
>10</SUB
></TD
><TD
>G<SUB
>10</SUB
></TD
><TD
>R<SUB
>10</SUB
></TD
><TD
>B<SUB
>11</SUB
></TD
><TD
>G<SUB
>11</SUB
></TD
><TD
>R<SUB
>11</SUB
></TD
><TD
>B<SUB
>12</SUB
></TD
><TD
>G<SUB
>12</SUB
></TD
><TD
>R<SUB
>12</SUB
></TD
><TD
>B<SUB
>13</SUB
></TD
><TD
>G<SUB
>13</SUB
></TD
><TD
>R<SUB
>13</SUB
></TD
></TR
><TR
><TD
>start + 24:</TD
><TD
>B<SUB
>20</SUB
></TD
><TD
>G<SUB
>20</SUB
></TD
><TD
>R<SUB
>20</SUB
></TD
><TD
>B<SUB
>21</SUB
></TD
><TD
>G<SUB
>21</SUB
></TD
><TD
>R<SUB
>21</SUB
></TD
><TD
>B<SUB
>22</SUB
></TD
><TD
>G<SUB
>22</SUB
></TD
><TD
>R<SUB
>22</SUB
></TD
><TD
>B<SUB
>23</SUB
></TD
><TD
>G<SUB
>23</SUB
></TD
><TD
>R<SUB
>23</SUB
></TD
></TR
><TR
><TD
>start + 36:</TD
><TD
>B<SUB
>30</SUB
></TD
><TD
>G<SUB
>30</SUB
></TD
><TD
>R<SUB
>30</SUB
></TD
><TD
>B<SUB
>31</SUB
></TD
><TD
>G<SUB
>31</SUB
></TD
><TD
>R<SUB
>31</SUB
></TD
><TD
>B<SUB
>32</SUB
></TD
><TD
>G<SUB
>32</SUB
></TD
><TD
>R<SUB
>32</SUB
></TD
><TD
>B<SUB
>33</SUB
></TD
><TD
>G<SUB
>33</SUB
></TD
><TD
>R<SUB
>33</SUB
></TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
>
</P
></DIV
></DIV
><DIV
CLASS="IMPORTANT"
><BLOCKQUOTE
CLASS="IMPORTANT"
><P
><B
>Important: </B
>Drivers may interpret these formats differently.</P
><P
>The <CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_RGB555</CODE
>,
<CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_RGB565</CODE
>,
<CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_RGB555X</CODE
> and
<CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_RGB565X</CODE
> formats are uncommon. Video
and display hardware typically supports variants with reversed order
of color components, i. e. blue towards the least, red towards the most
significant bit. Although presumably the original authors had the
common formats in mind, the definitions were always very clear and
cannot be simply regarded as erroneous.</P
><P
>If <CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_RGB332</CODE
> has been
chosen in accordance with the 15 and 16 bit formats, this format might
as well be interpreted differently, as "rrrgggbb" rather than
"bbgggrrr".</P
><P
>Finally some drivers, most prominently the BTTV driver,
might interpret <CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_RGB32</CODE
> as the
big-endian variant of <CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_BGR32</CODE
>,
consisting of bytes "?RGB" in memory. V4L2 never defined such a
format, lack of a <CODE
CLASS="CONSTANT"
>X</CODE
> suffix to the symbol suggests
it was intended this way, and a new symbol and four character code
should have been used instead.</P
><P
>Until these issues are solved, application writers are
advised that drivers might interpret these formats either way.</P
></BLOCKQUOTE
></DIV
></DIV
><DIV
CLASS="SECTION"
><HR><H2
CLASS="SECTION"
><A
NAME="YUV-FORMATS"
>2.4. YUV Formats</A
></H2
><DIV
CLASS="TOC"
><DL
><DT
><B
>Table of Contents</B
></DT
><DT
><A
HREF="#PIXFMT-GREY"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_GREY</CODE
></A
> -- Grey-scale image.</DT
><DT
><A
HREF="#PIXFMT-YUYV"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YUYV</CODE
></A
> -- Packed format with ½ horizontal chroma
resolution, also known as YUV 4:2:2.</DT
><DT
><A
HREF="#PIXFMT-UYVY"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_UYVY</CODE
></A
> -- Variation of
<CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YUYV</CODE
> with different order of samples
in memory.</DT
><DT
><A
HREF="#PIXFMT-Y41P"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_Y41P</CODE
></A
> -- Packed format with ¼ horizontal chroma
resolution, also known as YUV 4:1:1.</DT
><DT
><A
HREF="#PIXFMT-YVU420"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YVU420</CODE
>,
<CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YUV420</CODE
></A
> -- Planar formats with ½ horizontal and
vertical chroma resolution, also known as YUV 4:2:0.</DT
><DT
><A
HREF="#PIXFMT-YVU410"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YVU410</CODE
>,
<CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YUV410</CODE
></A
> -- Planar formats with ¼ horizontal and
vertical chroma resolution, also known as YUV 4:1:0.</DT
><DT
><A
HREF="#PIXFMT-YUV422P"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YUV422P</CODE
></A
> -- Format with ½ horizontal chroma resolution,
also known as YUV 4:2:2. Planar layout as opposed to
<CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YUYV</CODE
>.</DT
><DT
><A
HREF="#PIXFMT-YUV411P"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YUV411P</CODE
></A
> -- Format with ¼ horizontal chroma resolution,
also known as YUV 4:1:1. Planar layout as opposed to
<CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_Y41P</CODE
>.</DT
><DT
><A
HREF="#AEN3002"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_NV12</CODE
>,
<CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_NV21</CODE
></A
> -- Formats with ½ 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
<CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YVU420</CODE
>.</DT
></DL
></DIV
><P
>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 <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>color difference</I
></SPAN
> signals, this way
the green component can be reconstructed by subtracting from the
brightness component. See <A
HREF="#COLORSPACES"
>Section 2.2</A
> 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.</P
><H1
><A
NAME="PIXFMT-GREY"
></A
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_GREY</CODE
></H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN1812"
></A
><H2
>Name</H2
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_GREY</CODE
> ('GREY') -- Grey-scale image.</DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN1816"
></A
><H2
>Description</H2
><P
>This is a grey-scale image. It is really a degenerate
Y'CbCr format which simply contains no Cb or Cr data.</P
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN1819"
></A
><P
><B
>Example 2-1. <CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_GREY</CODE
> 4 × 4
pixel image</B
></P
><DIV
CLASS="FORMALPARA"
><P
><B
>Byte Order. </B
>Each cell is one byte.
<DIV
CLASS="INFORMALTABLE"
><P
></P
><A
NAME="AEN1825"
></A
><TABLE
BORDER="0"
FRAME="void"
CLASS="CALSTABLE"
><COL
WIDTH="2*"
ALIGN="LEFT"><COL><COL><COL><COL><TBODY
><TR
><TD
>start + 0:</TD
><TD
>Y'<SUB
>00</SUB
></TD
><TD
>Y'<SUB
>01</SUB
></TD
><TD
>Y'<SUB
>02</SUB
></TD
><TD
>Y'<SUB
>03</SUB
></TD
></TR
><TR
><TD
>start + 4:</TD
><TD
>Y'<SUB
>10</SUB
></TD
><TD
>Y'<SUB
>11</SUB
></TD
><TD
>Y'<SUB
>12</SUB
></TD
><TD
>Y'<SUB
>13</SUB
></TD
></TR
><TR
><TD
>start + 8:</TD
><TD
>Y'<SUB
>20</SUB
></TD
><TD
>Y'<SUB
>21</SUB
></TD
><TD
>Y'<SUB
>22</SUB
></TD
><TD
>Y'<SUB
>23</SUB
></TD
></TR
><TR
><TD
>start + 12:</TD
><TD
>Y'<SUB
>30</SUB
></TD
><TD
>Y'<SUB
>31</SUB
></TD
><TD
>Y'<SUB
>32</SUB
></TD
><TD
>Y'<SUB
>33</SUB
></TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
>
</P
></DIV
></DIV
></DIV
><H1
><A
NAME="PIXFMT-YUYV"
></A
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YUYV</CODE
></H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN1873"
></A
><H2
>Name</H2
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YUYV</CODE
>
('YUYV') -- Packed format with ½ horizontal chroma
resolution, also known as YUV 4:2:2.</DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN1877"
></A
><H2
>Description</H2
><P
>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.
<CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YUYV </CODE
> is known in the Windows
environment as YUY2.</P
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN1881"
></A
><P
><B
>Example 2-1. <CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YUYV</CODE
> 4 × 4
pixel image</B
></P
><DIV
CLASS="FORMALPARA"
><P
><B
>Byte Order. </B
>Each cell is one byte.
<DIV
CLASS="INFORMALTABLE"
><P
></P
><A
NAME="AEN1887"
></A
><TABLE
BORDER="0"
FRAME="void"
CLASS="CALSTABLE"
><COL
WIDTH="2*"
ALIGN="LEFT"><COL><COL><COL><COL><COL><COL><COL><COL><TBODY
><TR
><TD
>start + 0:</TD
><TD
>Y'<SUB
>00</SUB
></TD
><TD
>Cb<SUB
>00</SUB
></TD
><TD
>Y'<SUB
>01</SUB
></TD
><TD
>Cr<SUB
>00</SUB
></TD
><TD
>Y'<SUB
>02</SUB
></TD
><TD
>Cb<SUB
>01</SUB
></TD
><TD
>Y'<SUB
>03</SUB
></TD
><TD
>Cr<SUB
>01</SUB
></TD
></TR
><TR
><TD
>start + 8:</TD
><TD
>Y'<SUB
>10</SUB
></TD
><TD
>Cb<SUB
>10</SUB
></TD
><TD
>Y'<SUB
>11</SUB
></TD
><TD
>Cr<SUB
>10</SUB
></TD
><TD
>Y'<SUB
>12</SUB
></TD
><TD
>Cb<SUB
>11</SUB
></TD
><TD
>Y'<SUB
>13</SUB
></TD
><TD
>Cr<SUB
>11</SUB
></TD
></TR
><TR
><TD
>start + 16:</TD
><TD
>Y'<SUB
>20</SUB
></TD
><TD
>Cb<SUB
>20</SUB
></TD
><TD
>Y'<SUB
>21</SUB
></TD
><TD
>Cr<SUB
>20</SUB
></TD
><TD
>Y'<SUB
>22</SUB
></TD
><TD
>Cb<SUB
>21</SUB
></TD
><TD
>Y'<SUB
>23</SUB
></TD
><TD
>Cr<SUB
>21</SUB
></TD
></TR
><TR
><TD
>start + 24:</TD
><TD
>Y'<SUB
>30</SUB
></TD
><TD
>Cb<SUB
>30</SUB
></TD
><TD
>Y'<SUB
>31</SUB
></TD
><TD
>Cr<SUB
>30</SUB
></TD
><TD
>Y'<SUB
>32</SUB
></TD
><TD
>Cb<SUB
>31</SUB
></TD
><TD
>Y'<SUB
>33</SUB
></TD
><TD
>Cr<SUB
>31</SUB
></TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
>
</P
></DIV
><DIV
CLASS="FORMALPARA"
><P
><B
>Color Sample Location. </B
> <DIV
CLASS="INFORMALTABLE"
><P
></P
><A
NAME="AEN1966"
></A
><TABLE
BORDER="0"
FRAME="void"
CLASS="CALSTABLE"
><COL><COL><COL><COL><COL><COL><COL><TBODY
><TR
><TD
> </TD
><TD
>0</TD
><TD
> </TD
><TD
>1</TD
><TD
> </TD
><TD
>2</TD
><TD
> </TD
><TD
>3</TD
></TR
><TR
><TD
>0</TD
><TD
>Y</TD
><TD
>C</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
>C</TD
><TD
>Y</TD
></TR
><TR
><TD
>1</TD
><TD
>Y</TD
><TD
>C</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
>C</TD
><TD
>Y</TD
></TR
><TR
><TD
>2</TD
><TD
>Y</TD
><TD
>C</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
>C</TD
><TD
>Y</TD
></TR
><TR
><TD
>3</TD
><TD
>Y</TD
><TD
>C</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
>C</TD
><TD
>Y</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
>
</P
></DIV
></DIV
></DIV
><H1
><A
NAME="PIXFMT-UYVY"
></A
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_UYVY</CODE
></H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN2018"
></A
><H2
>Name</H2
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_UYVY</CODE
>
('UYVY') -- Variation of
<CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YUYV</CODE
> with different order of samples
in memory.</DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN2023"
></A
><H2
>Description</H2
><P
>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.</P
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN2026"
></A
><P
><B
>Example 2-1. <CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_UYVY</CODE
> 4 × 4
pixel image</B
></P
><DIV
CLASS="FORMALPARA"
><P
><B
>Byte Order. </B
>Each cell is one byte.
<DIV
CLASS="INFORMALTABLE"
><P
></P
><A
NAME="AEN2032"
></A
><TABLE
BORDER="0"
FRAME="void"
CLASS="CALSTABLE"
><COL
WIDTH="2*"
ALIGN="LEFT"><COL><COL><COL><COL><COL><COL><COL><COL><TBODY
><TR
><TD
>start + 0:</TD
><TD
>Cb<SUB
>00</SUB
></TD
><TD
>Y'<SUB
>00</SUB
></TD
><TD
>Cr<SUB
>00</SUB
></TD
><TD
>Y'<SUB
>01</SUB
></TD
><TD
>Cb<SUB
>01</SUB
></TD
><TD
>Y'<SUB
>02</SUB
></TD
><TD
>Cr<SUB
>01</SUB
></TD
><TD
>Y'<SUB
>03</SUB
></TD
></TR
><TR
><TD
>start + 8:</TD
><TD
>Cb<SUB
>10</SUB
></TD
><TD
>Y'<SUB
>10</SUB
></TD
><TD
>Cr<SUB
>10</SUB
></TD
><TD
>Y'<SUB
>11</SUB
></TD
><TD
>Cb<SUB
>11</SUB
></TD
><TD
>Y'<SUB
>12</SUB
></TD
><TD
>Cr<SUB
>11</SUB
></TD
><TD
>Y'<SUB
>13</SUB
></TD
></TR
><TR
><TD
>start + 16:</TD
><TD
>Cb<SUB
>20</SUB
></TD
><TD
>Y'<SUB
>20</SUB
></TD
><TD
>Cr<SUB
>20</SUB
></TD
><TD
>Y'<SUB
>21</SUB
></TD
><TD
>Cb<SUB
>21</SUB
></TD
><TD
>Y'<SUB
>22</SUB
></TD
><TD
>Cr<SUB
>21</SUB
></TD
><TD
>Y'<SUB
>23</SUB
></TD
></TR
><TR
><TD
>start + 24:</TD
><TD
>Cb<SUB
>30</SUB
></TD
><TD
>Y'<SUB
>30</SUB
></TD
><TD
>Cr<SUB
>30</SUB
></TD
><TD
>Y'<SUB
>31</SUB
></TD
><TD
>Cb<SUB
>31</SUB
></TD
><TD
>Y'<SUB
>32</SUB
></TD
><TD
>Cr<SUB
>31</SUB
></TD
><TD
>Y'<SUB
>33</SUB
></TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
>
</P
></DIV
><DIV
CLASS="FORMALPARA"
><P
><B
>Color Sample Location. </B
> <DIV
CLASS="INFORMALTABLE"
><P
></P
><A
NAME="AEN2111"
></A
><TABLE
BORDER="0"
FRAME="void"
CLASS="CALSTABLE"
><COL><COL><COL><COL><COL><COL><COL><TBODY
><TR
><TD
> </TD
><TD
>0</TD
><TD
> </TD
><TD
>1</TD
><TD
> </TD
><TD
>2</TD
><TD
> </TD
><TD
>3</TD
></TR
><TR
><TD
>0</TD
><TD
>Y</TD
><TD
>C</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
>C</TD
><TD
>Y</TD
></TR
><TR
><TD
>1</TD
><TD
>Y</TD
><TD
>C</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
>C</TD
><TD
>Y</TD
></TR
><TR
><TD
>2</TD
><TD
>Y</TD
><TD
>C</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
>C</TD
><TD
>Y</TD
></TR
><TR
><TD
>3</TD
><TD
>Y</TD
><TD
>C</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
>C</TD
><TD
>Y</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
>
</P
></DIV
></DIV
></DIV
><H1
><A
NAME="PIXFMT-Y41P"
></A
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_Y41P</CODE
></H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN2163"
></A
><H2
>Name</H2
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_Y41P</CODE
>
('Y41P') -- Packed format with ¼ horizontal chroma
resolution, also known as YUV 4:1:1.</DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN2167"
></A
><H2
>Description</H2
><P
>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.</P
><P
>Do not confuse this format with <A
HREF="#PIXFMT-YUV411P"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YUV411P</CODE
></A
>.
Y41P is derived from "YUV 4:1:1 <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>packed</I
></SPAN
>", possibly
in reference to a Windows FOURCC, while YUV411P stands for "YUV 4:1:1
<SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>planar</I
></SPAN
>".</P
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN2175"
></A
><P
><B
>Example 2-1. <CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_Y41P</CODE
> 8 × 4
pixel image</B
></P
><DIV
CLASS="FORMALPARA"
><P
><B
>Byte Order. </B
>Each cell is one byte.
<DIV
CLASS="INFORMALTABLE"
><P
></P
><A
NAME="AEN2181"
></A
><TABLE
BORDER="0"
FRAME="void"
CLASS="CALSTABLE"
><COL
WIDTH="2*"
ALIGN="LEFT"><COL><COL><COL><COL><COL><COL><COL><COL><COL><COL><COL><COL><TBODY
><TR
><TD
>start + 0:</TD
><TD
>Cb<SUB
>00</SUB
></TD
><TD
>Y'<SUB
>00</SUB
></TD
><TD
>Cr<SUB
>00</SUB
></TD
><TD
>Y'<SUB
>01</SUB
></TD
><TD
>Cb<SUB
>01</SUB
></TD
><TD
>Y'<SUB
>02</SUB
></TD
><TD
>Cr<SUB
>01</SUB
></TD
><TD
>Y'<SUB
>03</SUB
></TD
><TD
>Y'<SUB
>04</SUB
></TD
><TD
>Y'<SUB
>05</SUB
></TD
><TD
>Y'<SUB
>06</SUB
></TD
><TD
>Y'<SUB
>07</SUB
></TD
></TR
><TR
><TD
>start + 12:</TD
><TD
>Cb<SUB
>10</SUB
></TD
><TD
>Y'<SUB
>10</SUB
></TD
><TD
>Cr<SUB
>10</SUB
></TD
><TD
>Y'<SUB
>11</SUB
></TD
><TD
>Cb<SUB
>11</SUB
></TD
><TD
>Y'<SUB
>12</SUB
></TD
><TD
>Cr<SUB
>11</SUB
></TD
><TD
>Y'<SUB
>13</SUB
></TD
><TD
>Y'<SUB
>14</SUB
></TD
><TD
>Y'<SUB
>15</SUB
></TD
><TD
>Y'<SUB
>16</SUB
></TD
><TD
>Y'<SUB
>17</SUB
></TD
></TR
><TR
><TD
>start + 24:</TD
><TD
>Cb<SUB
>20</SUB
></TD
><TD
>Y'<SUB
>20</SUB
></TD
><TD
>Cr<SUB
>20</SUB
></TD
><TD
>Y'<SUB
>21</SUB
></TD
><TD
>Cb<SUB
>21</SUB
></TD
><TD
>Y'<SUB
>22</SUB
></TD
><TD
>Cr<SUB
>21</SUB
></TD
><TD
>Y'<SUB
>23</SUB
></TD
><TD
>Y'<SUB
>24</SUB
></TD
><TD
>Y'<SUB
>25</SUB
></TD
><TD
>Y'<SUB
>26</SUB
></TD
><TD
>Y'<SUB
>27</SUB
></TD
></TR
><TR
><TD
>start + 36:</TD
><TD
>Cb<SUB
>30</SUB
></TD
><TD
>Y'<SUB
>30</SUB
></TD
><TD
>Cr<SUB
>30</SUB
></TD
><TD
>Y'<SUB
>31</SUB
></TD
><TD
>Cb<SUB
>31</SUB
></TD
><TD
>Y'<SUB
>32</SUB
></TD
><TD
>Cr<SUB
>31</SUB
></TD
><TD
>Y'<SUB
>33</SUB
></TD
><TD
>Y'<SUB
>34</SUB
></TD
><TD
>Y'<SUB
>35</SUB
></TD
><TD
>Y'<SUB
>36</SUB
></TD
><TD
>Y'<SUB
>37</SUB
></TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
></P
></DIV
><DIV
CLASS="FORMALPARA"
><P
><B
>Color Sample Location. </B
> <DIV
CLASS="INFORMALTABLE"
><P
></P
><A
NAME="AEN2292"
></A
><TABLE
BORDER="0"
FRAME="void"
CLASS="CALSTABLE"
><COL><COL><COL><COL><COL><COL><COL><COL><COL><COL><COL><COL><COL><COL><COL><TBODY
><TR
><TD
> </TD
><TD
>0</TD
><TD
> </TD
><TD
>1</TD
><TD
> </TD
><TD
>2</TD
><TD
> </TD
><TD
>3</TD
><TD
> </TD
><TD
>4</TD
><TD
> </TD
><TD
>5</TD
><TD
> </TD
><TD
>6</TD
><TD
> </TD
><TD
>7</TD
></TR
><TR
><TD
>0</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
>C</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
>C</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
></TR
><TR
><TD
>1</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
>C</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
>C</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
></TR
><TR
><TD
>2</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
>C</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
>C</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
></TR
><TR
><TD
>3</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
>C</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
>C</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
>
</P
></DIV
></DIV
></DIV
><H1
><A
NAME="PIXFMT-YVU420"
></A
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YVU420</CODE
>,
<CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YUV420</CODE
></H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN2385"
></A
><H2
>Name</H2
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YVU420</CODE
>
('YV12'), <CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YUV420</CODE
>
('YU12') -- Planar formats with ½ horizontal and
vertical chroma resolution, also known as YUV 4:2:0.</DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN2391"
></A
><H2
>Description</H2
><P
>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
<CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YVU420</CODE
>, 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<SUB
>0</SUB
> belongs to Y'<SUB
>00</SUB
>,
Y'<SUB
>01</SUB
>, Y'<SUB
>10</SUB
>, and
Y'<SUB
>11</SUB
>. Following the Cr plane is the Cb plane,
just like the Cr plane. <CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YUV420</CODE
> is
the same except the Cb plane comes first, then the Cr plane.</P
><P
>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).</P
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN2402"
></A
><P
><B
>Example 2-1. <CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YVU420</CODE
> 4 × 4
pixel image</B
></P
><DIV
CLASS="FORMALPARA"
><P
><B
>Byte Order. </B
>Each cell is one byte.
<DIV
CLASS="INFORMALTABLE"
><P
></P
><A
NAME="AEN2408"
></A
><TABLE
BORDER="0"
FRAME="void"
CLASS="CALSTABLE"
><COL
WIDTH="2*"
ALIGN="LEFT"><COL><COL><COL><COL><TBODY
><TR
><TD
>start + 0:</TD
><TD
>Y'<SUB
>00</SUB
></TD
><TD
>Y'<SUB
>01</SUB
></TD
><TD
>Y'<SUB
>02</SUB
></TD
><TD
>Y'<SUB
>03</SUB
></TD
></TR
><TR
><TD
>start + 4:</TD
><TD
>Y'<SUB
>10</SUB
></TD
><TD
>Y'<SUB
>11</SUB
></TD
><TD
>Y'<SUB
>12</SUB
></TD
><TD
>Y'<SUB
>13</SUB
></TD
></TR
><TR
><TD
>start + 8:</TD
><TD
>Y'<SUB
>20</SUB
></TD
><TD
>Y'<SUB
>21</SUB
></TD
><TD
>Y'<SUB
>22</SUB
></TD
><TD
>Y'<SUB
>23</SUB
></TD
></TR
><TR
><TD
>start + 12:</TD
><TD
>Y'<SUB
>30</SUB
></TD
><TD
>Y'<SUB
>31</SUB
></TD
><TD
>Y'<SUB
>32</SUB
></TD
><TD
>Y'<SUB
>33</SUB
></TD
></TR
><TR
><TD
>start + 16:</TD
><TD
>Cr<SUB
>00</SUB
></TD
><TD
>Cr<SUB
>01</SUB
></TD
><TD
> </TD
><TD
> </TD
></TR
><TR
><TD
>start + 18:</TD
><TD
>Cr<SUB
>10</SUB
></TD
><TD
>Cr<SUB
>11</SUB
></TD
><TD
> </TD
><TD
> </TD
></TR
><TR
><TD
>start + 20:</TD
><TD
>Cb<SUB
>00</SUB
></TD
><TD
>Cb<SUB
>01</SUB
></TD
><TD
> </TD
><TD
> </TD
></TR
><TR
><TD
>start + 22:</TD
><TD
>Cb<SUB
>10</SUB
></TD
><TD
>Cb<SUB
>11</SUB
></TD
><TD
> </TD
><TD
> </TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
>
</P
></DIV
><DIV
CLASS="FORMALPARA"
><P
><B
>Color Sample Location. </B
> <DIV
CLASS="INFORMALTABLE"
><P
></P
><A
NAME="AEN2479"
></A
><TABLE
BORDER="0"
FRAME="void"
CLASS="CALSTABLE"
><COL><COL><COL><COL><COL><COL><COL><TBODY
><TR
><TD
> </TD
><TD
>0</TD
><TD
> </TD
><TD
>1</TD
><TD
> </TD
><TD
>2</TD
><TD
> </TD
><TD
>3</TD
></TR
><TR
><TD
>0</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
></TR
><TR
><TD
> </TD
><TD
> </TD
><TD
>C</TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
>C</TD
><TD
> </TD
></TR
><TR
><TD
>1</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
></TR
><TR
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
></TR
><TR
><TD
>2</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
></TR
><TR
><TD
> </TD
><TD
> </TD
><TD
>C</TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
>C</TD
><TD
> </TD
></TR
><TR
><TD
>3</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
>
</P
></DIV
></DIV
></DIV
><H1
><A
NAME="PIXFMT-YVU410"
></A
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YVU410</CODE
>,
<CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YUV410</CODE
></H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN2552"
></A
><H2
>Name</H2
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YVU410</CODE
>
('YVU9'), <CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YUV410</CODE
>
('YUV9') -- Planar formats with ¼ horizontal and
vertical chroma resolution, also known as YUV 4:1:0.</DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN2558"
></A
><H2
>Description</H2
><P
>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
<CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YVU410</CODE
>, the Cr plane immediately
follows the Y plane in memory. The Cr plane is ¼ the width and
¼ 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.
<CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YUV410</CODE
> is the same, except the Cb
plane comes first, then the Cr plane.</P
><P
>If the Y plane has pad bytes after each row, then the Cr
and Cb planes have ¼ 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).</P
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN2564"
></A
><P
><B
>Example 2-1. <CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YVU410</CODE
> 4 × 4
pixel image</B
></P
><DIV
CLASS="FORMALPARA"
><P
><B
>Byte Order. </B
>Each cell is one byte.
<DIV
CLASS="INFORMALTABLE"
><P
></P
><A
NAME="AEN2570"
></A
><TABLE
BORDER="0"
FRAME="void"
CLASS="CALSTABLE"
><COL
WIDTH="2*"
ALIGN="LEFT"><COL><COL><COL><COL><TBODY
><TR
><TD
>start + 0:</TD
><TD
>Y'<SUB
>00</SUB
></TD
><TD
>Y'<SUB
>01</SUB
></TD
><TD
>Y'<SUB
>02</SUB
></TD
><TD
>Y'<SUB
>03</SUB
></TD
></TR
><TR
><TD
>start + 4:</TD
><TD
>Y'<SUB
>10</SUB
></TD
><TD
>Y'<SUB
>11</SUB
></TD
><TD
>Y'<SUB
>12</SUB
></TD
><TD
>Y'<SUB
>13</SUB
></TD
></TR
><TR
><TD
>start + 8:</TD
><TD
>Y'<SUB
>20</SUB
></TD
><TD
>Y'<SUB
>21</SUB
></TD
><TD
>Y'<SUB
>22</SUB
></TD
><TD
>Y'<SUB
>23</SUB
></TD
></TR
><TR
><TD
>start + 12:</TD
><TD
>Y'<SUB
>30</SUB
></TD
><TD
>Y'<SUB
>31</SUB
></TD
><TD
>Y'<SUB
>32</SUB
></TD
><TD
>Y'<SUB
>33</SUB
></TD
></TR
><TR
><TD
>start + 16:</TD
><TD
>Cr<SUB
>00</SUB
></TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
></TR
><TR
><TD
>start + 17:</TD
><TD
>Cb<SUB
>00</SUB
></TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
>
</P
></DIV
><DIV
CLASS="FORMALPARA"
><P
><B
>Color Sample Location. </B
> <DIV
CLASS="INFORMALTABLE"
><P
></P
><A
NAME="AEN2625"
></A
><TABLE
BORDER="0"
FRAME="void"
CLASS="CALSTABLE"
><COL><COL><COL><COL><COL><COL><COL><TBODY
><TR
><TD
> </TD
><TD
>0</TD
><TD
> </TD
><TD
>1</TD
><TD
> </TD
><TD
>2</TD
><TD
> </TD
><TD
>3</TD
></TR
><TR
><TD
>0</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
></TR
><TR
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
></TR
><TR
><TD
>1</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
></TR
><TR
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
>C</TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
></TR
><TR
><TD
>2</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
></TR
><TR
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
></TR
><TR
><TD
>3</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
>
</P
></DIV
></DIV
></DIV
><H1
><A
NAME="PIXFMT-YUV422P"
></A
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YUV422P</CODE
></H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN2690"
></A
><H2
>Name</H2
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YUV422P</CODE
>
('422P') -- Format with ½ horizontal chroma resolution,
also known as YUV 4:2:2. Planar layout as opposed to
<CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YUYV</CODE
>.</DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN2695"
></A
><H2
>Description</H2
><P
>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<SUB
>0</SUB
> belongs to Y'<SUB
>00</SUB
>,
Y'<SUB
>01</SUB
>. Following the Cb plane is the Cr plane,
just like the Cb plane.</P
><P
>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).</P
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN2702"
></A
><P
><B
>Example 2-1. <CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YUV422P</CODE
> 4 × 4
pixel image</B
></P
><DIV
CLASS="FORMALPARA"
><P
><B
>Byte Order. </B
>Each cell is one byte.
<DIV
CLASS="INFORMALTABLE"
><P
></P
><A
NAME="AEN2708"
></A
><TABLE
BORDER="0"
FRAME="void"
CLASS="CALSTABLE"
><COL
WIDTH="2*"
ALIGN="LEFT"><COL><COL><COL><COL><TBODY
><TR
><TD
>start + 0:</TD
><TD
>Y'<SUB
>00</SUB
></TD
><TD
>Y'<SUB
>01</SUB
></TD
><TD
>Y'<SUB
>02</SUB
></TD
><TD
>Y'<SUB
>03</SUB
></TD
></TR
><TR
><TD
>start + 4:</TD
><TD
>Y'<SUB
>10</SUB
></TD
><TD
>Y'<SUB
>11</SUB
></TD
><TD
>Y'<SUB
>12</SUB
></TD
><TD
>Y'<SUB
>13</SUB
></TD
></TR
><TR
><TD
>start + 8:</TD
><TD
>Y'<SUB
>20</SUB
></TD
><TD
>Y'<SUB
>21</SUB
></TD
><TD
>Y'<SUB
>22</SUB
></TD
><TD
>Y'<SUB
>23</SUB
></TD
></TR
><TR
><TD
>start + 12:</TD
><TD
>Y'<SUB
>30</SUB
></TD
><TD
>Y'<SUB
>31</SUB
></TD
><TD
>Y'<SUB
>32</SUB
></TD
><TD
>Y'<SUB
>33</SUB
></TD
></TR
><TR
><TD
>start + 16:</TD
><TD
>Cb<SUB
>00</SUB
></TD
><TD
>Cb<SUB
>01</SUB
></TD
><TD
> </TD
><TD
> </TD
></TR
><TR
><TD
>start + 18:</TD
><TD
>Cb<SUB
>10</SUB
></TD
><TD
>Cb<SUB
>11</SUB
></TD
><TD
> </TD
><TD
> </TD
></TR
><TR
><TD
>start + 20:</TD
><TD
>Cb<SUB
>20</SUB
></TD
><TD
>Cb<SUB
>21</SUB
></TD
><TD
> </TD
><TD
> </TD
></TR
><TR
><TD
>start + 22:</TD
><TD
>Cb<SUB
>30</SUB
></TD
><TD
>Cb<SUB
>31</SUB
></TD
><TD
> </TD
><TD
> </TD
></TR
><TR
><TD
>start + 24:</TD
><TD
>Cr<SUB
>00</SUB
></TD
><TD
>Cr<SUB
>01</SUB
></TD
><TD
> </TD
><TD
> </TD
></TR
><TR
><TD
>start + 26:</TD
><TD
>Cr<SUB
>10</SUB
></TD
><TD
>Cr<SUB
>11</SUB
></TD
><TD
> </TD
><TD
> </TD
></TR
><TR
><TD
>start + 28:</TD
><TD
>Cr<SUB
>20</SUB
></TD
><TD
>Cr<SUB
>21</SUB
></TD
><TD
> </TD
><TD
> </TD
></TR
><TR
><TD
>start + 30:</TD
><TD
>Cr<SUB
>30</SUB
></TD
><TD
>Cr<SUB
>31</SUB
></TD
><TD
> </TD
><TD
> </TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
>
</P
></DIV
><DIV
CLASS="FORMALPARA"
><P
><B
>Color Sample Location. </B
> <DIV
CLASS="INFORMALTABLE"
><P
></P
><A
NAME="AEN2803"
></A
><TABLE
BORDER="0"
FRAME="void"
CLASS="CALSTABLE"
><COL><COL><COL><COL><COL><COL><COL><TBODY
><TR
><TD
> </TD
><TD
>0</TD
><TD
> </TD
><TD
>1</TD
><TD
> </TD
><TD
>2</TD
><TD
> </TD
><TD
>3</TD
></TR
><TR
><TD
>0</TD
><TD
>Y</TD
><TD
>C</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
>C</TD
><TD
>Y</TD
></TR
><TR
><TD
>1</TD
><TD
>Y</TD
><TD
>C</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
>C</TD
><TD
>Y</TD
></TR
><TR
><TD
>2</TD
><TD
>Y</TD
><TD
>C</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
>C</TD
><TD
>Y</TD
></TR
><TR
><TD
>3</TD
><TD
>Y</TD
><TD
>C</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
>C</TD
><TD
>Y</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
>
</P
></DIV
></DIV
></DIV
><H1
><A
NAME="PIXFMT-YUV411P"
></A
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YUV411P</CODE
></H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN2855"
></A
><H2
>Name</H2
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YUV411P</CODE
>
('411P') -- Format with ¼ horizontal chroma resolution,
also known as YUV 4:1:1. Planar layout as opposed to
<CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_Y41P</CODE
>.</DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN2860"
></A
><H2
>Description</H2
><P
>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
¼ the width of the Y plane (and of the image). Each Cb belongs
to 4 pixels all on the same row. For example,
Cb<SUB
>0</SUB
> belongs to Y'<SUB
>00</SUB
>,
Y'<SUB
>01</SUB
>, Y'<SUB
>02</SUB
> and
Y'<SUB
>03</SUB
>. Following the Cb plane is the Cr plane,
just like the Cb plane.</P
><P
>If the Y plane has pad bytes after each row, then the Cr
and Cb planes have ¼ 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).</P
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN2869"
></A
><P
><B
>Example 2-1. <CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YUV411P</CODE
> 4 × 4
pixel image</B
></P
><DIV
CLASS="FORMALPARA"
><P
><B
>Byte Order. </B
>Each cell is one byte.
<DIV
CLASS="INFORMALTABLE"
><P
></P
><A
NAME="AEN2875"
></A
><TABLE
BORDER="0"
FRAME="void"
CLASS="CALSTABLE"
><COL
WIDTH="2*"
ALIGN="LEFT"><COL><COL><COL><COL><TBODY
><TR
><TD
>start + 0:</TD
><TD
>Y'<SUB
>00</SUB
></TD
><TD
>Y'<SUB
>01</SUB
></TD
><TD
>Y'<SUB
>02</SUB
></TD
><TD
>Y'<SUB
>03</SUB
></TD
></TR
><TR
><TD
>start + 4:</TD
><TD
>Y'<SUB
>10</SUB
></TD
><TD
>Y'<SUB
>11</SUB
></TD
><TD
>Y'<SUB
>12</SUB
></TD
><TD
>Y'<SUB
>13</SUB
></TD
></TR
><TR
><TD
>start + 8:</TD
><TD
>Y'<SUB
>20</SUB
></TD
><TD
>Y'<SUB
>21</SUB
></TD
><TD
>Y'<SUB
>22</SUB
></TD
><TD
>Y'<SUB
>23</SUB
></TD
></TR
><TR
><TD
>start + 12:</TD
><TD
>Y'<SUB
>30</SUB
></TD
><TD
>Y'<SUB
>31</SUB
></TD
><TD
>Y'<SUB
>32</SUB
></TD
><TD
>Y'<SUB
>33</SUB
></TD
></TR
><TR
><TD
>start + 16:</TD
><TD
>Cb<SUB
>00</SUB
></TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
></TR
><TR
><TD
>start + 17:</TD
><TD
>Cb<SUB
>10</SUB
></TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
></TR
><TR
><TD
>start + 18:</TD
><TD
>Cb<SUB
>20</SUB
></TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
></TR
><TR
><TD
>start + 19:</TD
><TD
>Cb<SUB
>30</SUB
></TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
></TR
><TR
><TD
>start + 20:</TD
><TD
>Cr<SUB
>00</SUB
></TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
></TR
><TR
><TD
>start + 21:</TD
><TD
>Cr<SUB
>10</SUB
></TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
></TR
><TR
><TD
>start + 22:</TD
><TD
>Cr<SUB
>20</SUB
></TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
></TR
><TR
><TD
>start + 23:</TD
><TD
>Cr<SUB
>30</SUB
></TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
>
</P
></DIV
><DIV
CLASS="FORMALPARA"
><P
><B
>Color Sample Location. </B
> <DIV
CLASS="INFORMALTABLE"
><P
></P
><A
NAME="AEN2954"
></A
><TABLE
BORDER="0"
FRAME="void"
CLASS="CALSTABLE"
><COL><COL><COL><COL><COL><COL><COL><TBODY
><TR
><TD
> </TD
><TD
>0</TD
><TD
> </TD
><TD
>1</TD
><TD
> </TD
><TD
>2</TD
><TD
> </TD
><TD
>3</TD
></TR
><TR
><TD
>0</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
>C</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
></TR
><TR
><TD
>1</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
>C</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
></TR
><TR
><TD
>2</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
>C</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
></TR
><TR
><TD
>3</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
>C</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
>
</P
></DIV
></DIV
></DIV
><H1
><A
NAME="AEN3002"
></A
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_NV12</CODE
>,
<CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_NV21</CODE
></H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN3007"
></A
><H2
>Name</H2
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_NV12</CODE
>
('NV12'), <CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_NV21</CODE
>
('NV21') -- Formats with ½ 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
<CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YVU420</CODE
>.</DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN3014"
></A
><H2
>Description</H2
><P
>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
<CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_NV12</CODE
>, 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<SUB
>0</SUB
>/Cr<SUB
>0</SUB
> belongs to
Y'<SUB
>00</SUB
>, Y'<SUB
>01</SUB
>,
Y'<SUB
>10</SUB
>, Y'<SUB
>11</SUB
>.
<CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_NV21</CODE
> is the same except the Cb and
Cr bytes are swapped, the CrCb plane starts with a Cr byte.</P
><P
>If the Y plane has pad bytes after each row, then the
CbCr plane has as many pad bytes after its rows.</P
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN3026"
></A
><P
><B
>Example 2-1. <CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_NV12</CODE
> 4 × 4
pixel image</B
></P
><DIV
CLASS="FORMALPARA"
><P
><B
>Byte Order. </B
>Each cell is one byte.
<DIV
CLASS="INFORMALTABLE"
><P
></P
><A
NAME="AEN3032"
></A
><TABLE
BORDER="0"
FRAME="void"
CLASS="CALSTABLE"
><COL
WIDTH="2*"
ALIGN="LEFT"><COL><COL><COL><COL><TBODY
><TR
><TD
>start + 0:</TD
><TD
>Y'<SUB
>00</SUB
></TD
><TD
>Y'<SUB
>01</SUB
></TD
><TD
>Y'<SUB
>02</SUB
></TD
><TD
>Y'<SUB
>03</SUB
></TD
></TR
><TR
><TD
>start + 4:</TD
><TD
>Y'<SUB
>10</SUB
></TD
><TD
>Y'<SUB
>11</SUB
></TD
><TD
>Y'<SUB
>12</SUB
></TD
><TD
>Y'<SUB
>13</SUB
></TD
></TR
><TR
><TD
>start + 8:</TD
><TD
>Y'<SUB
>20</SUB
></TD
><TD
>Y'<SUB
>21</SUB
></TD
><TD
>Y'<SUB
>22</SUB
></TD
><TD
>Y'<SUB
>23</SUB
></TD
></TR
><TR
><TD
>start + 12:</TD
><TD
>Y'<SUB
>30</SUB
></TD
><TD
>Y'<SUB
>31</SUB
></TD
><TD
>Y'<SUB
>32</SUB
></TD
><TD
>Y'<SUB
>33</SUB
></TD
></TR
><TR
><TD
>start + 16:</TD
><TD
>Cb<SUB
>00</SUB
></TD
><TD
>Cr<SUB
>00</SUB
></TD
><TD
>Cb<SUB
>01</SUB
></TD
><TD
>Cr<SUB
>01</SUB
></TD
></TR
><TR
><TD
>start + 20:</TD
><TD
>Cb<SUB
>10</SUB
></TD
><TD
>Cr<SUB
>10</SUB
></TD
><TD
>Cb<SUB
>11</SUB
></TD
><TD
>Cr<SUB
>11</SUB
></TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
>
</P
></DIV
><DIV
CLASS="FORMALPARA"
><P
><B
>Color Sample Location. </B
> <DIV
CLASS="INFORMALTABLE"
><P
></P
><A
NAME="AEN3099"
></A
><TABLE
BORDER="0"
FRAME="void"
CLASS="CALSTABLE"
><COL><COL><COL><COL><COL><COL><COL><TBODY
><TR
><TD
> </TD
><TD
>0</TD
><TD
> </TD
><TD
>1</TD
><TD
> </TD
><TD
>2</TD
><TD
> </TD
><TD
>3</TD
></TR
><TR
><TD
>0</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
></TR
><TR
><TD
> </TD
><TD
> </TD
><TD
>C</TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
>C</TD
><TD
> </TD
></TR
><TR
><TD
>1</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
></TR
><TR
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
></TR
><TR
><TD
>2</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
></TR
><TR
><TD
> </TD
><TD
> </TD
><TD
>C</TD
><TD
> </TD
><TD
> </TD
><TD
> </TD
><TD
>C</TD
><TD
> </TD
></TR
><TR
><TD
>3</TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
><TD
> </TD
><TD
>Y</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
>
</P
></DIV
></DIV
></DIV
></DIV
><DIV
CLASS="SECTION"
><HR><H2
CLASS="SECTION"
><A
NAME="AEN3167"
>2.5. Compressed Formats</A
></H2
><P
>[to do, see also <A
HREF="#VIDIOC-G-COMP"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_COMP</CODE
></A
>, <A
HREF="#VIDIOC-G-COMP"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_COMP</CODE
></A
>,
<A
HREF="#VIDIOC-G-JPEGCOMP"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_JPEGCOMP</CODE
></A
>, <A
HREF="#VIDIOC-G-JPEGCOMP"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_JPEGCOMP</CODE
></A
>. The only compressed standard
format should be [M]JPEG.]</P
></DIV
><DIV
CLASS="SECTION"
><HR><H2
CLASS="SECTION"
><A
NAME="PIXFMT-RESERVED"
>2.6. Reserved Format Identifiers</A
></H2
><P
>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 V4L2 maintainer
Gerd Knorr <A
HREF="http://bytesex.org/"
TARGET="_top"
>http://bytesex.org/</A
>
for inclusion in the <TT
CLASS="FILENAME"
>videodev.h</TT
> file. If you want
to share your format with other developers add a link to your
documentation and send a copy to the maintainer of this document,
Michael Schimek <CODE
CLASS="EMAIL"
><<A
HREF="mailto:mschimek@gmx.at"
>mschimek@gmx.at</A
>></CODE
>, for inclusion in this
section. If you think your format should be listed in a standard
format section please make a proposal on the V4L mailing list:
<A
HREF="https://listman.redhat.com/mailman/listinfo/video4linux-list"
TARGET="_top"
>https://listman.redhat.com/mailman/listinfo/video4linux-list</A
>.</P
><DIV
CLASS="TABLE"
><A
NAME="RESERVED-FORMATS"
></A
><P
><B
>Table 2-4. Reserved Image Formats</B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="38%"
TITLE="C1"><COL
WIDTH="12%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><THEAD
><TR
><TH
>Identifier</TH
><TH
>Code</TH
><TH
>Details</TH
></TR
></THEAD
><TBODY
><TR
><TD
> <CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YYUV</CODE
>
</TD
><TD
>'YYUV'</TD
><TD
>unknown</TD
></TR
><TR
><TD
> <CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_HI240</CODE
>
</TD
><TD
>'HI24'</TD
><TD
> Used by the BTTV driver, <A
HREF="http://bytesex.org/bttv/"
TARGET="_top"
>http://bytesex.org/bttv/</A
>
</TD
></TR
><TR
><TD
> <CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_MJPEG</CODE
>
</TD
><TD
>'MJPG'</TD
><TD
>Used by the Zoran driver</TD
></TR
><TR
><TD
> <CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_JPEG</CODE
>
</TD
><TD
>'JPEG'</TD
><TD
>unknown [?]</TD
></TR
><TR
><TD
> <CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_DV</CODE
>
</TD
><TD
>'dvsd'</TD
><TD
>unknown</TD
></TR
><TR
><TD
> <CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_MPEG</CODE
>
</TD
><TD
>'MPEG'</TD
><TD
>unknown</TD
></TR
><TR
><TD
> <CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_WNVA</CODE
>
</TD
><TD
>'WNVA'</TD
><TD
> Used by the Winnov Videum driver, <A
HREF="http://www.thedirks.org/winnov/"
TARGET="_top"
>http://www.thedirks.org/winnov/</A
>
</TD
></TR
></TBODY
></TABLE
></DIV
></DIV
></DIV
><DIV
CLASS="CHAPTER"
><HR><H1
><A
NAME="IO"
></A
>Chapter 3. Input/Output</H1
><P
>The V4L2 API defines several different methods to read from or
write to a device. All drivers exchanging data with applications must
support at least one of them.</P
><P
>The classic I/O method using the <CODE
CLASS="FUNCTION"
>read()</CODE
>
and <CODE
CLASS="FUNCTION"
>write()</CODE
> function is automatically selected
after opening a V4L2 device. When the driver does not support this
method attempts to read or write will fail at any time.</P
><P
>Other methods must be negotiated. To select the streaming I/O
method with memory mapped or user buffers applications call the
<A
HREF="#VIDIOC-REQBUFS"
><CODE
CLASS="CONSTANT"
>VIDIOC_REQBUFS</CODE
></A
> ioctl. The asynchronous I/O method is not defined
yet.</P
><P
>Video overlay can be considered another I/O method, although
the application does not directly receive the image data. It is
selected by initiating video overlay with the <A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
></A
> ioctl.
For more information see <A
HREF="#OVERLAY"
>Section 4.2</A
>.</P
><P
>Generally exactly one I/O method, including overlay, is
associated with each file descriptor. The only exceptions are
applications not exchanging data with a driver ("panel applications",
see <A
HREF="#OPEN"
>Section 1.1</A
>) and drivers permitting simultaneous video capturing
and overlay using the same file descriptor, for compatibility with V4L
and earlier versions of V4L2.</P
><P
><CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
> and
<CODE
CLASS="CONSTANT"
>VIDIOC_REQBUFS</CODE
> would permit this to some degree,
but for simplicity drivers need not support switching the I/O method
(after first switching away from read/write) other than by closing
and reopening the device.</P
><P
>The following sections describe the various I/O methods in
more detail.</P
><DIV
CLASS="SECTION"
><HR><H2
CLASS="SECTION"
><A
NAME="RW"
>3.1. Read/Write</A
></H2
><P
>Input and output devices support the
<CODE
CLASS="FUNCTION"
>read()</CODE
> and <CODE
CLASS="FUNCTION"
>write()</CODE
> function,
respectively, when the <CODE
CLASS="CONSTANT"
>V4L2_CAP_READWRITE</CODE
> flag in
the <CODE
CLASS="STRUCTFIELD"
>capabilities</CODE
> field of struct <A
HREF="#V4L2-CAPABILITY"
>v4l2_capability</A
>
returned by the <A
HREF="#VIDIOC-QUERYCAP"
><CODE
CLASS="CONSTANT"
>VIDIOC_QUERYCAP</CODE
></A
> ioctl is set.</P
><P
>Drivers may need the CPU to copy the data, but they may also
support DMA to or from user memory, so this I/O method is not
necessarily less efficient than other methods merely exchanging buffer
pointers. It is considered inferior though because no meta-information
like frame counters or timestamps are passed. This information is
necessary to recognize frame dropping and to synchronize with other
data streams. However this is also the simplest I/O method, requiring
little or no setup to exchange data. It permits command line stunts
like this (the <SPAN
CLASS="APPLICATION"
>vidctrl</SPAN
> tool is
fictitious):</P
><DIV
CLASS="INFORMALEXAMPLE"
><P
></P
><A
NAME="AEN3266"
></A
><PRE
CLASS="SCREEN"
>> vidctrl /dev/video --input=0 --format=YUYV --size=352x288
> dd if=/dev/video of=myimage.422 bs=202752 count=1</PRE
><P
></P
></DIV
><P
>To read from the device applications use the
<A
HREF="#FUNC-READ"
><CODE
CLASS="FUNCTION"
>read()</CODE
></A
> function, to write the <A
HREF="#FUNC-WRITE"
><CODE
CLASS="FUNCTION"
>write()</CODE
></A
> function.
Drivers must implement one I/O method if they
exchange data with applications, but it need not be this.<A
NAME="AEN3273"
HREF="#FTN.AEN3273"
><SPAN
CLASS="footnote"
>[13]</SPAN
></A
> When reading or writing is supported, the driver
must also support the <A
HREF="#FUNC-SELECT"
><CODE
CLASS="FUNCTION"
>select()</CODE
></A
> and <A
HREF="#FUNC-POLL"
><CODE
CLASS="FUNCTION"
>poll()</CODE
></A
>
function.<A
NAME="AEN3279"
HREF="#FTN.AEN3279"
><SPAN
CLASS="footnote"
>[14]</SPAN
></A
></P
></DIV
><DIV
CLASS="SECTION"
><HR><H2
CLASS="SECTION"
><A
NAME="MMAP"
>3.2. Streaming I/O (Memory Mapping)</A
></H2
><P
>Input and output devices support this I/O method when the
<CODE
CLASS="CONSTANT"
>V4L2_CAP_STREAMING</CODE
> flag in the
<CODE
CLASS="STRUCTFIELD"
>capabilities</CODE
> field of struct <A
HREF="#V4L2-CAPABILITY"
>v4l2_capability</A
>
returned by the <A
HREF="#VIDIOC-QUERYCAP"
><CODE
CLASS="CONSTANT"
>VIDIOC_QUERYCAP</CODE
></A
> ioctl is set. There are two
streaming methods, to determine if the memory mapping flavor is
supported applications must call the <A
HREF="#VIDIOC-REQBUFS"
><CODE
CLASS="CONSTANT"
>VIDIOC_REQBUFS</CODE
></A
> ioctl.</P
><P
>Streaming is an I/O method where only pointers to buffers
are exchanged between application and driver, the data itself is not
copied. Memory mapping is primarily intended to map buffers in device
memory into the application's address space. Device memory can be for
example the video memory on a graphics card with a video capture
add-on. However, being the most efficient I/O method available for a
long time, many other drivers support streaming as well, allocating
buffers in DMA-able main memory.</P
><P
>A driver can support many sets of buffers. Each set is
identified by a unique buffer type value. The sets are independent and
each set can hold a different type of data. To access different sets
at the same time different file descriptors must be used.<A
NAME="AEN3296"
HREF="#FTN.AEN3296"
><SPAN
CLASS="footnote"
>[15]</SPAN
></A
></P
><P
>To allocate device buffers applications call the
<A
HREF="#VIDIOC-REQBUFS"
><CODE
CLASS="CONSTANT"
>VIDIOC_REQBUFS</CODE
></A
> ioctl with the desired number of buffers and buffer
type, for example <CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_VIDEO_CAPTURE</CODE
>.
This ioctl can also be used to change the number of buffers or to free
the allocated memory, provided none of the buffers are still
mapped.</P
><P
>Before applications can access the buffers they must map
them into their address space with the <A
HREF="#FUNC-MMAP"
><CODE
CLASS="FUNCTION"
>mmap()</CODE
></A
> function. The
location of the buffers in device memory can be determined with the
<A
HREF="#VIDIOC-QUERYBUF"
><CODE
CLASS="CONSTANT"
>VIDIOC_QUERYBUF</CODE
></A
> ioctl. The <CODE
CLASS="STRUCTFIELD"
>m.offset</CODE
> and
<CODE
CLASS="STRUCTFIELD"
>length</CODE
> returned in a struct <A
HREF="#V4L2-BUFFER"
>v4l2_buffer</A
> are
passed as sixth and second parameter to the
<CODE
CLASS="FUNCTION"
>mmap()</CODE
> function. The offset and length values
must not be modified. Remember the buffers are allocated in physical
memory, as opposed to virtual memory which can be swapped out to disk.
Applications should free the buffers as soon as possible with the
<A
HREF="#FUNC-MUNMAP"
><CODE
CLASS="FUNCTION"
>munmap()</CODE
></A
> function.</P
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN3316"
></A
><P
><B
>Example 3-1. Mapping buffers</B
></P
><PRE
CLASS="PROGRAMLISTING"
>struct <A
HREF="#V4L2-REQUESTBUFFERS"
>v4l2_requestbuffers</A
> reqbuf;
struct {
void *start;
size_t length;
} *buffers;
unsigned int i;
memset (&reqbuf, 0, sizeof (reqbuf));
reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
reqbuf.memory = V4L2_MEMORY_MMAP;
reqbuf.count = 20;
if (-1 == ioctl (fd, <A
HREF="#VIDIOC-REQBUFS"
><CODE
CLASS="CONSTANT"
>VIDIOC_REQBUFS</CODE
></A
>, &reqbuf)) {
if (errno == EINVAL)
printf ("Video capturing or mmap-streaming is not supported\n");
else
perror ("VIDIOC_REQBUFS");
exit (EXIT_FAILURE);
}
/* We want at least five buffers. */
if (reqbuf.count < 5) {
/* You may need to free the buffers here. */
printf ("Not enough buffer memory\n");
exit (EXIT_FAILURE);
}
buffers = calloc (reqbuf.count, sizeof (*buffers));
assert (buffers != NULL);
for (i = 0; i < reqbuf.count; i++) {
struct <A
HREF="#V4L2-BUFFER"
>v4l2_buffer</A
> buffer;
memset (&buffer, 0, sizeof (buffer));
buffer.type = reqbuf.type;
buffer.memory = V4L2_MEMORY_MMAP;
buffer.index = i;
if (-1 == ioctl (fd, <A
HREF="#VIDIOC-QUERYBUF"
><CODE
CLASS="CONSTANT"
>VIDIOC_QUERYBUF</CODE
></A
>, &buffer)) {
perror ("VIDIOC_QUERYBUF");
exit (EXIT_FAILURE);
}
buffers[i].length = buffer.length; /* remember for munmap() */
buffers[i].start = mmap (NULL, buffer.length,
PROT_READ | PROT_WRITE, /* required */
MAP_SHARED, /* recommended */
fd, buffer.m.offset);
if (buffers[i].start == MAP_FAILED) {
/* You may need to unmap and free the so far
mapped buffers here. */
perror ("mmap");
exit (EXIT_FAILURE);
}
}
/* Cleanup. */
for (i = 0; i < reqbuf.count; i++)
munmap (buffers[i].start, buffers[i].length);
</PRE
></DIV
><P
>Streaming drivers maintain two buffer queues, an incoming
and an outgoing queue. They separate the synchronous capture or output
operation locked to a video clock from the application which is
subject to random disk or network delays and preemption by
other processes, thereby reducing the probability of data loss.
The queues are organized as FIFOs, buffers will be
output in the order enqueued in the incoming FIFO, and were
captured in the order dequeued from the outgoing FIFO.</P
><P
>The driver may require a minimum number of buffers enqueued
at all times to function, apart of this no limit exists on the number
of buffers applications can enqueue in advance, or dequeue and
process. They can also enqueue in a different order than buffers have
been dequeued, and the driver can <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>fill</I
></SPAN
> enqueued
<SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>empty</I
></SPAN
> buffers in any order. <A
NAME="AEN3329"
HREF="#FTN.AEN3329"
><SPAN
CLASS="footnote"
>[16]</SPAN
></A
> The index number of a buffer (struct <A
HREF="#V4L2-BUFFER"
>v4l2_buffer</A
>
<CODE
CLASS="STRUCTFIELD"
>index</CODE
>) plays no role here, it only
identifies the buffer.</P
><P
>Initially all mapped buffers are in dequeued state,
inaccessible by the driver. For capturing applications it is customary
to first enqueue all mapped buffers, then to start capturing and enter
the read loop. Here the application waits until a filled buffer can be
dequeued, and re-enqueues the buffer when the data is no longer
needed. Output applications fill and enqueue buffers, when enough
buffers are stacked up the output is started with
<CODE
CLASS="CONSTANT"
>VIDIOC_STREAMON</CODE
>. In the write loop, when
the application runs out of free buffers, it must wait until an empty
buffer can be dequeued and reused.</P
><P
>To enqueue and dequeue a buffer applications use the
<A
HREF="#VIDIOC-QBUF"
><CODE
CLASS="CONSTANT"
>VIDIOC_QBUF</CODE
></A
> and <A
HREF="#VIDIOC-QBUF"
><CODE
CLASS="CONSTANT"
>VIDIOC_DQBUF</CODE
></A
> ioctl. The status of a buffer being
mapped, enqueued, full or empty can be determined at any time using the
<A
HREF="#VIDIOC-QUERYBUF"
><CODE
CLASS="CONSTANT"
>VIDIOC_QUERYBUF</CODE
></A
> ioctl. Two methods exist to suspend execution of the
application until one or more buffers can be dequeued. By default
<CODE
CLASS="CONSTANT"
>VIDIOC_DQBUF</CODE
> blocks when no buffer is in the
outgoing queue. When the <CODE
CLASS="CONSTANT"
>O_NONBLOCK</CODE
> flag was
given to the <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
> function, <CODE
CLASS="CONSTANT"
>VIDIOC_DQBUF</CODE
>
returns immediately with an <SPAN
CLASS="ERRORCODE"
>EAGAIN</SPAN
> error code when no buffer is available. The
<A
HREF="#FUNC-SELECT"
><CODE
CLASS="FUNCTION"
>select()</CODE
></A
> or <A
HREF="#FUNC-POLL"
><CODE
CLASS="FUNCTION"
>poll()</CODE
></A
> function are always available.</P
><P
>To start and stop capturing or output applications call the
<A
HREF="#VIDIOC-STREAMON"
><CODE
CLASS="CONSTANT"
>VIDIOC_STREAMON</CODE
></A
> and <A
HREF="#VIDIOC-STREAMON"
><CODE
CLASS="CONSTANT"
>VIDIOC_STREAMOFF</CODE
></A
> ioctl. Note
<CODE
CLASS="CONSTANT"
>VIDIOC_STREAMOFF</CODE
> removes all buffers from both
queues as a side effect. Since there is no notion of doing anything
"now" on a multitasking system, if an application needs to synchronize
with another event it should examine the struct <A
HREF="#V4L2-BUFFER"
>v4l2_buffer</A
>
<CODE
CLASS="STRUCTFIELD"
>timestamp</CODE
> of captured buffers, or set the
field before enqueuing buffers for output.</P
><P
>Drivers implementing memory mapping I/O must
support the <CODE
CLASS="CONSTANT"
>VIDIOC_REQBUFS</CODE
>,
<CODE
CLASS="CONSTANT"
>VIDIOC_QUERYBUF</CODE
>,
<CODE
CLASS="CONSTANT"
>VIDIOC_QBUF</CODE
>, <CODE
CLASS="CONSTANT"
>VIDIOC_DQBUF</CODE
>,
<CODE
CLASS="CONSTANT"
>VIDIOC_STREAMON</CODE
> and
<CODE
CLASS="CONSTANT"
>VIDIOC_STREAMOFF</CODE
> ioctl, the
<CODE
CLASS="FUNCTION"
>mmap()</CODE
>, <CODE
CLASS="FUNCTION"
>munmap()</CODE
>,
<CODE
CLASS="FUNCTION"
>select()</CODE
> and <CODE
CLASS="FUNCTION"
>poll()</CODE
>
function.<A
NAME="AEN3371"
HREF="#FTN.AEN3371"
><SPAN
CLASS="footnote"
>[17]</SPAN
></A
></P
><P
>[capture example]</P
></DIV
><DIV
CLASS="SECTION"
><HR><H2
CLASS="SECTION"
><A
NAME="USERP"
>3.3. Streaming I/O (User Pointers)</A
></H2
><P
>Input and output devices support this I/O method when the
<CODE
CLASS="CONSTANT"
>V4L2_CAP_STREAMING</CODE
> flag in the
<CODE
CLASS="STRUCTFIELD"
>capabilities</CODE
> field of struct <A
HREF="#V4L2-CAPABILITY"
>v4l2_capability</A
>
returned by the <A
HREF="#VIDIOC-QUERYCAP"
><CODE
CLASS="CONSTANT"
>VIDIOC_QUERYCAP</CODE
></A
> ioctl is set. If the particular user
pointer method (not only memory mapping) is supported must be
determined by calling the <A
HREF="#VIDIOC-REQBUFS"
><CODE
CLASS="CONSTANT"
>VIDIOC_REQBUFS</CODE
></A
> ioctl.</P
><P
>This I/O method combines advantages of the read/write and
memory mapping methods. Buffers are allocated by the application
itself, and can reside for example in virtual or shared memory. Only
pointers to data are exchanged, these pointers and meta-information
are passed in struct <A
HREF="#V4L2-BUFFER"
>v4l2_buffer</A
>. The driver must be switched
into user pointer I/O mode by calling the <A
HREF="#VIDIOC-REQBUFS"
><CODE
CLASS="CONSTANT"
>VIDIOC_REQBUFS</CODE
></A
> with the
desired buffer type. No buffers are allocated beforehands,
consequently they are not indexed and cannot be queried like mapped
buffers with the <CODE
CLASS="CONSTANT"
>VIDIOC_QUERYBUF</CODE
> ioctl.</P
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN3392"
></A
><P
><B
>Example 3-2. Initiating streaming I/O with user pointers</B
></P
><PRE
CLASS="PROGRAMLISTING"
>struct <A
HREF="#V4L2-REQUESTBUFFERS"
>v4l2_requestbuffers</A
> reqbuf;
memset (&reqbuf, 0, sizeof (reqbuf));
reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
reqbuf.memory = V4L2_MEMORY_USERPTR;
if (ioctl (fd, <A
HREF="#VIDIOC-REQBUFS"
><CODE
CLASS="CONSTANT"
>VIDIOC_REQBUFS</CODE
></A
>, &reqbuf) == -1) {
if (errno == EINVAL)
printf ("Video capturing or user pointer streaming is not supported\n");
else
perror ("VIDIOC_REQBUFS");
exit (EXIT_FAILURE);
}
</PRE
></DIV
><P
>Buffer addresses and sizes are passed on the fly with the
<A
HREF="#VIDIOC-QBUF"
><CODE
CLASS="CONSTANT"
>VIDIOC_QBUF</CODE
></A
> ioctl. Although buffers are commonly cycled,
applications can pass different addresses and sizes at each
<CODE
CLASS="CONSTANT"
>VIDIOC_QBUF</CODE
> call. If required by the hardware the
driver swaps memory pages within physical memory to create a
continuous area of memory. This happens transparently to the
application in the virtual memory subsystem of the kernel. When buffer
pages have been swapped out to disk they are brought back and finally
locked in physical memory for DMA.<A
NAME="AEN3402"
HREF="#FTN.AEN3402"
><SPAN
CLASS="footnote"
>[18]</SPAN
></A
></P
><P
>Filled or displayed buffers are dequeued with the
<A
HREF="#VIDIOC-QBUF"
><CODE
CLASS="CONSTANT"
>VIDIOC_DQBUF</CODE
></A
> ioctl. The driver can unlock the memory pages at any
time between the completion of the DMA and this ioctl. The memory is
also unlocked when <A
HREF="#VIDIOC-STREAMON"
><CODE
CLASS="CONSTANT"
>VIDIOC_STREAMOFF</CODE
></A
> is called, <A
HREF="#VIDIOC-REQBUFS"
><CODE
CLASS="CONSTANT"
>VIDIOC_REQBUFS</CODE
></A
>, or
when the device is closed. Applications must take care not to free
buffers without dequeuing. For once, the buffers remain locked until
further, wasting physical memory. Second the driver will not be
notified when the memory is returned to the application's free list
and subsequently reused for other purposes, possibly completing the
requested DMA and overwriting valuable data.</P
><P
>For capturing applications it is customary to enqueue a
number of empty buffers, to start capturing and enter the read loop.
Here the application waits until a filled buffer can be dequeued, and
re-enqueues the buffer when the data is no longer needed. Output
applications fill and enqueue buffers, when enough buffers are stacked
up output is started. In the write loop, when the application
runs out of free buffers it must wait until an empty buffer can be
dequeued and reused. Two methods exist to suspend execution of the
application until one or more buffers can be dequeued. By default
<CODE
CLASS="CONSTANT"
>VIDIOC_DQBUF</CODE
> blocks when no buffer is in the
outgoing queue. When the <CODE
CLASS="CONSTANT"
>O_NONBLOCK</CODE
> flag was
given to the <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
> function, <CODE
CLASS="CONSTANT"
>VIDIOC_DQBUF</CODE
>
returns immediately with an <SPAN
CLASS="ERRORCODE"
>EAGAIN</SPAN
> error code when no buffer is available. The
<A
HREF="#FUNC-SELECT"
><CODE
CLASS="FUNCTION"
>select()</CODE
></A
> or <A
HREF="#FUNC-POLL"
><CODE
CLASS="FUNCTION"
>poll()</CODE
></A
> function are always available.</P
><P
>To start and stop capturing or output applications call the
<A
HREF="#VIDIOC-STREAMON"
><CODE
CLASS="CONSTANT"
>VIDIOC_STREAMON</CODE
></A
> and <A
HREF="#VIDIOC-STREAMON"
><CODE
CLASS="CONSTANT"
>VIDIOC_STREAMOFF</CODE
></A
> ioctl. Note
<CODE
CLASS="CONSTANT"
>VIDIOC_STREAMOFF</CODE
> removes all buffers from both
queues and unlocks all buffers as a side effect. Since there is no
notion of doing anything "now" on a multitasking system, if an
application needs to synchronize with another event it should examine
the struct <A
HREF="#V4L2-BUFFER"
>v4l2_buffer</A
> <CODE
CLASS="STRUCTFIELD"
>timestamp</CODE
> of captured
buffers, or set the field before enqueuing buffers for output.</P
><P
>Drivers implementing user pointer I/O must
support the <CODE
CLASS="CONSTANT"
>VIDIOC_REQBUFS</CODE
>,
<CODE
CLASS="CONSTANT"
>VIDIOC_QBUF</CODE
>, <CODE
CLASS="CONSTANT"
>VIDIOC_DQBUF</CODE
>,
<CODE
CLASS="CONSTANT"
>VIDIOC_STREAMON</CODE
> and
<CODE
CLASS="CONSTANT"
>VIDIOC_STREAMOFF</CODE
> ioctl, the
<CODE
CLASS="FUNCTION"
>select()</CODE
> and <CODE
CLASS="FUNCTION"
>poll()</CODE
> function.<A
NAME="AEN3438"
HREF="#FTN.AEN3438"
><SPAN
CLASS="footnote"
>[19]</SPAN
></A
></P
></DIV
><DIV
CLASS="SECTION"
><HR><H2
CLASS="SECTION"
><A
NAME="ASYNC"
>3.4. Asynchronous I/O</A
></H2
><P
>This method is not defined yet.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H2
CLASS="SECTION"
><A
NAME="BUFFER"
>3.5. Buffers</A
></H2
><P
>A buffer contains data exchanged by application and
driver using one of the Streaming I/O methods. Only pointers to
buffers are exchanged, the data itself is not copied. These pointers,
together with meta-information like timestamps or field parity, are
stored in a struct <CODE
CLASS="STRUCTNAME"
>v4l2_buffer</CODE
>, argument to
the <A
HREF="#VIDIOC-QUERYBUF"
><CODE
CLASS="CONSTANT"
>VIDIOC_QUERYBUF</CODE
></A
>, <A
HREF="#VIDIOC-QBUF"
><CODE
CLASS="CONSTANT"
>VIDIOC_QBUF</CODE
></A
> and <A
HREF="#VIDIOC-QBUF"
><CODE
CLASS="CONSTANT"
>VIDIOC_DQBUF</CODE
></A
> ioctl.</P
><P
>Nominally timestamps refer to the first data byte transmitted.
In practice however the wide range of hardware covered by the V4L2 API
limits timestamp accuracy. Often an interrupt routine will
sample the system clock shortly after the field or frame was stored
completely in memory. So applications must expect a constant
difference up to one field or frame period plus a small (few scan
lines) random error. The delay and error can be much
larger due to compression or transmission over an external bus when
the frames are not properly stamped by the sender. This is frequently
the case with USB cameras. Here timestamps refer to the instant the
field or frame was received by the driver, not the capture time. These
devices identify by not enumerating any video standards, see <A
HREF="#STANDARD"
>Section 1.7</A
>.</P
><P
>Similar limitations apply to output timestamps. Typically
the video hardware locks to a clock controlling the video timing, the
horizontal and vertical synchronization pulses. At some point in the
line sequence, possibly the vertical blanking, an interrupt routine
samples the system clock, compares against the timestamp and programs
the hardware to repeat the previous field or frame, or to display the
buffer contents.</P
><P
>Apart of limitations of the video device and natural
inaccuracies of all clocks, it should be noted system time itself is
not perfectly stable. It can be affected by power saving cycles,
warped to insert leap seconds, or even turned back or forth by the
system administrator affecting long term measurements. <A
NAME="AEN3460"
HREF="#FTN.AEN3460"
><SPAN
CLASS="footnote"
>[20]</SPAN
></A
></P
><DIV
CLASS="TABLE"
><A
NAME="V4L2-BUFFER"
></A
><P
><B
>Table 3-1. struct <CODE
CLASS="STRUCTNAME"
>v4l2_buffer</CODE
></B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="50%"
TITLE="C1"><COL><COL><COL
WIDTH="50%"
TITLE="C4"><TBODY
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>index</CODE
></TD
><TD
> </TD
><TD
>Number of the buffer, set by the application. This
field is only used for <A
HREF="#MMAP"
>memory mapping</A
> I/O
and can range from zero to the number of buffers allocated
with the <A
HREF="#VIDIOC-REQBUFS"
><CODE
CLASS="CONSTANT"
>VIDIOC_REQBUFS</CODE
></A
> ioctl (struct <A
HREF="#V4L2-REQUESTBUFFERS"
>v4l2_requestbuffers</A
> <CODE
CLASS="STRUCTFIELD"
>count</CODE
>) minus one.</TD
></TR
><TR
><TD
>enum <A
HREF="#V4L2-BUF-TYPE"
>v4l2_buf_type</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>type</CODE
></TD
><TD
> </TD
><TD
>Type of the buffer, same as struct <A
HREF="#V4L2-FORMAT"
>v4l2_format</A
>
<CODE
CLASS="STRUCTFIELD"
>type</CODE
> or struct <A
HREF="#V4L2-REQUESTBUFFERS"
>v4l2_requestbuffers</A
>
<CODE
CLASS="STRUCTFIELD"
>type</CODE
>, set by the application.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>bytesused</CODE
></TD
><TD
> </TD
><TD
>The number of bytes occupied by the data in the
buffer. It depends on the negotiated data format and may change with
each buffer for compressed variable size data like JPEG images.
Drivers must set this field when <CODE
CLASS="STRUCTFIELD"
>type</CODE
>
refers to an input stream, applications when an output stream.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>flags</CODE
></TD
><TD
> </TD
><TD
>Flags set by the application or driver, see <A
HREF="#BUFFER-FLAGS"
>Table 3-3</A
>.</TD
></TR
><TR
><TD
>enum <A
HREF="#V4L2-FIELD"
>v4l2_field</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>field</CODE
></TD
><TD
> </TD
><TD
>Indicates the field order of the image in the
buffer, see <A
HREF="#V4L2-FIELD"
>Table 3-8</A
>. This field is not used when
the buffer contains VBI data. Drivers must set it when
<CODE
CLASS="STRUCTFIELD"
>type</CODE
> refers to an input stream,
applications when an output stream.</TD
></TR
><TR
><TD
>struct timeval</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>timestamp</CODE
></TD
><TD
> </TD
><TD
><P
>For input streams this is the
system time (as returned by the <CODE
CLASS="FUNCTION"
>gettimeofday()</CODE
>
function) when the first data byte was captured. For output streams
the data will not be displayed before this time, secondary to the
nominal frame rate determined by the current video standard in
enqueued order. Applications can for example zero this field to
display frames as soon as possible. The driver stores the time at
which the first data byte was actually sent out in the
<CODE
CLASS="STRUCTFIELD"
>timestamp</CODE
> field. This permits
applications to monitor the drift between the video and system
clock.</P
></TD
></TR
><TR
><TD
>struct <A
HREF="#V4L2-TIMECODE"
>v4l2_timecode</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>timecode</CODE
></TD
><TD
> </TD
><TD
>When <CODE
CLASS="STRUCTFIELD"
>type</CODE
> is
<CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_VIDEO_CAPTURE</CODE
> and the
<CODE
CLASS="CONSTANT"
>V4L2_BUF_FLAG_TIMECODE</CODE
> flag is set in
<CODE
CLASS="STRUCTFIELD"
>flags</CODE
>, this structure contains a frame
timecode. In <A
HREF="#V4L2-FIELD"
>V4L2_FIELD_ALTERNATE</A
>
mode the top and bottom field contain the same timecode.
Timecodes are intended to help video editing and are typically recorded on
video tapes, but also embedded in compressed formats like MPEG. This
field is independent of the <CODE
CLASS="STRUCTFIELD"
>timestamp</CODE
> and
<CODE
CLASS="STRUCTFIELD"
>sequence</CODE
> fields.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>sequence</CODE
></TD
><TD
> </TD
><TD
>Set by the driver, counting the frames in the
sequence.</TD
></TR
><TR
><TD
COLSPAN="4"
><P
>In <A
HREF="#V4L2-FIELD"
>V4L2_FIELD_ALTERNATE</A
> mode the top and
bottom field have the same sequence number. The count starts at zero
and includes dropped or repeated frames. A dropped frame was received
by an input device but could not be stored due to lack of free buffer
space. A repeated frame was displayed again by an output device
because the application did not pass new data in
time.</P
><P
>Note this may count the frames received
e.g. over USB, without taking into account the frames dropped by the
remote hardware due to limited compression throughput or bus
bandwidth. These devices identify by not enumerating any video
standards, see <A
HREF="#STANDARD"
>Section 1.7</A
>.</P
></TD
></TR
><TR
><TD
>enum <A
HREF="#V4L2-MEMORY"
>v4l2_memory</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>memory</CODE
></TD
><TD
> </TD
><TD
>This field must be set by applications and/or drivers
in accordance with the selected I/O method.</TD
></TR
><TR
><TD
>union</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>m</CODE
></TD
><TD
> </TD
><TD
> </TD
></TR
><TR
><TD
> </TD
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>offset</CODE
></TD
><TD
>When <CODE
CLASS="STRUCTFIELD"
>memory</CODE
> is
<CODE
CLASS="CONSTANT"
>V4L2_MEMORY_MMAP</CODE
> this is the offset of the buffer
from the start of the device memory. The value is returned by the
driver and apart of serving as parameter to the <A
HREF="#FUNC-MMAP"
><CODE
CLASS="FUNCTION"
>mmap()</CODE
></A
> function
not useful for applications. See <A
HREF="#MMAP"
>Section 3.2</A
> for details.</TD
></TR
><TR
><TD
> </TD
><TD
>unsigned long</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>userptr</CODE
></TD
><TD
>When <CODE
CLASS="STRUCTFIELD"
>memory</CODE
> is
<CODE
CLASS="CONSTANT"
>V4L2_MEMORY_USERPTR</CODE
> this is a pointer to the
buffer (casted to unsigned long type) in virtual memory, set by the
application. See <A
HREF="#USERP"
>Section 3.3</A
> for details.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>length</CODE
></TD
><TD
> </TD
><TD
>Size of the buffer (not the payload) in bytes.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>input</CODE
></TD
><TD
> </TD
><TD
>Some video capture drivers support rapid and
synchronous video input changes, a function useful for example in
video surveillance applications. For this purpose applications set the
<CODE
CLASS="CONSTANT"
>V4L2_BUF_FLAG_INPUT</CODE
> flag, and this field to the
number of a video input as in struct <A
HREF="#V4L2-INPUT"
>v4l2_input</A
> field
<CODE
CLASS="STRUCTFIELD"
>index</CODE
>.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>reserved</CODE
></TD
><TD
> </TD
><TD
>A place holder for future extensions and custom
(driver defined) buffer types
<CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_PRIVATE</CODE
> and higher.</TD
></TR
></TBODY
></TABLE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="V4L2-BUF-TYPE"
></A
><P
><B
>Table 3-2. enum v4l2_buf_type</B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="38%"
TITLE="C1"><COL
WIDTH="12%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_VIDEO_CAPTURE</CODE
></TD
><TD
>1</TD
><TD
>Buffer of a video capture stream, see <A
HREF="#CAPTURE"
>Section 4.1</A
>.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_VIDEO_OUTPUT</CODE
></TD
><TD
>2</TD
><TD
>Buffer of a video output stream, see <A
HREF="#OUTPUT"
>Section 4.3</A
>.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_VIDEO_OVERLAY</CODE
></TD
><TD
>3</TD
><TD
>Buffer for video overlay, see <A
HREF="#OVERLAY"
>Section 4.2</A
>.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_VBI_CAPTURE</CODE
></TD
><TD
>4</TD
><TD
>Buffer of a raw VBI capture stream, see <A
HREF="#RAW-VBI"
>Section 4.6</A
>.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_VBI_OUTPUT</CODE
></TD
><TD
>5</TD
><TD
>Buffer of a raw VBI output stream, see <A
HREF="#RAW-VBI"
>Section 4.6</A
>.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_PRIVATE</CODE
></TD
><TD
>0x80</TD
><TD
>This and higher values are reserved for custom
(driver defined) buffer types.</TD
></TR
></TBODY
></TABLE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="BUFFER-FLAGS"
></A
><P
><B
>Table 3-3. Buffer Flags</B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="38%"
TITLE="C1"><COL
WIDTH="12%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_BUF_FLAG_MAPPED</CODE
></TD
><TD
>0x0001</TD
><TD
>The buffer resides in device memory and has been mapped
into the application's address space, see <A
HREF="#MMAP"
>Section 3.2</A
> for details.
Drivers set or clear this flag when the
<A
HREF="#VIDIOC-QUERYBUF"
>VIDIOC_QUERYBUF</A
>, <A
HREF="#VIDIOC-QBUF"
>VIDIOC_QBUF</A
> or <A
HREF="#VIDIOC-QBUF"
>VIDIOC_DQBUF</A
> ioctl is called. Set by the driver.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_BUF_FLAG_QUEUED</CODE
></TD
><TD
>0x0002</TD
><TD
>Internally drivers maintain two buffer queues, an
incoming and outgoing queue. When this flag is set, the buffer is
currently on the incoming queue. It automatically moves to the
outgoing queue after the buffer has been filled (capture devices) or
displayed (output devices). Drivers set or clear this flag when the
<CODE
CLASS="CONSTANT"
>VIDIOC_QUERYBUF</CODE
> ioctl is called. After
(successful) calling the <CODE
CLASS="CONSTANT"
>VIDIOC_QBUF </CODE
>ioctl it is
always set and after <CODE
CLASS="CONSTANT"
>VIDIOC_DQBUF</CODE
> always
cleared.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_BUF_FLAG_DONE</CODE
></TD
><TD
>0x0004</TD
><TD
>When this flag is set, the buffer is currently on
the outgoing queue, ready to be dequeued from the driver. Drivers set
or clear this flag when the <CODE
CLASS="CONSTANT"
>VIDIOC_QUERYBUF</CODE
> ioctl
is called. After calling the <CODE
CLASS="CONSTANT"
>VIDIOC_QBUF</CODE
> or
<CODE
CLASS="CONSTANT"
>VIDIOC_DQBUF</CODE
> it is always cleared. Of course a
buffer cannot be on both queues at the same time, the
<CODE
CLASS="CONSTANT"
>V4L2_BUF_FLAG_QUEUED</CODE
> and
<CODE
CLASS="CONSTANT"
>V4L2_BUF_FLAG_DONE</CODE
> flag are mutually exclusive.
They can be both cleared however, then the buffer is in "dequeued"
state, in the application domain to say so.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_BUF_FLAG_KEYFRAME</CODE
></TD
><TD
>0x0008</TD
><TD
>Drivers set or clear this flag when calling the
<CODE
CLASS="CONSTANT"
>VIDIOC_DQBUF</CODE
> ioctl. It may be set by video
capture devices when the buffer contains a compressed image which is a
key frame (or field), i.e. can be decompressed on its own.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_BUF_FLAG_PFRAME</CODE
></TD
><TD
>0x0010</TD
><TD
>Similar to <CODE
CLASS="CONSTANT"
>V4L2_BUF_FLAG_KEYFRAME</CODE
>
this flags predicted frames or fields which contain only differences to a
previous key frame.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_BUF_FLAG_BFRAME</CODE
></TD
><TD
>0x0020</TD
><TD
>Similar to <CODE
CLASS="CONSTANT"
>V4L2_BUF_FLAG_PFRAME</CODE
>
this is a bidirectional predicted frame or field. [ooc tbd]</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_BUF_FLAG_TIMECODE</CODE
></TD
><TD
>0x0100</TD
><TD
>The <CODE
CLASS="STRUCTFIELD"
>timecode</CODE
> field is valid.
Drivers set or clear this flag when the <CODE
CLASS="CONSTANT"
>VIDIOC_DQBUF</CODE
>
ioctl is called.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_BUF_FLAG_INPUT</CODE
></TD
><TD
>0x0200</TD
><TD
>The <CODE
CLASS="STRUCTFIELD"
>input</CODE
> field is valid.
Applications set or clear this flag before calling the
<CODE
CLASS="CONSTANT"
>VIDIOC_QBUF</CODE
> ioctl.</TD
></TR
></TBODY
></TABLE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="V4L2-MEMORY"
></A
><P
><B
>Table 3-4. enum v4l2_memory</B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="38%"
TITLE="C1"><COL
WIDTH="12%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_MEMORY_MMAP</CODE
></TD
><TD
>1</TD
><TD
>The buffer is used for <A
HREF="#MMAP"
>memory
mapping</A
> I/O.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_MEMORY_USERPTR</CODE
></TD
><TD
>2</TD
><TD
>The buffer is used for <A
HREF="#USERP"
>user
pointer</A
> I/O.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_MEMORY_OVERLAY</CODE
></TD
><TD
>3</TD
><TD
>[to do]</TD
></TR
></TBODY
></TABLE
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN3738"
>3.5.1. Timecodes</A
></H3
><P
>The <CODE
CLASS="STRUCTNAME"
>v4l2_timecode</CODE
> structure is
designed to hold a <A
HREF="#SMPTE12M"
><ABBR
CLASS="ABBREV"
>SMPTE12M</ABBR
></A
> or similar timecode.
(struct <CODE
CLASS="STRUCTNAME"
>timeval</CODE
> timestamps are stored in
struct <A
HREF="#V4L2-BUFFER"
>v4l2_buffer</A
> field <CODE
CLASS="STRUCTFIELD"
>timestamp</CODE
>.)</P
><DIV
CLASS="TABLE"
><A
NAME="V4L2-TIMECODE"
></A
><P
><B
>Table 3-5. struct <CODE
CLASS="STRUCTNAME"
>v4l2_timecode</CODE
></B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="25%"
TITLE="C1"><COL
WIDTH="25%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>type</CODE
></TD
><TD
>Frame rate the timecodes are based on, see <A
HREF="#TIMECODE-TYPE"
>Table 3-6</A
>.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>flags</CODE
></TD
><TD
>Timecode flags, see <A
HREF="#TIMECODE-FLAGS"
>Table 3-7</A
>.</TD
></TR
><TR
><TD
>__u8</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>frames</CODE
></TD
><TD
>Frame count, 0 ... 23/24/29/49/59, depending on the
type of timecode.</TD
></TR
><TR
><TD
>__u8</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>seconds</CODE
></TD
><TD
>Seconds count, 0 ... 59. This is a binary, not BCD number.</TD
></TR
><TR
><TD
>__u8</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>minutes</CODE
></TD
><TD
>Minutes count, 0 ... 59. This is a binary, not BCD number.</TD
></TR
><TR
><TD
>__u8</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>hours</CODE
></TD
><TD
>Hours count, 0 ... 29. This is a binary, not BCD number.</TD
></TR
><TR
><TD
>__u8</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>userbits</CODE
>[4]</TD
><TD
>The "user group" bits from the timecode.</TD
></TR
></TBODY
></TABLE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="TIMECODE-TYPE"
></A
><P
><B
>Table 3-6. Timecode Types</B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="38%"
TITLE="C1"><COL
WIDTH="12%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_TC_TYPE_24FPS</CODE
></TD
><TD
>1</TD
><TD
>24 frames per second, i. e. film.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_TC_TYPE_25FPS</CODE
></TD
><TD
>2</TD
><TD
>25 frames per second, i.e. PAL or SECAM video.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_TC_TYPE_30FPS</CODE
></TD
><TD
>3</TD
><TD
>30 frames per second, i.e. NTSC video.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_TC_TYPE_50FPS</CODE
></TD
><TD
>4</TD
><TD
> </TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_TC_TYPE_60FPS</CODE
></TD
><TD
>5</TD
><TD
> </TD
></TR
></TBODY
></TABLE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="TIMECODE-FLAGS"
></A
><P
><B
>Table 3-7. Timecode Flags</B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="38%"
TITLE="C1"><COL
WIDTH="12%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_TC_FLAG_DROPFRAME</CODE
></TD
><TD
>0x0001</TD
><TD
>Indicates "drop frame" semantics for counting frames
in 29.97 fps material. When set, frame numbers 0 and 1 at the start of
each minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the
count.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_TC_FLAG_COLORFRAME</CODE
></TD
><TD
>0x0002</TD
><TD
>The "color frame" flag.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_TC_USERBITS_field</CODE
></TD
><TD
>0x000C</TD
><TD
>Field mask for the "binary group flags".</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_TC_USERBITS_USERDEFINED</CODE
></TD
><TD
>0x0000</TD
><TD
>Unspecified format.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_TC_USERBITS_8BITCHARS</CODE
></TD
><TD
>0x0008</TD
><TD
>8-bit ISO characters.</TD
></TR
></TBODY
></TABLE
></DIV
></DIV
></DIV
><DIV
CLASS="SECTION"
><HR><H2
CLASS="SECTION"
><A
NAME="FIELD-ORDER"
>3.6. Field Order</A
></H2
><P
>We have to distinguish between progressive and interlaced
video. Progressive video transmits all lines of a video image
sequentially. Interlaced video divides an image into two fields,
containing only the odd and even lines of the image, respectively.
Alternating the so called odd and even field are transmitted, and due
to a small delay between fields a cathode ray TV displays the lines
interleaved, yielding the original frame. This curious technique was
invented because at refresh rates similar to film the image would
fade out too quickly. Transmitting fields reduces the flicker without
the necessity of doubling the frame rate and with it the bandwidth
required for each channel.</P
><P
>It is important to understand a video camera does not expose
one frame at a time, merely transmitting the frames separated into
fields. The fields are in fact captured at two different instances in
time. An object on screen may well move between one field and the
next. For applications analysing motion it is of paramount importance
to recognize which field of a frame is older, the <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>temporal
order</I
></SPAN
>.</P
><P
>When the driver provides or accepts images field by field
rather than interleaved, it is also important applications understand
how the fields combine to frames. We distinguish between top and
bottom fields, the <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>spatial order</I
></SPAN
>: The first line
of the top field is the first line of an interlaced frame, the first
line of the bottom field is the second line of that frame.</P
><P
>However because fields were captured one after the other,
arguing whether a frame commences with the top or bottom field is
pointless. Any two successive top and bottom, or bottom and top fields
yield a valid frame. Only when the source was progressive to begin
with, e. g. when transferring film to video, two fields may come from
the same frame, creating a natural order.</P
><P
>Counter to intuition the top field is not necessarily the
older field. Whether the older field contains the top or bottom lines
is a convention determined by the video standard. Hence the
distinction between temporal and spatial order of fields. The diagrams
below should make this clearer.</P
><P
>All video capture and output devices must report the current
field order. Some drivers may permit the selection of a different
order, to this end applications initialize the
<CODE
CLASS="STRUCTFIELD"
>field</CODE
> field of struct <A
HREF="#V4L2-PIX-FORMAT"
>v4l2_pix_format</A
> before
calling the <A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
></A
> ioctl. If this is not desired it should
have the value <CODE
CLASS="CONSTANT"
>V4L2_FIELD_ANY</CODE
> (0).</P
><DIV
CLASS="TABLE"
><A
NAME="V4L2-FIELD"
></A
><P
><B
>Table 3-8. enum v4l2_field</B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="38%"
TITLE="C1"><COL
WIDTH="12%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_FIELD_ANY</CODE
></TD
><TD
>0</TD
><TD
>Applications request this field order when any
one of the <CODE
CLASS="CONSTANT"
>V4L2_FIELD_NONE</CODE
>,
<CODE
CLASS="CONSTANT"
>V4L2_FIELD_TOP</CODE
>,
<CODE
CLASS="CONSTANT"
>V4L2_FIELD_BOTTOM</CODE
>, or
<CODE
CLASS="CONSTANT"
>V4L2_FIELD_INTERLACED</CODE
> formats is acceptable.
Drivers choose depending on hardware capabilities or e. g. the
requested image size, and return the actual field order. struct <A
HREF="#V4L2-BUFFER"
>v4l2_buffer</A
>
<CODE
CLASS="STRUCTFIELD"
>field</CODE
> can never be
<CODE
CLASS="CONSTANT"
>V4L2_FIELD_ANY</CODE
>.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_FIELD_NONE</CODE
></TD
><TD
>1</TD
><TD
>Images are in progressive format, not interlaced.
The driver may also indicate this order when it cannot distinguish
between <CODE
CLASS="CONSTANT"
>V4L2_FIELD_TOP</CODE
> and
<CODE
CLASS="CONSTANT"
>V4L2_FIELD_BOTTOM</CODE
>.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_FIELD_TOP</CODE
></TD
><TD
>2</TD
><TD
>Images consist of the top field only.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_FIELD_BOTTOM</CODE
></TD
><TD
>3</TD
><TD
>Images consist of the bottom field only.
Applications may wish to prevent a device from capturing interlaced
images because they will have "comb" or "feathering" artefacts around
moving objects.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_FIELD_INTERLACED</CODE
></TD
><TD
>4</TD
><TD
>Images contain both fields, interleaved line by
line. The temporal order of the fields (whether the top or bottom
field is first transmitted) depends on the current video standard.
M/NTSC transmits the bottom field first, all other standards the top
field first.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_FIELD_SEQ_TB</CODE
></TD
><TD
>5</TD
><TD
>Images contain both fields, the top field lines
are stored first in memory, immediately followed by the bottom field
lines. Fields are always stored in temporal order, the older one first
in memory. Image sizes refer to the frame, not fields.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_FIELD_SEQ_BT</CODE
></TD
><TD
>6</TD
><TD
>Images contain both fields, the bottom field
lines are stored first in memory, immediately followed by the top
field lines. Fields are always stored in temporal order, the older one
first in memory. Image sizes refer to the frame, not fields.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_FIELD_ALTERNATE</CODE
></TD
><TD
>7</TD
><TD
>The two fields of a frame are passed in separate
buffers, in temporal order, i. e. the older one first. To indicate the field
parity (whether the current field is a top or bottom field) the driver
or application, depending on data direction, must set struct <A
HREF="#V4L2-BUFFER"
>v4l2_buffer</A
>
<CODE
CLASS="STRUCTFIELD"
>field</CODE
> to
<CODE
CLASS="CONSTANT"
>V4L2_FIELD_TOP</CODE
> or
<CODE
CLASS="CONSTANT"
>V4L2_FIELD_BOTTOM</CODE
>. Any two successive fields pair
to build a frame. If fields are successive, without any dropped fields
between them (fields can drop individually), can be determined from
the struct <A
HREF="#V4L2-BUFFER"
>v4l2_buffer</A
> <CODE
CLASS="STRUCTFIELD"
>sequence</CODE
> field. Image
sizes refer to the frame, not fields. This format cannot be selected
when using the read/write I/O method.</TD
></TR
></TBODY
></TABLE
></DIV
><DIV
CLASS="FIGURE"
><A
NAME="FIELDSEQ-TB"
></A
><P
><B
>Figure 3-1. Field Order, Top Field First Transmitted</B
></P
><DIV
CLASS="MEDIAOBJECT"
><P
><IMG
SRC="fieldseq_tb.gif"></P
></DIV
></DIV
><DIV
CLASS="FIGURE"
><A
NAME="FIELDSEQ-BT"
></A
><P
><B
>Figure 3-2. Field Order, Bottom Field First Transmitted</B
></P
><DIV
CLASS="MEDIAOBJECT"
><P
><IMG
SRC="fieldseq_bt.gif"></P
></DIV
></DIV
></DIV
></DIV
><DIV
CLASS="CHAPTER"
><HR><H1
><A
NAME="DEVICES"
></A
>Chapter 4. Device Types</H1
><DIV
CLASS="SECTION"
><H2
CLASS="SECTION"
><A
NAME="CAPTURE"
>4.1. Video Capture Interface</A
></H2
><P
>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.</P
><P
>Conventionally V4L2 video capture devices are accessed through
character device special files named <TT
CLASS="FILENAME"
>/dev/video</TT
>
and <TT
CLASS="FILENAME"
>/dev/video0</TT
> to
<TT
CLASS="FILENAME"
>/dev/video63</TT
> with major number 81 and minor
numbers 0 to 63. <TT
CLASS="FILENAME"
>/dev/video</TT
> is typically a
symbolic link to the preferred video capture device.</P
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN3960"
>4.1.1. Querying Capabilities</A
></H3
><P
>Devices supporting the video capture interface set the
<CODE
CLASS="CONSTANT"
>V4L2_CAP_VIDEO_CAPTURE</CODE
> flag in the
<CODE
CLASS="STRUCTFIELD"
>capabilities</CODE
> field of struct <A
HREF="#V4L2-CAPABILITY"
>v4l2_capability</A
>
returned by the <A
HREF="#VIDIOC-QUERYCAP"
><CODE
CLASS="CONSTANT"
>VIDIOC_QUERYCAP</CODE
></A
>. As secondary device functions they
may also support the <A
HREF="#OVERLAY"
>video overlay</A
>
(<CODE
CLASS="CONSTANT"
>V4L2_CAP_VIDEO_OVERLAY</CODE
>) and the <A
HREF="#RAW-VBI"
>raw VBI capture</A
>
(<CODE
CLASS="CONSTANT"
>V4L2_CAP_VBI_CAPTURE</CODE
>) interface. At least one of
the read/write or streaming I/O methods must be supported. Tuners and
audio inputs are optional.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN3972"
>4.1.2. Supplemental Functions</A
></H3
><P
>Video capture devices shall support <A
HREF="#AUDIO"
>audio input</A
>, <A
HREF="#TUNER"
>tuner</A
>, <A
HREF="#CONTROL"
>controls</A
>,
<A
HREF="#CROP"
>cropping and scaling</A
> and <A
HREF="#STREAMING-PAR"
>streaming parameter</A
> ioctls as needed.
The <A
HREF="#VIDEO"
>video input</A
> and <A
HREF="#STANDARD"
>video standard</A
> ioctls must be supported by
all video capture devices.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN3982"
>4.1.3. Image Format Negotiation</A
></H3
><P
>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,
i. e. 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.</P
><P
>As usual these parameters are <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>not</I
></SPAN
>
reset at <CODE
CLASS="FUNCTION"
>open()</CODE
> 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.</P
><P
>Cropping initialization at minimum requires to reset the
parameters to defaults. An example is given in <A
HREF="#CROP"
>Section 1.10</A
>.</P
><P
>To query the current image format applications set the
<CODE
CLASS="STRUCTFIELD"
>type</CODE
> field of a struct <A
HREF="#V4L2-FORMAT"
>v4l2_format</A
> to
<CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_VIDEO_CAPTURE</CODE
> and call the
<A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_FMT</CODE
></A
> ioctl with a pointer to this structure. Drivers fill
the struct <A
HREF="#V4L2-PIX-FORMAT"
>v4l2_pix_format</A
> <CODE
CLASS="STRUCTFIELD"
>pix</CODE
> member of the
<CODE
CLASS="STRUCTFIELD"
>fmt</CODE
> union.</P
><P
>To request different parameters applications set the
<CODE
CLASS="STRUCTFIELD"
>type</CODE
> field of a struct <A
HREF="#V4L2-FORMAT"
>v4l2_format</A
> as above and
initialize all fields of the struct <A
HREF="#V4L2-PIX-FORMAT"
>v4l2_pix_format</A
>
<CODE
CLASS="STRUCTFIELD"
>vbi</CODE
> member of the
<CODE
CLASS="STRUCTFIELD"
>fmt</CODE
> union, or better just modify the
results of <CODE
CLASS="CONSTANT"
>VIDIOC_G_FMT</CODE
>, and call the
<A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
></A
> ioctl with a pointer to this structure. Drivers may
adjust the parameters and finally return the actual parameters as
<CODE
CLASS="CONSTANT"
>VIDIOC_G_FMT</CODE
> does.</P
><P
>Like <CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
> the
<A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_TRY_FMT</CODE
></A
> ioctl can be used to learn about hardware limitations
without disabling I/O or possibly time consuming hardware
preparations.</P
><P
>The contents of struct <A
HREF="#V4L2-PIX-FORMAT"
>v4l2_pix_format</A
> are discussed in <A
HREF="#PIXFMT"
>Chapter 2</A
>. See also the specification of the
<CODE
CLASS="CONSTANT"
>VIDIOC_G_FMT</CODE
>, <CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
>
and <CODE
CLASS="CONSTANT"
>VIDIOC_TRY_FMT</CODE
> ioctls for details. Video
capture devices must implement both the
<CODE
CLASS="CONSTANT"
>VIDIOC_G_FMT</CODE
> and
<CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
> ioctl, even if
<CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
> ignores all requests and always
returns default parameters as <CODE
CLASS="CONSTANT"
>VIDIOC_G_FMT</CODE
> does.
<CODE
CLASS="CONSTANT"
>VIDIOC_TRY_FMT</CODE
> is optional.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN4024"
>4.1.4. Reading Images</A
></H3
><P
>A video capture device may support the <A
HREF="#RW"
>read() function</A
> and/or streaming (<A
HREF="#MMAP"
>memory mapping</A
> or <A
HREF="#USERP"
>user pointer</A
>) I/O. See <A
HREF="#IO"
>Chapter 3</A
> for details.</P
></DIV
></DIV
><DIV
CLASS="SECTION"
><HR><H2
CLASS="SECTION"
><A
NAME="OVERLAY"
>4.2. Video Overlay Interface</A
></H2
><FONT
COLOR="RED"
>Also known as Frame Buffer Overlay or Previewing</FONT
><P
>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.</P
><P
>Video overlay devices are accessed through the same character
special files as <A
HREF="#CAPTURE"
>video capture</A
> devices.
Note the default function of a <TT
CLASS="FILENAME"
>/dev/video</TT
> device
is video capturing. The overlay function is only available after
calling the <A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
></A
> ioctl.</P
><P
>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.</P
><P
>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.<A
NAME="AEN4042"
HREF="#FTN.AEN4042"
><SPAN
CLASS="footnote"
>[21]</SPAN
></A
></P
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN4048"
>4.2.1. Querying Capabilities</A
></H3
><P
>Devices supporting the video overlay interface set the
<CODE
CLASS="CONSTANT"
>V4L2_CAP_VIDEO_OVERLAY</CODE
> flag in the
<CODE
CLASS="STRUCTFIELD"
>capabilities</CODE
> field of struct <A
HREF="#V4L2-CAPABILITY"
>v4l2_capability</A
>
returned by the <A
HREF="#VIDIOC-QUERYCAP"
><CODE
CLASS="CONSTANT"
>VIDIOC_QUERYCAP</CODE
></A
>. The overlay I/O method specified
below must be supported. Tuners and audio inputs are optional.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN4056"
>4.2.2. Supplemental Functions</A
></H3
><P
>Video overlay devices shall support <A
HREF="#AUDIO"
>audio input</A
>, <A
HREF="#TUNER"
>tuner</A
>, <A
HREF="#CONTROL"
>controls</A
>,
<A
HREF="#CROP"
>cropping and scaling</A
> and <A
HREF="#STREAMING-PAR"
>streaming parameter</A
> ioctls as needed.
The <A
HREF="#VIDEO"
>video input</A
> and <A
HREF="#STANDARD"
>video standard</A
> ioctls must be supported by
all video overlay devices.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN4066"
>4.2.3. Setup</A
></H3
><P
>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
<A
HREF="#VIDIOC-G-FBUF"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_FBUF</CODE
></A
> and <A
HREF="#VIDIOC-G-FBUF"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_FBUF</CODE
></A
> ioctls are available to get
and set these parameters, respectively. The
<CODE
CLASS="CONSTANT"
>VIDIOC_S_FBUF</CODE
> 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.</P
><P
>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 <CODE
CLASS="CONSTANT"
>VIDIOC_S_FBUF</CODE
> ioctl
is not privileged. An application can check for this type of device by
calling the <CODE
CLASS="CONSTANT"
>VIDIOC_G_FBUF</CODE
> ioctl.</P
><P
>A driver may support any (or none) of three clipping
methods:<P
></P
><OL
TYPE="1"
><LI
><P
>Chroma-keying displays the overlaid image only where
pixels in the primary graphics surface assume a certain color.</P
></LI
><LI
><P
>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.</P
></LI
><LI
><P
>A list of clipping rectangles can be specified. In
these regions <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>no</I
></SPAN
> video is displayed, so the
graphics surface can be seen here.</P
></LI
></OL
></P
><P
>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
(<A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
></A
>) or overlay (<A
HREF="#VIDIOC-G-FBUF"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_FBUF</CODE
></A
>) may fail with an
<SPAN
CLASS="ERRORCODE"
>EBUSY</SPAN
> error code or return accordingly modified parameters..</P
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN4092"
>4.2.4. Overlay Window</A
></H3
><P
>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 <A
HREF="#CROP"
>Section 1.10</A
>.</P
><P
>The overlay window is described by a struct <A
HREF="#V4L2-WINDOW"
>v4l2_window</A
>. 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 <CODE
CLASS="STRUCTFIELD"
>type</CODE
> field of a struct <A
HREF="#V4L2-FORMAT"
>v4l2_format</A
> to
<CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_VIDEO_OVERLAY</CODE
> and call the
<A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_FMT</CODE
></A
> ioctl. The driver fills the
<CODE
CLASS="STRUCTNAME"
>v4l2_window</CODE
> substructure named
<CODE
CLASS="STRUCTFIELD"
>win</CODE
>. Retrieving a previously programmed
clipping list or bitmap is not possible.</P
><P
>To program the overlay window applications set the
<CODE
CLASS="STRUCTFIELD"
>type</CODE
> field of a struct <A
HREF="#V4L2-FORMAT"
>v4l2_format</A
> to
<CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_VIDEO_OVERLAY</CODE
>, initialize the
<CODE
CLASS="STRUCTFIELD"
>win</CODE
> substructure and call the
<A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
></A
> ioctl. The driver adjusts the parameters against
hardware limits and returns the actual parameters as
<CODE
CLASS="CONSTANT"
>VIDIOC_G_FMT</CODE
> does. Like
<CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
>, the <A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_TRY_FMT</CODE
></A
> ioctl can be
used to learn about driver capabilities without actually changing
driver state. Unlike <CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
> this also works
after the overlay has been enabled.</P
><P
>The scaling factor of the overlaid image is implied by the
width and height given in struct <A
HREF="#V4L2-WINDOW"
>v4l2_window</A
> and the size of the cropping
rectangle. For more information see <A
HREF="#CROP"
>Section 1.10</A
>.</P
><P
>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 (<A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
></A
>) may fail with an <SPAN
CLASS="ERRORCODE"
>EBUSY</SPAN
> error code or return accordingly
modified parameters.</P
><DIV
CLASS="TABLE"
><A
NAME="V4L2-WINDOW"
></A
><P
><B
>Table 4-1. struct <CODE
CLASS="STRUCTNAME"
>v4l2_window</CODE
></B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="25%"
TITLE="C1"><COL
WIDTH="25%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
>struct <A
HREF="#V4L2-RECT"
>v4l2_rect</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>w</CODE
></TD
><TD
>Size and position of the window relative to the
top, left corner of the frame buffer defined with <A
HREF="#VIDIOC-G-FBUF"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_FBUF</CODE
></A
>. The
window can extend the frame buffer width and height, the
<CODE
CLASS="STRUCTFIELD"
>x</CODE
> and <CODE
CLASS="STRUCTFIELD"
>y</CODE
>
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.</TD
></TR
><TR
><TD
>enum <A
HREF="#V4L2-FIELD"
>v4l2_field</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>field</CODE
></TD
><TD
>Applications set this field to determine which
video field shall be overlaid, typically one of
<CODE
CLASS="CONSTANT"
>V4L2_FIELD_ANY</CODE
> (0),
<CODE
CLASS="CONSTANT"
>V4L2_FIELD_TOP</CODE
>,
<CODE
CLASS="CONSTANT"
>V4L2_FIELD_BOTTOM</CODE
> or
<CODE
CLASS="CONSTANT"
>V4L2_FIELD_INTERLACED</CODE
>. Drivers may have to choose
a different field order and return the actual setting here.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>chromakey</CODE
></TD
><TD
>When chroma-keying has been negotiated with
<A
HREF="#VIDIOC-G-FBUF"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_FBUF</CODE
></A
> applications set this field to the desired host order
RGB32 value for the chroma key. [host order? alpha channel?]</TD
></TR
><TR
><TD
>struct <A
HREF="#V4L2-CLIP"
>v4l2_clip</A
> *</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>clips</CODE
></TD
><TD
>When chroma-keying has <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>not</I
></SPAN
>
been negotiated and <A
HREF="#VIDIOC-G-FBUF"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_FBUF</CODE
></A
> indicated this capability,
applications can set this field to point to the first in a list of
clipping rectangles.</TD
></TR
><TR
><TD
COLSPAN="3"
>Like the window coordinates
<CODE
CLASS="STRUCTFIELD"
>w</CODE
>, 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 <A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
></A
>
are undefined.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>clipcount</CODE
></TD
><TD
>When the application set the
<CODE
CLASS="STRUCTFIELD"
>clips</CODE
> 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
<CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
> are undefined. When clip lists are
supported but no clipping is desired this field must be set to
zero.</TD
></TR
><TR
><TD
>void *</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>bitmap</CODE
></TD
><TD
>When chroma-keying has
<SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>not</I
></SPAN
> been negotiated and <A
HREF="#VIDIOC-G-FBUF"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_FBUF</CODE
></A
> indicated
this capability, applications can set this field to point to a
clipping bit mask.</TD
></TR
><TR
><TD
COLSPAN="3"
><P
>It must be of the same size
as the window, <CODE
CLASS="STRUCTFIELD"
>w.width</CODE
> and
<CODE
CLASS="STRUCTFIELD"
>w.height</CODE
>. Each bit corresponds to a pixel
in the overlaid image, which is displayed only when the bit is
<SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>set</I
></SPAN
>. Pixel coordinates translate to bits like:
<PRE
CLASS="PROGRAMLISTING"
>((__u8 *) <CODE
CLASS="STRUCTFIELD"
>bitmap</CODE
>)[<CODE
CLASS="STRUCTFIELD"
>w.width</CODE
> * y + x / 8] & (1 << (x & 7))</PRE
></P
><P
>where <CODE
CLASS="STRUCTFIELD"
>0</CODE
> ≤ x <
<CODE
CLASS="STRUCTFIELD"
>w.width</CODE
> and <CODE
CLASS="STRUCTFIELD"
>0</CODE
> ≤
y <<CODE
CLASS="STRUCTFIELD"
>w.height</CODE
>.<SUP
>a</SUP
></P
><P
>When a clipping
bit mask is not supported the driver ignores this field, its contents
after calling <A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
></A
> are undefined. When a bit mask is supported
but no clipping is desired this field must be set to
<CODE
CLASS="CONSTANT"
>NULL</CODE
>.</P
><P
>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.<SUP
>b</SUP
></P
></TD
></TR
></TBODY
><TR
><TD
COLSPAN="3"
>Notes:<BR><A
NAME="FTN.AEN4203"
>a. </A
>Should we require
<CODE
CLASS="STRUCTFIELD"
>w.width</CODE
> to be a multiple of
eight?<BR><A
NAME="FTN.AEN4211"
>b. </A
>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.<BR></TD
></TR
></TABLE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="V4L2-CLIP"
></A
><P
><B
>Table 4-2. struct <CODE
CLASS="STRUCTNAME"
>v4l2_clip</CODE
><A
NAME="AEN4216"
HREF="#FTN.AEN4216"
><SPAN
CLASS="footnote"
>[22]</SPAN
></A
></B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="25%"
TITLE="C1"><COL
WIDTH="25%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
>struct <A
HREF="#V4L2-RECT"
>v4l2_rect</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>c</CODE
></TD
><TD
>Coordinates of the clipping rectangle, relative to
the top, left corner of the frame buffer. Only window pixels
<SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>outside</I
></SPAN
> all clipping rectangles are
displayed.</TD
></TR
><TR
><TD
>struct <A
HREF="#V4L2-CLIP"
>v4l2_clip</A
> *</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>next</CODE
></TD
><TD
>Pointer to the next clipping rectangle in the list,
NULL when this is the last rectangle.</TD
></TR
></TBODY
></TABLE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="V4L2-RECT"
></A
><P
><B
>Table 4-3. struct <CODE
CLASS="STRUCTNAME"
>v4l2_rect</CODE
></B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="25%"
TITLE="C1"><COL
WIDTH="25%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
>__s32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>left</CODE
></TD
><TD
>Horizontal offset of the top, left corner of the
rectangle, in pixels.</TD
></TR
><TR
><TD
>__s32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>top</CODE
></TD
><TD
>Vertical offset of the top, left corner of the
rectangle, in pixels. Offsets increase to the right and down.</TD
></TR
><TR
><TD
>__s32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>width</CODE
></TD
><TD
>Width of the rectangle, in pixels.</TD
></TR
><TR
><TD
>__s32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>height</CODE
></TD
><TD
>Height of the rectangle, in pixels. Width and
height cannot be negative, the fields are signed for hysterical
reasons. </TD
></TR
></TBODY
></TABLE
></DIV
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN4266"
>4.2.5. Enabling Overlay</A
></H3
><P
>To start or stop the frame buffer overlay applications call
the <A
HREF="#VIDIOC-OVERLAY"
><CODE
CLASS="CONSTANT"
>VIDIOC_OVERLAY</CODE
></A
> ioctl.</P
></DIV
></DIV
><DIV
CLASS="SECTION"
><HR><H2
CLASS="SECTION"
><A
NAME="OUTPUT"
>4.3. Video Output Interface</A
></H2
><P
>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.</P
><P
>Conventionally V4L2 video output devices are accessed through
character device special files named <TT
CLASS="FILENAME"
>/dev/vout</TT
> and
<TT
CLASS="FILENAME"
>/dev/vout0</TT
> to <TT
CLASS="FILENAME"
>/dev/voutN</TT
>. No
minor numbers were recommended yet. <TT
CLASS="FILENAME"
>/dev/vout</TT
> is
typically a symbolic link to the preferred video output device.</P
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN4279"
>4.3.1. Querying Capabilities</A
></H3
><P
>Devices supporting the video output interface set the
<CODE
CLASS="CONSTANT"
>V4L2_CAP_VIDEO_OUTPUT</CODE
> flag in the
<CODE
CLASS="STRUCTFIELD"
>capabilities</CODE
> field of struct <A
HREF="#V4L2-CAPABILITY"
>v4l2_capability</A
>
returned by the <A
HREF="#VIDIOC-QUERYCAP"
><CODE
CLASS="CONSTANT"
>VIDIOC_QUERYCAP</CODE
></A
>. As secondary device functions they
may also support the <A
HREF="#RAW-VBI"
>raw VBI output</A
>
(<CODE
CLASS="CONSTANT"
>V4L2_CAP_VBI_OUTPUT</CODE
>) interface. At least one of
the read/write or streaming I/O methods must be supported. Modulators
and audio outputs are optional.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN4289"
>4.3.2. Supplemental Functions</A
></H3
><P
>Video output devices shall support <A
HREF="#AUDIO"
>audio output</A
>, <A
HREF="#TUNER"
>modulator</A
>, <A
HREF="#CONTROL"
>controls</A
>,
<A
HREF="#CROP"
>cropping and scaling</A
> and <A
HREF="#STREAMING-PAR"
>streaming parameter</A
> ioctls as needed.
The <A
HREF="#VIDEO"
>video output</A
> and <A
HREF="#STANDARD"
>video standard</A
> ioctls must be supported by
all video output devices.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN4299"
>4.3.3. Image Format Negotiation</A
></H3
><P
>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, i. e. 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.</P
><P
>As usual these parameters are <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>not</I
></SPAN
>
reset at <CODE
CLASS="FUNCTION"
>open()</CODE
> 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.</P
><P
>Cropping initialization at minimum requires to reset the
parameters to defaults. An example is given in <A
HREF="#CROP"
>Section 1.10</A
>.</P
><P
>To query the current image format applications set the
<CODE
CLASS="STRUCTFIELD"
>type</CODE
> field of a struct <A
HREF="#V4L2-FORMAT"
>v4l2_format</A
> to
<CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_VIDEO_OUTPUT</CODE
> and call the
<A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_FMT</CODE
></A
> ioctl with a pointer to this structure. Drivers fill
the struct <A
HREF="#V4L2-PIX-FORMAT"
>v4l2_pix_format</A
> <CODE
CLASS="STRUCTFIELD"
>pix</CODE
> member of the
<CODE
CLASS="STRUCTFIELD"
>fmt</CODE
> union.</P
><P
>To request different parameters applications set the
<CODE
CLASS="STRUCTFIELD"
>type</CODE
> field of a struct <A
HREF="#V4L2-FORMAT"
>v4l2_format</A
> as above and
initialize all fields of the struct <A
HREF="#V4L2-PIX-FORMAT"
>v4l2_pix_format</A
>
<CODE
CLASS="STRUCTFIELD"
>vbi</CODE
> member of the
<CODE
CLASS="STRUCTFIELD"
>fmt</CODE
> union, or better just modify the
results of <CODE
CLASS="CONSTANT"
>VIDIOC_G_FMT</CODE
>, and call the
<A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
></A
> ioctl with a pointer to this structure. Drivers may
adjust the parameters and finally return the actual parameters as
<CODE
CLASS="CONSTANT"
>VIDIOC_G_FMT</CODE
> does.</P
><P
>Like <CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
> the
<A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_TRY_FMT</CODE
></A
> ioctl can be used to learn about hardware limitations
without disabling I/O or possibly time consuming hardware
preparations.</P
><P
>The contents of struct <A
HREF="#V4L2-PIX-FORMAT"
>v4l2_pix_format</A
> are discussed in <A
HREF="#PIXFMT"
>Chapter 2</A
>. See also the specification of the
<CODE
CLASS="CONSTANT"
>VIDIOC_G_FMT</CODE
>, <CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
>
and <CODE
CLASS="CONSTANT"
>VIDIOC_TRY_FMT</CODE
> ioctls for details. Video
output devices must implement both the
<CODE
CLASS="CONSTANT"
>VIDIOC_G_FMT</CODE
> and
<CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
> ioctl, even if
<CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
> ignores all requests and always
returns default parameters as <CODE
CLASS="CONSTANT"
>VIDIOC_G_FMT</CODE
> does.
<CODE
CLASS="CONSTANT"
>VIDIOC_TRY_FMT</CODE
> is optional.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN4341"
>4.3.4. Writing Images</A
></H3
><P
>A video output device may support the <A
HREF="#RW"
>write() function</A
> and/or streaming (<A
HREF="#MMAP"
>memory mapping</A
> or <A
HREF="#USERP"
>user pointer</A
>) I/O. See <A
HREF="#IO"
>Chapter 3</A
> for details.</P
></DIV
></DIV
><DIV
CLASS="SECTION"
><HR><H2
CLASS="SECTION"
><A
NAME="CODEC"
>4.4. Codec Interface</A
></H2
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Suspended: </B
>This interface has been be suspended from the V4L2 API
implemented in Linux 2.6 until we have more experience with codec
device interfaces.</P
></BLOCKQUOTE
></DIV
><P
>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
the <CODE
CLASS="FUNCTION"
>write()</CODE
> call, and receive the converted data
through the <CODE
CLASS="FUNCTION"
>read()</CODE
> call. For efficiency, a driver
may also support streaming I/O.</P
><P
>[to do]</P
></DIV
><DIV
CLASS="SECTION"
><HR><H2
CLASS="SECTION"
><A
NAME="EFFECT"
>4.5. Effect Devices Interface</A
></H2
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Suspended: </B
>This interface has been be suspended from the V4L2 API
implemented in Linux 2.6 until we have more experience with effect
device interfaces.</P
></BLOCKQUOTE
></DIV
><P
>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 <CODE
CLASS="FUNCTION"
>read()</CODE
> and
<CODE
CLASS="FUNCTION"
>write()</CODE
> functions, or through the streaming I/O
mechanism.</P
><P
>[to do]</P
></DIV
><DIV
CLASS="SECTION"
><HR><H2
CLASS="SECTION"
><A
NAME="RAW-VBI"
>4.6. Raw VBI Data Interface</A
></H2
><P
>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<A
NAME="AEN4369"
HREF="#FTN.AEN4369"
><SPAN
CLASS="footnote"
>[23]</SPAN
></A
>
onto the video signal. These are transmissions of services such as
Teletext or Closed Caption.</P
><P
>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.</P
><P
>Conventionally V4L2 VBI devices are accessed through character
device special files named <TT
CLASS="FILENAME"
>/dev/vbi</TT
> and
<TT
CLASS="FILENAME"
>/dev/vbi0</TT
> to <TT
CLASS="FILENAME"
>/dev/vbi15</TT
> with
major number 81 and minor numbers 224 to 239.
<TT
CLASS="FILENAME"
>/dev/vbi</TT
> is typically a symbolic link to the
preferred VBI device. This convention applies to both input and output
devices.</P
><P
>To address the problems of finding related video and VBI
devices VBI capturing is also available as device function under
<TT
CLASS="FILENAME"
>/dev/video</TT
>, VBI output under
<TT
CLASS="FILENAME"
>/dev/vout</TT
>. To capture raw VBI data from these
devices applications must call the <A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
></A
> ioctl. Accessed as
<TT
CLASS="FILENAME"
>/dev/vbi</TT
>, raw VBI capturing or output is
the default device function.</P
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN4383"
>4.6.1. Querying Capabilities</A
></H3
><P
>Devices supporting the raw VBI capturing or output API set
the <CODE
CLASS="CONSTANT"
>V4L2_CAP_VBI_CAPTURE</CODE
> or
<CODE
CLASS="CONSTANT"
>V4L2_CAP_VBI_OUTPUT</CODE
> flags, respectively, in the
<CODE
CLASS="STRUCTFIELD"
>capabilities</CODE
> field of struct <A
HREF="#V4L2-CAPABILITY"
>v4l2_capability</A
>
returned by the <A
HREF="#VIDIOC-QUERYCAP"
><CODE
CLASS="CONSTANT"
>VIDIOC_QUERYCAP</CODE
></A
>. 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.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN4392"
>4.6.2. Supplemental Functions</A
></H3
><P
>VBI devices shall support <A
HREF="#VIDEO"
>video
input or output</A
>, <A
HREF="#TUNER"
>tuner or
modulator</A
>, and <A
HREF="#CONTROL"
>controls</A
> ioctls
as needed. The <A
HREF="#STANDARD"
>video standard</A
> ioctls provide
information vital to program a VBI device, therefore must be
supported.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN4399"
>4.6.3. Raw VBI Format Negotiation</A
></H3
><P
>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.</P
><P
>As usual these parameters are <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>not</I
></SPAN
>
reset at <CODE
CLASS="FUNCTION"
>open()</CODE
> 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.</P
><P
>To query the current raw VBI capture parameters
applications set the <CODE
CLASS="STRUCTFIELD"
>type</CODE
> field of a
struct <A
HREF="#V4L2-FORMAT"
>v4l2_format</A
> to <CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_VBI_CAPTURE</CODE
> or
<CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_VBI_OUTPUT</CODE
>, and call the
<A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_FMT</CODE
></A
> ioctl with a pointer to this structure. Drivers fill
the struct <A
HREF="#V4L2-VBI-FORMAT"
>v4l2_vbi_format</A
> <CODE
CLASS="STRUCTFIELD"
>vbi</CODE
> member of the
<CODE
CLASS="STRUCTFIELD"
>fmt</CODE
> union.</P
><P
>To request different parameters applications set the
<CODE
CLASS="STRUCTFIELD"
>type</CODE
> field of a struct <A
HREF="#V4L2-FORMAT"
>v4l2_format</A
> as above and
initialize all fields of the struct <A
HREF="#V4L2-VBI-FORMAT"
>v4l2_vbi_format</A
>
<CODE
CLASS="STRUCTFIELD"
>vbi</CODE
> member of the
<CODE
CLASS="STRUCTFIELD"
>fmt</CODE
> union, or better just modify the
results of <CODE
CLASS="CONSTANT"
>VIDIOC-G-FMT</CODE
>, and call the
<A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
></A
> ioctl with a pointer to this structure. Drivers return
an <SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code 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 <SPAN
CLASS="ERRORCODE"
>EBUSY</SPAN
> error code 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 <SPAN
CLASS="ERRORCODE"
>EBUSY</SPAN
>, at the <A
HREF="#VIDIOC-STREAMON"
><CODE
CLASS="CONSTANT"
>VIDIOC_STREAMON</CODE
></A
> ioctl
and the first read(), write() and select() call.</P
><P
>VBI devices must implement both the
<CODE
CLASS="CONSTANT"
>VIDIOC_G_FMT</CODE
> and
<CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
> ioctl, even if
<CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
> ignores all requests and always
returns default parameters as <CODE
CLASS="CONSTANT"
>VIDIOC_G_FMT</CODE
> does.
<CODE
CLASS="CONSTANT"
>VIDIOC_TRY_FMT</CODE
> is optional.</P
><DIV
CLASS="TABLE"
><A
NAME="V4L2-VBI-FORMAT"
></A
><P
><B
>Table 4-4. struct <CODE
CLASS="STRUCTNAME"
>v4l2_vbi_format</CODE
></B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="25%"
TITLE="C1"><COL
WIDTH="25%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>sampling_rate</CODE
></TD
><TD
>Samples per second, i. e. unit 1 Hz.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>offset</CODE
></TD
><TD
><P
>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
<CODE
CLASS="STRUCTFIELD"
>offset</CODE
> /
<CODE
CLASS="STRUCTFIELD"
>sampling_rate</CODE
> seconds following the leading
edge. See also <A
HREF="#VBI-HSYNC"
>Figure 4-1</A
>.</P
></TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>samples_per_line</CODE
></TD
><TD
> </TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>sample_format</CODE
></TD
><TD
><P
>Defines the sample format as in <A
HREF="#PIXFMT"
>Chapter 2</A
>, a four-character-code.<SUP
>a</SUP
> Usually this is
<CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_GREY</CODE
>, i. 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.</P
></TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>start</CODE
>[2]</TD
><TD
>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 <A
HREF="#VBI-525"
>Figure 4-2</A
> and
<A
HREF="#VBI-625"
>Figure 4-3</A
> 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.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>count</CODE
>[2]</TD
><TD
>The number of lines in the first and second
field image, respectively.</TD
></TR
><TR
><TD
COLSPAN="3"
><P
>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.</P
><P
>An application can set the first or second
<CODE
CLASS="STRUCTFIELD"
>count</CODE
> value to zero if no data is required
from the respective field; <CODE
CLASS="STRUCTFIELD"
>count</CODE
>[1] if the
scanning system is progressive, i. e. 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.</P
><P
>Both
<CODE
CLASS="STRUCTFIELD"
>count</CODE
> values set to zero, or line numbers
outside the bounds depicted in <A
HREF="#VBI-525"
>Figure 4-2</A
> and <A
HREF="#VBI-625"
>Figure 4-3</A
>, or a field image covering
lines of two fields, are invalid and shall not be returned by the
driver.</P
><P
>To initialize the <CODE
CLASS="STRUCTFIELD"
>start</CODE
>
and <CODE
CLASS="STRUCTFIELD"
>count</CODE
> fields, applications must first
determine the current video standard selection. The <A
HREF="#V4L2-STD-ID"
>v4l2_std_id</A
> or
the <CODE
CLASS="STRUCTFIELD"
>framelines</CODE
> field of struct <A
HREF="#V4L2-STANDARD"
>v4l2_standard</A
> can
be evaluated for this purpose.</P
></TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>flags</CODE
></TD
><TD
>See <A
HREF="#VBIFMT-FLAGS"
>Table 4-5</A
> below. Currently
only drivers set flags, applications must set this field to
zero.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>reserved</CODE
>[2]</TD
><TD
>This array is reserved for future extensions.
Drivers and applications must set it to zero.</TD
></TR
></TBODY
><TR
><TD
COLSPAN="3"
>Notes:<BR><A
NAME="FTN.AEN4470"
>a. </A
>A few devices may be unable to
sample VBI data at all but can extend the video capture window to the
VBI region.<BR></TD
></TR
></TABLE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="VBIFMT-FLAGS"
></A
><P
><B
>Table 4-5. Raw VBI Format Flags</B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="38%"
TITLE="C1"><COL
WIDTH="12%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_VBI_UNSYNC</CODE
></TD
><TD
>0x0001</TD
><TD
><P
>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.<SUP
>a</SUP
></P
></TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_VBI_INTERLACED</CODE
></TD
><TD
>0x0002</TD
><TD
>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 <A
HREF="#FIELD-ORDER"
>Section 3.6</A
>
<CODE
CLASS="CONSTANT"
>V4L2_FIELD_SEQ_TB</CODE
> and
<CODE
CLASS="CONSTANT"
>V4L2_FIELD_SEQ_BT</CODE
>, 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.
<CODE
CLASS="CONSTANT"
>V4L2_FIELD_INTERLACED</CODE
>). 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
<CODE
CLASS="STRUCTFIELD"
>count</CODE
> values are equal and non-zero.</TD
></TR
></TBODY
><TR
><TD
COLSPAN="3"
>Notes:<BR><A
NAME="FTN.AEN4526"
>a. </A
>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
<CODE
CLASS="CONSTANT"
>V4L2_VBI_UNSYNC</CODE
> is set.<BR></TD
></TR
></TABLE
></DIV
><DIV
CLASS="FIGURE"
><A
NAME="VBI-HSYNC"
></A
><P
><B
>Figure 4-1. Line synchronization</B
></P
><DIV
CLASS="MEDIAOBJECT"
><P
><IMG
SRC="vbi_hsync.gif"></P
></DIV
></DIV
><DIV
CLASS="FIGURE"
><A
NAME="VBI-525"
></A
><P
><B
>Figure 4-2. ITU-R 525 line numbering (M/NTSC and M/PAL)</B
></P
><DIV
CLASS="MEDIAOBJECT"
><P
><IMG
SRC="vbi_525.gif"><DIV
CLASS="CAPTION"
><P
>(1) For the purpose of this specification field 2
starts in line 264 and not 263.5 because half line capturing is not
supported.</P
></DIV
></P
></DIV
></DIV
><DIV
CLASS="FIGURE"
><A
NAME="VBI-625"
></A
><P
><B
>Figure 4-3. ITU-R 625 line numbering</B
></P
><DIV
CLASS="MEDIAOBJECT"
><P
><IMG
SRC="vbi_625.gif"><DIV
CLASS="CAPTION"
><P
>(1) For the purpose of this specification field 2
starts in line 314 and not 313.5 because half line capturing is not
supported.</P
></DIV
></P
></DIV
></DIV
><P
>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.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN4571"
>4.6.4. Reading and writing VBI images</A
></H3
><P
>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.</P
><P
>The total size of a frame computes as follows:</P
><PRE
CLASS="PROGRAMLISTING"
>(<CODE
CLASS="STRUCTFIELD"
>count</CODE
>[0] + <CODE
CLASS="STRUCTFIELD"
>count</CODE
>[1]) *
<CODE
CLASS="STRUCTFIELD"
>samples_per_line</CODE
> * sample size in bytes</PRE
><P
>The sample size is most likely always one byte,
applications must check the <CODE
CLASS="STRUCTFIELD"
>sample_format</CODE
>
field though, to function properly with other drivers.</P
><P
>A VBI device may support <A
HREF="#RW"
>read/write</A
> and/or streaming (<A
HREF="#MMAP"
>memory mapping</A
> or <A
HREF="#USERP"
>user pointer</A
>) I/O. The latter bears the
possibility of synchronizing video and
VBI data by using buffer timestamps.</P
><P
>Remember the <A
HREF="#VIDIOC-STREAMON"
><CODE
CLASS="CONSTANT"
>VIDIOC_STREAMON</CODE
></A
> ioctl and the first read(),
write() and select() call can be resource allocation points returning
an <SPAN
CLASS="ERRORCODE"
>EBUSY</SPAN
> error code if the required hardware resources are temporarily
unavailable, for example the device is already in use by another
process.</P
></DIV
></DIV
><DIV
CLASS="SECTION"
><HR><H2
CLASS="SECTION"
><A
NAME="SLICED"
>4.7. Sliced VBI Data Interface</A
></H2
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Proposal: </B
>This interface is not yet implemented in v4l2.</P
></BLOCKQUOTE
></DIV
><P
>Sliced VBI data is VBI data after demodulation by hardware
decoders. Kernel drivers shall not convert to or from raw VBI data by
software. The data is passed as short packets of fixed size covering
one scan line each. The number of packets per frame is variable.</P
><P
>Sliced VBI input and output devices are accessed through the
same character special files as raw VBI devices. Note the default
function of a <TT
CLASS="FILENAME"
>/dev/vbi</TT
> device is raw VBI
capturing or output. The sliced VBI function is only available after
calling the <A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
></A
> ioctl.</P
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN4599"
>4.7.1. Querying Capabilities</A
></H3
><P
>Devices supporting the sliced VBI capturing or output API
set the <CODE
CLASS="CONSTANT"
>V4L2_CAP_SLICED_VBI_CAPTURE</CODE
> or
<CODE
CLASS="CONSTANT"
>V4L2_CAP_SLICED_VBI_OUTPUT</CODE
> flags in the
<CODE
CLASS="STRUCTFIELD"
>capabilities</CODE
> field of struct <A
HREF="#V4L2-CAPABILITY"
>v4l2_capability</A
>
returned by the <A
HREF="#VIDIOC-QUERYCAP"
><CODE
CLASS="CONSTANT"
>VIDIOC_QUERYCAP</CODE
></A
>. At least one of the read/write,
streaming or asynchronous I/O methods must be supported. VBI devices
may have a tuner or modulator.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN4608"
>4.7.2. Supplemental Functions</A
></H3
><P
>VBI devices shall support <A
HREF="#VIDEO"
>video
input or output</A
>, <A
HREF="#TUNER"
>tuner or
modulator</A
>, and <A
HREF="#CONTROL"
>controls</A
> ioctls
as needed. The <A
HREF="#STANDARD"
>video standard</A
> provide
information vital to program a VBI device, therefore must be
supported.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN4615"
>4.7.3. Sliced VBI Format Negotiation</A
></H3
><P
>To determine which data services are supported by the
hardware and which are desired by the application, the driver and application have to
negotiate the sliced VBI data format.</P
><P
>After setting the <CODE
CLASS="STRUCTFIELD"
>type</CODE
> field of
struct <A
HREF="#V4L2-FORMAT"
>v4l2_format</A
> to <CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</CODE
>
or <CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</CODE
>, a
<A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_FMT</CODE
></A
> fills the struct <CODE
CLASS="STRUCTNAME"
>v4l2_sliced_vbi_format</CODE
>
<CODE
CLASS="STRUCTFIELD"
>sliced</CODE
> member of the
<CODE
CLASS="STRUCTFIELD"
>fmt</CODE
> union of a struct <A
HREF="#V4L2-FORMAT"
>v4l2_format</A
>.</P
><P
>Applications can request different parameters by
initializing or modifying the <CODE
CLASS="STRUCTFIELD"
>sliced</CODE
> member
and calling the <A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
></A
> ioctl with a pointer to the
<CODE
CLASS="STRUCTNAME"
>v4l2_format</CODE
> structure. <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>All fields
of struct <CODE
CLASS="STRUCTNAME"
>v4l2_vbi_format</CODE
> must be
initialized</I
></SPAN
>. Drivers return an <SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code only when
the given parameters are ambiguous, otherwise they modify the
parameters according to the hardware capabilites. When the driver
allocates resources at this point, it may return an <SPAN
CLASS="ERRORCODE"
>EBUSY</SPAN
> error code to
indicate the returned parameters are valid but the required resources
are currently not available. Applications must expect other resource
allocation points which may return <SPAN
CLASS="ERRORCODE"
>EBUSY</SPAN
> at the
<A
HREF="#VIDIOC-STREAMON"
><CODE
CLASS="CONSTANT"
>VIDIOC_STREAMON</CODE
></A
> ioctl and the first read(), write() and select()
call. Different file descriptors must be used to pass raw and sliced
VBI data simultaneously, if this is supported by the driver.</P
><DIV
CLASS="TABLE"
><A
NAME="V4L2-SLICED-VBI-FORMAT"
></A
><P
><B
>Table 4-6. struct <CODE
CLASS="STRUCTNAME"
>v4l2_sliced_vbi_format</CODE
></B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="25%"
TITLE="C1"><COL
WIDTH="25%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>service_set</CODE
></TD
><TD
>A set of symbols defining which types of data
packets are passed. See <A
HREF="#SLICED-VBI-TYPES"
>Table 4-8</A
> for details.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>packet_size</CODE
></TD
><TD
><P
>The size of each type of packet is fixed,
however when different types of packets are exchanged between driver
and application their size can vary. This value defines the size of
the largest packet (struct <A
HREF="#V4L2-SLICED-DATA"
>v4l2_sliced_data</A
>) that will be
passed, smaller packets must be padded accordingly. When the
architecture requires special alignment of __u32 quantities the driver
shall round up <CODE
CLASS="STRUCTFIELD"
>packet_size </CODE
> as
necessary.</P
></TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>io_size</CODE
></TD
><TD
>Maximum number of bytes passed by one <CODE
CLASS="FUNCTION"
>read()</CODE
> or
<CODE
CLASS="FUNCTION"
>write()</CODE
> call, and the buffer size in bytes for the <A
HREF="#VIDIOC-QBUF"
><CODE
CLASS="CONSTANT"
>VIDIOC_QBUF</CODE
></A
> and
<A
HREF="#VIDIOC-QBUF"
><CODE
CLASS="CONSTANT"
>VIDIOC_DQBUF</CODE
></A
> ioctl. Usually this will be
<CODE
CLASS="STRUCTFIELD"
>packet_size</CODE
> times the number of scan lines
potentially containing the data in question. On input, applications
should set this field to zero and accept the value proposed by the
driver.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>reserved</CODE
></TD
><TD
>Applications and drivers must set this field to
zero.</TD
></TR
></TBODY
></TABLE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="V4L2-SLICED-DATA"
></A
><P
><B
>Table 4-7. struct <CODE
CLASS="STRUCTNAME"
>v4l2_sliced_data</CODE
></B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="38%"
TITLE="C1"><COL
WIDTH="12%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>id</CODE
></TD
><TD
>One of the symbols in <A
HREF="#SLICED-VBI-TYPES"
>Table 4-8</A
> defining the type of data in this packet. A
value of zero indicates an empty packet with no payload, in this case
<CODE
CLASS="STRUCTFIELD"
>line</CODE
> and <CODE
CLASS="STRUCTFIELD"
>data</CODE
>
are undefined.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>line</CODE
></TD
><TD
>The scanning system line number this data has
been captured from, or shall be inserted at. See <A
HREF="#VBI-525"
>Figure 4-2</A
>
and <A
HREF="#VBI-625"
>Figure 4-3</A
> for valid values. Sliced VBI input drivers
can set the line number of all packets to <CODE
CLASS="CONSTANT"
>0</CODE
> if
the hardware cannot reliable identify scan lines.</TD
></TR
><TR
><TD
>__u8</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>data</CODE
>[]</TD
><TD
>The packet payload. See <A
HREF="#SLICED-VBI-TYPES"
>Table 4-8</A
> for the contents and number of bytes passed
for each data type. The contents of padding bytes following up to
<CODE
CLASS="STRUCTFIELD"
>packet_size</CODE
> is undefined.</TD
></TR
></TBODY
></TABLE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="SLICED-VBI-TYPES"
></A
><P
><B
>Table 4-8. Sliced VBI data formats</B
></P
><TABLE
BORDER="1"
WIDTH="100%"
CLASS="CALSTABLE"
><COL><COL><COL><COL><THEAD
><TR
><TH
>Symbol</TH
><TH
>Reference</TH
><TH
>Lines, usually</TH
><TH
>Payload</TH
></TR
></THEAD
><TBODY
><TR
><TD
>V4L2_SLICED_TELETEXT_B (Teletext System B)</TD
><TD
><A
HREF="#TELETEXT"
><ABBR
CLASS="ABBREV"
>TELETEXT</ABBR
></A
></TD
><TD
>PAL/SECAM line 6-22, 318-335</TD
><TD
>Last 42 of the 45 byte Teletext packet, that is
without clock run-in and framing code, lsb first transmitted.</TD
></TR
><TR
><TD
>V4L2_SLICED_VPS</TD
><TD
><A
HREF="#VPS"
><ABBR
CLASS="ABBREV"
>VPS</ABBR
></A
></TD
><TD
>PAL line 16</TD
><TD
>Byte number 3 to 15 according to Figure 9 of ETS
300 231, lsb first transmitted.</TD
></TR
><TR
><TD
>V4L2_SLICED_CAPTION_625</TD
><TD
><A
HREF="#EIA608"
><ABBR
CLASS="ABBREV"
>EIA608</ABBR
></A
></TD
><TD
>PAL line 22 (?)</TD
><TD
>First and second byte including parity bit, lsb
first transmitted.</TD
></TR
><TR
><TD
>V4L2_SLICED_WSS_625</TD
><TD
><A
HREF="#WSS"
><ABBR
CLASS="ABBREV"
>WSS</ABBR
></A
></TD
><TD
>PAL/SECAM line 23</TD
><TD
><PRE
CLASS="SCREEN"
>Byte 0 1
msb lsb msb lsb
Bit 7 6 5 4 3 2 1 0 x x 13 12 11 10 9</PRE
></TD
></TR
><TR
><TD
>V4L2_SLICED_CAPTION_525</TD
><TD
><A
HREF="#EIA608"
><ABBR
CLASS="ABBREV"
>EIA608</ABBR
></A
></TD
><TD
>NTSC line 21, 284</TD
><TD
>First and second byte including parity bit, lsb
first transmitted.</TD
></TR
><TR
><TD
>V4L2_SLICED_RESERVED</TD
><TD
> </TD
><TD
>undefined</TD
><TD
>undefined</TD
></TR
></TBODY
></TABLE
></DIV
><P
>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 is not permitted during active i/o.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN4760"
>4.7.4. Reading and writing sliced VBI data</A
></H3
><P
>The smallest unit of data passed at a time is one sliced
data packet. Within the bounds of <CODE
CLASS="STRUCTFIELD"
>io_size</CODE
>
multiple packets can (and should) be passed, but no more than one
frame at a time (to keep the processing time low, for example from
reception to display of subtitles). Packets are always passed in
ascending line number order, without duplicate line numbers. If the
line numbers are unknown the driver must pass the packets in
transmitted order. Empty packets with <CODE
CLASS="STRUCTFIELD"
>id</CODE
>
set to zero can be inserted anywhere.</P
><P
>To assure synchronization and to distinguish from frame
dropping, when one frame does not contain any data in question one or
more empty packets must be passed. In streaming I/O mode one buffer of
<CODE
CLASS="STRUCTFIELD"
>io_size</CODE
> shall coincide with one video
frame. The <CODE
CLASS="STRUCTFIELD"
>id</CODE
> of unused packets must be
zero.</P
><P
>A sliced VBI device may support <A
HREF="#RW"
>read/write</A
> and/or streaming (<A
HREF="#MMAP"
>memory mapping</A
> or <A
HREF="#USERP"
>user pointer</A
>) I/O. The latter bears the
possibility of synchronizing video and VBI data by using buffer
timestamps.</P
><P
>Remember the <A
HREF="#VIDIOC-STREAMON"
><CODE
CLASS="CONSTANT"
>VIDIOC_STREAMON</CODE
></A
> ioctl and the first read(),
write() and select() call can be resource allocation points returning
an <SPAN
CLASS="ERRORCODE"
>EBUSY</SPAN
> error code if the required hardware resources are temporarily
unavailable, for example the device is already in use by another
process.</P
></DIV
></DIV
><DIV
CLASS="SECTION"
><HR><H2
CLASS="SECTION"
><A
NAME="TTX"
>4.8. Teletext Interface</A
></H2
><P
>This interface aims at devices receiving and demodulating
Teletext data [<A
HREF="#TELETEXT"
><ABBR
CLASS="ABBREV"
>TELETEXT</ABBR
></A
>], evaluating the
Teletext packages and storing formatted pages in cache memory. Such
devices are usually implemented as microcontrollers with serial
interface (I<SUP
>2</SUP
>C) and can be found on older
TV cards, dedicated Teletext decoding cards and home-brew devices
connected to the PC parallel port.</P
><P
>The Teletext API was designed by Martin Buck. It is defined in
the kernel header file <TT
CLASS="FILENAME"
>linux/videotext.h</TT
>, the
specification is available from <A
HREF="http://home.pages.de/~videotext/"
TARGET="_top"
>http://home.pages.de/~videotext/</A
>. (Videotext is the name of
the German public television Teletext service.) Conventional character
device file names are <TT
CLASS="FILENAME"
>/dev/vtx</TT
> and
<TT
CLASS="FILENAME"
>/dev/vttuner</TT
>, 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
<TT
CLASS="FILENAME"
>/dev/tlkN</TT
>, device number 102, N.</P
><P
>Eventually the Teletext API was integrated into the V4L API
with character device file names <TT
CLASS="FILENAME"
>/dev/vtx0</TT
> to
<TT
CLASS="FILENAME"
>/dev/vtx31</TT
>, 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.</P
><P
>There are no plans to replace the Teletext API or to integrate
it into V4L2. Please write to the Video4Linux mailing list: <A
HREF="https://listman.redhat.com/mailman/listinfo/video4linux-list"
TARGET="_top"
>https://listman.redhat.com/mailman/listinfo/video4linux-list</A
>
when the need arises.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H2
CLASS="SECTION"
><A
NAME="RADIO"
>4.9. Radio Interface</A
></H2
><P
>This interface is intended for AM and FM (analog) radio
receivers.</P
><P
>Conventionally V4L2 radio devices are accessed through
character device special files named <TT
CLASS="FILENAME"
>/dev/radio</TT
>
and <TT
CLASS="FILENAME"
>/dev/radio0</TT
> to
<TT
CLASS="FILENAME"
>/dev/radio63</TT
> with major number 81 and minor
numbers 64 to 127.</P
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN4799"
>4.9.1. Querying Capabilities</A
></H3
><P
>Devices supporting the radio interface set the
<CODE
CLASS="CONSTANT"
>V4L2_CAP_RADIO</CODE
> and
<CODE
CLASS="CONSTANT"
>V4L2_CAP_TUNER</CODE
> flag in the
<CODE
CLASS="STRUCTFIELD"
>capabilities</CODE
> field of struct <A
HREF="#V4L2-CAPABILITY"
>v4l2_capability</A
>
returned by the <A
HREF="#VIDIOC-QUERYCAP"
><CODE
CLASS="CONSTANT"
>VIDIOC_QUERYCAP</CODE
></A
> ioctl. Other combinations of
capability flags are reserved for future extensions.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN4808"
>4.9.2. Supplemental Functions</A
></H3
><P
>Radio devices can support <A
HREF="#CONTROL"
>controls</A
>, and must support the <A
HREF="#TUNER"
>tuner</A
> ioctls.</P
><P
>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.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN4814"
>4.9.3. Programming</A
></H3
><P
>Radio devices may have a couple audio controls (as discussed
in <A
HREF="#CONTROL"
>Section 1.8</A
>) such as a volume control, possibly custom
controls. Further all radio devices have one tuner (these are
discussed in <A
HREF="#TUNER"
>Section 1.6</A
>) with index number zero to select
the radio frequency and to determine if a monaural or FM stereo
program is received. Drivers switch automatically between AM and FM
depending on the selected frequency. The <A
HREF="#VIDIOC-G-TUNER"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_TUNER</CODE
></A
> ioctl
reports the supported frequency range.</P
></DIV
></DIV
><DIV
CLASS="SECTION"
><HR><H2
CLASS="SECTION"
><A
NAME="RDS"
>4.10. RDS Interface</A
></H2
><P
>The Radio Data System transmits supplementary
information in binary format, for example the station name or travel
information, on a inaudible audio subcarrier of a radio program. This
interface aims at devices capable of receiving and decoding RDS
information.</P
><P
>The V4L API defines its RDS API as follows.</P
><P
>From radio devices supporting it, RDS data can be
read with the <CODE
CLASS="FUNCTION"
>read()</CODE
> function. The data is packed
in groups of three, as follows:<P
></P
><OL
TYPE="1"
><LI
><P
>First Octet Least Significant Byte of RDS
Block</P
></LI
><LI
><P
>Second Octet Most Significant Byte of RDS
Block</P
></LI
><LI
><P
>Third Octet Bit 7: Error bit. Indicates that an
uncorrectable error occurred during reception of this block. Bit 6:
Corrected bit. Indicates that an error was corrected for this data
block. Bits 5-3: Received Offset. Indicates the offset received by the
sync system. Bits 2-0: Offset Name. Indicates the offset applied to
this data.</P
></LI
></OL
></P
><P
>It was argued <SPAN
CLASS="COMMENT"
>video4linux-list@redhat.com
on 12 Nov 2002, subject "RDS/RBDS"</SPAN
> the RDS API should be
extended before integration into V4L2, no new API has been devised yet.
Please write to the Video4Linux mailing list for discussion: <A
HREF="https://listman.redhat.com/mailman/listinfo/video4linux-list"
TARGET="_top"
>https://listman.redhat.com/mailman/listinfo/video4linux-list</A
>.
Meanwhile no V4L2 driver should set the
<CODE
CLASS="CONSTANT"
>V4L2_CAP_RDS_CAPTURE</CODE
> capability flag.</P
></DIV
></DIV
><DIV
CLASS="REFERENCE"
><A
NAME="USER-FUNC"
></A
><DIV
CLASS="TITLEPAGE"
><H1
CLASS="TITLE"
>I. Function Reference</H1
><DIV
CLASS="TOC"
><DL
><DT
><B
>Table of Contents</B
></DT
><DT
><A
HREF="#FUNC-CLOSE"
>close</A
> -- Close a V4L2 device</DT
><DT
><A
HREF="#FUNC-IOCTL"
>ioctl</A
> -- Program a V4L2 device</DT
><DT
><A
HREF="#VIDIOC-CROPCAP"
>ioctl VIDIOC_CROPCAP</A
> -- Information about the video cropping and scaling abilities.</DT
><DT
><A
HREF="#VIDIOC-ENUMAUDIO"
>ioctl VIDIOC_ENUMAUDIO</A
> -- Enumerate audio inputs</DT
><DT
><A
HREF="#VIDIOC-ENUMAUDIOOUT"
>ioctl VIDIOC_ENUMAUDOUT</A
> -- Enumerate audio outputs</DT
><DT
><A
HREF="#VIDIOC-ENUM-FMT"
>ioctl VIDIOC_ENUM_FMT</A
> -- Enumerate image formats</DT
><DT
><A
HREF="#VIDIOC-ENUMINPUT"
>ioctl VIDIOC_ENUMINPUT</A
> -- Enumerate video inputs</DT
><DT
><A
HREF="#VIDIOC-ENUMOUTPUT"
>ioctl VIDIOC_ENUMOUTPUT</A
> -- Enumerate video outputs</DT
><DT
><A
HREF="#VIDIOC-ENUMSTD"
>ioctl VIDIOC_ENUMSTD</A
> -- Enumerate supported video standards</DT
><DT
><A
HREF="#VIDIOC-G-AUDIO"
>ioctl VIDIOC_G_AUDIO, VIDIOC_S_AUDIO</A
> -- Query or select the current audio input and its
attributes</DT
><DT
><A
HREF="#VIDIOC-G-AUDIOOUT"
>ioctl VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT</A
> -- Query or select the current audio output</DT
><DT
><A
HREF="#VIDIOC-G-COMP"
>ioctl VIDIOC_G_COMP, VIDIOC_S_COMP</A
> -- Get or set compression parameters</DT
><DT
><A
HREF="#VIDIOC-G-CROP"
>ioctl VIDIOC_G_CROP, VIDIOC_S_CROP</A
> -- Get or set the current cropping rectangle</DT
><DT
><A
HREF="#VIDIOC-G-CTRL"
>ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL</A
> -- Get or set the value of a control</DT
><DT
><A
HREF="#VIDIOC-G-FBUF"
>ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF</A
> -- Get or set frame buffer overlay parameters.</DT
><DT
><A
HREF="#VIDIOC-G-FMT"
>ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT</A
> -- Get or set the data format, try a format.</DT
><DT
><A
HREF="#VIDIOC-G-FREQUENCY"
>ioctl VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY</A
> -- Get or set tuner or modulator radio
frequency</DT
><DT
><A
HREF="#VIDIOC-G-INPUT"
>ioctl VIDIOC_G_INPUT, VIDIOC_S_INPUT</A
> -- Query or select the current video input</DT
><DT
><A
HREF="#VIDIOC-G-JPEGCOMP"
>ioctl VIDIOC_G_JPEGCOMP, VIDIOC_S_JPEGCOMP</A
> -- </DT
><DT
><A
HREF="#VIDIOC-G-MODULATOR"
>ioctl VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR</A
> -- Get or set modulator attributes</DT
><DT
><A
HREF="#VIDIOC-G-OUTPUT"
>ioctl VIDIOC_G_OUTPUT, VIDIOC_S_OUTPUT</A
> -- Query or select the current video output</DT
><DT
><A
HREF="#VIDIOC-G-PARM"
>ioctl VIDIOC_G_PARM, VIDIOC_S_PARM</A
> -- Get or set streaming parameters</DT
><DT
><A
HREF="#VIDIOC-G-PRIORITY"
>ioctl VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY</A
> -- Query or request the access priority associated with a
file descriptor</DT
><DT
><A
HREF="#VIDIOC-G-STD"
>ioctl VIDIOC_G_STD, VIDIOC_S_STD</A
> -- Query or select the video standard of the current input</DT
><DT
><A
HREF="#VIDIOC-G-TUNER"
>ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER</A
> -- Get or set tuner attributes</DT
><DT
><A
HREF="#VIDIOC-OVERLAY"
>ioctl VIDIOC_OVERLAY</A
> -- Start or stop video overlay</DT
><DT
><A
HREF="#VIDIOC-QBUF"
>ioctl VIDIOC_QBUF, VIDIOC_DQBUF</A
> -- Exchange a buffer with the driver</DT
><DT
><A
HREF="#VIDIOC-QUERYBUF"
>ioctl VIDIOC_QUERYBUF</A
> -- Query the status of a buffer</DT
><DT
><A
HREF="#VIDIOC-QUERYCAP"
>ioctl VIDIOC_QUERYCAP</A
> -- Query device capabilities</DT
><DT
><A
HREF="#VIDIOC-QUERYCTRL"
>ioctl VIDIOC_QUERYCTRL, VIDIOC_QUERYMENU</A
> -- Enumerate controls and menu control items</DT
><DT
><A
HREF="#VIDIOC-QUERYSTD"
>ioctl VIDIOC_QUERYSTD</A
> -- Sense the video standard received by the current input</DT
><DT
><A
HREF="#VIDIOC-REQBUFS"
>ioctl VIDIOC_REQBUFS</A
> -- Initiate Memory Mapping or User Pointer I/O</DT
><DT
><A
HREF="#VIDIOC-STREAMON"
>ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF</A
> -- Start or stop streaming I/O.</DT
><DT
><A
HREF="#FUNC-MMAP"
>mmap</A
> -- Map device memory into application address space</DT
><DT
><A
HREF="#FUNC-MUNMAP"
>munmap</A
> -- Unmap device memory</DT
><DT
><A
HREF="#FUNC-OPEN"
>open</A
> -- Open a V4L2 device</DT
><DT
><A
HREF="#FUNC-POLL"
>poll</A
> -- Wait for some event on a file descriptor</DT
><DT
><A
HREF="#FUNC-READ"
>read</A
> -- Read from a V4L2 device</DT
><DT
><A
HREF="#FUNC-SELECT"
>select</A
> -- Synchronous I/O multiplexing</DT
><DT
><A
HREF="#FUNC-WRITE"
>write</A
> -- Write to a V4L2 device</DT
></DL
></DIV
></DIV
><H1
><A
NAME="FUNC-CLOSE"
></A
>close</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN4841"
></A
><H2
>Name</H2
>close -- Close a V4L2 device</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN4844"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN4845"
></A
><PRE
CLASS="FUNCSYNOPSISINFO"
>#include <unistd.h></PRE
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int close</CODE
>(int fd);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN4852"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><VAR
CLASS="PARAMETER"
>fd</VAR
></DT
><DD
><P
>File descriptor returned by <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
>.</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN4862"
></A
><H2
>Description</H2
><P
>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.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN4865"
></A
><H2
>Return Value</H2
><P
>The function returns <SPAN
CLASS="RETURNVALUE"
>0</SPAN
> on
success, <SPAN
CLASS="RETURNVALUE"
>-1</SPAN
> on failure and the
<VAR
CLASS="VARNAME"
>errno</VAR
> is set appropriately. Possible error
codes:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="ERRORCODE"
>EBADF</SPAN
></DT
><DD
><P
><VAR
CLASS="PARAMETER"
>fd</VAR
> is not a valid open file
descriptor.</P
></DD
></DL
></DIV
></DIV
><H1
><A
NAME="FUNC-IOCTL"
></A
>ioctl</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN4879"
></A
><H2
>Name</H2
>ioctl -- Program a V4L2 device</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN4882"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN4883"
></A
><PRE
CLASS="FUNCSYNOPSISINFO"
>#include <sys/ioctl.h></PRE
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, void *argp);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN4894"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><VAR
CLASS="PARAMETER"
>fd</VAR
></DT
><DD
><P
>File descriptor returned by <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
>.</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>request</VAR
></DT
><DD
><P
>V4L2 ioctl request code as defined in the <A
HREF="#VIDEODEV"
>videodev.h</A
> header file, for example
VIDIOC_QUERYCAP.</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>argp</VAR
></DT
><DD
><P
>Pointer to a function parameter, usually a structure.</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN4915"
></A
><H2
>Description</H2
><P
>The <CODE
CLASS="FUNCTION"
>ioctl()</CODE
> function is used to program
V4L2 devices. The argument <VAR
CLASS="PARAMETER"
>fd</VAR
> must be an open
file descriptor. An ioctl <VAR
CLASS="PARAMETER"
>request</VAR
> has encoded
in it whether the argument is an input, output or read/write
parameter, and the size of the argument <VAR
CLASS="PARAMETER"
>argp</VAR
> in
bytes. Macros and defines specifying V4L2 ioctl requests are located
in the <A
HREF="#VIDEODEV"
>videodev.h</A
> 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 <A
HREF="#USER-FUNC"
>Reference I, <I
>Function Reference</I
></A
>.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN4924"
></A
><H2
>Return Value</H2
><P
>On success the <CODE
CLASS="FUNCTION"
>ioctl()</CODE
> function returns
<SPAN
CLASS="RETURNVALUE"
>0</SPAN
> and does not reset the
<VAR
CLASS="VARNAME"
>errno</VAR
> variable. On failure
<SPAN
CLASS="RETURNVALUE"
>-1</SPAN
> is returned, when the ioctl takes an
output or read/write parameter it remains unmodified, and the
<VAR
CLASS="VARNAME"
>errno</VAR
> variable is set appropriately. See below for
possible error codes. Generic errors like <SPAN
CLASS="ERRORCODE"
>EBADF</SPAN
>
or <SPAN
CLASS="ERRORCODE"
>EFAULT</SPAN
> are not listed in the sections
discussing individual ioctl requests.</P
><P
>Note ioctls may return undefined error codes. Since errors
may have side effects such as a driver reset applications should
abort on unexpected errors.</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="ERRORCODE"
>EBADF</SPAN
></DT
><DD
><P
><VAR
CLASS="PARAMETER"
>fd</VAR
> is not a valid open file
descriptor.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>EBUSY</SPAN
></DT
><DD
><P
>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.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>EFAULT</SPAN
></DT
><DD
><P
><VAR
CLASS="PARAMETER"
>argp</VAR
> references an inaccessible
memory area.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>ENOTTY</SPAN
></DT
><DD
><P
><VAR
CLASS="PARAMETER"
>fd</VAR
> is not associated with a
character special device.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
></DT
><DD
><P
>The <VAR
CLASS="PARAMETER"
>request</VAR
> or the data pointed
to by <VAR
CLASS="PARAMETER"
>argp</VAR
> is not valid. This is a very common
error code, see the individual ioctl requests listed in <A
HREF="#USER-FUNC"
>Reference I, <I
>Function Reference</I
></A
> for actual causes.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>ENOMEM</SPAN
></DT
><DD
><P
>Insufficient memory to complete the request.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>ERANGE</SPAN
></DT
><DD
><P
>The application attempted to set a control with the
<A
HREF="#VIDIOC-G-CTRL"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_CTRL</CODE
></A
> ioctl to a value which is out of bounds.</P
></DD
></DL
></DIV
></DIV
><H1
><A
NAME="VIDIOC-CROPCAP"
></A
>ioctl VIDIOC_CROPCAP</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN4980"
></A
><H2
>Name</H2
>ioctl VIDIOC_CROPCAP -- Information about the video cropping and scaling abilities.</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN4983"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN4984"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, struct v4l2_cropcap
*argp);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN4994"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><VAR
CLASS="PARAMETER"
>fd</VAR
></DT
><DD
><P
>File descriptor returned by <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
>.</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>request</VAR
></DT
><DD
><P
>VIDIOC_CROPCAP</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>argp</VAR
></DT
><DD
><P
></P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN5014"
></A
><H2
>Description</H2
><P
>Applications use this function to query the cropping
limits, the pixel aspect of images and to calculate scale factors.
They set the <CODE
CLASS="STRUCTFIELD"
>type</CODE
> field of a v4l2_cropcap
structure to the respective buffer (stream) type and call the
<CODE
CLASS="CONSTANT"
>VIDIOC_CROPCAP</CODE
> 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.</P
><DIV
CLASS="TABLE"
><A
NAME="V4L2-CROPCAP"
></A
><P
><B
>Table 1. struct <CODE
CLASS="STRUCTNAME"
>v4l2_cropcap</CODE
></B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="25%"
TITLE="C1"><COL
WIDTH="25%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
>enum <A
HREF="#V4L2-BUF-TYPE"
>v4l2_buf_type</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>type</CODE
></TD
><TD
>Type of the data stream, set by the application.
Only these types are valid here:
<CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_VIDEO_CAPTURE</CODE
>,
<CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_VIDEO_OUTPUT</CODE
>,
<CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_VIDEO_OVERLAY</CODE
>, and custom (driver
defined) types with code <CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_PRIVATE</CODE
>
and higher.</TD
></TR
><TR
><TD
>struct <A
HREF="#V4L2-RECT-CROP"
>v4l2_rect</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>bounds</CODE
></TD
><TD
>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.</TD
></TR
><TR
><TD
>struct <A
HREF="#V4L2-RECT-CROP"
>v4l2_rect</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>defrect</CODE
></TD
><TD
>Default cropping rectangle, it shall cover the
"whole picture". Assuming pixel aspect 1/1 this could be for example a
640 × 480 rectangle for NTSC, a
768 × 576 rectangle for PAL and SECAM centered over
the active picture area. The same co-ordinate system as for
<CODE
CLASS="STRUCTFIELD"
>bounds</CODE
> is used.</TD
></TR
><TR
><TD
>struct <A
HREF="#V4L2-FRACT"
>v4l2_fract</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>pixelaspect</CODE
></TD
><TD
><P
>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.</P
><P
>When cropping coordinates refer to square pixels,
the driver sets <CODE
CLASS="STRUCTFIELD"
>pixelaspect</CODE
> to 1/1. Other
common values are 54/59 for PAL and SECAM, 11/10 for NTSC sampled
according to [<A
HREF="#ITU601"
><ABBR
CLASS="ABBREV"
>ITU601</ABBR
></A
>].</P
></TD
></TR
></TBODY
></TABLE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="V4L2-RECT-CROP"
></A
><P
><B
>Table 2. struct <CODE
CLASS="STRUCTNAME"
>v4l2_rect</CODE
></B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="25%"
TITLE="C1"><COL
WIDTH="25%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
>__s32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>left</CODE
></TD
><TD
>Horizontal offset of the top, left corner of the
rectangle, in pixels.</TD
></TR
><TR
><TD
>__s32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>top</CODE
></TD
><TD
>Vertical offset of the top, left corner of the
rectangle, in pixels.</TD
></TR
><TR
><TD
>__s32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>width</CODE
></TD
><TD
>Width of the rectangle, in pixels.</TD
></TR
><TR
><TD
>__s32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>height</CODE
></TD
><TD
>Height of the rectangle, in pixels. Width
and height cannot be negative, the fields are signed for
hysterical reasons. <P
CLASS="COMMENT"
>video4linux-list@redhat.com
on 22 Oct 2002 subject "Re:[V4L][patches!] Re:v4l2/kernel-2.5"</P
></TD
></TR
></TBODY
></TABLE
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN5091"
></A
><H2
>Return Value</H2
><P
>On success <SPAN
CLASS="RETURNVALUE"
>0</SPAN
> is returned, on
error <SPAN
CLASS="RETURNVALUE"
>-1</SPAN
> and <VAR
CLASS="VARNAME"
>errno</VAR
> is
set appropriately:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
></DT
><DD
><P
>The struct <A
HREF="#V4L2-CROPCAP"
>v4l2_cropcap</A
> <CODE
CLASS="STRUCTFIELD"
>type</CODE
> is
invalid or the ioctl is not supported. This is not permitted for
video capture, output and overlay devices, which must support
<CODE
CLASS="CONSTANT"
>VIDIOC_CROPCAP</CODE
>.</P
></DD
></DL
></DIV
></DIV
><H1
><A
NAME="VIDIOC-ENUMAUDIO"
></A
>ioctl VIDIOC_ENUMAUDIO</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN5107"
></A
><H2
>Name</H2
>ioctl VIDIOC_ENUMAUDIO -- Enumerate audio inputs</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN5110"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN5111"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, struct v4l2_audio *argp);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN5121"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><VAR
CLASS="PARAMETER"
>fd</VAR
></DT
><DD
><P
>File descriptor returned by <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
>.</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>request</VAR
></DT
><DD
><P
>VIDIOC_ENUMAUDIO</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>argp</VAR
></DT
><DD
><P
></P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN5141"
></A
><H2
>Description</H2
><P
>To query the attributes of an audio input applications
initialize the <CODE
CLASS="STRUCTFIELD"
>index</CODE
> field and zero out the
<CODE
CLASS="STRUCTFIELD"
>reserved</CODE
> array of a struct <A
HREF="#V4L2-AUDIO"
>v4l2_audio</A
>
and call the <CODE
CLASS="CONSTANT"
>VIDIOC_ENUMAUDIO</CODE
> ioctl with a pointer
to this structure. Drivers fill the rest of the structure or return an
<SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code 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 <SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
>.</P
><P
>See <A
HREF="#VIDIOC-G-AUDIO"
>ioctl VIDIOC_G_AUDIO, VIDIOC_S_AUDIO</A
> for a description of
struct <A
HREF="#V4L2-AUDIO"
>v4l2_audio</A
>.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN5153"
></A
><H2
>Return Value</H2
><P
>On success <SPAN
CLASS="RETURNVALUE"
>0</SPAN
> is returned, on
error <SPAN
CLASS="RETURNVALUE"
>-1</SPAN
> and <VAR
CLASS="VARNAME"
>errno</VAR
> is
set appropriately:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
></DT
><DD
><P
>The number of the audio input is out of bounds, or
there are no audio inputs at all and this ioctl is not
supported.</P
></DD
></DL
></DIV
></DIV
><H1
><A
NAME="VIDIOC-ENUMAUDIOOUT"
></A
>ioctl VIDIOC_ENUMAUDOUT</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN5166"
></A
><H2
>Name</H2
>ioctl VIDIOC_ENUMAUDOUT -- Enumerate audio outputs</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN5169"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN5170"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, struct v4l2_audioout *argp);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN5180"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><VAR
CLASS="PARAMETER"
>fd</VAR
></DT
><DD
><P
>File descriptor returned by <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
>.</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>request</VAR
></DT
><DD
><P
>VIDIOC_ENUMAUDOUT</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>argp</VAR
></DT
><DD
><P
></P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN5200"
></A
><H2
>Description</H2
><P
>To query the attributes of an audio output applications
initialize the <CODE
CLASS="STRUCTFIELD"
>index</CODE
> field and zero out the
<CODE
CLASS="STRUCTFIELD"
>reserved</CODE
> array of a struct <A
HREF="#V4L2-AUDIOOUT"
>v4l2_audioout</A
> and
call the <CODE
CLASS="CONSTANT"
>VIDIOC_G_AUDOUT</CODE
> ioctl with a pointer
to this structure. Drivers fill the rest of the structure or return an
<SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code 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 <SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
>.</P
><P
>Note connectors on a TV card to loop back the received audio
signal to a sound card are not audio outputs in this sense.</P
><P
>See <A
HREF="#VIDIOC-G-AUDIOOUT"
>ioctl VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT</A
> for a description of
struct <A
HREF="#V4L2-AUDIOOUT"
>v4l2_audioout</A
>.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN5213"
></A
><H2
>Return Value</H2
><P
>On success <SPAN
CLASS="RETURNVALUE"
>0</SPAN
> is returned, on
error <SPAN
CLASS="RETURNVALUE"
>-1</SPAN
> and <VAR
CLASS="VARNAME"
>errno</VAR
> is
set appropriately:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
></DT
><DD
><P
>The number of the audio output is out of bounds, or
there are no audio outputs at all and this ioctl is not
supported.</P
></DD
></DL
></DIV
></DIV
><H1
><A
NAME="VIDIOC-ENUM-FMT"
></A
>ioctl VIDIOC_ENUM_FMT</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN5226"
></A
><H2
>Name</H2
>ioctl VIDIOC_ENUM_FMT -- Enumerate image formats</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN5229"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN5230"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, struct v4l2_fmtdesc
*argp);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN5240"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><VAR
CLASS="PARAMETER"
>fd</VAR
></DT
><DD
><P
>File descriptor returned by <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
>.</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>request</VAR
></DT
><DD
><P
>VIDIOC_ENUM_FMT</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>argp</VAR
></DT
><DD
><P
></P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN5260"
></A
><H2
>Description</H2
><P
>To enumerate image formats applications initialize the
<CODE
CLASS="STRUCTFIELD"
>type</CODE
> and <CODE
CLASS="STRUCTFIELD"
>index</CODE
>
field of struct <A
HREF="#V4L2-FMTDESC"
>v4l2_fmtdesc</A
> and call the
<CODE
CLASS="CONSTANT"
>VIDIOC_ENUM_FMT</CODE
> ioctl with a pointer to this
structure. Drivers fill the rest of the structure or return an
<SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code. All formats are enumerable by beginning at index zero and
incrementing by one until <SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> is
returned.</P
><DIV
CLASS="TABLE"
><A
NAME="V4L2-FMTDESC"
></A
><P
><B
>Table 1. struct <CODE
CLASS="STRUCTNAME"
>v4l2_fmtdesc</CODE
></B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="25%"
TITLE="C1"><COL
WIDTH="25%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>index</CODE
></TD
><TD
>Number of the format in the enumeration, set by
the application. This is in no way related to the <CODE
CLASS="STRUCTFIELD"
>pixelformat</CODE
> field.</TD
></TR
><TR
><TD
>enum <A
HREF="#V4L2-BUF-TYPE"
>v4l2_buf_type</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>type</CODE
></TD
><TD
>Type of the data stream, set by the application.
Only these types are valid here:
<CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_VIDEO_CAPTURE</CODE
>,
<CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_VIDEO_OUTPUT</CODE
>,
<CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_VIDEO_OVERLAY</CODE
>, and custom (driver
defined) types with code <CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_PRIVATE</CODE
>
and higher.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>flags</CODE
></TD
><TD
>See <A
HREF="#FMTDESC-FLAGS"
>Table 2</A
></TD
></TR
><TR
><TD
>__u8</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>description</CODE
>[32]</TD
><TD
>Description of the format, a NUL-terminated ASCII
string. This information is intended for the user, for example: "YUV
4:2:2".</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>pixelformat</CODE
></TD
><TD
>The image format identifier. This is a
four character code as computed by the v4l2_fourcc()
macro:</TD
></TR
><TR
><TD
COLSPAN="3"
><P
><PRE
CLASS="PROGRAMLISTING"
>#define v4l2_fourcc(a,b,c,d) (((__u32)(a)<<0)|((__u32)(b)<<8)|((__u32)(c)<<16)|((__u32)(d)<<24))</PRE
></P
><P
>Several image formats are already
defined by this specification in <A
HREF="#PIXFMT"
>Chapter 2</A
>. Note these
codes are not the same as those used in the Windows world.</P
></TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>reserved</CODE
>[4]</TD
><TD
>Reserved for future extensions. Drivers must set
the array to zero.</TD
></TR
></TBODY
></TABLE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="FMTDESC-FLAGS"
></A
><P
><B
>Table 2. Image Format Description Flags</B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="38%"
TITLE="C1"><COL
WIDTH="12%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_FMT_FLAG_COMPRESSED</CODE
></TD
><TD
>0x0001</TD
><TD
>This is a compressed format.</TD
></TR
></TBODY
></TABLE
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN5334"
></A
><H2
>Return Value</H2
><P
>On success <SPAN
CLASS="RETURNVALUE"
>0</SPAN
> is returned, on
error <SPAN
CLASS="RETURNVALUE"
>-1</SPAN
> and <VAR
CLASS="VARNAME"
>errno</VAR
> is
set appropriately:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
></DT
><DD
><P
>The struct <A
HREF="#V4L2-FMTDESC"
>v4l2_fmtdesc</A
> <CODE
CLASS="STRUCTFIELD"
>type</CODE
>
is not supported or the <CODE
CLASS="STRUCTFIELD"
>index</CODE
> is out of
bounds.</P
></DD
></DL
></DIV
></DIV
><H1
><A
NAME="VIDIOC-ENUMINPUT"
></A
>ioctl VIDIOC_ENUMINPUT</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN5350"
></A
><H2
>Name</H2
>ioctl VIDIOC_ENUMINPUT -- Enumerate video inputs</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN5353"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN5354"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, struct v4l2_input
*argp);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN5364"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><VAR
CLASS="PARAMETER"
>fd</VAR
></DT
><DD
><P
>File descriptor returned by <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
>.</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>request</VAR
></DT
><DD
><P
>VIDIOC_ENUMINPUT</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>argp</VAR
></DT
><DD
><P
></P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN5384"
></A
><H2
>Description</H2
><P
>To query the attributes of a video input applications
initialize the <CODE
CLASS="STRUCTFIELD"
>index</CODE
> field of struct <A
HREF="#V4L2-INPUT"
>v4l2_input</A
>
and call the <CODE
CLASS="CONSTANT"
>VIDIOC_ENUMINPUT</CODE
> ioctl with a
pointer to this structure. Drivers fill the rest of the structure or
return an <SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code when the index is out of bounds. To enumerate all
inputs applications shall begin at index zero, incrementing by one
until the driver returns <SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
>.</P
><DIV
CLASS="TABLE"
><A
NAME="V4L2-INPUT"
></A
><P
><B
>Table 1. struct <CODE
CLASS="STRUCTNAME"
>v4l2_input</CODE
></B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="25%"
TITLE="C1"><COL
WIDTH="25%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>index</CODE
></TD
><TD
>Identifies the input, set by the
application.</TD
></TR
><TR
><TD
>__u8</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>name</CODE
>[32]</TD
><TD
>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.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>type</CODE
></TD
><TD
>Type of the input, see <A
HREF="#INPUT-TYPE"
>Table 2</A
>.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>audioset</CODE
></TD
><TD
>Video inputs combine with zero or more audio
inputs. For example one composite video connectors may exist, but two
audio connectors. On the other hand, video from a tuner will likely
combine only with audio from the same tuner. Devices with N audio
inputs number them 0 … N-1 with N ≤ 32. Each bit position of
<CODE
CLASS="STRUCTFIELD"
>audioset</CODE
> represents one audio input. For
details on audio inputs and how to switch see <A
HREF="#AUDIO"
>Section 1.5</A
>.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>tuner</CODE
></TD
><TD
>Capture devices can have zero or more tuners (RF
demodulators). When the <CODE
CLASS="STRUCTFIELD"
>type</CODE
> is set to
<CODE
CLASS="CONSTANT"
>V4L2_INPUT_TYPE_TUNER</CODE
> this is an RF connector and
this field identifies the tuner. It corresponds to
struct <A
HREF="#V4L2-TUNER"
>v4l2_tuner</A
> field <CODE
CLASS="STRUCTFIELD"
>index</CODE
>. For details on
tuners see <A
HREF="#TUNER"
>Section 1.6</A
>.</TD
></TR
><TR
><TD
><A
HREF="#V4L2-STD-ID"
>v4l2_std_id</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>std</CODE
></TD
><TD
>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 <A
HREF="#STANDARD"
>Section 1.7</A
>.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>status</CODE
></TD
><TD
>This field provides status information about the
input. See <A
HREF="#INPUT-STATUS"
>Table 3</A
> for flags.
<CODE
CLASS="STRUCTFIELD"
>status</CODE
> is only valid when this is the
current input.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>reserved</CODE
>[4]</TD
><TD
>Reserved for future extensions. Drivers must set
the array to zero.</TD
></TR
></TBODY
></TABLE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="INPUT-TYPE"
></A
><P
><B
>Table 2. Input Types</B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="38%"
TITLE="C1"><COL
WIDTH="12%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_INPUT_TYPE_TUNER</CODE
></TD
><TD
>1</TD
><TD
>This input uses a tuner (RF demodulator).</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_INPUT_TYPE_CAMERA</CODE
></TD
><TD
>2</TD
><TD
>Analog baseband input, for example CVBS /
Composite Video, S-Video, RGB.</TD
></TR
></TBODY
></TABLE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="INPUT-STATUS"
></A
><P
><B
>Table 3. Input Status Flags</B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="33%"
TITLE="C1"><COL
WIDTH="33%"
ALIGN="CENTER"
TITLE="C2"><COL
WIDTH="33%"
TITLE="C3"><TBODY
><TR
><TD
COLSPAN="3"
ALIGN="LEFT"
>General</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_IN_ST_NO_POWER</CODE
></TD
><TD
>0x00000001</TD
><TD
>Attached device is off.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_IN_ST_NO_SIGNAL</CODE
></TD
><TD
>0x00000002</TD
><TD
> </TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_IN_ST_NO_COLOR</CODE
></TD
><TD
>0x00000004</TD
><TD
> </TD
></TR
><TR
><TD
COLSPAN="3"
ALIGN="LEFT"
>Analog Video</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_IN_ST_NO_H_LOCK</CODE
></TD
><TD
>0x00000100</TD
><TD
>No horizontal sync lock.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_IN_ST_COLOR_KILL</CODE
></TD
><TD
>0x00000200</TD
><TD
>The color killer is a circuit that shuts off the
color decoding when it cannot find the color burst. This flag
indicates if the color killer is <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>enabled</I
></SPAN
>, while
<CODE
CLASS="CONSTANT"
>V4L2_IN_ST_NO_COLOR</CODE
> is set when no color is
<SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>detected</I
></SPAN
>.</TD
></TR
><TR
><TD
COLSPAN="3"
ALIGN="LEFT"
>Digital Video</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_IN_ST_NO_SYNC</CODE
></TD
><TD
>0x00010000</TD
><TD
>No synchronization lock.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_IN_ST_NO_EQU</CODE
></TD
><TD
>0x00020000</TD
><TD
>No equalizer lock.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_IN_ST_NO_CARRIER</CODE
></TD
><TD
>0x00040000</TD
><TD
>Carrier recovery failed.</TD
></TR
><TR
><TD
COLSPAN="3"
ALIGN="LEFT"
>VCR and Set-Top Box</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_IN_ST_MACROVISION</CODE
></TD
><TD
>0x01000000</TD
><TD
>Macrovision is an analog copy protection system
mangling the video signal to confuse video recorders. When this
flag is set Macrovision protection has been detected.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_IN_ST_NO_ACCESS</CODE
></TD
><TD
>0x02000000</TD
><TD
>Conditional access denied.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_IN_ST_VTR</CODE
></TD
><TD
>0x04000000</TD
><TD
>VTR time constant. [?]</TD
></TR
></TBODY
></TABLE
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN5545"
></A
><H2
>Return Value</H2
><P
>On success <SPAN
CLASS="RETURNVALUE"
>0</SPAN
> is returned, on
error <SPAN
CLASS="RETURNVALUE"
>-1</SPAN
> and <VAR
CLASS="VARNAME"
>errno</VAR
> is
set appropriately:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
></DT
><DD
><P
>The struct <A
HREF="#V4L2-INPUT"
>v4l2_input</A
> <CODE
CLASS="STRUCTFIELD"
>index</CODE
> is
out of bounds.</P
></DD
></DL
></DIV
></DIV
><H1
><A
NAME="VIDIOC-ENUMOUTPUT"
></A
>ioctl VIDIOC_ENUMOUTPUT</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN5560"
></A
><H2
>Name</H2
>ioctl VIDIOC_ENUMOUTPUT -- Enumerate video outputs</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN5563"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN5564"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, struct v4l2_output *argp);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN5574"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><VAR
CLASS="PARAMETER"
>fd</VAR
></DT
><DD
><P
>File descriptor returned by <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
>.</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>request</VAR
></DT
><DD
><P
>VIDIOC_ENUMOUTPUT</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>argp</VAR
></DT
><DD
><P
></P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN5594"
></A
><H2
>Description</H2
><P
>To query the attributes of a video outputs applications
initialize the <CODE
CLASS="STRUCTFIELD"
>index</CODE
> field of struct <A
HREF="#V4L2-OUTPUT"
>v4l2_output</A
>
and call the <CODE
CLASS="CONSTANT"
>VIDIOC_ENUMOUTPUT</CODE
> ioctl with a
pointer to this structure. Drivers fill the rest of the structure or
return an <SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code when the index is out of bounds. To enumerate all
outputs applications shall begin at index zero, incrementing by one
until the driver returns <SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
>.</P
><DIV
CLASS="TABLE"
><A
NAME="V4L2-OUTPUT"
></A
><P
><B
>Table 1. struct <CODE
CLASS="STRUCTNAME"
>v4l2_output</CODE
></B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="25%"
TITLE="C1"><COL
WIDTH="25%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>index</CODE
></TD
><TD
>Identifies the output, set by the
application.</TD
></TR
><TR
><TD
>__u8</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>name</CODE
>[32]</TD
><TD
>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.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>type</CODE
></TD
><TD
>Type of the output, see <A
HREF="#OUTPUT-TYPE"
>Table 2</A
>.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>audioset</CODE
></TD
><TD
>Video outputs combine with zero or more audio
outputs. For example one composite video connectors may exist, but two
audio connectors. On the other hand, video to a modulator will likely
combine only with audio to the same modulator. Devices with N audio
outputs number them 0 … N-1 with N ≤ 32. Each bit position of
<CODE
CLASS="STRUCTFIELD"
>audioset</CODE
> represents one audio output. For
details on audio outputs and how to switch see <A
HREF="#AUDIO"
>Section 1.5</A
>.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>modulator</CODE
></TD
><TD
>Output devices can have zero or more RF modulators.
When the <CODE
CLASS="STRUCTFIELD"
>type</CODE
> is
<CODE
CLASS="CONSTANT"
>V4L2_OUTPUT_TYPE_MODULATOR</CODE
> this is an RF
connector and this field identifies the modulator. It corresponds to
struct <A
HREF="#V4L2-MODULATOR"
>v4l2_modulator</A
> field <CODE
CLASS="STRUCTFIELD"
>index</CODE
>. For details
on modulators see <A
HREF="#TUNER"
>Section 1.6</A
>.</TD
></TR
><TR
><TD
><A
HREF="#V4L2-STD-ID"
>v4l2_std_id</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>std</CODE
></TD
><TD
>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 <A
HREF="#STANDARD"
>Section 1.7</A
>.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>reserved</CODE
>[4]</TD
><TD
>Reserved for future extensions. Drivers must set
the array to zero.</TD
></TR
></TBODY
></TABLE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="OUTPUT-TYPE"
></A
><P
><B
>Table 2. Output Type</B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="38%"
TITLE="C1"><COL
WIDTH="12%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_OUTPUT_TYPE_MODULATOR</CODE
></TD
><TD
>1</TD
><TD
>This output is an analog TV modulator.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_OUTPUT_TYPE_ANALOG</CODE
></TD
><TD
>2</TD
><TD
>Analog baseband output, for example Composite /
CVBS, S-Video, RGB.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_OUTPUT_TYPE_ANALOGVGAOVERLAY</CODE
></TD
><TD
>3</TD
><TD
>[?]</TD
></TR
></TBODY
></TABLE
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN5679"
></A
><H2
>Return Value</H2
><P
>On success <SPAN
CLASS="RETURNVALUE"
>0</SPAN
> is returned, on
error <SPAN
CLASS="RETURNVALUE"
>-1</SPAN
> and <VAR
CLASS="VARNAME"
>errno</VAR
> is
set appropriately:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
></DT
><DD
><P
>The struct <A
HREF="#V4L2-OUTPUT"
>v4l2_output</A
> <CODE
CLASS="STRUCTFIELD"
>index</CODE
>
is out of bounds.</P
></DD
></DL
></DIV
></DIV
><H1
><A
NAME="VIDIOC-ENUMSTD"
></A
>ioctl VIDIOC_ENUMSTD</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN5694"
></A
><H2
>Name</H2
>ioctl VIDIOC_ENUMSTD -- Enumerate supported video standards</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN5697"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN5698"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, struct v4l2_standard *argp);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN5708"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><VAR
CLASS="PARAMETER"
>fd</VAR
></DT
><DD
><P
>File descriptor returned by <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
>.</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>request</VAR
></DT
><DD
><P
>VIDIOC_ENUMSTD</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>argp</VAR
></DT
><DD
><P
></P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN5728"
></A
><H2
>Description</H2
><P
>To query the attributes of a video standard,
especially a custom (driver defined) one, applications initialize the
<CODE
CLASS="STRUCTFIELD"
>index</CODE
> field of struct <A
HREF="#V4L2-STANDARD"
>v4l2_standard</A
> and call the
<CODE
CLASS="CONSTANT"
>VIDIOC_ENUMSTD</CODE
> ioctl with a pointer to this
structure. Drivers fill the rest of the structure or return an
<SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code when the index is out of bounds. To enumerate all standards
applications shall begin at index zero, incrementing by one until the
driver returns <SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
>. Drivers may enumerate a
different set of standards after switching the video input or
output.<A
NAME="AEN5736"
HREF="#FTN.AEN5736"
><SPAN
CLASS="footnote"
>[24]</SPAN
></A
></P
><DIV
CLASS="TABLE"
><A
NAME="V4L2-STANDARD"
></A
><P
><B
>Table 1. struct <CODE
CLASS="STRUCTNAME"
>v4l2_standard</CODE
></B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="25%"
TITLE="C1"><COL
WIDTH="25%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>index</CODE
></TD
><TD
>Number of the video standard, set by the
application.</TD
></TR
><TR
><TD
><A
HREF="#V4L2-STD-ID"
>v4l2_std_id</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>id</CODE
></TD
><TD
>The bits in this field identify the standard as
one of the common standards listed in <A
HREF="#V4L2-STD-ID"
>Table 3</A
>,
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
<CODE
CLASS="STRUCTFIELD"
>id</CODE
> must be unique. No other enumerated
<CODE
CLASS="STRUCTNAME"
>v4l2_standard</CODE
> structure, for this input or
output anyway, can contain the same set of bits.</TD
></TR
><TR
><TD
>__u8</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>name</CODE
>[24]</TD
><TD
>Name of the standard, a NUL-terminated ASCII
string, for example: "PAL-B/G", "NTSC Japan". This information is
intended for the user.</TD
></TR
><TR
><TD
>struct <A
HREF="#V4L2-FRACT"
>v4l2_fract</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>frameperiod</CODE
></TD
><TD
>The frame period (not field period) is numerator
/ denominator. For example M/NTSC has a frame period of 1001 /
30000 seconds.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>framelines</CODE
></TD
><TD
>Total lines per frame including blanking,
e. g. 625 for B/PAL.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>reserved</CODE
>[4]</TD
><TD
>Reserved for future extensions. Drivers must set
the array to zero.</TD
></TR
></TBODY
></TABLE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="V4L2-FRACT"
></A
><P
><B
>Table 2. struct <CODE
CLASS="STRUCTNAME"
>v4l2_fract</CODE
></B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="25%"
TITLE="C1"><COL
WIDTH="25%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>numerator</CODE
></TD
><TD
> </TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>denominator</CODE
></TD
><TD
> </TD
></TR
></TBODY
></TABLE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="V4L2-STD-ID"
></A
><P
><B
>Table 3. typedef <CODE
CLASS="STRUCTNAME"
>v4l2_std_id</CODE
></B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="25%"
TITLE="C1"><COL
WIDTH="25%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
>__u64</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>v4l2_std_id</CODE
></TD
><TD
>This type is a set, each bit representing
another video standard as listed below and in <A
HREF="#VIDEO-STANDARDS"
>Table 4</A
>.</TD
></TR
><TR
><TD
COLSPAN="3"
><P
><CODE
CLASS="CONSTANT"
>V4L2_STD_PAL_60</CODE
> is a
hybrid standard with 525 lines, 60 Hz refresh rate, but PAL
color modulation. Some PAL video recorders can play back NTSC tapes in this
mode for display on 50/60 Hz agnostic PAL TVs.</P
><P
><CODE
CLASS="CONSTANT"
>V4L2_STD_ATSC_8_VSB</CODE
> and
<CODE
CLASS="CONSTANT"
>V4L2_STD_ATSC_16_VSB</CODE
> are the U.S. terrestrial
digital TV standards. The present V4L2 API makes no provisions for
digital TV reception, so no driver will report these standards
yet. See also the Linux DVB API at
<A
HREF="http://linuxtv.org"
TARGET="_top"
>http://linuxtv.org</A
>.</P
><P
>Bit
32 to 63 are reserved for custom (driver defined) video
standards.</P
></TD
></TR
></TBODY
></TABLE
></DIV
><P
><PRE
CLASS="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)
#define V4L2_STD_NTSC_M ((v4l2_std_id)0x00001000)
#define V4L2_STD_NTSC_M_JP ((v4l2_std_id)0x00002000)
#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)
/* ATSC/HDTV */
#define V4L2_STD_ATSC_8_VSB ((v4l2_std_id)0x01000000)
#define V4L2_STD_ATSC_16_VSB ((v4l2_std_id)0x02000000)
#define V4L2_STD_PAL_BG (V4L2_STD_PAL_B |\
V4L2_STD_PAL_B1 |\
V4L2_STD_PAL_G)
#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)
#define V4L2_STD_SECAM (V4L2_STD_SECAM_B |\
V4L2_STD_SECAM_D |\
V4L2_STD_SECAM_G |\
V4L2_STD_SECAM_H |\
V4L2_STD_SECAM_K |\
V4L2_STD_SECAM_K1 |\
V4L2_STD_SECAM_L)
#define V4L2_STD_525_60 (V4L2_STD_PAL_M |\
V4L2_STD_PAL_60 |\
V4L2_STD_NTSC)
#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)</PRE
></P
><DIV
CLASS="TABLE"
><A
NAME="VIDEO-STANDARDS"
></A
><P
><B
>Table 4. Video Standards (based on [<A
HREF="#ITU470"
><ABBR
CLASS="ABBREV"
>ITU470</ABBR
></A
>])</B
></P
><TABLE
BORDER="1"
RULES="all"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="12%"
ALIGN="LEFT"
TITLE="C1"><COL
WIDTH="12%"
TITLE="C2"><COL
WIDTH="12%"
TITLE="C3"><COL
WIDTH="12%"
TITLE="C4"><COL
WIDTH="12%"
TITLE="C5"><COL><COL
WIDTH="12%"
TITLE="C7"><COL><COL
WIDTH="12%"
TITLE="C9"><COL><COL><COL
WIDTH="12%"
TITLE="C12"><THEAD
><TR
><TH
>Characteristics</TH
><TH
><P
>M/NTSC<SUP
>a</SUP
></P
></TH
><TH
>M/PAL</TH
><TH
><P
>N/PAL<SUP
>b</SUP
></P
></TH
><TH
ALIGN="CENTER"
>B, B1, G/PAL</TH
><TH
ALIGN="CENTER"
>D, D1, K/PAL</TH
><TH
ALIGN="CENTER"
>H/PAL</TH
><TH
ALIGN="CENTER"
>I/PAL</TH
><TH
ALIGN="CENTER"
>B, G/SECAM</TH
><TH
ALIGN="CENTER"
>D, K/SECAM</TH
><TH
ALIGN="CENTER"
>K1/SECAM</TH
><TH
ALIGN="CENTER"
>L/SECAM</TH
></TR
></THEAD
><TBODY
><TR
><TD
>Frame lines</TD
><TD
COLSPAN="2"
ALIGN="CENTER"
>525</TD
><TD
COLSPAN="9"
ALIGN="CENTER"
>625</TD
></TR
><TR
><TD
>Frame period (s)</TD
><TD
COLSPAN="2"
ALIGN="CENTER"
>1001/30000</TD
><TD
COLSPAN="9"
ALIGN="CENTER"
>1/25</TD
></TR
><TR
><TD
>Chrominance sub-carrier frequency (Hz)</TD
><TD
>3579545 ± 10</TD
><TD
>3579611.49 ± 10</TD
><TD
>4433618.75 ± 5 (3582056.25
± 5)</TD
><TD
COLSPAN="3"
ALIGN="CENTER"
>4433618.75 ± 5</TD
><TD
>4433618.75 ± 1</TD
><TD
COLSPAN="4"
ALIGN="CENTER"
>f<SUB
>OR</SUB
> =
4406250 ± 2000, f<SUB
>OB</SUB
> = 4250000
± 2000</TD
></TR
><TR
><TD
>Nominal radio-frequency channel bandwidth
(MHz)</TD
><TD
>6</TD
><TD
>6</TD
><TD
>6</TD
><TD
>B: 7; B1, G: 8</TD
><TD
>8</TD
><TD
>8</TD
><TD
>8</TD
><TD
>8</TD
><TD
>8</TD
><TD
>8</TD
><TD
>8</TD
></TR
><TR
><TD
>Sound carrier relative to vision carrier
(MHz)</TD
><TD
>+ 4.5</TD
><TD
>+ 4.5</TD
><TD
>+ 4.5</TD
><TD
><P
>+ 5.5 ± 0.001
<SUP
>c</SUP
> <SUP
>d</SUP
> <SUP
>e</SUP
> <SUP
>f</SUP
></P
></TD
><TD
>+ 6.5 ± 0.001</TD
><TD
>+ 5.5</TD
><TD
>+ 5.9996 ± 0.0005</TD
><TD
>+ 5.5 ± 0.001</TD
><TD
>+ 6.5 ± 0.001</TD
><TD
>+ 6.5</TD
><TD
><P
>+ 6.5 <SUP
>g</SUP
></P
></TD
></TR
></TBODY
><TR
><TD
COLSPAN="12"
>Notes:<BR><A
NAME="FTN.AEN5849"
>a. </A
>Japan uses a standard
similar to M/NTSC
(V4L2_STD_NTSC_M_JP).<BR><A
NAME="FTN.AEN5854"
>b. </A
> The values in
brackets apply to the combination N/PAL a.k.a.
N<SUB
>C</SUB
> used in Argentina
(V4L2_STD_PAL_Nc).<BR><A
NAME="FTN.AEN5904"
>c. </A
>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 kHz above the frequency of the first sound carrier. For
stereophonic sound transmissions a similar system is used in
Australia.<BR><A
NAME="FTN.AEN5906"
>d. </A
>New Zealand uses a sound
carrier displaced 5.4996 ± 0.0005 MHz from the vision
carrier.<BR><A
NAME="FTN.AEN5908"
>e. </A
>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 MHz above the vision carrier and is DQPSK
modulated with 728 kbit/s sound and data multiplex. (NICAM
system)<BR><A
NAME="FTN.AEN5910"
>f. </A
>In the United Kingdom, a
system of two sound carriers is used. The second sound carrier is
6.552 MHz above the vision carrier and is DQPSK modulated with a
728 kbit/s sound and data multiplex able to carry two sound
channels. (NICAM system)<BR><A
NAME="FTN.AEN5920"
>g. </A
>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)<BR></TD
></TR
></TABLE
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN5922"
></A
><H2
>Return Value</H2
><P
>On success <SPAN
CLASS="RETURNVALUE"
>0</SPAN
> is returned, on
error <SPAN
CLASS="RETURNVALUE"
>-1</SPAN
> and <VAR
CLASS="VARNAME"
>errno</VAR
> is
set appropriately:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
></DT
><DD
><P
>The struct <A
HREF="#V4L2-STANDARD"
>v4l2_standard</A
> <CODE
CLASS="STRUCTFIELD"
>index</CODE
>
is out of bounds.</P
></DD
></DL
></DIV
></DIV
><H1
><A
NAME="VIDIOC-G-AUDIO"
></A
>ioctl VIDIOC_G_AUDIO, VIDIOC_S_AUDIO</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN5939"
></A
><H2
>Name</H2
>ioctl VIDIOC_G_AUDIO, ioctl VIDIOC_S_AUDIO -- Query or select the current audio input and its
attributes</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN5943"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN5944"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, struct v4l2_audio *argp);</CODE
></P
><P
></P
></DIV
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN5954"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, const struct v4l2_audio *argp);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN5964"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><VAR
CLASS="PARAMETER"
>fd</VAR
></DT
><DD
><P
>File descriptor returned by <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
>.</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>request</VAR
></DT
><DD
><P
>VIDIOC_G_AUDIO, VIDIOC_S_AUDIO</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>argp</VAR
></DT
><DD
><P
></P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN5984"
></A
><H2
>Description</H2
><P
>To query the current audio input applications zero out the
<CODE
CLASS="STRUCTFIELD"
>reserved</CODE
> array of a struct <A
HREF="#V4L2-AUDIO"
>v4l2_audio</A
>
and call the <CODE
CLASS="CONSTANT"
>VIDIOC_G_AUDIO</CODE
> ioctl with a pointer
to this structure. Drivers fill the rest of the structure or return an
<SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code when the device has no audio inputs, or none which combine
with the current video input.</P
><P
>Audio inputs have one writable property, the audio mode. To
select the current audio input <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>and</I
></SPAN
> change the
audio mode, applications initialize the
<CODE
CLASS="STRUCTFIELD"
>index</CODE
> and <CODE
CLASS="STRUCTFIELD"
>mode</CODE
>
fields, and the
<CODE
CLASS="STRUCTFIELD"
>reserved</CODE
> array of a
<CODE
CLASS="STRUCTNAME"
>v4l2_audio</CODE
> structure and call the
<CODE
CLASS="CONSTANT"
>VIDIOC_S_AUDIO</CODE
> 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.</P
><DIV
CLASS="TABLE"
><A
NAME="V4L2-AUDIO"
></A
><P
><B
>Table 1. struct <CODE
CLASS="STRUCTNAME"
>v4l2_audio</CODE
></B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="25%"
TITLE="C1"><COL
WIDTH="25%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>index</CODE
></TD
><TD
>Identifies the audio input, set by the
driver or application.</TD
></TR
><TR
><TD
>__u8</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>name</CODE
>[32]</TD
><TD
>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.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>capability</CODE
></TD
><TD
>Audio capability flags, see <A
HREF="#AUDIO-CAPABILITY"
>Table 2</A
>.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>mode</CODE
></TD
><TD
>Audio mode set by drivers and applications (on
<CODE
CLASS="CONSTANT"
>VIDIOC_S_AUDIO</CODE
> ioctl), see <A
HREF="#AUDIO-MODE"
>Table 3</A
>.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>reserved</CODE
>[2]</TD
><TD
>Reserved for future extensions. Drivers and
applications must set the array to zero.</TD
></TR
></TBODY
></TABLE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="AUDIO-CAPABILITY"
></A
><P
><B
>Table 2. Audio Capability Flags</B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="38%"
TITLE="C1"><COL
WIDTH="12%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_AUDCAP_STEREO</CODE
></TD
><TD
>0x00001</TD
><TD
>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
<SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>received</I
></SPAN
>, unless the audio input belongs to a
tuner.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_AUDCAP_AVL</CODE
></TD
><TD
>0x00002</TD
><TD
>Automatic Volume Level mode is supported.</TD
></TR
></TBODY
></TABLE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="AUDIO-MODE"
></A
><P
><B
>Table 3. Audio Modes</B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="38%"
TITLE="C1"><COL
WIDTH="12%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_AUDMODE_AVL</CODE
></TD
><TD
>0x00001</TD
><TD
>AVL mode is on.</TD
></TR
></TBODY
></TABLE
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN6067"
></A
><H2
>Return Value</H2
><P
>On success <SPAN
CLASS="RETURNVALUE"
>0</SPAN
> is returned, on
error <SPAN
CLASS="RETURNVALUE"
>-1</SPAN
> and <VAR
CLASS="VARNAME"
>errno</VAR
> is
set appropriately:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
></DT
><DD
><P
>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.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>EBUSY</SPAN
></DT
><DD
><P
>I/O is in progress, the input cannot be
switched.</P
></DD
></DL
></DIV
></DIV
><H1
><A
NAME="VIDIOC-G-AUDIOOUT"
></A
>ioctl VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN6087"
></A
><H2
>Name</H2
>ioctl VIDIOC_G_AUDOUT, ioctl VIDIOC_S_AUDOUT -- Query or select the current audio output</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN6091"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN6092"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, struct v4l2_audioout *argp);</CODE
></P
><P
></P
></DIV
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN6102"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, const struct v4l2_audioout *argp);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN6112"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><VAR
CLASS="PARAMETER"
>fd</VAR
></DT
><DD
><P
>File descriptor returned by <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
>.</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>request</VAR
></DT
><DD
><P
>VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>argp</VAR
></DT
><DD
><P
></P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN6132"
></A
><H2
>Description</H2
><P
>To query the current audio output applications zero out the
<CODE
CLASS="STRUCTFIELD"
>reserved</CODE
> array of a struct <A
HREF="#V4L2-AUDIOOUT"
>v4l2_audioout</A
> and
call the <CODE
CLASS="CONSTANT"
>VIDIOC_G_AUDOUT</CODE
> ioctl with a pointer
to this structure. Drivers fill the rest of the structure or return an
<SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code when the device has no audio inputs, or none which combine
with the current video output.</P
><P
>Audio outputs have no writable properties. Nevertheless, to
select the current audio output applications can initialize the
<CODE
CLASS="STRUCTFIELD"
>index</CODE
> field and
<CODE
CLASS="STRUCTFIELD"
>reserved</CODE
> array (which in the future may
contain writable properties) of a
<CODE
CLASS="STRUCTNAME"
>v4l2_audioout</CODE
> structure and call the
<CODE
CLASS="CONSTANT"
>VIDIOC_S_AUDOUT</CODE
> ioctl. Drivers switch to the
requested output or return the <SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code when the index is out of
bounds. This is a write-only ioctl, it does not return the current
audio output attributes as <CODE
CLASS="CONSTANT"
>VIDIOC_G_AUDOUT</CODE
>
does.</P
><P
>Note connectors on a TV card to loop back the received audio
signal to a sound card are not audio outputs in this sense.</P
><DIV
CLASS="TABLE"
><A
NAME="V4L2-AUDIOOUT"
></A
><P
><B
>Table 1. struct <CODE
CLASS="STRUCTNAME"
>v4l2_audioout</CODE
></B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="25%"
TITLE="C1"><COL
WIDTH="25%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>index</CODE
></TD
><TD
>Identifies the audio output, set by the
driver or application.</TD
></TR
><TR
><TD
>__u8</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>name</CODE
>[32]</TD
><TD
>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.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>capability</CODE
></TD
><TD
>Audio capability flags, none defined yet. Drivers
must set this field to zero.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>mode</CODE
></TD
><TD
>Audio mode, none defined yet. Drivers and
applications (on <CODE
CLASS="CONSTANT"
>VIDIOC_S_AUDOUT</CODE
>) must set this
field to zero.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>reserved</CODE
>[2]</TD
><TD
>Reserved for future extensions. Drivers and
applications must set the array to zero.</TD
></TR
></TBODY
></TABLE
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN6182"
></A
><H2
>Return Value</H2
><P
>On success <SPAN
CLASS="RETURNVALUE"
>0</SPAN
> is returned, on
error <SPAN
CLASS="RETURNVALUE"
>-1</SPAN
> and <VAR
CLASS="VARNAME"
>errno</VAR
> is
set appropriately:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
></DT
><DD
><P
>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.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>EBUSY</SPAN
></DT
><DD
><P
>I/O is in progress, the output cannot be
switched.</P
></DD
></DL
></DIV
></DIV
><H1
><A
NAME="VIDIOC-G-COMP"
></A
>ioctl VIDIOC_G_COMP, VIDIOC_S_COMP</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN6202"
></A
><H2
>Name</H2
>ioctl VIDIOC_G_COMP, ioctl VIDIOC_S_COMP -- Get or set compression parameters</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN6206"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN6207"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, v4l2_compression *argp);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN6217"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><VAR
CLASS="PARAMETER"
>fd</VAR
></DT
><DD
><P
>File descriptor returned by <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
>.</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>request</VAR
></DT
><DD
><P
>VIDIOC_G_COMP, VIDIOC_S_COMP</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>argp</VAR
></DT
><DD
><P
></P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN6237"
></A
><H2
>Description</H2
><P
>[to do]</P
><DIV
CLASS="TABLE"
><A
NAME="V4L2-COMPRESSION"
></A
><P
><B
>Table 1. struct <CODE
CLASS="STRUCTNAME"
>v4l2_compression</CODE
></B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="25%"
TITLE="C1"><COL
WIDTH="25%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>quality</CODE
></TD
><TD
> </TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>keyframerate</CODE
></TD
><TD
> </TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>pframerate</CODE
></TD
><TD
> </TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>reserved</CODE
>[5]</TD
><TD
> </TD
></TR
></TBODY
></TABLE
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN6269"
></A
><H2
>Return Value</H2
><P
>On success <SPAN
CLASS="RETURNVALUE"
>0</SPAN
> is returned, on
error <SPAN
CLASS="RETURNVALUE"
>-1</SPAN
> and <VAR
CLASS="VARNAME"
>errno</VAR
> is
set appropriately:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
></DT
><DD
><P
>This ioctl is not supported</P
></DD
></DL
></DIV
></DIV
><H1
><A
NAME="VIDIOC-G-CROP"
></A
>ioctl VIDIOC_G_CROP, VIDIOC_S_CROP</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN6284"
></A
><H2
>Name</H2
>ioctl VIDIOC_G_CROP, ioctl VIDIOC_S_CROP -- Get or set the current cropping rectangle</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN6288"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN6289"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, struct v4l2_crop *argp);</CODE
></P
><P
></P
></DIV
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN6299"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, const struct v4l2_crop *argp);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN6309"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><VAR
CLASS="PARAMETER"
>fd</VAR
></DT
><DD
><P
>File descriptor returned by <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
>.</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>request</VAR
></DT
><DD
><P
>VIDIOC_G_CROP, VIDIOC_S_CROP</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>argp</VAR
></DT
><DD
><P
></P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN6329"
></A
><H2
>Description</H2
><P
>To query the cropping rectangle size and position
applications set the <CODE
CLASS="STRUCTFIELD"
>type</CODE
> field of a
<CODE
CLASS="STRUCTNAME"
>v4l2_crop</CODE
> structure to the respective buffer
(stream) type and call the <CODE
CLASS="CONSTANT"
>VIDIOC_G_CROP</CODE
> ioctl
with a pointer to this structure. The driver fills the rest of the
structure or returns the <SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code if cropping is not supported.</P
><P
>To change the cropping rectangle applications initialize the
<CODE
CLASS="STRUCTFIELD"
>type</CODE
> and struct <A
HREF="#V4L2-RECT"
>v4l2_rect</A
> substructure named
<CODE
CLASS="STRUCTFIELD"
>c</CODE
> of a v4l2_crop structure and call the
<CODE
CLASS="CONSTANT"
>VIDIOC_S_CROP</CODE
> ioctl with a pointer to this
structure.</P
><P
>The driver first adjusts the requested dimensions against
hardware limits, i. e. 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.</P
><P
>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.</P
><P
>Finally the driver programs the hardware with the actual
cropping and image parameters. <CODE
CLASS="CONSTANT"
>VIDIOC_S_CROP</CODE
> is a
write-only ioctl, it does not return the actual parameters. To query
them applications must call <CODE
CLASS="CONSTANT"
>VIDIOC_G_CROP</CODE
> and
<A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_FMT</CODE
></A
>. When the parameters are unsuitable the application may
modify the cropping or image parameters and repeat the cycle until
satisfactory parameters have been negotiated.</P
><P
>When cropping is not supported then no parameters are
changed and <CODE
CLASS="CONSTANT"
>VIDIOC_S_CROP</CODE
> returns the
<SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code.</P
><DIV
CLASS="TABLE"
><A
NAME="V4L2-CROP"
></A
><P
><B
>Table 1. struct <CODE
CLASS="STRUCTNAME"
>v4l2_crop</CODE
></B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="25%"
TITLE="C1"><COL
WIDTH="25%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
>enum <A
HREF="#V4L2-BUF-TYPE"
>v4l2_buf_type</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>type</CODE
></TD
><TD
>Type of the data stream, set by the application.
Only these types are valid here: <CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_VIDEO_CAPTURE</CODE
>,
<CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_VIDEO_OUTPUT</CODE
>,
<CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_VIDEO_OVERLAY</CODE
>, and custom (driver
defined) types with code <CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_PRIVATE</CODE
>
and higher.</TD
></TR
><TR
><TD
>struct <A
HREF="#V4L2-RECT"
>v4l2_rect</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>c</CODE
></TD
><TD
>Cropping rectangle. The same co-ordinate system as
for struct <A
HREF="#V4L2-CROPCAP"
>v4l2_cropcap</A
> <CODE
CLASS="STRUCTFIELD"
>bounds</CODE
> is used.</TD
></TR
></TBODY
></TABLE
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN6378"
></A
><H2
>Return Value</H2
><P
>On success <SPAN
CLASS="RETURNVALUE"
>0</SPAN
> is returned, on
error <SPAN
CLASS="RETURNVALUE"
>-1</SPAN
> and <VAR
CLASS="VARNAME"
>errno</VAR
> is
set appropriately:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
></DT
><DD
><P
>Cropping is not supported.</P
></DD
></DL
></DIV
></DIV
><H1
><A
NAME="VIDIOC-G-CTRL"
></A
>ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN6393"
></A
><H2
>Name</H2
>ioctl VIDIOC_G_CTRL, ioctl VIDIOC_S_CTRL -- Get or set the value of a control</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN6397"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN6398"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, struct v4l2_control
*argp);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN6408"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><VAR
CLASS="PARAMETER"
>fd</VAR
></DT
><DD
><P
>File descriptor returned by <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
>.</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>request</VAR
></DT
><DD
><P
>VIDIOC_G_CTRL, VIDIOC_S_CTRL</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>argp</VAR
></DT
><DD
><P
></P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN6428"
></A
><H2
>Description</H2
><P
>To get the current value of a control applications
initialize the <CODE
CLASS="STRUCTFIELD"
>id</CODE
> field of a struct
<CODE
CLASS="STRUCTNAME"
>v4l2_control</CODE
> and call the
<CODE
CLASS="CONSTANT"
>VIDIOC_G_CTRL</CODE
> ioctl with a pointer to this
structure. To change the value of a control applications initialize
the <CODE
CLASS="STRUCTFIELD"
>id</CODE
> and <CODE
CLASS="STRUCTFIELD"
>value</CODE
>
fields of a struct <CODE
CLASS="STRUCTNAME"
>v4l2_control</CODE
> and call the
<CODE
CLASS="CONSTANT"
>VIDIOC_S_CTRL</CODE
> ioctl.</P
><P
>When the <CODE
CLASS="STRUCTFIELD"
>id</CODE
> is invalid drivers
return an <SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code. When the <CODE
CLASS="STRUCTFIELD"
>value</CODE
> is out
of bounds drivers can choose to take the closest valid value or return
an <SPAN
CLASS="ERRORCODE"
>ERANGE</SPAN
> error code, whatever seems more appropriate. However,
<CODE
CLASS="CONSTANT"
>VIDIOC_S_CTRL</CODE
> is a write-only ioctl, it does not
return the actual new value.</P
><DIV
CLASS="TABLE"
><A
NAME="V4L2-CONTROL"
></A
><P
><B
>Table 1. struct <CODE
CLASS="STRUCTNAME"
>v4l2_control</CODE
></B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="25%"
TITLE="C1"><COL
WIDTH="25%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>id</CODE
></TD
><TD
>Identifies the control, set by the
application.</TD
></TR
><TR
><TD
>__s32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>value</CODE
></TD
><TD
>New value or current value.</TD
></TR
></TBODY
></TABLE
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN6463"
></A
><H2
>Return Value</H2
><P
>On success <SPAN
CLASS="RETURNVALUE"
>0</SPAN
> is returned, on
error <SPAN
CLASS="RETURNVALUE"
>-1</SPAN
> and <VAR
CLASS="VARNAME"
>errno</VAR
> is
set appropriately:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
></DT
><DD
><P
>The struct <A
HREF="#V4L2-CONTROL"
>v4l2_control</A
> <CODE
CLASS="STRUCTFIELD"
>id</CODE
> is
invalid.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>ERANGE</SPAN
></DT
><DD
><P
>The struct <A
HREF="#V4L2-CONTROL"
>v4l2_control</A
> <CODE
CLASS="STRUCTFIELD"
>value</CODE
>
is out of bounds.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>EBUSY</SPAN
></DT
><DD
><P
>The control is temporarily not changeable, possibly
because another applications took over control of the device function
this control belongs to.</P
></DD
></DL
></DIV
></DIV
><H1
><A
NAME="VIDIOC-G-FBUF"
></A
>ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN6492"
></A
><H2
>Name</H2
>ioctl VIDIOC_G_FBUF, ioctl VIDIOC_S_FBUF -- Get or set frame buffer overlay parameters.</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN6496"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN6497"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, struct v4l2_framebuffer *argp);</CODE
></P
><P
></P
></DIV
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN6507"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, const struct v4l2_framebuffer *argp);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN6517"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><VAR
CLASS="PARAMETER"
>fd</VAR
></DT
><DD
><P
>File descriptor returned by <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
>.</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>request</VAR
></DT
><DD
><P
>VIDIOC_G_FBUF, VIDIOC_S_FBUF</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>argp</VAR
></DT
><DD
><P
></P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN6537"
></A
><H2
>Description</H2
><P
>The <CODE
CLASS="CONSTANT"
>VIDIOC_G_FBUF</CODE
> and
<CODE
CLASS="CONSTANT"
>VIDIOC_S_FBUF</CODE
> ioctl are used to get and set the
frame buffer parameters for <A
HREF="#OVERLAY"
>video overlay</A
>.</P
><P
>To get the current parameters applications call the
<CODE
CLASS="CONSTANT"
>VIDIOC_G_FBUF</CODE
> ioctl with a pointer to a
<CODE
CLASS="STRUCTNAME"
>v4l2_framebuffer</CODE
> structure, the driver fills
all fields of the structure or returns the <SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code when overlay is
not supported. To set the parameters applications initialize the
<CODE
CLASS="STRUCTFIELD"
>flags</CODE
> field,
<CODE
CLASS="STRUCTFIELD"
>base</CODE
> unless the overlay is of
<CODE
CLASS="CONSTANT"
>V4L2_FBUF_CAP_EXTERNOVERLAY</CODE
> type, and the
struct <A
HREF="#V4L2-PIX-FORMAT"
>v4l2_pix_format</A
> <CODE
CLASS="STRUCTFIELD"
>fmt</CODE
> substructure. The driver
accordingly prepares for overlay or returns an error code.</P
><P
>When the driver does <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>not</I
></SPAN
> support
<CODE
CLASS="CONSTANT"
>V4L2_FBUF_CAP_EXTERNOVERLAY</CODE
>, i. e. it will
write into video memory, the <CODE
CLASS="CONSTANT"
>VIDIOC_S_FBUF</CODE
> ioctl
is a privileged function and only the superuser can change the frame
buffer parameters.</P
><DIV
CLASS="TABLE"
><A
NAME="V4L2-FRAMEBUFFER"
></A
><P
><B
>Table 1. struct <CODE
CLASS="STRUCTNAME"
>v4l2_framebuffer</CODE
></B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="50%"
TITLE="C1"><COL><COL><COL
WIDTH="50%"
TITLE="C4"><TBODY
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>capability</CODE
></TD
><TD
> </TD
><TD
>Overlay capability flags set by the driver, see
<A
HREF="#FRAMEBUFFER-CAP"
>Table 2</A
>.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>flags</CODE
></TD
><TD
> </TD
><TD
>Overlay control flags set by application and
driver, see <A
HREF="#FRAMEBUFFER-FLAGS"
>Table 3</A
></TD
></TR
><TR
><TD
>void *</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>base</CODE
></TD
><TD
> </TD
><TD
><P
>Physical base address of the frame buffer,
the address of the pixel at coordinates (0; 0) in the frame buffer.
This field is not used when <CODE
CLASS="CONSTANT"
>VIDIOC_G_FBUF</CODE
> sets
the <CODE
CLASS="CONSTANT"
>V4L2_FBUF_CAP_EXTERNOVERLAY</CODE
> flag in the
<CODE
CLASS="STRUCTFIELD"
>capability</CODE
> field.<SUP
>a</SUP
></P
></TD
></TR
><TR
><TD
>struct <A
HREF="#V4L2-PIX-FORMAT"
>v4l2_pix_format</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>fmt</CODE
></TD
><TD
> </TD
><TD
>Physical layout of the frame buffer. The
<CODE
CLASS="STRUCTNAME"
>v4l2_pix_format</CODE
> structure is defined in <A
HREF="#PIXFMT"
>Chapter 2</A
>, for clarification the fields and expected values
are listed below.</TD
></TR
><TR
><TD
> </TD
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>width</CODE
></TD
><TD
>Width of the frame buffer in pixels.</TD
></TR
><TR
><TD
> </TD
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>height</CODE
></TD
><TD
>Height of the frame buffer in pixels. When the
driver <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>clears</I
></SPAN
>
<CODE
CLASS="CONSTANT"
>V4L2_FBUF_CAP_EXTERNOVERLAY</CODE
>, the visible portion
of the frame buffer can be smaller than width and height.</TD
></TR
><TR
><TD
> </TD
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>pixelformat</CODE
></TD
><TD
>The pixel format of the graphics surface, set by
the application. Usually this is an RGB format (for example RGB 5:6:5)
but YUV formats are also permitted. The behavior of the driver when
requesting a compressed format is undefined. See <A
HREF="#PIXFMT"
>Chapter 2</A
> for information on pixel formats. This field is not
used when the driver sets
<CODE
CLASS="CONSTANT"
>V4L2_FBUF_CAP_EXTERNOVERLAY</CODE
>.</TD
></TR
><TR
><TD
> </TD
><TD
>enum <A
HREF="#V4L2-FIELD"
>v4l2_field</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>field</CODE
></TD
><TD
>Ignored. The field order is selected with the
<A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
></A
> ioctl using struct <A
HREF="#V4L2-WINDOW"
>v4l2_window</A
>.</TD
></TR
><TR
><TD
> </TD
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>bytesperline</CODE
></TD
><TD
>Distance in bytes between the leftmost pixels in two
adjacent lines.</TD
></TR
><TR
><TD
COLSPAN="4"
><P
>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 <CODE
CLASS="STRUCTFIELD"
>width</CODE
> 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.</P
><P
>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.</P
><P
>When the image format is planar the
<CODE
CLASS="STRUCTFIELD"
>bytesperline</CODE
> value applies to the largest
plane and is divided by the same factor as the
<CODE
CLASS="STRUCTFIELD"
>width</CODE
> 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 <CODE
CLASS="STRUCTFIELD"
>bytesperline</CODE
> value
rounded up to a multiple of the scale factor.</P
><P
>This
field is not used when the driver sets
<CODE
CLASS="CONSTANT"
>V4L2_FBUF_CAP_EXTERNOVERLAY</CODE
>.</P
></TD
></TR
><TR
><TD
> </TD
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>sizeimage</CODE
></TD
><TD
><P
>Applications must initialize this field.
Together with <CODE
CLASS="STRUCTFIELD"
>base</CODE
> it defines the frame
buffer memory accessible by the driver.</P
><P
>The field is not
used when the driver sets
<CODE
CLASS="CONSTANT"
>V4L2_FBUF_CAP_EXTERNOVERLAY</CODE
>.</P
></TD
></TR
><TR
><TD
> </TD
><TD
>enum <A
HREF="#V4L2-COLORSPACE"
>v4l2_colorspace</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>colorspace</CODE
></TD
><TD
>This information supplements the
<CODE
CLASS="STRUCTFIELD"
>pixelformat</CODE
> and must be set by the driver,
see <A
HREF="#COLORSPACES"
>Section 2.2</A
>.</TD
></TR
><TR
><TD
> </TD
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>priv</CODE
></TD
><TD
>Reserved for additional information about custom
(driver defined) formats. When not used drivers and applications must
set this field to zero.</TD
></TR
></TBODY
><TR
><TD
COLSPAN="4"
>Notes:<BR><A
NAME="FTN.AEN6588"
>a. </A
>A
physical base address may not suit all platforms. GK notes in theory
we should pass something like PCI device + memory region + offset
instead. If you encounter problems please discuss on the Video4Linux
mailing list: <A
HREF="https://listman.redhat.com/mailman/listinfo/video4linux-list"
TARGET="_top"
>https://listman.redhat.com/mailman/listinfo/video4linux-list</A
>.<BR></TD
></TR
></TABLE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="FRAMEBUFFER-CAP"
></A
><P
><B
>Table 2. Frame Buffer Capability Flags</B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="38%"
TITLE="C1"><COL
WIDTH="12%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_FBUF_CAP_EXTERNOVERLAY</CODE
></TD
><TD
>0x0001</TD
><TD
>The video is overlaid externally onto the
video signal of the graphics card.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_FBUF_CAP_CHROMAKEY</CODE
></TD
><TD
>0x0002</TD
><TD
>The device supports clipping by chroma-keying the
image into the display.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_FBUF_CAP_LIST_CLIPPING</CODE
></TD
><TD
>0x0004</TD
><TD
>The device supports clipping using a list of clip
rectangles.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_FBUF_CAP_BITMAP_CLIPPING</CODE
></TD
><TD
>0x0008</TD
><TD
>The device supports clipping using a bit mask.</TD
></TR
></TBODY
></TABLE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="FRAMEBUFFER-FLAGS"
></A
><P
><B
>Table 3. Frame Buffer Flags</B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="38%"
TITLE="C1"><COL
WIDTH="12%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_FBUF_FLAG_PRIMARY</CODE
></TD
><TD
>0x0001</TD
><TD
>The frame buffer is the primary graphics surface.
In other words, the overlay is destructive, the video hardware will
write the image into visible graphics memory as opposed to merely
displaying the image in place of the original display contents.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_FBUF_FLAG_OVERLAY</CODE
></TD
><TD
>0x0002</TD
><TD
>The frame buffer is an overlay surface the same
size as the capture. [?]</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_FBUF_FLAG_CHROMAKEY</CODE
></TD
><TD
>0x0004</TD
><TD
>Use chromakey (when
<CODE
CLASS="CONSTANT"
>V4L2_FBUF_CAP_CHROMAKEY</CODE
> indicates this
capability). The other clipping methods are negotiated with the
<A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
></A
> ioctl, see also <A
HREF="#OVERLAY"
>Section 4.2</A
>.</TD
></TR
></TBODY
></TABLE
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN6729"
></A
><H2
>Return Value</H2
><P
>On success <SPAN
CLASS="RETURNVALUE"
>0</SPAN
> is returned, on
error <SPAN
CLASS="RETURNVALUE"
>-1</SPAN
> and <VAR
CLASS="VARNAME"
>errno</VAR
> is
set appropriately:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="ERRORCODE"
>EACCES</SPAN
></DT
><DD
><P
><CODE
CLASS="CONSTANT"
>VIDIOC_S_FBUF</CODE
> can only be called
by a privileged user.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>EBUSY</SPAN
></DT
><DD
><P
>The frame buffer parameters cannot be changed at this
time because overlay is already enabled, or capturing is enabled
and the hardware cannot capture and overlay simultaneously.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
></DT
><DD
><P
>The ioctl is not supported or the
<CODE
CLASS="CONSTANT"
>VIDIOC_S_FBUF</CODE
> parameters are unsuitable.</P
></DD
></DL
></DIV
></DIV
><H1
><A
NAME="VIDIOC-G-FMT"
></A
>ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN6756"
></A
><H2
>Name</H2
>ioctl VIDIOC_G_FMT, ioctl VIDIOC_S_FMT, ioctl VIDIOC_TRY_FMT -- Get or set the data format, try a format.</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN6761"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN6762"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, struct v4l2_format
*argp);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN6772"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><VAR
CLASS="PARAMETER"
>fd</VAR
></DT
><DD
><P
>File descriptor returned by <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
>.</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>request</VAR
></DT
><DD
><P
>VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>argp</VAR
></DT
><DD
><P
></P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN6792"
></A
><H2
>Description</H2
><P
>These ioctls are used to negotiate the format of data
(typically image format) exchanged between driver and
application.</P
><P
>To query the current parameters applications set the
<CODE
CLASS="STRUCTFIELD"
>type</CODE
> field of a struct
<CODE
CLASS="STRUCTNAME"
>v4l2_format</CODE
> to the respective buffer (stream)
type. For example video capture devices use
<CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_VIDEO_CAPTURE</CODE
>. When the application
calls the <CODE
CLASS="CONSTANT"
>VIDIOC_G_FMT</CODE
> ioctl with a pointer to
this structure the driver fills the respective member of the
<CODE
CLASS="STRUCTFIELD"
>fmt</CODE
> union. In case of video capture devices
that is the struct <A
HREF="#V4L2-PIX-FORMAT"
>v4l2_pix_format</A
> <CODE
CLASS="STRUCTFIELD"
>pix</CODE
> member.
When the requested buffer type is not supported drivers return an
<SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code.</P
><P
>To change the current format parameters applications
initialize the <CODE
CLASS="STRUCTFIELD"
>type</CODE
> field and all
fields of the respective <CODE
CLASS="STRUCTFIELD"
>fmt</CODE
>
union member. For details see the documentation of the various devices
types in <A
HREF="#DEVICES"
>Chapter 4</A
>. Good practice is to query the
current parameters first, and to
modify only those parameters not suitable for the application. When
the application calls the <CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
> ioctl
with a pointer to a <CODE
CLASS="STRUCTNAME"
>v4l2_format</CODE
> structure
the driver checks
and adjusts the parameters against hardware abilities. Drivers
should not return an error code unless the input is ambiguous, this is
a mechanism to fathom device capabilities and to approach parameters
acceptable for both the application and driver. On success the driver
may program the hardware, allocate resources and generally prepare for
data exchange.
Finally the <CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
> ioctl returns the
current format parameters as <CODE
CLASS="CONSTANT"
>VIDIOC_G_FMT</CODE
> does.
Very simple, inflexible devices may even ignore all input and always
return the default parameters. However all V4L2 devices exchanging
data with the application must implement the
<CODE
CLASS="CONSTANT"
>VIDIOC_G_FMT</CODE
> and
<CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
> ioctl. When the requested buffer
type is not supported drivers return an <SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code on a
<CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
> attempt. When I/O is already in
progress or the resource is not available for other reasons drivers
return the <SPAN
CLASS="ERRORCODE"
>EBUSY</SPAN
> error code.</P
><P
>The <CODE
CLASS="CONSTANT"
>VIDIOC_TRY_FMT</CODE
> ioctl is equivalent
to <CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
> with one exception: it does not
change driver state. It can also be called at any time, never
returning <SPAN
CLASS="ERRORCODE"
>EBUSY</SPAN
>. This function is provided to
negotiate parameters, to learn about hardware limitations, without
disabling I/O or possibly time consuming hardware preparations.
Although strongly recommended drivers are not required to implement
this ioctl.</P
><DIV
CLASS="TABLE"
><A
NAME="V4L2-FORMAT"
></A
><P
><B
>Table 1. struct <CODE
CLASS="STRUCTNAME"
>v4l2_format</CODE
></B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="25%"
TITLE="C1"><COL
WIDTH="25%"
TITLE="C2"><COL
WIDTH="25%"
TITLE="C3"><COL
WIDTH="25%"
TITLE="C4"><TBODY
><TR
><TD
>enum <A
HREF="#V4L2-BUF-TYPE"
>v4l2_buf_type</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>type</CODE
></TD
><TD
> </TD
><TD
>Type of the data stream, see <A
HREF="#V4L2-BUF-TYPE"
>Table 3-2</A
>.</TD
></TR
><TR
><TD
>union</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>fmt</CODE
></TD
><TD
> </TD
><TD
> </TD
></TR
><TR
><TD
> </TD
><TD
>struct <A
HREF="#V4L2-PIX-FORMAT"
>v4l2_pix_format</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>pix</CODE
></TD
><TD
>Definition of an image format, see <A
HREF="#PIXFMT"
>Chapter 2</A
>, used by video capture and output
devices.</TD
></TR
><TR
><TD
> </TD
><TD
>struct <A
HREF="#V4L2-WINDOW"
>v4l2_window</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>win</CODE
></TD
><TD
>Definition of an overlaid image, see <A
HREF="#OVERLAY"
>Section 4.2</A
>, used by video overlay devices.</TD
></TR
><TR
><TD
> </TD
><TD
>struct <A
HREF="#V4L2-VBI-FORMAT"
>v4l2_vbi_format</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>vbi</CODE
></TD
><TD
>Raw VBI capture or output parameters. This is
discussed in more detail in <A
HREF="#RAW-VBI"
>Section 4.6</A
>. Used by raw VBI
capture and output devices.</TD
></TR
><TR
><TD
> </TD
><TD
>__u8</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>raw_data</CODE
>[200]</TD
><TD
>Place holder for future extensions and custom
(driver defined) formats with <CODE
CLASS="STRUCTFIELD"
>type</CODE
>
<CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_PRIVATE</CODE
> and higher.</TD
></TR
></TBODY
></TABLE
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN6874"
></A
><H2
>Return Value</H2
><P
>On success <SPAN
CLASS="RETURNVALUE"
>0</SPAN
> is returned, on
error <SPAN
CLASS="RETURNVALUE"
>-1</SPAN
> and <VAR
CLASS="VARNAME"
>errno</VAR
> is
set appropriately:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="ERRORCODE"
>EBUSY</SPAN
></DT
><DD
><P
>The data format cannot be changed at this
time, for example because I/O is already in progress.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
></DT
><DD
><P
>The struct <A
HREF="#V4L2-FORMAT"
>v4l2_format</A
> <CODE
CLASS="STRUCTFIELD"
>type</CODE
>
field is invalid, the requested buffer type not supported, or
<CODE
CLASS="CONSTANT"
>VIDIOC_TRY_FMT</CODE
> was called and is not
supported with this buffer type.</P
></DD
></DL
></DIV
></DIV
><H1
><A
NAME="VIDIOC-G-FREQUENCY"
></A
>ioctl VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN6897"
></A
><H2
>Name</H2
>ioctl VIDIOC_G_FREQUENCY, ioctl VIDIOC_S_FREQUENCY -- Get or set tuner or modulator radio
frequency</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN6901"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN6902"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, struct v4l2_frequency
*argp);</CODE
></P
><P
></P
></DIV
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN6912"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, const struct v4l2_frequency
*argp);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN6922"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><VAR
CLASS="PARAMETER"
>fd</VAR
></DT
><DD
><P
>File descriptor returned by <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
>.</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>request</VAR
></DT
><DD
><P
>VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>argp</VAR
></DT
><DD
><P
></P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN6942"
></A
><H2
>Description</H2
><P
>To get the current tuner or modulator radio frequency
applications set the <CODE
CLASS="STRUCTFIELD"
>tuner</CODE
> field of a
struct <A
HREF="#V4L2-FREQUENCY"
>v4l2_frequency</A
> to the respective tuner or modulator number (only
input devices have tuners, only output devices have modulators), zero
out the <CODE
CLASS="STRUCTFIELD"
>reserved</CODE
> array and
call the <CODE
CLASS="CONSTANT"
>VIDIOC_G_FREQUENCY</CODE
> ioctl with a pointer
to this structure. The driver stores the current frequency in the
<CODE
CLASS="STRUCTFIELD"
>frequency</CODE
> field.</P
><P
>To change the current tuner or modulator radio frequency
applications initialize the <CODE
CLASS="STRUCTFIELD"
>tuner</CODE
> and
<CODE
CLASS="STRUCTFIELD"
>frequency</CODE
> fields, and the
<CODE
CLASS="STRUCTFIELD"
>reserved</CODE
> array of a struct <A
HREF="#V4L2-FREQUENCY"
>v4l2_frequency</A
> and
call the <CODE
CLASS="CONSTANT"
>VIDIOC_S_FREQUENCY</CODE
> ioctl with a pointer
to this structure. When the requested frequency is not possible the
driver assumes the closest possible value. However,
<CODE
CLASS="CONSTANT"
>VIDIOC_S_FREQUENCY</CODE
> is a write-only ioctl, it does
not return the actual new frequency.</P
><DIV
CLASS="TABLE"
><A
NAME="V4L2-FREQUENCY"
></A
><P
><B
>Table 1. struct <CODE
CLASS="STRUCTNAME"
>v4l2_frequency</CODE
></B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="25%"
TITLE="C1"><COL
WIDTH="25%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>tuner</CODE
></TD
><TD
>The tuner or modulator index number. This is the
same value as in the struct <A
HREF="#V4L2-INPUT"
>v4l2_input</A
> <CODE
CLASS="STRUCTFIELD"
>tuner</CODE
>
field and the struct <A
HREF="#V4L2-TUNER"
>v4l2_tuner</A
> <CODE
CLASS="STRUCTFIELD"
>index</CODE
> field, or
the struct <A
HREF="#V4L2-OUTPUT"
>v4l2_output</A
> <CODE
CLASS="STRUCTFIELD"
>modulator</CODE
> field and the
struct <A
HREF="#V4L2-MODULATOR"
>v4l2_modulator</A
> <CODE
CLASS="STRUCTFIELD"
>index</CODE
> field.</TD
></TR
><TR
><TD
>enum <A
HREF="#V4L2-TUNER-TYPE"
>v4l2_tuner_type</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>type</CODE
></TD
><TD
>The tuner type. This is the same value as in the
struct <A
HREF="#V4L2-TUNER"
>v4l2_tuner</A
> <CODE
CLASS="STRUCTFIELD"
>type</CODE
> field. The field is not
applicable to modulators, i. e. ignored by drivers.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>frequency</CODE
></TD
><TD
>Tuning frequency in units of 62.5 kHz, or if the
struct <A
HREF="#V4L2-TUNER"
>v4l2_tuner</A
> or struct <A
HREF="#V4L2-MODULATOR"
>v4l2_modulator</A
> <CODE
CLASS="STRUCTFIELD"
>capabilities</CODE
> flag
<CODE
CLASS="CONSTANT"
>V4L2_TUNER_CAP_LOW</CODE
> is set, in units of 62.5
Hz.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>reserved</CODE
>[8];</TD
><TD
>Reserved for future extensions. Drivers and
applications must set the array to zero.</TD
></TR
></TBODY
></TABLE
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN7001"
></A
><H2
>Return Value</H2
><P
>On success <SPAN
CLASS="RETURNVALUE"
>0</SPAN
> is returned, on
error <SPAN
CLASS="RETURNVALUE"
>-1</SPAN
> and <VAR
CLASS="VARNAME"
>errno</VAR
> is
set appropriately:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
></DT
><DD
><P
>The <CODE
CLASS="STRUCTFIELD"
>tuner</CODE
> field is out of
bounds.</P
></DD
></DL
></DIV
></DIV
><H1
><A
NAME="VIDIOC-G-INPUT"
></A
>ioctl VIDIOC_G_INPUT, VIDIOC_S_INPUT</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN7017"
></A
><H2
>Name</H2
>ioctl VIDIOC_G_INPUT, ioctl VIDIOC_S_INPUT -- Query or select the current video input</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN7021"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN7022"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, int *argp);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN7032"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><VAR
CLASS="PARAMETER"
>fd</VAR
></DT
><DD
><P
>File descriptor returned by <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
>.</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>request</VAR
></DT
><DD
><P
>VIDIOC_G_INPUT, VIDIOC_S_INPUT</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>argp</VAR
></DT
><DD
><P
></P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN7052"
></A
><H2
>Description</H2
><P
>To query the current video input applications call the
<CODE
CLASS="CONSTANT"
>VIDIOC_G_INPUT</CODE
> ioctl with a pointer to an integer
where the driver stores the number of the input, as in the
struct <A
HREF="#V4L2-INPUT"
>v4l2_input</A
> <CODE
CLASS="STRUCTFIELD"
>index</CODE
> field. This ioctl will
fail only when there are no video inputs, returning
<SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
>.</P
><P
>To select a video input applications store the number of the
desired input in an integer and call the
<CODE
CLASS="CONSTANT"
>VIDIOC_S_INPUT</CODE
> ioctl with a pointer to this
integer. Side effects are possible. For example inputs may support
different video standards, so the driver may implicitly switch the
current standard. It is good practice to select an input before
querying or negotiating any other parameters.</P
><P
>Information about video inputs is available using the
<A
HREF="#VIDIOC-ENUMINPUT"
><CODE
CLASS="CONSTANT"
>VIDIOC_ENUMINPUT</CODE
></A
> ioctl.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN7064"
></A
><H2
>Return Value</H2
><P
>On success <SPAN
CLASS="RETURNVALUE"
>0</SPAN
> is returned, on
error <SPAN
CLASS="RETURNVALUE"
>-1</SPAN
> and <VAR
CLASS="VARNAME"
>errno</VAR
> is
set appropriately:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
></DT
><DD
><P
>The number of the video input is out of bounds, or
there are no video inputs at all and this ioctl is not
supported.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>EBUSY</SPAN
></DT
><DD
><P
>I/O is in progress, the input cannot be
switched.</P
></DD
></DL
></DIV
></DIV
><H1
><A
NAME="VIDIOC-G-JPEGCOMP"
></A
>ioctl VIDIOC_G_JPEGCOMP, VIDIOC_S_JPEGCOMP</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN7084"
></A
><H2
>Name</H2
>ioctl VIDIOC_G_JPEGCOMP, ioctl VIDIOC_S_JPEGCOMP -- </DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN7088"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN7089"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, v4l2_jpegcompression *argp);</CODE
></P
><P
></P
></DIV
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN7099"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, const v4l2_jpegcompression *argp);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN7109"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><VAR
CLASS="PARAMETER"
>fd</VAR
></DT
><DD
><P
>File descriptor returned by <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
>.</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>request</VAR
></DT
><DD
><P
>VIDIOC_G_JPEGCOMP, VIDIOC_S_JPEGCOMP</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>argp</VAR
></DT
><DD
><P
></P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN7129"
></A
><H2
>Description</H2
><P
>[to do]</P
><P
>Ronald Bultje elaborates:</P
><P
>APP is some application-specific information. The
application can set it itself, and it'll be stored in the JPEG-encoded
fields (e.g. interlacing information for in an AVI or so). COM is the
same, but it's comments, like 'encoded by me' or so.</P
><P
>jpeg_markers describes whether the huffman tables,
quantization tables and the restart interval information (all
JPEG-specific stuff) should be stored in the JPEG-encoded fields.
These define how the JPEG field is encoded. If you omit them,
applications assume you've used standard encoding. You usually do want
to add them.</P
><P
CLASS="COMMENT"
>NB VIDIOC_S_JPEGCOMP is w/o.</P
><DIV
CLASS="TABLE"
><A
NAME="V4L2-JPEGCOMPRESSION"
></A
><P
><B
>Table 1. struct <CODE
CLASS="STRUCTNAME"
>v4l2_jpegcompression</CODE
></B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="25%"
TITLE="C1"><COL
WIDTH="25%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
>int</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>quality</CODE
></TD
><TD
> </TD
></TR
><TR
><TD
>int</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>APPn</CODE
></TD
><TD
> </TD
></TR
><TR
><TD
>int</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>APP_len</CODE
></TD
><TD
> </TD
></TR
><TR
><TD
>char</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>APP_data</CODE
>[60]</TD
><TD
> </TD
></TR
><TR
><TD
>int</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>COM_len</CODE
></TD
><TD
> </TD
></TR
><TR
><TD
>char</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>COM_data</CODE
>[60]</TD
><TD
> </TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>jpeg_markers</CODE
></TD
><TD
>See <A
HREF="#JPEG-MARKERS"
>Table 2</A
>.</TD
></TR
></TBODY
></TABLE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="JPEG-MARKERS"
></A
><P
><B
>Table 2. JPEG Markers Flags</B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="38%"
TITLE="C1"><COL
WIDTH="12%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_JPEG_MARKER_DHT</CODE
></TD
><TD
>(1<<3)</TD
><TD
>Define Huffman Tables</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_JPEG_MARKER_DQT</CODE
></TD
><TD
>(1<<4)</TD
><TD
>Define Quantization Tables</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_JPEG_MARKER_DRI</CODE
></TD
><TD
>(1<<5)</TD
><TD
>Define Restart Interval</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_JPEG_MARKER_COM</CODE
></TD
><TD
>(1<<6)</TD
><TD
>Comment segment</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_JPEG_MARKER_APP</CODE
></TD
><TD
>(1<<7)</TD
><TD
>App segment, driver will always use APP0</TD
></TR
></TBODY
></TABLE
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN7214"
></A
><H2
>Return Value</H2
><P
>On success <SPAN
CLASS="RETURNVALUE"
>0</SPAN
> is returned, on
error <SPAN
CLASS="RETURNVALUE"
>-1</SPAN
> and <VAR
CLASS="VARNAME"
>errno</VAR
> is
set appropriately:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
></DT
><DD
><P
>This ioctl is not supported.</P
></DD
></DL
></DIV
></DIV
><H1
><A
NAME="VIDIOC-G-MODULATOR"
></A
>ioctl VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN7229"
></A
><H2
>Name</H2
>ioctl VIDIOC_G_MODULATOR, ioctl VIDIOC_S_MODULATOR -- Get or set modulator attributes</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN7233"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN7234"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, struct v4l2_modulator
*argp);</CODE
></P
><P
></P
></DIV
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN7244"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, const struct v4l2_modulator
*argp);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN7254"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><VAR
CLASS="PARAMETER"
>fd</VAR
></DT
><DD
><P
>File descriptor returned by <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
>.</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>request</VAR
></DT
><DD
><P
>VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>argp</VAR
></DT
><DD
><P
></P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN7274"
></A
><H2
>Description</H2
><P
>To query the attributes of a modulator applications initialize
the <CODE
CLASS="STRUCTFIELD"
>index</CODE
> field and zero out the
<CODE
CLASS="STRUCTFIELD"
>reserved</CODE
> array of a struct <A
HREF="#V4L2-MODULATOR"
>v4l2_modulator</A
> and
call the <CODE
CLASS="CONSTANT"
>VIDIOC_G_MODULATOR</CODE
> ioctl with a pointer
to this structure. Drivers fill the rest of the structure or return an
<SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code when the index is out of bounds. To enumerate all modulators
applications shall begin at index zero, incrementing by one until the
driver returns <SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
>.</P
><P
>Modulators have two writable properties, an audio
modulation set and the radio frequency. To change the modulated audio
subprograms, applications initialize the <CODE
CLASS="STRUCTFIELD"
>index</CODE
> and <CODE
CLASS="STRUCTFIELD"
>txsubchans</CODE
> fields and the
<CODE
CLASS="STRUCTFIELD"
>reserved</CODE
> array and call the
<CODE
CLASS="CONSTANT"
>VIDIOC_S_MODULATOR</CODE
> ioctl. Drivers may choose a
different audio modulation if the request cannot be satisfied. However
this is a write-only ioctl, it does not return the actual audio
modulation selected.</P
><P
>To change the radio frequency the <A
HREF="#VIDIOC-G-FREQUENCY"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_FREQUENCY</CODE
></A
> ioctl
is available.</P
><DIV
CLASS="TABLE"
><A
NAME="V4L2-MODULATOR"
></A
><P
><B
>Table 1. struct <CODE
CLASS="STRUCTNAME"
>v4l2_modulator</CODE
></B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="25%"
TITLE="C1"><COL
WIDTH="25%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>index</CODE
></TD
><TD
>Identifies the modulator, set by the
application.</TD
></TR
><TR
><TD
>__u8</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>name</CODE
>[32]</TD
><TD
>Name of the modulator, a NUL-terminated ASCII
string. This information is intended for the user.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>capability</CODE
></TD
><TD
>Modulator capability flags. No flags are defined
for this field, the tuner flags in struct <A
HREF="#V4L2-TUNER"
>v4l2_tuner</A
>
are used accordingly. The audio flags indicate the ability
to encode audio subprograms. They will <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>not</I
></SPAN
>
change for example with the current video standard.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>rangelow</CODE
></TD
><TD
>The lowest tunable frequency in units of 62.5
KHz, or if the <CODE
CLASS="STRUCTFIELD"
>capability</CODE
> flag
<CODE
CLASS="CONSTANT"
>V4L2_TUNER_CAP_LOW</CODE
> is set, in units of 62.5
Hz.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>rangehigh</CODE
></TD
><TD
>The highest tunable frequency in units of 62.5
KHz, or if the <CODE
CLASS="STRUCTFIELD"
>capability</CODE
> flag
<CODE
CLASS="CONSTANT"
>V4L2_TUNER_CAP_LOW</CODE
> is set, in units of 62.5
Hz.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>txsubchans</CODE
></TD
><TD
>With this field applications can determine how
audio sub-carriers shall be modulated. It contains a set of flags as
defined in <A
HREF="#MODULATOR-TXSUBCHANS"
>Table 2</A
>. Note the tuner
<CODE
CLASS="STRUCTFIELD"
>rxsubchans</CODE
> flags are reused, but the
semantics are different. Video output devices are assumed to have an
analog or PCM audio input with 1-3 channels. The
<CODE
CLASS="STRUCTFIELD"
>txsubchans</CODE
> flags select one or more
channels for modulation, together with some audio subprogram
indicator, for example a stereo pilot tone.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>reserved</CODE
>[4]</TD
><TD
>Reserved for future extensions. Drivers and
applications must set the array to zero.</TD
></TR
></TBODY
></TABLE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="MODULATOR-TXSUBCHANS"
></A
><P
><B
>Table 2. Modulator Audio Transmission Flags</B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="38%"
TITLE="C1"><COL
WIDTH="12%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_TUNER_SUB_MONO</CODE
></TD
><TD
>0x0001</TD
><TD
>Modulate channel 1 as mono audio, when the input
has more channels, a down-mix of channel 1 and 2. This flag does not
combine with <CODE
CLASS="CONSTANT"
>V4L2_TUNER_SUB_STEREO</CODE
> or
<CODE
CLASS="CONSTANT"
>V4L2_TUNER_SUB_LANG1</CODE
>.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_TUNER_SUB_STEREO</CODE
></TD
><TD
>0x0002</TD
><TD
>Modulate channel 1 and 2 as left and right
channel of a stereo audio signal. When the input has only one channel
or two channels and <CODE
CLASS="CONSTANT"
>V4L2_TUNER_SUB_SAP</CODE
> is also
set, channel 1 is encoded as left and right channel. This flag does
not combine with <CODE
CLASS="CONSTANT"
>V4L2_TUNER_SUB_MONO </CODE
> or
<CODE
CLASS="CONSTANT"
>V4L2_TUNER_SUB_LANG1</CODE
>. When the driver does not
support stereo audio it shall fall back to mono.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_TUNER_SUB_LANG1</CODE
></TD
><TD
>0x0008</TD
><TD
>Modulate channel 1 and 2 as primary and secondary
language of a bilingual audio signal. When the input has only one
channel it is used for both languages. It is not possible to encode
the primary or secondary language only. This flag does not combine
with <CODE
CLASS="CONSTANT"
>V4L2_TUNER_SUB_MONO </CODE
> or
<CODE
CLASS="CONSTANT"
>V4L2_TUNER_SUB_STEREO</CODE
>. If the hardware does not
support the respective audio matrix, or the current video standard
does not permit bilingual audio the
<CODE
CLASS="CONSTANT"
>VIDIOC_S_MODULATOR</CODE
> ioctl shall return an <SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code
and the driver shall fall back to mono or stereo mode.
<A
HREF="#FTN.TUNER-AUDIO-CAP"
><SPAN
CLASS="footnote"
>[a]</SPAN
></A
></TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_TUNER_SUB_LANG2</CODE
></TD
><TD
>0x0004</TD
><TD
>Same effect as
<CODE
CLASS="CONSTANT"
>V4L2_TUNER_SUB_LANG1</CODE
>.
<A
HREF="#FTN.TUNER-AUDIO-CAP"
><SPAN
CLASS="footnote"
>[a]</SPAN
></A
></TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_TUNER_SUB_SAP</CODE
></TD
><TD
>0x0004</TD
><TD
>When combined with <CODE
CLASS="CONSTANT"
>V4L2_TUNER_SUB_MONO</CODE
> the first channel is encoded as mono audio, the last
channel as Second Audio Program. When the input has only one channel
it is used for both audio tracks. When the input has three channels
the mono track is a down-mix of channel 1 and 2. When combined with
<CODE
CLASS="CONSTANT"
>V4L2_TUNER_SUB_STEREO </CODE
> channel 1 and 2 are
encoded as left and right stereo audio, channel 3 as Second Audio
Program. When the input has only two channels, the first is encoded as
left and right channel and the second as SAP. When the input has only
one channel it is used for all audio tracks. It is not possible to
encode a Second Audio Program only. This flag must combine with
<CODE
CLASS="CONSTANT"
>V4L2_TUNER_SUB_MONO</CODE
> or
<CODE
CLASS="CONSTANT"
>V4L2_TUNER_SUB_STEREO</CODE
>. If the hardware does not
support the respective audio matrix, or the current video standard
does not permit SAP the <CODE
CLASS="CONSTANT"
> VIDIOC_S_MODULATOR</CODE
> ioctl
shall return an <SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code and driver shall fall back to mono or stereo
mode.<A
HREF="#FTN.TUNER-AUDIO-CAP"
><SPAN
CLASS="footnote"
>[a]</SPAN
></A
></TD
></TR
></TBODY
></TABLE
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN7396"
></A
><H2
>Return Value</H2
><P
>On success 0 is returned, on error -1 and
<VAR
CLASS="VARNAME"
>errno</VAR
> is set appropriately:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
></DT
><DD
><P
>The struct <A
HREF="#V4L2-MODULATOR"
>v4l2_modulator</A
>
<CODE
CLASS="STRUCTFIELD"
>index</CODE
> is out of bounds.</P
></DD
></DL
></DIV
></DIV
><H1
><A
NAME="VIDIOC-G-OUTPUT"
></A
>ioctl VIDIOC_G_OUTPUT, VIDIOC_S_OUTPUT</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN7411"
></A
><H2
>Name</H2
>ioctl VIDIOC_G_OUTPUT, ioctl VIDIOC_S_OUTPUT -- Query or select the current video output</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN7415"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN7416"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, int *argp);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN7426"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><VAR
CLASS="PARAMETER"
>fd</VAR
></DT
><DD
><P
>File descriptor returned by <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
>.</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>request</VAR
></DT
><DD
><P
>VIDIOC_G_OUTPUT, VIDIOC_S_OUTPUT</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>argp</VAR
></DT
><DD
><P
></P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN7446"
></A
><H2
>Description</H2
><P
>To query the current video output applications call the
<CODE
CLASS="CONSTANT"
>VIDIOC_G_OUTPUT</CODE
> ioctl with a pointer to an integer
where the driver stores the number of the output, as in the
struct <A
HREF="#V4L2-OUTPUT"
>v4l2_output</A
> <CODE
CLASS="STRUCTFIELD"
>index</CODE
> field. This ioctl
will fail only when there are no video outputs, returning the
<SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code.</P
><P
>To select a video output applications store the number of the
desired output in an integer and call the
<CODE
CLASS="CONSTANT"
>VIDIOC_S_OUTPUT</CODE
> ioctl with a pointer to this integer.
Side effects are possible. For example outputs may support different
video standards, so the driver may implicitly switch the current
standard. It is good practice to select an output before querying or
negotiating any other parameters.</P
><P
>Information about video outputs is available using the
<A
HREF="#VIDIOC-ENUMOUTPUT"
><CODE
CLASS="CONSTANT"
>VIDIOC_ENUMOUTPUT</CODE
></A
> ioctl.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN7458"
></A
><H2
>Return Value</H2
><P
>On success <SPAN
CLASS="RETURNVALUE"
>0</SPAN
> is returned, on
error <SPAN
CLASS="RETURNVALUE"
>-1</SPAN
> and <VAR
CLASS="VARNAME"
>errno</VAR
> is
set appropriately:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
></DT
><DD
><P
>The number of the video output is out of bounds, or
there are no video outputs at all and this ioctl is not
supported.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>EBUSY</SPAN
></DT
><DD
><P
>I/O is in progress, the output cannot be
switched.</P
></DD
></DL
></DIV
></DIV
><H1
><A
NAME="VIDIOC-G-PARM"
></A
>ioctl VIDIOC_G_PARM, VIDIOC_S_PARM</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN7478"
></A
><H2
>Name</H2
>ioctl VIDIOC_G_PARM, ioctl VIDIOC_S_PARM -- Get or set streaming parameters</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN7482"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN7483"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, v4l2_streamparm *argp);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN7493"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><VAR
CLASS="PARAMETER"
>fd</VAR
></DT
><DD
><P
>File descriptor returned by <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
>.</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>request</VAR
></DT
><DD
><P
>VIDIOC_G_PARM, VIDIOC_S_PARM</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>argp</VAR
></DT
><DD
><P
></P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN7513"
></A
><H2
>Description</H2
><P
>[to do]</P
><P
><CODE
CLASS="CONSTANT"
>VIDIOC_S_PARM</CODE
> is a write-only ioctl,
it does not return the actual parameters.</P
><DIV
CLASS="TABLE"
><A
NAME="V4L2-STREAMPARM"
></A
><P
><B
>Table 1. struct <CODE
CLASS="STRUCTNAME"
>v4l2_streamparm</CODE
></B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="50%"
TITLE="C1"><COL><COL><TBODY
><TR
><TD
>enum <A
HREF="#V4L2-BUF-TYPE"
>v4l2_buf_type</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>type</CODE
></TD
><TD
> </TD
><TD
>The buffer (stream) type, same as struct <A
HREF="#V4L2-FORMAT"
>v4l2_format</A
>
<CODE
CLASS="STRUCTFIELD"
>type</CODE
>, set by the application.</TD
></TR
><TR
><TD
>union</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>parm</CODE
></TD
><TD
> </TD
><TD
> </TD
></TR
><TR
><TD
> </TD
><TD
>struct <A
HREF="#V4L2-CAPTUREPARM"
>v4l2_captureparm</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>capture</CODE
></TD
><TD
>Parameters for capture devices, used when
<CODE
CLASS="STRUCTFIELD"
>type</CODE
> is
<CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_VIDEO_CAPTURE</CODE
>.</TD
></TR
><TR
><TD
> </TD
><TD
>struct <A
HREF="#V4L2-OUTPUTPARM"
>v4l2_outputparm</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>output</CODE
></TD
><TD
>Parameters for output devices, used when
<CODE
CLASS="STRUCTFIELD"
>type</CODE
> is
<CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_VIDEO_OUTPUT</CODE
>.</TD
></TR
><TR
><TD
> </TD
><TD
>__u8</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>raw_data</CODE
>[200]</TD
><TD
>A place holder for future extensions and custom
(driver defined) buffer types <CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_PRIVATE</CODE
> and
higher.</TD
></TR
></TBODY
></TABLE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="V4L2-CAPTUREPARM"
></A
><P
><B
>Table 2. struct <CODE
CLASS="STRUCTNAME"
>v4l2_captureparm</CODE
></B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="25%"
TITLE="C1"><COL
WIDTH="25%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>capability</CODE
></TD
><TD
>See <A
HREF="#PARM-CAPS"
>Table 4</A
>.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>capturemode</CODE
></TD
><TD
>Set by drivers and applications, see <A
HREF="#PARM-FLAGS"
>Table 5</A
>.</TD
></TR
><TR
><TD
>struct <A
HREF="#V4L2-FRACT"
>v4l2_fract</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>timeperframe</CODE
></TD
><TD
><P
>This is is the desired period between
successive frames captured by the driver, expressed in 0.1 µs
units. The field is intended to skip frames on the driver side, saving
I/O bandwidth.</P
><P
>Applications store here the desired frame
period, drivers return the actual frame period, which must be greater
or equal to the nominal frame period determined by the current video
standard (struct <A
HREF="#V4L2-STANDARD"
>v4l2_standard</A
> <CODE
CLASS="STRUCTFIELD"
>frameperiod</CODE
>
field). Changing the video standard (also implicitly by switching the
video input) may reset this parameter to the nominal frame period. To
reset manually applications can just set this field to
zero.</P
><P
>Drivers support this function only when they set the
<CODE
CLASS="CONSTANT"
>V4L2_CAP_TIMEPERFRAME</CODE
> flag in the
<CODE
CLASS="STRUCTFIELD"
>capability</CODE
> field.</P
></TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>extendedmode</CODE
></TD
><TD
>Custom (driver specific) streaming parameters. When
unused, applications and drivers must set this field to zero.
Applications using this field should check the driver name and
version, see <A
HREF="#QUERYCAP"
>Section 1.2</A
>.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>readbuffers</CODE
></TD
><TD
>Applications set this field to the desired number
of buffers used internally by the driver in <A
HREF="#FUNC-READ"
><CODE
CLASS="FUNCTION"
>read()</CODE
></A
>
mode. Drivers return the actual number of buffers. When an application requests
zero buffers, drivers should just return the current
setting rather than the minimum or an error code. For
details see <A
HREF="#RW"
>Section 3.1</A
>.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>reserved</CODE
>[4]</TD
><TD
>Reserved for future extensions. Drivers and
applications must set the array to zero.</TD
></TR
></TBODY
></TABLE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="V4L2-OUTPUTPARM"
></A
><P
><B
>Table 3. struct <CODE
CLASS="STRUCTNAME"
>v4l2_outputparm</CODE
></B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="25%"
TITLE="C1"><COL
WIDTH="25%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>capability</CODE
></TD
><TD
>See <A
HREF="#PARM-CAPS"
>Table 4</A
>.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>outputmode</CODE
></TD
><TD
>Set by drivers and applications, see <A
HREF="#PARM-FLAGS"
>Table 5</A
>.</TD
></TR
><TR
><TD
>struct <A
HREF="#V4L2-FRACT"
>v4l2_fract</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>timeperframe</CODE
></TD
><TD
>This is is the desired period between
successive frames output by the driver, expressed in 0.1 µs
units.</TD
></TR
><TR
><TD
COLSPAN="3"
><P
>The field is intended to
repeat frames on the driver side in <A
HREF="#FUNC-WRITE"
><CODE
CLASS="FUNCTION"
>write()</CODE
></A
> mode (in streaming
mode timestamps can be used to throttle the output), saving I/O
bandwidth.</P
><P
>Applications store here the desired frame
period, drivers return the actual frame period, which must be greater
or equal to the nominal frame period determined by the current video
standard (struct <A
HREF="#V4L2-STANDARD"
>v4l2_standard</A
> <CODE
CLASS="STRUCTFIELD"
>frameperiod</CODE
>
field). Changing the video standard (also implicitly by switching the
video output) may reset this parameter to the nominal frame period. To
reset manually applications can just set this field to
zero.</P
><P
>Drivers support this function only when they set the
<CODE
CLASS="CONSTANT"
>V4L2_CAP_TIMEPERFRAME</CODE
> flag in the
<CODE
CLASS="STRUCTFIELD"
>capability</CODE
> field.</P
></TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>extendedmode</CODE
></TD
><TD
>Custom (driver specific) streaming parameters. When
unused, applications and drivers must set this field to zero.
Applications using this field should check the driver name and
version, see <A
HREF="#QUERYCAP"
>Section 1.2</A
>.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>writebuffers</CODE
></TD
><TD
>Applications set this field to the desired number
of buffers used internally by the driver in
<CODE
CLASS="FUNCTION"
>write()</CODE
> mode. Drivers return the actual number of
buffers. When an application requests zero buffers, drivers should
just return the current setting rather than the minimum or an error
code. For details see <A
HREF="#RW"
>Section 3.1</A
>.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>reserved</CODE
>[4]</TD
><TD
>Reserved for future extensions. Drivers and
applications must set the array to zero.</TD
></TR
></TBODY
></TABLE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="PARM-CAPS"
></A
><P
><B
>Table 4. Streaming Parameters Capabilites</B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="38%"
TITLE="C1"><COL
WIDTH="12%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CAP_TIMEPERFRAME</CODE
></TD
><TD
>0x1000</TD
><TD
>The frame skipping/repeating controlled by the
<CODE
CLASS="STRUCTFIELD"
>timeperframe</CODE
> field is supported.</TD
></TR
></TBODY
></TABLE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="PARM-FLAGS"
></A
><P
><B
>Table 5. Capture Parameters Flags</B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="38%"
TITLE="C1"><COL
WIDTH="12%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_MODE_HIGHQUALITY</CODE
></TD
><TD
>0x0001</TD
><TD
><P
>High quality imaging mode. High quality mode
is intended for still imaging applications. The idea is to get the
best possible image quality that the hardware can deliver. It is not
defined how the driver writer may achieve that; it will depend on the
hardware and the ingenuity of the driver writer. High quality mode is
a different mode from the the regular motion video capture modes. In
high quality mode:<P
></P
><UL
><LI
><P
>The driver may be able to capture higher
resolutions than for motion capture.</P
></LI
><LI
><P
>The driver may support fewer pixel formats
than motion capture (e.g. true color).</P
></LI
><LI
><P
>The driver may capture and arithmetically
combine multiple successive fields or frames to remove color edge
artifacts and reduce the noise in the video data.</P
></LI
><LI
><P
>The driver may capture images in slices like
a scanner in order to handle larger format images than would otherwise
be possible. </P
></LI
><LI
><P
>An image capture operation may be
significantly slower than motion capture. </P
></LI
><LI
><P
>Moving objects in the image might have
excessive motion blur. </P
></LI
><LI
><P
>Capture might only work through the
<CODE
CLASS="FUNCTION"
>read()</CODE
> call.</P
></LI
></UL
></P
></TD
></TR
></TBODY
></TABLE
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN7719"
></A
><H2
>Return Value</H2
><P
>On success <SPAN
CLASS="RETURNVALUE"
>0</SPAN
> is returned, on
error <SPAN
CLASS="RETURNVALUE"
>-1</SPAN
> and <VAR
CLASS="VARNAME"
>errno</VAR
> is
set appropriately:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
></DT
><DD
><P
>This ioctl is not supported.</P
></DD
></DL
></DIV
></DIV
><H1
><A
NAME="VIDIOC-G-PRIORITY"
></A
>ioctl VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN7734"
></A
><H2
>Name</H2
>ioctl VIDIOC_G_PRIORITY, ioctl VIDIOC_S_PRIORITY -- Query or request the access priority associated with a
file descriptor</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN7738"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN7739"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, enum v4l2_priority *argp);</CODE
></P
><P
></P
></DIV
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN7749"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, const enum v4l2_priority *argp);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN7759"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><VAR
CLASS="PARAMETER"
>fd</VAR
></DT
><DD
><P
>File descriptor returned by <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
>.</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>request</VAR
></DT
><DD
><P
>VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>argp</VAR
></DT
><DD
><P
>Pointer to an enum v4l2_priority type.</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN7779"
></A
><H2
>Description</H2
><P
>To query the current access priority
applications call the <CODE
CLASS="CONSTANT"
>VIDIOC_G_PRIORITY</CODE
> ioctl
with a pointer to an enum v4l2_priority variable where the driver stores
the current priority.</P
><P
>To request an access priority applications store the
desired priority in an enum v4l2_priority variable and call
<CODE
CLASS="CONSTANT"
>VIDIOC_S_PRIORITY</CODE
> ioctl with a pointer to this
variable.</P
><DIV
CLASS="TABLE"
><A
NAME="V4L2-PRIORITY"
></A
><P
><B
>Table 1. enum v4l2_priority</B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="38%"
TITLE="C1"><COL
WIDTH="12%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_PRIORITY_UNSET</CODE
></TD
><TD
>0</TD
><TD
> </TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_PRIORITY_BACKGROUND</CODE
></TD
><TD
>1</TD
><TD
>Lowest priority, usually applications running in
background, for example monitoring VBI transmissions. A proxy
application running in user space will be necessary if multiple
applications want to read from a device at this priority.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_PRIORITY_INTERACTIVE</CODE
></TD
><TD
>2</TD
><TD
> </TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_PRIORITY_DEFAULT</CODE
></TD
><TD
>2</TD
><TD
>Medium priority, usually applications started and
interactively controlled by the user. For example TV viewers, Teletext
browsers, or just "panel" applications to change the channel or video
controls. This is the default priority unless an application requests
another.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_PRIORITY_RECORD</CODE
></TD
><TD
>3</TD
><TD
>Highest priority. Only one file descriptor can have
this priority, it blocks any other fd from changing device properties.
Usually applications which must not be interrupted, like video
recording.</TD
></TR
></TBODY
></TABLE
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN7818"
></A
><H2
>Return Value</H2
><P
>On success <SPAN
CLASS="RETURNVALUE"
>0</SPAN
> is returned, on
error <SPAN
CLASS="RETURNVALUE"
>-1</SPAN
> and <VAR
CLASS="VARNAME"
>errno</VAR
> is
set appropriately:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
></DT
><DD
><P
>The requested priority value is invalid, or the
driver does not support access priorities.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>EBUSY</SPAN
></DT
><DD
><P
>Another application already requested higher
priority.</P
></DD
></DL
></DIV
></DIV
><H1
><A
NAME="VIDIOC-G-STD"
></A
>ioctl VIDIOC_G_STD, VIDIOC_S_STD</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN7838"
></A
><H2
>Name</H2
>ioctl VIDIOC_G_STD, ioctl VIDIOC_S_STD -- Query or select the video standard of the current input</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN7842"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN7843"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, v4l2_std_id
*argp);</CODE
></P
><P
></P
></DIV
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN7853"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, const v4l2_std_id
*argp);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN7863"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><VAR
CLASS="PARAMETER"
>fd</VAR
></DT
><DD
><P
>File descriptor returned by <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
>.</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>request</VAR
></DT
><DD
><P
>VIDIOC_G_STD, VIDIOC_S_STD</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>argp</VAR
></DT
><DD
><P
></P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN7883"
></A
><H2
>Description</H2
><P
>To query and select the current video standard applications
use the <CODE
CLASS="CONSTANT"
>VIDIOC_G_STD</CODE
> and <CODE
CLASS="CONSTANT"
>VIDIOC_S_STD</CODE
> ioctls which take a pointer to a
<A
HREF="#V4L2-STD-ID"
>v4l2_std_id</A
> type as argument. <CODE
CLASS="CONSTANT"
>VIDIOC_G_STD</CODE
> can
return a single flag or a set of flags as in struct <A
HREF="#V4L2-STANDARD"
>v4l2_standard</A
> field
<CODE
CLASS="STRUCTFIELD"
>id</CODE
>. The flags must be unambiguous such
that they appear in only one enumerated <CODE
CLASS="STRUCTNAME"
>v4l2_standard</CODE
> structure.</P
><P
><CODE
CLASS="CONSTANT"
>VIDIOC_S_STD</CODE
> accepts one or more
flags, being a write-only ioctl it does not return the actual new standard as
<CODE
CLASS="CONSTANT"
>VIDIOC_G_STD</CODE
> does. When no flags are given or
the current input does not support the requested standard the driver
returns an <SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code. When the standard set is ambiguous drivers may
return <SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> or choose any of the requested
standards.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN7898"
></A
><H2
>Return Value</H2
><P
>On success <SPAN
CLASS="RETURNVALUE"
>0</SPAN
> is returned, on
error <SPAN
CLASS="RETURNVALUE"
>-1</SPAN
> and <VAR
CLASS="VARNAME"
>errno</VAR
> is
set appropriately:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
></DT
><DD
><P
>This ioctl is not supported, or the
<CODE
CLASS="CONSTANT"
>VIDIOC_S_STD</CODE
> parameter was unsuitable.</P
></DD
></DL
></DIV
></DIV
><H1
><A
NAME="VIDIOC-G-TUNER"
></A
>ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN7914"
></A
><H2
>Name</H2
>ioctl VIDIOC_G_TUNER, ioctl VIDIOC_S_TUNER -- Get or set tuner attributes</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN7918"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN7919"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, struct v4l2_tuner
*argp);</CODE
></P
><P
></P
></DIV
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN7929"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, const struct v4l2_tuner
*argp);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN7939"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><VAR
CLASS="PARAMETER"
>fd</VAR
></DT
><DD
><P
>File descriptor returned by <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
>.</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>request</VAR
></DT
><DD
><P
>VIDIOC_G_TUNER, VIDIOC_S_TUNER</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>argp</VAR
></DT
><DD
><P
></P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN7959"
></A
><H2
>Description</H2
><P
>To query the attributes of a tuner applications initialize the
<CODE
CLASS="STRUCTFIELD"
>index</CODE
> field and zero out the
<CODE
CLASS="STRUCTFIELD"
>reserved</CODE
> array of a struct <A
HREF="#V4L2-TUNER"
>v4l2_tuner</A
> and call the
<CODE
CLASS="CONSTANT"
>VIDIOC_G_TUNER</CODE
> ioctl with a pointer to this
structure. Drivers fill the rest of the structure or return an
<SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code when the index is out of bounds. To enumerate all tuners
applications shall begin at index zero, incrementing by one until the
driver returns <SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
>.</P
><P
>Tuners have two writable properties, the audio mode and
the radio frequency. To switch the audio mode, applications initialize
the <CODE
CLASS="STRUCTFIELD"
>index</CODE
> and
<CODE
CLASS="STRUCTFIELD"
>audmode</CODE
> fields and the
<CODE
CLASS="STRUCTFIELD"
>reserved</CODE
> array and call the
<CODE
CLASS="CONSTANT"
>VIDIOC_S_TUNER</CODE
> ioctl. This will
<SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>not</I
></SPAN
> change the currently selected tuner,
which is determined by the current video input. Drivers may choose a
different audio mode if the request cannot be satisfied. Since this
is a write-only ioctl it does not return the actual audio mode
selected.</P
><P
>To change the radio frequency the <A
HREF="#VIDIOC-G-FREQUENCY"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_FREQUENCY</CODE
></A
> ioctl
is available.</P
><DIV
CLASS="TABLE"
><A
NAME="V4L2-TUNER"
></A
><P
><B
>Table 1. struct <CODE
CLASS="STRUCTNAME"
>v4l2_tuner</CODE
></B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="25%"
TITLE="C1"><COL
WIDTH="25%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>index</CODE
></TD
><TD
>Identifies the tuner, set by the
application.</TD
></TR
><TR
><TD
>__u8</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>name</CODE
>[32]</TD
><TD
><P
>Name of the tuner, a NUL-terminated ASCII
string. This information is intended for the user.<SUP
>a</SUP
></P
></TD
></TR
><TR
><TD
>enum <A
HREF="#V4L2-TUNER-TYPE"
>v4l2_tuner_type</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>type</CODE
></TD
><TD
>Type of the tuner, see <A
HREF="#V4L2-TUNER-TYPE"
>Table 2</A
>.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>capability</CODE
></TD
><TD
><P
>Tuner capability flags, see <A
HREF="#TUNER-CAPABILITY"
>Table 3</A
>. Audio flags indicate
the ability to decode audio subprograms. They will
<SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>not</I
></SPAN
> change for example with the current video
standard.</P
><P
>When the structure refers to a radio tuner only
the <CODE
CLASS="CONSTANT"
>V4L2_TUNER_CAP_LOW</CODE
> and
<CODE
CLASS="CONSTANT"
>V4L2_TUNER_CAP_STEREO</CODE
> flags can be
set.</P
></TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>rangelow</CODE
></TD
><TD
>The lowest tunable frequency in units of 62.5
KHz, or if the <CODE
CLASS="STRUCTFIELD"
>capability</CODE
> flag
<CODE
CLASS="CONSTANT"
>V4L2_TUNER_CAP_LOW</CODE
> is set, in units of 62.5
Hz.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>rangehigh</CODE
></TD
><TD
>The highest tunable frequency in units of 62.5
KHz, or if the <CODE
CLASS="STRUCTFIELD"
>capability</CODE
> flag
<CODE
CLASS="CONSTANT"
>V4L2_TUNER_CAP_LOW</CODE
> is set, in units of 62.5
Hz.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>rxsubchans</CODE
></TD
><TD
><P
>Some tuners can report the audio subprograms
received by analyzing audio carriers, pilot tones or other indicators.
The <CODE
CLASS="STRUCTFIELD"
>rxsubchans</CODE
> field contains flags defined
in <A
HREF="#TUNER-RXSUBCHANS"
>Table 4</A
>, which are set by the driver to
indicate the audio subprograms the hardware <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>may</I
></SPAN
>
currently receive.</P
></TD
></TR
><TR
><TD
COLSPAN="3"
><P
>Only those flags can be set
here which are also set in the <CODE
CLASS="STRUCTFIELD"
>capability</CODE
>
field. When the detection is inconclusive the flags of all possible
audio subprograms must be set. When the driver cannot detect the audio
subprograms at all, this field must contain the same audio flags as
<CODE
CLASS="STRUCTFIELD"
>capability </CODE
>.<SUP
>b</SUP
></P
><P
>For example when two audio
channels are detected but the hardware cannot distinguish between
stereo and bilingual mode all the
<CODE
CLASS="CONSTANT"
>V4L2_TUNER_SUB_STEREO</CODE
>,
<CODE
CLASS="CONSTANT"
>V4L2_TUNER_SUB_LANG1</CODE
>, and
<CODE
CLASS="CONSTANT"
>V4L2_TUNER_SUB_LANG2</CODE
> flags may be set.</P
><P
>When the structure refers to a radio tuner only the
<CODE
CLASS="CONSTANT"
>V4L2_TUNER_SUB_MONO</CODE
> and
<CODE
CLASS="CONSTANT"
>V4L2_TUNER_SUB_STEREO</CODE
> flag can be
set.</P
><P
>The field is valid only when this is the tuner of the
current video input or a radio tuner.</P
></TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>audmode</CODE
></TD
><TD
><P
>The selected audio mode, see <A
HREF="#TUNER-AUDMODE"
>Table 5</A
> for valid values. The audio mode
does not affect audio subprogram detection, and it does not change
automatically. See <A
HREF="#TUNER-MATRIX"
>Table 6</A
> for possible results
when the selected and received audio programs do not
match.</P
><P
>When the structure refers to a radio tuner only the
<CODE
CLASS="CONSTANT"
>V4L2_TUNER_MODE_MONO</CODE
> and
<CODE
CLASS="CONSTANT"
>V4L2_TUNER_MODE_STEREO</CODE
> are valid
values.</P
><P
>Currently this is the only field of struct
<CODE
CLASS="STRUCTNAME"
>v4l2_tuner</CODE
> applications can change.</P
></TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>signal</CODE
></TD
><TD
>The signal strength if known, supposedly ranging
from 0 to 65535. Higher values indicate a better signal.</TD
></TR
><TR
><TD
>__s32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>afc</CODE
></TD
><TD
>Automatic frequency control: When the
<CODE
CLASS="STRUCTFIELD"
>afc</CODE
> value is negative, the frequency is too
low, when positive too high. [need example what to do when it never
settles at zero, i. e. range is what?]</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>reserved</CODE
>[4]</TD
><TD
>Reserved for future extensions. Drivers and
applications must set the array to zero.</TD
></TR
></TBODY
><TR
><TD
COLSPAN="3"
>Notes:<BR><A
NAME="FTN.AEN7997"
>a. </A
>Video inputs already have a name, the purpose
of this field is not quite clear.<BR><A
NAME="FTN.AEN8045"
>b. </A
>Purpose of
<CODE
CLASS="STRUCTFIELD"
>rxsubchans</CODE
> is to eliminate choice, i. e.
those audio subprograms the driver knows for sure are not received
right now.<BR></TD
></TR
></TABLE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="V4L2-TUNER-TYPE"
></A
><P
><B
>Table 2. enum v4l2_tuner_type</B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="38%"
TITLE="C1"><COL
WIDTH="12%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_TUNER_RADIO</CODE
></TD
><TD
>1</TD
><TD
> </TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_TUNER_ANALOG_TV</CODE
></TD
><TD
>2</TD
><TD
> </TD
></TR
></TBODY
></TABLE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="TUNER-CAPABILITY"
></A
><P
><B
>Table 3. Tuner and Modulator Capability Flags</B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="38%"
TITLE="C1"><COL
WIDTH="12%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_TUNER_CAP_LOW</CODE
></TD
><TD
>0x0001</TD
><TD
>When set frequencies are expressed in units of
62.5 Hz, otherwise in units of 62.5 kHz.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_TUNER_CAP_NORM</CODE
></TD
><TD
>0x0002</TD
><TD
>This is a multi-standard tuner; the video
standard can or must be switched. (B/G PAL tuners for example are
typically not considered multi-standard because the video standard is
automatically selected depending on the frequency band.) The supported
video standards are reported in the respective struct <A
HREF="#V4L2-INPUT"
>v4l2_input</A
> field
<CODE
CLASS="STRUCTFIELD"
>std</CODE
>. For details on video standards and how
to switch see <A
HREF="#STANDARD"
>Section 1.7</A
>.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_TUNER_CAP_STEREO</CODE
></TD
><TD
>0x0010</TD
><TD
>Stereo audio reception is supported.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_TUNER_CAP_LANG1</CODE
></TD
><TD
>0x0040</TD
><TD
>Reception of a primary language (of two) is
supported.<A
HREF="#FTN.TUNER-AUDIO-CAP"
><SPAN
CLASS="footnote"
>[a]</SPAN
></A
></TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_TUNER_CAP_LANG2</CODE
></TD
><TD
>0x0020</TD
><TD
>Reception of a secondary language is
supported.<A
HREF="#FTN.TUNER-AUDIO-CAP"
><SPAN
CLASS="footnote"
>[a]</SPAN
></A
></TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_TUNER_CAP_SAP</CODE
></TD
><TD
>0x0020</TD
><TD
><P
>Reception of the Secondary Audio Program
(typically a secondary language of the current program) is supported.
Note the <CODE
CLASS="CONSTANT"
>V4L2_TUNER_CAP_LANG2</CODE
> and
<CODE
CLASS="CONSTANT"
>V4L2_TUNER_CAP_SAP</CODE
> flags are synonyms. <SUP
>a</SUP
></P
></TD
></TR
></TBODY
><TR
><TD
COLSPAN="3"
>Notes:<BR><A
NAME="FTN.TUNER-AUDIO-CAP"
>a. </A
>The LANG1/LANG2
nomenclature refers to audio systems transmitting different languages
monaural on two audio subcarriers ("bilingual mode"), otherwise the
left and right stereo channel. Similar the NICAM digital audio system
with two audio channels, transmitted on a second audio subcarrier
while the main AM/FM audio carrier provides mono or primary language
audio for older TV sets. SAP is a feature of the U.S. BTSC audio
system, which consists of up to three audio subcarriers. Unlike LANG2
SAP is a separate mono audio track besides the primary mono or stereo
audio track.<BR>The <CODE
CLASS="CONSTANT"
>V4L2_TUNER_CAP_SAP</CODE
>
capability flag applies when the tuner supports the M/NTSC video
standard. <CODE
CLASS="CONSTANT"
>V4L2_TUNER_SUB_SAP</CODE
> and
<CODE
CLASS="CONSTANT"
>V4L2_TUNER_MODE_SAP</CODE
> apply when the M/NTSC video
standard is currently selected.<BR></TD
></TR
></TABLE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="TUNER-RXSUBCHANS"
></A
><P
><B
>Table 4. Tuner Audio Reception Flags</B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="38%"
TITLE="C1"><COL
WIDTH="12%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_TUNER_SUB_MONO</CODE
></TD
><TD
>0x0001</TD
><TD
>The tuner receives a mono audio signal.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_TUNER_SUB_STEREO</CODE
></TD
><TD
>0x0002</TD
><TD
>The tuner receives a stereo audio signal.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_TUNER_SUB_LANG1</CODE
></TD
><TD
>0x0008</TD
><TD
>The tuner receives the primary language of a
bilingual audio signal. This flag is not supposed to be set when the
tuner receives Mono + SAP or Stereo + SAP audio.<A
HREF="#FTN.TUNER-AUDIO-CAP"
><SPAN
CLASS="footnote"
>[a]</SPAN
></A
></TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_TUNER_SUB_LANG2</CODE
></TD
><TD
>0x0004</TD
><TD
>The tuner receives the secondary language of a
bilingual audio signal.<A
HREF="#FTN.TUNER-AUDIO-CAP"
><SPAN
CLASS="footnote"
>[a]</SPAN
></A
></TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_TUNER_SUB_SAP</CODE
></TD
><TD
>0x0004</TD
><TD
>The tuner receives a Second Audio Program. Note
the <CODE
CLASS="CONSTANT"
>V4L2_TUNER_SUB_LANG2</CODE
> and
<CODE
CLASS="CONSTANT"
>V4L2_TUNER_SUB_SAP</CODE
> flags are
synonyms.<A
HREF="#FTN.TUNER-AUDIO-CAP"
><SPAN
CLASS="footnote"
>[a]</SPAN
></A
></TD
></TR
></TBODY
></TABLE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="TUNER-AUDMODE"
></A
><P
><B
>Table 5. Tuner Audio Modes</B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="38%"
TITLE="C1"><COL
WIDTH="12%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_TUNER_MODE_MONO</CODE
></TD
><TD
>0</TD
><TD
>Play mono audio. When the tuner receives a stereo
signal this a down-mix of the left and right channel. When the tuner
receives a bilingual or SAP signal this mode selects the primary
language.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_TUNER_MODE_STEREO</CODE
></TD
><TD
>1</TD
><TD
>Play stereo audio. When the tuner receives
bilingual audio it may play different languages on the left and right
channel or the primary language on both channels. When it receives no
stereo signal or does not support stereo reception the driver shall
fall back to mono mode.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_TUNER_MODE_LANG1</CODE
></TD
><TD
>3</TD
><TD
>Play the primary language, mono or
stereo.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_TUNER_MODE_LANG2</CODE
></TD
><TD
>2</TD
><TD
>Play the secondary language, mono. When the tuner
receives no bilingual audio or SAP, or their reception is not
supported the driver shall fall back to mono or stereo mode.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_TUNER_MODE_SAP</CODE
></TD
><TD
>2</TD
><TD
>Play the Second Audio Program. When the tuner
receives no bilingual audio or SAP, or their reception is not
supported the driver shall fall back to mono or stereo mode. Note the
<CODE
CLASS="CONSTANT"
>V4L2_TUNER_MODE_LANG2</CODE
> and
<CODE
CLASS="CONSTANT"
>V4L2_TUNER_MODE_SAP</CODE
> identifiers are
synonyms.<A
HREF="#FTN.TUNER-AUDIO-CAP"
><SPAN
CLASS="footnote"
>[a]</SPAN
></A
></TD
></TR
></TBODY
></TABLE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="TUNER-MATRIX"
></A
><P
><B
>Table 6. Tuner Audio Matrix</B
></P
><TABLE
BORDER="1"
FRAME="border"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="33%"
ALIGN="LEFT"><COL
WIDTH="33%"
TITLE="C2"><COL><COL><COL
WIDTH="33%"
TITLE="C5"><THEAD
><TR
><TH
> </TH
><TH
COLSPAN="4"
ALIGN="CENTER"
>Selected</TH
></TR
><TR
><TH
>Received</TH
><TH
>Mono</TH
><TH
>Stereo</TH
><TH
>Language 1</TH
><TH
>Language 2 / SAP</TH
></TR
></THEAD
><TBODY
><TR
><TD
>Mono</TD
><TD
>Mono</TD
><TD
>Mono/Mono</TD
><TD
>Mono</TD
><TD
>Mono</TD
></TR
><TR
><TD
>Stereo</TD
><TD
>L+R</TD
><TD
>L/R</TD
><TD
>Undefined: L/L or L+R Mono or
L/R Stereo</TD
><TD
>Undefined: R/R or L+R Mono or
L/R Stereo</TD
></TR
><TR
><TD
>Mono/Stereo + SAP (BTSC only)</TD
><TD
>-</TD
><TD
>-</TD
><TD
>Main audio program, mono or stereo</TD
><TD
>SAP Mono</TD
></TR
><TR
><TD
>Bilingual (two carrier systems only)</TD
><TD
>Language 1</TD
><TD
>Undefined: Lang1/Lang1 or Lang1/Lang2</TD
><TD
>Language 1 Mono</TD
><TD
>Language 2 Mono</TD
></TR
></TBODY
></TABLE
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN8271"
></A
><H2
>Return Value</H2
><P
>On success <SPAN
CLASS="RETURNVALUE"
>0</SPAN
> is returned, on
error <SPAN
CLASS="RETURNVALUE"
>-1</SPAN
> and <VAR
CLASS="VARNAME"
>errno</VAR
> is
set appropriately:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
></DT
><DD
><P
>The struct <A
HREF="#V4L2-TUNER"
>v4l2_tuner</A
> <CODE
CLASS="STRUCTFIELD"
>index</CODE
> is
out of bounds.</P
></DD
></DL
></DIV
></DIV
><H1
><A
NAME="VIDIOC-OVERLAY"
></A
>ioctl VIDIOC_OVERLAY</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN8288"
></A
><H2
>Name</H2
>ioctl VIDIOC_OVERLAY -- Start or stop video overlay</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN8291"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN8292"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, const int *argp);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN8302"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><VAR
CLASS="PARAMETER"
>fd</VAR
></DT
><DD
><P
>File descriptor returned by <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
>.</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>request</VAR
></DT
><DD
><P
>VIDIOC_OVERLAY</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>argp</VAR
></DT
><DD
><P
></P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN8322"
></A
><H2
>Description</H2
><P
>This ioctl is part of the <A
HREF="#OVERLAY"
>video
overlay</A
> I/O method. Applications call
<CODE
CLASS="CONSTANT"
>VIDIOC_OVERLAY</CODE
> to start or stop the
overlay. It takes a pointer to an integer which must be set to
zero by the application to stop overlay, to one to start.</P
><P
>Drivers do not support <A
HREF="#VIDIOC-STREAMON"
><CODE
CLASS="CONSTANT"
>VIDIOC_STREAMON</CODE
></A
> or
<A
HREF="#VIDIOC-STREAMON"
><CODE
CLASS="CONSTANT"
>VIDIOC_STREAMOFF</CODE
></A
> with <CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_VIDEO_OVERLAY</CODE
>.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN8333"
></A
><H2
>Return Value</H2
><P
>On success <SPAN
CLASS="RETURNVALUE"
>0</SPAN
> is returned, on
error <SPAN
CLASS="RETURNVALUE"
>-1</SPAN
> and <VAR
CLASS="VARNAME"
>errno</VAR
> is
set appropriately:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
></DT
><DD
><P
>Video overlay is not supported, or the
parameters have not been set up. See <A
HREF="#OVERLAY"
>Section 4.2</A
> for the necessary steps.</P
></DD
></DL
></DIV
></DIV
><H1
><A
NAME="VIDIOC-QBUF"
></A
>ioctl VIDIOC_QBUF, VIDIOC_DQBUF</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN8349"
></A
><H2
>Name</H2
>ioctl VIDIOC_QBUF, ioctl VIDIOC_DQBUF -- Exchange a buffer with the driver</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN8353"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN8354"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, struct v4l2_buffer *argp);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN8364"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><VAR
CLASS="PARAMETER"
>fd</VAR
></DT
><DD
><P
>File descriptor returned by <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
>.</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>request</VAR
></DT
><DD
><P
>VIDIOC_QBUF, VIDIOC_DQBUF</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>argp</VAR
></DT
><DD
><P
></P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN8384"
></A
><H2
>Description</H2
><P
>Applications call the <CODE
CLASS="CONSTANT"
>VIDIOC_QBUF</CODE
> ioctl
to enqueue an empty (capturing) or filled (output) buffer in the
driver's incoming queue. The semantics depend on the selected I/O
method.</P
><P
>To enqueue a <A
HREF="#MMAP"
>memory mapped</A
>
buffer applications set the <CODE
CLASS="STRUCTFIELD"
>type</CODE
> field of a
struct <A
HREF="#V4L2-BUFFER"
>v4l2_buffer</A
> to the same buffer type as previously struct <A
HREF="#V4L2-FORMAT"
>v4l2_format</A
>
<CODE
CLASS="STRUCTFIELD"
>type</CODE
> and struct <A
HREF="#V4L2-REQUESTBUFFERS"
>v4l2_requestbuffers</A
>
<CODE
CLASS="STRUCTFIELD"
>type</CODE
>, the <CODE
CLASS="STRUCTFIELD"
>memory</CODE
>
field to <CODE
CLASS="CONSTANT"
>V4L2_MEMORY_MMAP</CODE
> and the
<CODE
CLASS="STRUCTFIELD"
>index</CODE
> field. Valid index numbers range from
zero to the number of buffers allocated with <A
HREF="#VIDIOC-REQBUFS"
><CODE
CLASS="CONSTANT"
>VIDIOC_REQBUFS</CODE
></A
>
(struct <A
HREF="#V4L2-REQUESTBUFFERS"
>v4l2_requestbuffers</A
> <CODE
CLASS="STRUCTFIELD"
>count</CODE
>) minus one. The
contents of the struct <CODE
CLASS="STRUCTNAME"
>v4l2_buffer</CODE
> returned
by a <A
HREF="#VIDIOC-QUERYBUF"
><CODE
CLASS="CONSTANT"
>VIDIOC_QUERYBUF</CODE
></A
> ioctl will do as well. When the buffer is
intended for output (<CODE
CLASS="STRUCTFIELD"
>type</CODE
> is
<CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_VIDEO_OUTPUT</CODE
> or
<CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_VBI_OUTPUT</CODE
>) applications must also
initialize the <CODE
CLASS="STRUCTFIELD"
>bytesused</CODE
>,
<CODE
CLASS="STRUCTFIELD"
>field</CODE
> and
<CODE
CLASS="STRUCTFIELD"
>timestamp</CODE
> fields. See <A
HREF="#BUFFER"
>Section 3.5</A
> for details. When
<CODE
CLASS="CONSTANT"
>VIDIOC_QBUF</CODE
> is called with a pointer to this
structure the driver sets the
<CODE
CLASS="CONSTANT"
>V4L2_BUF_FLAG_MAPPED</CODE
> and
<CODE
CLASS="CONSTANT"
>V4L2_BUF_FLAG_QUEUED</CODE
> flags and clears the
<CODE
CLASS="CONSTANT"
>V4L2_BUF_FLAG_DONE</CODE
> flag in the
<CODE
CLASS="STRUCTFIELD"
>flags</CODE
> field, or it returns an
<SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code.</P
><P
>To enqueue a <A
HREF="#USERP"
>user pointer</A
>
buffer applications set the <CODE
CLASS="STRUCTFIELD"
>type</CODE
> field of a
struct <A
HREF="#V4L2-BUFFER"
>v4l2_buffer</A
> to the same buffer type as previously struct <A
HREF="#V4L2-FORMAT"
>v4l2_format</A
>
<CODE
CLASS="STRUCTFIELD"
>type</CODE
> and struct <A
HREF="#V4L2-REQUESTBUFFERS"
>v4l2_requestbuffers</A
>
<CODE
CLASS="STRUCTFIELD"
>type</CODE
>, the <CODE
CLASS="STRUCTFIELD"
>memory</CODE
>
field to <CODE
CLASS="CONSTANT"
>V4L2_MEMORY_USERPTR</CODE
> and the
<CODE
CLASS="STRUCTFIELD"
>m.userptr</CODE
> field to the address of the
buffer and <CODE
CLASS="STRUCTFIELD"
>length</CODE
> to its size. When the
buffer is intended for output additional fields must be set as above.
When <CODE
CLASS="CONSTANT"
>VIDIOC_QBUF</CODE
> is called with a pointer to this
structure the driver sets the <CODE
CLASS="CONSTANT"
>V4L2_BUF_FLAG_QUEUED</CODE
>
flag and clears the <CODE
CLASS="CONSTANT"
>V4L2_BUF_FLAG_MAPPED</CODE
> and
<CODE
CLASS="CONSTANT"
>V4L2_BUF_FLAG_DONE</CODE
> flags in the
<CODE
CLASS="STRUCTFIELD"
>flags</CODE
> field, or it returns an error code.
This ioctl locks the memory pages of the buffer in physical memory,
they cannot be swapped out to disk. Buffers remain locked until
dequeued, until the <A
HREF="#VIDIOC-STREAMON"
><CODE
CLASS="CONSTANT"
>VIDIOC_STREAMOFF</CODE
></A
> or <A
HREF="#VIDIOC-REQBUFS"
><CODE
CLASS="CONSTANT"
>VIDIOC_REQBUFS</CODE
></A
> ioctl are
called, or until the device is closed.</P
><P
>Applications call the <CODE
CLASS="CONSTANT"
>VIDIOC_DQBUF</CODE
>
ioctl to dequeue a filled (capturing) or displayed (output) buffer
from the driver's outgoing queue. They just set the
<CODE
CLASS="STRUCTFIELD"
>type</CODE
> and <CODE
CLASS="STRUCTFIELD"
>memory</CODE
>
fields of a struct <A
HREF="#V4L2-BUFFER"
>v4l2_buffer</A
> as above, when <CODE
CLASS="CONSTANT"
>VIDIOC_DQBUF</CODE
>
is called with a pointer to this structure the driver fills the
remaining fields or returns an error code.</P
><P
>By default <CODE
CLASS="CONSTANT"
>VIDIOC_DQBUF</CODE
> blocks when no
buffer is in the outgoing queue. When the
<CODE
CLASS="CONSTANT"
>O_NONBLOCK</CODE
> flag was given to the <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
>
function, <CODE
CLASS="CONSTANT"
>VIDIOC_DQBUF</CODE
> returns immediately
with an <SPAN
CLASS="ERRORCODE"
>EAGAIN</SPAN
> error code when no buffer is available.</P
><P
>The <CODE
CLASS="STRUCTNAME"
>v4l2_buffer</CODE
> structure is
specified in <A
HREF="#BUFFER"
>Section 3.5</A
>.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN8456"
></A
><H2
>Return Value</H2
><P
>On success <SPAN
CLASS="RETURNVALUE"
>0</SPAN
> is returned, on
error <SPAN
CLASS="RETURNVALUE"
>-1</SPAN
> and <VAR
CLASS="VARNAME"
>errno</VAR
> is
set appropriately:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="ERRORCODE"
>EAGAIN</SPAN
></DT
><DD
><P
>Non-blocking I/O has been selected using
<CODE
CLASS="CONSTANT"
>O_NONBLOCK</CODE
> and no buffer was in the outgoing
queue.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
></DT
><DD
><P
>The buffer <CODE
CLASS="STRUCTFIELD"
>type</CODE
> is not
supported, or the <CODE
CLASS="STRUCTFIELD"
>index</CODE
> is out of bounds,
or no buffers have been allocated yet, or the
<CODE
CLASS="STRUCTFIELD"
>userptr</CODE
> or
<CODE
CLASS="STRUCTFIELD"
>length</CODE
> are invalid.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>ENOMEM</SPAN
></DT
><DD
><P
>Insufficient memory to enqueue a user pointer buffer.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>EIO</SPAN
></DT
><DD
><P
><CODE
CLASS="CONSTANT"
>VIDIOC_DQBUF</CODE
> failed due to an
internal error. Can also indicate temporary problems like signal
loss. Note the driver might dequeue an (empty) buffer despite
returning an error, or even stop capturing.</P
></DD
></DL
></DIV
></DIV
><H1
><A
NAME="VIDIOC-QUERYBUF"
></A
>ioctl VIDIOC_QUERYBUF</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN8490"
></A
><H2
>Name</H2
>ioctl VIDIOC_QUERYBUF -- Query the status of a buffer</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN8493"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN8494"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, struct v4l2_buffer *argp);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN8504"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><VAR
CLASS="PARAMETER"
>fd</VAR
></DT
><DD
><P
>File descriptor returned by <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
>.</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>request</VAR
></DT
><DD
><P
>VIDIOC_QUERYBUF</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>argp</VAR
></DT
><DD
><P
></P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN8524"
></A
><H2
>Description</H2
><P
>This ioctl is part of the <A
HREF="#MMAP"
>memory
mapping</A
> I/O method. It can be used to query the status of a
buffer at any time after buffers have been allocated with the
<A
HREF="#VIDIOC-REQBUFS"
><CODE
CLASS="CONSTANT"
>VIDIOC_REQBUFS</CODE
></A
> ioctl.</P
><P
>Applications set the <CODE
CLASS="STRUCTFIELD"
>type</CODE
> field
of a struct <A
HREF="#V4L2-BUFFER"
>v4l2_buffer</A
> to the same buffer type as previously
struct <A
HREF="#V4L2-FORMAT"
>v4l2_format</A
> <CODE
CLASS="STRUCTFIELD"
>type</CODE
> and struct <A
HREF="#V4L2-REQUESTBUFFERS"
>v4l2_requestbuffers</A
>
<CODE
CLASS="STRUCTFIELD"
>type</CODE
>, and the <CODE
CLASS="STRUCTFIELD"
>index</CODE
>
field. Valid index numbers range from zero
to the number of buffers allocated with <A
HREF="#VIDIOC-REQBUFS"
><CODE
CLASS="CONSTANT"
>VIDIOC_REQBUFS</CODE
></A
>
(struct <A
HREF="#V4L2-REQUESTBUFFERS"
>v4l2_requestbuffers</A
> <CODE
CLASS="STRUCTFIELD"
>count</CODE
>) minus one.
After calling <CODE
CLASS="CONSTANT"
>VIDIOC_QUERYBUF</CODE
> with a pointer to
this structure drivers return an error code or fill the rest of
the structure.</P
><P
>In the <CODE
CLASS="STRUCTFIELD"
>flags</CODE
> field the
<CODE
CLASS="CONSTANT"
>V4L2_BUF_FLAG_MAPPED</CODE
>,
<CODE
CLASS="CONSTANT"
>V4L2_BUF_FLAG_QUEUED</CODE
> and
<CODE
CLASS="CONSTANT"
>V4L2_BUF_FLAG_DONE</CODE
> flags will be valid. The
<CODE
CLASS="STRUCTFIELD"
>memory</CODE
> field will be set to
<CODE
CLASS="CONSTANT"
>V4L2_MEMORY_MMAP</CODE
>, the <CODE
CLASS="STRUCTFIELD"
>m.offset</CODE
>
contains the offset of the buffer from the start of the device memory,
the <CODE
CLASS="STRUCTFIELD"
>length</CODE
> field its size. The driver may
or may not set the remaining fields and flags, they are meaningless in
this context.</P
><P
>The <CODE
CLASS="STRUCTNAME"
>v4l2_buffer</CODE
> structure is
specified in <A
HREF="#BUFFER"
>Section 3.5</A
>.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN8555"
></A
><H2
>Return Value</H2
><P
>On success <SPAN
CLASS="RETURNVALUE"
>0</SPAN
> is returned, on
error <SPAN
CLASS="RETURNVALUE"
>-1</SPAN
> and <VAR
CLASS="VARNAME"
>errno</VAR
> is
set appropriately:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
></DT
><DD
><P
>The buffer <CODE
CLASS="STRUCTFIELD"
>type</CODE
> is not
supported, or the <CODE
CLASS="STRUCTFIELD"
>index</CODE
> is out of bounds.</P
></DD
></DL
></DIV
></DIV
><H1
><A
NAME="VIDIOC-QUERYCAP"
></A
>ioctl VIDIOC_QUERYCAP</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN8570"
></A
><H2
>Name</H2
>ioctl VIDIOC_QUERYCAP -- Query device capabilities</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN8573"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN8574"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, struct v4l2_capability *argp);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN8584"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><VAR
CLASS="PARAMETER"
>fd</VAR
></DT
><DD
><P
>File descriptor returned by <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
>.</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>request</VAR
></DT
><DD
><P
>VIDIOC_QUERYCAP</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>argp</VAR
></DT
><DD
><P
></P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN8604"
></A
><H2
>Description</H2
><P
>All V4L2 devices support the
<CODE
CLASS="CONSTANT"
>VIDIOC_QUERYCAP</CODE
> ioctl. It is used to identify
kernel devices compatible with this specification and to obtain
information about individual hardware capabilities. The ioctl takes a
pointer to a struct <A
HREF="#V4L2-CAPABILITY"
>v4l2_capability</A
> which is filled by the driver. When the
driver is not compatible with this specification the ioctl returns the
<SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code.</P
><DIV
CLASS="TABLE"
><A
NAME="V4L2-CAPABILITY"
></A
><P
><B
>Table 1. struct <CODE
CLASS="STRUCTNAME"
>v4l2_capability</CODE
></B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="25%"
TITLE="C1"><COL
WIDTH="25%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
>__u8</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>driver</CODE
>[16]</TD
><TD
><P
>Name of the driver, a unique NUL-terminated
ASCII string. For example: "bttv". Driver specific applications shall
use this information to verify the driver identity. It is also useful
to work around known bugs, or to print the driver name and version in
an error report to aid debugging. The driver version is stored in the
<CODE
CLASS="STRUCTFIELD"
>version</CODE
> field. [do we need a registry?]For
example: "bttv". Driver specific applications shall use this
information to verify the driver identity. It is also useful to work
around known bugs, or to print the driver name and version in an error
report to aid debugging. The driver version is stored in the
<CODE
CLASS="STRUCTFIELD"
>version</CODE
> field. [Do we need a
registry?]</P
><P
>Note storing strings in fixed sized arrays is
bad practice but unavoidable here. Drivers and applications should take
precautions to never read or write beyond the array end and to
properly terminate the strings.</P
></TD
></TR
><TR
><TD
>__u8</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>card</CODE
>[32]</TD
><TD
>Name of the device, a NUL-terminated ASCII
string. For example: "Yoyodyne TV/FM". Remember that one driver may
support different brands or models of video hardware. This information
can be used to build a menu of available devices for a device-select
user interface. Since drivers may support multiple installed devices
this name should be combined with the
<CODE
CLASS="STRUCTFIELD"
>bus_info</CODE
> string to avoid
ambiguities.</TD
></TR
><TR
><TD
>__u8</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>bus_info</CODE
>[32]</TD
><TD
>Location of the device in the system, a
NUL-terminated ASCII string. For example: "PCI Slot 4". This
information is intended for the user, to distinguish multiple
identical devices. If no such information is available the field may
simply count the devices controlled by the driver, or contain the
empty string (<CODE
CLASS="STRUCTFIELD"
>bus_info</CODE
>[0] = 0). [pci_dev->slot_name example].</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>version</CODE
></TD
><TD
><P
>Version number of the driver. Together with
the <CODE
CLASS="STRUCTFIELD"
>driver</CODE
> field this identifies a
particular driver. The version number is formatted using the
<CODE
CLASS="CONSTANT"
>KERNEL_VERSION()</CODE
> macro:</P
></TD
></TR
><TR
><TD
COLSPAN="3"
><P
><PRE
CLASS="PROGRAMLISTING"
>#define KERNEL_VERSION(a,b,c) (((a) << 16) + ((b) << 8) + (c))
__u32 version = KERNEL_VERSION(0, 8, 1);
printf ("Version: %u.%u.%u\n",
(version >> 16) & 0xFF,
(version >> 8) & 0xFF,
version & 0xFF);</PRE
></P
></TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>capabilities</CODE
></TD
><TD
>Device capabilities, see <A
HREF="#DEVICE-CAPABILITIES"
>Table 2</A
>.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>reserved</CODE
>[4]</TD
><TD
>Reserved for future extensions. Drivers must set
this array to zero.</TD
></TR
></TBODY
></TABLE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="DEVICE-CAPABILITIES"
></A
><P
><B
>Table 2. Device Capabilities Flags</B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="38%"
TITLE="C1"><COL
WIDTH="12%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CAP_VIDEO_CAPTURE</CODE
></TD
><TD
>0x00000001</TD
><TD
>The device supports the <A
HREF="#CAPTURE"
>video capture</A
> interface.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CAP_VIDEO_OUTPUT</CODE
></TD
><TD
>0x00000002</TD
><TD
>The device supports the <A
HREF="#OUTPUT"
>video output</A
> interface.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CAP_VIDEO_OVERLAY</CODE
></TD
><TD
>0x00000004</TD
><TD
>The device supports the <A
HREF="#OVERLAY"
>video overlay</A
> interface. Overlay typically
stores captured images directly in the video memory of a graphics
card, with support for clipping.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CAP_VBI_CAPTURE</CODE
></TD
><TD
>0x00000010</TD
><TD
>The device supports the VBI capture interface, see
<A
HREF="#RAW-VBI"
>Section 4.6</A
>, <A
HREF="#SLICED"
>Section 4.7</A
>.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CAP_VBI_OUTPUT</CODE
></TD
><TD
>0x00000020</TD
><TD
>The device supports the VBI output interface,
see <A
HREF="#RAW-VBI"
>Section 4.6</A
>, <A
HREF="#SLICED"
>Section 4.7</A
>.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CAP_RDS_CAPTURE</CODE
></TD
><TD
>0x00000100</TD
><TD
>[to be defined]</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CAP_TUNER</CODE
></TD
><TD
>0x00010000</TD
><TD
>The device has some sort of tuner or modulator to
receive or emit RF-modulated video signals. For more information see
<A
HREF="#TUNER"
>Section 1.6</A
>.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CAP_AUDIO</CODE
></TD
><TD
>0x00020000</TD
><TD
>The device has audio inputs or outputs. For more
information see <A
HREF="#AUDIO"
>Section 1.5</A
>. It may or may not support PCM
sampling or output, this function must be implemented as ALSA or OSS
PCM interface.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CAP_READWRITE</CODE
></TD
><TD
>0x01000000</TD
><TD
>The device supports the <A
HREF="#RW"
>read()
and/or write()</A
> I/O methods.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CAP_ASYNCIO</CODE
></TD
><TD
>0x02000000</TD
><TD
>The device supports the <A
HREF="#ASYNC"
>asynchronous</A
> I/O methods.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CAP_STREAMING</CODE
></TD
><TD
>0x04000000</TD
><TD
>The device supports the <A
HREF="#MMAP"
>streaming</A
> I/O method.</TD
></TR
></TBODY
></TABLE
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN8738"
></A
><H2
>Return Value</H2
><P
>On success <SPAN
CLASS="RETURNVALUE"
>0</SPAN
> is returned, on
error <SPAN
CLASS="RETURNVALUE"
>-1</SPAN
> and <VAR
CLASS="VARNAME"
>errno</VAR
> is
set appropriately:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
></DT
><DD
><P
>The kernel device is not compatible with this
specification.</P
></DD
></DL
></DIV
></DIV
><H1
><A
NAME="VIDIOC-QUERYCTRL"
></A
>ioctl VIDIOC_QUERYCTRL, VIDIOC_QUERYMENU</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN8753"
></A
><H2
>Name</H2
>ioctl VIDIOC_QUERYCTRL, ioctl VIDIOC_QUERYMENU -- Enumerate controls and menu control items</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN8757"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN8758"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, struct v4l2_queryctrl *argp);</CODE
></P
><P
></P
></DIV
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN8768"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, struct v4l2_querymenu *argp);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN8778"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><VAR
CLASS="PARAMETER"
>fd</VAR
></DT
><DD
><P
>File descriptor returned by <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
>.</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>request</VAR
></DT
><DD
><P
>VIDIOC_QUERYCTRL, VIDIOC_QUERYMENU</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>argp</VAR
></DT
><DD
><P
></P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN8798"
></A
><H2
>Description</H2
><P
>To query the attributes of a control applications set the
<CODE
CLASS="STRUCTFIELD"
>id</CODE
> field of a struct <A
HREF="#V4L2-QUERYCTRL"
>v4l2_queryctrl</A
> and call the
<CODE
CLASS="CONSTANT"
>VIDIOC_QUERYCTRL</CODE
> ioctl with a pointer to this
structure. The driver fills the rest of the structure or returns an
<SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code when the <CODE
CLASS="STRUCTFIELD"
>id</CODE
> is invalid.</P
><P
>It is possible to enumerate controls by calling
<CODE
CLASS="CONSTANT"
>VIDIOC_QUERYCTRL</CODE
> with successive
<CODE
CLASS="STRUCTFIELD"
>id</CODE
> values starting from
<CODE
CLASS="CONSTANT"
>V4L2_CID_BASE</CODE
> up to and exclusive
<CODE
CLASS="CONSTANT"
>V4L2_CID_BASE_LASTP1</CODE
>, or starting from
<CODE
CLASS="CONSTANT"
>V4L2_CID_PRIVATE_BASE</CODE
> until the driver returns
<SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
>. When the
<CODE
CLASS="CONSTANT"
>V4L2_CTRL_FLAG_DISABLED</CODE
> flag is set in the
<CODE
CLASS="STRUCTFIELD"
>flags</CODE
> field, this control is permanently
disabled and should be ignored by the application.<A
NAME="AEN8815"
HREF="#FTN.AEN8815"
><SPAN
CLASS="footnote"
>[25]</SPAN
></A
></P
><P
>Additional information is required for menu controls, the
name of menu items. To query them applications set the
<CODE
CLASS="STRUCTFIELD"
>id</CODE
> and <CODE
CLASS="STRUCTFIELD"
>index</CODE
>
fields of struct <A
HREF="#V4L2-QUERYMENU"
>v4l2_querymenu</A
> and call the
<CODE
CLASS="CONSTANT"
>VIDIOC_QUERYMENU</CODE
> ioctl with a pointer to this
structure. The driver fills the rest of the structure or returns an
<SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code when the <CODE
CLASS="STRUCTFIELD"
>id</CODE
> or
<CODE
CLASS="STRUCTFIELD"
>index</CODE
> is invalid. Menu items are enumerated
by calling <CODE
CLASS="CONSTANT"
>VIDIOC_QUERYMENU</CODE
> with successive
<CODE
CLASS="STRUCTFIELD"
>index</CODE
> values from struct <A
HREF="#V4L2-QUERYCTRL"
>v4l2_queryctrl</A
>
<CODE
CLASS="STRUCTFIELD"
>minimum</CODE
> (0) to
<CODE
CLASS="STRUCTFIELD"
>maximum</CODE
>, inclusive.</P
><DIV
CLASS="TABLE"
><A
NAME="V4L2-QUERYCTRL"
></A
><P
><B
>Table 1. struct <CODE
CLASS="STRUCTNAME"
>v4l2_queryctrl</CODE
></B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="25%"
TITLE="C1"><COL
WIDTH="25%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>id</CODE
></TD
><TD
>Identifies the control, set by the application.
See <A
HREF="#CONTROL-ID"
>Table 1-1</A
> for predefined IDs.</TD
></TR
><TR
><TD
>enum <A
HREF="#V4L2-CTRL-TYPE"
>v4l2_ctrl_type</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>type</CODE
></TD
><TD
>Type of control, see <A
HREF="#V4L2-CTRL-TYPE"
>Table 3</A
>.</TD
></TR
><TR
><TD
>__u8</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>name</CODE
>[32]</TD
><TD
>Name of the control, a NUL-terminated ASCII
string. This information is intended for the user.</TD
></TR
><TR
><TD
>__s32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>minimum</CODE
></TD
><TD
>Minimum value, inclusive. This field is mostly
useful to define a lower bound for integer controls. Note the value is
signed.</TD
></TR
><TR
><TD
>__s32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>maximum</CODE
></TD
><TD
>Maximum value, inclusive. Note the value is
signed.</TD
></TR
><TR
><TD
>__s32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>step</CODE
></TD
><TD
><P
>Generally drivers should not scale hardware
control values. It may be necessary for example when the
<CODE
CLASS="STRUCTFIELD"
>name</CODE
> or <CODE
CLASS="STRUCTFIELD"
>id</CODE
> imply
a particular unit and the hardware actually accepts only multiples of
said unit. If so, drivers must take care values are properly rounded
when scaling, such that errors will not accumulate on repeated
read-write cycles.</P
><P
>This field reports the smallest change
of an integer control actually affecting hardware. Often the
information is needed when the user can change controls by keyboard or
GUI buttons, rather than a slider. When for example a hardware
register accepts values 0-511 and the driver reports 0-65535, step
should be 128.</P
><P
>Note although signed, the step value is
supposed to be always positive.</P
></TD
></TR
><TR
><TD
>__s32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>default_value</CODE
></TD
><TD
>The default value of the control. Drivers reset
controls only when the driver is loaded, not later, in particular not
when the <CODE
CLASS="FUNCTION"
>open()</CODE
> is called.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>flags</CODE
></TD
><TD
>Control flags, see <A
HREF="#CONTROL-FLAGS"
>Table 4</A
>.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>reserved</CODE
>[2]</TD
><TD
>Reserved for future extensions. Drivers must set
the array to zero.</TD
></TR
></TBODY
></TABLE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="V4L2-QUERYMENU"
></A
><P
><B
>Table 2. struct <CODE
CLASS="STRUCTNAME"
>v4l2_querymenu</CODE
></B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="25%"
TITLE="C1"><COL
WIDTH="25%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>id</CODE
></TD
><TD
>Identifies the control, set by the application
from the respective struct <A
HREF="#V4L2-QUERYCTRL"
>v4l2_queryctrl</A
>
<CODE
CLASS="STRUCTFIELD"
>id</CODE
>.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>index</CODE
></TD
><TD
>Index of the menu item, starting at zero, set by
the application.</TD
></TR
><TR
><TD
>__u8</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>name</CODE
>[32]</TD
><TD
>Name of the menu item, a NUL-terminated ASCII
string. This information is intended for the user.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>reserved</CODE
></TD
><TD
>Reserved for future extensions. Drivers must set
the array to zero.</TD
></TR
></TBODY
></TABLE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="V4L2-CTRL-TYPE"
></A
><P
><B
>Table 3. enum v4l2_ctrl_type</B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="30%"><COL
WIDTH="5%"
ALIGN="CENTER"><COL
WIDTH="5%"
ALIGN="CENTER"><COL
WIDTH="5%"
ALIGN="CENTER"><COL
WIDTH="55%"><THEAD
><TR
><TH
>Type</TH
><TH
><CODE
CLASS="STRUCTFIELD"
>minimum</CODE
></TH
><TH
><CODE
CLASS="STRUCTFIELD"
>step</CODE
></TH
><TH
><CODE
CLASS="STRUCTFIELD"
>maximum</CODE
></TH
><TH
>Description</TH
></TR
></THEAD
><TBODY
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CTRL_TYPE_INTEGER</CODE
></TD
><TD
>low value</TD
><TD
>increment (positive) [__u32?]</TD
><TD
>high value</TD
><TD
>An integer-valued control ranging from minimum to
maximum inclusive. The step value indicates the increment between
values which are actually different on the hardware.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CTRL_TYPE_BOOLEAN</CODE
></TD
><TD
>0</TD
><TD
>1</TD
><TD
>1</TD
><TD
>A boolean-valued control. Zero corresponds to
"disabled", and one means "enabled".</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CTRL_TYPE_MENU</CODE
></TD
><TD
>0</TD
><TD
>1</TD
><TD
>N-1</TD
><TD
>The control has a menu of N choices. The names of
the menu items can be enumerated with the
<CODE
CLASS="CONSTANT"
>VIDIOC_QUERYMENU</CODE
> ioctl.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CTRL_TYPE_BUTTON</CODE
></TD
><TD
>0</TD
><TD
>0</TD
><TD
>0</TD
><TD
>A control which performs an action when set.
Drivers must ignore the value passed with
<CODE
CLASS="CONSTANT"
>VIDIOC_S_CTRL</CODE
> and return an <SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code on a
<CODE
CLASS="CONSTANT"
>VIDIOC_G_CTRL</CODE
> attempt.</TD
></TR
></TBODY
></TABLE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="CONTROL-FLAGS"
></A
><P
><B
>Table 4. Control Flags</B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="38%"
TITLE="C1"><COL
WIDTH="12%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CTRL_FLAG_DISABLED</CODE
></TD
><TD
>0x0001</TD
><TD
>This control is permanently disabled and should be ignored by the application. An attempt to change
this control results in an <SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CTRL_FLAG_GRABBED</CODE
></TD
><TD
>0x0002</TD
><TD
>This control is temporarily unchangeable, for
example because another application took over control of the
respective resource. Such controls may be displayed specially in a
user interface. An attempt to change a "grabbed" control results in an
<SPAN
CLASS="ERRORCODE"
>EBUSY</SPAN
> error code.</TD
></TR
></TBODY
></TABLE
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN8997"
></A
><H2
>Return Value</H2
><P
>On success <SPAN
CLASS="RETURNVALUE"
>0</SPAN
> is returned, on
error <SPAN
CLASS="RETURNVALUE"
>-1</SPAN
> and <VAR
CLASS="VARNAME"
>errno</VAR
> is
set appropriately:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
></DT
><DD
><P
>The struct <A
HREF="#V4L2-QUERYCTRL"
>v4l2_queryctrl</A
> <CODE
CLASS="STRUCTFIELD"
>id</CODE
>
is invalid. The struct <A
HREF="#V4L2-QUERYMENU"
>v4l2_querymenu</A
> <CODE
CLASS="STRUCTFIELD"
>id</CODE
> or
<CODE
CLASS="STRUCTFIELD"
>index</CODE
> is invalid.</P
></DD
></DL
></DIV
></DIV
><H1
><A
NAME="VIDIOC-QUERYSTD"
></A
>ioctl VIDIOC_QUERYSTD</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN9015"
></A
><H2
>Name</H2
>ioctl VIDIOC_QUERYSTD -- Sense the video standard received by the current input</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN9018"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN9019"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, v4l2_std_id *argp);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN9029"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><VAR
CLASS="PARAMETER"
>fd</VAR
></DT
><DD
><P
>File descriptor returned by <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
>.</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>request</VAR
></DT
><DD
><P
>VIDIOC_QUERYSTD</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>argp</VAR
></DT
><DD
><P
></P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN9049"
></A
><H2
>Description</H2
><P
>The hardware may be able to detect the current video
standard automatically. To do so, applications call <CODE
CLASS="CONSTANT"
>VIDIOC_QUERYSTD</CODE
> with a pointer to a <A
HREF="#V4L2-STD-ID"
>v4l2_std_id</A
> type. The
driver stores here a set of candidates, this can be a single flag or a
set of supported standards if for example the hardware can only
distinguish between 50 and 60 Hz systems. When detection is not
possible or fails, the set must contain all standards supported by the
current video input or output.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN9054"
></A
><H2
>Return Value</H2
><P
>On success <SPAN
CLASS="RETURNVALUE"
>0</SPAN
> is returned, on
error <SPAN
CLASS="RETURNVALUE"
>-1</SPAN
> and <VAR
CLASS="VARNAME"
>errno</VAR
> is
set appropriately:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
></DT
><DD
><P
>This ioctl is not supported.</P
></DD
></DL
></DIV
></DIV
><H1
><A
NAME="VIDIOC-REQBUFS"
></A
>ioctl VIDIOC_REQBUFS</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN9067"
></A
><H2
>Name</H2
>ioctl VIDIOC_REQBUFS -- Initiate Memory Mapping or User Pointer I/O</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN9070"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN9071"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, struct v4l2_requestbuffers *argp);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN9081"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><VAR
CLASS="PARAMETER"
>fd</VAR
></DT
><DD
><P
>File descriptor returned by <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
>.</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>request</VAR
></DT
><DD
><P
>VIDIOC_REQBUFS</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>argp</VAR
></DT
><DD
><P
></P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN9101"
></A
><H2
>Description</H2
><P
>This ioctl is used to initiate <A
HREF="#MMAP"
>memory
mapped</A
> or <A
HREF="#USERP"
>user pointer</A
>
I/O. Memory mapped buffers are located in device memory and must be
allocated with this ioctl before they can be mapped into the
application's address space. User buffers are allocated by
applications themselves, and this ioctl is merely used to switch the
driver into user pointer I/O mode.</P
><P
>To allocate device buffers applications initialize three
fields of a <CODE
CLASS="STRUCTNAME"
>v4l2_requestbuffers</CODE
> structure.
They set the <CODE
CLASS="STRUCTFIELD"
>type</CODE
> field to the respective
stream or buffer type, the <CODE
CLASS="STRUCTFIELD"
>count</CODE
> field to
the desired number of buffers, and <CODE
CLASS="STRUCTFIELD"
>memory</CODE
>
must be set to <CODE
CLASS="CONSTANT"
>V4L2_MEMORY_MMAP</CODE
>. When the ioctl
is called with a pointer to this structure the driver attempts to
allocate the requested number of buffers and stores the actual number
allocated in the <CODE
CLASS="STRUCTFIELD"
>count</CODE
> field. It can be
smaller than the number requested, even zero, when the driver runs out
of free memory. A larger number is possible when the driver requires
more buffers to function correctly.<A
NAME="AEN9113"
HREF="#FTN.AEN9113"
><SPAN
CLASS="footnote"
>[26]</SPAN
></A
> When memory mapping I/O is not supported the ioctl
returns an <SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code.</P
><P
>Applications can call <CODE
CLASS="CONSTANT"
>VIDIOC_REQBUFS</CODE
>
again to change the number of buffers, however this cannot succeed
when any buffers are still mapped. A <CODE
CLASS="STRUCTFIELD"
>count</CODE
>
value of zero frees all buffers, after aborting or finishing any DMA
in progress, an implicit <A
HREF="#VIDIOC-STREAMON"
><CODE
CLASS="CONSTANT"
>VIDIOC_STREAMOFF</CODE
></A
>. </P
><P
>To negotiate user pointer I/O, applications initialize only
the <CODE
CLASS="STRUCTFIELD"
>type</CODE
> field and set
<CODE
CLASS="STRUCTFIELD"
>memory</CODE
> to
<CODE
CLASS="CONSTANT"
>V4L2_MEMORY_USERPTR</CODE
>. When the ioctl is called
with a pointer to this structure the driver prepares for user pointer
I/O, when this I/O method is not supported the ioctl returns an
<SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code.</P
><DIV
CLASS="TABLE"
><A
NAME="V4L2-REQUESTBUFFERS"
></A
><P
><B
>Table 1. struct <CODE
CLASS="STRUCTNAME"
>v4l2_requestbuffers</CODE
></B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="25%"
TITLE="C1"><COL
WIDTH="25%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>count</CODE
></TD
><TD
>The number of buffers requested or granted. This
field is only used when <CODE
CLASS="STRUCTFIELD"
>memory</CODE
> is set to
<CODE
CLASS="CONSTANT"
>V4L2_MEMORY_MMAP</CODE
>.</TD
></TR
><TR
><TD
>enum <A
HREF="#V4L2-BUF-TYPE"
>v4l2_buf_type</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>type</CODE
></TD
><TD
>Type of the stream or buffers, this is the same
as the struct <A
HREF="#V4L2-FORMAT"
>v4l2_format</A
> <CODE
CLASS="STRUCTFIELD"
>type</CODE
> field. See <A
HREF="#V4L2-BUF-TYPE"
>Table 3-2</A
> for valid values.</TD
></TR
><TR
><TD
>enum <A
HREF="#V4L2-MEMORY"
>v4l2_memory</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>memory</CODE
></TD
><TD
>Applications set this field to
<CODE
CLASS="CONSTANT"
>V4L2_MEMORY_MMAP</CODE
> or
<CODE
CLASS="CONSTANT"
>V4L2_MEMORY_USERPTR</CODE
>.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>reserved</CODE
>[32]</TD
><TD
>A place holder for future extensions and custom
(driver defined) buffer types <CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_PRIVATE</CODE
> and
higher.</TD
></TR
></TBODY
></TABLE
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN9165"
></A
><H2
>Return Value</H2
><P
>On success <SPAN
CLASS="RETURNVALUE"
>0</SPAN
> is returned, on
error <SPAN
CLASS="RETURNVALUE"
>-1</SPAN
> and <VAR
CLASS="VARNAME"
>errno</VAR
> is
set appropriately:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="ERRORCODE"
>EBUSY</SPAN
></DT
><DD
><P
>The driver supports multiple opens and I/O is already
in progress, or reallocation of buffers was attempted although one or
more are still mapped.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
></DT
><DD
><P
>The buffer type (<CODE
CLASS="STRUCTFIELD"
>type</CODE
> field) or the
requested I/O method (<CODE
CLASS="STRUCTFIELD"
>memory</CODE
>) is not
supported.</P
></DD
></DL
></DIV
></DIV
><H1
><A
NAME="VIDIOC-STREAMON"
></A
>ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN9187"
></A
><H2
>Name</H2
>ioctl VIDIOC_STREAMON, ioctl VIDIOC_STREAMOFF -- Start or stop streaming I/O.</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN9191"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN9192"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, const int *argp);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN9202"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><VAR
CLASS="PARAMETER"
>fd</VAR
></DT
><DD
><P
>File descriptor returned by <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
>.</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>request</VAR
></DT
><DD
><P
>VIDIOC_STREAMON, VIDIOC_STREAMOFF</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>argp</VAR
></DT
><DD
><P
></P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN9222"
></A
><H2
>Description</H2
><P
>The <CODE
CLASS="CONSTANT"
>VIDIOC_STREAMON</CODE
> and
<CODE
CLASS="CONSTANT"
>VIDIOC_STREAMOFF</CODE
> ioctl start and stop the capture
or output process during streaming (<A
HREF="#MMAP"
>memory
mapping</A
> or <A
HREF="#USERP"
>user pointer</A
>) I/O.</P
><P
>Specifically the capture hardware is disabled and no input
buffers are filled (if there are any empty buffers in the incoming
queue) until <CODE
CLASS="CONSTANT"
>VIDIOC_STREAMON</CODE
> has been called.
Accordingly the output hardware is disabled, no video signal is
produced until <CODE
CLASS="CONSTANT"
>VIDIOC_STREAMON</CODE
> has been called.
The ioctl will succeed only when at least one output buffer is in the
incoming queue.</P
><P
>The <CODE
CLASS="CONSTANT"
>VIDIOC_STREAMOFF</CODE
> ioctl, apart of
aborting or finishing any DMA in progress, unlocks any user pointer
buffers locked in physical memory, and it removes all buffers from the
incoming and outgoing queues. That means all images captured but not
dequeued yet will be lost, likewise all images enqueued for output but
not transmitted yet. I/O returns to the same state as after calling
<A
HREF="#VIDIOC-REQBUFS"
><CODE
CLASS="CONSTANT"
>VIDIOC_REQBUFS</CODE
></A
> and can be restarted accordingly.</P
><P
>Both ioctls take a pointer to an integer, the desired buffer or
stream type. This is the same as struct <A
HREF="#V4L2-REQUESTBUFFERS"
>v4l2_requestbuffers</A
>
<CODE
CLASS="STRUCTFIELD"
>type</CODE
>.</P
><P
>Note applications can be preempted for unknown periods right
before or after the <CODE
CLASS="CONSTANT"
>VIDIOC_STREAMON</CODE
> or
<CODE
CLASS="CONSTANT"
>VIDIOC_STREAMOFF</CODE
> calls, there is no notion of
starting or stopping "now". Buffer timestamps can be used to
synchronize with other events.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN9242"
></A
><H2
>Return Value</H2
><P
>On success <SPAN
CLASS="RETURNVALUE"
>0</SPAN
> is returned, on
error <SPAN
CLASS="RETURNVALUE"
>-1</SPAN
> and <VAR
CLASS="VARNAME"
>errno</VAR
> is
set appropriately:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
></DT
><DD
><P
>Streaming I/O is not supported, the buffer
<CODE
CLASS="STRUCTFIELD"
>type</CODE
> is not supported, or no buffers have
been allocated (memory mapping) or enqueued (output) yet.</P
></DD
></DL
></DIV
></DIV
><H1
><A
NAME="FUNC-MMAP"
></A
>mmap</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN9256"
></A
><H2
>Name</H2
>mmap -- Map device memory into application address space</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN9259"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN9260"
></A
><PRE
CLASS="FUNCSYNOPSISINFO"
>#include <unistd.h>
#include <sys/mman.h></PRE
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void *mmap</CODE
>(void *start, size_t length, int prot, int flags, int fd, off_t offset);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN9277"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><VAR
CLASS="PARAMETER"
>start</VAR
></DT
><DD
><P
>Map the buffer to this address in the
application's address space. When the <CODE
CLASS="CONSTANT"
>MAP_FIXED</CODE
>
flag is specified, <VAR
CLASS="PARAMETER"
>start</VAR
> 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 <CODE
CLASS="CONSTANT"
>NULL</CODE
> pointer here.</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>length</VAR
></DT
><DD
><P
>Length of the memory area to map. This must be the
same value as returned by the driver in the struct <A
HREF="#V4L2-BUFFER"
>v4l2_buffer</A
>
<CODE
CLASS="STRUCTFIELD"
>length</CODE
> field.</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>prot</VAR
></DT
><DD
><P
>The <VAR
CLASS="PARAMETER"
>prot</VAR
> argument describes the
desired memory protection. It must be set to
<CODE
CLASS="CONSTANT"
>PROT_READ</CODE
> | <CODE
CLASS="CONSTANT"
>PROT_WRITE</CODE
>,
indicating pages may be read and written. This is a technicality
independent of the
device type and direction of data exchange. Note device memory
accesses may incur a performance penalty. It can happen when writing
to capture buffers, when reading from output buffers, or always. When
the application intends to modify buffers, other I/O methods may be
more efficient.</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>flags</VAR
></DT
><DD
><P
>The <VAR
CLASS="PARAMETER"
>flags</VAR
> 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.</P
><P
><CODE
CLASS="CONSTANT"
>MAP_FIXED</CODE
> requests that the
driver selects no other address than the one specified. If the
specified address cannot be used, mmap will fail. If
<CODE
CLASS="CONSTANT"
>MAP_FIXED</CODE
> is specified,
<VAR
CLASS="PARAMETER"
>start</VAR
> must be a multiple of the pagesize. Use
of this option is discouraged.</P
><P
>One of the <CODE
CLASS="CONSTANT"
>MAP_SHARED</CODE
> or
<CODE
CLASS="CONSTANT"
>MAP_PRIVATE</CODE
> flags must be set.
<CODE
CLASS="CONSTANT"
>MAP_SHARED</CODE
> allows to share this mapping with all
other processes that map this object. <CODE
CLASS="CONSTANT"
>MAP_PRIVATE</CODE
>
requests copy-on-write semantics. We recommend to set
<CODE
CLASS="CONSTANT"
>MAP_SHARED</CODE
>. The <CODE
CLASS="CONSTANT"
>MAP_PRIVATE</CODE
>,
<CODE
CLASS="CONSTANT"
>MAP_DENYWRITE</CODE
>,
<CODE
CLASS="CONSTANT"
>MAP_EXECUTABLE</CODE
> and <CODE
CLASS="CONSTANT"
>MAP_ANON</CODE
>
flags should not be set.</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>fd</VAR
></DT
><DD
><P
>File descriptor returned by <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
>.</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>offset</VAR
></DT
><DD
><P
>Offset of the buffer in device memory. This must be the
same value as returned by the driver in the struct <A
HREF="#V4L2-BUFFER"
>v4l2_buffer</A
>
<CODE
CLASS="STRUCTFIELD"
>m</CODE
> union <CODE
CLASS="STRUCTFIELD"
>offset</CODE
> field.</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN9338"
></A
><H2
>Description</H2
><P
>The <CODE
CLASS="FUNCTION"
>mmap()</CODE
> function asks to map
<VAR
CLASS="PARAMETER"
>length</VAR
> bytes starting at
<VAR
CLASS="PARAMETER"
>offset</VAR
> in the memory of the device specified by
<VAR
CLASS="PARAMETER"
>fd</VAR
> into the application address space,
preferably at address <VAR
CLASS="PARAMETER"
>start</VAR
>. This latter
address is a hint only, and is usually specified as 0.</P
><P
>Suitable length and offset parameters are queried with the
<A
HREF="#VIDIOC-QUERYBUF"
><CODE
CLASS="CONSTANT"
>VIDIOC_QUERYBUF</CODE
></A
> ioctl. Buffers must be allocated with the
<A
HREF="#VIDIOC-REQBUFS"
><CODE
CLASS="CONSTANT"
>VIDIOC_REQBUFS</CODE
></A
> ioctl before they can be queried.</P
><P
>To unmap buffers the <A
HREF="#FUNC-MUNMAP"
><CODE
CLASS="FUNCTION"
>munmap()</CODE
></A
> function is used.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN9354"
></A
><H2
>Return Value</H2
><P
>On success, <CODE
CLASS="FUNCTION"
>mmap()</CODE
> returns a pointer to
the mapped buffer. On error, <CODE
CLASS="CONSTANT"
>MAP_FAILED</CODE
> (-1) is
returned, and <VAR
CLASS="VARNAME"
>errno</VAR
> is set appropriately. Possible
error codes:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="ERRORCODE"
>EBADF</SPAN
></DT
><DD
><P
><VAR
CLASS="PARAMETER"
>fd</VAR
> is not a valid file
descriptor.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>EACCESS</SPAN
></DT
><DD
><P
><VAR
CLASS="PARAMETER"
>fd</VAR
> is
not open for reading and writing.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
></DT
><DD
><P
>The <VAR
CLASS="PARAMETER"
>start</VAR
> or
<VAR
CLASS="PARAMETER"
>length</VAR
> or <VAR
CLASS="PARAMETER"
>offset</VAR
> are not
suitable. (E.g., they are too large, or not aligned on a
<CODE
CLASS="CONSTANT"
>PAGESIZE</CODE
> boundary.) Or no buffers have been
allocated with the <A
HREF="#VIDIOC-REQBUFS"
><CODE
CLASS="CONSTANT"
>VIDIOC_REQBUFS</CODE
></A
> ioctl.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>ENOMEM</SPAN
></DT
><DD
><P
>No memory is available.</P
></DD
></DL
></DIV
></DIV
><H1
><A
NAME="FUNC-MUNMAP"
></A
>munmap</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN9390"
></A
><H2
>Name</H2
>munmap -- Unmap device memory</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN9393"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN9394"
></A
><PRE
CLASS="FUNCSYNOPSISINFO"
>#include <unistd.h>
#include <sys/mman.h></PRE
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int munmap</CODE
>(void *start, size_t length);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN9403"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><VAR
CLASS="PARAMETER"
>start</VAR
></DT
><DD
><P
>Address of the mapped buffer as returned by the
<A
HREF="#FUNC-MMAP"
><CODE
CLASS="FUNCTION"
>mmap()</CODE
></A
> function.</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>length</VAR
></DT
><DD
><P
>Length of the mapped buffer. This must be the same
value as given to <CODE
CLASS="FUNCTION"
>mmap()</CODE
> and returned by the
driver in the struct <A
HREF="#V4L2-BUFFER"
>v4l2_buffer</A
> <CODE
CLASS="STRUCTFIELD"
>length</CODE
>
field.</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN9421"
></A
><H2
>Description</H2
><P
>Unmaps a previously with the <A
HREF="#FUNC-MMAP"
><CODE
CLASS="FUNCTION"
>mmap()</CODE
></A
> function mapped
buffer and frees it, if possible. </P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN9426"
></A
><H2
>Return Value</H2
><P
>On success <CODE
CLASS="FUNCTION"
>munmap()</CODE
> returns 0, on
failure -1, and errno is set.</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
></DT
><DD
><P
>The <VAR
CLASS="PARAMETER"
>start</VAR
> or
<VAR
CLASS="PARAMETER"
>length</VAR
> is incorrect, or no buffers have been
mapped yet.</P
></DD
></DL
></DIV
></DIV
><H1
><A
NAME="FUNC-OPEN"
></A
>open</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN9439"
></A
><H2
>Name</H2
>open -- Open a V4L2 device</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN9442"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN9443"
></A
><PRE
CLASS="FUNCSYNOPSISINFO"
>#include <fcntl.h></PRE
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int open</CODE
>(const char *device_name, int flags);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN9452"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><VAR
CLASS="PARAMETER"
>device_name</VAR
></DT
><DD
><P
>Device to be opened.</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>flags</VAR
></DT
><DD
><P
>Open flags. Access mode must be
<CODE
CLASS="CONSTANT"
>O_RDWR</CODE
>. This is just a technicality, input devices
still support only reading and output devices only writing.</P
><P
>When the <CODE
CLASS="CONSTANT"
>O_NONBLOCK</CODE
> flag is
given, the read() function and the <A
HREF="#VIDIOC-QBUF"
><CODE
CLASS="CONSTANT"
>VIDIOC_DQBUF</CODE
></A
> ioctl will return
the <SPAN
CLASS="ERRORCODE"
>EAGAIN</SPAN
> error code 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 <CODE
CLASS="CONSTANT"
>O_NONBLOCK</CODE
> flag.</P
><P
>Other flags have no effect.</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN9473"
></A
><H2
>Description</H2
><P
>To open a V4L2 device applications call
<CODE
CLASS="FUNCTION"
>open()</CODE
> 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 <CODE
CLASS="FUNCTION"
>open()</CODE
> call after loading the driver
they will be reset to default values, drivers are never in an
undefined state.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN9478"
></A
><H2
>Return Value</H2
><P
>On success <CODE
CLASS="FUNCTION"
>open</CODE
> returns the new
file descriptor. On error -1 is returned, and <VAR
CLASS="VARNAME"
>errno</VAR
>
is set appropriately. Possible error codes:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="ERRORCODE"
>EACCES</SPAN
></DT
><DD
><P
>The caller has no permission to access the
device.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>EBUSY</SPAN
></DT
><DD
><P
>The driver does not support multiple opens and the
device is already in use.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>ENXIO</SPAN
></DT
><DD
><P
>No device corresponding to this device special file
exists.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>ENOMEM</SPAN
></DT
><DD
><P
>Insufficient kernel memory was available.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>EMFILE</SPAN
></DT
><DD
><P
>The process already has the maximum number of
files open.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>ENFILE</SPAN
></DT
><DD
><P
>The limit on the total number of files open on the
system has been reached.</P
></DD
></DL
></DIV
></DIV
><H1
><A
NAME="FUNC-POLL"
></A
>poll</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN9515"
></A
><H2
>Name</H2
>poll -- Wait for some event on a file descriptor</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN9518"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN9519"
></A
><PRE
CLASS="FUNCSYNOPSISINFO"
>#include <sys/poll.h></PRE
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int poll</CODE
>(struct pollfd *ufds, unsigned int nfds, int timeout);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN9530"
></A
><H2
>Description</H2
><P
>All drivers implementing the <CODE
CLASS="FUNCTION"
>read()</CODE
>
or <CODE
CLASS="FUNCTION"
>write()</CODE
> function or streaming I/O must also support the
<CODE
CLASS="FUNCTION"
>poll()</CODE
> function. See the
<CODE
CLASS="FUNCTION"
>poll()</CODE
> manual page for details.</P
></DIV
><H1
><A
NAME="FUNC-READ"
></A
>read</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN9538"
></A
><H2
>Name</H2
>read -- Read from a V4L2 device</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN9541"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN9542"
></A
><PRE
CLASS="FUNCSYNOPSISINFO"
>#include <unistd.h></PRE
><P
><CODE
><CODE
CLASS="FUNCDEF"
>ssize_t read</CODE
>(int fd, void *buf, size_t count);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN9553"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><VAR
CLASS="PARAMETER"
>fd</VAR
></DT
><DD
><P
>File descriptor returned by <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
>.</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>buf</VAR
></DT
><DD
><P
></P
></DD
><DT
><VAR
CLASS="PARAMETER"
>count</VAR
></DT
><DD
><P
></P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN9573"
></A
><H2
>Description</H2
><P
><CODE
CLASS="FUNCTION"
>read()</CODE
> attempts to read up to
<VAR
CLASS="PARAMETER"
>count</VAR
> bytes from file descriptor
<VAR
CLASS="PARAMETER"
>fd</VAR
> into the buffer starting at
<VAR
CLASS="PARAMETER"
>buf</VAR
>. The layout of the data in the buffer is
discussed in the respective device interface section, see ##. If <VAR
CLASS="PARAMETER"
>count</VAR
> is zero,
<CODE
CLASS="FUNCTION"
>read()</CODE
> returns zero and has no other results. If
<VAR
CLASS="PARAMETER"
>count</VAR
> is greater than
<CODE
CLASS="CONSTANT"
>SSIZE_MAX</CODE
>, the result is unspecified. Regardless
of the <VAR
CLASS="PARAMETER"
>count</VAR
> value each
<CODE
CLASS="FUNCTION"
>read()</CODE
> call will provide at most one frame (two
fields) worth of data.</P
><P
>By default <CODE
CLASS="FUNCTION"
>read()</CODE
> blocks until data
becomes available. When the <CODE
CLASS="CONSTANT"
>O_NONBLOCK</CODE
> flag was
given to the <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
> function it
returns immediately with an <SPAN
CLASS="ERRORCODE"
>EAGAIN</SPAN
> error code when no data is available. The
<A
HREF="#FUNC-SELECT"
><CODE
CLASS="FUNCTION"
>select()</CODE
></A
> or <A
HREF="#FUNC-POLL"
><CODE
CLASS="FUNCTION"
>poll()</CODE
></A
> functions
can always be used to suspend execution until data becomes available. All
drivers supporting the <CODE
CLASS="FUNCTION"
>read()</CODE
> function must also
support <CODE
CLASS="FUNCTION"
>select()</CODE
> and
<CODE
CLASS="FUNCTION"
>poll()</CODE
>.</P
><P
>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.</P
><P
><CODE
CLASS="FUNCTION"
>read()</CODE
> 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.</P
><P
>The behavior of
<CODE
CLASS="FUNCTION"
>read()</CODE
> 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 <CODE
CLASS="FUNCTION"
>read()</CODE
> call as
soon as it is complete.</P
><P
>A driver discarding the newest frames stops capturing until
the next <CODE
CLASS="FUNCTION"
>read()</CODE
> call. The frame being received at
<CODE
CLASS="FUNCTION"
>read()</CODE
> 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 <CODE
CLASS="FUNCTION"
>read()</CODE
> is called and returning when
the DMA finished.</P
><P
>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.</P
><P
>Applications can get and set the number of buffers used
internally by the driver with the streaming parameter ioctls, see
##streaming-par. They
are optional, however. The discarding policy is not reported and
cannot be changed. For minimum requirements see the respective device
interface section in ##.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN9611"
></A
><H2
>Return Value</H2
><P
>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 <CODE
CLASS="FUNCTION"
>read()</CODE
> was interrupted
by a signal. On error, -1 is returned, and <VAR
CLASS="VARNAME"
>errno</VAR
>
is set appropriately. In this case the next read will start at the
beginning of a new frame. Possible error codes:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="ERRORCODE"
>EAGAIN</SPAN
></DT
><DD
><P
>Non-blocking I/O has been selected using
O_NONBLOCK and no data was immediately available for reading.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>EBADF</SPAN
></DT
><DD
><P
><VAR
CLASS="PARAMETER"
>fd</VAR
> is not a valid file
descriptor or is not open for reading, or the process already has the
maximum number of files open.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>EBUSY</SPAN
></DT
><DD
><P
>The driver does not support multiple read streams and the
device is already in use.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>EFAULT</SPAN
></DT
><DD
><P
><VAR
CLASS="PARAMETER"
>buf</VAR
> is outside your
accessible address space.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>EINTR</SPAN
></DT
><DD
><P
>The call was interrupted by a signal before any
data was read.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>EIO</SPAN
></DT
><DD
><P
>I/O error. This indicates some hardware problem or a
failure to communicate with a remote device (USB camera etc.).</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
></DT
><DD
><P
>The <CODE
CLASS="FUNCTION"
>read()</CODE
> function is not
supported by this driver, not on this device, or generally not on this
type of device.</P
></DD
></DL
></DIV
></DIV
><H1
><A
NAME="FUNC-SELECT"
></A
>select</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN9656"
></A
><H2
>Name</H2
>select -- Synchronous I/O multiplexing</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN9659"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN9660"
></A
><PRE
CLASS="FUNCSYNOPSISINFO"
>#include <sys/time.h>
#include <sys/types.h>
#include <unistd.h></PRE
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int select</CODE
>(int n, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN9675"
></A
><H2
>Description</H2
><P
>All drivers implementing the <CODE
CLASS="FUNCTION"
>read()</CODE
>
or <CODE
CLASS="FUNCTION"
>write()</CODE
> function or streaming I/O must also support the
<CODE
CLASS="FUNCTION"
>select()</CODE
> function. See the
<CODE
CLASS="FUNCTION"
>select()</CODE
> manual page for details.</P
></DIV
><H1
><A
NAME="FUNC-WRITE"
></A
>write</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN9683"
></A
><H2
>Name</H2
>write -- Write to a V4L2 device</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN9686"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN9687"
></A
><PRE
CLASS="FUNCSYNOPSISINFO"
>#include <unistd.h></PRE
><P
><CODE
><CODE
CLASS="FUNCDEF"
>ssize_t write</CODE
>(int fd, void *buf, size_t count);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN9698"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><VAR
CLASS="PARAMETER"
>fd</VAR
></DT
><DD
><P
>File descriptor returned by <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
>.</P
></DD
><DT
><VAR
CLASS="PARAMETER"
>buf</VAR
></DT
><DD
><P
></P
></DD
><DT
><VAR
CLASS="PARAMETER"
>count</VAR
></DT
><DD
><P
></P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN9718"
></A
><H2
>Description</H2
><P
><CODE
CLASS="FUNCTION"
>write()</CODE
>
writes up to <VAR
CLASS="PARAMETER"
>count</VAR
> bytes to the device referenced by
the file descriptor <VAR
CLASS="PARAMETER"
>fd</VAR
> from the buffer
starting at <VAR
CLASS="PARAMETER"
>buf</VAR
>.
If <VAR
CLASS="PARAMETER"
>count</VAR
> is zero, 0 will be returned without
causing any other effect. [implementation tbd]</P
><P
>When the application does not provide more data in time, the
previous frame is displayed again.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN9727"
></A
><H2
>Return Value</H2
><P
>On success, the number of bytes written are returned.
Zero indicates nothing was written. [tbd] On error, -1 is
returned, and <VAR
CLASS="VARNAME"
>errno</VAR
> is set appropriately. In this
case the next write will start at the beginning of a new frame.
Possible error codes:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="ERRORCODE"
>EAGAIN</SPAN
></DT
><DD
><P
>Non-blocking I/O has been selected using
O_NONBLOCK and no buffer space was available to write the data
immediately. [tbd]</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>EBADF</SPAN
></DT
><DD
><P
><VAR
CLASS="PARAMETER"
>fd</VAR
> is not a valid file
descriptor or is not open for writing.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>EBUSY</SPAN
></DT
><DD
><P
>The driver does not support multiple write streams and the
device is already in use.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>EFAULT</SPAN
></DT
><DD
><P
><VAR
CLASS="PARAMETER"
>buf</VAR
> is outside your
accessible address space.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>EINTR</SPAN
></DT
><DD
><P
>The call was interrupted by a signal before any
data was written.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>EIO</SPAN
></DT
><DD
><P
>I/O error. This indicates some hardware problem.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
></DT
><DD
><P
>The <CODE
CLASS="FUNCTION"
>write()</CODE
> function is not
supported by this driver, not on this device, or generally not on this
type of device.</P
></DD
></DL
></DIV
></DIV
></DIV
><DIV
CLASS="CHAPTER"
><HR><H1
><A
NAME="DRIVER"
></A
>Chapter 5. Driver Interface</H1
><DIV
CLASS="SECTION"
><H2
CLASS="SECTION"
><A
NAME="FOO"
>5.1. to do</A
></H2
><DIV
CLASS="SECTION"
><H3
CLASS="SECTION"
><A
NAME="AEN9774"
>5.1.1. to do</A
></H3
><P
>to do</P
></DIV
></DIV
></DIV
><DIV
CLASS="CHAPTER"
><HR><H1
><A
NAME="COMPAT"
></A
>Chapter 6. History</H1
><P
>The following chapters document the evolution of the V4L2 API,
errata or extensions. They shall also aid application and driver
writers porting their software to later versions of V4L2.</P
><DIV
CLASS="SECTION"
><HR><H2
CLASS="SECTION"
><A
NAME="DIFF-V4L"
>6.1. Differences between V4L and V4L2</A
></H2
><P
>The Video For Linux API was first introduced in Linux 2.1 to
unify and replace various TV and radio device related interfaces,
developped independently by driver writers in prior years. Starting
with Linux 2.5 the much improved V4L2 API replaces the V4L API,
although existing drivers will continue to support V4L in the future,
either directly or through the V4L2 compatibility layer. For a
transition period not all drivers will support the V4L2 API.</P
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN9783"
>6.1.1. Opening and Closing Devices</A
></H3
><P
>For compatibility reasons the character device file names
recommended for V4L2 video capture, overlay, radio, teletext and raw
vbi capture devices did not change from those used by V4L. They are
listed in <A
HREF="#DEVICES"
>Chapter 4</A
> and below in <A
HREF="#V4L-DEV"
>Table 6-1</A
>.</P
><P
>The V4L "videodev" module automatically assigns minor
numbers to drivers in load order, depending on the registered device
type. We recommend V4L2 drivers by default register devices with the
same numbers, but in principle the system administrator can assign
arbitrary minor numbers using driver module options. The major device
number remains 81.</P
><DIV
CLASS="TABLE"
><A
NAME="V4L-DEV"
></A
><P
><B
>Table 6-1. V4L Device Types, Names and Numbers</B
></P
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><COL><COL><COL><THEAD
><TR
><TH
>Device Type</TH
><TH
>File Name</TH
><TH
>Minor Numbers</TH
></TR
></THEAD
><TBODY
><TR
><TD
>Video capture and overlay</TD
><TD
><P
><TT
CLASS="FILENAME"
>/dev/video</TT
> and
<TT
CLASS="FILENAME"
>/dev/bttv0</TT
><SUP
>a</SUP
>, <TT
CLASS="FILENAME"
>/dev/video0</TT
> to
<TT
CLASS="FILENAME"
>/dev/video63</TT
></P
></TD
><TD
>0-63</TD
></TR
><TR
><TD
>Radio receiver</TD
><TD
><P
><TT
CLASS="FILENAME"
>/dev/radio</TT
><SUP
>b</SUP
>, <TT
CLASS="FILENAME"
>/dev/radio0</TT
> to
<TT
CLASS="FILENAME"
>/dev/radio63</TT
></P
></TD
><TD
>64-127</TD
></TR
><TR
><TD
>Teletext decoder</TD
><TD
><P
><TT
CLASS="FILENAME"
>/dev/vtx</TT
>,
<TT
CLASS="FILENAME"
>/dev/vtx0</TT
> to
<TT
CLASS="FILENAME"
>/dev/vtx31</TT
></P
></TD
><TD
>192-223</TD
></TR
><TR
><TD
>Raw VBI capture</TD
><TD
><P
><TT
CLASS="FILENAME"
>/dev/vbi</TT
>,
<TT
CLASS="FILENAME"
>/dev/vbi0</TT
> to
<TT
CLASS="FILENAME"
>/dev/vbi15</TT
></P
></TD
><TD
><P
>224-239<SUP
>c</SUP
></P
></TD
></TR
></TBODY
><TR
><TD
COLSPAN="3"
>Notes:<BR><A
NAME="FTN.AEN9804"
>a. </A
>According to Documentation/devices.txt these
should be symbolic links to <TT
CLASS="FILENAME"
>/dev/video0</TT
>. Note the original bttv interface is not compatible with V4L or V4L2.<BR><A
NAME="FTN.AEN9815"
>b. </A
>According to
<TT
CLASS="FILENAME"
>Documentation/devices.txt</TT
> a symbolic link to
<TT
CLASS="FILENAME"
>/dev/radio0</TT
>.<BR><A
NAME="FTN.AEN9839"
>c. </A
>The range used to be 224-255. More device
types may be added in the future, so you should expect more range
splitting in the future.<BR></TD
></TR
></TABLE
></DIV
><P
>V4L prohibits (or used to) multiple opens. V4L2 drivers
<SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>may</I
></SPAN
> support multiple opens, see <A
HREF="#OPEN"
>Section 1.1</A
> for details and consequences.</P
><P
>V4L drivers respond to V4L2 ioctls with the <SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code. The
V4L2 "videodev" module backward compatibility layer can translate V4L
ioctl requests to their V4L2 counterpart, however a V4L2 driver
usually needs more preparation to become fully V4L compatible. This is
covered in more detail in <A
HREF="#DRIVER"
>Chapter 5</A
>.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN9847"
>6.1.2. Querying Capabilities</A
></H3
><P
>The V4L <CODE
CLASS="CONSTANT"
>VIDIOCGCAP</CODE
> ioctl is
equivalent to V4L2's <A
HREF="#VIDIOC-QUERYCAP"
><CODE
CLASS="CONSTANT"
>VIDIOC_QUERYCAP</CODE
></A
>.</P
><P
>The <CODE
CLASS="STRUCTFIELD"
>name</CODE
> field in struct
<CODE
CLASS="STRUCTNAME"
>video_capability</CODE
> became
<CODE
CLASS="STRUCTFIELD"
>card</CODE
> in struct <A
HREF="#V4L2-CAPABILITY"
>v4l2_capability</A
>,
<CODE
CLASS="STRUCTFIELD"
>type</CODE
> was replaced by
<CODE
CLASS="STRUCTFIELD"
>capabilities</CODE
>. Note V4L2 does not
distinguish between device types like this, better think of
basic video input, video output and radio devices supporting a set
of related functions like video capturing, video overlay and VBI
capturing. See <A
HREF="#OPEN"
>Section 1.1</A
> for an introduction.<DIV
CLASS="INFORMALTABLE"
><P
></P
><A
NAME="AEN9861"
></A
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><COL><COL><COL><THEAD
><TR
><TH
>struct <CODE
CLASS="STRUCTNAME"
>video_capability</CODE
>
<CODE
CLASS="STRUCTFIELD"
>type</CODE
></TH
><TH
>struct <A
HREF="#V4L2-CAPABILITY"
>v4l2_capability</A
>
<CODE
CLASS="STRUCTFIELD"
>capabilities</CODE
> flags</TH
><TH
>Purpose</TH
></TR
></THEAD
><TBODY
><TR
><TD
><CODE
CLASS="CONSTANT"
>VID_TYPE_CAPTURE</CODE
></TD
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CAP_VIDEO_CAPTURE</CODE
></TD
><TD
>The <A
HREF="#CAPTURE"
>video
capture</A
> interface is supported.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>VID_TYPE_TUNER</CODE
></TD
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CAP_TUNER</CODE
></TD
><TD
>The device has a <A
HREF="#TUNER"
>tuner or
modulator</A
>.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>VID_TYPE_TELETEXT</CODE
></TD
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CAP_VBI_CAPTURE</CODE
></TD
><TD
>The <A
HREF="#RAW-VBI"
>raw VBI
capture</A
> interface is supported.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>VID_TYPE_OVERLAY</CODE
></TD
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CAP_VIDEO_OVERLAY</CODE
></TD
><TD
>The <A
HREF="#OVERLAY"
>video overlay</A
>
interface is supported.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>VID_TYPE_CHROMAKEY</CODE
></TD
><TD
><CODE
CLASS="CONSTANT"
>V4L2_FBUF_CAP_CHROMAKEY</CODE
> in
field <CODE
CLASS="STRUCTFIELD"
>capability</CODE
> of
struct <A
HREF="#V4L2-FRAMEBUFFER"
>v4l2_framebuffer</A
></TD
><TD
>Whether chromakey overlay is supported. For
more information on overlay see
<A
HREF="#OVERLAY"
>Section 4.2</A
>.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>VID_TYPE_CLIPPING</CODE
></TD
><TD
><CODE
CLASS="CONSTANT"
>V4L2_FBUF_CAP_LIST_CLIPPING</CODE
>
and <CODE
CLASS="CONSTANT"
>V4L2_FBUF_CAP_BITMAP_CLIPPING</CODE
> in field
<CODE
CLASS="STRUCTFIELD"
>capability</CODE
> of struct <A
HREF="#V4L2-FRAMEBUFFER"
>v4l2_framebuffer</A
></TD
><TD
>Whether clipping the overlaid image is
supported, see <A
HREF="#OVERLAY"
>Section 4.2</A
>.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>VID_TYPE_FRAMERAM</CODE
></TD
><TD
><CODE
CLASS="CONSTANT"
>V4L2_FBUF_CAP_EXTERNOVERLAY</CODE
>
<SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>not set</I
></SPAN
> in field
<CODE
CLASS="STRUCTFIELD"
>capability</CODE
> of struct <A
HREF="#V4L2-FRAMEBUFFER"
>v4l2_framebuffer</A
></TD
><TD
>Whether overlay overwrites frame buffer memory,
see <A
HREF="#OVERLAY"
>Section 4.2</A
>.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>VID_TYPE_SCALES</CODE
></TD
><TD
><CODE
CLASS="CONSTANT"
>-</CODE
></TD
><TD
>This flag indicates if the hardware can scale
images. The V4L2 API implies the scale factor by setting the cropping
dimensions and image size with the <A
HREF="#VIDIOC-G-CROP"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_CROP</CODE
></A
> and <A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
></A
>
ioctl, respectively. The driver returns the closest sizes possible.
For more information on cropping and scaling see <A
HREF="#CROP"
>Section 1.10</A
>.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>VID_TYPE_MONOCHROME</CODE
></TD
><TD
><CODE
CLASS="CONSTANT"
>-</CODE
></TD
><TD
>Applications can enumerate the supported image
formats with the <A
HREF="#VIDIOC-ENUM-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_ENUM_FMT</CODE
></A
> ioctl to determine if the device
supports grey scale capturing only. For more information on image
formats see <A
HREF="#PIXFMT"
>Chapter 2</A
>.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>VID_TYPE_SUBCAPTURE</CODE
></TD
><TD
><CODE
CLASS="CONSTANT"
>-</CODE
></TD
><TD
>Applications can call the <A
HREF="#VIDIOC-G-CROP"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_CROP</CODE
></A
> ioctl
to determine if the device supports capturing a subsection of the full
picture ("cropping" in V4L2). If not, the ioctl returns the <SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code.
For more information on cropping and scaling see <A
HREF="#CROP"
>Section 1.10</A
>.</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
></P
><P
>The <CODE
CLASS="STRUCTFIELD"
>audios</CODE
> field was replaced
by <CODE
CLASS="STRUCTFIELD"
>capabilities</CODE
> flag
<CODE
CLASS="CONSTANT"
>V4L2_CAP_AUDIO</CODE
>, indicating
<SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>if</I
></SPAN
> the device has any audio inputs or outputs. To
determine their number applications can enumerate audio inputs with
the <A
HREF="#VIDIOC-G-AUDIO"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_AUDIO</CODE
></A
> ioctl. The audio ioctls are described in <A
HREF="#AUDIO"
>Section 1.5</A
>.</P
><P
>The <CODE
CLASS="STRUCTFIELD"
>maxwidth</CODE
>,
<CODE
CLASS="STRUCTFIELD"
>maxheight</CODE
>,
<CODE
CLASS="STRUCTFIELD"
>minwidth</CODE
> and
<CODE
CLASS="STRUCTFIELD"
>minheight</CODE
> fields were removed. Calling the
<A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
></A
> or <A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_TRY_FMT</CODE
></A
> ioctl with the desired dimensions
returns the closest size possible, taking into account the current
video standard, cropping and scaling.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN9977"
>6.1.3. Video Sources</A
></H3
><P
>V4L provides the <CODE
CLASS="CONSTANT"
>VIDIOCGCHAN</CODE
> and
<CODE
CLASS="CONSTANT"
>VIDIOCSCHAN</CODE
> ioctl using struct
<CODE
CLASS="STRUCTNAME"
>video_channel</CODE
> to enumerate
the video inputs of a V4L device. The equivalent V4L2 ioctls
are <A
HREF="#VIDIOC-ENUMINPUT"
><CODE
CLASS="CONSTANT"
>VIDIOC_ENUMINPUT</CODE
></A
>, <A
HREF="#VIDIOC-G-INPUT"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_INPUT</CODE
></A
> and <A
HREF="#VIDIOC-G-INPUT"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_INPUT</CODE
></A
>
using struct <A
HREF="#V4L2-INPUT"
>v4l2_input</A
> as discussed in <A
HREF="#VIDEO"
>Section 1.4</A
>.</P
><P
>The <CODE
CLASS="STRUCTFIELD"
>channel</CODE
> field counting
inputs was renamed to <CODE
CLASS="STRUCTFIELD"
>index</CODE
>, the video
input types were renamed: <DIV
CLASS="INFORMALTABLE"
><P
></P
><A
NAME="AEN9994"
></A
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><COL><COL><THEAD
><TR
><TH
>struct <CODE
CLASS="STRUCTNAME"
>video_channel</CODE
>
<CODE
CLASS="STRUCTFIELD"
>type</CODE
></TH
><TH
>struct <A
HREF="#V4L2-INPUT"
>v4l2_input</A
>
<CODE
CLASS="STRUCTFIELD"
>type</CODE
></TH
></TR
></THEAD
><TBODY
><TR
><TD
><CODE
CLASS="CONSTANT"
>VIDEO_TYPE_TV</CODE
></TD
><TD
><CODE
CLASS="CONSTANT"
>V4L2_INPUT_TYPE_TUNER</CODE
></TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>VIDEO_TYPE_CAMERA</CODE
></TD
><TD
><CODE
CLASS="CONSTANT"
>V4L2_INPUT_TYPE_CAMERA</CODE
></TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
></P
><P
>Unlike the <CODE
CLASS="STRUCTFIELD"
>tuners</CODE
> field
expressing the number of tuners of this input, V4L2 assumes each
video input is associated with at most one tuner. On the contrary a
tuner can have more than one input, i.e. RF connectors, and a device
can have multiple tuners. The index of the tuner associated with the
input, if any, is stored in field <CODE
CLASS="STRUCTFIELD"
>tuner</CODE
> of
struct <CODE
CLASS="STRUCTNAME"
>v4l2_input</CODE
>. Enumeration of tuners is
discussed in <A
HREF="#TUNER"
>Section 1.6</A
>.</P
><P
>The redundant <CODE
CLASS="CONSTANT"
>VIDEO_VC_TUNER</CODE
> flag was
dropped. Video inputs associated with a tuner are of type
<CODE
CLASS="CONSTANT"
>V4L2_INPUT_TYPE_TUNER</CODE
>. The
<CODE
CLASS="CONSTANT"
>VIDEO_VC_AUDIO</CODE
> flag was replaced by the
<CODE
CLASS="STRUCTFIELD"
>audioset</CODE
> field. V4L2 considers devices with
up to 32 audio inputs. Each set bit in the
<CODE
CLASS="STRUCTFIELD"
>audioset</CODE
> field represents one audio input
this video input combines with. For information about audio inputs and
how to switch see <A
HREF="#AUDIO"
>Section 1.5</A
>.</P
><P
>The <CODE
CLASS="STRUCTFIELD"
>norm</CODE
> field describing the
supported video standards was replaced by
<CODE
CLASS="STRUCTFIELD"
>std</CODE
>. The V4L specification mentions a flag
<CODE
CLASS="CONSTANT"
>VIDEO_VC_NORM</CODE
> indicating whether the standard can
be changed. This flag was a later addition together with the
<CODE
CLASS="STRUCTFIELD"
>norm</CODE
> field and has been removed in the
meantime. V4L2 has a similar, albeit more comprehensive approach
to video standards, see <A
HREF="#STANDARD"
>Section 1.7</A
> for more
information.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN10033"
>6.1.4. Tuning</A
></H3
><P
>The V4L <CODE
CLASS="CONSTANT"
>VIDIOCGTUNER</CODE
> and
<CODE
CLASS="CONSTANT"
>VIDIOCSTUNER</CODE
> ioctl and struct
<CODE
CLASS="STRUCTNAME"
>video_tuner</CODE
> can be used to enumerate the
tuners of a V4L TV or radio device. The equivalent V4L2 ioctls are
<A
HREF="#VIDIOC-G-TUNER"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_TUNER</CODE
></A
> and <A
HREF="#VIDIOC-G-TUNER"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_TUNER</CODE
></A
> using struct <A
HREF="#V4L2-TUNER"
>v4l2_tuner</A
>. Tuners are
covered in <A
HREF="#TUNER"
>Section 1.6</A
>.</P
><P
>The <CODE
CLASS="STRUCTFIELD"
>tuner</CODE
> field counting tuners
was renamed to <CODE
CLASS="STRUCTFIELD"
>index</CODE
>. The fields
<CODE
CLASS="STRUCTFIELD"
>name</CODE
>, <CODE
CLASS="STRUCTFIELD"
>rangelow</CODE
>
and <CODE
CLASS="STRUCTFIELD"
>rangehigh</CODE
> remained unchanged.</P
><P
>The <CODE
CLASS="CONSTANT"
>VIDEO_TUNER_PAL</CODE
>,
<CODE
CLASS="CONSTANT"
>VIDEO_TUNER_NTSC</CODE
> and
<CODE
CLASS="CONSTANT"
>VIDEO_TUNER_SECAM</CODE
> flags indicating the supported
video standards were dropped. This information is now contained in the
associated struct <A
HREF="#V4L2-INPUT"
>v4l2_input</A
>. No replacement exists for the
<CODE
CLASS="CONSTANT"
>VIDEO_TUNER_NORM</CODE
> flag indicating whether the
video standard can be switched. The <CODE
CLASS="STRUCTFIELD"
>mode</CODE
>
field to select a different video standard was replaced by a whole new
set of ioctls and structures described in <A
HREF="#STANDARD"
>Section 1.7</A
>.
Due to its ubiquity it should be mentioned the BTTV driver supports
several standards in addition to the regular
<CODE
CLASS="CONSTANT"
>VIDEO_MODE_PAL</CODE
> (0),
<CODE
CLASS="CONSTANT"
>VIDEO_MODE_NTSC</CODE
>,
<CODE
CLASS="CONSTANT"
>VIDEO_MODE_SECAM</CODE
> and
<CODE
CLASS="CONSTANT"
>VIDEO_MODE_AUTO</CODE
> (3). Namely N/PAL Argentina,
M/PAL, N/PAL, and NTSC Japan with numbers 3-6 (sic).</P
><P
>The <CODE
CLASS="CONSTANT"
>VIDEO_TUNER_STEREO_ON</CODE
> flag
indicating stereo reception became
<CODE
CLASS="CONSTANT"
>V4L2_TUNER_SUB_STEREO</CODE
> in field
<CODE
CLASS="STRUCTFIELD"
>rxsubchans</CODE
>. This field also permits the
detection of monaural and bilingual audio, see the definition of
struct <A
HREF="#V4L2-TUNER"
>v4l2_tuner</A
> for details. Presently no replacement exists for the
<CODE
CLASS="CONSTANT"
>VIDEO_TUNER_RDS_ON</CODE
> and
<CODE
CLASS="CONSTANT"
>VIDEO_TUNER_MBS_ON</CODE
> flags.</P
><P
> The <CODE
CLASS="CONSTANT"
>VIDEO_TUNER_LOW</CODE
> flag was renamed
to <CODE
CLASS="CONSTANT"
>V4L2_TUNER_CAP_LOW</CODE
> in the struct <A
HREF="#V4L2-TUNER"
>v4l2_tuner</A
>
<CODE
CLASS="STRUCTFIELD"
>capability</CODE
> field.</P
><P
>The <CODE
CLASS="CONSTANT"
>VIDIOCGFREQ</CODE
> and
<CODE
CLASS="CONSTANT"
>VIDIOCSFREQ</CODE
> ioctl to change the tuner frequency
where renamed to <A
HREF="#VIDIOC-G-FREQUENCY"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_FREQUENCY</CODE
></A
> and <A
HREF="#VIDIOC-G-FREQUENCY"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_FREQUENCY</CODE
></A
>. They
take a pointer to a struct <A
HREF="#V4L2-FREQUENCY"
>v4l2_frequency</A
> instead of an unsigned long
integer.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="V4L-IMAGE-PROPERTIES"
>6.1.5. Image Properties</A
></H3
><P
>V4L2 has no equivalent of the
<CODE
CLASS="CONSTANT"
>VIDIOCGPICT</CODE
> and <CODE
CLASS="CONSTANT"
>VIDIOCSPICT</CODE
>
ioctl and struct <CODE
CLASS="STRUCTNAME"
>video_picture</CODE
>. The following
fields where replaced by V4L2 controls accessible with the
<A
HREF="#VIDIOC-QUERYCTRL"
><CODE
CLASS="CONSTANT"
>VIDIOC_QUERYCTRL</CODE
></A
>, <A
HREF="#VIDIOC-G-CTRL"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_CTRL</CODE
></A
> and <A
HREF="#VIDIOC-G-CTRL"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_CTRL</CODE
></A
> ioctls:<DIV
CLASS="INFORMALTABLE"
><P
></P
><A
NAME="AEN10095"
></A
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><COL><COL><THEAD
><TR
><TH
>struct <CODE
CLASS="STRUCTNAME"
>video_picture</CODE
></TH
><TH
>V4L2 Control ID</TH
></TR
></THEAD
><TBODY
><TR
><TD
><CODE
CLASS="STRUCTFIELD"
>brightness</CODE
></TD
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CID_BRIGHTNESS</CODE
></TD
></TR
><TR
><TD
><CODE
CLASS="STRUCTFIELD"
>hue</CODE
></TD
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CID_HUE</CODE
></TD
></TR
><TR
><TD
><CODE
CLASS="STRUCTFIELD"
>colour</CODE
></TD
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CID_SATURATION</CODE
></TD
></TR
><TR
><TD
><CODE
CLASS="STRUCTFIELD"
>contrast</CODE
></TD
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CID_CONTRAST</CODE
></TD
></TR
><TR
><TD
><CODE
CLASS="STRUCTFIELD"
>whiteness</CODE
></TD
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CID_WHITENESS</CODE
></TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
></P
><P
>The V4L picture controls are assumed to range from 0 to
65535 with no particular reset value. The V4L2 API permits arbitrary
limits and defaults which can be queried with the <A
HREF="#VIDIOC-QUERYCTRL"
><CODE
CLASS="CONSTANT"
>VIDIOC_QUERYCTRL</CODE
></A
>
ioctl. For general information about controls see <A
HREF="#CONTROL"
>Section 1.8</A
>.</P
><P
>The <CODE
CLASS="STRUCTFIELD"
>depth</CODE
> (average number of
bits per pixel) of a video image is implied by the selected image
format. V4L2 does not explicitely provide such information assuming
applications recognizing the format are aware of the image depth and
others need not know. The <CODE
CLASS="STRUCTFIELD"
>palette</CODE
> field
moved into the struct <A
HREF="#V4L2-PIX-FORMAT"
>v4l2_pix_format</A
>:<DIV
CLASS="INFORMALTABLE"
><P
></P
><A
NAME="AEN10136"
></A
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><COL><COL><THEAD
><TR
><TH
>struct <CODE
CLASS="STRUCTNAME"
>video_picture</CODE
>
<CODE
CLASS="STRUCTFIELD"
>palette</CODE
></TH
><TH
>struct <A
HREF="#V4L2-PIX-FORMAT"
>v4l2_pix_format</A
>
<CODE
CLASS="STRUCTFIELD"
>pixfmt</CODE
></TH
></TR
></THEAD
><TBODY
><TR
><TD
><CODE
CLASS="CONSTANT"
>VIDEO_PALETTE_GREY</CODE
></TD
><TD
><P
><A
HREF="#PIXFMT-GREY"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_GREY</CODE
></A
></P
></TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>VIDEO_PALETTE_HI240</CODE
></TD
><TD
><P
><A
HREF="#PIXFMT-RESERVED"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_HI240</CODE
></A
><SUP
>a</SUP
></P
></TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>VIDEO_PALETTE_RGB565</CODE
></TD
><TD
><P
><A
HREF="#PIXFMT-RGB"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_RGB565</CODE
></A
></P
></TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>VIDEO_PALETTE_RGB555</CODE
></TD
><TD
><P
><A
HREF="#PIXFMT-RGB"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_RGB555</CODE
></A
></P
></TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>VIDEO_PALETTE_RGB24</CODE
></TD
><TD
><P
><A
HREF="#PIXFMT-RGB"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_BGR24</CODE
></A
></P
></TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>VIDEO_PALETTE_RGB32</CODE
></TD
><TD
><P
><A
HREF="#PIXFMT-RGB"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_BGR32</CODE
></A
><SUP
>b</SUP
></P
></TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>VIDEO_PALETTE_YUV422</CODE
></TD
><TD
><P
><A
HREF="#PIXFMT-YUYV"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YUYV</CODE
></A
></P
></TD
></TR
><TR
><TD
><P
><CODE
CLASS="CONSTANT"
>VIDEO_PALETTE_YUYV</CODE
><SUP
>c</SUP
></P
></TD
><TD
><P
><A
HREF="#PIXFMT-YUYV"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YUYV</CODE
></A
></P
></TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>VIDEO_PALETTE_UYVY</CODE
></TD
><TD
><P
><A
HREF="#PIXFMT-UYVY"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_UYVY</CODE
></A
></P
></TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>VIDEO_PALETTE_YUV420</CODE
></TD
><TD
>None</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>VIDEO_PALETTE_YUV411</CODE
></TD
><TD
><P
><A
HREF="#PIXFMT-Y41P"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_Y41P</CODE
></A
><SUP
>d</SUP
></P
></TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>VIDEO_PALETTE_RAW</CODE
></TD
><TD
><P
>None<SUP
>e</SUP
></P
></TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>VIDEO_PALETTE_YUV422P</CODE
></TD
><TD
><P
><A
HREF="#PIXFMT-YUV422P"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YUV422P</CODE
></A
></P
></TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>VIDEO_PALETTE_YUV411P</CODE
></TD
><TD
><P
><A
HREF="#PIXFMT-YUV411P"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YUV411P</CODE
></A
><SUP
>f</SUP
></P
></TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>VIDEO_PALETTE_YUV420P</CODE
></TD
><TD
><P
><A
HREF="#PIXFMT-YVU420"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YVU420</CODE
></A
></P
></TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>VIDEO_PALETTE_YUV410P</CODE
></TD
><TD
><P
><A
HREF="#PIXFMT-YVU410"
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YVU410</CODE
></A
></P
></TD
></TR
></TBODY
><TR
><TD
COLSPAN="2"
>Notes:<BR><A
NAME="FTN.AEN10161"
>a. </A
>This is a custom format used by the BTTV
driver, not one of the V4L2 standard formats.<BR><A
NAME="FTN.AEN10191"
>b. </A
>Presumably all V4L RGB formats are
little-endian, although some drivers might interpret them according to machine endianess. V4L2 defines little-endian, big-endian and red/blue
swapped variants. For details see <A
HREF="#PIXFMT-RGB"
>Section 2.3</A
>.<BR><A
NAME="FTN.AEN10205"
>c. </A
><CODE
CLASS="CONSTANT"
>VIDEO_PALETTE_YUV422</CODE
>
and <CODE
CLASS="CONSTANT"
>VIDEO_PALETTE_YUYV</CODE
> are the same formats. Some
V4L drivers respond to one, some to the other.<BR><A
NAME="FTN.AEN10231"
>d. </A
>Not to be confused with
<CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_YUV411P</CODE
>, which is a planar
format.<BR><A
NAME="FTN.AEN10239"
>e. </A
>V4L explains this
as: "RAW capture (BT848)"<BR><A
NAME="FTN.AEN10255"
>f. </A
>Not to be confused with
<CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_Y41P</CODE
>, which is a packed
format.<BR></TD
></TR
></TABLE
><P
></P
></DIV
></P
><P
>V4L2 image formats are defined in <A
HREF="#PIXFMT"
>Chapter 2</A
>. The image format can be selected with the
<A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
></A
> ioctl.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN10276"
>6.1.6. Audio</A
></H3
><P
>The <CODE
CLASS="CONSTANT"
>VIDIOCGAUDIO</CODE
> and
<CODE
CLASS="CONSTANT"
>VIDIOCSAUDIO</CODE
> ioctl and struct
<CODE
CLASS="STRUCTNAME"
>video_audio</CODE
> are used to enumerate the
audio inputs of a V4L device. The equivalent V4L2 ioctls are
<A
HREF="#VIDIOC-G-AUDIO"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_AUDIO</CODE
></A
> and <A
HREF="#VIDIOC-G-AUDIO"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_AUDIO</CODE
></A
> using struct <A
HREF="#V4L2-AUDIO"
>v4l2_audio</A
> as
discussed in <A
HREF="#AUDIO"
>Section 1.5</A
>.</P
><P
>The <CODE
CLASS="STRUCTFIELD"
>audio</CODE
> "channel number"
field counting audio inputs was renamed to
<CODE
CLASS="STRUCTFIELD"
>index</CODE
>.</P
><P
>On <CODE
CLASS="CONSTANT"
>VIDIOCSAUDIO</CODE
> the
<CODE
CLASS="STRUCTFIELD"
>mode</CODE
> field selects <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>one</I
></SPAN
>
of the <CODE
CLASS="CONSTANT"
>VIDEO_SOUND_MONO</CODE
>,
<CODE
CLASS="CONSTANT"
>VIDEO_SOUND_STEREO</CODE
>,
<CODE
CLASS="CONSTANT"
>VIDEO_SOUND_LANG1</CODE
> or
<CODE
CLASS="CONSTANT"
>VIDEO_SOUND_LANG2</CODE
> audio demodulation modes. When
the current audio standard is BTSC
<CODE
CLASS="CONSTANT"
>VIDEO_SOUND_LANG2</CODE
> refers to SAP and
<CODE
CLASS="CONSTANT"
>VIDEO_SOUND_LANG1</CODE
> is meaningless. Also
undocumented in the V4L specification, there is no way to query the
selected mode. On <CODE
CLASS="CONSTANT"
>VIDIOCGAUDIO</CODE
> the driver returns
the <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>actually received</I
></SPAN
> audio programmes in this
field. In the V4L2 API this information is stored in the struct <A
HREF="#V4L2-TUNER"
>v4l2_tuner</A
>
<CODE
CLASS="STRUCTFIELD"
>rxsubchans</CODE
> and
<CODE
CLASS="STRUCTFIELD"
>audmode</CODE
> fields, respectively. See <A
HREF="#TUNER"
>Section 1.6</A
> for more information on tuners. Related to audio
modes struct <A
HREF="#V4L2-AUDIO"
>v4l2_audio</A
> also reports if this is a mono or stereo
input, regardless if the source is a tuner.</P
><P
>The following fields where replaced by V4L2 controls
accessible with the <A
HREF="#VIDIOC-QUERYCTRL"
><CODE
CLASS="CONSTANT"
>VIDIOC_QUERYCTRL</CODE
></A
>, <A
HREF="#VIDIOC-G-CTRL"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_CTRL</CODE
></A
> and
<A
HREF="#VIDIOC-G-CTRL"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_CTRL</CODE
></A
> ioctls:<DIV
CLASS="INFORMALTABLE"
><P
></P
><A
NAME="AEN10315"
></A
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><COL><COL><THEAD
><TR
><TH
>struct
<CODE
CLASS="STRUCTNAME"
>video_audio</CODE
></TH
><TH
>V4L2 Control ID</TH
></TR
></THEAD
><TBODY
><TR
><TD
><CODE
CLASS="STRUCTFIELD"
>volume</CODE
></TD
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CID_AUDIO_VOLUME</CODE
></TD
></TR
><TR
><TD
><CODE
CLASS="STRUCTFIELD"
>bass</CODE
></TD
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CID_AUDIO_BASS</CODE
></TD
></TR
><TR
><TD
><CODE
CLASS="STRUCTFIELD"
>treble</CODE
></TD
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CID_AUDIO_TREBLE</CODE
></TD
></TR
><TR
><TD
><CODE
CLASS="STRUCTFIELD"
>balance</CODE
></TD
><TD
><CODE
CLASS="CONSTANT"
>V4L2_CID_AUDIO_BALANCE</CODE
></TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
></P
><P
>To determine which of these controls are supported by a
driver V4L provides the <CODE
CLASS="STRUCTFIELD"
>flags</CODE
>
<CODE
CLASS="CONSTANT"
>VIDEO_AUDIO_VOLUME</CODE
>,
<CODE
CLASS="CONSTANT"
>VIDEO_AUDIO_BASS</CODE
>,
<CODE
CLASS="CONSTANT"
>VIDEO_AUDIO_TREBLE</CODE
> and
<CODE
CLASS="CONSTANT"
>VIDEO_AUDIO_BALANCE</CODE
>. In the V4L2 API the
<A
HREF="#VIDIOC-QUERYCTRL"
><CODE
CLASS="CONSTANT"
>VIDIOC_QUERYCTRL</CODE
></A
> ioctl reports if the respective control is
supported. Accordingly the <CODE
CLASS="CONSTANT"
>VIDEO_AUDIO_MUTABLE</CODE
>
and <CODE
CLASS="CONSTANT"
>VIDEO_AUDIO_MUTE</CODE
> flags where replaced by the
boolean <CODE
CLASS="CONSTANT"
>V4L2_CID_AUDIO_MUTE</CODE
> control.</P
><P
>All V4L2 controls have a <CODE
CLASS="STRUCTFIELD"
>step</CODE
>
attribute replacing the struct <CODE
CLASS="STRUCTNAME"
>video_audio</CODE
>
<CODE
CLASS="STRUCTFIELD"
>step</CODE
> field. The V4L audio controls are
assumed to range from 0 to 65535 with no particular reset value. The
V4L2 API permits arbitrary limits and defaults which can be queried
with the <A
HREF="#VIDIOC-QUERYCTRL"
><CODE
CLASS="CONSTANT"
>VIDIOC_QUERYCTRL</CODE
></A
> ioctl. For general information about
controls see <A
HREF="#CONTROL"
>Section 1.8</A
>.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN10361"
>6.1.7. Frame Buffer Overlay</A
></H3
><P
>The V4L2 ioctls equivalent to
<CODE
CLASS="CONSTANT"
>VIDIOCGFBUF</CODE
> and <CODE
CLASS="CONSTANT"
>VIDIOCSFBUF</CODE
>
are <A
HREF="#VIDIOC-G-FBUF"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_FBUF</CODE
></A
> and <A
HREF="#VIDIOC-G-FBUF"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_FBUF</CODE
></A
>. The
<CODE
CLASS="STRUCTFIELD"
>base</CODE
> field of struct
<CODE
CLASS="STRUCTNAME"
>video_buffer</CODE
> remained unchanged, except V4L2
using a flag to indicate non-destructive overlay instead of a
<CODE
CLASS="CONSTANT"
>NULL</CODE
> pointer. All other fields moved into the
struct <A
HREF="#V4L2-PIX-FORMAT"
>v4l2_pix_format</A
> substructure <CODE
CLASS="STRUCTFIELD"
>fmt</CODE
> of
struct <A
HREF="#V4L2-FRAMEBUFFER"
>v4l2_framebuffer</A
>. The <CODE
CLASS="STRUCTFIELD"
>depth</CODE
> field was
replaced by <CODE
CLASS="STRUCTFIELD"
>pixelformat</CODE
>. A conversion table
is available in the <A
HREF="#PIXFMT-RGB"
>Section 2.3</A
>.</P
><P
>Instead of the special ioctls
<CODE
CLASS="CONSTANT"
>VIDIOCGWIN</CODE
> and <CODE
CLASS="CONSTANT"
>VIDIOCSWIN</CODE
>
V4L2 uses the general-purpose data format negotiation ioctls
<A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_FMT</CODE
></A
> and <A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
></A
>. They take a pointer to a
struct <A
HREF="#V4L2-FORMAT"
>v4l2_format</A
> as argument, here the struct <A
HREF="#V4L2-WINDOW"
>v4l2_window</A
> named
<CODE
CLASS="STRUCTFIELD"
>win</CODE
> of its <CODE
CLASS="STRUCTFIELD"
>fmt</CODE
>
union is used.</P
><P
>The <CODE
CLASS="STRUCTFIELD"
>x</CODE
>,
<CODE
CLASS="STRUCTFIELD"
>y</CODE
>, <CODE
CLASS="STRUCTFIELD"
>width</CODE
> and
<CODE
CLASS="STRUCTFIELD"
>height</CODE
> fields of struct
<CODE
CLASS="STRUCTNAME"
>video_window</CODE
> moved into struct <A
HREF="#V4L2-RECT"
>v4l2_rect</A
>
substructure <CODE
CLASS="STRUCTFIELD"
>w</CODE
> of struct
<CODE
CLASS="STRUCTNAME"
>v4l2_window</CODE
>. The
<CODE
CLASS="STRUCTFIELD"
>chromakey</CODE
>,
<CODE
CLASS="STRUCTFIELD"
>clips</CODE
>, and
<CODE
CLASS="STRUCTFIELD"
>clipcount</CODE
> fields remained unchanged. Struct
<CODE
CLASS="STRUCTNAME"
>video_clip</CODE
> was renamed to struct <A
HREF="#V4L2-CLIP"
>v4l2_clip</A
>, also
containing a struct <CODE
CLASS="STRUCTNAME"
>v4l2_rect</CODE
>, but the
semantics are still the same.</P
><P
>The <CODE
CLASS="CONSTANT"
>VIDEO_WINDOW_INTERLACE</CODE
> flag was
dropped, instead applications must set the
<CODE
CLASS="STRUCTFIELD"
>field</CODE
> field to
<CODE
CLASS="CONSTANT"
>V4L2_FIELD_ANY</CODE
> or
<CODE
CLASS="CONSTANT"
>V4L2_FIELD_INTERLACED</CODE
>. The
<CODE
CLASS="CONSTANT"
>VIDEO_WINDOW_CHROMAKEY</CODE
> flag moved into
struct <A
HREF="#V4L2-FRAMEBUFFER"
>v4l2_framebuffer</A
>, renamed to
<CODE
CLASS="CONSTANT"
>V4L2_FBUF_FLAG_CHROMAKEY</CODE
>.</P
><P
>In V4L, storing a bitmap pointer in
<CODE
CLASS="STRUCTFIELD"
>clips</CODE
> and setting
<CODE
CLASS="STRUCTFIELD"
>clipcount</CODE
> to
<CODE
CLASS="CONSTANT"
>VIDEO_CLIP_BITMAP</CODE
> (-1) requests bitmap
clipping, using a fixed size bitmap of 1024 × 625 bits. Struct
<CODE
CLASS="STRUCTNAME"
>v4l2_window</CODE
> has a separate
<CODE
CLASS="STRUCTFIELD"
>bitmap</CODE
> pointer field for this purpose and
the bitmap size is determined by <CODE
CLASS="STRUCTFIELD"
>w.width</CODE
> and
<CODE
CLASS="STRUCTFIELD"
>w.height</CODE
>.</P
><P
>The <CODE
CLASS="CONSTANT"
>VIDIOCCAPTURE</CODE
> ioctl to enable or
disable overlay was renamed to <A
HREF="#VIDIOC-OVERLAY"
><CODE
CLASS="CONSTANT"
>VIDIOC_OVERLAY</CODE
></A
>.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN10425"
>6.1.8. Cropping</A
></H3
><P
>To capture only a subsection of the full picture V4L
provides the <CODE
CLASS="CONSTANT"
>VIDIOCGCAPTURE</CODE
> and
<CODE
CLASS="CONSTANT"
>VIDIOCSCAPTURE</CODE
> ioctl using struct
<CODE
CLASS="STRUCTNAME"
>video_capture</CODE
>. The equivalent V4L2 ioctls are
<A
HREF="#VIDIOC-G-CROP"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_CROP</CODE
></A
> and <A
HREF="#VIDIOC-G-CROP"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_CROP</CODE
></A
> using struct <A
HREF="#V4L2-CROP"
>v4l2_crop</A
>, and the related
<A
HREF="#VIDIOC-CROPCAP"
><CODE
CLASS="CONSTANT"
>VIDIOC_CROPCAP</CODE
></A
> ioctl. This is a rather complex matter, see
<A
HREF="#CROP"
>Section 1.10</A
> for details.</P
><P
>The <CODE
CLASS="STRUCTFIELD"
>x</CODE
>,
<CODE
CLASS="STRUCTFIELD"
>y</CODE
>, <CODE
CLASS="STRUCTFIELD"
>width</CODE
> and
<CODE
CLASS="STRUCTFIELD"
>height</CODE
> fields moved into struct <A
HREF="#V4L2-RECT"
>v4l2_rect</A
>
substructure <CODE
CLASS="STRUCTFIELD"
>c</CODE
> of struct
<CODE
CLASS="STRUCTNAME"
>v4l2_crop</CODE
>. The
<CODE
CLASS="STRUCTFIELD"
>decimation</CODE
> field was dropped. The scaling factor is
implied by the size of the cropping rectangle and the size of the
captured or overlaid image.</P
><P
>The <CODE
CLASS="CONSTANT"
>VIDEO_CAPTURE_ODD</CODE
>
and <CODE
CLASS="CONSTANT"
>VIDEO_CAPTURE_EVEN</CODE
> flags to capture only the
odd or even field, respectively, were replaced by
<CODE
CLASS="CONSTANT"
>V4L2_FIELD_TOP</CODE
> and
<CODE
CLASS="CONSTANT"
>V4L2_FIELD_BOTTOM</CODE
> in the field named
<CODE
CLASS="STRUCTFIELD"
>field</CODE
> of struct <A
HREF="#V4L2-PIX-FORMAT"
>v4l2_pix_format</A
> and
struct <A
HREF="#V4L2-WINDOW"
>v4l2_window</A
>. These structures are used to determine the capture or
overlay format with the <A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
></A
> ioctl.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN10458"
>6.1.9. Reading Images, Memory Mapping</A
></H3
><DIV
CLASS="SECTION"
><H4
CLASS="SECTION"
><A
NAME="AEN10460"
>6.1.9.1. Capturing using the read method</A
></H4
><P
>There is no essential difference between reading images
from a V4L or V4L2 device using the <A
HREF="#FUNC-READ"
><CODE
CLASS="FUNCTION"
>read()</CODE
></A
> function. Supporting
this method is optional for V4L2 devices. Whether the function is
available can be determined with the <A
HREF="#VIDIOC-QUERYCAP"
><CODE
CLASS="CONSTANT"
>VIDIOC_QUERYCAP</CODE
></A
> ioctl. All V4L2
devices exchanging data with applications must support the
<A
HREF="#FUNC-SELECT"
><CODE
CLASS="FUNCTION"
>select()</CODE
></A
> and <A
HREF="#FUNC-POLL"
><CODE
CLASS="FUNCTION"
>poll()</CODE
></A
> function.</P
><P
>To select an image format and size, V4L provides the
<CODE
CLASS="CONSTANT"
>VIDIOCSPICT</CODE
> and <CODE
CLASS="CONSTANT"
>VIDIOCSWIN</CODE
>
ioctls. V4L2 uses the general-purpose data format negotiation ioctls
<A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_FMT</CODE
></A
> and <A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
></A
>. They take a pointer to a
struct <A
HREF="#V4L2-FORMAT"
>v4l2_format</A
> as argument, here the struct <A
HREF="#V4L2-PIX-FORMAT"
>v4l2_pix_format</A
> named
<CODE
CLASS="STRUCTFIELD"
>pix</CODE
> of its <CODE
CLASS="STRUCTFIELD"
>fmt</CODE
>
union is used.</P
><P
>For more information about the V4L2 read interface see
<A
HREF="#RW"
>Section 3.1</A
>.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H4
CLASS="SECTION"
><A
NAME="AEN10484"
>6.1.9.2. Capturing using memory mapping</A
></H4
><P
>Applications can read from V4L devices by mapping
buffers in device memory, or more often just buffers allocated in
DMA-able system memory, into their address space. This avoids the data
copy overhead of the read method. V4L2 supports memory mapping as
well, with a few differences.</P
><DIV
CLASS="INFORMALTABLE"
><P
></P
><A
NAME="AEN10487"
></A
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><COL><COL><THEAD
><TR
><TH
>V4L</TH
><TH
>V4L2</TH
></TR
></THEAD
><TBODY
><TR
><TD
> </TD
><TD
>The image format must be selected before
buffers are allocated, with the <A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
></A
> ioctl. When no format
is selected the driver may use the last, possibly by another
application requested format.</TD
></TR
><TR
><TD
><P
>Applications cannot change the number of
buffers allocated. The number is built into the driver, unless it
has a module option to change the number when the driver module is
loaded.</P
></TD
><TD
><P
>The <A
HREF="#VIDIOC-REQBUFS"
><CODE
CLASS="CONSTANT"
>VIDIOC_REQBUFS</CODE
></A
> ioctl allocates the
desired number of buffers, this is a required step in the initialization
sequence.</P
></TD
></TR
><TR
><TD
><P
>Drivers map all buffers as one contiguous range
of memory. The <CODE
CLASS="CONSTANT"
>VIDIOCGMBUF</CODE
> ioctl is
available to query the number of buffers, the offset of
each buffer from the start of the virtual file, and the
overall amount of memory used, which can be used as arguments to the
<A
HREF="#FUNC-MMAP"
><CODE
CLASS="FUNCTION"
>mmap()</CODE
></A
> function.</P
></TD
><TD
><P
>Buffers are individually mapped. The offset and size of each buffer can be determined with the <A
HREF="#VIDIOC-QUERYBUF"
><CODE
CLASS="CONSTANT"
>VIDIOC_QUERYBUF</CODE
></A
> ioctl.</P
></TD
></TR
><TR
><TD
><P
>The <CODE
CLASS="CONSTANT"
>VIDIOCMCAPTURE</CODE
>
ioctl prepares a buffer for capturing. It also determines the image
format for this buffer. The ioctl returns immediately, eventually with
an <SPAN
CLASS="ERRORCODE"
>EAGAIN</SPAN
> error code if no video signal had been detected. When the driver
supports more than one buffer applications can call the ioctl multiple
times and thus have multiple outstanding capture
requests.</P
><P
>The <CODE
CLASS="CONSTANT"
>VIDIOCSYNC</CODE
> ioctl
suspends execution until a particular buffer has been
filled.</P
></TD
><TD
><P
>Drivers maintain an incoming and outgoing
queue. <A
HREF="#VIDIOC-QBUF"
><CODE
CLASS="CONSTANT"
>VIDIOC_QBUF</CODE
></A
> enqueues any empty buffer into the incoming
queue. Filled buffers are dequeued from the outgoing queue with the
<A
HREF="#VIDIOC-QBUF"
><CODE
CLASS="CONSTANT"
>VIDIOC_DQBUF</CODE
></A
> ioctl. To wait until filled buffers become available this
function, <A
HREF="#FUNC-SELECT"
><CODE
CLASS="FUNCTION"
>select()</CODE
></A
> or <A
HREF="#FUNC-POLL"
><CODE
CLASS="FUNCTION"
>poll()</CODE
></A
> can be used. The
<A
HREF="#VIDIOC-STREAMON"
><CODE
CLASS="CONSTANT"
>VIDIOC_STREAMON</CODE
></A
> ioctl must be called once after enqueuing one or
more buffers to start capturing. Its counterpart
<A
HREF="#VIDIOC-STREAMON"
><CODE
CLASS="CONSTANT"
>VIDIOC_STREAMOFF</CODE
></A
> stops capturing and dequeues all buffers from both
queues. Applications can query the signal status, if known, with the
<A
HREF="#VIDIOC-ENUMINPUT"
><CODE
CLASS="CONSTANT"
>VIDIOC_ENUMINPUT</CODE
></A
> ioctl.</P
></TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
><P
>For a more in-depth discussion of memory mapping and
examples, see <A
HREF="#MMAP"
>Section 3.2</A
>.</P
></DIV
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN10541"
>6.1.10. Reading Raw VBI Data</A
></H3
><P
>Originally the V4L API did not specify a raw VBI capture
interface, merely the device file <TT
CLASS="FILENAME"
>/dev/vbi</TT
> was
reserved for this purpose. The only driver supporting this interface
was the BTTV driver, de-facto defining the V4L VBI interface. Reading
from the device yields a raw VBI image with the following
parameters:<DIV
CLASS="INFORMALTABLE"
><P
></P
><A
NAME="AEN10545"
></A
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><COL><COL><THEAD
><TR
><TH
>struct <A
HREF="#V4L2-VBI-FORMAT"
>v4l2_vbi_format</A
></TH
><TH
>V4L, BTTV driver</TH
></TR
></THEAD
><TBODY
><TR
><TD
>sampling_rate</TD
><TD
>28636363 Hz NTSC (precisely all 525-line
standards); 35468950 Hz PAL and SECAM (625-line)</TD
></TR
><TR
><TD
>offset</TD
><TD
>?</TD
></TR
><TR
><TD
>samples_per_line</TD
><TD
>2048</TD
></TR
><TR
><TD
>sample_format</TD
><TD
>V4L2_PIX_FMT_GREY. The last four bytes
(machine endianess integer) contain a frame counter.</TD
></TR
><TR
><TD
>start[]</TD
><TD
>10, 273 NTSC; 22, 335 PAL and SECAM</TD
></TR
><TR
><TD
>count[]</TD
><TD
><P
>16, 16<SUP
>a</SUP
></P
></TD
></TR
><TR
><TD
>flags</TD
><TD
>0</TD
></TR
></TBODY
><TR
><TD
COLSPAN="2"
>Notes:<BR><A
NAME="FTN.AEN10572"
>a. </A
>Old driver
versions used different values, eventually the custom
<CODE
CLASS="CONSTANT"
>BTTV_VBISIZE</CODE
> ioctl was added to query the
correct values.<BR></TD
></TR
></TABLE
><P
></P
></DIV
></P
><P
>Undocumented in the V4L specification, in Linux 2.3 the
<CODE
CLASS="CONSTANT"
>VIDIOCGVBIFMT</CODE
> and
<CODE
CLASS="CONSTANT"
>VIDIOCSVBIFMT</CODE
> ioctls using struct
<CODE
CLASS="STRUCTNAME"
>vbi_format</CODE
> were added to determine the VBI
image parameters. These ioctls are only partially compatible with the
V4L2 VBI interface specified in <A
HREF="#RAW-VBI"
>Section 4.6</A
>.</P
><P
>An <CODE
CLASS="STRUCTFIELD"
>offset</CODE
> field does not
exist, <CODE
CLASS="STRUCTFIELD"
>sample_format</CODE
> is supposed to be
<CODE
CLASS="CONSTANT"
>VIDEO_PALETTE_RAW</CODE
>, here equivalent to
<CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_GREY</CODE
>. The remaining fields are
probably equivalent to struct <A
HREF="#V4L2-VBI-FORMAT"
>v4l2_vbi_format</A
>.</P
><P
>Apparently only the Zoran (ZR 36120) driver implements
these ioctls. The semantics differ from those specified for V4L2 in two
ways. The parameters are reset on <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
> and
<CODE
CLASS="CONSTANT"
>VIDIOCSVBIFMT</CODE
> always returns the <SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code if the
parameters are invalid.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN10594"
>6.1.11. Miscellaneous</A
></H3
><P
>V4L2 has no equivalent of the
<CODE
CLASS="CONSTANT"
>VIDIOCGUNIT</CODE
> ioctl. Applications can find the VBI
device associated with a video capture device (or vice versa) by
reopening the device and requesting VBI data. For details see
<A
HREF="#OPEN"
>Section 1.1</A
>.</P
><P
>Presently no replacement exists for
<CODE
CLASS="CONSTANT"
>VIDIOCKEY</CODE
>, the V4L functions
regarding MPEG compression and decompression, and microcode
programming. Drivers may implement the respective V4L ioctls for
these purposes.</P
></DIV
></DIV
><DIV
CLASS="SECTION"
><HR><H2
CLASS="SECTION"
><A
NAME="HIST-V4L2"
>6.2. History of the V4L2 API</A
></H2
><P
>Soon after the V4L API was added to the kernel it was
criticised as too inflexible. In August 1998 Bill Dirks proposed a
number of improvements and began work on documentation, example
drivers and applications. With the help of other volunteers this
eventually became the V4L2 API, not just an extension but a
replacement for the V4L API. However it took another four years and
two stable kernel releases until the new API was finally accepted for
inclusion into the kernel in its present form.</P
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN10604"
>6.2.1. Early Versions</A
></H3
><P
>1998-08-20: First version.</P
><P
>1998-08-27: select() function was introduced.</P
><P
>1998-09-10: New video standard interface.</P
><P
>1998-09-18: The VIDIOC_NONCAP ioctl was replaced by the O_TRUNC open()
flag (with synonym O_NONCAP/O_NOIO) to indicate a non-capturing open. The
VIDEO_STD_XXX identifiers are now ordinals rather than bits, and
video_std_construct helper function takes id and transmission as
arguments.</P
><P
>1998-09-28: Revamped video standard. Made video controls individually
enumerable.</P
><P
>1998-10-02: Removed id from video_standard, renamed color subcarrier
fields. Renamed VIDIOC_QUERYSTD to VIDIOC_ENUMSTD and VIDIOC_G_INPUT
to VIDIOC_ENUMINPUT. Added preliminary /proc/videodev file. First
draft of CODEC driver API spec.</P
><P
>1998-11-08: Updating for many minor changes to the V4L2 spec. Most
symbols have been renamed. Some material changes to
v4l2_capability.</P
><P
>1998-11-12 bugfix: some of the VIDIOC_* symbols were not constructed
with the right macros, which could lead to errors on what should have
been valid ioctl() calls.</P
><P
>1998-11-14: V4L2_PIX_FMT_RGB24 changed to V4L2_PIX_FMT_BGR24. Same for
RGB32. Audio UI controls moved to VIDIOC_S_CTRL system and assigned
V4L2_CID_AUDIO_* symbols. Removed V4L2_MAJOR from videodev.h since it
is only used at one place in videodev. Added YUV422 and YUV411 planar
formats.</P
><P
>1998-11-28: Changed a few ioctl symbols. Added stuff for codec and
video output devices.</P
><P
>1999-01-14: Added raw VBI interface.</P
><P
>1999-01-19: Removed VIDIOC_NEXTBUF ioctl.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN10618"
>6.2.2. V4L2 Version 0.16 1999-01-31</A
></H3
><P
>1999-01-27: There is now one QBUF ioctl, VIDIOC_QWBUF and VIDIOC_QRBUF
are gone. VIDIOC_QBUF takes a v4l2_buffer as a parameter. Added
digital zoom (cropping) controls.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN10621"
>6.2.3. V4L2 Version 0.18 1999-03-16</A
></H3
><P
>Added a v4l to V4L2 ioctl compatibility layer to
videodev.c. Driver writers, this changes how you implement your ioctl
handler. See the Driver Writer's Guide. Added some more control id
codes.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN10624"
>6.2.4. V4L2 Version 0.19 1999-06-05</A
></H3
><P
>1999-03-18: Fill in the category and catname fields of
v4l2_queryctrl objects before passing them to the driver. Required a
minor change to the VIDIOC_QUERYCTRL handlers in the sample
drivers.</P
><P
>1999-03-31: Better compatibility for v4l memory capture
ioctls. Requires changes to drivers to fully support new compatibility
features, see Driver Writer's Guide and v4l2cap.c. Added new control
IDs: V4L2_CID_HFLIP, _VFLIP. Changed V4L2_PIX_FMT_YUV422P to _YUV422P,
and _YUV411P to _YUV411P.</P
><P
>1999-04-04: Added a few more control IDs.</P
><P
>1999-04-07: Added the button control type.</P
><P
>1999-05-02: Fixed a typo in videodev.h, and added the
V4L2_CTRL_FLAG_GRAYED (later V4L2_CTRL_FLAG_GRABBED) flag.</P
><P
>1999-05-20: Definition of VIDIOC_G_CTRL was wrong causing
a malfunction of this ioctl.</P
><P
>1999-06-05: Changed the value of
V4L2_CID_WHITENESS.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN10633"
>6.2.5. V4L2 Version 0.20 1999-09-10</A
></H3
><P
>Version 0.20 introduced a number of changes not backward
compatible with 0.19 and earlier. The purpose was to simplify the API,
while at the same time make it more extensible, and follow common
Linux driver API conventions.</P
><P
></P
><OL
TYPE="1"
><LI
><P
>Fixed typos in some V4L2_FMT_FLAG symbols. Changed
struct <A
HREF="#V4L2-CLIP"
>v4l2_clip</A
> to be compatible with v4l. (1999-08-30)</P
></LI
><LI
><P
>Added V4L2_TUNER_SUB_LANG1. (1999-09-05)</P
></LI
><LI
><P
>All ioctl() commands that took an integer argument
before, will now take a pointer to an integer. Where it makes sense,
the driver will return the actual value used in the integer pointed to
by the argument. This is a common convention, and also makes certain
things easier in libv4l2 and other system code when the parameter to
ioctl() is always a pointer. The ioctl commands affected are:
VIDIOC_PREVIEW, VIDIOC_STREAMON, VIDIOC_STREAMOFF, VIDIOC_S_FREQ,
VIDIOC_S_INPUT, VIDIOC_S_OUTPUT, VIDIOC_S_EFFECT. For example, where
before you might have had code like: <PRE
CLASS="PROGRAMLISTING"
>err = ioctl (fd, VIDIOC_XXX, V4L2_XXX);</PRE
> that becomes <PRE
CLASS="PROGRAMLISTING"
>int a = V4L2_XXX; err = ioctl(fd, VIDIOC_XXX, &a);</PRE
>
</P
></LI
><LI
><P
>All the different set-format ioctl() commands are
swept into a single set-format command whose parameter consists of an
integer value indicating the type of format, followed by the format
data. The same for the get-format commands, of course. This will
simplify the API by eliminating several ioctl codes and also make it
possible to add additional kinds of data streams, or driver-private
kinds of streams without having to add more set-format ioctls. The
parameter to VIDIOC_S_FMT is as follows. The first field is a
V4L2_BUF_TYPE_XXX value that indicates which stream the set-format is
for, and implicitly, what type of format data. After that is a union
of the different format structures. More can be added later without
breaking backward compatibility. Nonstandard driver-private formats
can be used by casting raw_data.</P
><P
><PRE
CLASS="PROGRAMLISTING"
>struct <A
HREF="#V4L2-FORMAT"
>v4l2_format</A
> {
__u32 type;
union {
struct <A
HREF="#V4L2-PIX-FORMAT"
>v4l2_pix_format</A
> pix;
struct <A
HREF="#V4L2-VBI-FORMAT"
>v4l2_vbi_format</A
> vbi;
... and so on ...
__u8 raw_data[200];
} fmt;
};
</PRE
></P
><P
>For a get-format, the application fills in the type
field, and the driver fills in the rest. What was before the image
format structure, struct <A
HREF="#V4L2-FORMAT"
>v4l2_format</A
>, becomes struct <A
HREF="#V4L2-PIX-FORMAT"
>v4l2_pix_format</A
>. These
ioctls become obsolete: VIDIOC_S_INFMT, VIDIOC_G_INFMT,
VIDIOC_S_OUTFMT, VIDIOC_G_OUTFMT, VIDIOC_S_VBIFMT
VIDIOC_G_VBIFMT.</P
></LI
><LI
><P
>Similar to item 2, VIDIOC_G/S_PARM and
VIDIOC_G/S_OUTPARM are merged, along with the corresponding 'get'
functions. A type field will indicate which stream the parameters are
for, set to a V4L2_BUF_TYPE_* value.</P
><P
><PRE
CLASS="PROGRAMLISTING"
>struct <A
HREF="#V4L2-STREAMPARM"
>v4l2_streamparm</A
> {
__u32 type;
union {
struct <A
HREF="#V4L2-CAPTUREPARM"
>v4l2_captureparm</A
> capture;
struct <A
HREF="#V4L2-OUTPUTPARM"
>v4l2_outputparm</A
> output;
__u8 raw_data[200];
} parm;
};
</PRE
></P
><P
>These ioctls become obsolete: VIDIOC_G_OUTPARM,
VIDIOC_S_OUTPARM.</P
></LI
><LI
><P
>The way controls are enumerated is simplified.
Simultaneously, two new control flags are introduced and the existing
flag is dropped. Also, the catname field is dropped in favor of a
group name. To enumerate controls call VIDIOC_QUERYCTRL with
successive id's starting from V4L2_CID_BASE or V4L2_CID_PRIVATE_BASE
and stop when the driver returns the EINVAL error code. Controls that
are not supported on the hardware are marked with the
V4L2_CTRL_FLAG_DISABLED flag.</P
><P
>Additionally, controls that are temporarily
unavailable, or that can only be controlled from another file
descriptor are marked with the V4L2_CTRL_FLAG_GRABBED flag. Usually, a
control that is GRABBED, but not DISABLED can be read, but changed.
The group name indicates a possibly narrower classification than the
category. In other words, there may be multiple groups within a
category. Controls within a group would typically be drawn within a
group box. Controls in different categories might have a greater
separation, or even be in separate windows.</P
></LI
><LI
><P
>The v4l2_buffer timestamp field is changed to a 64-bit
integer, and holds the time of the frame based on the system time, in
1 nanosecond units. Additionally, timestamps will be in absolute
system time, not starting from zero at the beginning of a stream as it
is now. The data type name for timestamps is stamp_t, defined as a
signed 64-bit integer. Output devices should not send a buffer out
until the time in the timestamp field has arrived. I would like to
follow SGI's lead, and adopt a multimedia timestamping system like
their UST (Unadjusted System Time). See
http://reality.sgi.com/cpirazzi_engr/lg/time/intro.html. [This link is
no longer valid.] UST uses timestamps that are 64-bit signed integers
(not struct timeval's) and given in nanosecond units. The UST clock
starts at zero when the system is booted and runs continuously and
uniformly. It takes a little over 292 years for UST to overflow. There
is no way to set the UST clock. The regular Linux time-of-day clock
can be changed periodically, which would cause errors if it were being
used for timestamping a multimedia stream. A real UST style clock will
require some support in the kernel that is not there yet. But in
anticipation, I will change the timestamp field to a 64-bit integer,
and I will change the v4l2_masterclock_gettime() function (used only
by drivers) to return a 64-bit integer.</P
></LI
><LI
><P
>The sequence field is added to the struct <A
HREF="#V4L2-BUFFER"
>v4l2_buffer</A
>. The
sequence field indicates which frame this is in the sequence-- 0, 1,
2, 3, 4, etc. Set by capturing devices. Ignored by output devices. If
a capture driver drops a frame, the sequence number of that frame is
skipped. A break in the sequence will indicate to the application
which frame was dropped.</P
></LI
></OL
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN10672"
>6.2.6. V4L2 Version 0.20 incremental changes</A
></H3
><P
>1999-12-23: In struct <A
HREF="#V4L2-VBI-FORMAT"
>v4l2_vbi_format</A
> field
<CODE
CLASS="STRUCTFIELD"
>reserved1</CODE
> became <CODE
CLASS="STRUCTFIELD"
>offset</CODE
>.
Previously <CODE
CLASS="STRUCTFIELD"
>reserved1</CODE
> was required to always read
zero.</P
><P
>2000-01-13: Added V4L2_FMT_FLAG_NOT_INTERLACED.</P
><P
>2000-07-31: Included linux/poll.h in videodev.h for compatibility with
the original videodev.h.</P
><P
>2000-11-20: Added V4L2_TYPE_VBI_OUTPUT. Added V4L2_PIX_FMT_Y41P.</P
><P
>2000-11-25: Added V4L2_TYPE_VBI_INPUT.</P
><P
>2000-12-04: Fixed a couple typos in symbol names.</P
><P
>2001-01-18: Fixed a namespace conflict (the fourcc macro changed to
v4l2_fourcc).</P
><P
>2001-01-25: Fixed a possible driver-level compatibility problem
between the original 2.4.0 videodev.h and the videodev.h that comes
with videodevX. If you were using an earlier version of videodevX on
2.4.0, then you should recompile your v4l and V4L2 drivers to be
safe.</P
><P
>2001-01-26: videodevX: Fixed a possible kernel-level incompatibility
between the videodevX videodev.h and the 2.2.x videodev.h that had the
devfs patches applied. videodev: Changed fourcc to v4l2_fourcc to
avoid namespace pollution. Some other cleanup.</P
><P
>2001-03-02: Certain v4l ioctls that really pass data both ways, but
whose types are read-only, did not work correctly through the backward
compatibility layer. [Solution?]</P
><P
>2001-04-13: Added big endian 16-bit RGB formats.</P
><P
>2001-09-17: Added new YUV formats. Added VIDIOC_G_FREQUENCY and
VIDIOC_S_FREQUENCY. (The VIDIOC_G/S_FREQ ioctls did not take multiple
tuners into account.)</P
><P
>2000-09-18: Added V4L2_BUF_TYPE_VBI. Raw VBI VIDIOC_G_FMT and
VIDIOC_S_FMT may fail if field <CODE
CLASS="STRUCTFIELD"
>type</CODE
> is not
V4L2_BUF_TYPE_VBI. Changed the ambiguous phrase "rising edge" to "leading
edge" in the definition of struct <A
HREF="#V4L2-VBI-FORMAT"
>v4l2_vbi_format</A
> field
<CODE
CLASS="STRUCTFIELD"
>offset</CODE
>.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN10694"
>6.2.7. V4L2 Version 0.20 2000-11-23</A
></H3
><P
>A number of changes were made to the raw VBI
interface.</P
><P
></P
><OL
TYPE="1"
><LI
><P
>Added figures clarifying the line numbering scheme.
The description of <CODE
CLASS="STRUCTFIELD"
>start</CODE
>[0] and
<CODE
CLASS="STRUCTFIELD"
>start</CODE
>[1] as base 0 offset has been dropped.
Rationale: a) The previous definition was unclear. b) The
<CODE
CLASS="STRUCTFIELD"
>start</CODE
>[] values are not an offset into anything,
as a means of identifying scanning lines it can only be
counterproductive to deviate from common numbering conventions.
Compatibility: Add one to the start values. Applications depending on
the previous semantics of start values may not function
correctly.</P
></LI
><LI
><P
>The restriction "count[0] > 0 and count[1] > 0" has
been relaxed to "(count[0] + count[1]) > 0". Rationale: Drivers
allocating resources at scanning line granularity and first field only
data services. The comment that both 'count' values will usually be
equal is misleading and pointless and has been removed. Compatibility:
Drivers may return EINVAL, applications depending on the previous
restriction may not function correctly.</P
></LI
><LI
><P
>Restored description of the driver option to return
negative start values. Existed in the initial revision of this
document, not traceable why it disappeared in later versions.
Compatibility: Applications depending on the returned start values
being positive may not function correctly. Clarification on the use of
EBUSY and EINVAL in VIDIOC_S_FMT ioctl. Added EBUSY paragraph to
section. Added description of reserved2, previously mentioned only in
videodev.h.</P
></LI
><LI
><P
>Added V4L2_TYPE_VBI_INPUT and V4L2_TYPE_VBI_OUTPUT
here and in videodev.h. The first is an alias for the older
V4L2_TYPE_VBI, the latter was missing in videodev.h.</P
></LI
></OL
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN10709"
>6.2.8. V4L2 Version 0.20 2002-07-25</A
></H3
><P
>Added sliced VBI interface proposal.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN10712"
>6.2.9. V4L2 in Linux 2.5.46, 2002-10</A
></H3
><P
>Around October-November 2002, prior to an announced
feature freeze of Linux 2.5, the API was revised, drawing from
experience with V4L2 0.20. This unnamed version was finally merged
into Linux 2.5.46.</P
><P
></P
><OL
TYPE="1"
><LI
><P
>As specified in <A
HREF="#RELATED"
>Section 1.1.2</A
> drivers
must make related device functions available under all minor device
numbers.</P
></LI
><LI
><P
>The <A
HREF="#FUNC-OPEN"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
> function requires access mode
<CODE
CLASS="CONSTANT"
>O_RDWR</CODE
> regardless of device type. All V4L2
drivers exchanging data with applications must support the
<CODE
CLASS="CONSTANT"
>O_NONBLOCK</CODE
> flag. The <CODE
CLASS="CONSTANT"
>O_NOIO</CODE
>
flag (alias of meaningless <CODE
CLASS="CONSTANT"
>O_TRUNC</CODE
>) to indicate
accesses without data exchange (panel applications) was
dropped. Drivers must assume panel mode until the application attempts
to initiate data exchange, see <A
HREF="#OPEN"
>Section 1.1</A
>.</P
></LI
><LI
><P
>The struct <A
HREF="#V4L2-CAPABILITY"
>v4l2_capability</A
> changed dramatically. Note that
also the size of the structure changed, which is encoded in the ioctl
request code, thus older V4L2 devices will respond with an <SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code to
the new <A
HREF="#VIDIOC-QUERYCAP"
><CODE
CLASS="CONSTANT"
>VIDIOC_QUERYCAP</CODE
></A
> ioctl.</P
><P
>There are new fields to identify the driver, a new (as
of yet unspecified) device function
<CODE
CLASS="CONSTANT"
>V4L2_CAP_RDS_CAPTURE</CODE
>, the
<CODE
CLASS="CONSTANT"
>V4L2_CAP_AUDIO</CODE
> flag indicates if the device has
any audio connectors, another I/O capability
<CODE
CLASS="CONSTANT"
>V4L2_CAP_ASYNCIO</CODE
> can be flagged. Field
<CODE
CLASS="STRUCTFIELD"
>type</CODE
> became a set in response to the change
above and was merged with <CODE
CLASS="STRUCTFIELD"
>flags</CODE
>.
<CODE
CLASS="CONSTANT"
>V4L2_FLAG_TUNER</CODE
> was renamed to
<CODE
CLASS="CONSTANT"
>V4L2_CAP_TUNER</CODE
>,
<CODE
CLASS="CONSTANT"
>V4L2_CAP_VIDEO_OVERLAY</CODE
> replaced
<CODE
CLASS="CONSTANT"
>V4L2_FLAG_PREVIEW</CODE
> and
<CODE
CLASS="CONSTANT"
>V4L2_CAP_VBI_CAPTURE</CODE
> and
<CODE
CLASS="CONSTANT"
>V4L2_CAP_VBI_OUTPUT</CODE
> replaced
<CODE
CLASS="CONSTANT"
>V4L2_FLAG_DATA_SERVICE</CODE
>.
<CODE
CLASS="CONSTANT"
>V4L2_FLAG_READ</CODE
> and
<CODE
CLASS="CONSTANT"
>V4L2_FLAG_WRITE</CODE
> merged to
<CODE
CLASS="CONSTANT"
>V4L2_CAP_READWRITE</CODE
>.</P
><P
>Redundant fields
<CODE
CLASS="STRUCTFIELD"
>inputs</CODE
>, <CODE
CLASS="STRUCTFIELD"
>outputs</CODE
>,
<CODE
CLASS="STRUCTFIELD"
>audios</CODE
> were removed, these can be
determined as described in <A
HREF="#VIDEO"
>Section 1.4</A
> and <A
HREF="#AUDIO"
>Section 1.5</A
>.</P
><P
>The somewhat volatile and therefore
barely useful fields <CODE
CLASS="STRUCTFIELD"
>maxwidth</CODE
>,
<CODE
CLASS="STRUCTFIELD"
>maxheight</CODE
>,
<CODE
CLASS="STRUCTFIELD"
>minwidth</CODE
>,
<CODE
CLASS="STRUCTFIELD"
>minheight</CODE
>,
<CODE
CLASS="STRUCTFIELD"
>maxframerate</CODE
> were removed, this information
is available as described in <A
HREF="#FORMAT"
>Section 1.9</A
> and
<A
HREF="#STANDARD"
>Section 1.7</A
>.</P
><P
><CODE
CLASS="CONSTANT"
>V4L2_FLAG_SELECT</CODE
>
was removed, this function is considered important enough that all
V4L2 drivers exchanging data with applications must support
<CODE
CLASS="FUNCTION"
>select()</CODE
>. The redundant flag
<CODE
CLASS="CONSTANT"
>V4L2_FLAG_MONOCHROME</CODE
> was removed, this
information is available as described in <A
HREF="#FORMAT"
>Section 1.9</A
>.</P
></LI
><LI
><P
>In struct <A
HREF="#V4L2-INPUT"
>v4l2_input</A
> the
<CODE
CLASS="STRUCTFIELD"
>assoc_audio</CODE
> field and the
<CODE
CLASS="STRUCTFIELD"
>capability</CODE
> field and its only
flag <CODE
CLASS="CONSTANT"
>V4L2_INPUT_CAP_AUDIO</CODE
> was replaced
by the new <CODE
CLASS="STRUCTFIELD"
>audioset</CODE
>
field. Instead of linking one video input to one audio input
this field reports all audio inputs this video input
combines with.</P
><P
>New fields are <CODE
CLASS="STRUCTFIELD"
>tuner</CODE
>
(reversing the former link from tuners to video inputs),
<CODE
CLASS="STRUCTFIELD"
>std</CODE
> and
<CODE
CLASS="STRUCTFIELD"
>status</CODE
>.</P
><P
>Accordingly struct <A
HREF="#V4L2-OUTPUT"
>v4l2_output</A
> lost its
<CODE
CLASS="STRUCTFIELD"
>capability</CODE
> and
<CODE
CLASS="STRUCTFIELD"
>assoc_audio</CODE
> fields,
<CODE
CLASS="STRUCTFIELD"
>audioset</CODE
>,
<CODE
CLASS="STRUCTFIELD"
>modulator</CODE
> and
<CODE
CLASS="STRUCTFIELD"
>std</CODE
> where added.</P
></LI
><LI
><P
>The struct <A
HREF="#V4L2-AUDIO"
>v4l2_audio</A
> field
<CODE
CLASS="STRUCTFIELD"
>audio</CODE
> was renamed to
<CODE
CLASS="STRUCTFIELD"
>index</CODE
>, consistent with other structures.
Capability flag <CODE
CLASS="CONSTANT"
>V4L2_AUDCAP_STEREO</CODE
> was added to
indicated if this is a stereo input.
<CODE
CLASS="CONSTANT"
>V4L2_AUDCAP_EFFECTS</CODE
> and the corresponding
<CODE
CLASS="CONSTANT"
>V4L2_AUDMODE</CODE
> flags where removed, this can be
easily implemented using controls. (However the same applies to AVL
which is still there.)</P
><P
>The struct <A
HREF="#V4L2-AUDIOOUT"
>v4l2_audioout</A
> field
<CODE
CLASS="STRUCTFIELD"
>audio</CODE
> was renamed to
<CODE
CLASS="STRUCTFIELD"
>index</CODE
>.</P
></LI
><LI
><P
>The struct <A
HREF="#V4L2-TUNER"
>v4l2_tuner</A
>
<CODE
CLASS="STRUCTFIELD"
>input</CODE
> field was replaced by an
<CODE
CLASS="STRUCTFIELD"
>index</CODE
> field, permitting devices with
multiple tuners. The link between video inputs and tuners is now
reversed, inputs point to the tuner they are on. The
<CODE
CLASS="STRUCTFIELD"
>std</CODE
> substructure became a
simple set (more about this below) and moved into struct <A
HREF="#V4L2-INPUT"
>v4l2_input</A
>. A
<CODE
CLASS="STRUCTFIELD"
>type</CODE
> field was added.</P
><P
>Accordingly in struct <A
HREF="#V4L2-MODULATOR"
>v4l2_modulator</A
> the
<CODE
CLASS="STRUCTFIELD"
>output</CODE
> was replaced by an
<CODE
CLASS="STRUCTFIELD"
>index</CODE
> field.</P
><P
>In struct <A
HREF="#V4L2-FREQUENCY"
>v4l2_frequency</A
> the
<CODE
CLASS="STRUCTFIELD"
>port</CODE
> field was replaced by a
<CODE
CLASS="STRUCTFIELD"
>tuner</CODE
> field containing the respective tuner
or modulator index number. A tuner <CODE
CLASS="STRUCTFIELD"
>type</CODE
>
field was added and the <CODE
CLASS="STRUCTFIELD"
>reserved</CODE
> field
became larger for future extensions (satellite tuners in
particular).</P
></LI
><LI
><P
>The idea of completely transparent video standards was
dropped. Experience showed that applications must be able to work with
video standards beyond presenting the user a menu. To this end V4L2
returned to defined standards as <A
HREF="#V4L2-STD-ID"
>v4l2_std_id</A
>, replacing references
to standards throughout the API. For details see <A
HREF="#STANDARD"
>Section 1.7</A
>. <A
HREF="#VIDIOC-G-STD"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_STD</CODE
></A
> and <A
HREF="#VIDIOC-G-STD"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_STD</CODE
></A
>
now take a pointer to this type as argument. <A
HREF="#VIDIOC-QUERYSTD"
><CODE
CLASS="CONSTANT"
>VIDIOC_QUERYSTD</CODE
></A
> was
added to autodetect the received standard. In struct <A
HREF="#V4L2-STANDARD"
>v4l2_standard</A
> an
<CODE
CLASS="STRUCTFIELD"
>index</CODE
> field was added for <A
HREF="#VIDIOC-ENUMSTD"
><CODE
CLASS="CONSTANT"
>VIDIOC_ENUMSTD</CODE
></A
>.
A <A
HREF="#V4L2-STD-ID"
>v4l2_std_id</A
> field named <CODE
CLASS="STRUCTFIELD"
>id</CODE
> was added as
machine readable identifier, also replacing the
<CODE
CLASS="STRUCTFIELD"
>transmission</CODE
> field.
<CODE
CLASS="STRUCTFIELD"
>framerate</CODE
>, which is misleading, was renamed
to <CODE
CLASS="STRUCTFIELD"
>frameperiod</CODE
>. The now obsolete
<CODE
CLASS="STRUCTFIELD"
>colorstandard</CODE
> information, originally
needed to distguish between variations of standards, were
removed.</P
><P
>Struct <CODE
CLASS="STRUCTNAME"
>v4l2_enumstd</CODE
> ceased to
be. <A
HREF="#VIDIOC-ENUMSTD"
><CODE
CLASS="CONSTANT"
>VIDIOC_ENUMSTD</CODE
></A
> now takes a pointer to a struct <A
HREF="#V4L2-STANDARD"
>v4l2_standard</A
>
directly. The information which standards are supported by a
particular video input or output moved into struct <A
HREF="#V4L2-INPUT"
>v4l2_input</A
> and
struct <A
HREF="#V4L2-OUTPUT"
>v4l2_output</A
> fields named <CODE
CLASS="STRUCTFIELD"
>std</CODE
>,
respectively.</P
></LI
><LI
><P
>The struct <A
HREF="#V4L2-QUERYCTRL"
>v4l2_queryctrl</A
> fields
<CODE
CLASS="STRUCTFIELD"
>category</CODE
> and
<CODE
CLASS="STRUCTFIELD"
>group</CODE
> did not catch on and/or were not
implemented as expected and therefore removed.</P
></LI
><LI
><P
>The <A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_TRY_FMT</CODE
></A
> ioctl was added to negotiate data
formats as with <A
HREF="#VIDIOC-G-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
></A
>, but without the overhead of
programming the hardware and regardless of I/O in progress.</P
><P
>In struct <A
HREF="#V4L2-FORMAT"
>v4l2_format</A
> the <CODE
CLASS="STRUCTFIELD"
>fmt</CODE
>
union was extended to contain struct <A
HREF="#V4L2-WINDOW"
>v4l2_window</A
>. As a result
all data format negotiation is now possible with
<CODE
CLASS="CONSTANT"
>VIDIOC_G_FMT</CODE
>,
<CODE
CLASS="CONSTANT"
>VIDIOC_S_FMT</CODE
> and
<CODE
CLASS="CONSTANT"
>VIDIOC_TRY_FMT</CODE
>; the
<CODE
CLASS="CONSTANT"
>VIDIOC_G_WIN</CODE
>,
<CODE
CLASS="CONSTANT"
>VIDIOC_S_WIN</CODE
> and ioctl to prepare for
overlay were removed. The <CODE
CLASS="STRUCTFIELD"
>type</CODE
>
field changed to type enum <A
HREF="#V4L2-BUF-TYPE"
>v4l2_buf_type</A
> and the buffer type
names changed as follows.<DIV
CLASS="INFORMALTABLE"
><P
></P
><A
NAME="AEN10867"
></A
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><COL><COL><THEAD
><TR
><TH
>Old defines</TH
><TH
>enum <A
HREF="#V4L2-BUF-TYPE"
>v4l2_buf_type</A
></TH
></TR
></THEAD
><TBODY
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_CAPTURE</CODE
></TD
><TD
><CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_VIDEO_CAPTURE</CODE
></TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_CODECIN</CODE
></TD
><TD
><CODE
CLASS="CONSTANT"
>Preliminary omitted</CODE
></TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_CODECOUT</CODE
></TD
><TD
><CODE
CLASS="CONSTANT"
>Preliminary omitted</CODE
></TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_EFFECTSIN</CODE
></TD
><TD
><CODE
CLASS="CONSTANT"
>Preliminary omitted</CODE
></TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_EFFECTSIN2</CODE
></TD
><TD
><CODE
CLASS="CONSTANT"
>Preliminary omitted</CODE
></TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_EFFECTSOUT</CODE
></TD
><TD
><CODE
CLASS="CONSTANT"
>Preliminary omitted</CODE
></TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_VIDEOOUT</CODE
></TD
><TD
><CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_VIDEO_OUTPUT</CODE
></TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>-</CODE
></TD
><TD
><CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_VIDEO_OVERLAY</CODE
></TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>-</CODE
></TD
><TD
><CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_VBI_CAPTURE</CODE
></TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>-</CODE
></TD
><TD
><CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_VBI_OUTPUT</CODE
></TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_PRIVATE_BASE</CODE
></TD
><TD
><CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_PRIVATE</CODE
></TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
></P
></LI
><LI
><P
>In struct <A
HREF="#V4L2-FMTDESC"
>v4l2_fmtdesc</A
> a enum <A
HREF="#V4L2-BUF-TYPE"
>v4l2_buf_type</A
> field named
<CODE
CLASS="STRUCTFIELD"
>type</CODE
> was added as in struct <A
HREF="#V4L2-FORMAT"
>v4l2_format</A
>. As a
result the <CODE
CLASS="CONSTANT"
>VIDIOC_ENUM_FBUFFMT</CODE
> ioctl is no longer
needed and was removed. These calls can be replaced by
<A
HREF="#VIDIOC-ENUM-FMT"
><CODE
CLASS="CONSTANT"
>VIDIOC_ENUM_FMT</CODE
></A
> with type
<CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_VIDEO_OVERLAY</CODE
>.</P
></LI
><LI
><P
>In struct <A
HREF="#V4L2-PIX-FORMAT"
>v4l2_pix_format</A
> the
<CODE
CLASS="STRUCTFIELD"
>depth</CODE
> was removed, assuming applications
recognizing the format are aware of the image depth and others need
not know. The same rationale lead to the removal of the
<CODE
CLASS="CONSTANT"
>V4L2_FMT_FLAG_COMPRESSED</CODE
> flag. The
<CODE
CLASS="CONSTANT"
>V4L2_FMT_FLAG_SWCONVECOMPRESSED</CODE
> flag was removed
because drivers are not supposed to convert image formats in kernel
space. The <CODE
CLASS="CONSTANT"
>V4L2_FMT_FLAG_BYTESPERLINE</CODE
> flag was
redundant, applications can set the
<CODE
CLASS="STRUCTFIELD"
>bytesperline</CODE
> field to zero to get a
reasonable default. Since also the remaining flags were replaced, the
<CODE
CLASS="STRUCTFIELD"
>flags</CODE
> field itself was removed.</P
><P
>The interlace flags were replaced by a enum <A
HREF="#V4L2-FIELD"
>v4l2_field</A
>
value in a newly added <CODE
CLASS="STRUCTFIELD"
>field</CODE
> field.<DIV
CLASS="INFORMALTABLE"
><P
></P
><A
NAME="AEN10952"
></A
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><COL><COL><THEAD
><TR
><TH
>Old flag</TH
><TH
>enum <A
HREF="#V4L2-FIELD"
>v4l2_field</A
></TH
></TR
></THEAD
><TBODY
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_FMT_FLAG_NOT_INTERLACED</CODE
></TD
><TD
><CODE
CLASS="CONSTANT"
>?</CODE
></TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_FMT_FLAG_INTERLACED</CODE
>
= <CODE
CLASS="CONSTANT"
>V4L2_FMT_FLAG_COMBINED</CODE
></TD
><TD
><CODE
CLASS="CONSTANT"
>V4L2_FIELD_INTERLACED</CODE
></TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_FMT_FLAG_TOPFIELD</CODE
>
= <CODE
CLASS="CONSTANT"
>V4L2_FMT_FLAG_ODDFIELD</CODE
></TD
><TD
><CODE
CLASS="CONSTANT"
>V4L2_FIELD_TOP</CODE
></TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_FMT_FLAG_BOTFIELD</CODE
>
= <CODE
CLASS="CONSTANT"
>V4L2_FMT_FLAG_EVENFIELD</CODE
></TD
><TD
><CODE
CLASS="CONSTANT"
>V4L2_FIELD_BOTTOM</CODE
></TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>-</CODE
></TD
><TD
><CODE
CLASS="CONSTANT"
>V4L2_FIELD_SEQ_TB</CODE
></TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>-</CODE
></TD
><TD
><CODE
CLASS="CONSTANT"
>V4L2_FIELD_SEQ_BT</CODE
></TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>-</CODE
></TD
><TD
><CODE
CLASS="CONSTANT"
>V4L2_FIELD_ALTERNATE</CODE
></TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
></P
><P
>The color space flags were replaced by a
enum <A
HREF="#V4L2-COLORSPACE"
>v4l2_colorspace</A
> value in a newly added
<CODE
CLASS="STRUCTFIELD"
>colorspace</CODE
> field, where one of
<CODE
CLASS="CONSTANT"
>V4L2_COLORSPACE_SMPTE170M</CODE
>,
<CODE
CLASS="CONSTANT"
>V4L2_COLORSPACE_BT878</CODE
>,
<CODE
CLASS="CONSTANT"
>V4L2_COLORSPACE_470_SYSTEM_M</CODE
> or
<CODE
CLASS="CONSTANT"
>V4L2_COLORSPACE_470_SYSTEM_BG</CODE
> replaces
<CODE
CLASS="CONSTANT"
>V4L2_FMT_CS_601YUV</CODE
>.</P
></LI
><LI
><P
>In struct <A
HREF="#V4L2-REQUESTBUFFERS"
>v4l2_requestbuffers</A
> the
<CODE
CLASS="STRUCTFIELD"
>type</CODE
> field was properly typed as
enum <A
HREF="#V4L2-BUF-TYPE"
>v4l2_buf_type</A
>. Buffer types changed as mentioned above. A new
<CODE
CLASS="STRUCTFIELD"
>memory</CODE
> field of type enum <A
HREF="#V4L2-MEMORY"
>v4l2_memory</A
> was
added to distinguish between mapping methods using buffers allocated
by the driver or the application. See <A
HREF="#IO"
>Chapter 3</A
> for
details.</P
></LI
><LI
><P
>In struct <A
HREF="#V4L2-BUFFER"
>v4l2_buffer</A
> the <CODE
CLASS="STRUCTFIELD"
>type</CODE
>
field was properly typed as enum <A
HREF="#V4L2-BUF-TYPE"
>v4l2_buf_type</A
>. Buffer types changed as
mentioned above. A <CODE
CLASS="STRUCTFIELD"
>field</CODE
> field of type
enum <A
HREF="#V4L2-FIELD"
>v4l2_field</A
> was added to indicate if a buffer contains a top or
bottom field, the field flags were removed. Realizing the efforts to
introduce an unadjusted system time clock failed, the
<CODE
CLASS="STRUCTFIELD"
>timestamp</CODE
> field changed back from type
stamp_t, an unsigned 64 bit integer expressing time in nanoseconds, to
struct <CODE
CLASS="STRUCTNAME"
>timeval</CODE
>. With the addition of a second
memory mapping method the <CODE
CLASS="STRUCTFIELD"
>offset</CODE
> field
moved into union <CODE
CLASS="STRUCTFIELD"
>m</CODE
>, and a new
<CODE
CLASS="STRUCTFIELD"
>memory</CODE
> field of type enum <A
HREF="#V4L2-MEMORY"
>v4l2_memory</A
> was
added to distinguish between mapping methods. See <A
HREF="#IO"
>Chapter 3</A
>
for details.</P
><P
>The <CODE
CLASS="CONSTANT"
>V4L2_BUF_REQ_CONTIG</CODE
>
flag was used by the V4L compatibility layer, after changes to this
code it was no longer needed. The
<CODE
CLASS="CONSTANT"
>V4L2_BUF_ATTR_DEVICEMEM</CODE
> flag would indicate if
the buffer was indeed allocated in device memory rather than DMA-able
system memory. It was barely useful and so has been removed.</P
></LI
><LI
><P
>In struct <A
HREF="#V4L2-FRAMEBUFFER"
>v4l2_framebuffer</A
> the
<CODE
CLASS="STRUCTFIELD"
>base[3]</CODE
> array anticipating double- and
triple-buffering in off-screen video memory, however without defining
a synchronization mechanism, was replaced by a single
pointer. The <CODE
CLASS="CONSTANT"
>V4L2_FBUF_CAP_SCALEUP</CODE
> and
<CODE
CLASS="CONSTANT"
>V4L2_FBUF_CAP_SCALEDOWN</CODE
> flags were
removed. Applications can determine this capability more
accurately using the new cropping and scaling interface. The
<CODE
CLASS="CONSTANT"
>V4L2_FBUF_CAP_CLIPPING</CODE
> flag was
replaced by <CODE
CLASS="CONSTANT"
>V4L2_FBUF_CAP_LIST_CLIPPING</CODE
>
and <CODE
CLASS="CONSTANT"
>V4L2_FBUF_CAP_BITMAP_CLIPPING</CODE
>.</P
></LI
><LI
><P
>In struct <A
HREF="#V4L2-CLIP"
>v4l2_clip</A
> the <CODE
CLASS="STRUCTFIELD"
>x</CODE
>,
<CODE
CLASS="STRUCTFIELD"
>y</CODE
>, <CODE
CLASS="STRUCTFIELD"
>width</CODE
> and
<CODE
CLASS="STRUCTFIELD"
>height</CODE
> field moved into a
<CODE
CLASS="STRUCTFIELD"
>c</CODE
> substructure of type struct <A
HREF="#V4L2-RECT"
>v4l2_rect</A
>. The
<CODE
CLASS="STRUCTFIELD"
>x</CODE
> and <CODE
CLASS="STRUCTFIELD"
>y</CODE
> field
were renamed to <CODE
CLASS="STRUCTFIELD"
>left</CODE
> and
<CODE
CLASS="STRUCTFIELD"
>top</CODE
>, i. e. offsets to a context dependent
origin.</P
></LI
><LI
><P
>In struct <A
HREF="#V4L2-WINDOW"
>v4l2_window</A
> the <CODE
CLASS="STRUCTFIELD"
>x</CODE
>,
<CODE
CLASS="STRUCTFIELD"
>y</CODE
>, <CODE
CLASS="STRUCTFIELD"
>width</CODE
> and
<CODE
CLASS="STRUCTFIELD"
>height</CODE
> field moved into a
<CODE
CLASS="STRUCTFIELD"
>w</CODE
> substructure as above. A
<CODE
CLASS="STRUCTFIELD"
>field</CODE
> field of type %v4l2-field; was added
to distinguish between field and frame (interlaced) overlay.</P
></LI
><LI
><P
>The digital zoom interface, including struct
<CODE
CLASS="STRUCTNAME"
>v4l2_zoomcap</CODE
>, struct
<CODE
CLASS="STRUCTNAME"
>v4l2_zoom</CODE
>,
<CODE
CLASS="CONSTANT"
>V4L2_ZOOM_NONCAP</CODE
> and
<CODE
CLASS="CONSTANT"
>V4L2_ZOOM_WHILESTREAMING</CODE
> was replaced by a new
cropping and scaling interface. The previously unused struct
<CODE
CLASS="STRUCTNAME"
>v4l2_cropcap</CODE
> and
<CODE
CLASS="STRUCTNAME"
>v4l2_crop</CODE
> where redefined for this purpose.
See <A
HREF="#CROP"
>Section 1.10</A
> for details.</P
></LI
><LI
><P
>In struct <A
HREF="#V4L2-VBI-FORMAT"
>v4l2_vbi_format</A
> the
<CODE
CLASS="STRUCTFIELD"
>SAMPLE_FORMAT</CODE
> field now contains a
four-character-code as used to identify video image formats.
<CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_GREY</CODE
> replaces the
<CODE
CLASS="CONSTANT"
>V4L2_VBI_SF_UBYTE</CODE
> define. The
<CODE
CLASS="STRUCTFIELD"
>reserved</CODE
> field was extended.</P
></LI
><LI
><P
>In struct <A
HREF="#V4L2-CAPTUREPARM"
>v4l2_captureparm</A
> the type of the
<CODE
CLASS="STRUCTFIELD"
>timeperframe</CODE
> field changed from unsigned
long to struct <A
HREF="#V4L2-FRACT"
>v4l2_fract</A
>. A new field
<CODE
CLASS="STRUCTFIELD"
>readbuffers</CODE
> was added to control the driver
behaviour in read I/O mode.</P
><P
>According changes were made to
struct <A
HREF="#V4L2-OUTPUTPARM"
>v4l2_outputparm</A
>.</P
></LI
><LI
><P
>The struct <CODE
CLASS="STRUCTNAME"
>v4l2_performance</CODE
>
and <CODE
CLASS="CONSTANT"
>VIDIOC_G_PERF</CODE
> ioctl were dropped. Except when
using the <A
HREF="#RW"
>read/write I/O method</A
>, which is
limited anyway, this information is already available to the
application.</P
></LI
><LI
><P
>The example transformation from RGB to YCbCr color
space in the old V4L2 documentation was inaccurate, this has been
corrected in <A
HREF="#PIXFMT"
>Chapter 2</A
>.</P
></LI
></OL
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN11094"
>6.2.10. V4L2 2003-06-19</A
></H3
><P
></P
><OL
TYPE="1"
><LI
><P
>A new capability flag
<CODE
CLASS="CONSTANT"
>V4L2_CAP_RADIO</CODE
> was added for radio devices. Prior
to this change radio devices would identify soley by having exactly one
tuner whose type field reads <CODE
CLASS="CONSTANT"
>V4L2_TUNER_RADIO</CODE
>.</P
></LI
><LI
><P
>An optional priority mechanism was added, see <A
HREF="#APP-PRI"
>Section 1.3</A
> for details.</P
></LI
><LI
><P
>The audio input and output interface was found to be
incomplete.</P
><P
>Previously the <CODE
CLASS="CONSTANT"
>VIDIOC_G_AUDIO</CODE
>
ioctl would enumerate the available audio inputs. An ioctl to
determine the current audio input, if more than one combines with the
current video input, did not exist. So
<CODE
CLASS="CONSTANT"
>VIDIOC_G_AUDIO</CODE
> was renamed to
<CODE
CLASS="CONSTANT"
>VIDIOC_G_AUDIO_OLD</CODE
>, this ioctl will be removed in
the future. The <A
HREF="#VIDIOC-ENUMAUDIO"
><CODE
CLASS="CONSTANT"
>VIDIOC_ENUMAUDIO</CODE
></A
> ioctl was added to enumerate
audio inputs, while <A
HREF="#VIDIOC-G-AUDIO"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_AUDIO</CODE
></A
> now reports the current audio
input.</P
><P
>The same changes were made to <A
HREF="#VIDIOC-G-AUDIOOUT"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_AUDOUT</CODE
></A
> and
<A
HREF="#VIDIOC-ENUMAUDIOOUT"
><CODE
CLASS="CONSTANT"
>VIDIOC_ENUMAUDOUT</CODE
></A
>.</P
><P
>Until further the "videodev" module will automatically
translate to the new versions, drivers and applications must be updated
when they are recompiled.</P
></LI
><LI
><P
>The <A
HREF="#VIDIOC-OVERLAY"
><CODE
CLASS="CONSTANT"
>VIDIOC_OVERLAY</CODE
></A
> ioctl was incorrectly defined with
read-write parameter. It was changed to write-only, while the read-write
version was renamed to <CODE
CLASS="CONSTANT"
>VIDIOC_OVERLAY_OLD</CODE
>. This
function will be removed in the future. Until further the "videodev"
module will automatically translate to the new version, so drivers
must be recompiled, but not applications.</P
></LI
><LI
><P
><A
HREF="#OVERLAY"
>Section 4.2</A
> incorrectly stated that
clipping rectangles define regions where the video can be seen.
Correct is that clipping rectangles define regions where
<SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>no</I
></SPAN
> video shall be displayed and so the graphics
surface can be seen.</P
></LI
><LI
><P
>The <A
HREF="#VIDIOC-G-PARM"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_PARM</CODE
></A
> and <A
HREF="#VIDIOC-G-CTRL"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_CTRL</CODE
></A
> were defined
with write-only parameter, inconsistent with other ioctls modifying
their argument. They were changed to read-write, while a
<CODE
CLASS="CONSTANT"
>_OLD</CODE
> suffix was added to the write-only version.
These functions will be removed in the future. Drivers, and
applications assuming a constant parameter, need an update.</P
></LI
></OL
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN11136"
>6.2.11. V4L2 2003-11-05</A
></H3
><P
></P
><OL
TYPE="1"
><LI
><P
>In <A
HREF="#PIXFMT-RGB"
>Section 2.3</A
> the following pixel
formats were incorrectly transferred from Bill Dirks' V4L2
specification. Descriptions refer to bytes in memory, in ascending
address order.<DIV
CLASS="INFORMALTABLE"
><P
></P
><A
NAME="AEN11142"
></A
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><COL><COL><COL><THEAD
><TR
><TH
>Symbol</TH
><TH
>In this document prior to revision 0.5</TH
><TH
>Correct</TH
></TR
></THEAD
><TBODY
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_RGB24</CODE
></TD
><TD
>B, G, R</TD
><TD
>R, G, B</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_BGR24</CODE
></TD
><TD
>R, G, B</TD
><TD
>B, G, R</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_RGB32</CODE
></TD
><TD
>B, G, R, X</TD
><TD
>R, G, B, X</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_BGR32</CODE
></TD
><TD
>R, G, B, X</TD
><TD
>B, G, R, X</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
> The
<CODE
CLASS="CONSTANT"
>V4L2_PIX_FMT_BGR24</CODE
> example was always
correct.</P
><P
>In <A
HREF="#V4L-IMAGE-PROPERTIES"
>Section 6.1.5</A
> the mapping of
<CODE
CLASS="CONSTANT"
>VIDEO_PALETTE_RGB24</CODE
> and
<CODE
CLASS="CONSTANT"
>VIDEO_PALETTE_RGB32</CODE
> to V4L2 pixel formats was accordingly corrected.</P
></LI
><LI
><P
>Unrelated to the fixes above, drivers may still interpret some V4L2 RGB pixel formats differently. These issues have yet to be addressed, for details see <A
HREF="#PIXFMT-RGB"
>Section 2.3</A
>.</P
></LI
></OL
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN11178"
>6.2.12. V4L2 in Linux 2.6.6, 2004-05-09</A
></H3
><P
></P
><OL
TYPE="1"
><LI
><P
>The <A
HREF="#VIDIOC-CROPCAP"
><CODE
CLASS="CONSTANT"
>VIDIOC_CROPCAP</CODE
></A
> ioctl was incorrectly defined with
read-only parameter. It was changed to read-write, while the read-only
version was renamed to <CODE
CLASS="CONSTANT"
>VIDIOC_CROPCAP_OLD</CODE
>. This
function will be removed in the future.</P
></LI
></OL
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN11186"
>6.2.13. V4L2 in Linux 2.6.8</A
></H3
><P
></P
><OL
TYPE="1"
><LI
><P
>A new field <CODE
CLASS="STRUCTFIELD"
>input</CODE
> (former
<CODE
CLASS="STRUCTFIELD"
>reserved[0]</CODE
>) was added to the
struct <A
HREF="#V4L2-BUFFER"
>v4l2_buffer</A
> structure. It must be enabled with the new
<CODE
CLASS="CONSTANT"
>V4L2_BUF_FLAG_INPUT</CODE
> flag. The
<CODE
CLASS="STRUCTFIELD"
>flags</CODE
> field is no longer read-only.</P
></LI
></OL
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN11196"
>6.2.14. V4L2 spec erratum 2004-08-01</A
></H3
><P
></P
><OL
TYPE="1"
><LI
><P
>The return value of the
<A
HREF="#FUNC-OPEN"
>open</A
> function was incorrect.</P
></LI
><LI
><P
>Audio output ioctls end in -AUDOUT, not -AUDIOOUT.</P
></LI
><LI
><P
>In the current audio input example the
<CODE
CLASS="CONSTANT"
>VIDIOC_G_AUDIO</CODE
> ioctl took the wrong
argument.</P
></LI
><LI
><P
>The <A
HREF="#VIDIOC-QBUF"
><CODE
CLASS="CONSTANT"
>VIDIOC_QBUF</CODE
></A
> and <A
HREF="#VIDIOC-QBUF"
><CODE
CLASS="CONSTANT"
>VIDIOC_DQBUF</CODE
></A
> ioctl did not
mention the struct <A
HREF="#V4L2-BUFFER"
>v4l2_buffer</A
> <CODE
CLASS="STRUCTFIELD"
>memory</CODE
> field, it
was also missing from examples. Added description of the
<CODE
CLASS="CONSTANT"
>VIDIOC_DQBUF</CODE
> <CODE
CLASS="CONSTANT"
>EIO</CODE
> error.</P
></LI
></OL
></DIV
></DIV
><DIV
CLASS="SECTION"
><HR><H2
CLASS="SECTION"
><A
NAME="OTHER"
>6.3. Relation of V4L2 to other Linux multimedia APIs</A
></H2
><DIV
CLASS="SECTION"
><H3
CLASS="SECTION"
><A
NAME="XVIDEO"
>6.3.1. X Video Extension</A
></H3
><P
>The X Video Extension (abbreviated XVideo or just Xv) is
an extension of the X Window system, implemented for example by the
XFree86 project. Its scope is similar to V4L2, an API to video capture
and output devices for X clients. Xv allows applications to display
live video in a window, send window contents to a TV output, and
capture or output still images in XPixmaps<A
NAME="AEN11222"
HREF="#FTN.AEN11222"
><SPAN
CLASS="footnote"
>[27]</SPAN
></A
>. With their implementation XFree86 makes the
extension available across many operating systems and
architectures.</P
><P
>Because the driver is embedded into the X server Xv has a
number of advantages over the V4L2 <A
HREF="#OVERLAY"
>video
overlay interface</A
>. The driver can easily determine the overlay
target, i. e. visible graphics memory or off-screen buffers for
non-destructive overlay. It can program the RAMDAC for overlay,
scaling or color-keying, or the clipping functions of the video
capture hardware, always in sync with drawing operations or windows
moving or changing their stacking order.</P
><P
>To combine the advantages of Xv and V4L a special Xv
driver exists in XFree86, just programming any overlay capable
Video4Linux device it finds. To enable it
<TT
CLASS="FILENAME"
>/etc/X11/XF86Config</TT
> must contain these lines:</P
><P
><PRE
CLASS="SCREEN"
>Section "Module"
Load "v4l"
EndSection</PRE
></P
><P
>As of XFree86 4.2 this driver still supports only V4L
ioctls, however it should work just fine with all V4L2 devices through
the V4L2 backward-compatibility layer. Since V4L2 permits multiple
opens it is possible (if supported by the V4L2 driver) to capture
video while an X client requested video overlay. Restrictions of
simultaneous capturing and overlay mentioned in <A
HREF="#OVERLAY"
>Section 4.2</A
> apply.</P
><P
>Only marginally related to V4L2, XFree86 extended Xv to
support hardware YUV to RGB conversion and scaling for faster video
playback, and added an interface to MPEG-2 decoding hardware. This
can be used to improve displaying captured images.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN11233"
>6.3.2. Digital Video</A
></H3
><P
>V4L2 does not, at this time and possibly never, support
digital terrestrial, cable or satellite broadcast. A separate project
aiming at digital receivers exists. You can find its homepage at
<A
HREF="http://linuxtv.org"
TARGET="_top"
>http://linuxtv.org</A
>. This group
found the requirements sufficiently different from analog television
to choose independent development of their interfaces.</P
></DIV
><DIV
CLASS="SECTION"
><HR><H3
CLASS="SECTION"
><A
NAME="AEN11237"
>6.3.3. Audio Interfaces</A
></H3
><P
>[to do - OSS/ALSA]</P
></DIV
></DIV
></DIV
><DIV
CLASS="APPENDIX"
><HR><H1
><A
NAME="VIDEODEV"
></A
>Appendix A. Video For Linux Two Header File</H1
><PRE
CLASS="PROGRAMLISTING"
>#ifndef __LINUX_VIDEODEV2_H
#define __LINUX_VIDEODEV2_H
/*
* Video for Linux Two
*
* Header file for v4l or V4L2 drivers and applications, for
* Linux kernels 2.2.x or 2.4.x.
*
* See http://bytesex.org/v4l/ for API specs and other
* v4l2 documentation.
*
* Author: Bill Dirks <bdirks@pacbell.net>
* Justin Schoeman
* et al.
*/
#ifdef __KERNEL__
#include <linux/time.h> /* need struct timeval */
#endif
/*
* M I S C E L L A N E O U S
*/
/* Four-character-code (FOURCC) */
#define v4l2_fourcc(a,b,c,d)\
(((__u32)(a)<<0)|((__u32)(b)<<8)|((__u32)(c)<<16)|((__u32)(d)<<24))
/*
* E N U M S
*/
enum <A
HREF="#V4L2-FIELD"
>v4l2_field</A
> {
V4L2_FIELD_ANY = 0, /* driver can choose from none,
top, bottom, interlaced
depending on whatever it thinks
is approximate ... */
V4L2_FIELD_NONE = 1, /* this device has no fields ... */
V4L2_FIELD_TOP = 2, /* top field only */
V4L2_FIELD_BOTTOM = 3, /* bottom field only */
V4L2_FIELD_INTERLACED = 4, /* both fields interlaced */
V4L2_FIELD_SEQ_TB = 5, /* both fields sequential into one
buffer, top-bottom order */
V4L2_FIELD_SEQ_BT = 6, /* same as above + bottom-top order */
V4L2_FIELD_ALTERNATE = 7, /* both fields alternating into
separate buffers */
};
#define V4L2_FIELD_HAS_TOP(field) \
((field) == V4L2_FIELD_TOP ||\
(field) == V4L2_FIELD_INTERLACED ||\
(field) == V4L2_FIELD_SEQ_TB ||\
(field) == V4L2_FIELD_SEQ_BT)
#define V4L2_FIELD_HAS_BOTTOM(field) \
((field) == V4L2_FIELD_BOTTOM ||\
(field) == V4L2_FIELD_INTERLACED ||\
(field) == V4L2_FIELD_SEQ_TB ||\
(field) == V4L2_FIELD_SEQ_BT)
#define V4L2_FIELD_HAS_BOTH(field) \
((field) == V4L2_FIELD_INTERLACED ||\
(field) == V4L2_FIELD_SEQ_TB ||\
(field) == V4L2_FIELD_SEQ_BT)
enum <A
HREF="#V4L2-BUF-TYPE"
>v4l2_buf_type</A
> {
V4L2_BUF_TYPE_VIDEO_CAPTURE = 1,
V4L2_BUF_TYPE_VIDEO_OUTPUT = 2,
V4L2_BUF_TYPE_VIDEO_OVERLAY = 3,
V4L2_BUF_TYPE_VBI_CAPTURE = 4,
V4L2_BUF_TYPE_VBI_OUTPUT = 5,
V4L2_BUF_TYPE_PRIVATE = 0x80,
};
enum <A
HREF="#V4L2-CTRL-TYPE"
>v4l2_ctrl_type</A
> {
V4L2_CTRL_TYPE_INTEGER = 1,
V4L2_CTRL_TYPE_BOOLEAN = 2,
V4L2_CTRL_TYPE_MENU = 3,
V4L2_CTRL_TYPE_BUTTON = 4,
};
enum <A
HREF="#V4L2-TUNER-TYPE"
>v4l2_tuner_type</A
> {
V4L2_TUNER_RADIO = 1,
V4L2_TUNER_ANALOG_TV = 2,
};
enum <A
HREF="#V4L2-MEMORY"
>v4l2_memory</A
> {
V4L2_MEMORY_MMAP = 1,
V4L2_MEMORY_USERPTR = 2,
V4L2_MEMORY_OVERLAY = 3,
};
/* see also http://vektor.theorem.ca/graphics/ycbcr/ */
enum <A
HREF="#V4L2-COLORSPACE"
>v4l2_colorspace</A
> {
/* ITU-R 601 -- broadcast NTSC/PAL */
V4L2_COLORSPACE_SMPTE170M = 1,
/* 1125-Line (US) HDTV */
V4L2_COLORSPACE_SMPTE240M = 2,
/* HD and modern captures. */
V4L2_COLORSPACE_REC709 = 3,
/* broken BT878 extents (601, luma range 16-253 instead of 16-235) */
V4L2_COLORSPACE_BT878 = 4,
/* These should be useful. Assume 601 extents. */
V4L2_COLORSPACE_470_SYSTEM_M = 5,
V4L2_COLORSPACE_470_SYSTEM_BG = 6,
/* I know there will be cameras that send this. So, this is
* unspecified chromaticities and full 0-255 on each of the
* Y'CbCr components
*/
V4L2_COLORSPACE_JPEG = 7,
/* For RGB colourspaces, this is probably a good start. */
V4L2_COLORSPACE_SRGB = 8,
};
enum <A
HREF="#V4L2-PRIORITY"
>v4l2_priority</A
> {
V4L2_PRIORITY_UNSET = 0, /* not initialized */
V4L2_PRIORITY_BACKGROUND = 1,
V4L2_PRIORITY_INTERACTIVE = 2,
V4L2_PRIORITY_RECORD = 3,
V4L2_PRIORITY_DEFAULT = V4L2_PRIORITY_INTERACTIVE,
};
struct <A
HREF="#V4L2-RECT"
>v4l2_rect</A
> {
__s32 left;
__s32 top;
__s32 width;
__s32 height;
};
struct <A
HREF="#V4L2-FRACT"
>v4l2_fract</A
> {
__u32 numerator;
__u32 denominator;
};
/*
* D R I V E R C A P A B I L I T I E S
*/
struct <A
HREF="#V4L2-CAPABILITY"
>v4l2_capability</A
>
{
__u8 driver[16]; /* i.e. "bttv" */
__u8 card[32]; /* i.e. "Hauppauge WinTV" */
__u8 bus_info[32]; /* "PCI:" + pci_name(pci_dev) */
__u32 version; /* should use KERNEL_VERSION() */
__u32 capabilities; /* Device capabilities */
__u32 reserved[4];
};
/* Values for 'capabilities' field */
#define V4L2_CAP_VIDEO_CAPTURE 0x00000001 /* Is a video capture device */
#define V4L2_CAP_VIDEO_OUTPUT 0x00000002 /* Is a video output device */
#define V4L2_CAP_VIDEO_OVERLAY 0x00000004 /* Can do video overlay */
#define V4L2_CAP_VBI_CAPTURE 0x00000010 /* Is a VBI capture device */
#define V4L2_CAP_VBI_OUTPUT 0x00000020 /* Is a VBI output device */
#define V4L2_CAP_RDS_CAPTURE 0x00000100 /* RDS data capture */
#define V4L2_CAP_TUNER 0x00010000 /* has a tuner */
#define V4L2_CAP_AUDIO 0x00020000 /* has audio support */
#define V4L2_CAP_RADIO 0x00040000 /* is a radio device */
#define V4L2_CAP_READWRITE 0x01000000 /* read/write systemcalls */
#define V4L2_CAP_ASYNCIO 0x02000000 /* async I/O */
#define V4L2_CAP_STREAMING 0x04000000 /* streaming I/O ioctls */
/*
* V I D E O I M A G E F O R M A T
*/
struct <A
HREF="#V4L2-PIX-FORMAT"
>v4l2_pix_format</A
>
{
__u32 width;
__u32 height;
__u32 pixelformat;
enum <A
HREF="#V4L2-FIELD"
>v4l2_field</A
> field;
__u32 bytesperline; /* for padding, zero if unused */
__u32 sizeimage;
enum <A
HREF="#V4L2-COLORSPACE"
>v4l2_colorspace</A
> colorspace;
__u32 priv; /* private data, depends on pixelformat */
};
/* Pixel format FOURCC depth Description */
#define V4L2_PIX_FMT_RGB332 v4l2_fourcc('R','G','B','1') /* 8 RGB-3-3-2 */
#define V4L2_PIX_FMT_RGB555 v4l2_fourcc('R','G','B','O') /* 16 RGB-5-5-5 */
#define V4L2_PIX_FMT_RGB565 v4l2_fourcc('R','G','B','P') /* 16 RGB-5-6-5 */
#define V4L2_PIX_FMT_RGB555X v4l2_fourcc('R','G','B','Q') /* 16 RGB-5-5-5 BE */
#define V4L2_PIX_FMT_RGB565X v4l2_fourcc('R','G','B','R') /* 16 RGB-5-6-5 BE */
#define V4L2_PIX_FMT_BGR24 v4l2_fourcc('B','G','R','3') /* 24 BGR-8-8-8 */
#define V4L2_PIX_FMT_RGB24 v4l2_fourcc('R','G','B','3') /* 24 RGB-8-8-8 */
#define V4L2_PIX_FMT_BGR32 v4l2_fourcc('B','G','R','4') /* 32 BGR-8-8-8-8 */
#define V4L2_PIX_FMT_RGB32 v4l2_fourcc('R','G','B','4') /* 32 RGB-8-8-8-8 */
#define V4L2_PIX_FMT_GREY v4l2_fourcc('G','R','E','Y') /* 8 Greyscale */
#define V4L2_PIX_FMT_YVU410 v4l2_fourcc('Y','V','U','9') /* 9 YVU 4:1:0 */
#define V4L2_PIX_FMT_YVU420 v4l2_fourcc('Y','V','1','2') /* 12 YVU 4:2:0 */
#define V4L2_PIX_FMT_YUYV v4l2_fourcc('Y','U','Y','V') /* 16 YUV 4:2:2 */
#define V4L2_PIX_FMT_UYVY v4l2_fourcc('U','Y','V','Y') /* 16 YUV 4:2:2 */
#define V4L2_PIX_FMT_YUV422P v4l2_fourcc('4','2','2','P') /* 16 YVU422 planar */
#define V4L2_PIX_FMT_YUV411P v4l2_fourcc('4','1','1','P') /* 16 YVU411 planar */
#define V4L2_PIX_FMT_Y41P v4l2_fourcc('Y','4','1','P') /* 12 YUV 4:1:1 */
/* two planes -- one Y, one Cr + Cb interleaved */
#define V4L2_PIX_FMT_NV12 v4l2_fourcc('N','V','1','2') /* 12 Y/CbCr 4:2:0 */
#define V4L2_PIX_FMT_NV21 v4l2_fourcc('N','V','2','1') /* 12 Y/CrCb 4:2:0 */
/* The following formats are not defined in the V4L2 specification */
#define V4L2_PIX_FMT_YUV410 v4l2_fourcc('Y','U','V','9') /* 9 YUV 4:1:0 */
#define V4L2_PIX_FMT_YUV420 v4l2_fourcc('Y','U','1','2') /* 12 YUV 4:2:0 */
#define V4L2_PIX_FMT_YYUV v4l2_fourcc('Y','Y','U','V') /* 16 YUV 4:2:2 */
#define V4L2_PIX_FMT_HI240 v4l2_fourcc('H','I','2','4') /* 8 8-bit color */
/* compressed formats */
#define V4L2_PIX_FMT_MJPEG v4l2_fourcc('M','J','P','G') /* Motion-JPEG */
#define V4L2_PIX_FMT_JPEG v4l2_fourcc('J','P','E','G') /* JFIF JPEG */
#define V4L2_PIX_FMT_DV v4l2_fourcc('d','v','s','d') /* 1394 */
#define V4L2_PIX_FMT_MPEG v4l2_fourcc('M','P','E','G') /* MPEG */
/* Vendor-specific formats */
#define V4L2_PIX_FMT_WNVA v4l2_fourcc('W','N','V','A') /* Winnov hw compress */
/*
* F O R M A T E N U M E R A T I O N
*/
struct <A
HREF="#V4L2-FMTDESC"
>v4l2_fmtdesc</A
>
{
__u32 index; /* Format number */
enum <A
HREF="#V4L2-BUF-TYPE"
>v4l2_buf_type</A
> type; /* buffer type */
__u32 flags;
__u8 description[32]; /* Description string */
__u32 pixelformat; /* Format fourcc */
__u32 reserved[4];
};
#define V4L2_FMT_FLAG_COMPRESSED 0x0001
/*
* T I M E C O D E
*/
struct <A
HREF="#V4L2-TIMECODE"
>v4l2_timecode</A
>
{
__u32 type;
__u32 flags;
__u8 frames;
__u8 seconds;
__u8 minutes;
__u8 hours;
__u8 userbits[4];
};
/* Type */
#define V4L2_TC_TYPE_24FPS 1
#define V4L2_TC_TYPE_25FPS 2
#define V4L2_TC_TYPE_30FPS 3
#define V4L2_TC_TYPE_50FPS 4
#define V4L2_TC_TYPE_60FPS 5
/* Flags */
#define V4L2_TC_FLAG_DROPFRAME 0x0001 /* "drop-frame" mode */
#define V4L2_TC_FLAG_COLORFRAME 0x0002
#define V4L2_TC_USERBITS_field 0x000C
#define V4L2_TC_USERBITS_USERDEFINED 0x0000
#define V4L2_TC_USERBITS_8BITCHARS 0x0008
/* The above is based on SMPTE timecodes */
/*
* C O M P R E S S I O N P A R A M E T E R S
*/
#if 0
/* ### generic compression settings don't work, there is too much
* ### codec-specific stuff. Maybe reuse that for MPEG codec settings
* ### later ... */
struct <A
HREF="#V4L2-COMPRESSION"
>v4l2_compression</A
>
{
__u32 quality;
__u32 keyframerate;
__u32 pframerate;
__u32 reserved[5];
/* what we'll need for MPEG, extracted from some postings on
the v4l list (Gert Vervoort, PlasmaJohn).
system stream:
- type: elementary stream(ES), packatised elementary stream(s) (PES)
program stream(PS), transport stream(TS)
- system bitrate
- PS packet size (DVD: 2048 bytes, VCD: 2324 bytes)
- TS video PID
- TS audio PID
- TS PCR PID
- TS system information tables (PAT, PMT, CAT, NIT and SIT)
- (MPEG-1 systems stream vs. MPEG-2 program stream (TS not supported
by MPEG-1 systems)
audio:
- type: MPEG (+Layer I,II,III), AC-3, LPCM
- bitrate
- sampling frequency (DVD: 48 Khz, VCD: 44.1 KHz, 32 kHz)
- Trick Modes? (ff, rew)
- Copyright
- Inverse Telecine
video:
- picturesize (SIF, 1/2 D1, 2/3 D1, D1) and PAL/NTSC norm can be set
through excisting V4L2 controls
- noise reduction, parameters encoder specific?
- MPEG video version: MPEG-1, MPEG-2
- GOP (Group Of Pictures) definition:
- N: number of frames per GOP
- M: distance between reference (I,P) frames
- open/closed GOP
- quantiser matrix: inter Q matrix (64 bytes) and intra Q matrix (64 bytes)
- quantiser scale: linear or logarithmic
- scanning: alternate or zigzag
- bitrate mode: CBR (constant bitrate) or VBR (variable bitrate).
- target video bitrate for CBR
- target video bitrate for VBR
- maximum video bitrate for VBR - min. quantiser value for VBR
- max. quantiser value for VBR
- adaptive quantisation value
- return the number of bytes per GOP or bitrate for bitrate monitoring
*/
};
#endif
struct <A
HREF="#V4L2-JPEGCOMPRESSION"
>v4l2_jpegcompression</A
>
{
int quality;
int APPn; /* Number of APP segment to be written,
* must be 0..15 */
int APP_len; /* Length of data in JPEG APPn segment */
char APP_data[60]; /* Data in the JPEG APPn segment. */
int COM_len; /* Length of data in JPEG COM segment */
char COM_data[60]; /* Data in JPEG COM segment */
__u32 jpeg_markers; /* Which markers should go into the JPEG
* output. Unless you exactly know what
* you do, leave them untouched.
* Inluding less markers will make the
* resulting code smaller, but there will
* be fewer aplications which can read it.
* The presence of the APP and COM marker
* is influenced by APP_len and COM_len
* ONLY, not by this property! */
#define V4L2_JPEG_MARKER_DHT (1<<3) /* Define Huffman Tables */
#define V4L2_JPEG_MARKER_DQT (1<<4) /* Define Quantization Tables */
#define V4L2_JPEG_MARKER_DRI (1<<5) /* Define Restart Interval */
#define V4L2_JPEG_MARKER_COM (1<<6) /* Comment segment */
#define V4L2_JPEG_MARKER_APP (1<<7) /* App segment, driver will
* allways use APP0 */
};
/*
* M E M O R Y - M A P P I N G B U F F E R S
*/
struct <A
HREF="#V4L2-REQUESTBUFFERS"
>v4l2_requestbuffers</A
>
{
__u32 count;
enum <A
HREF="#V4L2-BUF-TYPE"
>v4l2_buf_type</A
> type;
enum <A
HREF="#V4L2-MEMORY"
>v4l2_memory</A
> memory;
__u32 reserved[2];
};
struct <A
HREF="#V4L2-BUFFER"
>v4l2_buffer</A
>
{
__u32 index;
enum <A
HREF="#V4L2-BUF-TYPE"
>v4l2_buf_type</A
> type;
__u32 bytesused;
__u32 flags;
enum <A
HREF="#V4L2-FIELD"
>v4l2_field</A
> field;
struct timeval timestamp;
struct <A
HREF="#V4L2-TIMECODE"
>v4l2_timecode</A
> timecode;
__u32 sequence;
/* memory location */
enum <A
HREF="#V4L2-MEMORY"
>v4l2_memory</A
> memory;
union {
__u32 offset;
unsigned long userptr;
} m;
__u32 length;
__u32 input;
__u32 reserved;
};
/* Flags for 'flags' field */
#define V4L2_BUF_FLAG_MAPPED 0x0001 /* Buffer is mapped (flag) */
#define V4L2_BUF_FLAG_QUEUED 0x0002 /* Buffer is queued for processing */
#define V4L2_BUF_FLAG_DONE 0x0004 /* Buffer is ready */
#define V4L2_BUF_FLAG_KEYFRAME 0x0008 /* Image is a keyframe (I-frame) */
#define V4L2_BUF_FLAG_PFRAME 0x0010 /* Image is a P-frame */
#define V4L2_BUF_FLAG_BFRAME 0x0020 /* Image is a B-frame */
#define V4L2_BUF_FLAG_TIMECODE 0x0100 /* timecode field is valid */
#define V4L2_BUF_FLAG_INPUT 0x0200 /* input field is valid */
/*
* O V E R L A Y P R E V I E W
*/
struct <A
HREF="#V4L2-FRAMEBUFFER"
>v4l2_framebuffer</A
>
{
__u32 capability;
__u32 flags;
/* FIXME: in theory we should pass something like PCI device + memory
* region + offset instead of some physical address */
void* base;
struct <A
HREF="#V4L2-PIX-FORMAT"
>v4l2_pix_format</A
> fmt;
};
/* Flags for the 'capability' field. Read only */
#define V4L2_FBUF_CAP_EXTERNOVERLAY 0x0001
#define V4L2_FBUF_CAP_CHROMAKEY 0x0002
#define V4L2_FBUF_CAP_LIST_CLIPPING 0x0004
#define V4L2_FBUF_CAP_BITMAP_CLIPPING 0x0008
/* Flags for the 'flags' field. */
#define V4L2_FBUF_FLAG_PRIMARY 0x0001
#define V4L2_FBUF_FLAG_OVERLAY 0x0002
#define V4L2_FBUF_FLAG_CHROMAKEY 0x0004
struct <A
HREF="#V4L2-CLIP"
>v4l2_clip</A
>
{
struct <A
HREF="#V4L2-RECT"
>v4l2_rect</A
> c;
struct <A
HREF="#V4L2-CLIP"
>v4l2_clip</A
> *next;
};
struct <A
HREF="#V4L2-WINDOW"
>v4l2_window</A
>
{
struct <A
HREF="#V4L2-RECT"
>v4l2_rect</A
> w;
enum <A
HREF="#V4L2-FIELD"
>v4l2_field</A
> field;
__u32 chromakey;
struct <A
HREF="#V4L2-CLIP"
>v4l2_clip</A
> *clips;
__u32 clipcount;
void *bitmap;
};
/*
* C A P T U R E P A R A M E T E R S
*/
struct <A
HREF="#V4L2-CAPTUREPARM"
>v4l2_captureparm</A
>
{
__u32 capability; /* Supported modes */
__u32 capturemode; /* Current mode */
struct <A
HREF="#V4L2-FRACT"
>v4l2_fract</A
> timeperframe; /* Time per frame in .1us units */
__u32 extendedmode; /* Driver-specific extensions */
__u32 readbuffers; /* # of buffers for read */
__u32 reserved[4];
};
/* Flags for 'capability' and 'capturemode' fields */
#define V4L2_MODE_HIGHQUALITY 0x0001 /* High quality imaging mode */
#define V4L2_CAP_TIMEPERFRAME 0x1000 /* timeperframe field is supported */
struct <A
HREF="#V4L2-OUTPUTPARM"
>v4l2_outputparm</A
>
{
__u32 capability; /* Supported modes */
__u32 outputmode; /* Current mode */
struct <A
HREF="#V4L2-FRACT"
>v4l2_fract</A
> timeperframe; /* Time per frame in seconds */
__u32 extendedmode; /* Driver-specific extensions */
__u32 writebuffers; /* # of buffers for write */
__u32 reserved[4];
};
/*
* I N P U T I M A G E C R O P P I N G
*/
struct <A
HREF="#V4L2-CROPCAP"
>v4l2_cropcap</A
> {
enum <A
HREF="#V4L2-BUF-TYPE"
>v4l2_buf_type</A
> type;
struct <A
HREF="#V4L2-RECT"
>v4l2_rect</A
> bounds;
struct <A
HREF="#V4L2-RECT"
>v4l2_rect</A
> defrect;
struct <A
HREF="#V4L2-FRACT"
>v4l2_fract</A
> pixelaspect;
};
struct <A
HREF="#V4L2-CROP"
>v4l2_crop</A
> {
enum <A
HREF="#V4L2-BUF-TYPE"
>v4l2_buf_type</A
> type;
struct <A
HREF="#V4L2-RECT"
>v4l2_rect</A
> c;
};
/*
* A N A L O G V I D E O S T A N D A R D
*/
typedef __u64 v4l2_std_id;
/* one bit for each */
#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)
#define V4L2_STD_NTSC_M ((v4l2_std_id)0x00001000)
#define V4L2_STD_NTSC_M_JP ((v4l2_std_id)0x00002000)
#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)
/* ATSC/HDTV */
#define V4L2_STD_ATSC_8_VSB ((v4l2_std_id)0x01000000)
#define V4L2_STD_ATSC_16_VSB ((v4l2_std_id)0x02000000)
/* some common needed stuff */
#define V4L2_STD_PAL_BG (V4L2_STD_PAL_B |\
V4L2_STD_PAL_B1 |\
V4L2_STD_PAL_G)
#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)
#define V4L2_STD_SECAM (V4L2_STD_SECAM_B |\
V4L2_STD_SECAM_D |\
V4L2_STD_SECAM_G |\
V4L2_STD_SECAM_H |\
V4L2_STD_SECAM_K |\
V4L2_STD_SECAM_K1 |\
V4L2_STD_SECAM_L)
#define V4L2_STD_525_60 (V4L2_STD_PAL_M |\
V4L2_STD_PAL_60 |\
V4L2_STD_NTSC)
#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)
struct <A
HREF="#V4L2-STANDARD"
>v4l2_standard</A
>
{
__u32 index;
v4l2_std_id id;
__u8 name[24];
struct <A
HREF="#V4L2-FRACT"
>v4l2_fract</A
> frameperiod; /* Frames, not fields */
__u32 framelines;
__u32 reserved[4];
};
/*
* V I D E O I N P U T S
*/
struct <A
HREF="#V4L2-INPUT"
>v4l2_input</A
>
{
__u32 index; /* Which input */
__u8 name[32]; /* Label */
__u32 type; /* Type of input */
__u32 audioset; /* Associated audios (bitfield) */
__u32 tuner; /* Associated tuner */
v4l2_std_id std;
__u32 status;
__u32 reserved[4];
};
/* Values for the 'type' field */
#define V4L2_INPUT_TYPE_TUNER 1
#define V4L2_INPUT_TYPE_CAMERA 2
/* field 'status' - general */
#define V4L2_IN_ST_NO_POWER 0x00000001 /* Attached device is off */
#define V4L2_IN_ST_NO_SIGNAL 0x00000002
#define V4L2_IN_ST_NO_COLOR 0x00000004
/* field 'status' - analog */
#define V4L2_IN_ST_NO_H_LOCK 0x00000100 /* No horizontal sync lock */
#define V4L2_IN_ST_COLOR_KILL 0x00000200 /* Color killer is active */
/* field 'status' - digital */
#define V4L2_IN_ST_NO_SYNC 0x00010000 /* No synchronization lock */
#define V4L2_IN_ST_NO_EQU 0x00020000 /* No equalizer lock */
#define V4L2_IN_ST_NO_CARRIER 0x00040000 /* Carrier recovery failed */
/* field 'status' - VCR and set-top box */
#define V4L2_IN_ST_MACROVISION 0x01000000 /* Macrovision detected */
#define V4L2_IN_ST_NO_ACCESS 0x02000000 /* Conditional access denied */
#define V4L2_IN_ST_VTR 0x04000000 /* VTR time constant */
/*
* V I D E O O U T P U T S
*/
struct <A
HREF="#V4L2-OUTPUT"
>v4l2_output</A
>
{
__u32 index; /* Which output */
__u8 name[32]; /* Label */
__u32 type; /* Type of output */
__u32 audioset; /* Associated audios (bitfield) */
__u32 modulator; /* Associated modulator */
v4l2_std_id std;
__u32 reserved[4];
};
/* Values for the 'type' field */
#define V4L2_OUTPUT_TYPE_MODULATOR 1
#define V4L2_OUTPUT_TYPE_ANALOG 2
#define V4L2_OUTPUT_TYPE_ANALOGVGAOVERLAY 3
/*
* C O N T R O L S
*/
struct <A
HREF="#V4L2-CONTROL"
>v4l2_control</A
>
{
__u32 id;
__s32 value;
};
/* Used in the VIDIOC_QUERYCTRL ioctl for querying controls */
struct <A
HREF="#V4L2-QUERYCTRL"
>v4l2_queryctrl</A
>
{
__u32 id;
enum <A
HREF="#V4L2-CTRL-TYPE"
>v4l2_ctrl_type</A
> type;
__u8 name[32]; /* Whatever */
__s32 minimum; /* Note signedness */
__s32 maximum;
__s32 step;
__s32 default_value;
__u32 flags;
__u32 reserved[2];
};
/* Used in the VIDIOC_QUERYMENU ioctl for querying menu items */
struct <A
HREF="#V4L2-QUERYMENU"
>v4l2_querymenu</A
>
{
__u32 id;
__u32 index;
__u8 name[32]; /* Whatever */
__u32 reserved;
};
/* Control flags */
#define V4L2_CTRL_FLAG_DISABLED 0x0001
#define V4L2_CTRL_FLAG_GRABBED 0x0002
/* Control IDs defined by V4L2 */
#define V4L2_CID_BASE 0x00980900
/* IDs reserved for driver specific controls */
#define V4L2_CID_PRIVATE_BASE 0x08000000
#define V4L2_CID_BRIGHTNESS (V4L2_CID_BASE+0)
#define V4L2_CID_CONTRAST (V4L2_CID_BASE+1)
#define V4L2_CID_SATURATION (V4L2_CID_BASE+2)
#define V4L2_CID_HUE (V4L2_CID_BASE+3)
#define V4L2_CID_AUDIO_VOLUME (V4L2_CID_BASE+5)
#define V4L2_CID_AUDIO_BALANCE (V4L2_CID_BASE+6)
#define V4L2_CID_AUDIO_BASS (V4L2_CID_BASE+7)
#define V4L2_CID_AUDIO_TREBLE (V4L2_CID_BASE+8)
#define V4L2_CID_AUDIO_MUTE (V4L2_CID_BASE+9)
#define V4L2_CID_AUDIO_LOUDNESS (V4L2_CID_BASE+10)
#define V4L2_CID_BLACK_LEVEL (V4L2_CID_BASE+11)
#define V4L2_CID_AUTO_WHITE_BALANCE (V4L2_CID_BASE+12)
#define V4L2_CID_DO_WHITE_BALANCE (V4L2_CID_BASE+13)
#define V4L2_CID_RED_BALANCE (V4L2_CID_BASE+14)
#define V4L2_CID_BLUE_BALANCE (V4L2_CID_BASE+15)
#define V4L2_CID_GAMMA (V4L2_CID_BASE+16)
#define V4L2_CID_WHITENESS (V4L2_CID_GAMMA) /* ? Not sure */
#define V4L2_CID_EXPOSURE (V4L2_CID_BASE+17)
#define V4L2_CID_AUTOGAIN (V4L2_CID_BASE+18)
#define V4L2_CID_GAIN (V4L2_CID_BASE+19)
#define V4L2_CID_HFLIP (V4L2_CID_BASE+20)
#define V4L2_CID_VFLIP (V4L2_CID_BASE+21)
#define V4L2_CID_HCENTER (V4L2_CID_BASE+22)
#define V4L2_CID_VCENTER (V4L2_CID_BASE+23)
#define V4L2_CID_LASTP1 (V4L2_CID_BASE+24) /* last CID + 1 */
/*
* T U N I N G
*/
struct <A
HREF="#V4L2-TUNER"
>v4l2_tuner</A
>
{
__u32 index;
__u8 name[32];
enum <A
HREF="#V4L2-TUNER-TYPE"
>v4l2_tuner_type</A
> type;
__u32 capability;
__u32 rangelow;
__u32 rangehigh;
__u32 rxsubchans;
__u32 audmode;
__s32 signal;
__s32 afc;
__u32 reserved[4];
};
struct <A
HREF="#V4L2-MODULATOR"
>v4l2_modulator</A
>
{
__u32 index;
__u8 name[32];
__u32 capability;
__u32 rangelow;
__u32 rangehigh;
__u32 txsubchans;
__u32 reserved[4];
};
/* Flags for the 'capability' field */
#define V4L2_TUNER_CAP_LOW 0x0001
#define V4L2_TUNER_CAP_NORM 0x0002
#define V4L2_TUNER_CAP_STEREO 0x0010
#define V4L2_TUNER_CAP_LANG2 0x0020
#define V4L2_TUNER_CAP_SAP 0x0020
#define V4L2_TUNER_CAP_LANG1 0x0040
/* Flags for the 'rxsubchans' field */
#define V4L2_TUNER_SUB_MONO 0x0001
#define V4L2_TUNER_SUB_STEREO 0x0002
#define V4L2_TUNER_SUB_LANG2 0x0004
#define V4L2_TUNER_SUB_SAP 0x0004
#define V4L2_TUNER_SUB_LANG1 0x0008
/* Values for the 'audmode' field */
#define V4L2_TUNER_MODE_MONO 0x0000
#define V4L2_TUNER_MODE_STEREO 0x0001
#define V4L2_TUNER_MODE_LANG2 0x0002
#define V4L2_TUNER_MODE_SAP 0x0002
#define V4L2_TUNER_MODE_LANG1 0x0003
struct <A
HREF="#V4L2-FREQUENCY"
>v4l2_frequency</A
>
{
__u32 tuner;
enum <A
HREF="#V4L2-TUNER-TYPE"
>v4l2_tuner_type</A
> type;
__u32 frequency;
__u32 reserved[8];
};
/*
* A U D I O
*/
struct <A
HREF="#V4L2-AUDIO"
>v4l2_audio</A
>
{
__u32 index;
__u8 name[32];
__u32 capability;
__u32 mode;
__u32 reserved[2];
};
/* Flags for the 'capability' field */
#define V4L2_AUDCAP_STEREO 0x00001
#define V4L2_AUDCAP_AVL 0x00002
/* Flags for the 'mode' field */
#define V4L2_AUDMODE_AVL 0x00001
struct <A
HREF="#V4L2-AUDIOOUT"
>v4l2_audioout</A
>
{
__u32 index;
__u8 name[32];
__u32 capability;
__u32 mode;
__u32 reserved[2];
};
/*
* D A T A S E R V I C E S ( V B I )
*
* Data services API by Michael Schimek
*/
struct <A
HREF="#V4L2-VBI-FORMAT"
>v4l2_vbi_format</A
>
{
__u32 sampling_rate; /* in 1 Hz */
__u32 offset;
__u32 samples_per_line;
__u32 sample_format; /* V4L2_PIX_FMT_* */
__s32 start[2];
__u32 count[2];
__u32 flags; /* V4L2_VBI_* */
__u32 reserved[2]; /* must be zero */
};
/* VBI flags */
#define V4L2_VBI_UNSYNC (1<< 0)
#define V4L2_VBI_INTERLACED (1<< 1)
/*
* A G G R E G A T E S T R U C T U R E S
*/
/* Stream data format
*/
struct <A
HREF="#V4L2-FORMAT"
>v4l2_format</A
>
{
enum <A
HREF="#V4L2-BUF-TYPE"
>v4l2_buf_type</A
> type;
union
{
struct <A
HREF="#V4L2-PIX-FORMAT"
>v4l2_pix_format</A
> pix; // V4L2_BUF_TYPE_VIDEO_CAPTURE
struct <A
HREF="#V4L2-WINDOW"
>v4l2_window</A
> win; // V4L2_BUF_TYPE_VIDEO_OVERLAY
struct <A
HREF="#V4L2-VBI-FORMAT"
>v4l2_vbi_format</A
> vbi; // V4L2_BUF_TYPE_VBI_CAPTURE
__u8 raw_data[200]; // user-defined
} fmt;
};
/* Stream type-dependent parameters
*/
struct <A
HREF="#V4L2-STREAMPARM"
>v4l2_streamparm</A
>
{
enum <A
HREF="#V4L2-BUF-TYPE"
>v4l2_buf_type</A
> type;
union
{
struct <A
HREF="#V4L2-CAPTUREPARM"
>v4l2_captureparm</A
> capture;
struct <A
HREF="#V4L2-OUTPUTPARM"
>v4l2_outputparm</A
> output;
__u8 raw_data[200]; /* user-defined */
} parm;
};
/*
* I O C T L C O D E S F O R V I D E O D E V I C E S
*
*/
#define VIDIOC_QUERYCAP _IOR ('V', 0, struct <A
HREF="#V4L2-CAPABILITY"
>v4l2_capability</A
>)
#define VIDIOC_RESERVED _IO ('V', 1)
#define VIDIOC_ENUM_FMT _IOWR ('V', 2, struct <A
HREF="#V4L2-FMTDESC"
>v4l2_fmtdesc</A
>)
#define VIDIOC_G_FMT _IOWR ('V', 4, struct <A
HREF="#V4L2-FORMAT"
>v4l2_format</A
>)
#define VIDIOC_S_FMT _IOWR ('V', 5, struct <A
HREF="#V4L2-FORMAT"
>v4l2_format</A
>)
#if 0
#define VIDIOC_G_COMP _IOR ('V', 6, struct <A
HREF="#V4L2-COMPRESSION"
>v4l2_compression</A
>)
#define VIDIOC_S_COMP _IOW ('V', 7, struct <A
HREF="#V4L2-COMPRESSION"
>v4l2_compression</A
>)
#endif
#define VIDIOC_REQBUFS _IOWR ('V', 8, struct <A
HREF="#V4L2-REQUESTBUFFERS"
>v4l2_requestbuffers</A
>)
#define VIDIOC_QUERYBUF _IOWR ('V', 9, struct <A
HREF="#V4L2-BUFFER"
>v4l2_buffer</A
>)
#define VIDIOC_G_FBUF _IOR ('V', 10, struct <A
HREF="#V4L2-FRAMEBUFFER"
>v4l2_framebuffer</A
>)
#define VIDIOC_S_FBUF _IOW ('V', 11, struct <A
HREF="#V4L2-FRAMEBUFFER"
>v4l2_framebuffer</A
>)
#define VIDIOC_OVERLAY _IOW ('V', 14, int)
#define VIDIOC_QBUF _IOWR ('V', 15, struct <A
HREF="#V4L2-BUFFER"
>v4l2_buffer</A
>)
#define VIDIOC_DQBUF _IOWR ('V', 17, struct <A
HREF="#V4L2-BUFFER"
>v4l2_buffer</A
>)
#define VIDIOC_STREAMON _IOW ('V', 18, int)
#define VIDIOC_STREAMOFF _IOW ('V', 19, int)
#define VIDIOC_G_PARM _IOWR ('V', 21, struct <A
HREF="#V4L2-STREAMPARM"
>v4l2_streamparm</A
>)
#define VIDIOC_S_PARM _IOWR ('V', 22, struct <A
HREF="#V4L2-STREAMPARM"
>v4l2_streamparm</A
>)
#define VIDIOC_G_STD _IOR ('V', 23, v4l2_std_id)
#define VIDIOC_S_STD _IOW ('V', 24, v4l2_std_id)
#define VIDIOC_ENUMSTD _IOWR ('V', 25, struct <A
HREF="#V4L2-STANDARD"
>v4l2_standard</A
>)
#define VIDIOC_ENUMINPUT _IOWR ('V', 26, struct <A
HREF="#V4L2-INPUT"
>v4l2_input</A
>)
#define VIDIOC_G_CTRL _IOWR ('V', 27, struct <A
HREF="#V4L2-CONTROL"
>v4l2_control</A
>)
#define VIDIOC_S_CTRL _IOWR ('V', 28, struct <A
HREF="#V4L2-CONTROL"
>v4l2_control</A
>)
#define VIDIOC_G_TUNER _IOWR ('V', 29, struct <A
HREF="#V4L2-TUNER"
>v4l2_tuner</A
>)
#define VIDIOC_S_TUNER _IOW ('V', 30, struct <A
HREF="#V4L2-TUNER"
>v4l2_tuner</A
>)
#define VIDIOC_G_AUDIO _IOR ('V', 33, struct <A
HREF="#V4L2-AUDIO"
>v4l2_audio</A
>)
#define VIDIOC_S_AUDIO _IOW ('V', 34, struct <A
HREF="#V4L2-AUDIO"
>v4l2_audio</A
>)
#define VIDIOC_QUERYCTRL _IOWR ('V', 36, struct <A
HREF="#V4L2-QUERYCTRL"
>v4l2_queryctrl</A
>)
#define VIDIOC_QUERYMENU _IOWR ('V', 37, struct <A
HREF="#V4L2-QUERYMENU"
>v4l2_querymenu</A
>)
#define VIDIOC_G_INPUT _IOR ('V', 38, int)
#define VIDIOC_S_INPUT _IOWR ('V', 39, int)
#define VIDIOC_G_OUTPUT _IOR ('V', 46, int)
#define VIDIOC_S_OUTPUT _IOWR ('V', 47, int)
#define VIDIOC_ENUMOUTPUT _IOWR ('V', 48, struct <A
HREF="#V4L2-OUTPUT"
>v4l2_output</A
>)
#define VIDIOC_G_AUDOUT _IOR ('V', 49, struct <A
HREF="#V4L2-AUDIOOUT"
>v4l2_audioout</A
>)
#define VIDIOC_S_AUDOUT _IOW ('V', 50, struct <A
HREF="#V4L2-AUDIOOUT"
>v4l2_audioout</A
>)
#define VIDIOC_G_MODULATOR _IOWR ('V', 54, struct <A
HREF="#V4L2-MODULATOR"
>v4l2_modulator</A
>)
#define VIDIOC_S_MODULATOR _IOW ('V', 55, struct <A
HREF="#V4L2-MODULATOR"
>v4l2_modulator</A
>)
#define VIDIOC_G_FREQUENCY _IOWR ('V', 56, struct <A
HREF="#V4L2-FREQUENCY"
>v4l2_frequency</A
>)
#define VIDIOC_S_FREQUENCY _IOW ('V', 57, struct <A
HREF="#V4L2-FREQUENCY"
>v4l2_frequency</A
>)
#define VIDIOC_CROPCAP _IOWR ('V', 58, struct <A
HREF="#V4L2-CROPCAP"
>v4l2_cropcap</A
>)
#define VIDIOC_G_CROP _IOWR ('V', 59, struct <A
HREF="#V4L2-CROP"
>v4l2_crop</A
>)
#define VIDIOC_S_CROP _IOW ('V', 60, struct <A
HREF="#V4L2-CROP"
>v4l2_crop</A
>)
#define VIDIOC_G_JPEGCOMP _IOR ('V', 61, struct <A
HREF="#V4L2-JPEGCOMPRESSION"
>v4l2_jpegcompression</A
>)
#define VIDIOC_S_JPEGCOMP _IOW ('V', 62, struct <A
HREF="#V4L2-JPEGCOMPRESSION"
>v4l2_jpegcompression</A
>)
#define VIDIOC_QUERYSTD _IOR ('V', 63, v4l2_std_id)
#define VIDIOC_TRY_FMT _IOWR ('V', 64, struct <A
HREF="#V4L2-FORMAT"
>v4l2_format</A
>)
#define VIDIOC_ENUMAUDIO _IOWR ('V', 65, struct <A
HREF="#V4L2-AUDIO"
>v4l2_audio</A
>)
#define VIDIOC_ENUMAUDOUT _IOWR ('V', 66, struct <A
HREF="#V4L2-AUDIOOUT"
>v4l2_audioout</A
>)
#define VIDIOC_G_PRIORITY _IOR ('V', 67, enum <A
HREF="#V4L2-PRIORITY"
>v4l2_priority</A
>)
#define VIDIOC_S_PRIORITY _IOW ('V', 68, enum <A
HREF="#V4L2-PRIORITY"
>v4l2_priority</A
>)
/* for compatibility, will go away some day */
#define VIDIOC_OVERLAY_OLD _IOWR ('V', 14, int)
#define VIDIOC_S_PARM_OLD _IOW ('V', 22, struct <A
HREF="#V4L2-STREAMPARM"
>v4l2_streamparm</A
>)
#define VIDIOC_S_CTRL_OLD _IOW ('V', 28, struct <A
HREF="#V4L2-CONTROL"
>v4l2_control</A
>)
#define VIDIOC_G_AUDIO_OLD _IOWR ('V', 33, struct <A
HREF="#V4L2-AUDIO"
>v4l2_audio</A
>)
#define VIDIOC_G_AUDOUT_OLD _IOWR ('V', 49, struct <A
HREF="#V4L2-AUDIOOUT"
>v4l2_audioout</A
>)
#define VIDIOC_CROPCAP_OLD _IOR ('V', 58, struct <A
HREF="#V4L2-CROPCAP"
>v4l2_cropcap</A
>)
#define BASE_VIDIOC_PRIVATE 192 /* 192-255 are private */
#ifdef __KERNEL__
/*
*
* V 4 L 2 D R I V E R H E L P E R A P I
*
* Some commonly needed functions for drivers (v4l2-common.o module)
*/
#include <linux/fs.h>
/* Video standard functions */
extern unsigned int v4l2_video_std_fps(struct <A
HREF="#V4L2-STANDARD"
>v4l2_standard</A
> *vs);
extern int v4l2_video_std_construct(struct <A
HREF="#V4L2-STANDARD"
>v4l2_standard</A
> *vs,
int id, char *name);
/* prority handling */
struct v4l2_prio_state {
atomic_t prios[4];
};
int v4l2_prio_init(struct v4l2_prio_state *global);
int v4l2_prio_change(struct v4l2_prio_state *global, enum <A
HREF="#V4L2-PRIORITY"
>v4l2_priority</A
> *local,
enum <A
HREF="#V4L2-PRIORITY"
>v4l2_priority</A
> new);
int v4l2_prio_open(struct v4l2_prio_state *global, enum <A
HREF="#V4L2-PRIORITY"
>v4l2_priority</A
> *local);
int v4l2_prio_close(struct v4l2_prio_state *global, enum <A
HREF="#V4L2-PRIORITY"
>v4l2_priority</A
> *local);
enum <A
HREF="#V4L2-PRIORITY"
>v4l2_priority</A
> v4l2_prio_max(struct v4l2_prio_state *global);
int v4l2_prio_check(struct v4l2_prio_state *global, enum <A
HREF="#V4L2-PRIORITY"
>v4l2_priority</A
> *local);
/* names for fancy debug output */
extern char *v4l2_field_names[];
extern char *v4l2_type_names[];
extern char *v4l2_ioctl_names[];
/* Compatibility layer interface -- v4l1-compat module */
typedef int (*v4l2_kioctl)(struct inode *inode, struct file *file,
unsigned int cmd, void *arg);
int v4l_compat_translate_ioctl(struct inode *inode, struct file *file,
int cmd, void *arg, v4l2_kioctl driver_ioctl);
#endif /* __KERNEL__ */
#endif /* __LINUX_VIDEODEV2_H */
/*
* Local variables:
* c-basic-offset: 8
* End:
*/</PRE
></DIV
><DIV
CLASS="APPENDIX"
><HR><H1
><A
NAME="CAPTURE-EXAMPLE"
></A
>Appendix B. Video Capture Example</H1
><PRE
CLASS="PROGRAMLISTING"
>/*
* V4L2 video capture example
*/
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <assert.h>
#include <getopt.h> /* getopt_long() */
#include <fcntl.h> /* low-level i/o */
#include <unistd.h>
#include <errno.h>
#include <sys/stat.h>
#include <sys/types.h>
#include <sys/time.h>
#include <sys/mman.h>
#include <sys/ioctl.h>
#include <asm/types.h> /* for videodev2.h */
#include <linux/videodev2.h>
#define CLEAR(x) memset (&(x), 0, sizeof (x))
typedef enum {
IO_METHOD_READ,
IO_METHOD_MMAP,
IO_METHOD_USERPTR,
} io_method;
struct buffer {
void * start;
size_t length;
};
static char * dev_name = NULL;
static io_method io = IO_METHOD_MMAP;
static int fd = -1;
struct buffer * buffers = NULL;
static unsigned int n_buffers = 0;
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 fd,
int request,
void * arg)
{
int r;
do r = ioctl (fd, request, arg);
while (-1 == r && EINTR == errno);
return r;
}
static void
process_image (const void * p)
{
fputc ('.', stdout);
fflush (stdout);
}
static int
read_frame (void)
{
struct <A
HREF="#V4L2-BUFFER"
>v4l2_buffer</A
> 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);
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, &buf)) {
switch (errno) {
case EAGAIN:
return 0;
case EIO:
/* Could ignore EIO, see spec. */
/* fall through */
default:
errno_exit ("VIDIOC_DQBUF");
}
}
assert (buf.index < n_buffers);
process_image (buffers[buf.index].start);
if (-1 == xioctl (fd, VIDIOC_QBUF, &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, &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 < n_buffers; ++i)
if (buf.m.userptr == (unsigned long) buffers[i].start
&& buf.length == buffers[i].length)
break;
assert (i < n_buffers);
process_image ((void *) buf.m.userptr);
if (-1 == xioctl (fd, VIDIOC_QBUF, &buf))
errno_exit ("VIDIOC_QBUF");
break;
}
return 1;
}
static void
mainloop (void)
{
unsigned int count;
count = 100;
while (count-- > 0) {
for (;;) {
fd_set fds;
struct timeval tv;
int r;
FD_ZERO (&fds);
FD_SET (fd, &fds);
/* Timeout. */
tv.tv_sec = 2;
tv.tv_usec = 0;
r = select (fd + 1, &fds, NULL, NULL, &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 <A
HREF="#V4L2-BUF-TYPE"
>v4l2_buf_type</A
> 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, &type))
errno_exit ("VIDIOC_STREAMOFF");
break;
}
}
static void
start_capturing (void)
{
unsigned int i;
enum <A
HREF="#V4L2-BUF-TYPE"
>v4l2_buf_type</A
> type;
switch (io) {
case IO_METHOD_READ:
/* Nothing to do. */
break;
case IO_METHOD_MMAP:
for (i = 0; i < n_buffers; ++i) {
struct <A
HREF="#V4L2-BUFFER"
>v4l2_buffer</A
> buf;
CLEAR (buf);
buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
buf.memory = V4L2_MEMORY_MMAP;
buf.index = i;
if (-1 == xioctl (fd, VIDIOC_QBUF, &buf))
errno_exit ("VIDIOC_QBUF");
}
type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
if (-1 == xioctl (fd, VIDIOC_STREAMON, &type))
errno_exit ("VIDIOC_STREAMON");
break;
case IO_METHOD_USERPTR:
for (i = 0; i < n_buffers; ++i) {
struct <A
HREF="#V4L2-BUFFER"
>v4l2_buffer</A
> buf;
CLEAR (buf);
buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
buf.memory = V4L2_MEMORY_USERPTR;
buf.m.userptr = (unsigned long) buffers[i].start;
buf.length = buffers[i].length;
if (-1 == xioctl (fd, VIDIOC_QBUF, &buf))
errno_exit ("VIDIOC_QBUF");
}
type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
if (-1 == xioctl (fd, VIDIOC_STREAMON, &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 < n_buffers; ++i)
if (-1 == munmap (buffers[i].start, buffers[i].length))
errno_exit ("munmap");
break;
case IO_METHOD_USERPTR:
for (i = 0; i < 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 <A
HREF="#V4L2-REQUESTBUFFERS"
>v4l2_requestbuffers</A
> req;
CLEAR (req);
req.count = 4;
req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
req.memory = V4L2_MEMORY_MMAP;
if (-1 == xioctl (fd, VIDIOC_REQBUFS, &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 < 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 < req.count; ++n_buffers) {
struct <A
HREF="#V4L2-BUFFER"
>v4l2_buffer</A
> 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, &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 <A
HREF="#V4L2-REQUESTBUFFERS"
>v4l2_requestbuffers</A
> req;
CLEAR (req);
req.count = 4;
req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
req.memory = V4L2_MEMORY_USERPTR;
if (-1 == xioctl (fd, VIDIOC_REQBUFS, &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 < 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 <A
HREF="#V4L2-CAPABILITY"
>v4l2_capability</A
> cap;
struct <A
HREF="#V4L2-CROPCAP"
>v4l2_cropcap</A
> cropcap;
struct <A
HREF="#V4L2-CROP"
>v4l2_crop</A
> crop;
struct <A
HREF="#V4L2-FORMAT"
>v4l2_format</A
> fmt;
unsigned int min;
if (-1 == xioctl (fd, VIDIOC_QUERYCAP, &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 & 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 & 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 & 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. */
cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
if (-1 == xioctl (fd, VIDIOC_CROPCAP, &cropcap)) {
/* Errors ignored. */
}
crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
crop.c = cropcap.defrect; /* reset to default */
if (-1 == xioctl (fd, VIDIOC_S_CROP, &crop)) {
switch (errno) {
case EINVAL:
/* Cropping not supported. */
break;
default:
/* Errors ignored. */
break;
}
}
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_YUYV;
fmt.fmt.pix.field = V4L2_FIELD_INTERLACED;
if (-1 == xioctl (fd, VIDIOC_S_FMT, &fmt))
errno_exit ("VIDIOC_S_FMT");
/* Note VIDIOC_S_FMT may change width and height. */
/* Buggy driver paranoia. */
min = fmt.fmt.pix.width * 2;
if (fmt.fmt.pix.bytesperline < min)
fmt.fmt.pix.bytesperline = min;
min = fmt.fmt.pix.bytesperline * fmt.fmt.pix.height;
if (fmt.fmt.pix.sizeimage < 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, &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"
"Options:\n"
"-d | --device name Video device name [/dev/video]\n"
"-h | --help Print this message\n"
"-m | --mmap Use memory mapped buffers\n"
"-r | --read Use read() calls\n"
"-u | --userp Use application allocated buffers\n"
"",
argv[0]);
}
static const char short_options [] = "d:hmru";
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' },
{ 0, 0, 0, 0 }
};
int
main (int argc,
char ** argv)
{
dev_name = "/dev/video";
for (;;) {
int index;
int c;
c = getopt_long (argc, argv,
short_options, long_options,
&index);
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;
default:
usage (stderr, argc, argv);
exit (EXIT_FAILURE);
}
}
open_device ();
init_device ();
start_capturing ();
mainloop ();
stop_capturing ();
uninit_device ();
close_device ();
exit (EXIT_SUCCESS);
return 0;
}</PRE
></DIV
><DIV
CLASS="APPENDIX"
><HR><H1
><A
NAME="FDL"
></A
>Appendix C. GNU Free Documentation License</H1
><DIV
CLASS="SECT1"
><H2
CLASS="SECT1"
><A
NAME="FDL-PREAMBLE"
>C.1. 0. PREAMBLE</A
></H2
><P
> The purpose of this License is to make a manual, textbook, or
other written document <SPAN
CLASS="QUOTE"
>"free"</SPAN
> 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.
</P
><P
> This License is a kind of <SPAN
CLASS="QUOTE"
>"copyleft"</SPAN
>, 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.
</P
><P
> 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.
</P
></DIV
><DIV
CLASS="SECT1"
><HR><H2
CLASS="SECT1"
><A
NAME="FDL-SECTION1"
>C.2. 1. APPLICABILITY AND DEFINITIONS</A
></H2
><P
> 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
<SPAN
CLASS="QUOTE"
>"Document"</SPAN
>, below, refers to any such manual or
work. Any member of the public is a licensee, and is addressed
as <SPAN
CLASS="QUOTE"
>"you"</SPAN
>.
</P
><P
> A <SPAN
CLASS="QUOTE"
>"Modified Version"</SPAN
> 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.
</P
><P
> A <SPAN
CLASS="QUOTE"
>"Secondary Section"</SPAN
> is a named appendix or a
front-matter section of the <A
HREF="#FDL-DOCUMENT"
>Document</A
> 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.
</P
><P
> The <SPAN
CLASS="QUOTE"
>"Invariant Sections"</SPAN
> are certain <A
HREF="#FDL-SECONDARY"
> Secondary Sections</A
> whose titles
are designated, as being those of Invariant Sections, in the
notice that says that the <A
HREF="#FDL-DOCUMENT"
>Document</A
> is released under this
License.
</P
><P
> The <SPAN
CLASS="QUOTE"
>"Cover Texts"</SPAN
> are certain short passages of
text that are listed, as Front-Cover Texts or Back-Cover Texts,
in the notice that says that the <A
HREF="#FDL-DOCUMENT"
>Document</A
> is released under this
License.
</P
><P
> A <SPAN
CLASS="QUOTE"
>"Transparent"</SPAN
> copy of the <A
HREF="#FDL-DOCUMENT"
> Document</A
> 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 <SPAN
CLASS="QUOTE"
>"Transparent"</SPAN
> is called
<SPAN
CLASS="QUOTE"
>"Opaque"</SPAN
>.
</P
><P
> 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.
</P
><P
> The <SPAN
CLASS="QUOTE"
>"Title Page"</SPAN
> 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, <SPAN
CLASS="QUOTE"
>"Title Page"</SPAN
> means the text near the
most prominent appearance of the work's title, preceding the
beginning of the body of the text.
</P
></DIV
><DIV
CLASS="SECT1"
><HR><H2
CLASS="SECT1"
><A
NAME="FDL-SECTION2"
>C.3. 2. VERBATIM COPYING</A
></H2
><P
> You may copy and distribute the <A
HREF="#FDL-DOCUMENT"
>Document</A
> 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 <A
HREF="#FDL-SECTION3"
>section 3</A
>.
</P
><P
> You may also lend copies, under the same conditions stated
above, and you may publicly display copies.
</P
></DIV
><DIV
CLASS="SECT1"
><HR><H2
CLASS="SECT1"
><A
NAME="FDL-SECTION3"
>C.4. 3. COPYING IN QUANTITY</A
></H2
><P
> If you publish printed copies of the <A
HREF="#FDL-DOCUMENT"
>Document</A
> numbering more than 100,
and the Document's license notice requires <A
HREF="#FDL-COVER-TEXTS"
>Cover Texts</A
>, 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
<A
HREF="#FDL-DOCUMENT"
>Document</A
> and satisfy these
conditions, can be treated as verbatim copying in other
respects.
</P
><P
> 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.
</P
><P
> If you publish or distribute <A
HREF="#FDL-TRANSPARENT"
>Opaque</A
> copies of the <A
HREF="#FDL-DOCUMENT"
>Document</A
> numbering more than 100,
you must either include a machine-readable <A
HREF="#FDL-TRANSPARENT"
>Transparent</A
> 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.
</P
><P
> It is requested, but not required, that you contact the authors
of the <A
HREF="#FDL-DOCUMENT"
>Document</A
> well before
redistributing any large number of copies, to give them a chance
to provide you with an updated version of the Document.
</P
></DIV
><DIV
CLASS="SECT1"
><HR><H2
CLASS="SECT1"
><A
NAME="FDL-SECTION4"
>C.5. 4. MODIFICATIONS</A
></H2
><P
> You may copy and distribute a <A
HREF="#FDL-MODIFIED"
>Modified Version</A
> of the <A
HREF="#FDL-DOCUMENT"
>Document</A
> under the conditions of
sections <A
HREF="#FDL-SECTION2"
>2</A
> and <A
HREF="#FDL-SECTION3"
>3</A
> 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:
</P
><P
></P
><UL
><LI
STYLE="list-style-type: opencircle"
><DIV
CLASS="FORMALPARA"
><P
><B
>A. </B
> Use in the <A
HREF="#FDL-TITLE-PAGE"
>Title
Page</A
> (and on the covers, if any) a title distinct
from that of the <A
HREF="#FDL-DOCUMENT"
>Document</A
>, 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.
</P
></DIV
></LI
><LI
STYLE="list-style-type: opencircle"
><DIV
CLASS="FORMALPARA"
><P
><B
>B. </B
> List on the <A
HREF="#FDL-TITLE-PAGE"
>Title
Page</A
>, as authors, one or more persons or entities
responsible for authorship of the modifications in the
<A
HREF="#FDL-MODIFIED"
>Modified Version</A
>,
together with at least five of the principal authors of
the <A
HREF="#FDL-DOCUMENT"
>Document</A
> (all of
its principal authors, if it has less than five).
</P
></DIV
></LI
><LI
STYLE="list-style-type: opencircle"
><DIV
CLASS="FORMALPARA"
><P
><B
>C. </B
> State on the <A
HREF="#FDL-TITLE-PAGE"
>Title
Page</A
> the name of the publisher of the <A
HREF="#FDL-MODIFIED"
>Modified Version</A
>, as the
publisher.
</P
></DIV
></LI
><LI
STYLE="list-style-type: opencircle"
><DIV
CLASS="FORMALPARA"
><P
><B
>D. </B
> Preserve all the copyright notices of the <A
HREF="#FDL-DOCUMENT"
>Document</A
>.
</P
></DIV
></LI
><LI
STYLE="list-style-type: opencircle"
><DIV
CLASS="FORMALPARA"
><P
><B
>E. </B
> Add an appropriate copyright notice for your modifications
adjacent to the other copyright notices.
</P
></DIV
></LI
><LI
STYLE="list-style-type: opencircle"
><DIV
CLASS="FORMALPARA"
><P
><B
>F. </B
> Include, immediately after the copyright notices, a
license notice giving the public permission to use the
<A
HREF="#FDL-MODIFIED"
>Modified Version</A
> under
the terms of this License, in the form shown in the
Addendum below.
</P
></DIV
></LI
><LI
STYLE="list-style-type: opencircle"
><DIV
CLASS="FORMALPARA"
><P
><B
>G. </B
> Preserve in that license notice the full lists of <A
HREF="#FDL-INVARIANT"
> Invariant Sections</A
> and
required <A
HREF="#FDL-COVER-TEXTS"
>Cover
Texts</A
> given in the <A
HREF="#FDL-DOCUMENT"
>Document's</A
> license notice.
</P
></DIV
></LI
><LI
STYLE="list-style-type: opencircle"
><DIV
CLASS="FORMALPARA"
><P
><B
>H. </B
> Include an unaltered copy of this License.
</P
></DIV
></LI
><LI
STYLE="list-style-type: opencircle"
><DIV
CLASS="FORMALPARA"
><P
><B
>I. </B
> Preserve the section entitled <SPAN
CLASS="QUOTE"
>"History"</SPAN
>, and
its title, and add to it an item stating at least the
title, year, new authors, and publisher of the <A
HREF="#FDL-MODIFIED"
>Modified Version </A
>as given on
the <A
HREF="#FDL-TITLE-PAGE"
>Title Page</A
>. If
there is no section entitled <SPAN
CLASS="QUOTE"
>"History"</SPAN
> in the
<A
HREF="#FDL-DOCUMENT"
>Document</A
>, 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.
</P
></DIV
></LI
><LI
STYLE="list-style-type: opencircle"
><DIV
CLASS="FORMALPARA"
><P
><B
>J. </B
> Preserve the network location, if any, given in the <A
HREF="#FDL-DOCUMENT"
>Document</A
> for public access
to a <A
HREF="#FDL-TRANSPARENT"
>Transparent</A
>
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 <SPAN
CLASS="QUOTE"
>"History"</SPAN
>
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.
</P
></DIV
></LI
><LI
STYLE="list-style-type: opencircle"
><DIV
CLASS="FORMALPARA"
><P
><B
>K. </B
> In any section entitled <SPAN
CLASS="QUOTE"
>"Acknowledgements"</SPAN
> or
<SPAN
CLASS="QUOTE"
>"Dedications"</SPAN
>, 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.
</P
></DIV
></LI
><LI
STYLE="list-style-type: opencircle"
><DIV
CLASS="FORMALPARA"
><P
><B
>L. </B
> Preserve all the <A
HREF="#FDL-INVARIANT"
>Invariant
Sections</A
> of the <A
HREF="#FDL-DOCUMENT"
>Document</A
>, unaltered in their
text and in their titles. Section numbers or the
equivalent are not considered part of the section titles.
</P
></DIV
></LI
><LI
STYLE="list-style-type: opencircle"
><DIV
CLASS="FORMALPARA"
><P
><B
>M. </B
> Delete any section entitled
<SPAN
CLASS="QUOTE"
>"Endorsements"</SPAN
>. Such a section may not be
included in the <A
HREF="#FDL-MODIFIED"
>Modified
Version</A
>.
</P
></DIV
></LI
><LI
STYLE="list-style-type: opencircle"
><DIV
CLASS="FORMALPARA"
><P
><B
>N. </B
> Do not retitle any existing section as
<SPAN
CLASS="QUOTE"
>"Endorsements"</SPAN
> or to conflict in title with
any <A
HREF="#FDL-INVARIANT"
>Invariant
Section</A
>.
</P
></DIV
></LI
></UL
><P
> If the <A
HREF="#FDL-MODIFIED"
>Modified Version</A
>
includes new front-matter sections or appendices that qualify as
<A
HREF="#FDL-SECONDARY"
>Secondary Sections</A
> 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 <A
HREF="#FDL-INVARIANT"
>Invariant Sections</A
> in the
Modified Version's license notice. These titles must be
distinct from any other section titles.
</P
><P
> You may add a section entitled <SPAN
CLASS="QUOTE"
>"Endorsements"</SPAN
>,
provided it contains nothing but endorsements of your <A
HREF="#FDL-MODIFIED"
>Modified Version</A
> 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.
</P
><P
> You may add a passage of up to five words as a <A
HREF="#FDL-COVER-TEXTS"
>Front-Cover Text</A
>, and a passage
of up to 25 words as a <A
HREF="#FDL-COVER-TEXTS"
>Back-Cover Text</A
>, to the end of
the list of <A
HREF="#FDL-COVER-TEXTS"
>Cover Texts</A
>
in the <A
HREF="#FDL-MODIFIED"
>Modified Version</A
>.
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 <A
HREF="#FDL-DOCUMENT"
>Document</A
>
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.
</P
><P
> The author(s) and publisher(s) of the <A
HREF="#FDL-DOCUMENT"
>Document</A
> do not by this License
give permission to use their names for publicity for or to
assert or imply endorsement of any <A
HREF="#FDL-MODIFIED"
>Modified Version </A
>.
</P
></DIV
><DIV
CLASS="SECT1"
><HR><H2
CLASS="SECT1"
><A
NAME="FDL-SECTION5"
>C.6. 5. COMBINING DOCUMENTS</A
></H2
><P
> You may combine the <A
HREF="#FDL-DOCUMENT"
>Document</A
>
with other documents released under this License, under the
terms defined in <A
HREF="#FDL-SECTION4"
>section 4</A
>
above for modified versions, provided that you include in the
combination all of the <A
HREF="#FDL-INVARIANT"
>Invariant
Sections</A
> of all of the original documents, unmodified,
and list them all as Invariant Sections of your combined work in
its license notice.
</P
><P
> The combined work need only contain one copy of this License,
and multiple identical <A
HREF="#FDL-INVARIANT"
>Invariant
Sections</A
> 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.
</P
><P
> In the combination, you must combine any sections entitled
<SPAN
CLASS="QUOTE"
>"History"</SPAN
> in the various original documents,
forming one section entitled <SPAN
CLASS="QUOTE"
>"History"</SPAN
>; likewise
combine any sections entitled <SPAN
CLASS="QUOTE"
>"Acknowledgements"</SPAN
>,
and any sections entitled <SPAN
CLASS="QUOTE"
>"Dedications"</SPAN
>. You must
delete all sections entitled <SPAN
CLASS="QUOTE"
>"Endorsements."</SPAN
>
</P
></DIV
><DIV
CLASS="SECT1"
><HR><H2
CLASS="SECT1"
><A
NAME="FDL-SECTION6"
>C.7. 6. COLLECTIONS OF DOCUMENTS</A
></H2
><P
> You may make a collection consisting of the <A
HREF="#FDL-DOCUMENT"
>Document</A
> 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.
</P
><P
> 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.
</P
></DIV
><DIV
CLASS="SECT1"
><HR><H2
CLASS="SECT1"
><A
NAME="FDL-SECTION7"
>C.8. 7. AGGREGATION WITH INDEPENDENT WORKS</A
></H2
><P
> A compilation of the <A
HREF="#FDL-DOCUMENT"
>Document</A
> 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 <A
HREF="#FDL-MODIFIED"
>Modified Version</A
>
of the Document, provided no compilation copyright is claimed
for the compilation. Such a compilation is called an
<SPAN
CLASS="QUOTE"
>"aggregate"</SPAN
>, 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 <A
HREF="#FDL-COVER-TEXTS"
>Cover Text</A
> requirement of <A
HREF="#FDL-SECTION3"
>section 3</A
> 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.
</P
></DIV
><DIV
CLASS="SECT1"
><HR><H2
CLASS="SECT1"
><A
NAME="FDL-SECTION8"
>C.9. 8. TRANSLATION</A
></H2
><P
> Translation is considered a kind of modification, so you may
distribute translations of the <A
HREF="#FDL-DOCUMENT"
>Document</A
> under the terms of <A
HREF="#FDL-SECTION4"
>section 4</A
>. Replacing <A
HREF="#FDL-INVARIANT"
> Invariant Sections</A
> 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.
</P
></DIV
><DIV
CLASS="SECT1"
><HR><H2
CLASS="SECT1"
><A
NAME="FDL-SECTION9"
>C.10. 9. TERMINATION</A
></H2
><P
> You may not copy, modify, sublicense, or distribute the <A
HREF="#FDL-DOCUMENT"
>Document</A
> 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.
</P
></DIV
><DIV
CLASS="SECT1"
><HR><H2
CLASS="SECT1"
><A
NAME="FDL-SECTION10"
>C.11. 10. FUTURE REVISIONS OF THIS LICENSE</A
></H2
><P
> The <A
HREF="http://www.gnu.org/fsf/fsf.html"
TARGET="_top"
>Free Software
Foundation</A
> 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 <A
HREF="http://www.gnu.org/copyleft"
TARGET="_top"
>http://www.gnu.org/copyleft/</A
>.
</P
><P
> Each version of the License is given a distinguishing version
number. If the <A
HREF="#FDL-DOCUMENT"
>Document</A
>
specifies that a particular numbered version of this License
<SPAN
CLASS="QUOTE"
>"or any later version"</SPAN
> 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.
</P
></DIV
><DIV
CLASS="SECT1"
><HR><H2
CLASS="SECT1"
><A
NAME="FDL-USING"
>C.12. Addendum</A
></H2
><P
> 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:
</P
><A
NAME="AEN11607"
></A
><BLOCKQUOTE
CLASS="BLOCKQUOTE"
><P
> Copyright © YEAR YOUR NAME.
</P
><P
> 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 <A
HREF="#FDL-INVARIANT"
>Invariant Sections</A
> being LIST
THEIR TITLES, with the <A
HREF="#FDL-COVER-TEXTS"
>Front-Cover Texts</A
> being LIST,
and with the <A
HREF="#FDL-COVER-TEXTS"
>Back-Cover
Texts</A
> being LIST. A copy of the license is included in
the section entitled <SPAN
CLASS="QUOTE"
>"GNU Free Documentation
License"</SPAN
>.
</P
></BLOCKQUOTE
><P
> If you have no <A
HREF="#FDL-INVARIANT"
>Invariant
Sections</A
>, write <SPAN
CLASS="QUOTE"
>"with no Invariant Sections"</SPAN
>
instead of saying which ones are invariant. If you have no
<A
HREF="#FDL-COVER-TEXTS"
>Front-Cover Texts</A
>, write
<SPAN
CLASS="QUOTE"
>"no Front-Cover Texts"</SPAN
> instead of
<SPAN
CLASS="QUOTE"
>"Front-Cover Texts being LIST"</SPAN
>; likewise for <A
HREF="#FDL-COVER-TEXTS"
>Back-Cover Texts</A
>.
</P
><P
> 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 <A
HREF="http://www.gnu.org/copyleft/gpl.html"
TARGET="_top"
> GNU General Public
License</A
>, to permit their use in free software.
</P
></DIV
></DIV
><A
NAME="AEN11623"
></A
><HR><H1
><A
NAME="AEN11623"
></A
>Bibliography</H1
><DIV
CLASS="BIBLIOENTRY"
><A
NAME="EIA608"
></A
><P
>[EIA608] Electronic Industries Alliance (<A
HREF="http://www.eia.org"
TARGET="_top"
>http://www.eia.org</A
>), <I
>EIA 608 "Recommended Practice for Line 21 Data
Service"</I
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="BIBLIOENTRY"
><A
NAME="ITU470"
></A
><P
>[ITU470] International Telecommunication Union (<A
HREF="http://www.itu.ch"
TARGET="_top"
>http://www.itu.ch</A
>), <I
>ITU-R Recommendation BT.470-6 "Conventional Television
Systems"</I
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="BIBLIOENTRY"
><A
NAME="ITU601"
></A
><P
>[ITU601] International Telecommunication Union (<A
HREF="http://www.itu.ch"
TARGET="_top"
>http://www.itu.ch</A
>), <I
>ITU-R Recommendation BT.601-5 "Studio Encoding Parameters
of Digital Television for Standard 4:3 and Wide-Screen 16:9 Aspect
Ratios"</I
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="BIBLIOENTRY"
><A
NAME="ITU709"
></A
><P
>[ITU709] International Telecommunication Union (<A
HREF="http://www.itu.ch"
TARGET="_top"
>http://www.itu.ch</A
>), <I
>ITU-R Recommendation BT.709-5 "Parameter values for the
HDTV standards for production and international programme
exchange"</I
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="BIBLIOENTRY"
><A
NAME="JFIF"
></A
><P
>[JFIF] Independent JPEG Group (<A
HREF="http://www.ijg.org"
TARGET="_top"
>http://www.ijg.org</A
>), <I
>JPEG File Interchange Format</I
><I
>: </I
><I
>Version 1.02</I
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="BIBLIOENTRY"
><A
NAME="SMPTE12M"
></A
><P
>[SMPTE12M] Society of Motion Picture and Television Engineers
(<A
HREF="http://www.smpte.org"
TARGET="_top"
>http://www.smpte.org</A
>), <I
>SMPTE 12M-1999 "Television, Audio and Film - Time and
Control Code"</I
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="BIBLIOENTRY"
><A
NAME="SMPTE170M"
></A
><P
>[SMPTE170M] Society of Motion Picture and Television Engineers
(<A
HREF="http://www.smpte.org"
TARGET="_top"
>http://www.smpte.org</A
>), <I
>SMPTE 170M-1999 "Television - Composite Analog Video
Signal - NTSC for Studio Applications"</I
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="BIBLIOENTRY"
><A
NAME="SMPTE240M"
></A
><P
>[SMPTE240M] Society of Motion Picture and Television Engineers
(<A
HREF="http://www.smpte.org"
TARGET="_top"
>http://www.smpte.org</A
>), <I
>SMPTE 240M-1999 "Television - Signal Parameters -
1125-Line High-Definition Production"</I
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="BIBLIOENTRY"
><A
NAME="TELETEXT"
></A
><P
>[TELETEXT] European Telecommunication Standards Institute
(<A
HREF="http://www.etsi.org"
TARGET="_top"
>http://www.etsi.org</A
>), <I
>ETS 300 706 "Enhanced Teletext specification"</I
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="BIBLIOENTRY"
><A
NAME="V4L"
></A
><P
>[V4L] <SPAN
CLASS="AUTHOR"
>Alan Cox</SPAN
>, <I
>Video4Linux API Specification</I
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
><DIV
CLASS="ABSTRACT"
><P
>This file is part of the Linux kernel sources under
<TT
CLASS="FILENAME"
>Documentation/video4linux</TT
>.</P
></DIV
></DIV
></DIV
><DIV
CLASS="BIBLIOENTRY"
><A
NAME="V4LPROG"
></A
><P
>[V4LPROG] <SPAN
CLASS="AUTHOR"
>Alan Cox</SPAN
>, <I
>Video4Linux Programming (a.k.a. The Video4Linux
Book)</I
>, 2000.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
><DIV
CLASS="ABSTRACT"
><P
>About V4L <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>driver</I
></SPAN
> programming. This
book is part of the Linux kernel DocBook documentation, for example at
<A
HREF="http://kernelnewbies.org/documents/"
TARGET="_top"
>http://kernelnewbies.org/documents/</A
>. SGML sources are included
in the kernel sources.</P
></DIV
></DIV
></DIV
><DIV
CLASS="BIBLIOENTRY"
><A
NAME="VPS"
></A
><P
>[VPS] European Telecommunication Standards Institute
(<A
HREF="http://www.etsi.org"
TARGET="_top"
>http://www.etsi.org</A
>), <I
>ETS 300 231 "Specification of the domestic video
Programme Delivery Control system (PDC)"</I
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="BIBLIOENTRY"
><A
NAME="WSS"
></A
><P
>[WSS] International Telecommunication Union (<A
HREF="http://www.itu.ch"
TARGET="_top"
>http://www.itu.ch</A
>), European
Telecommunication Standards Institute (<A
HREF="http://www.etsi.org"
TARGET="_top"
>http://www.etsi.org</A
>), <I
>ITU-R Recommendation BT.1119, EN 300 294 "625-line
television Wide Screen Signalling (WSS)"</I
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
></DIV
><H3
CLASS="FOOTNOTES"
>Notes</H3
><TABLE
BORDER="0"
CLASS="FOOTNOTES"
WIDTH="100%"
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="5%"
><A
NAME="FTN.AEN104"
HREF="#AEN104"
><SPAN
CLASS="footnote"
>[1]</SPAN
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="95%"
><P
>Access permissions are associated with character
device special files, we must ensure device numbers cannot change with
load order. To this end minor numbers are no longer automatically assigned
by the "videodev" module as in V4L but requested by the driver. The defaults
will suffice for most people, unless two drivers are used which compete for
the same minor numbers.</P
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="5%"
><A
NAME="FTN.AEN107"
HREF="#AEN107"
><SPAN
CLASS="footnote"
>[2]</SPAN
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="95%"
><P
>In earlier versions of the V4L2 API the module options
where named after the device special file with a "unit_" prefix, expressing
the minor number itself, not an offset. Rationale for this change is unknown.
Lastly the naming and semantics are just a convention among driver writers,
the point to note is that minor numbers are not supposed to be hardcoded
into drivers.</P
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="5%"
><A
NAME="FTN.AEN135"
HREF="#AEN135"
><SPAN
CLASS="footnote"
>[3]</SPAN
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="95%"
><P
>Given a device file name one cannot reliable find
related devices. For once names are arbitrary, they can be chosen
freely by the system administrator. Also when there are multiple
devices and only some support VBI capturing, say,
<TT
CLASS="FILENAME"
>/dev/video2</TT
> is not necessarily related to
<TT
CLASS="FILENAME"
>/dev/vbi2</TT
>. We already noted finding devices by
name or minor number is unreliable, accordingly useful is the ioctl
offered by V4L to query the minor numbers of related devices.</P
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="5%"
><A
NAME="FTN.AEN166"
HREF="#AEN166"
><SPAN
CLASS="footnote"
>[4]</SPAN
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="95%"
><P
>Drivers could recognize the
<CODE
CLASS="CONSTANT"
>O_EXCL</CODE
> open flag. Presently this is not required,
so application cannot know if it really works.</P
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="5%"
><A
NAME="FTN.AEN245"
HREF="#AEN245"
><SPAN
CLASS="footnote"
>[5]</SPAN
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="95%"
><P
>Actually struct <A
HREF="#V4L2-AUDIO"
>v4l2_audio</A
> ought to have a
<CODE
CLASS="STRUCTFIELD"
>tuner</CODE
> field like struct <A
HREF="#V4L2-INPUT"
>v4l2_input</A
>, not only
making the API more consistent but also permitting radio devices with
multiple tuners.</P
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="5%"
><A
NAME="FTN.AEN363"
HREF="#AEN363"
><SPAN
CLASS="footnote"
>[6]</SPAN
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="95%"
><P
>Some users are already confused by technical terms PAL,
NTSC and SECAM. There is no point asking them to distinguish between
B, G, D, or K when the software or hardware can do that
automatically.</P
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="5%"
><A
NAME="FTN.AEN375"
HREF="#AEN375"
><SPAN
CLASS="footnote"
>[7]</SPAN
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="95%"
><P
>An alternative to the current scheme is to use pointers
to indices as arguments of <CODE
CLASS="CONSTANT"
>VIDIOC_G_STD</CODE
> and
<CODE
CLASS="CONSTANT"
>VIDIOC_S_STD</CODE
>, the struct <A
HREF="#V4L2-INPUT"
>v4l2_input</A
> and
struct <A
HREF="#V4L2-OUTPUT"
>v4l2_output</A
> <CODE
CLASS="STRUCTFIELD"
>std</CODE
> field would be a set of
indices like <CODE
CLASS="STRUCTFIELD"
>audioset</CODE
>.</P
><P
>Indices are consistent with the rest of the API
and identify the standard unambiguously. In the present scheme of
things an enumerated standard is looked up by <A
HREF="#V4L2-STD-ID"
>v4l2_std_id</A
>. Now the
standards supported by the inputs of a device can overlap. Just
assume the tuner and composite input in the example above both
exist on a device. An enumeration of "PAL-B/G", "PAL-H/I" suggests
a choice which does not exist. We cannot merge or omit sets, because
applications would be unable to find the standards reported by
<CODE
CLASS="CONSTANT"
>VIDIOC_G_STD</CODE
>. That leaves separate enumerations
for each input. Also selecting a standard by <A
HREF="#V4L2-STD-ID"
>v4l2_std_id</A
> can be
ambiguous. Advantage of this method is that applications need not
identify the standard indirectly, after enumerating.</P
><P
>So in
summary, the lookup itself is unavoidable. The difference is only
whether the lookup is necessary to find an enumerated standard or to
switch to a standard by <A
HREF="#V4L2-STD-ID"
>v4l2_std_id</A
>.</P
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="5%"
><A
NAME="FTN.AEN407"
HREF="#AEN407"
><SPAN
CLASS="footnote"
>[8]</SPAN
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="95%"
><P
>See <A
HREF="#BUFFER"
>Section 3.5</A
> for a rationale. Probably
even USB cameras follow some well known video standard. It might have
been better to explicitly indicate elsewhere if a device cannot live
up to normal expectations, instead of this exception.</P
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="5%"
><A
NAME="FTN.AEN451"
HREF="#AEN451"
><SPAN
CLASS="footnote"
>[9]</SPAN
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="95%"
><P
>It will be more convenient for applications if drivers
make use of the <CODE
CLASS="CONSTANT"
>V4L2_CTRL_FLAG_DISABLED</CODE
> flag, but
that was never required.</P
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="5%"
><A
NAME="FTN.AEN454"
HREF="#AEN454"
><SPAN
CLASS="footnote"
>[10]</SPAN
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="95%"
><P
>Applications could call an ioctl to request events.
After another process called <A
HREF="#VIDIOC-G-CTRL"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_CTRL</CODE
></A
> or another ioctl changing
shared properties the <CODE
CLASS="FUNCTION"
>select()</CODE
> function would
indicate readability until any ioctl (querying the properties) is
called.</P
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="5%"
><A
NAME="FTN.AEN692"
HREF="#AEN692"
><SPAN
CLASS="footnote"
>[11]</SPAN
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="95%"
><P
>Enumerating formats an application has no a-priori
knowledge of (otherwise it could explicitely ask for them and need not
enumerate) seems useless, but there are applications serving as proxy
between drivers and the actual video applications for which this is
useful.</P
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="5%"
><A
NAME="FTN.AEN714"
HREF="#AEN714"
><SPAN
CLASS="footnote"
>[12]</SPAN
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="95%"
><P
>It may be desirable to refer to the cropping area in
terms of sampling frequency and scanning system lines, but in order to
support a wide range of hardware we better make as few assumptions as
possible.</P
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="5%"
><A
NAME="FTN.AEN3273"
HREF="#AEN3273"
><SPAN
CLASS="footnote"
>[13]</SPAN
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="95%"
><P
>It would be desirable if applications could depend on
drivers supporting all I/O interfaces, but as much as the complex
memory mapping I/O can be inadequate for some devices we have no
reason to require this interface, which is most useful for simple
applications capturing still images.</P
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="5%"
><A
NAME="FTN.AEN3279"
HREF="#AEN3279"
><SPAN
CLASS="footnote"
>[14]</SPAN
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="95%"
><P
>At the driver level <CODE
CLASS="FUNCTION"
>select()</CODE
> and
<CODE
CLASS="FUNCTION"
>poll()</CODE
> are the same, and
<CODE
CLASS="FUNCTION"
>select()</CODE
> is too important to be optional.</P
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="5%"
><A
NAME="FTN.AEN3296"
HREF="#AEN3296"
><SPAN
CLASS="footnote"
>[15]</SPAN
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="95%"
><P
>One could use one file descriptor and set the buffer
type field accordingly when calling <A
HREF="#VIDIOC-QBUF"
><CODE
CLASS="CONSTANT"
>VIDIOC_QBUF</CODE
></A
> etc., but it makes
the <CODE
CLASS="FUNCTION"
>select()</CODE
> function ambiguous. We also like the
clean approach of one file descriptor per logical stream. Video
overlay for example is also a logical stream, although the CPU is not
needed for continuous operation.</P
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="5%"
><A
NAME="FTN.AEN3329"
HREF="#AEN3329"
><SPAN
CLASS="footnote"
>[16]</SPAN
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="95%"
><P
>Random enqueue order permits applications processing
images out of order (such as video codecs) to return buffers earlier,
reducing the probability of data loss. Random fill order allows
drivers to reuse buffers on a LIFO-basis, taking advantage of caches
holding scatter-gather lists and the like.</P
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="5%"
><A
NAME="FTN.AEN3371"
HREF="#AEN3371"
><SPAN
CLASS="footnote"
>[17]</SPAN
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="95%"
><P
>At the driver level <CODE
CLASS="FUNCTION"
>select()</CODE
> and
<CODE
CLASS="FUNCTION"
>poll()</CODE
> are the same, and
<CODE
CLASS="FUNCTION"
>select()</CODE
> is too important to be optional. The
rest should be evident.</P
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="5%"
><A
NAME="FTN.AEN3402"
HREF="#AEN3402"
><SPAN
CLASS="footnote"
>[18]</SPAN
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="95%"
><P
>We expect that frequently used buffers are typically not
swapped out. Anyway, the process of swapping, locking or generating
scatter-gather lists may be time consuming. The delay can be masked by
the depth of the incoming buffer queue, and perhaps by maintaining
caches assuming a buffer will be soon enqueued again. On the other
hand, to optimize memory usage drivers can limit the number of buffers
locked in advance and recycle the most recently used buffers first. Of
course, the pages of empty buffers in the incoming queue need not be
saved to disk. Output buffers must be saved on the incoming and
outgoing queue because an application may share them with other
processes.</P
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="5%"
><A
NAME="FTN.AEN3438"
HREF="#AEN3438"
><SPAN
CLASS="footnote"
>[19]</SPAN
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="95%"
><P
>At the driver level <CODE
CLASS="FUNCTION"
>select()</CODE
> and
<CODE
CLASS="FUNCTION"
>poll()</CODE
> are the same, and
<CODE
CLASS="FUNCTION"
>select()</CODE
> is too important to be optional. The
rest should be evident.</P
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="5%"
><A
NAME="FTN.AEN3460"
HREF="#AEN3460"
><SPAN
CLASS="footnote"
>[20]</SPAN
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="95%"
><P
>Since no other Linux multimedia
API supports unadjusted time it would be foolish to introduce here. We
must use a universally supported clock to synchronize different media,
hence time of day.</P
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="5%"
><A
NAME="FTN.AEN4042"
HREF="#AEN4042"
><SPAN
CLASS="footnote"
>[21]</SPAN
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="95%"
><P
>A common application of two file descriptors is the
XFree86 <A
HREF="#XVIDEO"
>Xv/V4L</A
> interface driver and
a V4L2 application. While the X server controls video overlay, the
application can take advantage of memory mapping and DMA.</P
><P
>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
<SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>must</I
></SPAN
> support two file descriptors and
<SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>may</I
></SPAN
> support single fd operation.</P
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="5%"
><A
NAME="FTN.AEN4216"
HREF="#AEN4216"
><SPAN
CLASS="footnote"
>[22]</SPAN
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="95%"
><P
>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.</P
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="5%"
><A
NAME="FTN.AEN4369"
HREF="#AEN4369"
><SPAN
CLASS="footnote"
>[23]</SPAN
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="95%"
><P
>ASK: Amplitude-Shift Keying. A high signal
level represents a '1' bit, a low level a '0' bit.</P
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="5%"
><A
NAME="FTN.AEN5736"
HREF="#AEN5736"
><SPAN
CLASS="footnote"
>[24]</SPAN
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="95%"
><P
>The supported standards may overlap and we need an
unambiguous set to find the current standard returned by
<CODE
CLASS="CONSTANT"
>VIDIOC_G_STD</CODE
>.</P
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="5%"
><A
NAME="FTN.AEN8815"
HREF="#AEN8815"
><SPAN
CLASS="footnote"
>[25]</SPAN
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="95%"
><P
><CODE
CLASS="CONSTANT"
>V4L2_CTRL_FLAG_DISABLED</CODE
> was intended
for two purposes: Drivers can skip predefined controls not supported
by the hardware (although returning EINVAL would do as well), or
disable predefined and custom controls after hardware detection
without the trouble of reordering control arrays and indices.</P
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="5%"
><A
NAME="FTN.AEN9113"
HREF="#AEN9113"
><SPAN
CLASS="footnote"
>[26]</SPAN
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="95%"
><P
>For example video output requires at least two buffers,
one displayed and one filled by the application.</P
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="5%"
><A
NAME="FTN.AEN11222"
HREF="#AEN11222"
><SPAN
CLASS="footnote"
>[27]</SPAN
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="95%"
><P
>This is not implemented in XFree86.</P
></TD
></TR
></TABLE
></BODY
></HTML
>