Doug / smarc-fsl-linux-kernel | Embedian Git Server

Commit 53b5d5749b6fcca37c7ad60cd40feafadd390b70

Authored by Pawel Osciak 2011-01-07 12:41:33 +0800

Committed by Mauro Carvalho Chehab 2011-03-22 07:31:35 +0800

Exists in master and in 7 other branches

[media] Add multi-planar API documentation

Add DocBook documentation for the new multi-planar API extensions to the
Video for Linux 2 API DocBook.

Signed-off-by: Pawel Osciak <pawel@osciak.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>

Showing 16 changed files with 530 additions and 70 deletions Inline Diff

Documentation/DocBook/media-entities.tmpl
Documentation/DocBook/v4l/common.xml
Documentation/DocBook/v4l/compat.xml
Documentation/DocBook/v4l/dev-capture.xml
Documentation/DocBook/v4l/dev-output.xml
Documentation/DocBook/v4l/func-mmap.xml
Documentation/DocBook/v4l/func-munmap.xml
Documentation/DocBook/v4l/io.xml
Documentation/DocBook/v4l/pixfmt.xml
Documentation/DocBook/v4l/planar-apis.xml
Documentation/DocBook/v4l/v4l2.xml
Documentation/DocBook/v4l/vidioc-enum-fmt.xml
Documentation/DocBook/v4l/vidioc-g-fmt.xml
Documentation/DocBook/v4l/vidioc-qbuf.xml
Documentation/DocBook/v4l/vidioc-querybuf.xml
Documentation/DocBook/v4l/vidioc-querycap.xml

Documentation/DocBook/media-entities.tmpl

Diff comments View file @ 53b5d57

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

Documentation/DocBook/v4l/common.xml

