diff options
Diffstat (limited to 'v4l/API/V4L2_API.html')
| -rw-r--r-- | v4l/API/V4L2_API.html | 39683 |
1 files changed, 0 insertions, 39683 deletions
diff --git a/v4l/API/V4L2_API.html b/v4l/API/V4L2_API.html deleted file mode 100644 index f1ef6aed3..000000000 --- a/v4l/API/V4L2_API.html +++ /dev/null @@ -1,39683 +0,0 @@ -<!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 ->
\ No newline at end of file |