Diff comments View file @ 53b5d57

   <title>Common API Elements</title>
   <para>Programming a V4L2 device consists of these
 steps:</para>
   <itemizedlist>
     <listitem>
       <para>Opening the device</para>
     </listitem>
     <listitem>
       <para>Changing device properties, selecting a video and audio
 input, video standard, picture brightness a.&nbsp;o.</para>
     </listitem>
     <listitem>
       <para>Negotiating a data format</para>
     </listitem>
     <listitem>
       <para>Negotiating an input/output method</para>
     </listitem>
     <listitem>
       <para>The actual input/output loop</para>
     </listitem>
     <listitem>
       <para>Closing the device</para>
     </listitem>
   </itemizedlist>
   <para>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 <xref linkend="devices" />. In this chapter we will discuss
 the basic concepts applicable to all devices.</para>
   <section id="open">
     <title>Opening and Closing Devices</title>
     <section>
       <title>Device Naming</title>
       <para>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 specified in this document.</para>
       <para>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.<footnote>
 	  <para>Access permissions are associated with character
 device special files, hence we must ensure device numbers cannot
 change with the module 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 compete for the same minor numbers.</para>
 	</footnote> The module options to select minor numbers are named
 after the device special file with a "_nr" suffix. For example "video_nr"
 for <filename>/dev/video</filename> video capture devices. The number is
 an offset to the base minor number associated with the device type.
 <footnote>
 	  <para>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.</para>
 	</footnote> When the driver supports multiple devices of the same
 type more than one minor number can be assigned, separated by commas:
 <informalexample>
 	  <screen>
 &gt; insmod mydriver.o video_nr=0,1 radio_nr=0,1</screen>
 	</informalexample></para>
       <para>In <filename>/etc/modules.conf</filename> this may be
 written as: <informalexample>
 	  <screen>
 alias char-major-81-0 mydriver
 alias char-major-81-1 mydriver
 alias char-major-81-64 mydriver              <co id="alias" />
 options mydriver video_nr=0,1 radio_nr=0,1   <co id="options" />
 	  </screen>
 	  <calloutlist>
 	    <callout arearefs="alias">
 	      <para>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).</para>
 	    </callout>
 	    <callout arearefs="options">
 	      <para>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).</para>
 	    </callout>
 	  </calloutlist>
 	</informalexample> When no minor number is given as module
 option the driver supplies a default. <xref linkend="devices" />
 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 <emphasis>offending device</emphasis> will not be
 registered. <!-- Blessed by Linus Torvalds on
 linux-kernel@vger.kernel.org, 2002-11-20. --></para>
       <para>By convention system administrators create various
 character device special files with these major and minor numbers in
 the <filename>/dev</filename> directory. The names recomended for the
 different V4L2 device types are listed in <xref linkend="devices" />.
 </para>
       <para>The creation of character special files (with
 <application>mknod</application>) is a privileged operation and
 devices cannot be opened by major and minor number. That means
 applications cannot <emphasis>reliable</emphasis> scan for loaded or
 installed drivers. The user must enter a device name, or the
 application can try the conventional device names.</para>
       <para>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
 <filename>/dev/v4l</filename> directory using the conventional device
 names above.</para>
     </section>
     <section id="related">
       <title>Related Devices</title>
       <para>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<footnote>
 	  <para>Given a device file name one cannot reliable find
 related devices. For once names are arbitrary and in a system with
 multiple devices, where only some support VBI capturing, a
 <filename>/dev/video2</filename> is not necessarily related to
 <filename>/dev/vbi2</filename>. The V4L
 <constant>VIDIOCGUNIT</constant> ioctl would require a search for a
 device file with a particular major and minor number.</para>
 	</footnote>, and to make things worse the V4L videodev module
 used to prohibit multiple opens of a device.</para>
       <para>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 <xref linkend="devices" />.</para>
       <para>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
 <filename>/dev/video</filename> (81, 0) or
 <filename>/dev/vbi</filename> (81, 224) is opened the application can
 select any one of the video capturing, overlay or VBI capturing
 functions. Without programming (e.&nbsp;g. reading from the device
 with <application>dd</application> or <application>cat</application>)
 <filename>/dev/video</filename> captures video images, while
 <filename>/dev/vbi</filename> captures raw VBI data.
 <filename>/dev/radio</filename> (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 &func-open;
 function may very well return an &EBUSY;.</para>
       <para>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 linux-media
 mailing list: &v4l-ml;.</para>
     </section>
     <section>
       <title>Multiple Opens</title>
       <para>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
 <emphasis>simultaneously</emphasis>, multiple opens allow concurrent
 use of the device by forked processes or specialized applications.</para>
       <para>Multiple opens are optional, although drivers should
 permit at least concurrent accesses without data exchange, &ie; panel
 applications. This implies &func-open; can return an &EBUSY; when the
 device is already in use, as well as &func-ioctl; functions initiating
 data exchange (namely the &VIDIOC-S-FMT; ioctl), and the &func-read;
 and &func-write; functions.</para>
       <para>Mere opening a V4L2 device does not grant exclusive
 access.<footnote>
 	  <para>Drivers could recognize the
 <constant>O_EXCL</constant> open flag. Presently this is not required,
 so applications cannot know if it really works.</para>
 	</footnote> 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
 <xref linkend="app-pri" />.</para>
     </section>
     <section>
       <title>Shared Data Streams</title>
       <para>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. <!-- For example O_EXCL when the
 application does not want to be preempted, PROT_READ mmapped buffers
 which can be mapped twice, what happens when image formats do not
 match etc.--></para>
     </section>
     <section>
       <title>Functions</title>
     <para>To open and close V4L2 devices applications use the
 &func-open; and &func-close; function, respectively. Devices are
 programmed using the &func-ioctl; function as explained in the
 following sections.</para>
     </section>
   </section>
   <section id="querycap">
     <title>Querying Capabilities</title>
     <para>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.</para>
     <para>The &VIDIOC-QUERYCAP; ioctl is available to check if the kernel
 device is compatible with this specification, and to query the <link
 linkend="devices">functions</link> and <link linkend="io">I/O
 methods</link> supported by the device. Other features can be queried
 by calling the respective ioctl, for example &VIDIOC-ENUMINPUT;
 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.</para>
     <para>All V4L2 drivers must support
 <constant>VIDIOC_QUERYCAP</constant>. Applications should always call
 this ioctl after opening the device.</para>
   </section>
   <section id="app-pri">
     <title>Application Priority</title>
     <para>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.</para>
     <para>Since these features cannot be implemented entirely in user
 space V4L2 defines the &VIDIOC-G-PRIORITY; and &VIDIOC-S-PRIORITY;
 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
 <constant>VIDIOC_S_PRIORITY</constant> after verifying the device with
 the &VIDIOC-QUERYCAP; ioctl.</para>
     <para>Ioctls changing driver properties, such as &VIDIOC-S-INPUT;,
 return an &EBUSY; after another application obtained higher priority.
 An event mechanism to notify applications about asynchronous property
 changes has been proposed but not added yet.</para>
   </section>
   <section id="video">
     <title>Video Inputs and Outputs</title>
     <para>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.</para>
     <para>To learn about the number and attributes of the
 available inputs and outputs applications can enumerate them with the
 &VIDIOC-ENUMINPUT; and &VIDIOC-ENUMOUTPUT; ioctl, respectively. The
 &v4l2-input; returned by the <constant>VIDIOC_ENUMINPUT</constant>
 ioctl also contains signal status information applicable when the
 current video input is queried.</para>
     <para>The &VIDIOC-G-INPUT; and &VIDIOC-G-OUTPUT; ioctl return the
 index of the current video input or output. To select a different
 input or output applications call the &VIDIOC-S-INPUT; and
 &VIDIOC-S-OUTPUT; 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.</para>
     <!--
     <figure id=io-tree>
       <title>Input and output enumeration is the root of most device properties.</title>
       <mediaobject>
 	<imageobject>
 	  <imagedata fileref="links.pdf" format="ps" />
 	</imageobject>
 	<imageobject>
 	  <imagedata fileref="links.gif" format="gif" />
 	</imageobject>
 	<textobject>
 	  <phrase>Links between various device property structures.</phrase>
 	</textobject>
       </mediaobject>
     </figure>
     -->
     <example>
       <title>Information about the current video input</title>
       <programlisting>
 &v4l2-input; input;
 int index;
 if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &amp;index)) {
 	perror ("VIDIOC_G_INPUT");
 	exit (EXIT_FAILURE);
 }
 memset (&amp;input, 0, sizeof (input));
 input.index = index;
 if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
 	perror ("VIDIOC_ENUMINPUT");
 	exit (EXIT_FAILURE);
 }
 printf ("Current input: %s\n", input.name);
       </programlisting>
     </example>
     <example>
       <title>Switching to the first video input</title>
       <programlisting>
 int index;
 index = 0;
 if (-1 == ioctl (fd, &VIDIOC-S-INPUT;, &amp;index)) {
 	perror ("VIDIOC_S_INPUT");
 	exit (EXIT_FAILURE);
 }
       </programlisting>
     </example>
   </section>
   <section id="audio">
     <title>Audio Inputs and Outputs</title>
     <para>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
 <emphasis>is</emphasis> an audio source, but this API associates
 tuners with video inputs or outputs only, and radio devices have
 none of these.<footnote>
 	<para>Actually &v4l2-audio; ought to have a
 <structfield>tuner</structfield> field like &v4l2-input;, not only
 making the API more consistent but also permitting radio devices with
 multiple tuners.</para>
       </footnote> A connector on a TV card to loop back the received
 audio signal to a sound card is not considered an audio output.</para>
     <para>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 <structfield>audioset</structfield> field of the
 respective &v4l2-input; or &v4l2-output;, where each bit represents
 the index number, starting at zero, of one audio input or output.</para>
     <para>To learn about the number and attributes of the
 available inputs and outputs applications can enumerate them with the
 &VIDIOC-ENUMAUDIO; and &VIDIOC-ENUMAUDOUT; ioctl, respectively. The
 &v4l2-audio; returned by the <constant>VIDIOC_ENUMAUDIO</constant> ioctl
 also contains signal status information applicable when the current
 audio input is queried.</para>
     <para>The &VIDIOC-G-AUDIO; and &VIDIOC-G-AUDOUT; ioctl report
 the current audio input and output, respectively. Note that, unlike
 &VIDIOC-G-INPUT; and &VIDIOC-G-OUTPUT; these ioctls return a structure
 as <constant>VIDIOC_ENUMAUDIO</constant> and
 <constant>VIDIOC_ENUMAUDOUT</constant> do, not just an index.</para>
     <para>To select an audio input and change its properties
 applications call the &VIDIOC-S-AUDIO; ioctl. To select an audio
 output (which presently has no changeable properties) applications
 call the &VIDIOC-S-AUDOUT; ioctl.</para>
     <para>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 <constant>V4L2_CAP_AUDIO</constant> flag in the
 &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl.</para>
     <example>
       <title>Information about the current audio input</title>
       <programlisting>
 &v4l2-audio; audio;
 memset (&amp;audio, 0, sizeof (audio));
 if (-1 == ioctl (fd, &VIDIOC-G-AUDIO;, &amp;audio)) {
 	perror ("VIDIOC_G_AUDIO");
 	exit (EXIT_FAILURE);
 }
 printf ("Current input: %s\n", audio.name);
       </programlisting>
     </example>
     <example>
       <title>Switching to the first audio input</title>
       <programlisting>
 &v4l2-audio; audio;
 memset (&amp;audio, 0, sizeof (audio)); /* clear audio.mode, audio.reserved */
 audio.index = 0;
 if (-1 == ioctl (fd, &VIDIOC-S-AUDIO;, &amp;audio)) {
 	perror ("VIDIOC_S_AUDIO");
 	exit (EXIT_FAILURE);
 }
       </programlisting>
     </example>
   </section>
   <section id="tuner">
     <title>Tuners and Modulators</title>
     <section>
       <title>Tuners</title>
       <para>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 <structfield>type</structfield> field of the respective
 &v4l2-input; returned by the &VIDIOC-ENUMINPUT; ioctl is set to
 <constant>V4L2_INPUT_TYPE_TUNER</constant> and its
 <structfield>tuner</structfield> field contains the index number of
 the tuner.</para>
       <para>Radio devices have exactly one tuner with index zero, no
 video inputs.</para>
       <para>To query and change tuner properties applications use the
 &VIDIOC-G-TUNER; and &VIDIOC-S-TUNER; ioctl, respectively. The
 &v4l2-tuner; returned by <constant>VIDIOC_G_TUNER</constant> also
 contains signal status information applicable when the tuner of the
 current video input, or a radio tuner is queried. Note that
 <constant>VIDIOC_S_TUNER</constant> 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
 <constant>V4L2_CAP_TUNER</constant> flag in the &v4l2-capability;
 returned by the &VIDIOC-QUERYCAP; ioctl when the device has one or
 more tuners.</para>
     </section>
     <section>
       <title>Modulators</title>
       <para>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 <structfield>type</structfield> field of the
 respective &v4l2-output; returned by the &VIDIOC-ENUMOUTPUT; ioctl is
 set to <constant>V4L2_OUTPUT_TYPE_MODULATOR</constant> and its
 <structfield>modulator</structfield> field contains the index number
 of the modulator. This specification does not define radio output
 devices.</para>
       <para>To query and change modulator properties applications use
 the &VIDIOC-G-MODULATOR; and &VIDIOC-S-MODULATOR; ioctl. Note that
 <constant>VIDIOC_S_MODULATOR</constant> 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 <constant>V4L2_CAP_MODULATOR</constant> flag in
 the &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl when the
 device has one or more modulators.</para>
     </section>
     <section>
       <title>Radio Frequency</title>
       <para>To get and set the tuner or modulator radio frequency
 applications use the &VIDIOC-G-FREQUENCY; and &VIDIOC-S-FREQUENCY;
 ioctl which both take a pointer to a &v4l2-frequency;. 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.</para>
     </section>
   </section>
   <section id="standard">
     <title>Video Standards</title>
     <para>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
 <structfield>std</structfield> field of &v4l2-input; and
 &v4l2-output; returned by the &VIDIOC-ENUMINPUT; and
 &VIDIOC-ENUMOUTPUT; ioctl, respectively.</para>
     <para>V4L2 defines one bit for each analog video standard
 currently in use worldwide, and sets aside bits for driver defined
 standards, &eg; 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 &VIDIOC-ENUMSTD; ioctl.</para>
     <para>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.</para>
     <para>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".<footnote>
 	<para>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.</para>
     </footnote></para>
     <para>To query and select the standard used by the current video
 input or output applications call the &VIDIOC-G-STD; and
 &VIDIOC-S-STD; ioctl, respectively. The <emphasis>received</emphasis>
 standard can be sensed with the &VIDIOC-QUERYSTD; ioctl. Note parameter of all these ioctls is a pointer to a &v4l2-std-id; type (a standard set), <emphasis>not</emphasis> an index into the standard enumeration.<footnote>
 	<para>An alternative to the current scheme is to use pointers
 to indices as arguments of <constant>VIDIOC_G_STD</constant> and
 <constant>VIDIOC_S_STD</constant>, the &v4l2-input; and
 &v4l2-output; <structfield>std</structfield> field would be a set of
 indices like <structfield>audioset</structfield>.</para>
 	<para>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 &v4l2-std-id;. 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
 <constant>VIDIOC_G_STD</constant>. That leaves separate enumerations
 for each input. Also selecting a standard by &v4l2-std-id; can be
 ambiguous. Advantage of this method is that applications need not
 identify the standard indirectly, after enumerating.</para><para>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 &v4l2-std-id;.</para>
       </footnote> Drivers must implement all video standard ioctls
 when the device has one or more video inputs or outputs.</para>
     <para>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 <itemizedlist>
 	<listitem>
 	  <para>incapable of capturing fields or frames at the nominal
 rate of the video standard, or</para>
 	</listitem>
 	<listitem>
 	  <para>where <link linkend="buffer">timestamps</link> refer
 to the instant the field or frame was received by the driver, not the
 capture time, or</para>
 	</listitem>
 	<listitem>
 	  <para>where <link linkend="buffer">sequence numbers</link>
 refer to the frames received by the driver, not the captured
 frames.</para>
 	</listitem>
       </itemizedlist> Here the driver shall set the
 <structfield>std</structfield> field of &v4l2-input; and &v4l2-output;
 to zero, the <constant>VIDIOC_G_STD</constant>,
 <constant>VIDIOC_S_STD</constant>,
 <constant>VIDIOC_QUERYSTD</constant> and
 <constant>VIDIOC_ENUMSTD</constant> ioctls shall return the
 &EINVAL;.<footnote>
 	<para>See <xref linkend="buffer" /> 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.</para>
 	    </footnote></para>
     <example>
       <title>Information about the current video standard</title>
       <programlisting>
 &v4l2-std-id; std_id;
 &v4l2-standard; standard;
 if (-1 == ioctl (fd, &VIDIOC-G-STD;, &amp;std_id)) {
 	/* 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 (&amp;standard, 0, sizeof (standard));
 standard.index = 0;
 while (0 == ioctl (fd, &VIDIOC-ENUMSTD;, &amp;standard)) {
 	if (standard.id &amp; std_id) {
 	       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);
 }
       </programlisting>
     </example>
     <example>
       <title>Listing the video standards supported by the current
 input</title>
       <programlisting>
 &v4l2-input; input;
 &v4l2-standard; standard;
 memset (&amp;input, 0, sizeof (input));
 if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &amp;input.index)) {
 	perror ("VIDIOC_G_INPUT");
 	exit (EXIT_FAILURE);
 }
 if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
 	perror ("VIDIOC_ENUM_INPUT");
 	exit (EXIT_FAILURE);
 }
 printf ("Current input %s supports:\n", input.name);
 memset (&amp;standard, 0, sizeof (standard));
 standard.index = 0;
 while (0 == ioctl (fd, &VIDIOC-ENUMSTD;, &amp;standard)) {
 	if (standard.id &amp; 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);
 }
       </programlisting>
     </example>
     <example>
       <title>Selecting a new video standard</title>
       <programlisting>
 &v4l2-input; input;
 &v4l2-std-id; std_id;
 memset (&amp;input, 0, sizeof (input));
 if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &amp;input.index)) {
 	perror ("VIDIOC_G_INPUT");
 	exit (EXIT_FAILURE);
 }
 if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
 	perror ("VIDIOC_ENUM_INPUT");
 	exit (EXIT_FAILURE);
 }
 if (0 == (input.std &amp; 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
    <emphasis>or</emphasis> G/PAL is supported. */
 std_id = V4L2_STD_PAL_BG;
 if (-1 == ioctl (fd, &VIDIOC-S-STD;, &amp;std_id)) {
 	perror ("VIDIOC_S_STD");
 	exit (EXIT_FAILURE);
 }
       </programlisting>
     </example>
   <section id="dv-timings">
 	<title>Digital Video (DV) Timings</title>
 	<para>
 	The video standards discussed so far has been dealing with Analog TV and the
 corresponding video timings. Today there are many more different hardware interfaces
 such as High Definition TV interfaces (HDMI), VGA, DVI connectors etc., that carry
 video signals and there is a need to extend the API to select the video timings
 for these interfaces. Since it is not possible to extend the &v4l2-std-id; due to
 the limited bits available, a new set of IOCTLs is added to set/get video timings at
 the input and output: </para><itemizedlist>
 	<listitem>
 	<para>DV Presets: Digital Video (DV) presets. These are IDs representing a
 video timing at the input/output. Presets are pre-defined timings implemented
 by the hardware according to video standards. A __u32 data type is used to represent
 a preset unlike the bit mask that is used in &v4l2-std-id; allowing future extensions
 to support as many different presets as needed.</para>
 	</listitem>
 	<listitem>
 	<para>Custom DV Timings: This will allow applications to define more detailed
 custom video timings for the interface. This includes parameters such as width, height,
 polarities, frontporch, backporch etc.
 	</para>
 	</listitem>
 	</itemizedlist>
 	<para>To enumerate and query the attributes of DV presets supported by a device,
 applications use the &VIDIOC-ENUM-DV-PRESETS; ioctl. To get the current DV preset,
 applications use the &VIDIOC-G-DV-PRESET; ioctl and to set a preset they use the
 &VIDIOC-S-DV-PRESET; ioctl.</para>
 	<para>To set custom DV timings for the device, applications use the
 &VIDIOC-S-DV-TIMINGS; ioctl and to get current custom DV timings they use the
 &VIDIOC-G-DV-TIMINGS; ioctl.</para>
 	<para>Applications can make use of the <xref linkend="input-capabilities" /> and
 <xref linkend="output-capabilities"/> flags to decide what ioctls are available to set the
 video timings for the device.</para>
 	</section>
   </section>
   &sub-controls;
   <section id="format">
     <title>Data Formats</title>
     <section>
       <title>Data Format Negotiation</title>
       <para>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.</para>
       <para>A single mechanism exists to negotiate all data formats
 using the aggregate &v4l2-format; and the &VIDIOC-G-FMT; and
 &VIDIOC-S-FMT; ioctls. Additionally the &VIDIOC-TRY-FMT; ioctl can be
 used to examine what the hardware <emphasis>could</emphasis> do,
 without actually selecting a new data format. The data formats
 supported by the V4L2 API are covered in the respective device section
 in <xref linkend="devices" />. For a closer look at image formats see
 <xref linkend="pixfmt" />.</para>
       <para>The <constant>VIDIOC_S_FMT</constant> 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 <constant>VIDIOC_S_FMT</constant> assigns a logical stream
 (video data, VBI data etc.) exclusively to one file descriptor.</para>
       <para>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.</para>
       <para>When applications omit the
 <constant>VIDIOC_S_FMT</constant> ioctl its locking side effects are
 implied by the next step, the selection of an I/O method with the
 &VIDIOC-REQBUFS; ioctl or implicit with the first &func-read; or
 &func-write; call.</para>
       <para>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 <emphasis>may</emphasis> support a
 switch using <constant>VIDIOC_S_FMT</constant>.</para>
       <para>All drivers exchanging data with
 applications must support the <constant>VIDIOC_G_FMT</constant> and
 <constant>VIDIOC_S_FMT</constant> ioctl. Implementation of the
 <constant>VIDIOC_TRY_FMT</constant> is highly recommended but
 optional.</para>
     </section>
     <section>
       <title>Image Format Enumeration</title>
       <para>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.<footnote>
 	  <para>Enumerating formats an application has no a-priori
 knowledge of (otherwise it could explicitly 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.</para>
 	</footnote></para>
       <para>The &VIDIOC-ENUM-FMT; ioctl must be supported
 by all drivers exchanging image data with applications.</para>
       <important>
 	<para>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.</para>
       </important>
     </section>
   </section>
+  &sub-planar-apis;
   <section id="crop">
     <title>Image Cropping, Insertion and Scaling</title>
     <para>Some video capture devices can sample a subsection of the
 picture and shrink or enlarge it to an image of arbitrary size. We
 call these abilities cropping and scaling. Some video output devices
 can scale an image up or down and insert it at an arbitrary scan line
 and horizontal offset into a video signal.</para>
     <para>Applications can use the following API to select an area in
 the video signal, query the default area and the hardware limits.
 <emphasis>Despite their name, the &VIDIOC-CROPCAP;, &VIDIOC-G-CROP;
 and &VIDIOC-S-CROP; ioctls apply to input as well as output
 devices.</emphasis></para>
     <para>Scaling requires a source and a target. On a video capture
 or overlay device the source is the video signal, and the cropping
 ioctls determine the area actually sampled. The target are images
 read by the application or overlaid onto the graphics screen. Their
 size (and position for an overlay) is negotiated with the
 &VIDIOC-G-FMT; and &VIDIOC-S-FMT; ioctls.</para>
     <para>On a video output device the source are the images passed in
 by the application, and their size is again negotiated with the
 <constant>VIDIOC_G/S_FMT</constant> ioctls, or may be encoded in a
 compressed video stream. The target is the video signal, and the
 cropping ioctls determine the area where the images are
 inserted.</para>
     <para>Source and target rectangles are defined even if the device
 does not support scaling or the <constant>VIDIOC_G/S_CROP</constant>
 ioctls. Their size (and position where applicable) will be fixed in
 this case. <emphasis>All capture and output device must support the
 <constant>VIDIOC_CROPCAP</constant> ioctl such that applications can
 determine if scaling takes place.</emphasis></para>
     <section>
       <title>Cropping Structures</title>
       <figure id="crop-scale">
 	<title>Image Cropping, Insertion and Scaling</title>
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="crop.pdf" format="PS" />
 	  </imageobject>
 	  <imageobject>
 	    <imagedata fileref="crop.gif" format="GIF" />
 	  </imageobject>
 	  <textobject>
 	    <phrase>The cropping, insertion and scaling process</phrase>
 	  </textobject>
 	</mediaobject>
       </figure>
       <para>For capture devices the coordinates of the top left
 corner, width and height of the area which can be sampled is given by
 the <structfield>bounds</structfield> substructure of the
 &v4l2-cropcap; returned by the <constant>VIDIOC_CROPCAP</constant>
 ioctl. To support a wide range of hardware this specification does not
 define an origin or units. However by convention drivers should
 horizontally count unscaled samples relative to 0H (the leading edge
 of the horizontal sync pulse, see <xref linkend="vbi-hsync" />).
 Vertically ITU-R line
 numbers of the first field (<xref linkend="vbi-525" />, <xref
 linkend="vbi-625" />), multiplied by two if the driver can capture both
 fields.</para>
       <para>The top left corner, width and height of the source
 rectangle, that is the area actually sampled, is given by &v4l2-crop;
 using the same coordinate system as &v4l2-cropcap;. Applications can
 use the <constant>VIDIOC_G_CROP</constant> and
 <constant>VIDIOC_S_CROP</constant> ioctls to get and set this
 rectangle. It must lie completely within the capture boundaries and
 the driver may further adjust the requested size and/or position
 according to hardware limitations.</para>
       <para>Each capture device has a default source rectangle, given
 by the <structfield>defrect</structfield> substructure of
 &v4l2-cropcap;. 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. Drivers shall reset
 the source rectangle to the default when the driver is first loaded,
 but not later.</para>
       <para>For output devices these structures and ioctls are used
 accordingly, defining the <emphasis>target</emphasis> rectangle where
 the images will be inserted into the video signal.</para>
     </section>
     <section>
       <title>Scaling Adjustments</title>
       <para>Video hardware can have various cropping, insertion and
 scaling limitations. It may only scale up or down, support only
 discrete scaling factors, or have different scaling abilities in
 horizontal and vertical direction. Also it may not support scaling at
 all. At the same time the &v4l2-crop; rectangle may have to be
 aligned, and both the source and target rectangles may have arbitrary
 upper and lower size limits. In particular the maximum
 <structfield>width</structfield> and <structfield>height</structfield>
 in &v4l2-crop; may be smaller than the
 &v4l2-cropcap;.<structfield>bounds</structfield> area. Therefore, as
 usual, drivers are expected to adjust the requested parameters and
 return the actual values selected.</para>
       <para>Applications can change the source or the target rectangle
 first, as they may prefer a particular image size or a certain area in
 the video signal. If the driver has to adjust both to satisfy hardware
 limitations, the last requested rectangle shall take priority, and the
 driver should preferably adjust the opposite one. The &VIDIOC-TRY-FMT;
 ioctl however shall not change the driver state and therefore only
 adjust the requested rectangle.</para>
       <para>Suppose scaling on a video capture device is restricted to
 a factor 1:1 or 2:1 in either direction and the target image size must
 be a multiple of 16&nbsp;&times;&nbsp;16 pixels. The source cropping
 rectangle is set to defaults, which are also the upper limit in this
 example, of 640&nbsp;&times;&nbsp;400 pixels at offset 0,&nbsp;0. An
 application requests an image size of 300&nbsp;&times;&nbsp;225
 pixels, assuming video will be scaled down from the "full picture"
 accordingly. The driver sets the image size to the closest possible
 values 304&nbsp;&times;&nbsp;224, then chooses the cropping rectangle
 closest to the requested size, that is 608&nbsp;&times;&nbsp;224
 (224&nbsp;&times;&nbsp;2:1 would exceed the limit 400). The offset
 0,&nbsp;0 is still valid, thus unmodified. Given the default cropping
 rectangle reported by <constant>VIDIOC_CROPCAP</constant> the
 application can easily propose another offset to center the cropping
 rectangle.</para>
       <para>Now the application may insist on covering an area using a
 picture aspect ratio closer to the original request, so it asks for a
 cropping rectangle of 608&nbsp;&times;&nbsp;456 pixels. The present
 scaling factors limit cropping to 640&nbsp;&times;&nbsp;384, so the
 driver returns the cropping size 608&nbsp;&times;&nbsp;384 and adjusts
 the image size to closest possible 304&nbsp;&times;&nbsp;192.</para>
     </section>
     <section>
       <title>Examples</title>
       <para>Source and target rectangles shall remain unchanged across
 closing and reopening a device, such that piping data into or out of a
 device will work without special preparations. More advanced
 applications should ensure the parameters are suitable before starting
 I/O.</para>
       <example>
 	<title>Resetting the cropping parameters</title>
 	<para>(A video capture device is assumed; change
 <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> for other
 devices.)</para>
 	<programlisting>
 &v4l2-cropcap; cropcap;
 &v4l2-crop; crop;
 memset (&amp;cropcap, 0, sizeof (cropcap));
 cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
 if (-1 == ioctl (fd, &VIDIOC-CROPCAP;, &amp;cropcap)) {
 	perror ("VIDIOC_CROPCAP");
 	exit (EXIT_FAILURE);
 }
 memset (&amp;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, &VIDIOC-S-CROP;, &amp;crop)
     &amp;&amp; errno != EINVAL) {
 	perror ("VIDIOC_S_CROP");
 	exit (EXIT_FAILURE);
 }
       </programlisting>
       </example>
       <example>
 	<title>Simple downscaling</title>
 	<para>(A video capture device is assumed.)</para>
 	<programlisting>
 &v4l2-cropcap; cropcap;
 &v4l2-format; format;
 reset_cropping_parameters ();
 /* Scale down to 1/4 size of full picture. */
 memset (&amp;format, 0, sizeof (format)); /* defaults */
 format.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
 format.fmt.pix.width = cropcap.defrect.width &gt;&gt; 1;
 format.fmt.pix.height = cropcap.defrect.height &gt;&gt; 1;
 format.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV;
 if (-1 == ioctl (fd, &VIDIOC-S-FMT;, &amp;format)) {
 	perror ("VIDIOC_S_FORMAT");
 	exit (EXIT_FAILURE);
 }
 /* We could check the actual image size now, the actual scaling factor
    or if the driver can scale at all. */
 	</programlisting>
       </example>
       <example>
 	<title>Selecting an output area</title>
 	<programlisting>
 &v4l2-cropcap; cropcap;
 &v4l2-crop; crop;
 memset (&amp;cropcap, 0, sizeof (cropcap));
 cropcap.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
 if (-1 == ioctl (fd, VIDIOC_CROPCAP;, &amp;cropcap)) {
 	perror ("VIDIOC_CROPCAP");
 	exit (EXIT_FAILURE);
 }
 memset (&amp;crop, 0, sizeof (crop));
 crop.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
 crop.c = cropcap.defrect;
 /* Scale the width and height to 50 % of their original size
    and center the output. */
 crop.c.width /= 2;
 crop.c.height /= 2;
 crop.c.left += crop.c.width / 2;
 crop.c.top += crop.c.height / 2;
 /* Ignore if cropping is not supported (EINVAL). */
 if (-1 == ioctl (fd, VIDIOC_S_CROP, &amp;crop)
     &amp;&amp; errno != EINVAL) {
 	perror ("VIDIOC_S_CROP");
 	exit (EXIT_FAILURE);
 }
 </programlisting>
       </example>
       <example>
 	<title>Current scaling factor and pixel aspect</title>
 	<para>(A video capture device is assumed.)</para>
 	<programlisting>
 &v4l2-cropcap; cropcap;
 &v4l2-crop; crop;
 &v4l2-format; format;
 double hscale, vscale;
 double aspect;
 int dwidth, dheight;
 memset (&amp;cropcap, 0, sizeof (cropcap));
 cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
 if (-1 == ioctl (fd, &VIDIOC-CROPCAP;, &amp;cropcap)) {
 	perror ("VIDIOC_CROPCAP");
 	exit (EXIT_FAILURE);
 }
 memset (&amp;crop, 0, sizeof (crop));
 crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
 if (-1 == ioctl (fd, &VIDIOC-G-CROP;, &amp;crop)) {
 	if (errno != EINVAL) {
 		perror ("VIDIOC_G_CROP");
 		exit (EXIT_FAILURE);
 	}
 	/* Cropping not supported. */
 	crop.c = cropcap.defrect;
 }
 memset (&amp;format, 0, sizeof (format));
 format.fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
 if (-1 == ioctl (fd, &VIDIOC-G-FMT;, &amp;format)) {
 	perror ("VIDIOC_G_FMT");
 	exit (EXIT_FAILURE);
 }
 /* The scaling applied by the driver. */
 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;
 /* Devices following ITU-R BT.601 do not capture
    square pixels. For playback on a computer monitor
    we should scale the images to this size. */
 dwidth = format.fmt.pix.width / aspect;
 dheight = format.fmt.pix.height;
 	</programlisting>
       </example>
     </section>
   </section>
   <section id="streaming-par">
     <title>Streaming Parameters</title>
     <para>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 &VIDIOC-S-PARM; ioctl.</para>
     <para>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 especially useful when using
 the &func-read; or &func-write;, which are not augmented by timestamps
 or sequence counters, and to avoid unnecessary data copying.</para>
     <para>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 &func-read;
 function.</para>
     <para>To get and set the streaming parameters applications call
 the &VIDIOC-G-PARM; and &VIDIOC-S-PARM; ioctl, respectively. They take
 a pointer to a &v4l2-streamparm;, which contains a union holding
 separate parameters for input and output devices.</para>
     <para>These ioctls are optional, drivers need not implement
 them. If so, they return the &EINVAL;.</para>
   </section>
   <!--
 Local Variables:
 mode: sgml
 sgml-parent-document: "v4l2.sgml"
 indent-tabs-mode: nil
 End:
   -->

Documentation/DocBook/v4l/compat.xml

Diff comments View file @ 53b5d57

   <title>Changes</title>
   <para>The following chapters document the evolution of the V4L2 API,
 errata or extensions. They are also intended to help application and
 driver writers to port or update their code.</para>
   <section id="diff-v4l">
     <title>Differences between V4L and V4L2</title>
     <para>The Video For Linux API was first introduced in Linux 2.1 to
 unify and replace various TV and radio device related interfaces,
 developed 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 applications in
 the future, either directly or through the V4L2 compatibility layer in
 the <filename>videodev</filename> kernel module translating ioctls on
 the fly. For a transition period not all drivers will support the V4L2
 API.</para>
     <section>
       <title>Opening and Closing Devices</title>
       <para>For compatibility reasons the character device file names
 recommended for V4L2 video capture, overlay, radio and raw
 vbi capture devices did not change from those used by V4L. They are
 listed in <xref linkend="devices" /> and below in <xref
 	  linkend="v4l-dev" />.</para>
       <para>The teletext devices (minor range 192-223) have been removed in
 V4L2 and no longer exist. There is no hardware available anymore for handling
 pure teletext. Instead raw or sliced VBI is used.</para>
       <para>The V4L <filename>videodev</filename> module automatically
 assigns minor numbers to drivers in load order, depending on the
 registered device type. We recommend that V4L2 drivers by default
 register devices with the same numbers, but the system administrator
 can assign arbitrary minor numbers using driver module options. The
 major device number remains 81.</para>
       <table id="v4l-dev">
 	<title>V4L Device Types, Names and Numbers</title>
 	<tgroup cols="3">
 	  <thead>
 	    <row>
 	      <entry>Device Type</entry>
 	      <entry>File Name</entry>
 	      <entry>Minor Numbers</entry>
 	    </row>
 	  </thead>
 	  <tbody valign="top">
 	    <row>
 	      <entry>Video capture and overlay</entry>
 	      <entry><para><filename>/dev/video</filename> and
 <filename>/dev/bttv0</filename><footnote> <para>According to
 Documentation/devices.txt these should be symbolic links to
 <filename>/dev/video0</filename>. Note the original bttv interface is
 not compatible with V4L or V4L2.</para> </footnote>,
 <filename>/dev/video0</filename> to
 <filename>/dev/video63</filename></para></entry>
 	      <entry>0-63</entry>
 	    </row>
 	    <row>
 	      <entry>Radio receiver</entry>
 	      <entry><para><filename>/dev/radio</filename><footnote>
 		    <para>According to
 <filename>Documentation/devices.txt</filename> a symbolic link to
 <filename>/dev/radio0</filename>.</para>
 		  </footnote>, <filename>/dev/radio0</filename> to
 <filename>/dev/radio63</filename></para></entry>
 	      <entry>64-127</entry>
 	    </row>
 	    <row>
 	      <entry>Raw VBI capture</entry>
 	      <entry><para><filename>/dev/vbi</filename>,
 <filename>/dev/vbi0</filename> to
 <filename>/dev/vbi31</filename></para></entry>
 	      <entry>224-255</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </table>
       <para>V4L prohibits (or used to prohibit) multiple opens of a
 device file. V4L2 drivers <emphasis>may</emphasis> support multiple
 opens, see <xref linkend="open" /> for details and consequences.</para>
       <para>V4L drivers respond to V4L2 ioctls with an &EINVAL;. The
 compatibility layer in the V4L2 <filename>videodev</filename> module
 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 <xref
 	  linkend="driver" />.</para>
     </section>
     <section>
       <title>Querying Capabilities</title>
       <para>The V4L <constant>VIDIOCGCAP</constant> ioctl is
 equivalent to V4L2's &VIDIOC-QUERYCAP;.</para>
       <para>The <structfield>name</structfield> field in struct
 <structname>video_capability</structname> became
 <structfield>card</structfield> in &v4l2-capability;,
 <structfield>type</structfield> was replaced by
 <structfield>capabilities</structfield>. 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 <xref linkend="open" /> for an
 introduction.<informaltable>
 	  <tgroup cols="3">
 	    <thead>
 	      <row>
 		<entry>struct
 <structname>video_capability</structname>
 <structfield>type</structfield></entry>
 		<entry>&v4l2-capability;
 <structfield>capabilities</structfield> flags</entry>
 		<entry>Purpose</entry>
 	      </row>
 	    </thead>
 	    <tbody valign="top">
 	      <row>
 		<entry><constant>VID_TYPE_CAPTURE</constant></entry>
 		<entry><constant>V4L2_CAP_VIDEO_CAPTURE</constant></entry>
 		<entry>The <link linkend="capture">video
 capture</link> interface is supported.</entry>
 	      </row>
 	      <row>
 		<entry><constant>VID_TYPE_TUNER</constant></entry>
 		<entry><constant>V4L2_CAP_TUNER</constant></entry>
 		<entry>The device has a <link linkend="tuner">tuner or
 modulator</link>.</entry>
 	      </row>
 	      <row>
 		<entry><constant>VID_TYPE_TELETEXT</constant></entry>
 		<entry><constant>V4L2_CAP_VBI_CAPTURE</constant></entry>
 		<entry>The <link linkend="raw-vbi">raw VBI
 capture</link> interface is supported.</entry>
 	      </row>
 	      <row>
 		<entry><constant>VID_TYPE_OVERLAY</constant></entry>
 		<entry><constant>V4L2_CAP_VIDEO_OVERLAY</constant></entry>
 		<entry>The <link linkend="overlay">video
 overlay</link> interface is supported.</entry>
 	      </row>
 	      <row>
 		<entry><constant>VID_TYPE_CHROMAKEY</constant></entry>
 		<entry><constant>V4L2_FBUF_CAP_CHROMAKEY</constant> in
 field <structfield>capability</structfield> of
 &v4l2-framebuffer;</entry>
 		<entry>Whether chromakey overlay is supported. For
 more information on overlay see
 <xref linkend="overlay" />.</entry>
 	      </row>
 	      <row>
 		<entry><constant>VID_TYPE_CLIPPING</constant></entry>
 		<entry><constant>V4L2_FBUF_CAP_LIST_CLIPPING</constant>
 and <constant>V4L2_FBUF_CAP_BITMAP_CLIPPING</constant> in field
 <structfield>capability</structfield> of &v4l2-framebuffer;</entry>
 		<entry>Whether clipping the overlaid image is
 supported, see <xref linkend="overlay" />.</entry>
 	      </row>
 	      <row>
 		<entry><constant>VID_TYPE_FRAMERAM</constant></entry>
 		<entry><constant>V4L2_FBUF_CAP_EXTERNOVERLAY</constant>
 <emphasis>not set</emphasis> in field
 <structfield>capability</structfield> of &v4l2-framebuffer;</entry>
 		<entry>Whether overlay overwrites frame buffer memory,
 see <xref linkend="overlay" />.</entry>
 	      </row>
 	      <row>
 		<entry><constant>VID_TYPE_SCALES</constant></entry>
 		<entry><constant>-</constant></entry>
 		<entry>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 &VIDIOC-S-CROP; and &VIDIOC-S-FMT;
 ioctl, respectively. The driver returns the closest sizes possible.
 For more information on cropping and scaling see <xref
 		    linkend="crop" />.</entry>
 	      </row>
 	      <row>
 		<entry><constant>VID_TYPE_MONOCHROME</constant></entry>
 		<entry><constant>-</constant></entry>
 		<entry>Applications can enumerate the supported image
 formats with the &VIDIOC-ENUM-FMT; ioctl to determine if the device
 supports grey scale capturing only. For more information on image
 formats see <xref linkend="pixfmt" />.</entry>
 	      </row>
 	      <row>
 		<entry><constant>VID_TYPE_SUBCAPTURE</constant></entry>
 		<entry><constant>-</constant></entry>
 		<entry>Applications can call the &VIDIOC-G-CROP; ioctl
 to determine if the device supports capturing a subsection of the full
 picture ("cropping" in V4L2). If not, the ioctl returns the &EINVAL;.
 For more information on cropping and scaling see <xref
 		    linkend="crop" />.</entry>
 	      </row>
 	      <row>
 		<entry><constant>VID_TYPE_MPEG_DECODER</constant></entry>
 		<entry><constant>-</constant></entry>
 		<entry>Applications can enumerate the supported image
 formats with the &VIDIOC-ENUM-FMT; ioctl to determine if the device
 supports MPEG streams.</entry>
 	      </row>
 	      <row>
 		<entry><constant>VID_TYPE_MPEG_ENCODER</constant></entry>
 		<entry><constant>-</constant></entry>
 		<entry>See above.</entry>
 	      </row>
 	      <row>
 		<entry><constant>VID_TYPE_MJPEG_DECODER</constant></entry>
 		<entry><constant>-</constant></entry>
 		<entry>See above.</entry>
 	      </row>
 	      <row>
 		<entry><constant>VID_TYPE_MJPEG_ENCODER</constant></entry>
 		<entry><constant>-</constant></entry>
 		<entry>See above.</entry>
 	      </row>
 	    </tbody>
 	  </tgroup>
 	</informaltable></para>
       <para>The <structfield>audios</structfield> field was replaced
 by <structfield>capabilities</structfield> flag
 <constant>V4L2_CAP_AUDIO</constant>, indicating
 <emphasis>if</emphasis> the device has any audio inputs or outputs. To
 determine their number applications can enumerate audio inputs with
 the &VIDIOC-G-AUDIO; ioctl. The audio ioctls are described in <xref
 	  linkend="audio" />.</para>
       <para>The <structfield>maxwidth</structfield>,
 <structfield>maxheight</structfield>,
 <structfield>minwidth</structfield> and
 <structfield>minheight</structfield> fields were removed. Calling the
 &VIDIOC-S-FMT; or &VIDIOC-TRY-FMT; ioctl with the desired dimensions
 returns the closest size possible, taking into account the current
 video standard, cropping and scaling limitations.</para>
     </section>
     <section>
       <title>Video Sources</title>
       <para>V4L provides the <constant>VIDIOCGCHAN</constant> and
 <constant>VIDIOCSCHAN</constant> ioctl using struct
 <structname>video_channel</structname> to enumerate
 the video inputs of a V4L device. The equivalent V4L2 ioctls
 are &VIDIOC-ENUMINPUT;, &VIDIOC-G-INPUT; and &VIDIOC-S-INPUT;
 using &v4l2-input; as discussed in <xref linkend="video" />.</para>
       <para>The <structfield>channel</structfield> field counting
 inputs was renamed to <structfield>index</structfield>, the video
 input types were renamed as follows: <informaltable>
 	  <tgroup cols="2">
 	    <thead>
 	      <row>
 		<entry>struct <structname>video_channel</structname>
 <structfield>type</structfield></entry>
 		<entry>&v4l2-input;
 <structfield>type</structfield></entry>
 	      </row>
 	    </thead>
 	    <tbody valign="top">
 	      <row>
 		<entry><constant>VIDEO_TYPE_TV</constant></entry>
 		<entry><constant>V4L2_INPUT_TYPE_TUNER</constant></entry>
 	      </row>
 	      <row>
 		<entry><constant>VIDEO_TYPE_CAMERA</constant></entry>
 		<entry><constant>V4L2_INPUT_TYPE_CAMERA</constant></entry>
 	      </row>
 	    </tbody>
 	  </tgroup>
 	</informaltable></para>
       <para>Unlike the <structfield>tuners</structfield> field
 expressing the number of tuners of this input, V4L2 assumes each video
 input is connected to at most one tuner. However a tuner can have more
 than one input, &ie; RF connectors, and a device can have multiple
 tuners. The index number of the tuner associated with the input, if
 any, is stored in field <structfield>tuner</structfield> of
 &v4l2-input;. Enumeration of tuners is discussed in <xref
 	  linkend="tuner" />.</para>
       <para>The redundant <constant>VIDEO_VC_TUNER</constant> flag was
 dropped. Video inputs associated with a tuner are of type
 <constant>V4L2_INPUT_TYPE_TUNER</constant>. The
 <constant>VIDEO_VC_AUDIO</constant> flag was replaced by the
 <structfield>audioset</structfield> field. V4L2 considers devices with
 up to 32 audio inputs. Each set bit in the
 <structfield>audioset</structfield> field represents one audio input
 this video input combines with. For information about audio inputs and
 how to switch between them see <xref linkend="audio" />.</para>
       <para>The <structfield>norm</structfield> field describing the
 supported video standards was replaced by
 <structfield>std</structfield>. The V4L specification mentions a flag
 <constant>VIDEO_VC_NORM</constant> indicating whether the standard can
 be changed. This flag was a later addition together with the
 <structfield>norm</structfield> field and has been removed in the
 meantime. V4L2 has a similar, albeit more comprehensive approach
 to video standards, see <xref linkend="standard" /> for more
 information.</para>
     </section>
     <section>
       <title>Tuning</title>
       <para>The V4L <constant>VIDIOCGTUNER</constant> and
 <constant>VIDIOCSTUNER</constant> ioctl and struct
 <structname>video_tuner</structname> can be used to enumerate the
 tuners of a V4L TV or radio device. The equivalent V4L2 ioctls are
 &VIDIOC-G-TUNER; and &VIDIOC-S-TUNER; using &v4l2-tuner;. Tuners are
 covered in <xref linkend="tuner" />.</para>
       <para>The <structfield>tuner</structfield> field counting tuners
 was renamed to <structfield>index</structfield>. The fields
 <structfield>name</structfield>, <structfield>rangelow</structfield>
 and <structfield>rangehigh</structfield> remained unchanged.</para>
       <para>The <constant>VIDEO_TUNER_PAL</constant>,
 <constant>VIDEO_TUNER_NTSC</constant> and
 <constant>VIDEO_TUNER_SECAM</constant> flags indicating the supported
 video standards were dropped. This information is now contained in the
 associated &v4l2-input;. No replacement exists for the
 <constant>VIDEO_TUNER_NORM</constant> flag indicating whether the
 video standard can be switched. The <structfield>mode</structfield>
 field to select a different video standard was replaced by a whole new
 set of ioctls and structures described in <xref linkend="standard" />.
 Due to its ubiquity it should be mentioned the BTTV driver supports
 several standards in addition to the regular
 <constant>VIDEO_MODE_PAL</constant> (0),
 <constant>VIDEO_MODE_NTSC</constant>,
 <constant>VIDEO_MODE_SECAM</constant> and
 <constant>VIDEO_MODE_AUTO</constant> (3). Namely N/PAL Argentina,
 M/PAL, N/PAL, and NTSC Japan with numbers 3-6 (sic).</para>
       <para>The <constant>VIDEO_TUNER_STEREO_ON</constant> flag
 indicating stereo reception became
 <constant>V4L2_TUNER_SUB_STEREO</constant> in field
 <structfield>rxsubchans</structfield>. This field also permits the
 detection of monaural and bilingual audio, see the definition of
 &v4l2-tuner; for details. Presently no replacement exists for the
 <constant>VIDEO_TUNER_RDS_ON</constant> and
 <constant>VIDEO_TUNER_MBS_ON</constant> flags.</para>
       <para> The <constant>VIDEO_TUNER_LOW</constant> flag was renamed
 to <constant>V4L2_TUNER_CAP_LOW</constant> in the &v4l2-tuner;
 <structfield>capability</structfield> field.</para>
       <para>The <constant>VIDIOCGFREQ</constant> and
 <constant>VIDIOCSFREQ</constant> ioctl to change the tuner frequency
 where renamed to &VIDIOC-G-FREQUENCY; and  &VIDIOC-S-FREQUENCY;. They
 take a pointer to a &v4l2-frequency; instead of an unsigned long
 integer.</para>
     </section>
     <section id="v4l-image-properties">
       <title>Image Properties</title>
       <para>V4L2 has no equivalent of the
 <constant>VIDIOCGPICT</constant> and <constant>VIDIOCSPICT</constant>
 ioctl and struct <structname>video_picture</structname>. The following
 fields where replaced by V4L2 controls accessible with the
 &VIDIOC-QUERYCTRL;, &VIDIOC-G-CTRL; and &VIDIOC-S-CTRL; ioctls:<informaltable>
 	  <tgroup cols="2">
 	    <thead>
 	      <row>
 		<entry>struct <structname>video_picture</structname></entry>
 		<entry>V4L2 Control ID</entry>
 	      </row>
 	    </thead>
 	    <tbody valign="top">
 	      <row>
 		<entry><structfield>brightness</structfield></entry>
 		<entry><constant>V4L2_CID_BRIGHTNESS</constant></entry>
 	      </row>
 	      <row>
 		<entry><structfield>hue</structfield></entry>
 		<entry><constant>V4L2_CID_HUE</constant></entry>
 	      </row>
 	      <row>
 		<entry><structfield>colour</structfield></entry>
 		<entry><constant>V4L2_CID_SATURATION</constant></entry>
 	      </row>
 	      <row>
 		<entry><structfield>contrast</structfield></entry>
 		<entry><constant>V4L2_CID_CONTRAST</constant></entry>
 	      </row>
 	      <row>
 		<entry><structfield>whiteness</structfield></entry>
 		<entry><constant>V4L2_CID_WHITENESS</constant></entry>
 	      </row>
 	    </tbody>
 	  </tgroup>
 	</informaltable></para>
       <para>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 &VIDIOC-QUERYCTRL;
 ioctl. For general information about controls see <xref
 linkend="control" />.</para>
       <para>The <structfield>depth</structfield> (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 <structfield>palette</structfield> field
 moved into the &v4l2-pix-format;:<informaltable>
 	  <tgroup cols="2">
 	    <thead>
 	      <row>
 		<entry>struct <structname>video_picture</structname>
 <structfield>palette</structfield></entry>
 		<entry>&v4l2-pix-format;
 <structfield>pixfmt</structfield></entry>
 	      </row>
 	    </thead>
 	    <tbody valign="top">
 	      <row>
 		<entry><constant>VIDEO_PALETTE_GREY</constant></entry>
 		<entry><para><link
 linkend="V4L2-PIX-FMT-GREY"><constant>V4L2_PIX_FMT_GREY</constant></link></para></entry>
 	      </row>
 	      <row>
 		<entry><constant>VIDEO_PALETTE_HI240</constant></entry>
 		<entry><para><link
 linkend="pixfmt-reserved"><constant>V4L2_PIX_FMT_HI240</constant></link><footnote>
 		      <para>This is a custom format used by the BTTV
 driver, not one of the V4L2 standard formats.</para>
 		    </footnote></para></entry>
 	      </row>
 	      <row>
 		<entry><constant>VIDEO_PALETTE_RGB565</constant></entry>
 		<entry><para><link
 linkend="pixfmt-rgb"><constant>V4L2_PIX_FMT_RGB565</constant></link></para></entry>
 	      </row>
 	      <row>
 		<entry><constant>VIDEO_PALETTE_RGB555</constant></entry>
 		<entry><para><link
 linkend="pixfmt-rgb"><constant>V4L2_PIX_FMT_RGB555</constant></link></para></entry>
 	      </row>
 	      <row>
 		<entry><constant>VIDEO_PALETTE_RGB24</constant></entry>
 		<entry><para><link
 linkend="pixfmt-rgb"><constant>V4L2_PIX_FMT_BGR24</constant></link></para></entry>
 	      </row>
 	      <row>
 		<entry><constant>VIDEO_PALETTE_RGB32</constant></entry>
 		<entry><para><link
 linkend="pixfmt-rgb"><constant>V4L2_PIX_FMT_BGR32</constant></link><footnote>
 		      <para>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 <xref linkend="pixfmt-rgb" />.</para>
 		    </footnote></para></entry>
 	      </row>
 	      <row>
 		<entry><constant>VIDEO_PALETTE_YUV422</constant></entry>
 		<entry><para><link
 linkend="V4L2-PIX-FMT-YUYV"><constant>V4L2_PIX_FMT_YUYV</constant></link></para></entry>
 	      </row>
 	      <row>
 		<entry><para><constant>VIDEO_PALETTE_YUYV</constant><footnote>
 		      <para><constant>VIDEO_PALETTE_YUV422</constant>
 and <constant>VIDEO_PALETTE_YUYV</constant> are the same formats. Some
 V4L drivers respond to one, some to the other.</para>
 		    </footnote></para></entry>
 		<entry><para><link
 linkend="V4L2-PIX-FMT-YUYV"><constant>V4L2_PIX_FMT_YUYV</constant></link></para></entry>
 	      </row>
 	      <row>
 		<entry><constant>VIDEO_PALETTE_UYVY</constant></entry>
 		<entry><para><link
 linkend="V4L2-PIX-FMT-UYVY"><constant>V4L2_PIX_FMT_UYVY</constant></link></para></entry>
 	      </row>
 	      <row>
 		<entry><constant>VIDEO_PALETTE_YUV420</constant></entry>
 		<entry>None</entry>
 	      </row>
 	      <row>
 		<entry><constant>VIDEO_PALETTE_YUV411</constant></entry>
 		<entry><para><link
 linkend="V4L2-PIX-FMT-Y41P"><constant>V4L2_PIX_FMT_Y41P</constant></link><footnote>
 		      <para>Not to be confused with
 <constant>V4L2_PIX_FMT_YUV411P</constant>, which is a planar
 format.</para> </footnote></para></entry>
 	      </row>
 	      <row>
 		<entry><constant>VIDEO_PALETTE_RAW</constant></entry>
 		<entry><para>None<footnote> <para>V4L explains this
 as: "RAW capture (BT848)"</para> </footnote></para></entry>
 	      </row>
 	      <row>
 		<entry><constant>VIDEO_PALETTE_YUV422P</constant></entry>
 		<entry><para><link
 linkend="V4L2-PIX-FMT-YUV422P"><constant>V4L2_PIX_FMT_YUV422P</constant></link></para></entry>
 	      </row>
 	      <row>
 		<entry><constant>VIDEO_PALETTE_YUV411P</constant></entry>
 		<entry><para><link
 linkend="V4L2-PIX-FMT-YUV411P"><constant>V4L2_PIX_FMT_YUV411P</constant></link><footnote>
 		      <para>Not to be confused with
 <constant>V4L2_PIX_FMT_Y41P</constant>, which is a packed
 format.</para> </footnote></para></entry>
 	      </row>
 	      <row>
 		<entry><constant>VIDEO_PALETTE_YUV420P</constant></entry>
 		<entry><para><link
 linkend="V4L2-PIX-FMT-YVU420"><constant>V4L2_PIX_FMT_YVU420</constant></link></para></entry>
 	      </row>
 	      <row>
 		<entry><constant>VIDEO_PALETTE_YUV410P</constant></entry>
 		<entry><para><link
 linkend="V4L2-PIX-FMT-YVU410"><constant>V4L2_PIX_FMT_YVU410</constant></link></para></entry>
 	      </row>
 	    </tbody>
 	  </tgroup>
 	</informaltable></para>
       <para>V4L2 image formats are defined in <xref
 linkend="pixfmt" />. The image format can be selected with the
 &VIDIOC-S-FMT; ioctl.</para>
     </section>
     <section>
       <title>Audio</title>
       <para>The <constant>VIDIOCGAUDIO</constant> and
 <constant>VIDIOCSAUDIO</constant> ioctl and struct
 <structname>video_audio</structname> are used to enumerate the
 audio inputs of a V4L device. The equivalent V4L2 ioctls are
 &VIDIOC-G-AUDIO; and &VIDIOC-S-AUDIO; using &v4l2-audio; as
 discussed in <xref linkend="audio" />.</para>
       <para>The <structfield>audio</structfield> "channel number"
 field counting audio inputs was renamed to
 <structfield>index</structfield>.</para>
       <para>On <constant>VIDIOCSAUDIO</constant> the
 <structfield>mode</structfield> field selects <emphasis>one</emphasis>
 of the <constant>VIDEO_SOUND_MONO</constant>,
 <constant>VIDEO_SOUND_STEREO</constant>,
 <constant>VIDEO_SOUND_LANG1</constant> or
 <constant>VIDEO_SOUND_LANG2</constant> audio demodulation modes. When
 the current audio standard is BTSC
 <constant>VIDEO_SOUND_LANG2</constant> refers to SAP and
 <constant>VIDEO_SOUND_LANG1</constant> is meaningless. Also
 undocumented in the V4L specification, there is no way to query the
 selected mode. On <constant>VIDIOCGAUDIO</constant> the driver returns
 the <emphasis>actually received</emphasis> audio programmes in this
 field. In the V4L2 API this information is stored in the &v4l2-tuner;
 <structfield>rxsubchans</structfield> and
 <structfield>audmode</structfield> fields, respectively. See <xref
 linkend="tuner" /> for more information on tuners. Related to audio
 modes &v4l2-audio; also reports if this is a mono or stereo
 input, regardless if the source is a tuner.</para>
       <para>The following fields where replaced by V4L2 controls
 accessible with the &VIDIOC-QUERYCTRL;, &VIDIOC-G-CTRL; and
 &VIDIOC-S-CTRL; ioctls:<informaltable>
 	  <tgroup cols="2">
 	    <thead>
 	      <row>
 		<entry>struct
 <structname>video_audio</structname></entry>
 		<entry>V4L2 Control ID</entry>
 	      </row>
 	    </thead>
 	    <tbody valign="top">
 	      <row>
 		<entry><structfield>volume</structfield></entry>
 		<entry><constant>V4L2_CID_AUDIO_VOLUME</constant></entry>
 	      </row>
 	      <row>
 		<entry><structfield>bass</structfield></entry>
 		<entry><constant>V4L2_CID_AUDIO_BASS</constant></entry>
 	      </row>
 	      <row>
 		<entry><structfield>treble</structfield></entry>
 		<entry><constant>V4L2_CID_AUDIO_TREBLE</constant></entry>
 	      </row>
 	      <row>
 		<entry><structfield>balance</structfield></entry>
 		<entry><constant>V4L2_CID_AUDIO_BALANCE</constant></entry>
 	      </row>
 	    </tbody>
 	  </tgroup>
 	</informaltable></para>
       <para>To determine which of these controls are supported by a
 driver V4L provides the <structfield>flags</structfield>
 <constant>VIDEO_AUDIO_VOLUME</constant>,
 <constant>VIDEO_AUDIO_BASS</constant>,
 <constant>VIDEO_AUDIO_TREBLE</constant> and
 <constant>VIDEO_AUDIO_BALANCE</constant>. In the V4L2 API the
 &VIDIOC-QUERYCTRL; ioctl reports if the respective control is
 supported. Accordingly the <constant>VIDEO_AUDIO_MUTABLE</constant>
 and <constant>VIDEO_AUDIO_MUTE</constant> flags where replaced by the
 boolean <constant>V4L2_CID_AUDIO_MUTE</constant> control.</para>
       <para>All V4L2 controls have a <structfield>step</structfield>
 attribute replacing the struct <structname>video_audio</structname>
 <structfield>step</structfield> 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 &VIDIOC-QUERYCTRL; ioctl. For general information about
 controls see <xref linkend="control" />.</para>
     </section>
     <section>
       <title>Frame Buffer Overlay</title>
       <para>The V4L2 ioctls equivalent to
 <constant>VIDIOCGFBUF</constant> and <constant>VIDIOCSFBUF</constant>
 are &VIDIOC-G-FBUF; and &VIDIOC-S-FBUF;. The
 <structfield>base</structfield> field of struct
 <structname>video_buffer</structname> remained unchanged, except V4L2
 defines a flag to indicate non-destructive overlays instead of a
 <constant>NULL</constant> pointer. All other fields moved into the
 &v4l2-pix-format; <structfield>fmt</structfield> substructure of
 &v4l2-framebuffer;. The <structfield>depth</structfield> field was
 replaced by <structfield>pixelformat</structfield>. See <xref
 	  linkend="pixfmt-rgb" /> for a list of RGB formats and their
 respective color depths.</para>
       <para>Instead of the special ioctls
 <constant>VIDIOCGWIN</constant> and <constant>VIDIOCSWIN</constant>
 V4L2 uses the general-purpose data format negotiation ioctls
 &VIDIOC-G-FMT; and &VIDIOC-S-FMT;. They take a pointer to a
 &v4l2-format; as argument. Here the <structfield>win</structfield>
 member of the <structfield>fmt</structfield> union is used, a
 &v4l2-window;.</para>
       <para>The <structfield>x</structfield>,
 <structfield>y</structfield>, <structfield>width</structfield> and
 <structfield>height</structfield> fields of struct
 <structname>video_window</structname> moved into &v4l2-rect;
 substructure <structfield>w</structfield> of struct
 <structname>v4l2_window</structname>. The
 <structfield>chromakey</structfield>,
 <structfield>clips</structfield>, and
 <structfield>clipcount</structfield> fields remained unchanged. Struct
 <structname>video_clip</structname> was renamed to &v4l2-clip;, also
 containing a struct <structname>v4l2_rect</structname>, but the
 semantics are still the same.</para>
       <para>The <constant>VIDEO_WINDOW_INTERLACE</constant> flag was
 dropped. Instead applications must set the
 <structfield>field</structfield> field to
 <constant>V4L2_FIELD_ANY</constant> or
 <constant>V4L2_FIELD_INTERLACED</constant>. The
 <constant>VIDEO_WINDOW_CHROMAKEY</constant> flag moved into
 &v4l2-framebuffer;, under the new name
 <constant>V4L2_FBUF_FLAG_CHROMAKEY</constant>.</para>
       <para>In V4L, storing a bitmap pointer in
 <structfield>clips</structfield> and setting
 <structfield>clipcount</structfield> to
 <constant>VIDEO_CLIP_BITMAP</constant> (-1) requests bitmap
 clipping, using a fixed size bitmap of 1024 &times; 625 bits. Struct
 <structname>v4l2_window</structname> has a separate
 <structfield>bitmap</structfield> pointer field for this purpose and
 the bitmap size is determined by <structfield>w.width</structfield> and
 <structfield>w.height</structfield>.</para>
       <para>The <constant>VIDIOCCAPTURE</constant> ioctl to enable or
 disable overlay was renamed to &VIDIOC-OVERLAY;.</para>
     </section>
     <section>
       <title>Cropping</title>
       <para>To capture only a subsection of the full picture V4L
 defines the <constant>VIDIOCGCAPTURE</constant> and
 <constant>VIDIOCSCAPTURE</constant> ioctls using struct
 <structname>video_capture</structname>. The equivalent V4L2 ioctls are
 &VIDIOC-G-CROP; and &VIDIOC-S-CROP; using &v4l2-crop;, and the related
 &VIDIOC-CROPCAP; ioctl. This is a rather complex matter, see
 <xref linkend="crop" /> for details.</para>
       <para>The <structfield>x</structfield>,
 <structfield>y</structfield>, <structfield>width</structfield> and
 <structfield>height</structfield> fields moved into &v4l2-rect;
 substructure <structfield>c</structfield> of struct
 <structname>v4l2_crop</structname>. The
 <structfield>decimation</structfield> field was dropped. In the V4L2
 API the scaling factor is implied by the size of the cropping
 rectangle and the size of the captured or overlaid image.</para>
       <para>The <constant>VIDEO_CAPTURE_ODD</constant>
 and <constant>VIDEO_CAPTURE_EVEN</constant> flags to capture only the
 odd or even field, respectively, were replaced by
 <constant>V4L2_FIELD_TOP</constant> and
 <constant>V4L2_FIELD_BOTTOM</constant> in the field named
 <structfield>field</structfield> of &v4l2-pix-format; and
 &v4l2-window;. These structures are used to select a capture or
 overlay format with the &VIDIOC-S-FMT; ioctl.</para>
     </section>
     <section>
       <title>Reading Images, Memory Mapping</title>
       <section>
 	<title>Capturing using the read method</title>
 	<para>There is no essential difference between reading images
 from a V4L or V4L2 device using the &func-read; function, however V4L2
 drivers are not required to support this I/O method. Applications can
 determine if the function is available with the &VIDIOC-QUERYCAP;
 ioctl. All V4L2 devices exchanging data with applications must support
 the &func-select; and &func-poll; functions.</para>
 	<para>To select an image format and size, V4L provides the
 <constant>VIDIOCSPICT</constant> and <constant>VIDIOCSWIN</constant>
 ioctls. V4L2 uses the general-purpose data format negotiation ioctls
 &VIDIOC-G-FMT; and &VIDIOC-S-FMT;. They take a pointer to a
 &v4l2-format; as argument, here the &v4l2-pix-format; named
 <structfield>pix</structfield> of its <structfield>fmt</structfield>
 union is used.</para>
 	<para>For more information about the V4L2 read interface see
 <xref linkend="rw" />.</para>
       </section>
       <section>
 	<title>Capturing using memory mapping</title>
 	<para>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
 copying overhead of the read method. V4L2 supports memory mapping as
 well, with a few differences.</para>
 	<informaltable>
 	  <tgroup cols="2">
 	    <thead>
 	      <row>
 		<entry>V4L</entry>
 		<entry>V4L2</entry>
 	      </row>
 	    </thead>
 	    <tbody valign="top">
 	      <row>
 		<entry></entry>
 		<entry>The image format must be selected before
 buffers are allocated, with the &VIDIOC-S-FMT; ioctl. When no format
 is selected the driver may use the last, possibly by another
 application requested format.</entry>
 	      </row>
 	      <row>
 		<entry><para>Applications cannot change the number of
 buffers. The it is built into the driver, unless it has a module
 option to change the number when the driver module is
 loaded.</para></entry>
 		<entry><para>The &VIDIOC-REQBUFS; ioctl allocates the
 desired number of buffers, this is a required step in the initialization
 sequence.</para></entry>
 	      </row>
 	      <row>
 		<entry><para>Drivers map all buffers as one contiguous
 range of memory. The <constant>VIDIOCGMBUF</constant> 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 for the &func-mmap;
 function.</para></entry>
 		<entry><para>Buffers are individually mapped. The
 offset and size of each buffer can be determined with the
 &VIDIOC-QUERYBUF; ioctl.</para></entry>
 	      </row>
 	      <row>
 		<entry><para>The <constant>VIDIOCMCAPTURE</constant>
 ioctl prepares a buffer for capturing. It also determines the image
 format for this buffer. The ioctl returns immediately, eventually with
 an &EAGAIN; 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.</para><para>The <constant>VIDIOCSYNC</constant> ioctl
 suspends execution until a particular buffer has been
 filled.</para></entry>
 		<entry><para>Drivers maintain an incoming and outgoing
 queue. &VIDIOC-QBUF; enqueues any empty buffer into the incoming
 queue. Filled buffers are dequeued from the outgoing queue with the
 &VIDIOC-DQBUF; ioctl. To wait until filled buffers become available this
 function, &func-select; or &func-poll; can be used. The
 &VIDIOC-STREAMON; ioctl must be called once after enqueuing one or
 more buffers to start capturing. Its counterpart
 &VIDIOC-STREAMOFF; stops capturing and dequeues all buffers from both
 queues. Applications can query the signal status, if known, with the
 &VIDIOC-ENUMINPUT; ioctl.</para></entry>
 	      </row>
 	    </tbody>
 	  </tgroup>
 	</informaltable>
 	<para>For a more in-depth discussion of memory mapping and
 examples, see <xref linkend="mmap" />.</para>
       </section>
     </section>
     <section>
       <title>Reading Raw VBI Data</title>
       <para>Originally the V4L API did not specify a raw VBI capture
 interface, only the device file <filename>/dev/vbi</filename> 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:<informaltable>
 	    <tgroup cols="2">
 	      <thead>
 		<row>
 		  <entry>&v4l2-vbi-format;</entry>
 		  <entry>V4L, BTTV driver</entry>
 		</row>
 	      </thead>
 	      <tbody valign="top">
 		<row>
 		  <entry>sampling_rate</entry>
 		  <entry>28636363&nbsp;Hz NTSC (or any other 525-line
 standard); 35468950&nbsp;Hz PAL and SECAM (625-line standards)</entry>
 		</row>
 		<row>
 		  <entry>offset</entry>
 		  <entry>?</entry>
 		</row>
 		<row>
 		  <entry>samples_per_line</entry>
 		  <entry>2048</entry>
 		</row>
 		<row>
 		  <entry>sample_format</entry>
 		  <entry>V4L2_PIX_FMT_GREY. The last four bytes (a
 machine endianess integer) contain a frame counter.</entry>
 		</row>
 		<row>
 		  <entry>start[]</entry>
 		  <entry>10, 273 NTSC; 22, 335 PAL and SECAM</entry>
 		</row>
 		<row>
 		  <entry>count[]</entry>
 		  <entry><para>16, 16<footnote><para>Old driver
 versions used different values, eventually the custom
 <constant>BTTV_VBISIZE</constant> ioctl was added to query the
 correct values.</para></footnote></para></entry>
 		</row>
 		<row>
 		  <entry>flags</entry>
 		  <entry>0</entry>
 		</row>
 	      </tbody>
 	    </tgroup>
 	</informaltable></para>
       <para>Undocumented in the V4L specification, in Linux 2.3 the
 <constant>VIDIOCGVBIFMT</constant> and
 <constant>VIDIOCSVBIFMT</constant> ioctls using struct
 <structname>vbi_format</structname> were added to determine the VBI
 image parameters. These ioctls are only partially compatible with the
 V4L2 VBI interface specified in <xref linkend="raw-vbi" />.</para>
       <para>An <structfield>offset</structfield> field does not
 exist, <structfield>sample_format</structfield> is supposed to be
 <constant>VIDEO_PALETTE_RAW</constant>, equivalent to
 <constant>V4L2_PIX_FMT_GREY</constant>. The remaining fields are
 probably equivalent to &v4l2-vbi-format;.</para>
       <para>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 &func-open; and
 <constant>VIDIOCSVBIFMT</constant> always returns an &EINVAL; if the
 parameters are invalid.</para>
     </section>
     <section>
       <title>Miscellaneous</title>
       <para>V4L2 has no equivalent of the
 <constant>VIDIOCGUNIT</constant> 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
 <xref linkend="open" />.</para>
       <para>No replacement exists for <constant>VIDIOCKEY</constant>,
 and the V4L functions for microcode programming. A new interface for
 MPEG compression and playback devices is documented in <xref
 	  linkend="extended-controls" />.</para>
     </section>
   </section>
   <section id="hist-v4l2">
     <title>Changes of the V4L2 API</title>
     <para>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 to 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.</para>
     <section>
       <title>Early Versions</title>
       <para>1998-08-20: First version.</para>
       <para>1998-08-27: The &func-select; function was introduced.</para>
       <para>1998-09-10: New video standard interface.</para>
       <para>1998-09-18: The <constant>VIDIOC_NONCAP</constant> ioctl
 was replaced by the otherwise meaningless <constant>O_TRUNC</constant>
 &func-open; flag, and the aliases <constant>O_NONCAP</constant> and
 <constant>O_NOIO</constant> were defined. Applications can set this
 flag if they intend to access controls only, as opposed to capture
 applications which need exclusive access. The
 <constant>VIDEO_STD_XXX</constant> identifiers are now ordinals
 instead of flags, and the <function>video_std_construct()</function>
 helper function takes id and transmission arguments.</para>
       <para>1998-09-28: Revamped video standard. Made video controls
 individually enumerable.</para>
       <para>1998-10-02: The <structfield>id</structfield> field was
 removed from struct <structname>video_standard</structname> and the
 color subcarrier fields were renamed. The &VIDIOC-QUERYSTD; ioctl was
 renamed to &VIDIOC-ENUMSTD;, &VIDIOC-G-INPUT; to &VIDIOC-ENUMINPUT;. A
 first draft of the Codec API was released.</para>
       <para>1998-11-08: Many minor changes. Most symbols have been
 renamed. Some material changes to &v4l2-capability;.</para>
       <para>1998-11-12: The read/write directon of some ioctls was misdefined.</para>
       <para>1998-11-14: <constant>V4L2_PIX_FMT_RGB24</constant>
 changed to <constant>V4L2_PIX_FMT_BGR24</constant>, and
 <constant>V4L2_PIX_FMT_RGB32</constant> changed to
 <constant>V4L2_PIX_FMT_BGR32</constant>. Audio controls are now
 accessible with the &VIDIOC-G-CTRL; and &VIDIOC-S-CTRL; ioctls under
 names starting with <constant>V4L2_CID_AUDIO</constant>. The
 <constant>V4L2_MAJOR</constant> define was removed from
 <filename>videodev.h</filename> since it was only used once in the
 <filename>videodev</filename> kernel module. The
 <constant>YUV422</constant> and <constant>YUV411</constant> planar
 image formats were added.</para>
       <para>1998-11-28: A few ioctl symbols changed. Interfaces for codecs and
 video output devices were added.</para>
       <para>1999-01-14: A raw VBI capture interface was added.</para>
       <para>1999-01-19: The <constant>VIDIOC_NEXTBUF</constant> ioctl
       was removed.</para>
     </section>
     <section>
       <title>V4L2 Version 0.16 1999-01-31</title>
       <para>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.</para>
     </section>
     <!-- Where's 0.17? mhs couldn't find that videodev.h, perhaps Bill
 	 forgot to bump the version number or never released it. -->
     <section>
       <title>V4L2 Version 0.18 1999-03-16</title>
       <para>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.</para>
     </section>
     <section>
       <title>V4L2 Version 0.19 1999-06-05</title>
       <para>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.</para>
       <para>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.</para>
       <para>1999-04-04: Added a few more control IDs.</para>
       <para>1999-04-07: Added the button control type.</para>
       <para>1999-05-02: Fixed a typo in videodev.h, and added the
 V4L2_CTRL_FLAG_GRAYED (later V4L2_CTRL_FLAG_GRABBED) flag.</para>
       <para>1999-05-20: Definition of VIDIOC_G_CTRL was wrong causing
 a malfunction of this ioctl.</para>
       <para>1999-06-05: Changed the value of
 V4L2_CID_WHITENESS.</para>
     </section>
     <section>
       <title>V4L2 Version 0.20 (1999-09-10)</title>
       <para>Version 0.20 introduced a number of changes which were
 <emphasis>not backward compatible</emphasis> with 0.19 and earlier
 versions. Purpose of these changes was to simplify the API, while
 making it more extensible and following common Linux driver API
 conventions.</para>
       <orderedlist>
 	<listitem>
 	  <para>Some typos in <constant>V4L2_FMT_FLAG</constant>
 symbols were fixed. &v4l2-clip; was changed for compatibility with
 v4l. (1999-08-30)</para>
 	</listitem>
 	<listitem>
 	  <para><constant>V4L2_TUNER_SUB_LANG1</constant> was added.
 (1999-09-05)</para>
 	</listitem>
 	<listitem>
 	  <para>All ioctl() commands that used an integer argument now
 take a pointer to an integer. Where it makes sense, ioctls will return
 the actual new value in the integer pointed to by the argument, a
 common convention in the V4L2 API. The affected ioctls are:
 VIDIOC_PREVIEW, VIDIOC_STREAMON, VIDIOC_STREAMOFF, VIDIOC_S_FREQ,
 VIDIOC_S_INPUT, VIDIOC_S_OUTPUT, VIDIOC_S_EFFECT. For example
 <programlisting>
 err = ioctl (fd, VIDIOC_XXX, V4L2_XXX);
 </programlisting> becomes <programlisting>
 int a = V4L2_XXX; err = ioctl(fd, VIDIOC_XXX, &amp;a);
 </programlisting>
 	  </para>
 	</listitem>
 	<listitem>
 	  <para>All the different get- and set-format commands were
 swept into one &VIDIOC-G-FMT; and &VIDIOC-S-FMT; ioctl taking a union
 and a type field selecting the union member as parameter. Purpose is to
 simplify the API by eliminating several ioctls and to allow new and
 driver private data streams without adding new ioctls.</para>
 	  <para>This change obsoletes the following ioctls:
 <constant>VIDIOC_S_INFMT</constant>,
 <constant>VIDIOC_G_INFMT</constant>,
 <constant>VIDIOC_S_OUTFMT</constant>,
 <constant>VIDIOC_G_OUTFMT</constant>,
 <constant>VIDIOC_S_VBIFMT</constant> and
 <constant>VIDIOC_G_VBIFMT</constant>. The image format structure
 <structname>v4l2_format</structname> was renamed to &v4l2-pix-format;,
 while &v4l2-format; is now the envelopping structure for all format
 negotiations.</para>
 	</listitem>
 	<listitem>
 	  <para>Similar to the changes above, the
 <constant>VIDIOC_G_PARM</constant> and
 <constant>VIDIOC_S_PARM</constant> ioctls were merged with
 <constant>VIDIOC_G_OUTPARM</constant> and
 <constant>VIDIOC_S_OUTPARM</constant>. A
 <structfield>type</structfield> field in the new &v4l2-streamparm;
 selects the respective union member.</para>
 	  <para>This change obsoletes the
 <constant>VIDIOC_G_OUTPARM</constant> and
 <constant>VIDIOC_S_OUTPARM</constant> ioctls.</para>
 	</listitem>
 	<listitem>
 	  <para>Control enumeration was simplified, and two new
 control flags were introduced and one dropped. The
 <structfield>catname</structfield> field was replaced by a
 <structfield>group</structfield> field.</para>
 	  <para>Drivers can now flag unsupported and temporarily
 unavailable controls with <constant>V4L2_CTRL_FLAG_DISABLED</constant>
 and <constant>V4L2_CTRL_FLAG_GRABBED</constant> respectively. The
 <structfield>group</structfield> name indicates a possibly narrower
 classification than the <structfield>category</structfield>. 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 may even
 appear in separate windows.</para>
 	</listitem>
 	<listitem>
 	  <para>The &v4l2-buffer; <structfield>timestamp</structfield>
 was changed to a 64 bit integer, containing the sampling or output
 time of the frame in nanoseconds. Additionally timestamps will be in
 absolute system time, not starting from zero at the beginning of a
 stream. 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://web.archive.org/web/*/http://reality.sgi.com
 /cpirazzi_engr/lg/time/intro.html.
 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.</para>
 	</listitem>
 	<listitem>
 	  <para>A <structfield>sequence</structfield> field was added
 to &v4l2-buffer;. The <structfield>sequence</structfield> field counts
 captured frames, it is ignored by output devices. When a capture
 driver drops a frame, the sequence number of that frame is
 skipped.</para>
 	</listitem>
       </orderedlist>
     </section>
     <section>
       <title>V4L2 Version 0.20 incremental changes</title>
       <!-- Version number didn't change anymore, reason unknown. -->
       <para>1999-12-23: In &v4l2-vbi-format; the
 <structfield>reserved1</structfield> field became
 <structfield>offset</structfield>. Previously drivers were required to
 clear the <structfield>reserved1</structfield> field.</para>
       <para>2000-01-13: The
       <constant>V4L2_FMT_FLAG_NOT_INTERLACED</constant> flag was added.</para>
       <para>2000-07-31: The <filename>linux/poll.h</filename> header
 is now included by <filename>videodev.h</filename> for compatibility
 with the original <filename>videodev.h</filename> file.</para>
       <para>2000-11-20: <constant>V4L2_TYPE_VBI_OUTPUT</constant> and
 <constant>V4L2_PIX_FMT_Y41P</constant> were added.</para>
       <para>2000-11-25: <constant>V4L2_TYPE_VBI_INPUT</constant> was
 added.</para>
       <para>2000-12-04: A couple typos in symbol names were fixed.</para>
       <para>2001-01-18: To avoid namespace conflicts the
 <constant>fourcc</constant> macro defined in the
 <filename>videodev.h</filename> header file was renamed to
 <constant>v4l2_fourcc</constant>.</para>
       <para>2001-01-25: A possible driver-level compatibility problem
 between the <filename>videodev.h</filename> file in Linux 2.4.0 and
 the <filename>videodev.h</filename> file included in the
 <filename>videodevX</filename> patch was fixed. Users of an earlier
 version of <filename>videodevX</filename> on Linux 2.4.0 should
 recompile their V4L and V4L2 drivers.</para>
       <para>2001-01-26: A possible kernel-level incompatibility
 between the <filename>videodev.h</filename> file in the
 <filename>videodevX</filename> patch and the
 <filename>videodev.h</filename> file in Linux 2.2.x with devfs patches
 applied was fixed.</para>
       <para>2001-03-02: Certain V4L ioctls which pass data in both
 direction although they are defined with read-only parameter, did not
 work correctly through the backward compatibility layer.
 [Solution?]</para>
       <para>2001-04-13: Big endian 16-bit RGB formats were added.</para>
       <para>2001-09-17: New YUV formats and the &VIDIOC-G-FREQUENCY; and
 &VIDIOC-S-FREQUENCY; ioctls were added. (The old
 <constant>VIDIOC_G_FREQ</constant> and
 <constant>VIDIOC_S_FREQ</constant> ioctls did not take multiple tuners
 into account.)</para>
       <para>2000-09-18: <constant>V4L2_BUF_TYPE_VBI</constant> was
 added. This may <emphasis>break compatibility</emphasis> as the
 &VIDIOC-G-FMT; and &VIDIOC-S-FMT; ioctls may fail now if the struct
 <structname>v4l2_fmt</structname> <structfield>type</structfield>
 field does not contain <constant>V4L2_BUF_TYPE_VBI</constant>. In the
 documentation of the &v4l2-vbi-format;
 <structfield>offset</structfield> field the ambiguous phrase "rising
 edge" was changed to "leading edge".</para>
     </section>
     <section>
       <title>V4L2 Version 0.20 2000-11-23</title>
       <para>A number of changes were made to the raw VBI
 interface.</para>
       <orderedlist>
 	<listitem>
 	  <para>Figures clarifying the line numbering scheme were
 added to the V4L2 API specification. The
 <structfield>start</structfield>[0] and
 <structfield>start</structfield>[1] fields no longer count line
 numbers beginning at zero. Rationale: a) The previous definition was
 unclear. b) The <structfield>start</structfield>[] values are ordinal
 numbers. c) There is no point in inventing a new line numbering
 scheme. We now use line number as defined by ITU-R, period.
 Compatibility: Add one to the start values. Applications depending on
 the previous semantics may not function correctly.</para>
 	</listitem>
 	<listitem>
 	  <para>The restriction "count[0] &gt; 0 and count[1] &gt; 0"
 has been relaxed  to "(count[0] + count[1]) &gt; 0". Rationale:
 Drivers may allocate resources at scan line granularity and some data
 services are transmitted only on the first field. The comment that
 both <structfield>count</structfield> values will usually be equal is
 misleading and pointless and has been removed. This change
 <emphasis>breaks compatibility</emphasis> with earlier versions:
 Drivers may return EINVAL, applications may not function
 correctly.</para>
 	</listitem>
 	<listitem>
 	  <para>Drivers are again permitted to return negative
 (unknown) start values as proposed earlier. Why this feature was
 dropped is unclear. This change may <emphasis>break
 compatibility</emphasis> with applications depending on the start
 values being positive. The use of <constant>EBUSY</constant> and
 <constant>EINVAL</constant> error codes with the &VIDIOC-S-FMT; ioctl
 was clarified. The &EBUSY; was finally documented, and the
 <structfield>reserved2</structfield> field which was previously
 mentioned only in the <filename>videodev.h</filename> header
 file.</para>
 	</listitem>
 	<listitem>
 	  <para>New buffer types
 <constant>V4L2_TYPE_VBI_INPUT</constant> and
 <constant>V4L2_TYPE_VBI_OUTPUT</constant> were added. The former is an
 alias for the old <constant>V4L2_TYPE_VBI</constant>, the latter was
 missing in the <filename>videodev.h</filename> file.</para>
 	</listitem>
       </orderedlist>
     </section>
     <section>
       <title>V4L2 Version 0.20 2002-07-25</title>
       <para>Added sliced VBI interface proposal.</para>
     </section>
     <section>
       <title>V4L2 in Linux 2.5.46, 2002-10</title>
       <para>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.</para>
       <orderedlist>
 	<listitem>
 	  <para>As specified in <xref linkend="related" />, drivers
 must make related device functions available under all minor device
 numbers.</para>
 	</listitem>
 	<listitem>
 	  <para>The &func-open; function requires access mode
 <constant>O_RDWR</constant> regardless of the device type. All V4L2
 drivers exchanging data with applications must support the
 <constant>O_NONBLOCK</constant> flag. The <constant>O_NOIO</constant>
 flag, a V4L2 symbol which aliased the meaningless
 <constant>O_TRUNC</constant> to indicate accesses without data
 exchange (panel applications) was dropped. Drivers must stay in "panel
 mode" until the application attempts to initiate a data exchange, see
 <xref linkend="open" />.</para>
 	</listitem>
 	<listitem>
 	  <para>The &v4l2-capability; 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 &EINVAL; to
 the new &VIDIOC-QUERYCAP; ioctl.</para>
 	  <para>There are new fields to identify the driver, a new RDS
 device function <constant>V4L2_CAP_RDS_CAPTURE</constant>, the
 <constant>V4L2_CAP_AUDIO</constant> flag indicates if the device has
 any audio connectors, another I/O capability
 <constant>V4L2_CAP_ASYNCIO</constant> can be flagged. In response to
 these changes the <structfield>type</structfield> field became a bit
 set and was merged into the <structfield>flags</structfield> field.
 <constant>V4L2_FLAG_TUNER</constant> was renamed to
 <constant>V4L2_CAP_TUNER</constant>,
 <constant>V4L2_CAP_VIDEO_OVERLAY</constant> replaced
 <constant>V4L2_FLAG_PREVIEW</constant> and
 <constant>V4L2_CAP_VBI_CAPTURE</constant> and
 <constant>V4L2_CAP_VBI_OUTPUT</constant> replaced
 <constant>V4L2_FLAG_DATA_SERVICE</constant>.
 <constant>V4L2_FLAG_READ</constant> and
 <constant>V4L2_FLAG_WRITE</constant> were merged into
 <constant>V4L2_CAP_READWRITE</constant>.</para>
 	  <para>The redundant fields
 <structfield>inputs</structfield>, <structfield>outputs</structfield>
 and <structfield>audios</structfield> were removed. These properties
 can be determined as described in <xref linkend="video" /> and <xref
 linkend="audio" />.</para>
 	  <para>The somewhat volatile and therefore barely useful
 fields <structfield>maxwidth</structfield>,
 <structfield>maxheight</structfield>,
 <structfield>minwidth</structfield>,
 <structfield>minheight</structfield>,
 <structfield>maxframerate</structfield> were removed. This information
 is available as described in <xref linkend="format" /> and
 <xref linkend="standard" />.</para>
 	  <para><constant>V4L2_FLAG_SELECT</constant> was removed. We
 believe the select() function is important enough to require support
 of it in all V4L2 drivers exchanging data with applications. The
 redundant <constant>V4L2_FLAG_MONOCHROME</constant> flag was removed,
 this information is available as described in <xref
 	      linkend="format" />.</para>
 	</listitem>
 	<listitem>
 	  <para>In &v4l2-input; the
 <structfield>assoc_audio</structfield> field and the
 <structfield>capability</structfield> field and its only flag
 <constant>V4L2_INPUT_CAP_AUDIO</constant> was replaced by the new
 <structfield>audioset</structfield> field. Instead of linking one
 video input to one audio input this field reports all audio inputs
 this video input combines with.</para>
 	  <para>New fields are <structfield>tuner</structfield>
 (reversing the former link from tuners to video inputs),
 <structfield>std</structfield> and
 <structfield>status</structfield>.</para>
 	  <para>Accordingly &v4l2-output; lost its
 <structfield>capability</structfield> and
 <structfield>assoc_audio</structfield> fields.
 <structfield>audioset</structfield>,
 <structfield>modulator</structfield> and
 <structfield>std</structfield> where added instead.</para>
 	</listitem>
 	<listitem>
 	  <para>The &v4l2-audio; field
 <structfield>audio</structfield> was renamed to
 <structfield>index</structfield>, for consistency with other
 structures. A new capability flag
 <constant>V4L2_AUDCAP_STEREO</constant> was added to indicated if the
 audio input in question supports stereo sound.
 <constant>V4L2_AUDCAP_EFFECTS</constant> and the corresponding
 <constant>V4L2_AUDMODE</constant> flags where removed. This can be
 easily implemented using controls. (However the same applies to AVL
 which is still there.)</para>
 	  <para>Again for consistency the &v4l2-audioout; field
 <structfield>audio</structfield> was renamed to
 <structfield>index</structfield>.</para>
 	</listitem>
 	<listitem>
 	  <para>The &v4l2-tuner;
 <structfield>input</structfield> field was replaced by an
 <structfield>index</structfield> field, permitting devices with
 multiple tuners. The link between video inputs and tuners is now
 reversed, inputs point to their tuner. The
 <structfield>std</structfield> substructure became a
 simple set (more about this below) and moved into &v4l2-input;. A
 <structfield>type</structfield> field was added.</para>
 	  <para>Accordingly in &v4l2-modulator; the
 <structfield>output</structfield> was replaced by an
 <structfield>index</structfield> field.</para>
 	  <para>In &v4l2-frequency; the
 <structfield>port</structfield> field was replaced by a
 <structfield>tuner</structfield> field containing the respective tuner
 or modulator index number. A tuner <structfield>type</structfield>
 field was added and the <structfield>reserved</structfield> field
 became larger for future extensions (satellite tuners in
 particular).</para>
 	</listitem>
 	<listitem>
 	  <para>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. Instead of
 enumerating supported standards with an ioctl applications can now
 refer to standards by &v4l2-std-id; and symbols defined in the
 <filename>videodev2.h</filename> header file. For details see <xref
 	      linkend="standard" />. The &VIDIOC-G-STD; and
 &VIDIOC-S-STD; now take a pointer to this type as argument.
 &VIDIOC-QUERYSTD; was added to autodetect the received standard, if
 the hardware has this capability. In &v4l2-standard; an
 <structfield>index</structfield> field was added for &VIDIOC-ENUMSTD;.
 A &v4l2-std-id; field named <structfield>id</structfield> was added as
 machine readable identifier, also replacing the
 <structfield>transmission</structfield> field. The misleading
 <structfield>framerate</structfield> field was renamed
 to <structfield>frameperiod</structfield>. The now obsolete
 <structfield>colorstandard</structfield> information, originally
 needed to distguish between variations of standards, were
 removed.</para>
 	  <para>Struct <structname>v4l2_enumstd</structname> ceased to
 be. &VIDIOC-ENUMSTD; now takes a pointer to a &v4l2-standard;
 directly. The information which standards are supported by a
 particular video input or output moved into &v4l2-input; and
 &v4l2-output; fields named <structfield>std</structfield>,
 respectively.</para>
 	</listitem>
 	<listitem>
 	  <para>The &v4l2-queryctrl; fields
 <structfield>category</structfield> and
 <structfield>group</structfield> did not catch on and/or were not
 implemented as expected and therefore removed.</para>
 	</listitem>
 	<listitem>
 	  <para>The &VIDIOC-TRY-FMT; ioctl was added to negotiate data
 formats as with &VIDIOC-S-FMT;, but without the overhead of
 programming the hardware and regardless of I/O in progress.</para>
 	  <para>In &v4l2-format; the <structfield>fmt</structfield>
 union was extended to contain &v4l2-window;. All image format
 negotiations are now possible with <constant>VIDIOC_G_FMT</constant>,
 <constant>VIDIOC_S_FMT</constant> and
 <constant>VIDIOC_TRY_FMT</constant>; ioctl. The
 <constant>VIDIOC_G_WIN</constant> and
 <constant>VIDIOC_S_WIN</constant> ioctls to prepare for a video
 overlay were removed. The <structfield>type</structfield> field
 changed to type &v4l2-buf-type; and the buffer type names changed as
 follows.<informaltable>
 	      <tgroup cols="2">
 		<thead>
 		  <row>
 		    <entry>Old defines</entry>
 		    <entry>&v4l2-buf-type;</entry>
 		  </row>
 		</thead>
 		<tbody valign="top">
 		  <row>
 		    <entry><constant>V4L2_BUF_TYPE_CAPTURE</constant></entry>
 		    <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant></entry>
 		  </row>
 		  <row>
 		    <entry><constant>V4L2_BUF_TYPE_CODECIN</constant></entry>
 		    <entry>Omitted for now</entry>
 		  </row>
 		  <row>
 		    <entry><constant>V4L2_BUF_TYPE_CODECOUT</constant></entry>
 		    <entry>Omitted for now</entry>
 		  </row>
 		  <row>
 		    <entry><constant>V4L2_BUF_TYPE_EFFECTSIN</constant></entry>
 		    <entry>Omitted for now</entry>
 		  </row>
 		  <row>
 		    <entry><constant>V4L2_BUF_TYPE_EFFECTSIN2</constant></entry>
 		    <entry>Omitted for now</entry>
 		  </row>
 		  <row>
 		    <entry><constant>V4L2_BUF_TYPE_EFFECTSOUT</constant></entry>
 		    <entry>Omitted for now</entry>
 		  </row>
 		  <row>
 		    <entry><constant>V4L2_BUF_TYPE_VIDEOOUT</constant></entry>
 		    <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant></entry>
 		  </row>
 		  <row>
 		    <entry><constant>-</constant></entry>
 		    <entry><constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant></entry>
 		  </row>
 		  <row>
 		    <entry><constant>-</constant></entry>
 		    <entry><constant>V4L2_BUF_TYPE_VBI_CAPTURE</constant></entry>
 		  </row>
 		  <row>
 		    <entry><constant>-</constant></entry>
 		    <entry><constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant></entry>
 		  </row>
 		  <row>
 		    <entry><constant>-</constant></entry>
 		    <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant></entry>
 		  </row>
 		  <row>
 		    <entry><constant>-</constant></entry>
 		    <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant></entry>
 		  </row>
 		  <row>
 		    <entry><constant>V4L2_BUF_TYPE_PRIVATE_BASE</constant></entry>
 		    <entry><constant>V4L2_BUF_TYPE_PRIVATE</constant></entry>
 		  </row>
 		</tbody>
 	      </tgroup>
 	    </informaltable></para>
 	</listitem>
 	<listitem>
 	  <para>In &v4l2-fmtdesc; a &v4l2-buf-type; field named
 <structfield>type</structfield> was added as in &v4l2-format;. The
 <constant>VIDIOC_ENUM_FBUFFMT</constant> ioctl is no longer needed and
 was removed. These calls can be replaced by &VIDIOC-ENUM-FMT; with
 type <constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>.</para>
 	</listitem>
 	<listitem>
 	  <para>In &v4l2-pix-format; the
 <structfield>depth</structfield> field was removed, assuming
 applications which recognize the format by its four-character-code
 already know the color depth, and others do not care about it. The
 same rationale lead to the removal of the
 <constant>V4L2_FMT_FLAG_COMPRESSED</constant> flag. The
 <constant>V4L2_FMT_FLAG_SWCONVECOMPRESSED</constant> flag was removed
 because drivers are not supposed to convert images in kernel space. A
 user library of conversion functions should be provided instead. The
 <constant>V4L2_FMT_FLAG_BYTESPERLINE</constant> flag was redundant.
 Applications can set the <structfield>bytesperline</structfield> field
 to zero to get a reasonable default. Since the remaining flags were
 replaced as well, the <structfield>flags</structfield> field itself
 was removed.</para>
 	  <para>The interlace flags were replaced by a &v4l2-field;
 value in a newly added <structfield>field</structfield>
 field.<informaltable>
 	      <tgroup cols="2">
 		<thead>
 		  <row>
 		    <entry>Old flag</entry>
 		    <entry>&v4l2-field;</entry>
 		  </row>
 		</thead>
 		<tbody valign="top">
 		  <row>
 		    <entry><constant>V4L2_FMT_FLAG_NOT_INTERLACED</constant></entry>
 		    <entry>?</entry>
 		  </row>
 		  <row>
 		    <entry><constant>V4L2_FMT_FLAG_INTERLACED</constant>
 = <constant>V4L2_FMT_FLAG_COMBINED</constant></entry>
 		    <entry><constant>V4L2_FIELD_INTERLACED</constant></entry>
 		  </row>
 		  <row>
 		    <entry><constant>V4L2_FMT_FLAG_TOPFIELD</constant>
 = <constant>V4L2_FMT_FLAG_ODDFIELD</constant></entry>
 		    <entry><constant>V4L2_FIELD_TOP</constant></entry>
 		  </row>
 		  <row>
 		    <entry><constant>V4L2_FMT_FLAG_BOTFIELD</constant>
 = <constant>V4L2_FMT_FLAG_EVENFIELD</constant></entry>
 		    <entry><constant>V4L2_FIELD_BOTTOM</constant></entry>
 		  </row>
 		  <row>
 		    <entry><constant>-</constant></entry>
 		    <entry><constant>V4L2_FIELD_SEQ_TB</constant></entry>
 		  </row>
 		  <row>
 		    <entry><constant>-</constant></entry>
 		    <entry><constant>V4L2_FIELD_SEQ_BT</constant></entry>
 		  </row>
 		  <row>
 		    <entry><constant>-</constant></entry>
 		    <entry><constant>V4L2_FIELD_ALTERNATE</constant></entry>
 		  </row>
 		</tbody>
 	      </tgroup>
 	    </informaltable></para>
 	  <para>The color space flags were replaced by a
 &v4l2-colorspace; value in a newly added
 <structfield>colorspace</structfield> field, where one of
 <constant>V4L2_COLORSPACE_SMPTE170M</constant>,
 <constant>V4L2_COLORSPACE_BT878</constant>,
 <constant>V4L2_COLORSPACE_470_SYSTEM_M</constant> or
 <constant>V4L2_COLORSPACE_470_SYSTEM_BG</constant> replaces
 <constant>V4L2_FMT_CS_601YUV</constant>.</para>
 	</listitem>
 	<listitem>
 	  <para>In &v4l2-requestbuffers; the
 <structfield>type</structfield> field was properly defined as
 &v4l2-buf-type;. Buffer types changed as mentioned above. A new
 <structfield>memory</structfield> field of type &v4l2-memory; was
 added to distinguish between I/O methods using buffers allocated
 by the driver or the application. See <xref linkend="io" /> for
 details.</para>
 	</listitem>
 	<listitem>
 	  <para>In &v4l2-buffer; the <structfield>type</structfield>
 field was properly defined as &v4l2-buf-type;. Buffer types changed as
 mentioned above. A <structfield>field</structfield> field of type
 &v4l2-field; was added to indicate if a buffer contains a top or
 bottom field. The old field flags were removed. Since no unadjusted
 system time clock was added to the kernel as planned, the
 <structfield>timestamp</structfield> field changed back from type
 stamp_t, an unsigned 64 bit integer expressing the sample time in
 nanoseconds, to struct <structname>timeval</structname>. With the
 addition of a second memory mapping method the
 <structfield>offset</structfield> field moved into union
 <structfield>m</structfield>, and a new
 <structfield>memory</structfield> field of type &v4l2-memory; was
 added to distinguish between I/O methods. See <xref linkend="io" />
 for details.</para>
 	  <para>The <constant>V4L2_BUF_REQ_CONTIG</constant>
 flag was used by the V4L compatibility layer, after changes to this
 code it was no longer needed. The
 <constant>V4L2_BUF_ATTR_DEVICEMEM</constant> flag would indicate if
 the buffer was indeed allocated in device memory rather than DMA-able
 system memory. It was barely useful and so was removed.</para>
 	</listitem>
 	<listitem>
 	  <para>In &v4l2-framebuffer; the
 <structfield>base[3]</structfield> array anticipating double- and
 triple-buffering in off-screen video memory, however without defining
 a synchronization mechanism, was replaced by a single pointer. The
 <constant>V4L2_FBUF_CAP_SCALEUP</constant> and
 <constant>V4L2_FBUF_CAP_SCALEDOWN</constant> flags were removed.
 Applications can determine this capability more accurately using the
 new cropping and scaling interface. The
 <constant>V4L2_FBUF_CAP_CLIPPING</constant> flag was replaced by
 <constant>V4L2_FBUF_CAP_LIST_CLIPPING</constant> and
 <constant>V4L2_FBUF_CAP_BITMAP_CLIPPING</constant>.</para>
 	</listitem>
 	<listitem>
 	  <para>In &v4l2-clip; the <structfield>x</structfield>,
 <structfield>y</structfield>, <structfield>width</structfield> and
 <structfield>height</structfield> field moved into a
 <structfield>c</structfield> substructure of type &v4l2-rect;. The
 <structfield>x</structfield> and <structfield>y</structfield> fields
 were renamed to <structfield>left</structfield> and
 <structfield>top</structfield>, &ie; offsets to a context dependent
 origin.</para>
 	</listitem>
 	<listitem>
 	  <para>In &v4l2-window; the <structfield>x</structfield>,
 <structfield>y</structfield>, <structfield>width</structfield> and
 <structfield>height</structfield> field moved into a
 <structfield>w</structfield> substructure as above. A
 <structfield>field</structfield> field of type %v4l2-field; was added
 to distinguish between field and frame (interlaced) overlay.</para>
 	</listitem>
 	<listitem>
 	  <para>The digital zoom interface, including struct
 <structname>v4l2_zoomcap</structname>, struct
 <structname>v4l2_zoom</structname>,
 <constant>V4L2_ZOOM_NONCAP</constant> and
 <constant>V4L2_ZOOM_WHILESTREAMING</constant> was replaced by a new
 cropping and scaling interface. The previously unused struct
 <structname>v4l2_cropcap</structname> and
 <structname>v4l2_crop</structname> where redefined for this purpose.
 See <xref linkend="crop" /> for details.</para>
 	</listitem>
 	<listitem>
 	  <para>In &v4l2-vbi-format; the
 <structfield>SAMPLE_FORMAT</structfield> field now contains a
 four-character-code as used to identify video image formats and
 <constant>V4L2_PIX_FMT_GREY</constant> replaces the
 <constant>V4L2_VBI_SF_UBYTE</constant> define. The
 <structfield>reserved</structfield> field was extended.</para>
 	</listitem>
 	<listitem>
 	  <para>In &v4l2-captureparm; the type of the
 <structfield>timeperframe</structfield> field changed from unsigned
 long to &v4l2-fract;. This allows the accurate expression of multiples
 of the NTSC-M frame rate 30000 / 1001. A new field
 <structfield>readbuffers</structfield> was added to control the driver
 behaviour in read I/O mode.</para>
 	  <para>Similar changes were made to &v4l2-outputparm;.</para>
 	</listitem>
 	<listitem>
 	  <para>The struct <structname>v4l2_performance</structname>
 and <constant>VIDIOC_G_PERF</constant> ioctl were dropped. Except when
 using the <link linkend="rw">read/write I/O method</link>, which is
 limited anyway, this information is already available to
 applications.</para>
 	</listitem>
 	<listitem>
 	  <para>The example transformation from RGB to YCbCr color
 space in the old V4L2 documentation was inaccurate, this has been
 corrected in <xref linkend="pixfmt" />.<!-- 0.5670G should be
 0.587, and 127/112 != 255/224 --></para>
 	</listitem>
       </orderedlist>
     </section>
     <section>
       <title>V4L2 2003-06-19</title>
       <orderedlist>
 	<listitem>
 	  <para>A new capability flag
 <constant>V4L2_CAP_RADIO</constant> was added for radio devices. Prior
 to this change radio devices would identify solely by having exactly one
 tuner whose type field reads <constant>V4L2_TUNER_RADIO</constant>.</para>
 	</listitem>
 	<listitem>
 	  <para>An optional driver access priority mechanism was
 added, see <xref linkend="app-pri" /> for details.</para>
 	</listitem>
 	<listitem>
 	  <para>The audio input and output interface was found to be
 incomplete.</para>
 	  <para>Previously the &VIDIOC-G-AUDIO;
 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
 <constant>VIDIOC_G_AUDIO</constant> was renamed to
 <constant>VIDIOC_G_AUDIO_OLD</constant>, this ioctl will be removed in
 the future. The &VIDIOC-ENUMAUDIO; ioctl was added to enumerate
 audio inputs, while &VIDIOC-G-AUDIO; now reports the current audio
 input.</para>
 	  <para>The same changes were made to &VIDIOC-G-AUDOUT; and
 &VIDIOC-ENUMAUDOUT;.</para>
 	  <para>Until further the "videodev" module will automatically
 translate between the old and new ioctls, but drivers and applications
 must be updated to successfully compile again.</para>
 	</listitem>
 	<listitem>
 	  <para>The &VIDIOC-OVERLAY; ioctl was incorrectly defined with
 write-read parameter. It was changed to write-only, while the write-read
 version was renamed to <constant>VIDIOC_OVERLAY_OLD</constant>. The old
 ioctl will be removed in the future. Until further the "videodev"
 kernel module will automatically translate to the new version, so drivers
 must be recompiled, but not applications.</para>
 	</listitem>
 	<listitem>
 	  <para><xref linkend="overlay" /> incorrectly stated that
 clipping rectangles define regions where the video can be seen.
 Correct is that clipping rectangles define regions where
 <emphasis>no</emphasis> video shall be displayed and so the graphics
 surface can be seen.</para>
 	</listitem>
 	<listitem>
 	  <para>The &VIDIOC-S-PARM; and &VIDIOC-S-CTRL; ioctls were
 defined with write-only parameter, inconsistent with other ioctls
 modifying their argument. They were changed to write-read, while a
 <constant>_OLD</constant> suffix was added to the write-only versions.
 The old ioctls will be removed in the future. Drivers and
 applications assuming a constant parameter need an update.</para>
 	</listitem>
       </orderedlist>
     </section>
     <section>
       <title>V4L2 2003-11-05</title>
       <orderedlist>
 	<listitem>
 	  <para>In <xref linkend="pixfmt-rgb" /> the following pixel
 formats were incorrectly transferred from Bill Dirks' V4L2
 specification. Descriptions below refer to bytes in memory, in
 ascending address order.<informaltable>
 	      <tgroup cols="3">
 		<thead>
 		  <row>
 		    <entry>Symbol</entry>
 		    <entry>In this document prior to revision
 0.5</entry>
 		    <entry>Corrected</entry>
 		  </row>
 		</thead>
 		<tbody valign="top">
 		  <row>
 		    <entry><constant>V4L2_PIX_FMT_RGB24</constant></entry>
 		    <entry>B, G, R</entry>
 		    <entry>R, G, B</entry>
 		  </row>
 		  <row>
 		    <entry><constant>V4L2_PIX_FMT_BGR24</constant></entry>
 		    <entry>R, G, B</entry>
 		    <entry>B, G, R</entry>
 		  </row>
 		  <row>
 		    <entry><constant>V4L2_PIX_FMT_RGB32</constant></entry>
 		    <entry>B, G, R, X</entry>
 		    <entry>R, G, B, X</entry>
 		  </row>
 		  <row>
 		    <entry><constant>V4L2_PIX_FMT_BGR32</constant></entry>
 		    <entry>R, G, B, X</entry>
 		    <entry>B, G, R, X</entry>
 		  </row>
 		</tbody>
 	      </tgroup>
 	    </informaltable> The
 <constant>V4L2_PIX_FMT_BGR24</constant> example was always
 correct.</para>
 	  <para>In <xref linkend="v4l-image-properties" /> the mapping
 of the V4L <constant>VIDEO_PALETTE_RGB24</constant> and
 <constant>VIDEO_PALETTE_RGB32</constant> formats to V4L2 pixel formats
 was accordingly corrected.</para>
 	</listitem>
 	<listitem>
 	  <para>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 <xref
 	      linkend="pixfmt-rgb" />.</para>
 	</listitem>
       </orderedlist>
     </section>
     <section>
       <title>V4L2 in Linux 2.6.6, 2004-05-09</title>
       <orderedlist>
 	<listitem>
 	  <para>The &VIDIOC-CROPCAP; ioctl was incorrectly defined
 with read-only parameter. It is now defined as write-read ioctl, while
 the read-only version was renamed to
 <constant>VIDIOC_CROPCAP_OLD</constant>. The old ioctl will be removed
 in the future.</para>
 	</listitem>
       </orderedlist>
     </section>
     <section>
       <title>V4L2 in Linux 2.6.8</title>
       <orderedlist>
 	<listitem>
 	  <para>A new field <structfield>input</structfield> (former
 <structfield>reserved[0]</structfield>) was added to the &v4l2-buffer;
 structure. Purpose of this field is to alternate between video inputs
 (&eg; cameras) in step with the video capturing process. This function
 must be enabled with the new <constant>V4L2_BUF_FLAG_INPUT</constant>
 flag. The <structfield>flags</structfield> field is no longer
 read-only.</para>
 	</listitem>
       </orderedlist>
     </section>
     <section>
       <title>V4L2 spec erratum 2004-08-01</title>
       <orderedlist>
 	<listitem>
 	  <para>The return value of the
 <xref linkend="func-open" /> function was incorrectly documented.</para>
 	</listitem>
 	<listitem>
 	  <para>Audio output ioctls end in -AUDOUT, not -AUDIOOUT.</para>
 	</listitem>
 	<listitem>
 	  <para>In the Current Audio Input example the
 <constant>VIDIOC_G_AUDIO</constant> ioctl took the wrong
 argument.</para>
 	</listitem>
 	<listitem>
 	  <para>The documentation of the &VIDIOC-QBUF; and
 &VIDIOC-DQBUF; ioctls did not mention the &v4l2-buffer;
 <structfield>memory</structfield> field. It was also missing from
 examples. Also on the <constant>VIDIOC_DQBUF</constant> page the &EIO;
 was not documented.</para>
 	</listitem>
       </orderedlist>
     </section>
     <section>
       <title>V4L2 in Linux 2.6.14</title>
       <orderedlist>
 	<listitem>
 	  <para>A new sliced VBI interface was added. It is documented
 in <xref linkend="sliced" /> and replaces the interface first
 proposed in V4L2 specification 0.8.</para>
 	</listitem>
       </orderedlist>
     </section>
     <section>
       <title>V4L2 in Linux 2.6.15</title>
       <orderedlist>
 	<listitem>
 	  <para>The &VIDIOC-LOG-STATUS; ioctl was added.</para>
 	</listitem>
 	<listitem>
 	  <para>New video standards
 <constant>V4L2_STD_NTSC_443</constant>,
 <constant>V4L2_STD_SECAM_LC</constant>,
 <constant>V4L2_STD_SECAM_DK</constant> (a set of SECAM D, K and K1),
 and <constant>V4L2_STD_ATSC</constant> (a set of
 <constant>V4L2_STD_ATSC_8_VSB</constant> and
 <constant>V4L2_STD_ATSC_16_VSB</constant>) were defined. Note the
 <constant>V4L2_STD_525_60</constant> set now includes
 <constant>V4L2_STD_NTSC_443</constant>. See also <xref
 	      linkend="v4l2-std-id" />.</para>
 	</listitem>
 	<listitem>
 	  <para>The <constant>VIDIOC_G_COMP</constant> and
 <constant>VIDIOC_S_COMP</constant> ioctl were renamed to
 <constant>VIDIOC_G_MPEGCOMP</constant> and
 <constant>VIDIOC_S_MPEGCOMP</constant> respectively. Their argument
 was replaced by a struct
 <structname>v4l2_mpeg_compression</structname> pointer. (The
 <constant>VIDIOC_G_MPEGCOMP</constant> and
 <constant>VIDIOC_S_MPEGCOMP</constant> ioctls where removed in Linux
 2.6.25.)</para>
 	</listitem>
       </orderedlist>
     </section>
     <section>
       <title>V4L2 spec erratum 2005-11-27</title>
       <para>The capture example in <xref linkend="capture-example" />
 called the &VIDIOC-S-CROP; ioctl without checking if cropping is
 supported. In the video standard selection example in
 <xref linkend="standard" /> the &VIDIOC-S-STD; call used the wrong
 argument type.</para>
     </section>
     <section>
       <title>V4L2 spec erratum 2006-01-10</title>
       <orderedlist>
 	<listitem>
 	  <para>The <constant>V4L2_IN_ST_COLOR_KILL</constant> flag in
 &v4l2-input; not only indicates if the color killer is enabled, but
 also if it is active. (The color killer disables color decoding when
 it detects no color in the video signal to improve the image
 quality.)</para>
 	</listitem>
 	<listitem>
 	  <para>&VIDIOC-S-PARM; is a write-read ioctl, not write-only as
 stated on its reference page. The ioctl changed in 2003 as noted above.</para>
 	</listitem>
       </orderedlist>
     </section>
     <section>
       <title>V4L2 spec erratum 2006-02-03</title>
       <orderedlist>
 	<listitem>
 	  <para>In &v4l2-captureparm; and &v4l2-outputparm; the
 <structfield>timeperframe</structfield> field gives the time in
 seconds, not microseconds.</para>
 	</listitem>
       </orderedlist>
     </section>
     <section>
       <title>V4L2 spec erratum 2006-02-04</title>
       <orderedlist>
 	<listitem>
 	  <para>The <structfield>clips</structfield> field in
 &v4l2-window; must point to an array of &v4l2-clip;, not a linked
 list, because drivers ignore the struct
 <structname>v4l2_clip</structname>.<structfield>next</structfield>
 pointer.</para>
 	</listitem>
       </orderedlist>
     </section>
     <section>
       <title>V4L2 in Linux 2.6.17</title>
       <orderedlist>
 	<listitem>
 	  <para>New video standard macros were added:
 <constant>V4L2_STD_NTSC_M_KR</constant> (NTSC M South Korea), and the
 sets <constant>V4L2_STD_MN</constant>,
 <constant>V4L2_STD_B</constant>, <constant>V4L2_STD_GH</constant> and
 <constant>V4L2_STD_DK</constant>. The
 <constant>V4L2_STD_NTSC</constant> and
 <constant>V4L2_STD_SECAM</constant> sets now include
 <constant>V4L2_STD_NTSC_M_KR</constant> and
 <constant>V4L2_STD_SECAM_LC</constant> respectively.</para>
 	</listitem>
 	<listitem>
 	  <para>A new <constant>V4L2_TUNER_MODE_LANG1_LANG2</constant>
 was defined to record both languages of a bilingual program. The
 use of <constant>V4L2_TUNER_MODE_STEREO</constant> for this purpose
 is deprecated now. See the &VIDIOC-G-TUNER; section for
 details.</para>
 	</listitem>
       </orderedlist>
     </section>
     <section>
       <title>V4L2 spec erratum 2006-09-23 (Draft 0.15)</title>
       <orderedlist>
 	<listitem>
 	  <para>In various places
 <constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant> and
 <constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant> of the sliced VBI
 interface were not mentioned along with other buffer types.</para>
 	</listitem>
 	<listitem>
 	  <para>In <xref linkend="vidioc-g-audio" /> it was clarified
 that the &v4l2-audio; <structfield>mode</structfield> field is a flags
 field.</para>
 	</listitem>
 	<listitem>
 	  <para><xref linkend="vidioc-querycap" /> did not mention the
 sliced VBI and radio capability flags.</para>
 	</listitem>
 	<listitem>
 	  <para>In <xref linkend="vidioc-g-frequency" /> it was
 clarified that applications must initialize the tuner
 <structfield>type</structfield> field of &v4l2-frequency; before
 calling &VIDIOC-S-FREQUENCY;.</para>
 	</listitem>
 	<listitem>
 	  <para>The <structfield>reserved</structfield> array
 in &v4l2-requestbuffers; has 2 elements, not 32.</para>
 	</listitem>
 	<listitem>
 	  <para>In <xref linkend="output" /> and <xref
 	      linkend="raw-vbi" /> the device file names
 <filename>/dev/vout</filename> which never caught on were replaced
 by <filename>/dev/video</filename>.</para>
 	</listitem>
 	<listitem>
 	  <para>With Linux 2.6.15 the possible range for VBI device minor
 numbers was extended from 224-239 to 224-255. Accordingly device file names
 <filename>/dev/vbi0</filename> to <filename>/dev/vbi31</filename> are
 possible now.</para>
 	</listitem>
       </orderedlist>
     </section>
     <section>
       <title>V4L2 in Linux 2.6.18</title>
       <orderedlist>
 	<listitem>
 	  <para>New ioctls &VIDIOC-G-EXT-CTRLS;, &VIDIOC-S-EXT-CTRLS;
 and &VIDIOC-TRY-EXT-CTRLS; were added, a flag to skip unsupported
 controls with &VIDIOC-QUERYCTRL;, new control types
 <constant>V4L2_CTRL_TYPE_INTEGER64</constant> and
 <constant>V4L2_CTRL_TYPE_CTRL_CLASS</constant> (<xref
 	      linkend="v4l2-ctrl-type" />), and new control flags
 <constant>V4L2_CTRL_FLAG_READ_ONLY</constant>,
 <constant>V4L2_CTRL_FLAG_UPDATE</constant>,
 <constant>V4L2_CTRL_FLAG_INACTIVE</constant> and
 <constant>V4L2_CTRL_FLAG_SLIDER</constant> (<xref
 	      linkend="control-flags" />). See <xref
 	      linkend="extended-controls" /> for details.</para>
 	</listitem>
       </orderedlist>
     </section>
     <section>
       <title>V4L2 in Linux 2.6.19</title>
       <orderedlist>
 	<listitem>
 	  <para>In &v4l2-sliced-vbi-cap; a buffer type field was added
 replacing a reserved field. Note on architectures where the size of
 enum types differs from int types the size of the structure changed.
 The &VIDIOC-G-SLICED-VBI-CAP; ioctl was redefined from being read-only
 to write-read. Applications must initialize the type field and clear
 the reserved fields now. These changes may <emphasis>break the
 compatibility</emphasis> with older drivers and applications.</para>
 	</listitem>
 	<listitem>
 	  <para>The ioctls &VIDIOC-ENUM-FRAMESIZES; and
 &VIDIOC-ENUM-FRAMEINTERVALS; were added.</para>
 	</listitem>
 	<listitem>
 	  <para>A new pixel format <constant>V4L2_PIX_FMT_RGB444</constant> (<xref
 linkend="rgb-formats" />) was added.</para>
 	</listitem>
       </orderedlist>
     </section>
     <section>
       <title>V4L2 spec erratum 2006-10-12 (Draft 0.17)</title>
       <orderedlist>
 	<listitem>
 	  <para><constant>V4L2_PIX_FMT_HM12</constant> (<xref
 linkend="reserved-formats" />) is a YUV 4:2:0, not 4:2:2 format.</para>
 	</listitem>
       </orderedlist>
     </section>
     <section>
       <title>V4L2 in Linux 2.6.21</title>
       <orderedlist>
 	<listitem>
 	  <para>The <filename>videodev2.h</filename> header file is
 now dual licensed under GNU General Public License version two or
 later, and under a 3-clause BSD-style license.</para>
 	</listitem>
       </orderedlist>
     </section>
     <section>
       <title>V4L2 in Linux 2.6.22</title>
       <orderedlist>
 	<listitem>
 	  <para>Two new field orders
 	  <constant>V4L2_FIELD_INTERLACED_TB</constant> and
 	  <constant>V4L2_FIELD_INTERLACED_BT</constant> were
 	  added. See <xref linkend="v4l2-field" /> for details.</para>
 	</listitem>
 	<listitem>
 	  <para>Three new clipping/blending methods with a global or
 straight or inverted local alpha value were added to the video overlay
 interface. See the description of the &VIDIOC-G-FBUF; and
 &VIDIOC-S-FBUF; ioctls for details.</para>
 	  <para>A new <structfield>global_alpha</structfield> field
 was added to <link
 linkend="v4l2-window"><structname>v4l2_window</structname></link>,
 extending the structure. This may <emphasis>break
 compatibility</emphasis> with applications using a struct
 <structname>v4l2_window</structname> directly. However the <link
 linkend="vidioc-g-fmt">VIDIOC_G/S/TRY_FMT</link> ioctls, which take a
 pointer to a <link linkend="v4l2-format">v4l2_format</link> parent
 structure with padding bytes at the end, are not affected.</para>
 	</listitem>
 	<listitem>
 	  <para>The format of the <structfield>chromakey</structfield>
 field in &v4l2-window; changed from "host order RGB32" to a pixel
 value in the same format as the framebuffer. This may <emphasis>break
 compatibility</emphasis> with existing applications. Drivers
 supporting the "host order RGB32" format are not known.</para>
 	</listitem>
       </orderedlist>
     </section>
     <section>
       <title>V4L2 in Linux 2.6.24</title>
       <orderedlist>
 	<listitem>
 	  <para>The pixel formats
 <constant>V4L2_PIX_FMT_PAL8</constant>,
 <constant>V4L2_PIX_FMT_YUV444</constant>,
 <constant>V4L2_PIX_FMT_YUV555</constant>,
 <constant>V4L2_PIX_FMT_YUV565</constant> and
 <constant>V4L2_PIX_FMT_YUV32</constant> were added.</para>
 	</listitem>
       </orderedlist>
     </section>
     <section>
       <title>V4L2 in Linux 2.6.25</title>
       <orderedlist>
 	<listitem>
 	  <para>The pixel formats <link linkend="V4L2-PIX-FMT-Y16">
 <constant>V4L2_PIX_FMT_Y16</constant></link> and <link
 linkend="V4L2-PIX-FMT-SBGGR16">
 <constant>V4L2_PIX_FMT_SBGGR16</constant></link> were added.</para>
 	</listitem>
 	<listitem>
 	  <para>New <link linkend="control">controls</link>
 <constant>V4L2_CID_POWER_LINE_FREQUENCY</constant>,
 <constant>V4L2_CID_HUE_AUTO</constant>,
 <constant>V4L2_CID_WHITE_BALANCE_TEMPERATURE</constant>,
 <constant>V4L2_CID_SHARPNESS</constant> and
 <constant>V4L2_CID_BACKLIGHT_COMPENSATION</constant> were added. The
 controls <constant>V4L2_CID_BLACK_LEVEL</constant>,
 <constant>V4L2_CID_WHITENESS</constant>,
 <constant>V4L2_CID_HCENTER</constant> and
 <constant>V4L2_CID_VCENTER</constant> were deprecated.
 </para>
 	</listitem>
 	<listitem>
 	  <para>A <link linkend="camera-controls">Camera controls
 class</link> was added, with the new controls
 <constant>V4L2_CID_EXPOSURE_AUTO</constant>,
 <constant>V4L2_CID_EXPOSURE_ABSOLUTE</constant>,
 <constant>V4L2_CID_EXPOSURE_AUTO_PRIORITY</constant>,
 <constant>V4L2_CID_PAN_RELATIVE</constant>,
 <constant>V4L2_CID_TILT_RELATIVE</constant>,
 <constant>V4L2_CID_PAN_RESET</constant>,
 <constant>V4L2_CID_TILT_RESET</constant>,
 <constant>V4L2_CID_PAN_ABSOLUTE</constant>,
 <constant>V4L2_CID_TILT_ABSOLUTE</constant>,
 <constant>V4L2_CID_FOCUS_ABSOLUTE</constant>,
 <constant>V4L2_CID_FOCUS_RELATIVE</constant> and
 <constant>V4L2_CID_FOCUS_AUTO</constant>.</para>
 	</listitem>
 	<listitem>
 	  <para>The <constant>VIDIOC_G_MPEGCOMP</constant> and
 <constant>VIDIOC_S_MPEGCOMP</constant> ioctls, which were superseded
 by the <link linkend="extended-controls">extended controls</link>
 interface in Linux 2.6.18, where finally removed from the
 <filename>videodev2.h</filename> header file.</para>
 	</listitem>
       </orderedlist>
     </section>
     <section>
       <title>V4L2 in Linux 2.6.26</title>
       <orderedlist>
 	<listitem>
 	  <para>The pixel formats
 <constant>V4L2_PIX_FMT_Y16</constant> and
 <constant>V4L2_PIX_FMT_SBGGR16</constant> were added.</para>
 	</listitem>
 	<listitem>
 	  <para>Added user controls
 <constant>V4L2_CID_CHROMA_AGC</constant> and
 <constant>V4L2_CID_COLOR_KILLER</constant>.</para>
 	</listitem>
       </orderedlist>
     </section>
     <section>
       <title>V4L2 in Linux 2.6.27</title>
       <orderedlist>
 	<listitem>
 	  <para>The &VIDIOC-S-HW-FREQ-SEEK; ioctl and the
 <constant>V4L2_CAP_HW_FREQ_SEEK</constant> capability were added.</para>
 	</listitem>
 	<listitem>
 	  <para>The pixel formats
 <constant>V4L2_PIX_FMT_YVYU</constant>,
 <constant>V4L2_PIX_FMT_PCA501</constant>,
 <constant>V4L2_PIX_FMT_PCA505</constant>,
 <constant>V4L2_PIX_FMT_PCA508</constant>,
 <constant>V4L2_PIX_FMT_PCA561</constant>,
 <constant>V4L2_PIX_FMT_SGBRG8</constant>,
 <constant>V4L2_PIX_FMT_PAC207</constant> and
 <constant>V4L2_PIX_FMT_PJPG</constant> were added.</para>
 	</listitem>
       </orderedlist>
     </section>
     <section>
       <title>V4L2 in Linux 2.6.28</title>
       <orderedlist>
 	<listitem>
 	  <para>Added <constant>V4L2_MPEG_AUDIO_ENCODING_AAC</constant> and
 <constant>V4L2_MPEG_AUDIO_ENCODING_AC3</constant> MPEG audio encodings.</para>
 	</listitem>
 	<listitem>
 	  <para>Added <constant>V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC</constant> MPEG
 video encoding.</para>
 	</listitem>
 	<listitem>
 	  <para>The pixel formats
 <constant>V4L2_PIX_FMT_SGRBG10</constant> and
 <constant>V4L2_PIX_FMT_SGRBG10DPCM8</constant> were added.</para>
 	</listitem>
       </orderedlist>
     </section>
     <section>
       <title>V4L2 in Linux 2.6.29</title>
       <orderedlist>
 	<listitem>
 	  <para>The <constant>VIDIOC_G_CHIP_IDENT</constant> ioctl was renamed
 to <constant>VIDIOC_G_CHIP_IDENT_OLD</constant> and &VIDIOC-DBG-G-CHIP-IDENT;
 was introduced in its place. The old struct <structname>v4l2_chip_ident</structname>
 was renamed to <structname id="v4l2-chip-ident-old">v4l2_chip_ident_old</structname>.</para>
 	</listitem>
 	<listitem>
 	  <para>The pixel formats
 <constant>V4L2_PIX_FMT_VYUY</constant>,
 <constant>V4L2_PIX_FMT_NV16</constant> and
 <constant>V4L2_PIX_FMT_NV61</constant> were added.</para>
 	</listitem>
 	<listitem>
 	  <para>Added camera controls
 <constant>V4L2_CID_ZOOM_ABSOLUTE</constant>,
 <constant>V4L2_CID_ZOOM_RELATIVE</constant>,
 <constant>V4L2_CID_ZOOM_CONTINUOUS</constant> and
 <constant>V4L2_CID_PRIVACY</constant>.</para>
 	</listitem>
       </orderedlist>
     </section>
     <section>
       <title>V4L2 in Linux 2.6.30</title>
       <orderedlist>
 	<listitem>
 	  <para>New control flag <constant>V4L2_CTRL_FLAG_WRITE_ONLY</constant> was added.</para>
 	</listitem>
 	<listitem>
 	  <para>New control <constant>V4L2_CID_COLORFX</constant> was added.</para>
 	</listitem>
       </orderedlist>
     </section>
     <section>
       <title>V4L2 in Linux 2.6.32</title>
       <orderedlist>
 	<listitem>
 	  <para>In order to be easier to compare a V4L2 API and a kernel
 version, now V4L2 API is numbered using the Linux Kernel version numeration.</para>
 	</listitem>
 	<listitem>
 	  <para>Finalized the RDS capture API. See <xref linkend="rds" /> for
 more information.</para>
 	</listitem>
 	<listitem>
 	  <para>Added new capabilities for modulators and RDS encoders.</para>
 	</listitem>
 	<listitem>
 	  <para>Add description for libv4l API.</para>
 	</listitem>
 	<listitem>
 	  <para>Added support for string controls via new type <constant>V4L2_CTRL_TYPE_STRING</constant>.</para>
 	</listitem>
 	<listitem>
 	  <para>Added <constant>V4L2_CID_BAND_STOP_FILTER</constant> documentation.</para>
 	</listitem>
 	<listitem>
 	  <para>Added FM Modulator (FM TX) Extended Control Class: <constant>V4L2_CTRL_CLASS_FM_TX</constant> and their Control IDs.</para>
 	</listitem>
 	<listitem>
 	  <para>Added Remote Controller chapter, describing the default Remote Controller mapping for media devices.</para>
 	</listitem>
       </orderedlist>
     </section>
     <section>
       <title>V4L2 in Linux 2.6.33</title>
       <orderedlist>
 	<listitem>
 	  <para>Added support for Digital Video timings in order to support HDTV receivers and transmitters.</para>
 	</listitem>
       </orderedlist>
     </section>
     <section>
       <title>V4L2 in Linux 2.6.34</title>
       <orderedlist>
 	<listitem>
 	  <para>Added
 <constant>V4L2_CID_IRIS_ABSOLUTE</constant> and
 <constant>V4L2_CID_IRIS_RELATIVE</constant> controls to the
 	    <link linkend="camera-controls">Camera controls class</link>.
 	  </para>
 	</listitem>
       </orderedlist>
     </section>
     <section>
       <title>V4L2 in Linux 2.6.37</title>
       <orderedlist>
 	<listitem>
 	  <para>Remove the vtx (videotext/teletext) API. This API was no longer
 used and no hardware exists to verify the API. Nor were any userspace applications found
 that used it. It was originally scheduled for removal in 2.6.35.
 	  </para>
 	</listitem>
       </orderedlist>
     </section>
+    <section>
+      <title>V4L2 in Linux 2.6.38</title>
+      <orderedlist>
+        <listitem>
+          <para>Multi-planar API added. Does not affect the compatibility of
+          current drivers and applications. See
+          <link linkend="planar-apis">multi-planar API</link>
+          for details.</para>
+        </listitem>
+      </orderedlist>
+    </section>
     <section id="other">
       <title>Relation of V4L2 to other Linux multimedia APIs</title>
       <section id="xvideo">
         <title>X Video Extension</title>
         <para>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<footnote>
 	  <para>This is not implemented in XFree86.</para>
 	</footnote>. With their implementation XFree86 makes the
 extension available across many operating systems and
 architectures.</para>
         <para>Because the driver is embedded into the X server Xv has a
 number of advantages over the V4L2 <link linkend="overlay">video
 overlay interface</link>. The driver can easily determine the overlay
 target, &ie; visible graphics memory or off-screen buffers for a
 destructive overlay. It can program the RAMDAC for a non-destructive
 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.</para>
         <para>To combine the advantages of Xv and V4L a special Xv
 driver exists in XFree86 and XOrg, just programming any overlay capable
 Video4Linux device it finds. To enable it
 <filename>/etc/X11/XF86Config</filename> must contain these lines:</para>
         <para><screen>
 Section "Module"
     Load "v4l"
 EndSection</screen></para>
         <para>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 are discussed in <xref
 	  linkend="overlay" /> apply.</para>
         <para>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 API
 is useful to display images captured with V4L2 devices.</para>
       </section>
       <section>
         <title>Digital Video</title>
         <para>V4L2 does not support digital terrestrial, cable or
 satellite broadcast. A separate project aiming at digital receivers
 exists. You can find its homepage at <ulink
 url="http://linuxtv.org">http://linuxtv.org</ulink>. The Linux DVB API
 has no connection to the V4L2 API except that drivers for hybrid
 hardware may support both.</para>
       </section>
       <section>
         <title>Audio Interfaces</title>
         <para>[to do - OSS/ALSA]</para>
       </section>
     </section>
     <section id="experimental">
       <title>Experimental API Elements</title>
       <para>The following V4L2 API elements are currently experimental
 and may change in the future.</para>
       <itemizedlist>
         <listitem>
 	  <para>Video Output Overlay (OSD) Interface, <xref
 	    linkend="osd" />.</para>
         </listitem>
 	<listitem>
 	  <para><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant>,
 	&v4l2-buf-type;, <xref linkend="v4l2-buf-type" />.</para>
         </listitem>
         <listitem>
 	  <para><constant>V4L2_CAP_VIDEO_OUTPUT_OVERLAY</constant>,
 &VIDIOC-QUERYCAP; ioctl, <xref linkend="device-capabilities" />.</para>
         </listitem>
         <listitem>
 	  <para>&VIDIOC-ENUM-FRAMESIZES; and
 &VIDIOC-ENUM-FRAMEINTERVALS; ioctls.</para>
         </listitem>
         <listitem>
 	  <para>&VIDIOC-G-ENC-INDEX; ioctl.</para>
         </listitem>
         <listitem>
 	  <para>&VIDIOC-ENCODER-CMD; and &VIDIOC-TRY-ENCODER-CMD;
 ioctls.</para>
         </listitem>
         <listitem>
 	  <para>&VIDIOC-DBG-G-REGISTER; and &VIDIOC-DBG-S-REGISTER;
 ioctls.</para>
         </listitem>
         <listitem>
 	  <para>&VIDIOC-DBG-G-CHIP-IDENT; ioctl.</para>
         </listitem>
       </itemizedlist>
     </section>
     <section id="obsolete">
       <title>Obsolete API Elements</title>
       <para>The following V4L2 API elements were superseded by new
 interfaces and should not be implemented in new drivers.</para>
       <itemizedlist>
         <listitem>
 	  <para><constant>VIDIOC_G_MPEGCOMP</constant> and
 <constant>VIDIOC_S_MPEGCOMP</constant> ioctls. Use Extended Controls,
 <xref linkend="extended-controls" />.</para>
         </listitem>
       </itemizedlist>
     </section>
   </section>
   <!--
 Local Variables:
 mode: sgml
 sgml-parent-document: "v4l2.sgml"
 indent-tabs-mode: nil
 End:
   -->

Documentation/DocBook/v4l/dev-capture.xml

Diff comments View file @ 53b5d57

   <title>Video Capture Interface</title>
   <para>Video capture devices sample an analog video signal and store
 the digitized images in memory. Today nearly all devices can capture
 at full 25 or 30 frames/second. With this interface applications can
 control the capture process and move images from the driver into user
 space.</para>
   <para>Conventionally V4L2 video capture devices are accessed through
 character device special files named <filename>/dev/video</filename>
 and <filename>/dev/video0</filename> to
 <filename>/dev/video63</filename> with major number 81 and minor
 numbers 0 to 63. <filename>/dev/video</filename> is typically a
 symbolic link to the preferred video device. Note the same device
 files are used for video output devices.</para>
   <section>
     <title>Querying Capabilities</title>
     <para>Devices supporting the video capture interface set the
-<constant>V4L2_CAP_VIDEO_CAPTURE</constant> flag in the
+<constant>V4L2_CAP_VIDEO_CAPTURE</constant> or
+<constant>V4L2_CAP_VIDEO_CAPTURE_MPLANE</constant> flag in the
 <structfield>capabilities</structfield> field of &v4l2-capability;
 returned by the &VIDIOC-QUERYCAP; ioctl. As secondary device functions
 they may also support the <link linkend="overlay">video overlay</link>
 (<constant>V4L2_CAP_VIDEO_OVERLAY</constant>) and the <link
 linkend="raw-vbi">raw VBI capture</link>
 (<constant>V4L2_CAP_VBI_CAPTURE</constant>) interface. At least one of
 the read/write or streaming I/O methods must be supported. Tuners and
 audio inputs are optional.</para>
   </section>
   <section>
     <title>Supplemental Functions</title>
     <para>Video capture devices shall support <link
 linkend="audio">audio input</link>, <link
 linkend="tuner">tuner</link>, <link linkend="control">controls</link>,
 <link linkend="crop">cropping and scaling</link> and <link
 linkend="streaming-par">streaming parameter</link> ioctls as needed.
 The <link linkend="video">video input</link> and <link
 linkend="standard">video standard</link> ioctls must be supported by
 all video capture devices.</para>
   </section>
   <section>
     <title>Image Format Negotiation</title>
     <para>The result of a capture operation is determined by
 cropping and image format parameters. The former select an area of the
 video picture to capture, the latter how images are stored in memory,
 &ie; in RGB or YUV format, the number of bits per pixel or width and
 height. Together they also define how images are scaled in the
 process.</para>
     <para>As usual these parameters are <emphasis>not</emphasis> reset
 at &func-open; time to permit Unix tool chains, programming a device
 and then reading from it as if it was a plain file. Well written V4L2
 applications ensure they really get what they want, including cropping
 and scaling.</para>
     <para>Cropping initialization at minimum requires to reset the
 parameters to defaults. An example is given in <xref
 linkend="crop" />.</para>
     <para>To query the current image format applications set the
 <structfield>type</structfield> field of a &v4l2-format; to
-<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> and call the
+<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> or
+<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant> and call the
 &VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill
-the &v4l2-pix-format; <structfield>pix</structfield> member of the
+the &v4l2-pix-format; <structfield>pix</structfield> or the
+&v4l2-pix-format-mplane; <structfield>pix_mp</structfield> member of the
 <structfield>fmt</structfield> union.</para>
     <para>To request different parameters applications set the
 <structfield>type</structfield> field of a &v4l2-format; as above and
 initialize all fields of the &v4l2-pix-format;
 <structfield>vbi</structfield> member of the
 <structfield>fmt</structfield> union, or better just modify the
 results of <constant>VIDIOC_G_FMT</constant>, and call the
 &VIDIOC-S-FMT; ioctl with a pointer to this structure. Drivers may
 adjust the parameters and finally return the actual parameters as
 <constant>VIDIOC_G_FMT</constant> does.</para>
     <para>Like <constant>VIDIOC_S_FMT</constant> the
 &VIDIOC-TRY-FMT; ioctl can be used to learn about hardware limitations
 without disabling I/O or possibly time consuming hardware
 preparations.</para>
-    <para>The contents of &v4l2-pix-format; are discussed in <xref
+    <para>The contents of &v4l2-pix-format; and &v4l2-pix-format-mplane;
-linkend="pixfmt" />. See also the specification of the
+are discussed in <xref linkend="pixfmt" />. See also the specification of the
 <constant>VIDIOC_G_FMT</constant>, <constant>VIDIOC_S_FMT</constant>
 and <constant>VIDIOC_TRY_FMT</constant> ioctls for details. Video
 capture devices must implement both the
 <constant>VIDIOC_G_FMT</constant> and
 <constant>VIDIOC_S_FMT</constant> ioctl, even if
 <constant>VIDIOC_S_FMT</constant> ignores all requests and always
 returns default parameters as <constant>VIDIOC_G_FMT</constant> does.
 <constant>VIDIOC_TRY_FMT</constant> is optional.</para>
   </section>
   <section>
     <title>Reading Images</title>
     <para>A video capture device may support the <link
 linkend="rw">read() function</link> and/or streaming (<link
 linkend="mmap">memory mapping</link> or <link
 linkend="userp">user pointer</link>) I/O. See <xref
 linkend="io" /> for details.</para>
   </section>
   <!--
 Local Variables:
 mode: sgml
 sgml-parent-document: "v4l2.sgml"
 indent-tabs-mode: nil
 End:
   -->

Documentation/DocBook/v4l/dev-output.xml

Diff comments View file @ 53b5d57

   <title>Video Output Interface</title>
   <para>Video output devices encode stills or image sequences as
 analog video signal. With this interface applications can
 control the encoding process and move images from user space to
 the driver.</para>
   <para>Conventionally V4L2 video output devices are accessed through
 character device special files named <filename>/dev/video</filename>
 and <filename>/dev/video0</filename> to
 <filename>/dev/video63</filename> with major number 81 and minor
 numbers 0 to 63. <filename>/dev/video</filename> is typically a
 symbolic link to the preferred video device. Note the same device
 files are used for video capture devices.</para>
   <section>
     <title>Querying Capabilities</title>
     <para>Devices supporting the video output interface set the
-<constant>V4L2_CAP_VIDEO_OUTPUT</constant> flag in the
+<constant>V4L2_CAP_VIDEO_OUTPUT</constant> or
+<constant>V4L2_CAP_VIDEO_OUTPUT_MPLANE</constant> flag in the
 <structfield>capabilities</structfield> field of &v4l2-capability;
 returned by the &VIDIOC-QUERYCAP; ioctl. As secondary device functions
 they may also support the <link linkend="raw-vbi">raw VBI
 output</link> (<constant>V4L2_CAP_VBI_OUTPUT</constant>) interface. At
 least one of the read/write or streaming I/O methods must be
 supported. Modulators and audio outputs are optional.</para>
   </section>
   <section>
     <title>Supplemental Functions</title>
     <para>Video output devices shall support <link
 linkend="audio">audio output</link>, <link
 linkend="tuner">modulator</link>, <link linkend="control">controls</link>,
 <link linkend="crop">cropping and scaling</link> and <link
 linkend="streaming-par">streaming parameter</link> ioctls as needed.
 The <link linkend="video">video output</link> and <link
 linkend="standard">video standard</link> ioctls must be supported by
 all video output devices.</para>
   </section>
   <section>
     <title>Image Format Negotiation</title>
     <para>The output is determined by cropping and image format
 parameters. The former select an area of the video picture where the
 image will appear, the latter how images are stored in memory, &ie; in
 RGB or YUV format, the number of bits per pixel or width and height.
 Together they also define how images are scaled in the process.</para>
     <para>As usual these parameters are <emphasis>not</emphasis> reset
 at &func-open; time to permit Unix tool chains, programming a device
 and then writing to it as if it was a plain file. Well written V4L2
 applications ensure they really get what they want, including cropping
 and scaling.</para>
     <para>Cropping initialization at minimum requires to reset the
 parameters to defaults. An example is given in <xref
 linkend="crop" />.</para>
     <para>To query the current image format applications set the
 <structfield>type</structfield> field of a &v4l2-format; to
-<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> and call the
+<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> or
+<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant> and call the
 &VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill
-the &v4l2-pix-format; <structfield>pix</structfield> member of the
+the &v4l2-pix-format; <structfield>pix</structfield> or the
+&v4l2-pix-format-mplane; <structfield>pix_mp</structfield> member of the
 <structfield>fmt</structfield> union.</para>
     <para>To request different parameters applications set the
 <structfield>type</structfield> field of a &v4l2-format; as above and
 initialize all fields of the &v4l2-pix-format;
 <structfield>vbi</structfield> member of the
 <structfield>fmt</structfield> union, or better just modify the
 results of <constant>VIDIOC_G_FMT</constant>, and call the
 &VIDIOC-S-FMT; ioctl with a pointer to this structure. Drivers may
 adjust the parameters and finally return the actual parameters as
 <constant>VIDIOC_G_FMT</constant> does.</para>
     <para>Like <constant>VIDIOC_S_FMT</constant> the
 &VIDIOC-TRY-FMT; ioctl can be used to learn about hardware limitations
 without disabling I/O or possibly time consuming hardware
 preparations.</para>
-    <para>The contents of &v4l2-pix-format; are discussed in <xref
+    <para>The contents of &v4l2-pix-format; and &v4l2-pix-format-mplane;
-linkend="pixfmt" />. See also the specification of the
+are discussed in <xref linkend="pixfmt" />. See also the specification of the
 <constant>VIDIOC_G_FMT</constant>, <constant>VIDIOC_S_FMT</constant>
 and <constant>VIDIOC_TRY_FMT</constant> ioctls for details. Video
 output devices must implement both the
 <constant>VIDIOC_G_FMT</constant> and
 <constant>VIDIOC_S_FMT</constant> ioctl, even if
 <constant>VIDIOC_S_FMT</constant> ignores all requests and always
 returns default parameters as <constant>VIDIOC_G_FMT</constant> does.
 <constant>VIDIOC_TRY_FMT</constant> is optional.</para>
   </section>
   <section>
     <title>Writing Images</title>
     <para>A video output device may support the <link
 linkend="rw">write() function</link> and/or streaming (<link
 linkend="mmap">memory mapping</link> or <link
 linkend="userp">user pointer</link>) I/O. See <xref
 linkend="io" /> for details.</para>
   </section>
   <!--
 Local Variables:
 mode: sgml
 sgml-parent-document: "v4l2.sgml"
 indent-tabs-mode: nil
 End:
   -->

Documentation/DocBook/v4l/func-mmap.xml

Diff comments View file @ 53b5d57

 <refentry id="func-mmap">
   <refmeta>
     <refentrytitle>V4L2 mmap()</refentrytitle>
     &manvol;
   </refmeta>
   <refnamediv>
     <refname>v4l2-mmap</refname>
     <refpurpose>Map device memory into application address space</refpurpose>
   </refnamediv>
   <refsynopsisdiv>
     <funcsynopsis>
       <funcsynopsisinfo>
 #include &lt;unistd.h&gt;
 #include &lt;sys/mman.h&gt;</funcsynopsisinfo>
       <funcprototype>
 	<funcdef>void *<function>mmap</function></funcdef>
 	<paramdef>void *<parameter>start</parameter></paramdef>
 	<paramdef>size_t <parameter>length</parameter></paramdef>
 	<paramdef>int <parameter>prot</parameter></paramdef>
 	<paramdef>int <parameter>flags</parameter></paramdef>
 	<paramdef>int <parameter>fd</parameter></paramdef>
 	<paramdef>off_t <parameter>offset</parameter></paramdef>
       </funcprototype>
     </funcsynopsis>
   </refsynopsisdiv>
   <refsect1>
     <title>Arguments</title>
     <variablelist>
       <varlistentry>
 	<term><parameter>start</parameter></term>
 	<listitem>
 	  <para>Map the buffer to this address in the
 application's address space. When the <constant>MAP_FIXED</constant>
 flag is specified, <parameter>start</parameter> must be a multiple of the
 pagesize and mmap will fail when the specified address
 cannot be used. Use of this option is discouraged; applications should
 just specify a <constant>NULL</constant> pointer here.</para>
 	</listitem>
       </varlistentry>
       <varlistentry>
 	<term><parameter>length</parameter></term>
 	<listitem>
 	  <para>Length of the memory area to map. This must be the
 same value as returned by the driver in the &v4l2-buffer;
-<structfield>length</structfield> field.</para>
+<structfield>length</structfield> field for the
+single-planar API, and the same value as returned by the driver
+in the &v4l2-plane; <structfield>length</structfield> field for the
+multi-planar API.</para>
 	</listitem>
       </varlistentry>
       <varlistentry>
 	<term><parameter>prot</parameter></term>
 	<listitem>
 	  <para>The <parameter>prot</parameter> argument describes the
 desired memory protection. Regardless of the device type and the
 direction of data exchange it should be set to
 <constant>PROT_READ</constant> | <constant>PROT_WRITE</constant>,
 permitting read and write access to image buffers. Drivers should
 support at least this combination of flags. Note the Linux
 <filename>video-buf</filename> kernel module, which is used by the
 bttv, saa7134, saa7146, cx88 and vivi driver supports only
 <constant>PROT_READ</constant> | <constant>PROT_WRITE</constant>. When
 the driver does not support the desired protection the
 <function>mmap()</function> function fails.</para>
 	  <para>Note device memory accesses (&eg; the memory on a
 graphics card with video capturing hardware) may incur a performance
 penalty compared to main memory accesses, or reads may be
 significantly slower than writes or vice versa. Other I/O methods may
 be more efficient in this case.</para>
 	</listitem>
       </varlistentry>
       <varlistentry>
 	<term><parameter>flags</parameter></term>
 	<listitem>
 	  <para>The <parameter>flags</parameter> parameter
 specifies the type of the mapped object, mapping options and whether
 modifications made to the mapped copy of the page are private to the
 process or are to be shared with other references.</para>
 	  <para><constant>MAP_FIXED</constant> requests that the
 driver selects no other address than the one specified. If the
 specified address cannot be used, <function>mmap()</function> will fail. If
 <constant>MAP_FIXED</constant> is specified,
 <parameter>start</parameter> must be a multiple of the pagesize. Use
 of this option is discouraged.</para>
 	  <para>One of the <constant>MAP_SHARED</constant> or
 <constant>MAP_PRIVATE</constant> flags must be set.
 <constant>MAP_SHARED</constant> allows applications to share the
 mapped memory with other (&eg; child-) processes. Note the Linux
 <filename>video-buf</filename> module which is used by the bttv,
 saa7134, saa7146, cx88 and vivi driver supports only
 <constant>MAP_SHARED</constant>. <constant>MAP_PRIVATE</constant>
 requests copy-on-write semantics. V4L2 applications should not set the
 <constant>MAP_PRIVATE</constant>, <constant>MAP_DENYWRITE</constant>,
 <constant>MAP_EXECUTABLE</constant> or <constant>MAP_ANON</constant>
 flag.</para>
 	</listitem>
       </varlistentry>
       <varlistentry>
 	<term><parameter>fd</parameter></term>
 	<listitem>
 	  <para>&fd;</para>
 	</listitem>
       </varlistentry>
       <varlistentry>
 	<term><parameter>offset</parameter></term>
 	<listitem>
 	  <para>Offset of the buffer in device memory. This must be the
 same value as returned by the driver in the &v4l2-buffer;
-<structfield>m</structfield> union <structfield>offset</structfield> field.</para>
+<structfield>m</structfield> union <structfield>offset</structfield> field for
+the single-planar API, and the same value as returned by the driver
+in the &v4l2-plane; <structfield>m</structfield> union
+<structfield>mem_offset</structfield> field for the multi-planar API.</para>
 	</listitem>
       </varlistentry>
     </variablelist>
   </refsect1>
   <refsect1>
     <title>Description</title>
     <para>The <function>mmap()</function> function asks to map
 <parameter>length</parameter> bytes starting at
 <parameter>offset</parameter> in the memory of the device specified by
 <parameter>fd</parameter> into the application address space,
 preferably at address <parameter>start</parameter>. This latter
 address is a hint only, and is usually specified as 0.</para>
     <para>Suitable length and offset parameters are queried with the
 &VIDIOC-QUERYBUF; ioctl. Buffers must be allocated with the
 &VIDIOC-REQBUFS; ioctl before they can be queried.</para>
     <para>To unmap buffers the &func-munmap; function is used.</para>
   </refsect1>
   <refsect1>
     <title>Return Value</title>
     <para>On success <function>mmap()</function> returns a pointer to
 the mapped buffer. On error <constant>MAP_FAILED</constant> (-1) is
 returned, and the <varname>errno</varname> variable is set
 appropriately. Possible error codes are:</para>
     <variablelist>
       <varlistentry>
 	<term><errorcode>EBADF</errorcode></term>
 	<listitem>
 	  <para><parameter>fd</parameter> is not a valid file
 descriptor.</para>
 	</listitem>
       </varlistentry>
       <varlistentry>
 	<term><errorcode>EACCES</errorcode></term>
 	<listitem>
 	  <para><parameter>fd</parameter> is
 not open for reading and writing.</para>
 	</listitem>
       </varlistentry>
       <varlistentry>
 	<term><errorcode>EINVAL</errorcode></term>
 	<listitem>
 	  <para>The <parameter>start</parameter> or
 <parameter>length</parameter> or <parameter>offset</parameter> are not
 suitable. (E.&nbsp;g. they are too large, or not aligned on a
 <constant>PAGESIZE</constant> boundary.)</para>
 	  <para>The <parameter>flags</parameter> or
 <parameter>prot</parameter> value is not supported.</para>
 	  <para>No buffers have been allocated with the
 &VIDIOC-REQBUFS; ioctl.</para>
 	</listitem>
       </varlistentry>
       <varlistentry>
 	<term><errorcode>ENOMEM</errorcode></term>
 	<listitem>
 	  <para>Not enough physical or virtual memory was available to
 complete the request.</para>
 	</listitem>
       </varlistentry>
     </variablelist>
   </refsect1>
 </refentry>
 <!--
 Local Variables:
 mode: sgml
 sgml-parent-document: "v4l2.sgml"
 indent-tabs-mode: nil
 End:
 -->

Documentation/DocBook/v4l/func-munmap.xml

Diff comments View file @ 53b5d57

 <refentry id="func-munmap">
   <refmeta>
     <refentrytitle>V4L2 munmap()</refentrytitle>
     &manvol;
   </refmeta>
   <refnamediv>
     <refname>v4l2-munmap</refname>
     <refpurpose>Unmap device memory</refpurpose>
   </refnamediv>
   <refsynopsisdiv>
     <funcsynopsis>
       <funcsynopsisinfo>
 #include &lt;unistd.h&gt;
 #include &lt;sys/mman.h&gt;</funcsynopsisinfo>
       <funcprototype>
 	<funcdef>int <function>munmap</function></funcdef>
 	<paramdef>void *<parameter>start</parameter></paramdef>
 	<paramdef>size_t <parameter>length</parameter></paramdef>
       </funcprototype>
     </funcsynopsis>
   </refsynopsisdiv>
   <refsect1>
     <title>Arguments</title>
     <variablelist>
       <varlistentry>
 	<term><parameter>start</parameter></term>
 	<listitem>
 	  <para>Address of the mapped buffer as returned by the
 &func-mmap; function.</para>
 	</listitem>
       </varlistentry>
       <varlistentry>
 	<term><parameter>length</parameter></term>
 	<listitem>
 	  <para>Length of the mapped buffer. This must be the same
 value as given to <function>mmap()</function> and returned by the
 driver in the &v4l2-buffer; <structfield>length</structfield>
-field.</para>
+field for the single-planar API and in the &v4l2-plane;
+<structfield>length</structfield> field for the multi-planar API.</para>
 	</listitem>
       </varlistentry>
     </variablelist>
   </refsect1>
   <refsect1>
     <title>Description</title>
     <para>Unmaps a previously with the &func-mmap; function mapped
 buffer and frees it, if possible. <!-- ? This function (not freeing)
 has no impact on I/O in progress, specifically it does not imply
 &VIDIOC-STREAMOFF; to terminate I/O. Unmapped buffers can still be
 enqueued, dequeued or queried, they are just not accessible by the
 application.--></para>
   </refsect1>
   <refsect1>
     <title>Return Value</title>
     <para>On success <function>munmap()</function> returns 0, on
 failure -1 and the <varname>errno</varname> variable is set
 appropriately:</para>
     <variablelist>
       <varlistentry>
 	<term><errorcode>EINVAL</errorcode></term>
 	<listitem>
 	  <para>The <parameter>start</parameter> or
 <parameter>length</parameter> is incorrect, or no buffers have been
 mapped yet.</para>
 	</listitem>
       </varlistentry>
     </variablelist>
   </refsect1>
 </refentry>
 <!--
 Local Variables:
 mode: sgml
 sgml-parent-document: "v4l2.sgml"
 indent-tabs-mode: nil
 End:
 -->

Documentation/DocBook/v4l/io.xml

Diff comments View file @ 53b5d57

   <title>Input/Output</title>
   <para>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.</para>
   <para>The classic I/O method using the <function>read()</function>
 and <function>write()</function> 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.</para>
   <para>Other methods must be negotiated. To select the streaming I/O
 method with memory mapped or user buffers applications call the
 &VIDIOC-REQBUFS; ioctl. The asynchronous I/O method is not defined
 yet.</para>
   <para>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 &VIDIOC-S-FMT; ioctl.
 For more information see <xref linkend="overlay" />.</para>
   <para>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 <xref linkend="open" />) and drivers permitting simultaneous video capturing
 and overlay using the same file descriptor, for compatibility with V4L
 and earlier versions of V4L2.</para>
   <para><constant>VIDIOC_S_FMT</constant> and
 <constant>VIDIOC_REQBUFS</constant> 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.</para>
   <para>The following sections describe the various I/O methods in
 more detail.</para>
   <section id="rw">
     <title>Read/Write</title>
     <para>Input and output devices support the
 <function>read()</function> and <function>write()</function> function,
 respectively, when the <constant>V4L2_CAP_READWRITE</constant> flag in
 the <structfield>capabilities</structfield> field of &v4l2-capability;
 returned by the &VIDIOC-QUERYCAP; ioctl is set.</para>
     <para>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 <application>vidctrl</application> tool is
 fictitious):</para>
     <informalexample>
       <screen>
 &gt; vidctrl /dev/video --input=0 --format=YUYV --size=352x288
 &gt; dd if=/dev/video of=myimage.422 bs=202752 count=1
 </screen>
     </informalexample>
     <para>To read from the device applications use the
 &func-read; function, to write the &func-write; function.
 Drivers must implement one I/O method if they
 exchange data with applications, but it need not be this.<footnote>
 	<para>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.</para>
       </footnote> When reading or writing is supported, the driver
 must also support the &func-select; and &func-poll;
 function.<footnote>
 	<para>At the driver level <function>select()</function> and
 <function>poll()</function> are the same, and
 <function>select()</function> is too important to be optional.</para>
       </footnote></para>
   </section>
   <section id="mmap">
     <title>Streaming I/O (Memory Mapping)</title>
     <para>Input and output devices support this I/O method when the
 <constant>V4L2_CAP_STREAMING</constant> flag in the
 <structfield>capabilities</structfield> field of &v4l2-capability;
 returned by the &VIDIOC-QUERYCAP; ioctl is set. There are two
 streaming methods, to determine if the memory mapping flavor is
 supported applications must call the &VIDIOC-REQBUFS; ioctl.</para>
     <para>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.</para>
     <para>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.<footnote>
 	<para>One could use one file descriptor and set the buffer
 type field accordingly when calling &VIDIOC-QBUF; etc., but it makes
 the <function>select()</function> 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.</para>
       </footnote></para>
     <para>To allocate device buffers applications call the
 &VIDIOC-REQBUFS; ioctl with the desired number of buffers and buffer
 type, for example <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>.
 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.</para>
     <para>Before applications can access the buffers they must map
 them into their address space with the &func-mmap; function. The
 location of the buffers in device memory can be determined with the
-&VIDIOC-QUERYBUF; ioctl. The <structfield>m.offset</structfield> and
+&VIDIOC-QUERYBUF; ioctl. In the single-planar API case, the
-<structfield>length</structfield> returned in a &v4l2-buffer; are
+<structfield>m.offset</structfield> and <structfield>length</structfield>
-passed as sixth and second parameter to the
+returned in a &v4l2-buffer; are passed as sixth and second parameter to the
-<function>mmap()</function> function. The offset and length values
+<function>mmap()</function> function. When using the multi-planar API,
-must not be modified. Remember the buffers are allocated in physical
+struct &v4l2-buffer; contains an array of &v4l2-plane; structures, each
-memory, as opposed to virtual memory which can be swapped out to disk.
+containing its own <structfield>m.offset</structfield> and
-Applications should free the buffers as soon as possible with the
+<structfield>length</structfield>. When using the multi-planar API, every
-&func-munmap; function.</para>
+plane of every buffer has to be mapped separately, so the number of
+calls to &func-mmap; should be equal to number of buffers times number of
+planes in each buffer. 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 &func-munmap; function.</para>
     <example>
-      <title>Mapping buffers</title>
+      <title>Mapping buffers in the single-planar API</title>
       <programlisting>
 &v4l2-requestbuffers; reqbuf;
 struct {
 	void *start;
 	size_t length;
 } *buffers;
 unsigned int i;
 memset(&amp;reqbuf, 0, sizeof(reqbuf));
 reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
 reqbuf.memory = V4L2_MEMORY_MMAP;
 reqbuf.count = 20;
 if (-1 == ioctl (fd, &VIDIOC-REQBUFS;, &amp;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 &lt; 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 &lt; reqbuf.count; i++) {
 	&v4l2-buffer; buffer;
 	memset(&amp;buffer, 0, sizeof(buffer));
 	buffer.type = reqbuf.type;
 	buffer.memory = V4L2_MEMORY_MMAP;
 	buffer.index = i;
 	if (-1 == ioctl (fd, &VIDIOC-QUERYBUF;, &amp;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, /* recommended */
 				MAP_SHARED,             /* recommended */
 				fd, buffer.m.offset);
 	if (MAP_FAILED == buffers[i].start) {
 		/* If you do not exit here you should unmap() and free()
 		   the buffers mapped so far. */
 		perror("mmap");
 		exit(EXIT_FAILURE);
 	}
 }
 /* Cleanup. */
 for (i = 0; i &lt; reqbuf.count; i++)
 	munmap(buffers[i].start, buffers[i].length);
       </programlisting>
     </example>
+    <example>
+      <title>Mapping buffers in the multi-planar API</title>
+      <programlisting>
+&v4l2-requestbuffers; reqbuf;
+/* Our current format uses 3 planes per buffer */
+#define FMT_NUM_PLANES = 3;
+struct {
+	void *start[FMT_NUM_PLANES];
+	size_t length[FMT_NUM_PLANES];
+} *buffers;
+unsigned int i, j;
+memset(&amp;reqbuf, 0, sizeof(reqbuf));
+reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE;
+reqbuf.memory = V4L2_MEMORY_MMAP;
+reqbuf.count = 20;
+if (ioctl(fd, &VIDIOC-REQBUFS;, &amp;reqbuf) &lt; 0) {
+	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 &lt; 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 &lt; reqbuf.count; i++) {
+	&v4l2-buffer; buffer;
+	&v4l2-plane; planes[FMT_NUM_PLANES];
+	memset(&amp;buffer, 0, sizeof(buffer));
+	buffer.type = reqbuf.type;
+	buffer.memory = V4L2_MEMORY_MMAP;
+	buffer.index = i;
+	/* length in struct v4l2_buffer in multi-planar API stores the size
+	 * of planes array. */
+	buffer.length = FMT_NUM_PLANES;
+	buffer.m.planes = planes;
+	if (ioctl(fd, &VIDIOC-QUERYBUF;, &amp;buffer) &lt; 0) {
+		perror("VIDIOC_QUERYBUF");
+		exit(EXIT_FAILURE);
+	}
+	/* Every plane has to be mapped separately */
+	for (j = 0; j &lt; FMT_NUM_PLANES; j++) {
+		buffers[i].length[j] = buffer.m.planes[j].length; /* remember for munmap() */
+		buffers[i].start[j] = mmap(NULL, buffer.m.planes[j].length,
+				 PROT_READ | PROT_WRITE, /* recommended */
+				 MAP_SHARED,             /* recommended */
+				 fd, buffer.m.planes[j].m.offset);
+		if (MAP_FAILED == buffers[i].start[j]) {
+			/* If you do not exit here you should unmap() and free()
+			   the buffers and planes mapped so far. */
+			perror("mmap");
+			exit(EXIT_FAILURE);
+		}
+	}
+}
+/* Cleanup. */
+for (i = 0; i &lt; reqbuf.count; i++)
+	for (j = 0; j &lt; FMT_NUM_PLANES; j++)
+		munmap(buffers[i].start[j], buffers[i].length[j]);
+      </programlisting>
+    </example>
     <para>Conceptually 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.</para>
     <para>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 <emphasis>fill</emphasis> enqueued
 <emphasis>empty</emphasis> buffers in any order. <footnote>
 	<para>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.</para>
       </footnote> The index number of a buffer (&v4l2-buffer;
 <structfield>index</structfield>) plays no role here, it only
 identifies the buffer.</para>
     <para>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
 <constant>VIDIOC_STREAMON</constant>. In the write loop, when
 the application runs out of free buffers, it must wait until an empty
 buffer can be dequeued and reused.</para>
     <para>To enqueue and dequeue a buffer applications use the
 &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl. The status of a buffer being
 mapped, enqueued, full or empty can be determined at any time using the
 &VIDIOC-QUERYBUF; ioctl. Two methods exist to suspend execution of the
 application until one or more buffers can be dequeued. By default
 <constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the
 outgoing queue. When the <constant>O_NONBLOCK</constant> flag was
 given to the &func-open; function, <constant>VIDIOC_DQBUF</constant>
 returns immediately with an &EAGAIN; when no buffer is available. The
 &func-select; or &func-poll; function are always available.</para>
     <para>To start and stop capturing or output applications call the
 &VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctl. Note
 <constant>VIDIOC_STREAMOFF</constant> 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 &v4l2-buffer;
 <structfield>timestamp</structfield> of captured buffers, or set the
 field before enqueuing buffers for output.</para>
     <para>Drivers implementing memory mapping I/O must
 support the <constant>VIDIOC_REQBUFS</constant>,
 <constant>VIDIOC_QUERYBUF</constant>,
 <constant>VIDIOC_QBUF</constant>, <constant>VIDIOC_DQBUF</constant>,
 <constant>VIDIOC_STREAMON</constant> and
 <constant>VIDIOC_STREAMOFF</constant> ioctl, the
 <function>mmap()</function>, <function>munmap()</function>,
 <function>select()</function> and <function>poll()</function>
 function.<footnote>
 	<para>At the driver level <function>select()</function> and
 <function>poll()</function> are the same, and
 <function>select()</function> is too important to be optional. The
 rest should be evident.</para>
       </footnote></para>
     <para>[capture example]</para>
   </section>
   <section id="userp">
     <title>Streaming I/O (User Pointers)</title>
     <para>Input and output devices support this I/O method when the
 <constant>V4L2_CAP_STREAMING</constant> flag in the
 <structfield>capabilities</structfield> field of &v4l2-capability;
 returned by the &VIDIOC-QUERYCAP; ioctl is set. If the particular user
 pointer method (not only memory mapping) is supported must be
 determined by calling the &VIDIOC-REQBUFS; ioctl.</para>
     <para>This I/O method combines advantages of the read/write and
-memory mapping methods. Buffers are allocated by the application
+memory mapping methods. Buffers (planes) 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 &v4l2-buffer;. The driver must be switched
+are passed in &v4l2-buffer; (or in &v4l2-plane; in the multi-planar API case).
-into user pointer I/O mode by calling the &VIDIOC-REQBUFS; with the
+The driver must be switched into user pointer I/O mode by calling the
-desired buffer type. No buffers are allocated beforehands,
+&VIDIOC-REQBUFS; with the desired buffer type. No buffers (planes) are allocated
-consequently they are not indexed and cannot be queried like mapped
+beforehand, consequently they are not indexed and cannot be queried like mapped
 buffers with the <constant>VIDIOC_QUERYBUF</constant> ioctl.</para>
     <example>
       <title>Initiating streaming I/O with user pointers</title>
       <programlisting>
 &v4l2-requestbuffers; reqbuf;
 memset (&amp;reqbuf, 0, sizeof (reqbuf));
 reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
 reqbuf.memory = V4L2_MEMORY_USERPTR;
 if (ioctl (fd, &VIDIOC-REQBUFS;, &amp;reqbuf) == -1) {
 	if (errno == EINVAL)
 		printf ("Video capturing or user pointer streaming is not supported\n");
 	else
 		perror ("VIDIOC_REQBUFS");
 	exit (EXIT_FAILURE);
 }
       </programlisting>
     </example>
-    <para>Buffer addresses and sizes are passed on the fly with the
+    <para>Buffer (plane) addresses and sizes are passed on the fly with the
 &VIDIOC-QBUF; ioctl. Although buffers are commonly cycled,
 applications can pass different addresses and sizes at each
 <constant>VIDIOC_QBUF</constant> 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.<footnote>
 	<para>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.</para>
       </footnote></para>
     <para>Filled or displayed buffers are dequeued with the
 &VIDIOC-DQBUF; 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 &VIDIOC-STREAMOFF; is called, &VIDIOC-REQBUFS;, 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.</para>
     <para>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
 <constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the
 outgoing queue. When the <constant>O_NONBLOCK</constant> flag was
 given to the &func-open; function, <constant>VIDIOC_DQBUF</constant>
 returns immediately with an &EAGAIN; when no buffer is available. The
 &func-select; or &func-poll; function are always available.</para>
     <para>To start and stop capturing or output applications call the
 &VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctl. Note
 <constant>VIDIOC_STREAMOFF</constant> 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 &v4l2-buffer; <structfield>timestamp</structfield> of captured
 buffers, or set the field before enqueuing buffers for output.</para>
     <para>Drivers implementing user pointer I/O must
 support the <constant>VIDIOC_REQBUFS</constant>,
 <constant>VIDIOC_QBUF</constant>, <constant>VIDIOC_DQBUF</constant>,
 <constant>VIDIOC_STREAMON</constant> and
 <constant>VIDIOC_STREAMOFF</constant> ioctl, the
 <function>select()</function> and <function>poll()</function> function.<footnote>
 	<para>At the driver level <function>select()</function> and
 <function>poll()</function> are the same, and
 <function>select()</function> is too important to be optional. The
 rest should be evident.</para>
       </footnote></para>
   </section>
   <section id="async">
     <title>Asynchronous I/O</title>
     <para>This method is not defined yet.</para>
   </section>
   <section id="buffer">
     <title>Buffers</title>
     <para>A buffer contains data exchanged by application and
-driver using one of the Streaming I/O methods. Only pointers to
+driver using one of the Streaming I/O methods. In the multi-planar API, the
-buffers are exchanged, the data itself is not copied. These pointers,
+data is held in planes, while the buffer structure acts as a container
-together with meta-information like timestamps or field parity, are
+for the planes. Only pointers to buffers (planes) are exchanged, the data
-stored in a struct <structname>v4l2_buffer</structname>, argument to
+itself is not copied. These pointers, together with meta-information like
-the &VIDIOC-QUERYBUF;, &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl.</para>
+timestamps or field parity, are stored in a struct
+<structname>v4l2_buffer</structname>, argument to
+the &VIDIOC-QUERYBUF;, &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl.
+In the multi-planar API, some plane-specific members of struct
+<structname>v4l2_buffer</structname>, such as pointers and sizes for each
+plane, are stored in struct <structname>v4l2_plane</structname> instead.
+In that case, struct <structname>v4l2_buffer</structname> contains an array of
+plane structures.</para>
       <para>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 <xref
 linkend="standard" />.</para>
       <para>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.</para>
       <para>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. <footnote>
 	  <para>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.</para>
 	</footnote></para>
     <table frame="none" pgwide="1" id="v4l2-buffer">
       <title>struct <structname>v4l2_buffer</structname></title>
       <tgroup cols="4">
 	&cs-ustr;
 	<tbody valign="top">
 	  <row>
 	    <entry>__u32</entry>
 	    <entry><structfield>index</structfield></entry>
 	    <entry></entry>
 	    <entry>Number of the buffer, set by the application. This
 field is only used for <link linkend="mmap">memory mapping</link> I/O
 and can range from zero to the number of buffers allocated
 with the &VIDIOC-REQBUFS; ioctl (&v4l2-requestbuffers; <structfield>count</structfield>) minus one.</entry>
 	  </row>
 	  <row>
 	    <entry>&v4l2-buf-type;</entry>
 	    <entry><structfield>type</structfield></entry>
 	    <entry></entry>
 	    <entry>Type of the buffer, same as &v4l2-format;
 <structfield>type</structfield> or &v4l2-requestbuffers;
 <structfield>type</structfield>, set by the application.</entry>
 	  </row>
 	  <row>
 	    <entry>__u32</entry>
 	    <entry><structfield>bytesused</structfield></entry>
 	    <entry></entry>
 	    <entry>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 <structfield>type</structfield>
 refers to an input stream, applications when an output stream.</entry>
 	  </row>
 	  <row>
 	    <entry>__u32</entry>
 	    <entry><structfield>flags</structfield></entry>
 	    <entry></entry>
 	    <entry>Flags set by the application or driver, see <xref
 linkend="buffer-flags" />.</entry>
 	  </row>
 	  <row>
 	    <entry>&v4l2-field;</entry>
 	    <entry><structfield>field</structfield></entry>
 	    <entry></entry>
 	    <entry>Indicates the field order of the image in the
 buffer, see <xref linkend="v4l2-field" />. This field is not used when
 the buffer contains VBI data. Drivers must set it when
 <structfield>type</structfield> refers to an input stream,
 applications when an output stream.</entry>
 	  </row>
 	  <row>
 	    <entry>struct timeval</entry>
 	    <entry><structfield>timestamp</structfield></entry>
 	    <entry></entry>
 	    <entry><para>For input streams this is the
 system time (as returned by the <function>gettimeofday()</function>
 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
 <structfield>timestamp</structfield> field. This permits
 applications to monitor the drift between the video and system
 clock.</para></entry>
 	  </row>
 	  <row>
 	    <entry>&v4l2-timecode;</entry>
 	    <entry><structfield>timecode</structfield></entry>
 	    <entry></entry>
 	    <entry>When <structfield>type</structfield> is
 <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> and the
 <constant>V4L2_BUF_FLAG_TIMECODE</constant> flag is set in
 <structfield>flags</structfield>, this structure contains a frame
 timecode. In <link linkend="v4l2-field">V4L2_FIELD_ALTERNATE</link>
 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 <structfield>timestamp</structfield> and
 <structfield>sequence</structfield> fields.</entry>
 	  </row>
 	  <row>
 	    <entry>__u32</entry>
 	    <entry><structfield>sequence</structfield></entry>
 	    <entry></entry>
 	    <entry>Set by the driver, counting the frames in the
 sequence.</entry>
 	  </row>
 	  <row>
 	    <entry spanname="hspan"><para>In <link
 linkend="v4l2-field">V4L2_FIELD_ALTERNATE</link> 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.</para><para>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 <xref linkend="standard" />.</para></entry>
 	  </row>
 	  <row>
 	    <entry>&v4l2-memory;</entry>
 	    <entry><structfield>memory</structfield></entry>
 	    <entry></entry>
 	    <entry>This field must be set by applications and/or drivers
 in accordance with the selected I/O method.</entry>
 	  </row>
 	  <row>
 	    <entry>union</entry>
 	    <entry><structfield>m</structfield></entry>
 	  </row>
 	  <row>
 	    <entry></entry>
 	    <entry>__u32</entry>
 	    <entry><structfield>offset</structfield></entry>
-	    <entry>When <structfield>memory</structfield> is
+	    <entry>For the single-planar API and when
-<constant>V4L2_MEMORY_MMAP</constant> this is the offset of the buffer
+<structfield>memory</structfield> is <constant>V4L2_MEMORY_MMAP</constant> this
-from the start of the device memory. The value is returned by the
+is the offset of the buffer from the start of the device memory. The value is
-driver and apart of serving as parameter to the &func-mmap; function
+returned by the driver and apart of serving as parameter to the &func-mmap;
-not useful for applications. See <xref linkend="mmap" /> for details.</entry>
+function not useful for applications. See <xref linkend="mmap" /> for details
+	  </entry>
 	  </row>
 	  <row>
 	    <entry></entry>
 	    <entry>unsigned long</entry>
 	    <entry><structfield>userptr</structfield></entry>
-	    <entry>When <structfield>memory</structfield> is
+	    <entry>For the single-planar API and when
-<constant>V4L2_MEMORY_USERPTR</constant> this is a pointer to the
+<structfield>memory</structfield> is <constant>V4L2_MEMORY_USERPTR</constant>
-buffer (casted to unsigned long type) in virtual memory, set by the
+this is a pointer to the buffer (casted to unsigned long type) in virtual
-application. See <xref linkend="userp" /> for details.</entry>
+memory, set by the application. See <xref linkend="userp" /> for details.
+	    </entry>
 	  </row>
 	  <row>
+	    <entry></entry>
+	    <entry>struct v4l2_plane</entry>
+	    <entry><structfield>*planes</structfield></entry>
+	    <entry>When using the multi-planar API, contains a userspace pointer
+	    to an array of &v4l2-plane;. The size of the array should be put
+	    in the <structfield>length</structfield> field of this
+	    <structname>v4l2_buffer</structname> structure.</entry>
+	  </row>
+	  <row>
 	    <entry>__u32</entry>
 	    <entry><structfield>length</structfield></entry>
 	    <entry></entry>
-	    <entry>Size of the buffer (not the payload) in bytes.</entry>
+	    <entry>Size of the buffer (not the payload) in bytes for the
+	    single-planar API. For the multi-planar API should contain the
+	    number of elements in the <structfield>planes</structfield> array.
+	    </entry>
 	  </row>
 	  <row>
 	    <entry>__u32</entry>
 	    <entry><structfield>input</structfield></entry>
 	    <entry></entry>
 	    <entry>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
 <constant>V4L2_BUF_FLAG_INPUT</constant> flag, and this field to the
 number of a video input as in &v4l2-input; field
 <structfield>index</structfield>.</entry>
 	  </row>
 	  <row>
 	    <entry>__u32</entry>
 	    <entry><structfield>reserved</structfield></entry>
 	    <entry></entry>
 	    <entry>A place holder for future extensions and custom
 (driver defined) buffer types
 <constant>V4L2_BUF_TYPE_PRIVATE</constant> and higher. Applications
 should set this to 0.</entry>
 	  </row>
 	</tbody>
       </tgroup>
     </table>
+    <table frame="none" pgwide="1" id="v4l2-plane">
+      <title>struct <structname>v4l2_plane</structname></title>
+      <tgroup cols="4">
+        &cs-ustr;
+	<tbody valign="top">
+	  <row>
+	    <entry>__u32</entry>
+	    <entry><structfield>bytesused</structfield></entry>
+	    <entry></entry>
+	    <entry>The number of bytes occupied by data in the plane
+	    (its payload).</entry>
+	  </row>
+	  <row>
+	    <entry>__u32</entry>
+	    <entry><structfield>length</structfield></entry>
+	    <entry></entry>
+	    <entry>Size in bytes of the plane (not its payload).</entry>
+	  </row>
+	  <row>
+	    <entry>union</entry>
+	    <entry><structfield>m</structfield></entry>
+	    <entry></entry>
+	    <entry></entry>
+	  </row>
+	  <row>
+	    <entry></entry>
+	    <entry>__u32</entry>
+	    <entry><structfield>mem_offset</structfield></entry>
+	    <entry>When the memory type in the containing &v4l2-buffer; is
+	      <constant>V4L2_MEMORY_MMAP</constant>, this is the value that
+	      should be passed to &func-mmap;, similar to the
+	      <structfield>offset</structfield> field in &v4l2-buffer;.</entry>
+	  </row>
+	  <row>
+	    <entry></entry>
+	    <entry>__unsigned long</entry>
+	    <entry><structfield>userptr</structfield></entry>
+	    <entry>When the memory type in the containing &v4l2-buffer; is
+	      <constant>V4L2_MEMORY_USERPTR</constant>, this is a userspace
+	      pointer to the memory allocated for this plane by an application.
+	      </entry>
+	  </row>
+	  <row>
+	    <entry>__u32</entry>
+	    <entry><structfield>data_offset</structfield></entry>
+	    <entry></entry>
+	    <entry>Offset in bytes to video data in the plane, if applicable.
+	    </entry>
+	  </row>
+	  <row>
+	    <entry>__u32</entry>
+	    <entry><structfield>reserved[11]</structfield></entry>
+	    <entry></entry>
+	    <entry>Reserved for future use. Should be zeroed by an
+	    application.</entry>
+	  </row>
+	</tbody>
+      </tgroup>
+    </table>
     <table frame="none" pgwide="1" id="v4l2-buf-type">
       <title>enum v4l2_buf_type</title>
       <tgroup cols="3">
 	&cs-def;
 	<tbody valign="top">
 	  <row>
 	    <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant></entry>
 	    <entry>1</entry>
-	    <entry>Buffer of a video capture stream, see <xref
+	    <entry>Buffer of a single-planar video capture stream, see <xref
 		linkend="capture" />.</entry>
 	  </row>
 	  <row>
+	    <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant>
+	    </entry>
+	    <entry>9</entry>
+	    <entry>Buffer of a multi-planar video capture stream, see <xref
+		linkend="capture" />.</entry>
+	  </row>
+	  <row>
 	    <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant></entry>
 	    <entry>2</entry>
-	    <entry>Buffer of a video output stream, see <xref
+	    <entry>Buffer of a single-planar video output stream, see <xref
+		linkend="output" />.</entry>
+	  </row>
+	  <row>
+	    <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>
+	    </entry>
+	    <entry>10</entry>
+	    <entry>Buffer of a multi-planar video output stream, see <xref
 		linkend="output" />.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant></entry>
 	    <entry>3</entry>
 	    <entry>Buffer for video overlay, see <xref linkend="overlay" />.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_BUF_TYPE_VBI_CAPTURE</constant></entry>
 	    <entry>4</entry>
 	    <entry>Buffer of a raw VBI capture stream, see <xref
 		linkend="raw-vbi" />.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant></entry>
 	    <entry>5</entry>
 	    <entry>Buffer of a raw VBI output stream, see <xref
 		linkend="raw-vbi" />.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant></entry>
 	    <entry>6</entry>
 	    <entry>Buffer of a sliced VBI capture stream, see <xref
 		linkend="sliced" />.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant></entry>
 	    <entry>7</entry>
 	    <entry>Buffer of a sliced VBI output stream, see <xref
 		linkend="sliced" />.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant></entry>
 	    <entry>8</entry>
 	    <entry>Buffer for video output overlay (OSD), see <xref
 		linkend="osd" />. Status: <link
 linkend="experimental">Experimental</link>.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_BUF_TYPE_PRIVATE</constant></entry>
 	    <entry>0x80</entry>
 	  <entry>This and higher values are reserved for custom
 (driver defined) buffer types.</entry>
 	  </row>
 	</tbody>
       </tgroup>
     </table>
     <table frame="none" pgwide="1" id="buffer-flags">
       <title>Buffer Flags</title>
       <tgroup cols="3">
 	&cs-def;
 	<tbody valign="top">
 	  <row>
 	    <entry><constant>V4L2_BUF_FLAG_MAPPED</constant></entry>
 	    <entry>0x0001</entry>
 	    <entry>The buffer resides in device memory and has been mapped
 into the application's address space, see <xref linkend="mmap" /> for details.
 Drivers set or clear this flag when the
 <link linkend="vidioc-querybuf">VIDIOC_QUERYBUF</link>, <link
 	  linkend="vidioc-qbuf">VIDIOC_QBUF</link> or <link
 	  linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl is called. Set by the driver.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_BUF_FLAG_QUEUED</constant></entry>
 	    <entry>0x0002</entry>
 	  <entry>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
 <constant>VIDIOC_QUERYBUF</constant> ioctl is called. After
 (successful) calling the <constant>VIDIOC_QBUF </constant>ioctl it is
 always set and after <constant>VIDIOC_DQBUF</constant> always
 cleared.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_BUF_FLAG_DONE</constant></entry>
 	    <entry>0x0004</entry>
 	    <entry>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 <constant>VIDIOC_QUERYBUF</constant> ioctl
 is called. After calling the <constant>VIDIOC_QBUF</constant> or
 <constant>VIDIOC_DQBUF</constant> it is always cleared. Of course a
 buffer cannot be on both queues at the same time, the
 <constant>V4L2_BUF_FLAG_QUEUED</constant> and
 <constant>V4L2_BUF_FLAG_DONE</constant> flag are mutually exclusive.
 They can be both cleared however, then the buffer is in "dequeued"
 state, in the application domain to say so.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_BUF_FLAG_ERROR</constant></entry>
 	    <entry>0x0040</entry>
 	    <entry>When this flag is set, the buffer has been dequeued
 	    successfully, although the data might have been corrupted.
 	    This is recoverable, streaming may continue as normal and
 	    the buffer may be reused normally.
 	    Drivers set this flag when the <constant>VIDIOC_DQBUF</constant>
 	    ioctl is called.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_BUF_FLAG_KEYFRAME</constant></entry>
 	    <entry>0x0008</entry>
 	  <entry>Drivers set or clear this flag when calling the
 <constant>VIDIOC_DQBUF</constant> ioctl. It may be set by video
 capture devices when the buffer contains a compressed image which is a
 key frame (or field), &ie; can be decompressed on its own.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_BUF_FLAG_PFRAME</constant></entry>
 	    <entry>0x0010</entry>
 	    <entry>Similar to <constant>V4L2_BUF_FLAG_KEYFRAME</constant>
 this flags predicted frames or fields which contain only differences to a
 previous key frame.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_BUF_FLAG_BFRAME</constant></entry>
 	    <entry>0x0020</entry>
 	    <entry>Similar to <constant>V4L2_BUF_FLAG_PFRAME</constant>
 	this is a bidirectional predicted frame or field. [ooc tbd]</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_BUF_FLAG_TIMECODE</constant></entry>
 	    <entry>0x0100</entry>
 	    <entry>The <structfield>timecode</structfield> field is valid.
 Drivers set or clear this flag when the <constant>VIDIOC_DQBUF</constant>
 ioctl is called.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_BUF_FLAG_INPUT</constant></entry>
 	    <entry>0x0200</entry>
 	    <entry>The <structfield>input</structfield> field is valid.
 Applications set or clear this flag before calling the
 <constant>VIDIOC_QBUF</constant> ioctl.</entry>
 	  </row>
 	</tbody>
       </tgroup>
     </table>
     <table pgwide="1" frame="none" id="v4l2-memory">
       <title>enum v4l2_memory</title>
       <tgroup cols="3">
 	&cs-def;
 	<tbody valign="top">
 	  <row>
 	    <entry><constant>V4L2_MEMORY_MMAP</constant></entry>
 	    <entry>1</entry>
 	    <entry>The buffer is used for <link linkend="mmap">memory
 mapping</link> I/O.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_MEMORY_USERPTR</constant></entry>
 	    <entry>2</entry>
 	    <entry>The buffer is used for <link linkend="userp">user
 pointer</link> I/O.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_MEMORY_OVERLAY</constant></entry>
 	    <entry>3</entry>
 	    <entry>[to do]</entry>
 	  </row>
 	</tbody>
       </tgroup>
     </table>
     <section>
       <title>Timecodes</title>
       <para>The <structname>v4l2_timecode</structname> structure is
 designed to hold a <xref linkend="smpte12m" /> or similar timecode.
 (struct <structname>timeval</structname> timestamps are stored in
 &v4l2-buffer; field <structfield>timestamp</structfield>.)</para>
       <table frame="none" pgwide="1" id="v4l2-timecode">
 	<title>struct <structname>v4l2_timecode</structname></title>
 	<tgroup cols="3">
 	  &cs-str;
 	  <tbody valign="top">
 	    <row>
 	      <entry>__u32</entry>
 	      <entry><structfield>type</structfield></entry>
 	      <entry>Frame rate the timecodes are based on, see <xref
 		  linkend="timecode-type" />.</entry>
 	    </row>
 	    <row>
 	      <entry>__u32</entry>
 	      <entry><structfield>flags</structfield></entry>
 	      <entry>Timecode flags, see <xref linkend="timecode-flags" />.</entry>
 	    </row>
 	    <row>
 	      <entry>__u8</entry>
 	      <entry><structfield>frames</structfield></entry>
 	      <entry>Frame count, 0 ... 23/24/29/49/59, depending on the
 	    type of timecode.</entry>
 	    </row>
 	    <row>
 	      <entry>__u8</entry>
 	      <entry><structfield>seconds</structfield></entry>
 	      <entry>Seconds count, 0 ... 59. This is a binary, not BCD number.</entry>
 	    </row>
 	    <row>
 	      <entry>__u8</entry>
 	      <entry><structfield>minutes</structfield></entry>
 	      <entry>Minutes count, 0 ... 59. This is a binary, not BCD number.</entry>
 	    </row>
 	    <row>
 	      <entry>__u8</entry>
 	      <entry><structfield>hours</structfield></entry>
 	      <entry>Hours count, 0 ... 29. This is a binary, not BCD number.</entry>
 	    </row>
 	    <row>
 	      <entry>__u8</entry>
 	      <entry><structfield>userbits</structfield>[4]</entry>
 	      <entry>The "user group" bits from the timecode.</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </table>
       <table frame="none" pgwide="1" id="timecode-type">
 	<title>Timecode Types</title>
 	<tgroup cols="3">
 	&cs-def;
 	  <tbody valign="top">
 	    <row>
 	      <entry><constant>V4L2_TC_TYPE_24FPS</constant></entry>
 	      <entry>1</entry>
 	      <entry>24 frames per second, i.&nbsp;e. film.</entry>
 	    </row>
 	    <row>
 	      <entry><constant>V4L2_TC_TYPE_25FPS</constant></entry>
 	      <entry>2</entry>
 	      <entry>25 frames per second, &ie; PAL or SECAM video.</entry>
 	    </row>
 	    <row>
 	      <entry><constant>V4L2_TC_TYPE_30FPS</constant></entry>
 	      <entry>3</entry>
 	      <entry>30 frames per second, &ie; NTSC video.</entry>
 	    </row>
 	    <row>
 	      <entry><constant>V4L2_TC_TYPE_50FPS</constant></entry>
 	      <entry>4</entry>
 	      <entry></entry>
 	    </row>
 	    <row>
 	      <entry><constant>V4L2_TC_TYPE_60FPS</constant></entry>
 	      <entry>5</entry>
 	      <entry></entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </table>
       <table frame="none" pgwide="1" id="timecode-flags">
 	<title>Timecode Flags</title>
 	<tgroup cols="3">
 	&cs-def;
 	  <tbody valign="top">
 	    <row>
 	      <entry><constant>V4L2_TC_FLAG_DROPFRAME</constant></entry>
 	      <entry>0x0001</entry>
 	      <entry>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.</entry>
 	    </row>
 	    <row>
 	      <entry><constant>V4L2_TC_FLAG_COLORFRAME</constant></entry>
 	      <entry>0x0002</entry>
 	      <entry>The "color frame" flag.</entry>
 	    </row>
 	    <row>
 	      <entry><constant>V4L2_TC_USERBITS_field</constant></entry>
 	      <entry>0x000C</entry>
 	      <entry>Field mask for the "binary group flags".</entry>
 	    </row>
 	    <row>
 	      <entry><constant>V4L2_TC_USERBITS_USERDEFINED</constant></entry>
 	      <entry>0x0000</entry>
 	      <entry>Unspecified format.</entry>
 	    </row>
 	    <row>
 	      <entry><constant>V4L2_TC_USERBITS_8BITCHARS</constant></entry>
 	      <entry>0x0008</entry>
 	      <entry>8-bit ISO characters.</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </table>
     </section>
   </section>
   <section id="field-order">
     <title>Field Order</title>
     <para>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.</para>
     <para>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 <emphasis>temporal
 order</emphasis>.</para>
     <para>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 (aka odd) and
 bottom (aka even) fields, the <emphasis>spatial order</emphasis>: 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.</para>
     <para>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, &eg; when transferring film to video, two fields may come from
 the same frame, creating a natural order.</para>
     <para>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.</para>
     <para>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
 <structfield>field</structfield> field of &v4l2-pix-format; before
 calling the &VIDIOC-S-FMT; ioctl. If this is not desired it should
 have the value <constant>V4L2_FIELD_ANY</constant> (0).</para>
     <table frame="none" pgwide="1" id="v4l2-field">
       <title>enum v4l2_field</title>
       <tgroup cols="3">
 	&cs-def;
 	<tbody valign="top">
 	  <row>
 	    <entry><constant>V4L2_FIELD_ANY</constant></entry>
 	    <entry>0</entry>
 	    <entry>Applications request this field order when any
 one of the <constant>V4L2_FIELD_NONE</constant>,
 <constant>V4L2_FIELD_TOP</constant>,
 <constant>V4L2_FIELD_BOTTOM</constant>, or
 <constant>V4L2_FIELD_INTERLACED</constant> formats is acceptable.
 Drivers choose depending on hardware capabilities or e.&nbsp;g. the
 requested image size, and return the actual field order. &v4l2-buffer;
 <structfield>field</structfield> can never be
 <constant>V4L2_FIELD_ANY</constant>.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_FIELD_NONE</constant></entry>
 	    <entry>1</entry>
 	    <entry>Images are in progressive format, not interlaced.
 The driver may also indicate this order when it cannot distinguish
 between <constant>V4L2_FIELD_TOP</constant> and
 <constant>V4L2_FIELD_BOTTOM</constant>.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_FIELD_TOP</constant></entry>
 	    <entry>2</entry>
 	    <entry>Images consist of the top (aka odd) field only.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_FIELD_BOTTOM</constant></entry>
 	    <entry>3</entry>
 	    <entry>Images consist of the bottom (aka even) field only.
 Applications may wish to prevent a device from capturing interlaced
 images because they will have "comb" or "feathering" artefacts around
 moving objects.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_FIELD_INTERLACED</constant></entry>
 	    <entry>4</entry>
 	    <entry>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.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_FIELD_SEQ_TB</constant></entry>
 	    <entry>5</entry>
 	    <entry>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.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_FIELD_SEQ_BT</constant></entry>
 	    <entry>6</entry>
 	    <entry>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.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_FIELD_ALTERNATE</constant></entry>
 	    <entry>7</entry>
 	    <entry>The two fields of a frame are passed in separate
 buffers, in temporal order, &ie; 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 &v4l2-buffer;
 <structfield>field</structfield> to
 <constant>V4L2_FIELD_TOP</constant> or
 <constant>V4L2_FIELD_BOTTOM</constant>. 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 &v4l2-buffer; <structfield>sequence</structfield> field. Image
 sizes refer to the frame, not fields. This format cannot be selected
 when using the read/write I/O method.<!-- Where it's indistinguishable
 from V4L2_FIELD_SEQ_*. --></entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_FIELD_INTERLACED_TB</constant></entry>
 	    <entry>8</entry>
 	    <entry>Images contain both fields, interleaved line by
 line, top field first. The top field is transmitted first.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_FIELD_INTERLACED_BT</constant></entry>
 	    <entry>9</entry>
 	    <entry>Images contain both fields, interleaved line by
 line, top field first. The bottom field is transmitted first.</entry>
 	  </row>
 	</tbody>
       </tgroup>
     </table>
     <figure id="fieldseq-tb">
 	<title>Field Order, Top Field First Transmitted</title>
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="fieldseq_tb.pdf" format="PS" />
 	  </imageobject>
 	  <imageobject>
 	    <imagedata fileref="fieldseq_tb.gif" format="GIF" />
 	  </imageobject>
 	</mediaobject>
     </figure>
     <figure id="fieldseq-bt">
 	<title>Field Order, Bottom Field First Transmitted</title>
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="fieldseq_bt.pdf" format="PS" />
 	  </imageobject>
 	  <imageobject>
 	    <imagedata fileref="fieldseq_bt.gif" format="GIF" />
 	  </imageobject>
 	</mediaobject>
     </figure>
   </section>
   <!--
 Local Variables:
 mode: sgml
 sgml-parent-document: "v4l2.sgml"
 indent-tabs-mode: nil
 End:
   -->

Documentation/DocBook/v4l/pixfmt.xml

Diff comments View file @ 53b5d57

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

Documentation/DocBook/v4l/planar-apis.xml

Diff comments View file @ 53b5d57

File was created	1	<section id="planar-apis">
	2	<title>Single- and multi-planar APIs</title>
	3
	4	<para>Some devices require data for each input or output video frame
	5	to be placed in discontiguous memory buffers. In such cases one
	6	video frame has to be addressed using more than one memory address, i.e. one
	7	pointer per "plane". A plane is a sub-buffer of current frame. For examples
	8	of such formats see <xref linkend="pixfmt" />.</para>
	9
	10	<para>Initially, V4L2 API did not support multi-planar buffers and a set of
	11	extensions has been introduced to handle them. Those extensions constitute
	12	what is being referred to as the "multi-planar API".</para>
	13
	14	<para>Some of the V4L2 API calls and structures are interpreted differently,
	15	depending on whether single- or multi-planar API is being used. An application
	16	can choose whether to use one or the other by passing a corresponding buffer
	17	type to its ioctl calls. Multi-planar versions of buffer types are suffixed with
	18	an `_MPLANE' string. For a list of available multi-planar buffer types
	19	see &v4l2-buf-type;.
	20	</para>
	21
	22	<section>
	23	<title>Multi-planar formats</title>
	24	<para>Multi-planar API introduces new multi-planar formats. Those formats
	25	use a separate set of FourCC codes. It is important to distinguish between
	26	the multi-planar API and a multi-planar format. Multi-planar API calls can
	27	handle all single-planar formats as well, while the single-planar API cannot
	28	handle multi-planar formats. Applications do not have to switch between APIs
	29	when handling both single- and multi-planar devices and should use the
	30	multi-planar API version for both single- and multi-planar formats.
	31	Drivers that do not support multi-planar API can still be handled with it,
	32	utilizing a compatibility layer built into standard V4L2 ioctl handling.
	33	</para>
	34	</section>
	35
	36	<section>
	37	<title>Single and multi-planar API compatibility layer</title>
	38	<para>In most cases<footnote><para>The compatibility layer does not cover
	39	drivers that do not use video_ioctl2() call.</para></footnote>, applications
	40	can use the multi-planar API with older drivers that support
	41	only its single-planar version and vice versa. Appropriate conversion is
	42	done seamlessly for both applications and drivers in the V4L2 core. The
	43	general rule of thumb is: as long as an application uses formats that
	44	a driver supports, it can use either API (although use of multi-planar
	45	formats is only possible with the multi-planar API). The list of formats
	46	supported by a driver can be obtained using the &VIDIOC-ENUM-FMT; call.
	47	It is possible, but discouraged, for a driver or an application to support
	48	and use both versions of the API.</para>
	49	</section>
	50
	51	<section>
	52	<title>Calls that distinguish between single and multi-planar APIs</title>
	53	<variablelist>
	54	<varlistentry>
	55	<term>&VIDIOC-QUERYCAP;</term>
	56	<listitem>Two additional multi-planar capabilities are added. They can
	57	be set together with non-multi-planar ones for devices that handle
	58	both single- and multi-planar formats.</listitem>
	59	</varlistentry>
	60	<varlistentry>
	61	<term>&VIDIOC-G-FMT;, &VIDIOC-S-FMT;, &VIDIOC-TRY-FMT;</term>
	62	<listitem>New structures for describing multi-planar formats are added:
	63	&v4l2-pix-format-mplane; and &v4l2-plane-pix-format;. Drivers may
	64	define new multi-planar formats, which have distinct FourCC codes from
	65	the existing single-planar ones.
	66	</listitem>
	67	</varlistentry>
	68	<varlistentry>
	69	<term>&VIDIOC-QBUF;, &VIDIOC-DQBUF;, &VIDIOC-QUERYBUF;</term>
	70	<listitem>A new &v4l2-plane; structure for describing planes is added.
	71	Arrays of this structure are passed in the new
	72	<structfield>m.planes</structfield> field of &v4l2-buffer;.
	73	</listitem>
	74	</varlistentry>
	75	<varlistentry>
	76	<term>&VIDIOC-REQBUFS;</term>
	77	<listitem>Will allocate multi-planar buffers as requested.</listitem>
	78	</varlistentry>
	79	</variablelist>
	80	</section>
	81	</section>
	82

Documentation/DocBook/v4l/v4l2.xml

Diff comments View file @ 53b5d57

  <partinfo>
     <authorgroup>
       <author>
 	<firstname>Michael</firstname>
 	<surname>Schimek</surname>
 	<othername role="mi">H</othername>
 	<affiliation>
 	  <address>
 	    <email>mschimek@gmx.at</email>
 	  </address>
 	</affiliation>
       </author>
       <author>
 	<firstname>Bill</firstname>
 	<surname>Dirks</surname>
 	<!-- Commented until Bill opts in to be spammed.
 	<affiliation>
 	  <address>
 	    <email>bill@thedirks.org</email>
 	  </address>
 	</affiliation> -->
 	<contrib>Original author of the V4L2 API and
 documentation.</contrib>
       </author>
       <author>
 	<firstname>Hans</firstname>
 	<surname>Verkuil</surname>
 	<contrib>Designed and documented the VIDIOC_LOG_STATUS ioctl,
 the extended control ioctls and major parts of the sliced VBI
 API.</contrib>
 	<affiliation>
 	  <address>
 	    <email>hverkuil@xs4all.nl</email>
 	  </address>
 	</affiliation>
       </author>
       <author>
 	<firstname>Martin</firstname>
 	<surname>Rubli</surname>
 	<!--
 	<affiliation>
 	  <address>
 	    <email>martin_rubli@logitech.com</email>
 	  </address>
 	</affiliation> -->
 	<contrib>Designed and documented the VIDIOC_ENUM_FRAMESIZES
 and VIDIOC_ENUM_FRAMEINTERVALS ioctls.</contrib>
       </author>
       <author>
 	<firstname>Andy</firstname>
 	<surname>Walls</surname>
 	<contrib>Documented the fielded V4L2_MPEG_STREAM_VBI_FMT_IVTV
 MPEG stream embedded, sliced VBI data format in this specification.
 </contrib>
 	<affiliation>
 	  <address>
 	    <email>awalls@md.metrocast.net</email>
 	  </address>
 	</affiliation>
       </author>
       <author>
 	<firstname>Mauro</firstname>
 	<surname>Carvalho Chehab</surname>
 	<contrib>Documented libv4l, designed and added v4l2grab example,
 Remote Controller chapter.</contrib>
 	<affiliation>
 	  <address>
 	    <email>mchehab@redhat.com</email>
 	  </address>
 	</affiliation>
       </author>
       <author>
 	<firstname>Muralidharan</firstname>
 	<surname>Karicheri</surname>
 	<contrib>Documented the Digital Video timings API.</contrib>
 	<affiliation>
 	  <address>
 	    <email>m-karicheri2@ti.com</email>
 	  </address>
 	</affiliation>
       </author>
+      <author>
+      	<firstname>Pawel</firstname>
+	<surname>Osciak</surname>
+	<contrib>Designed and documented the multi-planar API.</contrib>
+	<affiliation>
+	  <address>
+	    <email>pawel AT osciak.com</email>
+	  </address>
+	</affiliation>
+      </author>
     </authorgroup>
     <copyright>
       <year>1999</year>
       <year>2000</year>
       <year>2001</year>
       <year>2002</year>
       <year>2003</year>
       <year>2004</year>
       <year>2005</year>
       <year>2006</year>
       <year>2007</year>
       <year>2008</year>
       <year>2009</year>
       <year>2010</year>
       <year>2011</year>
       <holder>Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin
-Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab</holder>
+Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab,
+	Pawel Osciak</holder>
     </copyright>
     <legalnotice>
     <para>Except when explicitly stated as GPL, programming examples within
 	    this part can be used and distributed without restrictions.</para>
     </legalnotice>
     <revhistory>
       <!-- Put document revisions here, newest first. -->
       <!-- API revisions (changes and additions of defines, enums,
 structs, ioctls) must be noted in more detail in the history chapter
 (compat.xml), along with the possible impact on existing drivers and
 applications. -->
+      <revision>
+	<revnumber>2.6.38</revnumber>
+	<authorinitials>po</authorinitials>
+	<revremark>Added the <link linkend="planar-apis">multi-planar API</link>.
+	</revremark>
+      </revision>
       <revision>
 	<revnumber>2.6.37</revnumber>
 	<date>2010-08-06</date>
 	<authorinitials>hv</authorinitials>
 	<revremark>Removed obsolete vtx (videotext) API.</revremark>
       </revision>
       <revision>
 	<revnumber>2.6.33</revnumber>
 	<date>2009-12-03</date>
 	<authorinitials>mk</authorinitials>
 	<revremark>Added documentation for the Digital Video timings API.</revremark>
       </revision>
       <revision>
 	<revnumber>2.6.32</revnumber>
 	<date>2009-08-31</date>
 	<authorinitials>mcc</authorinitials>
 	<revremark>Now, revisions will match the kernel version where
 the V4L2 API changes will be used by the Linux Kernel.
 Also added Remote Controller chapter.</revremark>
       </revision>
       <revision>
 	<revnumber>0.29</revnumber>
 	<date>2009-08-26</date>
 	<authorinitials>ev</authorinitials>
 	<revremark>Added documentation for string controls and for FM Transmitter controls.</revremark>
       </revision>
       <revision>
 	<revnumber>0.28</revnumber>
 	<date>2009-08-26</date>
 	<authorinitials>gl</authorinitials>
 	<revremark>Added V4L2_CID_BAND_STOP_FILTER documentation.</revremark>
       </revision>
       <revision>
 	<revnumber>0.27</revnumber>
 	<date>2009-08-15</date>
 	<authorinitials>mcc</authorinitials>
 	<revremark>Added libv4l and Remote Controller documentation;
 added v4l2grab and keytable application examples.</revremark>
       </revision>
       <revision>
 	<revnumber>0.26</revnumber>
 	<date>2009-07-23</date>
 	<authorinitials>hv</authorinitials>
 	<revremark>Finalized the RDS capture API. Added modulator and RDS encoder
 capabilities. Added support for string controls.</revremark>
       </revision>
       <revision>
 	<revnumber>0.25</revnumber>
 	<date>2009-01-18</date>
 	<authorinitials>hv</authorinitials>
 	<revremark>Added pixel formats VYUY, NV16 and NV61, and changed
 the debug ioctls VIDIOC_DBG_G/S_REGISTER and VIDIOC_DBG_G_CHIP_IDENT.
 Added camera controls V4L2_CID_ZOOM_ABSOLUTE, V4L2_CID_ZOOM_RELATIVE,
 V4L2_CID_ZOOM_CONTINUOUS and V4L2_CID_PRIVACY.</revremark>
       </revision>
       <revision>
 	<revnumber>0.24</revnumber>
 	<date>2008-03-04</date>
 	<authorinitials>mhs</authorinitials>
 	<revremark>Added pixel formats Y16 and SBGGR16, new controls
 and a camera controls class. Removed VIDIOC_G/S_MPEGCOMP.</revremark>
       </revision>
       <revision>
 	<revnumber>0.23</revnumber>
 	<date>2007-08-30</date>
 	<authorinitials>mhs</authorinitials>
 	<revremark>Fixed a typo in VIDIOC_DBG_G/S_REGISTER.
 Clarified the byte order of packed pixel formats.</revremark>
       </revision>
       <revision>
 	<revnumber>0.22</revnumber>
 	<date>2007-08-29</date>
 	<authorinitials>mhs</authorinitials>
 	<revremark>Added the Video Output Overlay interface, new MPEG
 controls, V4L2_FIELD_INTERLACED_TB and V4L2_FIELD_INTERLACED_BT,
 VIDIOC_DBG_G/S_REGISTER, VIDIOC_(TRY_)ENCODER_CMD,
 VIDIOC_G_CHIP_IDENT, VIDIOC_G_ENC_INDEX, new pixel formats.
 Clarifications in the cropping chapter, about RGB pixel formats, the
 mmap(), poll(), select(), read() and write() functions. Typographical
 fixes.</revremark>
       </revision>
       <revision>
 	<revnumber>0.21</revnumber>
 	<date>2006-12-19</date>
 	<authorinitials>mhs</authorinitials>
 	<revremark>Fixed a link in the VIDIOC_G_EXT_CTRLS section.</revremark>
       </revision>
       <revision>
 	<revnumber>0.20</revnumber>
 	<date>2006-11-24</date>
 	<authorinitials>mhs</authorinitials>
 	<revremark>Clarified the purpose of the audioset field in
 struct v4l2_input and v4l2_output.</revremark>
       </revision>
       <revision>
 	<revnumber>0.19</revnumber>
 	<date>2006-10-19</date>
 	<authorinitials>mhs</authorinitials>
 	<revremark>Documented V4L2_PIX_FMT_RGB444.</revremark>
       </revision>
       <revision>
 	<revnumber>0.18</revnumber>
 	<date>2006-10-18</date>
 	<authorinitials>mhs</authorinitials>
 	<revremark>Added the description of extended controls by Hans
 Verkuil. Linked V4L2_PIX_FMT_MPEG to V4L2_CID_MPEG_STREAM_TYPE.</revremark>
       </revision>
       <revision>
 	<revnumber>0.17</revnumber>
 	<date>2006-10-12</date>
 	<authorinitials>mhs</authorinitials>
 	<revremark>Corrected V4L2_PIX_FMT_HM12 description.</revremark>
       </revision>
       <revision>
 	<revnumber>0.16</revnumber>
 	<date>2006-10-08</date>
 	<authorinitials>mhs</authorinitials>
 	<revremark>VIDIOC_ENUM_FRAMESIZES and
 VIDIOC_ENUM_FRAMEINTERVALS are now part of the API.</revremark>
       </revision>
       <revision>
 	<revnumber>0.15</revnumber>
 	<date>2006-09-23</date>
 	<authorinitials>mhs</authorinitials>
 	<revremark>Cleaned up the bibliography, added BT.653 and
 BT.1119. capture.c/start_capturing() for user pointer I/O did not
 initialize the buffer index. Documented the V4L MPEG and MJPEG
 VID_TYPEs and V4L2_PIX_FMT_SBGGR8. Updated the list of reserved pixel
 formats. See the history chapter for API changes.</revremark>
       </revision>
       <revision>
 	<revnumber>0.14</revnumber>
 	<date>2006-09-14</date>
 	<authorinitials>mr</authorinitials>
 	<revremark>Added VIDIOC_ENUM_FRAMESIZES and
 VIDIOC_ENUM_FRAMEINTERVALS proposal for frame format enumeration of
 digital devices.</revremark>
       </revision>
       <revision>
 	<revnumber>0.13</revnumber>
 	<date>2006-04-07</date>
 	<authorinitials>mhs</authorinitials>
 	<revremark>Corrected the description of struct v4l2_window
 clips. New V4L2_STD_ and V4L2_TUNER_MODE_LANG1_LANG2
 defines.</revremark>
       </revision>
       <revision>
 	<revnumber>0.12</revnumber>
 	<date>2006-02-03</date>
 	<authorinitials>mhs</authorinitials>
 	<revremark>Corrected the description of struct
 v4l2_captureparm and v4l2_outputparm.</revremark>
       </revision>
       <revision>
 	<revnumber>0.11</revnumber>
 	<date>2006-01-27</date>
 	<authorinitials>mhs</authorinitials>
 	<revremark>Improved the description of struct
 v4l2_tuner.</revremark>
       </revision>
       <revision>
 	<revnumber>0.10</revnumber>
 	<date>2006-01-10</date>
 	<authorinitials>mhs</authorinitials>
 	<revremark>VIDIOC_G_INPUT and VIDIOC_S_PARM
 clarifications.</revremark>
       </revision>
       <revision>
 	<revnumber>0.9</revnumber>
 	<date>2005-11-27</date>
 	<authorinitials>mhs</authorinitials>
 	<revremark>Improved the 525 line numbering diagram. Hans
 Verkuil and I rewrote the sliced VBI section. He also contributed a
 VIDIOC_LOG_STATUS page. Fixed VIDIOC_S_STD call in the video standard
 selection example. Various updates.</revremark>
       </revision>
       <revision>
 	<revnumber>0.8</revnumber>
 	<date>2004-10-04</date>
 	<authorinitials>mhs</authorinitials>
 	<revremark>Somehow a piece of junk slipped into the capture
 example, removed.</revremark>
       </revision>
       <revision>
 	<revnumber>0.7</revnumber>
 	<date>2004-09-19</date>
 	<authorinitials>mhs</authorinitials>
 	<revremark>Fixed video standard selection, control
 enumeration, downscaling and aspect example. Added read and user
 pointer i/o to video capture example.</revremark>
       </revision>
       <revision>
 	<revnumber>0.6</revnumber>
 	<date>2004-08-01</date>
 	<authorinitials>mhs</authorinitials>
 	<revremark>v4l2_buffer changes, added video capture example,
 various corrections.</revremark>
       </revision>
       <revision>
 	<revnumber>0.5</revnumber>
 	<date>2003-11-05</date>
 	<authorinitials>mhs</authorinitials>
 	<revremark>Pixel format erratum.</revremark>
       </revision>
       <revision>
 	<revnumber>0.4</revnumber>
 	<date>2003-09-17</date>
 	<authorinitials>mhs</authorinitials>
 	<revremark>Corrected source and Makefile to generate a PDF.
 SGML fixes. Added latest API changes. Closed gaps in the history
 chapter.</revremark>
       </revision>
       <revision>
 	<revnumber>0.3</revnumber>
 	<date>2003-02-05</date>
 	<authorinitials>mhs</authorinitials>
 	<revremark>Another draft, more corrections.</revremark>
       </revision>
       <revision>
 	<revnumber>0.2</revnumber>
 	<date>2003-01-15</date>
 	<authorinitials>mhs</authorinitials>
 	<revremark>Second draft, with corrections pointed out by Gerd
 Knorr.</revremark>
       </revision>
       <revision>
 	<revnumber>0.1</revnumber>
 	<date>2002-12-01</date>
 	<authorinitials>mhs</authorinitials>
 	<revremark>First draft, based on documentation by Bill Dirks
 and discussions on the V4L mailing list.</revremark>
       </revision>
     </revhistory>
 </partinfo>
 <title>Video for Linux Two API Specification</title>
  <subtitle>Revision 2.6.38</subtitle>
   <chapter id="common">
     &sub-common;
   </chapter>
   <chapter id="pixfmt">
     &sub-pixfmt;
   </chapter>
   <chapter id="io">
     &sub-io;
   </chapter>
   <chapter id="devices">
     <title>Interfaces</title>
     <section id="capture"> &sub-dev-capture; </section>
     <section id="overlay"> &sub-dev-overlay; </section>
     <section id="output"> &sub-dev-output; </section>
     <section id="osd"> &sub-dev-osd; </section>
     <section id="codec"> &sub-dev-codec; </section>
     <section id="effect"> &sub-dev-effect; </section>
     <section id="raw-vbi"> &sub-dev-raw-vbi; </section>
     <section id="sliced"> &sub-dev-sliced-vbi; </section>
     <section id="ttx"> &sub-dev-teletext; </section>
     <section id="radio"> &sub-dev-radio; </section>
     <section id="rds"> &sub-dev-rds; </section>
     <section id="event"> &sub-dev-event; </section>
   </chapter>
   <chapter id="driver">
 	  &sub-driver;
   </chapter>
   <chapter id="libv4l">
 	  &sub-libv4l;
   </chapter>
   <chapter id="compat">
 	  &sub-compat;
   </chapter>
   <appendix id="user-func">
   <title>Function Reference</title>
     <!-- Keep this alphabetically sorted. -->
     &sub-close;
     &sub-ioctl;
     <!-- All ioctls go here. -->
     &sub-cropcap;
     &sub-dbg-g-chip-ident;
     &sub-dbg-g-register;
     &sub-dqevent;
     &sub-encoder-cmd;
     &sub-enumaudio;
     &sub-enumaudioout;
     &sub-enum-dv-presets;
     &sub-enum-fmt;
     &sub-enum-framesizes;
     &sub-enum-frameintervals;
     &sub-enuminput;
     &sub-enumoutput;
     &sub-enumstd;
     &sub-g-audio;
     &sub-g-audioout;
     &sub-g-crop;
     &sub-g-ctrl;
     &sub-g-dv-preset;
     &sub-g-dv-timings;
     &sub-g-enc-index;
     &sub-g-ext-ctrls;
     &sub-g-fbuf;
     &sub-g-fmt;
     &sub-g-frequency;
     &sub-g-input;
     &sub-g-jpegcomp;
     &sub-g-modulator;
     &sub-g-output;
     &sub-g-parm;
     &sub-g-priority;
     &sub-g-sliced-vbi-cap;
     &sub-g-std;
     &sub-g-tuner;
     &sub-log-status;
     &sub-overlay;
     &sub-qbuf;
     &sub-querybuf;
     &sub-querycap;
     &sub-queryctrl;
     &sub-query-dv-preset;
     &sub-querystd;
     &sub-reqbufs;
     &sub-s-hw-freq-seek;
     &sub-streamon;
     &sub-subscribe-event;
     <!-- End of ioctls. -->
     &sub-mmap;
     &sub-munmap;
     &sub-open;
     &sub-poll;
     &sub-read;
     &sub-select;
     &sub-write;
   </appendix>
   <appendix id="videodev">
     <title>Video For Linux Two Header File</title>
     &sub-videodev2-h;
   </appendix>
   <appendix id="capture-example">
     <title>Video Capture Example</title>
     &sub-capture-c;
   </appendix>
   <appendix id="v4l2grab-example">
     <title>Video Grabber example using libv4l</title>
     <para>This program demonstrates how to grab V4L2 images in ppm format by
 using libv4l handlers. The advantage is that this grabber can potentially work
 with any V4L2 driver.</para>
     &sub-v4l2grab-c;
   </appendix>
   &sub-media-indices;
   &sub-biblio;

Documentation/DocBook/v4l/vidioc-enum-fmt.xml

Diff comments View file @ 53b5d57

 <refentry id="vidioc-enum-fmt">
   <refmeta>
     <refentrytitle>ioctl VIDIOC_ENUM_FMT</refentrytitle>
     &manvol;
   </refmeta>
   <refnamediv>
     <refname>VIDIOC_ENUM_FMT</refname>
     <refpurpose>Enumerate image formats</refpurpose>
   </refnamediv>
   <refsynopsisdiv>
     <funcsynopsis>
       <funcprototype>
 	<funcdef>int <function>ioctl</function></funcdef>
 	<paramdef>int <parameter>fd</parameter></paramdef>
 	<paramdef>int <parameter>request</parameter></paramdef>
 	<paramdef>struct v4l2_fmtdesc
 *<parameter>argp</parameter></paramdef>
       </funcprototype>
     </funcsynopsis>
   </refsynopsisdiv>
   <refsect1>
     <title>Arguments</title>
     <variablelist>
       <varlistentry>
 	<term><parameter>fd</parameter></term>
 	<listitem>
 	  <para>&fd;</para>
 	</listitem>
       </varlistentry>
       <varlistentry>
 	<term><parameter>request</parameter></term>
 	<listitem>
 	  <para>VIDIOC_ENUM_FMT</para>
 	</listitem>
       </varlistentry>
       <varlistentry>
 	<term><parameter>argp</parameter></term>
 	<listitem>
 	  <para></para>
 	</listitem>
       </varlistentry>
     </variablelist>
   </refsect1>
   <refsect1>
     <title>Description</title>
     <para>To enumerate image formats applications initialize the
 <structfield>type</structfield> and <structfield>index</structfield>
 field of &v4l2-fmtdesc; and call the
 <constant>VIDIOC_ENUM_FMT</constant> ioctl with a pointer to this
 structure. Drivers fill the rest of the structure or return an
 &EINVAL;. All formats are enumerable by beginning at index zero and
 incrementing by one until <errorcode>EINVAL</errorcode> is
 returned.</para>
     <table pgwide="1" frame="none" id="v4l2-fmtdesc">
       <title>struct <structname>v4l2_fmtdesc</structname></title>
       <tgroup cols="3">
 	&cs-str;
 	<tbody valign="top">
 	  <row>
 	    <entry>__u32</entry>
 	    <entry><structfield>index</structfield></entry>
 	    <entry>Number of the format in the enumeration, set by
 the application. This is in no way related to the <structfield>
 pixelformat</structfield> field.</entry>
 	  </row>
 	  <row>
 	    <entry>&v4l2-buf-type;</entry>
 	    <entry><structfield>type</structfield></entry>
 	    <entry>Type of the data stream, set by the application.
 Only these types are valid here:
 <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>,
+<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant>,
 <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>,
+<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>,
 <constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>, and custom (driver
 defined) types with code <constant>V4L2_BUF_TYPE_PRIVATE</constant>
 and higher.</entry>
 	  </row>
 	  <row>
 	    <entry>__u32</entry>
 	    <entry><structfield>flags</structfield></entry>
 	    <entry>See <xref linkend="fmtdesc-flags" /></entry>
 	  </row>
 	  <row>
 	    <entry>__u8</entry>
 	    <entry><structfield>description</structfield>[32]</entry>
 	    <entry>Description of the format, a NUL-terminated ASCII
 string. This information is intended for the user, for example: "YUV
 4:2:2".</entry>
 	  </row>
 	  <row>
 	    <entry>__u32</entry>
 	    <entry><structfield>pixelformat</structfield></entry>
 	    <entry>The image format identifier. This is a
 four character code as computed by the v4l2_fourcc()
 macro:</entry>
 	  </row>
 	  <row>
 	    <entry spanname="hspan"><para><programlisting id="v4l2-fourcc">
 #define v4l2_fourcc(a,b,c,d) (((__u32)(a)&lt;&lt;0)|((__u32)(b)&lt;&lt;8)|((__u32)(c)&lt;&lt;16)|((__u32)(d)&lt;&lt;24))
 </programlisting></para><para>Several image formats are already
 defined by this specification in <xref linkend="pixfmt" />. Note these
 codes are not the same as those used in the Windows world.</para></entry>
 	  </row>
 	  <row>
 	    <entry>__u32</entry>
 	    <entry><structfield>reserved</structfield>[4]</entry>
 	    <entry>Reserved for future extensions. Drivers must set
 the array to zero.</entry>
 	  </row>
 	</tbody>
       </tgroup>
     </table>
     <table pgwide="1" frame="none" id="fmtdesc-flags">
       <title>Image Format Description Flags</title>
       <tgroup cols="3">
 	&cs-def;
 	<tbody valign="top">
 	  <row>
 	    <entry><constant>V4L2_FMT_FLAG_COMPRESSED</constant></entry>
 	    <entry>0x0001</entry>
 	    <entry>This is a compressed format.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_FMT_FLAG_EMULATED</constant></entry>
 	    <entry>0x0002</entry>
 	    <entry>This format is not native to the device but emulated
 through software (usually libv4l2), where possible try to use a native format
 instead for better performance.</entry>
 	  </row>
 	</tbody>
       </tgroup>
     </table>
   </refsect1>
   <refsect1>
     &return-value;
     <variablelist>
       <varlistentry>
 	<term><errorcode>EINVAL</errorcode></term>
 	<listitem>
 	  <para>The &v4l2-fmtdesc; <structfield>type</structfield>
 is not supported or the <structfield>index</structfield> is out of
 bounds.</para>
 	</listitem>
       </varlistentry>
     </variablelist>
   </refsect1>
 </refentry>
 <!--
 Local Variables:
 mode: sgml
 sgml-parent-document: "v4l2.sgml"
 indent-tabs-mode: nil
 End:
 -->

Documentation/DocBook/v4l/vidioc-g-fmt.xml

Diff comments View file @ 53b5d57

 <refentry id="vidioc-g-fmt">
   <refmeta>
     <refentrytitle>ioctl VIDIOC_G_FMT, VIDIOC_S_FMT,
 VIDIOC_TRY_FMT</refentrytitle>
     &manvol;
   </refmeta>
   <refnamediv>
     <refname>VIDIOC_G_FMT</refname>
     <refname>VIDIOC_S_FMT</refname>
     <refname>VIDIOC_TRY_FMT</refname>
     <refpurpose>Get or set the data format, try a format</refpurpose>
   </refnamediv>
   <refsynopsisdiv>
     <funcsynopsis>
       <funcprototype>
 	<funcdef>int <function>ioctl</function></funcdef>
 	<paramdef>int <parameter>fd</parameter></paramdef>
 	<paramdef>int <parameter>request</parameter></paramdef>
 	<paramdef>struct v4l2_format
 *<parameter>argp</parameter></paramdef>
       </funcprototype>
     </funcsynopsis>
   </refsynopsisdiv>
   <refsect1>
     <title>Arguments</title>
     <variablelist>
       <varlistentry>
 	<term><parameter>fd</parameter></term>
 	<listitem>
 	  <para>&fd;</para>
 	</listitem>
       </varlistentry>
       <varlistentry>
 	<term><parameter>request</parameter></term>
 	<listitem>
 	  <para>VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT</para>
 	</listitem>
       </varlistentry>
       <varlistentry>
 	<term><parameter>argp</parameter></term>
 	<listitem>
 	  <para></para>
 	</listitem>
       </varlistentry>
     </variablelist>
   </refsect1>
   <refsect1>
     <title>Description</title>
     <para>These ioctls are used to negotiate the format of data
 (typically image format) exchanged between driver and
 application.</para>
     <para>To query the current parameters applications set the
 <structfield>type</structfield> field of a struct
 <structname>v4l2_format</structname> to the respective buffer (stream)
 type. For example video capture devices use
-<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>. When the application
+<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> or
+<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant>. When the application
 calls the <constant>VIDIOC_G_FMT</constant> ioctl with a pointer to
 this structure the driver fills the respective member of the
 <structfield>fmt</structfield> union. In case of video capture devices
-that is the &v4l2-pix-format; <structfield>pix</structfield> member.
+that is either the &v4l2-pix-format; <structfield>pix</structfield> or
+the &v4l2-pix-format-mplane; <structfield>pix_mp</structfield> member.
 When the requested buffer type is not supported drivers return an
 &EINVAL;.</para>
     <para>To change the current format parameters applications
 initialize the <structfield>type</structfield> field and all
 fields of the respective <structfield>fmt</structfield>
 union member. For details see the documentation of the various devices
 types in <xref linkend="devices" />. 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 <constant>VIDIOC_S_FMT</constant> ioctl
 with a pointer to a <structname>v4l2_format</structname> 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 <constant>VIDIOC_S_FMT</constant> ioctl returns the
 current format parameters as <constant>VIDIOC_G_FMT</constant> 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
 <constant>VIDIOC_G_FMT</constant> and
 <constant>VIDIOC_S_FMT</constant> ioctl. When the requested buffer
 type is not supported drivers return an &EINVAL; on a
 <constant>VIDIOC_S_FMT</constant> attempt. When I/O is already in
 progress or the resource is not available for other reasons drivers
 return the &EBUSY;.</para>
     <para>The <constant>VIDIOC_TRY_FMT</constant> ioctl is equivalent
 to <constant>VIDIOC_S_FMT</constant> with one exception: it does not
 change driver state. It can also be called at any time, never
 returning <errorcode>EBUSY</errorcode>. 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.</para>
     <table pgwide="1" frame="none" id="v4l2-format">
       <title>struct <structname>v4l2_format</structname></title>
       <tgroup cols="4">
 	<colspec colname="c1" />
 	<colspec colname="c2" />
 	<colspec colname="c3" />
 	<colspec colname="c4" />
 	<tbody valign="top">
 	  <row>
 	    <entry>&v4l2-buf-type;</entry>
 	    <entry><structfield>type</structfield></entry>
 	    <entry></entry>
 	    <entry>Type of the data stream, see <xref
 		linkend="v4l2-buf-type" />.</entry>
 	  </row>
 	  <row>
 	    <entry>union</entry>
 	    <entry><structfield>fmt</structfield></entry>
 	  </row>
 	  <row>
 	    <entry></entry>
 	    <entry>&v4l2-pix-format;</entry>
 	    <entry><structfield>pix</structfield></entry>
 	    <entry>Definition of an image format, see <xref
 		linkend="pixfmt" />, used by video capture and output
 devices.</entry>
+	  </row>
+	  <row>
+	    <entry></entry>
+	    <entry>&v4l2-pix-format-mplane;</entry>
+	    <entry><structfield>pix_mp</structfield></entry>
+	    <entry>Definition of an image format, see <xref
+		linkend="pixfmt" />, used by video capture and output
+devices that support the <link linkend="planar-apis">multi-planar
+version of the API</link>.</entry>
 	  </row>
 	  <row>
 	    <entry></entry>
 	    <entry>&v4l2-window;</entry>
 	    <entry><structfield>win</structfield></entry>
 	    <entry>Definition of an overlaid image, see <xref
 	    linkend="overlay" />, used by video overlay devices.</entry>
 	  </row>
 	  <row>
 	    <entry></entry>
 	    <entry>&v4l2-vbi-format;</entry>
 	    <entry><structfield>vbi</structfield></entry>
 	    <entry>Raw VBI capture or output parameters. This is
 discussed in more detail in <xref linkend="raw-vbi" />. Used by raw VBI
 capture and output devices.</entry>
 	  </row>
 	  <row>
 	    <entry></entry>
 	    <entry>&v4l2-sliced-vbi-format;</entry>
 	    <entry><structfield>sliced</structfield></entry>
 	    <entry>Sliced VBI capture or output parameters. See
 <xref linkend="sliced" /> for details. Used by sliced VBI
 capture and output devices.</entry>
 	  </row>
 	  <row>
 	    <entry></entry>
 	    <entry>__u8</entry>
 	    <entry><structfield>raw_data</structfield>[200]</entry>
 	    <entry>Place holder for future extensions and custom
 (driver defined) formats with <structfield>type</structfield>
 <constant>V4L2_BUF_TYPE_PRIVATE</constant> and higher.</entry>
 	  </row>
 	</tbody>
       </tgroup>
     </table>
   </refsect1>
   <refsect1>
     &return-value;
     <variablelist>
       <varlistentry>
 	<term><errorcode>EBUSY</errorcode></term>
 	<listitem>
 	  <para>The data format cannot be changed at this
 time, for example because I/O is already in progress.</para>
 	</listitem>
       </varlistentry>
       <varlistentry>
 	<term><errorcode>EINVAL</errorcode></term>
 	<listitem>
 	  <para>The &v4l2-format; <structfield>type</structfield>
 field is invalid, the requested buffer type not supported, or
 <constant>VIDIOC_TRY_FMT</constant> was called and is not
 supported with this buffer type.</para>
 	</listitem>
       </varlistentry>
     </variablelist>
   </refsect1>
 </refentry>
 <!--
 Local Variables:
 mode: sgml
 sgml-parent-document: "v4l2.sgml"
 indent-tabs-mode: nil
 End:
 -->

Documentation/DocBook/v4l/vidioc-qbuf.xml

Diff comments View file @ 53b5d57

 <refentry id="vidioc-qbuf">
   <refmeta>
     <refentrytitle>ioctl VIDIOC_QBUF, VIDIOC_DQBUF</refentrytitle>
     &manvol;
   </refmeta>
   <refnamediv>
     <refname>VIDIOC_QBUF</refname>
     <refname>VIDIOC_DQBUF</refname>
     <refpurpose>Exchange a buffer with the driver</refpurpose>
   </refnamediv>
   <refsynopsisdiv>
     <funcsynopsis>
       <funcprototype>
 	<funcdef>int <function>ioctl</function></funcdef>
 	<paramdef>int <parameter>fd</parameter></paramdef>
 	<paramdef>int <parameter>request</parameter></paramdef>
 	<paramdef>struct v4l2_buffer *<parameter>argp</parameter></paramdef>
       </funcprototype>
     </funcsynopsis>
   </refsynopsisdiv>
   <refsect1>
     <title>Arguments</title>
     <variablelist>
       <varlistentry>
 	<term><parameter>fd</parameter></term>
 	<listitem>
 	  <para>&fd;</para>
 	</listitem>
       </varlistentry>
       <varlistentry>
 	<term><parameter>request</parameter></term>
 	<listitem>
 	  <para>VIDIOC_QBUF, VIDIOC_DQBUF</para>
 	</listitem>
       </varlistentry>
       <varlistentry>
 	<term><parameter>argp</parameter></term>
 	<listitem>
 	  <para></para>
 	</listitem>
       </varlistentry>
     </variablelist>
   </refsect1>
   <refsect1>
     <title>Description</title>
     <para>Applications call the <constant>VIDIOC_QBUF</constant> 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.</para>
     <para>To enqueue a buffer applications set the <structfield>type</structfield>
 field of a &v4l2-buffer; to the same buffer type as was previously used
 with &v4l2-format; <structfield>type</structfield> and &v4l2-requestbuffers;
 <structfield>type</structfield>. Applications must also set the
 <structfield>index</structfield> field. Valid index numbers range from
 zero to the number of buffers allocated with &VIDIOC-REQBUFS;
 (&v4l2-requestbuffers; <structfield>count</structfield>) minus one. The
 contents of the struct <structname>v4l2_buffer</structname> returned
 by a &VIDIOC-QUERYBUF; ioctl will do as well. When the buffer is
 intended for output (<structfield>type</structfield> is
-<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> or
+<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>,
+<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>, or
 <constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant>) applications must also
 initialize the <structfield>bytesused</structfield>,
 <structfield>field</structfield> and
 <structfield>timestamp</structfield> fields, see <xref
 linkend="buffer" /> for details.
 Applications must also set <structfield>flags</structfield> to 0. If a driver
 supports capturing from specific video inputs and you want to specify a video
 input, then <structfield>flags</structfield> should be set to
 <constant>V4L2_BUF_FLAG_INPUT</constant> and the field
 <structfield>input</structfield> must be initialized to the desired input.
-The <structfield>reserved</structfield> field must be set to 0.
+The <structfield>reserved</structfield> field must be set to 0. When using
+the <link linkend="planar-apis">multi-planar API</link>, the
+<structfield>m.planes</structfield> field must contain a userspace pointer
+to a filled-in array of &v4l2-plane; and the <structfield>length</structfield>
+field must be set to the number of elements in that array.
 </para>
     <para>To enqueue a <link linkend="mmap">memory mapped</link>
 buffer applications set the <structfield>memory</structfield>
 field to <constant>V4L2_MEMORY_MMAP</constant>. When
 <constant>VIDIOC_QBUF</constant> is called with a pointer to this
 structure the driver sets the
 <constant>V4L2_BUF_FLAG_MAPPED</constant> and
 <constant>V4L2_BUF_FLAG_QUEUED</constant> flags and clears the
 <constant>V4L2_BUF_FLAG_DONE</constant> flag in the
 <structfield>flags</structfield> field, or it returns an
 &EINVAL;.</para>
     <para>To enqueue a <link linkend="userp">user pointer</link>
 buffer applications set the <structfield>memory</structfield>
 field to <constant>V4L2_MEMORY_USERPTR</constant>, the
 <structfield>m.userptr</structfield> field to the address of the
-buffer and <structfield>length</structfield> to its size.
+buffer and <structfield>length</structfield> to its size. When the multi-planar
-When <constant>VIDIOC_QBUF</constant> is called with a pointer to this
+API is used, <structfield>m.userptr</structfield> and
-structure the driver sets the <constant>V4L2_BUF_FLAG_QUEUED</constant>
+<structfield>length</structfield> members of the passed array of &v4l2-plane;
-flag and clears the <constant>V4L2_BUF_FLAG_MAPPED</constant> and
+have to be used instead. When <constant>VIDIOC_QBUF</constant> is called with
+a pointer to this structure the driver sets the
+<constant>V4L2_BUF_FLAG_QUEUED</constant> flag and clears the
+<constant>V4L2_BUF_FLAG_MAPPED</constant> and
 <constant>V4L2_BUF_FLAG_DONE</constant> flags in the
 <structfield>flags</structfield> 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 &VIDIOC-STREAMOFF; or &VIDIOC-REQBUFS; ioctl is
 called, or until the device is closed.</para>
     <para>Applications call the <constant>VIDIOC_DQBUF</constant>
 ioctl to dequeue a filled (capturing) or displayed (output) buffer
 from the driver's outgoing queue. They just set the
 <structfield>type</structfield>, <structfield>memory</structfield>
 and <structfield>reserved</structfield>
 fields of a &v4l2-buffer; as above, when <constant>VIDIOC_DQBUF</constant>
 is called with a pointer to this structure the driver fills the
 remaining fields or returns an error code. The driver may also set
 <constant>V4L2_BUF_FLAG_ERROR</constant> in the <structfield>flags</structfield>
 field. It indicates a non-critical (recoverable) streaming error. In such case
 the application may continue as normal, but should be aware that data in the
-dequeued buffer might be corrupted.</para>
+dequeued buffer might be corrupted. When using the multi-planar API, the
+planes array does not have to be passed; the <structfield>m.planes</structfield>
+member must be set to NULL in that case.</para>
     <para>By default <constant>VIDIOC_DQBUF</constant> blocks when no
 buffer is in the outgoing queue. When the
 <constant>O_NONBLOCK</constant> flag was given to the &func-open;
 function, <constant>VIDIOC_DQBUF</constant> returns immediately
 with an &EAGAIN; when no buffer is available.</para>
     <para>The <structname>v4l2_buffer</structname> structure is
 specified in <xref linkend="buffer" />.</para>
   </refsect1>
   <refsect1>
     &return-value;
     <variablelist>
       <varlistentry>
 	<term><errorcode>EAGAIN</errorcode></term>
 	<listitem>
 	  <para>Non-blocking I/O has been selected using
 <constant>O_NONBLOCK</constant> and no buffer was in the outgoing
 queue.</para>
 	</listitem>
       </varlistentry>
       <varlistentry>
 	<term><errorcode>EINVAL</errorcode></term>
 	<listitem>
 	  <para>The buffer <structfield>type</structfield> is not
 supported, or the <structfield>index</structfield> is out of bounds,
 or no buffers have been allocated yet, or the
 <structfield>userptr</structfield> or
 <structfield>length</structfield> are invalid.</para>
 	</listitem>
       </varlistentry>
       <varlistentry>
 	<term><errorcode>ENOMEM</errorcode></term>
 	<listitem>
 	  <para>Not enough physical or virtual memory was available to
 enqueue a user pointer buffer.</para>
 	</listitem>
       </varlistentry>
       <varlistentry>
 	<term><errorcode>EIO</errorcode></term>
 	<listitem>
 	  <para><constant>VIDIOC_DQBUF</constant> 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. Reusing such buffer may be unsafe
 though and its details (e.g. <structfield>index</structfield>) may not be
 returned either. It is recommended that drivers indicate recoverable errors
 by setting the <constant>V4L2_BUF_FLAG_ERROR</constant> and returning 0 instead.
 In that case the application should be able to safely reuse the buffer and
 continue streaming.
 	</para>
 	</listitem>
       </varlistentry>
     </variablelist>
   </refsect1>
 </refentry>
 <!--
 Local Variables:
 mode: sgml
 sgml-parent-document: "v4l2.sgml"
 indent-tabs-mode: nil
 End:
 -->

Documentation/DocBook/v4l/vidioc-querybuf.xml

Diff comments View file @ 53b5d57

 <refentry id="vidioc-querybuf">
   <refmeta>
     <refentrytitle>ioctl VIDIOC_QUERYBUF</refentrytitle>
     &manvol;
   </refmeta>
   <refnamediv>
     <refname>VIDIOC_QUERYBUF</refname>
     <refpurpose>Query the status of a buffer</refpurpose>
   </refnamediv>
   <refsynopsisdiv>
     <funcsynopsis>
       <funcprototype>
 	<funcdef>int <function>ioctl</function></funcdef>
 	<paramdef>int <parameter>fd</parameter></paramdef>
 	<paramdef>int <parameter>request</parameter></paramdef>
 	<paramdef>struct v4l2_buffer *<parameter>argp</parameter></paramdef>
       </funcprototype>
     </funcsynopsis>
   </refsynopsisdiv>
   <refsect1>
     <title>Arguments</title>
     <variablelist>
       <varlistentry>
 	<term><parameter>fd</parameter></term>
 	<listitem>
 	  <para>&fd;</para>
 	</listitem>
       </varlistentry>
       <varlistentry>
 	<term><parameter>request</parameter></term>
 	<listitem>
 	  <para>VIDIOC_QUERYBUF</para>
 	</listitem>
       </varlistentry>
       <varlistentry>
 	<term><parameter>argp</parameter></term>
 	<listitem>
 	  <para></para>
 	</listitem>
       </varlistentry>
     </variablelist>
   </refsect1>
   <refsect1>
     <title>Description</title>
     <para>This ioctl is part of the <link linkend="mmap">memory
 mapping</link> I/O method. It can be used to query the status of a
 buffer at any time after buffers have been allocated with the
 &VIDIOC-REQBUFS; ioctl.</para>
     <para>Applications set the <structfield>type</structfield> field
     of a &v4l2-buffer; to the same buffer type as was previously used with
 &v4l2-format; <structfield>type</structfield> and &v4l2-requestbuffers;
 <structfield>type</structfield>, and the <structfield>index</structfield>
     field. Valid index numbers range from zero
 to the number of buffers allocated with &VIDIOC-REQBUFS;
     (&v4l2-requestbuffers; <structfield>count</structfield>) minus one.
 The <structfield>reserved</structfield> field should to set to 0.
+When using the <link linkend="planar-apis">multi-planar API</link>, the
+<structfield>m.planes</structfield> field must contain a userspace pointer to an
+array of &v4l2-plane; and the <structfield>length</structfield> field has
+to be set to the number of elements in that array.
 After calling <constant>VIDIOC_QUERYBUF</constant> with a pointer to
     this structure drivers return an error code or fill the rest of
 the structure.</para>
     <para>In the <structfield>flags</structfield> field the
 <constant>V4L2_BUF_FLAG_MAPPED</constant>,
 <constant>V4L2_BUF_FLAG_QUEUED</constant> and
 <constant>V4L2_BUF_FLAG_DONE</constant> flags will be valid. The
 <structfield>memory</structfield> field will be set to the current
-I/O method, the <structfield>m.offset</structfield>
+I/O method. For the single-planar API, the <structfield>m.offset</structfield>
 contains the offset of the buffer from the start of the device memory,
-the <structfield>length</structfield> field its size. The driver may
+the <structfield>length</structfield> field its size. For the multi-planar API,
-or may not set the remaining fields and flags, they are meaningless in
+fields <structfield>m.mem_offset</structfield> and
-this context.</para>
+<structfield>length</structfield> in the <structfield>m.planes</structfield>
+array elements will be used instead. The driver may or may not set the remaining
+fields and flags, they are meaningless in this context.</para>
     <para>The <structname>v4l2_buffer</structname> structure is
     specified in <xref linkend="buffer" />.</para>
   </refsect1>
   <refsect1>
     &return-value;
     <variablelist>
       <varlistentry>
 	<term><errorcode>EINVAL</errorcode></term>
 	<listitem>
 	  <para>The buffer <structfield>type</structfield> is not
 supported, or the <structfield>index</structfield> is out of bounds.</para>
 	</listitem>
       </varlistentry>
     </variablelist>
   </refsect1>
 </refentry>
 <!--
 Local Variables:
 mode: sgml
 sgml-parent-document: "v4l2.sgml"
 indent-tabs-mode: nil
 End:
 -->

Documentation/DocBook/v4l/vidioc-querycap.xml

Diff comments View file @ 53b5d57

 <refentry id="vidioc-querycap">
   <refmeta>
     <refentrytitle>ioctl VIDIOC_QUERYCAP</refentrytitle>
     &manvol;
   </refmeta>
   <refnamediv>
     <refname>VIDIOC_QUERYCAP</refname>
     <refpurpose>Query device capabilities</refpurpose>
   </refnamediv>
   <refsynopsisdiv>
     <funcsynopsis>
       <funcprototype>
 	<funcdef>int <function>ioctl</function></funcdef>
 	<paramdef>int <parameter>fd</parameter></paramdef>
 	<paramdef>int <parameter>request</parameter></paramdef>
 	<paramdef>struct v4l2_capability *<parameter>argp</parameter></paramdef>
       </funcprototype>
     </funcsynopsis>
   </refsynopsisdiv>
   <refsect1>
     <title>Arguments</title>
     <variablelist>
       <varlistentry>
 	<term><parameter>fd</parameter></term>
 	<listitem>
 	  <para>&fd;</para>
 	</listitem>
       </varlistentry>
       <varlistentry>
 	<term><parameter>request</parameter></term>
 	<listitem>
 	  <para>VIDIOC_QUERYCAP</para>
 	</listitem>
       </varlistentry>
       <varlistentry>
 	<term><parameter>argp</parameter></term>
 	<listitem>
 	  <para></para>
 	</listitem>
       </varlistentry>
     </variablelist>
   </refsect1>
   <refsect1>
     <title>Description</title>
     <para>All V4L2 devices support the
 <constant>VIDIOC_QUERYCAP</constant> ioctl. It is used to identify
 kernel devices compatible with this specification and to obtain
 information about driver and hardware capabilities. The ioctl takes a
 pointer to a &v4l2-capability; which is filled by the driver. When the
 driver is not compatible with this specification the ioctl returns an
 &EINVAL;.</para>
     <table pgwide="1" frame="none" id="v4l2-capability">
       <title>struct <structname>v4l2_capability</structname></title>
       <tgroup cols="3">
 	&cs-str;
 	<tbody valign="top">
 	  <row>
 	    <entry>__u8</entry>
 	    <entry><structfield>driver</structfield>[16]</entry>
 	    <entry><para>Name of the driver, a unique NUL-terminated
 ASCII string. For example: "bttv". Driver specific applications can
 use this information to verify the driver identity. It is also useful
 to work around known bugs, or to identify drivers in error reports.
 The driver version is stored in the <structfield>version</structfield>
 field.</para><para>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 end of the array and to
 make sure the strings are properly NUL-terminated.</para></entry>
 	  </row>
 	  <row>
 	    <entry>__u8</entry>
 	    <entry><structfield>card</structfield>[32]</entry>
 	    <entry>Name of the device, a NUL-terminated ASCII string.
 For example: "Yoyodyne TV/FM". One driver may support different brands
 or models of video hardware. This information is intended for users,
 for example in a menu of available devices. Since multiple TV cards of
 the same brand may be installed which are supported by the same
 driver, this name should be combined with the character device file
 name (&eg; <filename>/dev/video2</filename>) or the
 <structfield>bus_info</structfield> string to avoid
 ambiguities.</entry>
 	  </row>
 	  <row>
 	    <entry>__u8</entry>
 	    <entry><structfield>bus_info</structfield>[32]</entry>
 	    <entry>Location of the device in the system, a
 NUL-terminated ASCII string. For example: "PCI Slot 4". This
 information is intended for users, 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 (<structfield>bus_info</structfield>[0] = 0).<!-- XXX pci_dev->slot_name example --></entry>
 	  </row>
 	  <row>
 	    <entry>__u32</entry>
 	    <entry><structfield>version</structfield></entry>
 	    <entry><para>Version number of the driver. Together with
 the <structfield>driver</structfield> field this identifies a
 particular driver. The version number is formatted using the
 <constant>KERNEL_VERSION()</constant> macro:</para></entry>
 	  </row>
 	  <row>
 	    <entry spanname="hspan"><para>
 <programlisting>
 #define KERNEL_VERSION(a,b,c) (((a) &lt;&lt; 16) + ((b) &lt;&lt; 8) + (c))
 __u32 version = KERNEL_VERSION(0, 8, 1);
 printf ("Version: %u.%u.%u\n",
 	(version &gt;&gt; 16) &amp; 0xFF,
 	(version &gt;&gt; 8) &amp; 0xFF,
 	 version &amp; 0xFF);
 </programlisting></para></entry>
 	  </row>
 	  <row>
 	    <entry>__u32</entry>
 	    <entry><structfield>capabilities</structfield></entry>
 	    <entry>Device capabilities, see <xref
 		linkend="device-capabilities" />.</entry>
 	  </row>
 	  <row>
 	    <entry>__u32</entry>
 	    <entry><structfield>reserved</structfield>[4]</entry>
 	    <entry>Reserved for future extensions. Drivers must set
 this array to zero.</entry>
 	  </row>
 	</tbody>
       </tgroup>
     </table>
     <table pgwide="1" frame="none" id="device-capabilities">
       <title>Device Capabilities Flags</title>
       <tgroup cols="3">
 	&cs-def;
 	<tbody valign="top">
 	  <row>
 	    <entry><constant>V4L2_CAP_VIDEO_CAPTURE</constant></entry>
 	    <entry>0x00000001</entry>
-	    <entry>The device supports the <link
+	    <entry>The device supports single-planar formats through the <link
-linkend="capture">Video Capture</link> interface.</entry>
+linkend="capture">Video Capture</link> interface. An application can use either
+<link linkend="planar-apis">the single or the multi-planar API</link>.</entry>
 	  </row>
 	  <row>
+	    <entry><constant>V4L2_CAP_VIDEO_CAPTURE_MPLANE</constant></entry>
+	    <entry>0x00001000</entry>
+	    <entry>The device supports multi-planar formats through the <link
+linkend="capture">Video Capture</link> interface. An application has to use the
+<link linkend="planar-apis">multi-planar API</link>.</entry>
+	  </row>
+	  <row>
 	    <entry><constant>V4L2_CAP_VIDEO_OUTPUT</constant></entry>
 	    <entry>0x00000002</entry>
-	    <entry>The device supports the <link
+	    <entry>The device supports single-planar formats through the <link
-linkend="output">Video Output</link> interface.</entry>
+linkend="output">Video Output</link> interface. An application can use either
+<link linkend="planar-apis">the single or the multi-planar API</link>.</entry>
+	  </row>
+	  <row>
+	    <entry><constant>V4L2_CAP_VIDEO_OUTPUT_MPLANE</constant></entry>
+	    <entry>0x00002000</entry>
+	    <entry>The device supports multi-planar formats through the <link
+linkend="output">Video Output</link> interface. An application has to use the
+<link linkend="planar-apis">multi-planar API</link>.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_CAP_VIDEO_OVERLAY</constant></entry>
 	    <entry>0x00000004</entry>
 	    <entry>The device supports the <link
 linkend="overlay">Video Overlay</link> interface. A video overlay device
 typically stores captured images directly in the video memory of a
 graphics card, with hardware clipping and scaling.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_CAP_VBI_CAPTURE</constant></entry>
 	    <entry>0x00000010</entry>
 	    <entry>The device supports the <link linkend="raw-vbi">Raw
 VBI Capture</link> interface, providing Teletext and Closed Caption
 data.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_CAP_VBI_OUTPUT</constant></entry>
 	    <entry>0x00000020</entry>
 	    <entry>The device supports the <link linkend="raw-vbi">Raw VBI Output</link> interface.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_CAP_SLICED_VBI_CAPTURE</constant></entry>
 	    <entry>0x00000040</entry>
 	    <entry>The device supports the <link linkend="sliced">Sliced VBI Capture</link> interface.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_CAP_SLICED_VBI_OUTPUT</constant></entry>
 	    <entry>0x00000080</entry>
 	    <entry>The device supports the <link linkend="sliced">Sliced VBI Output</link> interface.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_CAP_RDS_CAPTURE</constant></entry>
 	    <entry>0x00000100</entry>
 	    <entry>The device supports the <link linkend="rds">RDS</link> capture interface.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_CAP_VIDEO_OUTPUT_OVERLAY</constant></entry>
 	    <entry>0x00000200</entry>
 	    <entry>The device supports the <link linkend="osd">Video
 Output Overlay</link> (OSD) interface. Unlike the <wordasword>Video
 Overlay</wordasword> interface, this is a secondary function of video
 output devices and overlays an image onto an outgoing video signal.
 When the driver sets this flag, it must clear the
 <constant>V4L2_CAP_VIDEO_OVERLAY</constant> flag and vice
 versa.<footnote><para>The &v4l2-framebuffer; lacks an
 &v4l2-buf-type; field, therefore the type of overlay is implied by the
 driver capabilities.</para></footnote></entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_CAP_HW_FREQ_SEEK</constant></entry>
 	    <entry>0x00000400</entry>
 	    <entry>The device supports the &VIDIOC-S-HW-FREQ-SEEK; ioctl for
 hardware frequency seeking.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_CAP_RDS_OUTPUT</constant></entry>
 	    <entry>0x00000800</entry>
 	    <entry>The device supports the <link linkend="rds">RDS</link> output interface.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_CAP_TUNER</constant></entry>
 	    <entry>0x00010000</entry>
 	    <entry>The device has some sort of tuner to
 receive RF-modulated video signals. For more information about
 tuner programming see
 <xref linkend="tuner" />.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_CAP_AUDIO</constant></entry>
 	    <entry>0x00020000</entry>
 	    <entry>The device has audio inputs or outputs. It may or
 may not support audio recording or playback, in PCM or compressed
 formats. PCM audio support must be implemented as ALSA or OSS
 interface. For more information on audio inputs and outputs see <xref
 		linkend="audio" />.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_CAP_RADIO</constant></entry>
 	    <entry>0x00040000</entry>
 	    <entry>This is a radio receiver.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_CAP_MODULATOR</constant></entry>
 	    <entry>0x00080000</entry>
 	    <entry>The device has some sort of modulator to
 emit RF-modulated video/audio signals. For more information about
 modulator programming see
 <xref linkend="tuner" />.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_CAP_READWRITE</constant></entry>
 	    <entry>0x01000000</entry>
 	    <entry>The device supports the <link
 linkend="rw">read()</link> and/or <link linkend="rw">write()</link>
 I/O methods.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_CAP_ASYNCIO</constant></entry>
 	    <entry>0x02000000</entry>
 	    <entry>The device supports the <link
 linkend="async">asynchronous</link> I/O methods.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_CAP_STREAMING</constant></entry>
 	    <entry>0x04000000</entry>
 	    <entry>The device supports the <link
 linkend="mmap">streaming</link> I/O method.</entry>
 	  </row>
 	</tbody>
       </tgroup>
     </table>
   </refsect1>
   <refsect1>
     &return-value;
     <variablelist>
       <varlistentry>
 	<term><errorcode>EINVAL</errorcode></term>
 	<listitem>
 	  <para>The device is not compatible with this
 specification.</para>
 	</listitem>
       </varlistentry>
     </variablelist>
   </refsect1>
 </refentry>
 <!--
 Local Variables:
 mode: sgml
 sgml-parent-document: "v4l2.sgml"
 indent-tabs-mode: nil
 End:
 -->