From 849369d6c66d3054688672f97d31fceb8e8230fb Mon Sep 17 00:00:00 2001 From: root Date: Fri, 25 Dec 2015 04:40:36 +0000 Subject: initial_commit --- Documentation/DocBook/v4l/compat.xml | 2500 ++++++++++++++++++++++++++++++++++ 1 file changed, 2500 insertions(+) create mode 100644 Documentation/DocBook/v4l/compat.xml (limited to 'Documentation/DocBook/v4l/compat.xml') diff --git a/Documentation/DocBook/v4l/compat.xml b/Documentation/DocBook/v4l/compat.xml new file mode 100644 index 00000000..9f7cd4f2 --- /dev/null +++ b/Documentation/DocBook/v4l/compat.xml @@ -0,0 +1,2500 @@ + Changes + + 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. + +
+ Differences between V4L and V4L2 + + 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 videodev kernel module translating ioctls on +the fly. For a transition period not all drivers will support the V4L2 +API. + +
+ Opening and Closing Devices + + 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 and below in . + + 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. + + The V4L videodev 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. + + + V4L Device Types, Names and Numbers + + + + Device Type + File Name + Minor Numbers + + + + + Video capture and overlay + /dev/video and +/dev/bttv0 According to +Documentation/devices.txt these should be symbolic links to +/dev/video0. Note the original bttv interface is +not compatible with V4L or V4L2. , +/dev/video0 to +/dev/video63 + 0-63 + + + Radio receiver + /dev/radio + According to +Documentation/devices.txt a symbolic link to +/dev/radio0. + , /dev/radio0 to +/dev/radio63 + 64-127 + + + Raw VBI capture + /dev/vbi, +/dev/vbi0 to +/dev/vbi31 + 224-255 + + + +
+ + V4L prohibits (or used to prohibit) multiple opens of a +device file. V4L2 drivers may support multiple +opens, see for details and consequences. + + V4L drivers respond to V4L2 ioctls with an &EINVAL;. The +compatibility layer in the V4L2 videodev 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 . +
+ +
+ Querying Capabilities + + The V4L VIDIOCGCAP ioctl is +equivalent to V4L2's &VIDIOC-QUERYCAP;. + + The name field in struct +video_capability became +card in &v4l2-capability;, +type was replaced by +capabilities. 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 for an +introduction. + + + + struct +video_capability +type + &v4l2-capability; +capabilities flags + Purpose + + + + + VID_TYPE_CAPTURE + V4L2_CAP_VIDEO_CAPTURE + The video +capture interface is supported. + + + VID_TYPE_TUNER + V4L2_CAP_TUNER + The device has a tuner or +modulator. + + + VID_TYPE_TELETEXT + V4L2_CAP_VBI_CAPTURE + The raw VBI +capture interface is supported. + + + VID_TYPE_OVERLAY + V4L2_CAP_VIDEO_OVERLAY + The video +overlay interface is supported. + + + VID_TYPE_CHROMAKEY + V4L2_FBUF_CAP_CHROMAKEY in +field capability of +&v4l2-framebuffer; + Whether chromakey overlay is supported. For +more information on overlay see +. + + + VID_TYPE_CLIPPING + V4L2_FBUF_CAP_LIST_CLIPPING +and V4L2_FBUF_CAP_BITMAP_CLIPPING in field +capability of &v4l2-framebuffer; + Whether clipping the overlaid image is +supported, see . + + + VID_TYPE_FRAMERAM + V4L2_FBUF_CAP_EXTERNOVERLAY +not set in field +capability of &v4l2-framebuffer; + Whether overlay overwrites frame buffer memory, +see . + + + VID_TYPE_SCALES + - + 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 . + + + VID_TYPE_MONOCHROME + - + 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 . + + + VID_TYPE_SUBCAPTURE + - + 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 . + + + VID_TYPE_MPEG_DECODER + - + Applications can enumerate the supported image +formats with the &VIDIOC-ENUM-FMT; ioctl to determine if the device +supports MPEG streams. + + + VID_TYPE_MPEG_ENCODER + - + See above. + + + VID_TYPE_MJPEG_DECODER + - + See above. + + + VID_TYPE_MJPEG_ENCODER + - + See above. + + + + + + The audios field was replaced +by capabilities flag +V4L2_CAP_AUDIO, indicating +if 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 . + + The maxwidth, +maxheight, +minwidth and +minheight 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. +
+ +
+ Video Sources + + V4L provides the VIDIOCGCHAN and +VIDIOCSCHAN ioctl using struct +video_channel 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 . + + The channel field counting +inputs was renamed to index, the video +input types were renamed as follows: + + + + struct video_channel +type + &v4l2-input; +type + + + + + VIDEO_TYPE_TV + V4L2_INPUT_TYPE_TUNER + + + VIDEO_TYPE_CAMERA + V4L2_INPUT_TYPE_CAMERA + + + + + + Unlike the tuners 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 tuner of +&v4l2-input;. Enumeration of tuners is discussed in . + + The redundant VIDEO_VC_TUNER flag was +dropped. Video inputs associated with a tuner are of type +V4L2_INPUT_TYPE_TUNER. The +VIDEO_VC_AUDIO flag was replaced by the +audioset field. V4L2 considers devices with +up to 32 audio inputs. Each set bit in the +audioset field represents one audio input +this video input combines with. For information about audio inputs and +how to switch between them see . + + The norm field describing the +supported video standards was replaced by +std. The V4L specification mentions a flag +VIDEO_VC_NORM indicating whether the standard can +be changed. This flag was a later addition together with the +norm field and has been removed in the +meantime. V4L2 has a similar, albeit more comprehensive approach +to video standards, see for more +information. +
+ +
+ Tuning + + The V4L VIDIOCGTUNER and +VIDIOCSTUNER ioctl and struct +video_tuner 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 . + + The tuner field counting tuners +was renamed to index. The fields +name, rangelow +and rangehigh remained unchanged. + + The VIDEO_TUNER_PAL, +VIDEO_TUNER_NTSC and +VIDEO_TUNER_SECAM flags indicating the supported +video standards were dropped. This information is now contained in the +associated &v4l2-input;. No replacement exists for the +VIDEO_TUNER_NORM flag indicating whether the +video standard can be switched. The mode +field to select a different video standard was replaced by a whole new +set of ioctls and structures described in . +Due to its ubiquity it should be mentioned the BTTV driver supports +several standards in addition to the regular +VIDEO_MODE_PAL (0), +VIDEO_MODE_NTSC, +VIDEO_MODE_SECAM and +VIDEO_MODE_AUTO (3). Namely N/PAL Argentina, +M/PAL, N/PAL, and NTSC Japan with numbers 3-6 (sic). + + The VIDEO_TUNER_STEREO_ON flag +indicating stereo reception became +V4L2_TUNER_SUB_STEREO in field +rxsubchans. 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 +VIDEO_TUNER_RDS_ON and +VIDEO_TUNER_MBS_ON flags. + + The VIDEO_TUNER_LOW flag was renamed +to V4L2_TUNER_CAP_LOW in the &v4l2-tuner; +capability field. + + The VIDIOCGFREQ and +VIDIOCSFREQ 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. +
+ +
+ Image Properties + + V4L2 has no equivalent of the +VIDIOCGPICT and VIDIOCSPICT +ioctl and struct video_picture. The following +fields where replaced by V4L2 controls accessible with the +&VIDIOC-QUERYCTRL;, &VIDIOC-G-CTRL; and &VIDIOC-S-CTRL; ioctls: + + + + struct video_picture + V4L2 Control ID + + + + + brightness + V4L2_CID_BRIGHTNESS + + + hue + V4L2_CID_HUE + + + colour + V4L2_CID_SATURATION + + + contrast + V4L2_CID_CONTRAST + + + whiteness + V4L2_CID_WHITENESS + + + + + + 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 . + + The depth (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 palette field +moved into the &v4l2-pix-format;: + + + + struct video_picture +palette + &v4l2-pix-format; +pixfmt + + + + + VIDEO_PALETTE_GREY + V4L2_PIX_FMT_GREY + + + VIDEO_PALETTE_HI240 + V4L2_PIX_FMT_HI240 + This is a custom format used by the BTTV +driver, not one of the V4L2 standard formats. + + + + VIDEO_PALETTE_RGB565 + V4L2_PIX_FMT_RGB565 + + + VIDEO_PALETTE_RGB555 + V4L2_PIX_FMT_RGB555 + + + VIDEO_PALETTE_RGB24 + V4L2_PIX_FMT_BGR24 + + + VIDEO_PALETTE_RGB32 + V4L2_PIX_FMT_BGR32 + 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 . + + + + VIDEO_PALETTE_YUV422 + V4L2_PIX_FMT_YUYV + + + VIDEO_PALETTE_YUYV + VIDEO_PALETTE_YUV422 +and VIDEO_PALETTE_YUYV are the same formats. Some +V4L drivers respond to one, some to the other. + + V4L2_PIX_FMT_YUYV + + + VIDEO_PALETTE_UYVY + V4L2_PIX_FMT_UYVY + + + VIDEO_PALETTE_YUV420 + None + + + VIDEO_PALETTE_YUV411 + V4L2_PIX_FMT_Y41P + Not to be confused with +V4L2_PIX_FMT_YUV411P, which is a planar +format. + + + VIDEO_PALETTE_RAW + None V4L explains this +as: "RAW capture (BT848)" + + + VIDEO_PALETTE_YUV422P + V4L2_PIX_FMT_YUV422P + + + VIDEO_PALETTE_YUV411P + V4L2_PIX_FMT_YUV411P + Not to be confused with +V4L2_PIX_FMT_Y41P, which is a packed +format. + + + VIDEO_PALETTE_YUV420P + V4L2_PIX_FMT_YVU420 + + + VIDEO_PALETTE_YUV410P + V4L2_PIX_FMT_YVU410 + + + + + + V4L2 image formats are defined in . The image format can be selected with the +&VIDIOC-S-FMT; ioctl. +
+ +
+ Audio + + The VIDIOCGAUDIO and +VIDIOCSAUDIO ioctl and struct +video_audio 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 . + + The audio "channel number" +field counting audio inputs was renamed to +index. + + On VIDIOCSAUDIO the +mode field selects one +of the VIDEO_SOUND_MONO, +VIDEO_SOUND_STEREO, +VIDEO_SOUND_LANG1 or +VIDEO_SOUND_LANG2 audio demodulation modes. When +the current audio standard is BTSC +VIDEO_SOUND_LANG2 refers to SAP and +VIDEO_SOUND_LANG1 is meaningless. Also +undocumented in the V4L specification, there is no way to query the +selected mode. On VIDIOCGAUDIO the driver returns +the actually received audio programmes in this +field. In the V4L2 API this information is stored in the &v4l2-tuner; +rxsubchans and +audmode fields, respectively. See 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. + + The following fields where replaced by V4L2 controls +accessible with the &VIDIOC-QUERYCTRL;, &VIDIOC-G-CTRL; and +&VIDIOC-S-CTRL; ioctls: + + + + struct +video_audio + V4L2 Control ID + + + + + volume + V4L2_CID_AUDIO_VOLUME + + + bass + V4L2_CID_AUDIO_BASS + + + treble + V4L2_CID_AUDIO_TREBLE + + + balance + V4L2_CID_AUDIO_BALANCE + + + + + + To determine which of these controls are supported by a +driver V4L provides the flags +VIDEO_AUDIO_VOLUME, +VIDEO_AUDIO_BASS, +VIDEO_AUDIO_TREBLE and +VIDEO_AUDIO_BALANCE. In the V4L2 API the +&VIDIOC-QUERYCTRL; ioctl reports if the respective control is +supported. Accordingly the VIDEO_AUDIO_MUTABLE +and VIDEO_AUDIO_MUTE flags where replaced by the +boolean V4L2_CID_AUDIO_MUTE control. + + All V4L2 controls have a step +attribute replacing the struct video_audio +step 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 . +
+ +
+ Frame Buffer Overlay + + The V4L2 ioctls equivalent to +VIDIOCGFBUF and VIDIOCSFBUF +are &VIDIOC-G-FBUF; and &VIDIOC-S-FBUF;. The +base field of struct +video_buffer remained unchanged, except V4L2 +defines a flag to indicate non-destructive overlays instead of a +NULL pointer. All other fields moved into the +&v4l2-pix-format; fmt substructure of +&v4l2-framebuffer;. The depth field was +replaced by pixelformat. See for a list of RGB formats and their +respective color depths. + + Instead of the special ioctls +VIDIOCGWIN and VIDIOCSWIN +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 win +member of the fmt union is used, a +&v4l2-window;. + + The x, +y, width and +height fields of struct +video_window moved into &v4l2-rect; +substructure w of struct +v4l2_window. The +chromakey, +clips, and +clipcount fields remained unchanged. Struct +video_clip was renamed to &v4l2-clip;, also +containing a struct v4l2_rect, but the +semantics are still the same. + + The VIDEO_WINDOW_INTERLACE flag was +dropped. Instead applications must set the +field field to +V4L2_FIELD_ANY or +V4L2_FIELD_INTERLACED. The +VIDEO_WINDOW_CHROMAKEY flag moved into +&v4l2-framebuffer;, under the new name +V4L2_FBUF_FLAG_CHROMAKEY. + + In V4L, storing a bitmap pointer in +clips and setting +clipcount to +VIDEO_CLIP_BITMAP (-1) requests bitmap +clipping, using a fixed size bitmap of 1024 × 625 bits. Struct +v4l2_window has a separate +bitmap pointer field for this purpose and +the bitmap size is determined by w.width and +w.height. + + The VIDIOCCAPTURE ioctl to enable or +disable overlay was renamed to &VIDIOC-OVERLAY;. +
+ +
+ Cropping + + To capture only a subsection of the full picture V4L +defines the VIDIOCGCAPTURE and +VIDIOCSCAPTURE ioctls using struct +video_capture. 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 + for details. + + The x, +y, width and +height fields moved into &v4l2-rect; +substructure c of struct +v4l2_crop. The +decimation 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. + + The VIDEO_CAPTURE_ODD +and VIDEO_CAPTURE_EVEN flags to capture only the +odd or even field, respectively, were replaced by +V4L2_FIELD_TOP and +V4L2_FIELD_BOTTOM in the field named +field of &v4l2-pix-format; and +&v4l2-window;. These structures are used to select a capture or +overlay format with the &VIDIOC-S-FMT; ioctl. +
+ +
+ Reading Images, Memory Mapping + +
+ Capturing using the read method + + 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. + + To select an image format and size, V4L provides the +VIDIOCSPICT and VIDIOCSWIN +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 +pix of its fmt +union is used. + + For more information about the V4L2 read interface see +. +
+
+ Capturing using memory mapping + + 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. + + + + + + V4L + V4L2 + + + + + + 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. + + + 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. + The &VIDIOC-REQBUFS; ioctl allocates the +desired number of buffers, this is a required step in the initialization +sequence. + + + Drivers map all buffers as one contiguous +range of memory. The VIDIOCGMBUF 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. + Buffers are individually mapped. The +offset and size of each buffer can be determined with the +&VIDIOC-QUERYBUF; ioctl. + + + The VIDIOCMCAPTURE +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.The VIDIOCSYNC ioctl +suspends execution until a particular buffer has been +filled. + 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. + + + + + + For a more in-depth discussion of memory mapping and +examples, see . +
+
+ +
+ Reading Raw VBI Data + + Originally the V4L API did not specify a raw VBI capture +interface, only the device file /dev/vbi 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: + + + + &v4l2-vbi-format; + V4L, BTTV driver + + + + + sampling_rate + 28636363 Hz NTSC (or any other 525-line +standard); 35468950 Hz PAL and SECAM (625-line standards) + + + offset + ? + + + samples_per_line + 2048 + + + sample_format + V4L2_PIX_FMT_GREY. The last four bytes (a +machine endianess integer) contain a frame counter. + + + start[] + 10, 273 NTSC; 22, 335 PAL and SECAM + + + count[] + 16, 16Old driver +versions used different values, eventually the custom +BTTV_VBISIZE ioctl was added to query the +correct values. + + + flags + 0 + + + + + + Undocumented in the V4L specification, in Linux 2.3 the +VIDIOCGVBIFMT and +VIDIOCSVBIFMT ioctls using struct +vbi_format were added to determine the VBI +image parameters. These ioctls are only partially compatible with the +V4L2 VBI interface specified in . + + An offset field does not +exist, sample_format is supposed to be +VIDEO_PALETTE_RAW, equivalent to +V4L2_PIX_FMT_GREY. The remaining fields are +probably equivalent to &v4l2-vbi-format;. + + 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 +VIDIOCSVBIFMT always returns an &EINVAL; if the +parameters are invalid. +
+ +
+ Miscellaneous + + V4L2 has no equivalent of the +VIDIOCGUNIT 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 +. + + No replacement exists for VIDIOCKEY, +and the V4L functions for microcode programming. A new interface for +MPEG compression and playback devices is documented in . +
+ +
+ +
+ Changes of the V4L2 API + + 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. + +
+ Early Versions + 1998-08-20: First version. + + 1998-08-27: The &func-select; function was introduced. + + 1998-09-10: New video standard interface. + + 1998-09-18: The VIDIOC_NONCAP ioctl +was replaced by the otherwise meaningless O_TRUNC +&func-open; flag, and the aliases O_NONCAP and +O_NOIO were defined. Applications can set this +flag if they intend to access controls only, as opposed to capture +applications which need exclusive access. The +VIDEO_STD_XXX identifiers are now ordinals +instead of flags, and the video_std_construct() +helper function takes id and transmission arguments. + + 1998-09-28: Revamped video standard. Made video controls +individually enumerable. + + 1998-10-02: The id field was +removed from struct video_standard 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. + + 1998-11-08: Many minor changes. Most symbols have been +renamed. Some material changes to &v4l2-capability;. + + 1998-11-12: The read/write directon of some ioctls was misdefined. + + 1998-11-14: V4L2_PIX_FMT_RGB24 +changed to V4L2_PIX_FMT_BGR24, and +V4L2_PIX_FMT_RGB32 changed to +V4L2_PIX_FMT_BGR32. Audio controls are now +accessible with the &VIDIOC-G-CTRL; and &VIDIOC-S-CTRL; ioctls under +names starting with V4L2_CID_AUDIO. The +V4L2_MAJOR define was removed from +videodev.h since it was only used once in the +videodev kernel module. The +YUV422 and YUV411 planar +image formats were added. + + 1998-11-28: A few ioctl symbols changed. Interfaces for codecs and +video output devices were added. + + 1999-01-14: A raw VBI capture interface was added. + + 1999-01-19: The VIDIOC_NEXTBUF ioctl + was removed. +
+ +
+ V4L2 Version 0.16 1999-01-31 + 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. +
+ + + +
+ V4L2 Version 0.18 1999-03-16 + 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. +
+ +
+ V4L2 Version 0.19 1999-06-05 + 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. + 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. + 1999-04-04: Added a few more control IDs. + 1999-04-07: Added the button control type. + 1999-05-02: Fixed a typo in videodev.h, and added the +V4L2_CTRL_FLAG_GRAYED (later V4L2_CTRL_FLAG_GRABBED) flag. + 1999-05-20: Definition of VIDIOC_G_CTRL was wrong causing +a malfunction of this ioctl. + 1999-06-05: Changed the value of +V4L2_CID_WHITENESS. +
+ +
+ V4L2 Version 0.20 (1999-09-10) + + Version 0.20 introduced a number of changes which were +not backward compatible 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. + + + + Some typos in V4L2_FMT_FLAG +symbols were fixed. &v4l2-clip; was changed for compatibility with +v4l. (1999-08-30) + + + + V4L2_TUNER_SUB_LANG1 was added. +(1999-09-05) + + + + 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 + +err = ioctl (fd, VIDIOC_XXX, V4L2_XXX); + becomes +int a = V4L2_XXX; err = ioctl(fd, VIDIOC_XXX, &a); + + + + + + 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. + + This change obsoletes the following ioctls: +VIDIOC_S_INFMT, +VIDIOC_G_INFMT, +VIDIOC_S_OUTFMT, +VIDIOC_G_OUTFMT, +VIDIOC_S_VBIFMT and +VIDIOC_G_VBIFMT. The image format structure +v4l2_format was renamed to &v4l2-pix-format;, +while &v4l2-format; is now the envelopping structure for all format +negotiations. + + + + Similar to the changes above, the +VIDIOC_G_PARM and +VIDIOC_S_PARM ioctls were merged with +VIDIOC_G_OUTPARM and +VIDIOC_S_OUTPARM. A +type field in the new &v4l2-streamparm; +selects the respective union member. + + This change obsoletes the +VIDIOC_G_OUTPARM and +VIDIOC_S_OUTPARM ioctls. + + + + Control enumeration was simplified, and two new +control flags were introduced and one dropped. The +catname field was replaced by a +group field. + + Drivers can now flag unsupported and temporarily +unavailable controls with V4L2_CTRL_FLAG_DISABLED +and V4L2_CTRL_FLAG_GRABBED respectively. The +group name indicates a possibly narrower +classification than the category. In other +words, there may be multiple groups within a category. Controls within +a group would typically be drawn within a group box. Controls in +different categories might have a greater separation, or may even +appear in separate windows. + + + + The &v4l2-buffer; timestamp +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. + + + + A sequence field was added +to &v4l2-buffer;. The sequence 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. + + +
+ +
+ V4L2 Version 0.20 incremental changes + + + 1999-12-23: In &v4l2-vbi-format; the +reserved1 field became +offset. Previously drivers were required to +clear the reserved1 field. + + 2000-01-13: The + V4L2_FMT_FLAG_NOT_INTERLACED flag was added. + + 2000-07-31: The linux/poll.h header +is now included by videodev.h for compatibility +with the original videodev.h file. + + 2000-11-20: V4L2_TYPE_VBI_OUTPUT and +V4L2_PIX_FMT_Y41P were added. + + 2000-11-25: V4L2_TYPE_VBI_INPUT was +added. + + 2000-12-04: A couple typos in symbol names were fixed. + + 2001-01-18: To avoid namespace conflicts the +fourcc macro defined in the +videodev.h header file was renamed to +v4l2_fourcc. + + 2001-01-25: A possible driver-level compatibility problem +between the videodev.h file in Linux 2.4.0 and +the videodev.h file included in the +videodevX patch was fixed. Users of an earlier +version of videodevX on Linux 2.4.0 should +recompile their V4L and V4L2 drivers. + + 2001-01-26: A possible kernel-level incompatibility +between the videodev.h file in the +videodevX patch and the +videodev.h file in Linux 2.2.x with devfs patches +applied was fixed. + + 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?] + + 2001-04-13: Big endian 16-bit RGB formats were added. + + 2001-09-17: New YUV formats and the &VIDIOC-G-FREQUENCY; and +&VIDIOC-S-FREQUENCY; ioctls were added. (The old +VIDIOC_G_FREQ and +VIDIOC_S_FREQ ioctls did not take multiple tuners +into account.) + + 2000-09-18: V4L2_BUF_TYPE_VBI was +added. This may break compatibility as the +&VIDIOC-G-FMT; and &VIDIOC-S-FMT; ioctls may fail now if the struct +v4l2_fmt type +field does not contain V4L2_BUF_TYPE_VBI. In the +documentation of the &v4l2-vbi-format; +offset field the ambiguous phrase "rising +edge" was changed to "leading edge". +
+ +
+ V4L2 Version 0.20 2000-11-23 + + A number of changes were made to the raw VBI +interface. + + + + Figures clarifying the line numbering scheme were +added to the V4L2 API specification. The +start[0] and +start[1] fields no longer count line +numbers beginning at zero. Rationale: a) The previous definition was +unclear. b) The start[] 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. + + + + The restriction "count[0] > 0 and count[1] > 0" +has been relaxed to "(count[0] + count[1]) > 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 count values will usually be equal is +misleading and pointless and has been removed. This change +breaks compatibility with earlier versions: +Drivers may return EINVAL, applications may not function +correctly. + + + + Drivers are again permitted to return negative +(unknown) start values as proposed earlier. Why this feature was +dropped is unclear. This change may break +compatibility with applications depending on the start +values being positive. The use of EBUSY and +EINVAL error codes with the &VIDIOC-S-FMT; ioctl +was clarified. The &EBUSY; was finally documented, and the +reserved2 field which was previously +mentioned only in the videodev.h header +file. + + + + New buffer types +V4L2_TYPE_VBI_INPUT and +V4L2_TYPE_VBI_OUTPUT were added. The former is an +alias for the old V4L2_TYPE_VBI, the latter was +missing in the videodev.h file. + + +
+ +
+ V4L2 Version 0.20 2002-07-25 + Added sliced VBI interface proposal. +
+ +
+ V4L2 in Linux 2.5.46, 2002-10 + + 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. + + + + As specified in , drivers +must make related device functions available under all minor device +numbers. + + + + The &func-open; function requires access mode +O_RDWR regardless of the device type. All V4L2 +drivers exchanging data with applications must support the +O_NONBLOCK flag. The O_NOIO +flag, a V4L2 symbol which aliased the meaningless +O_TRUNC 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 +. + + + + 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. + + There are new fields to identify the driver, a new RDS +device function V4L2_CAP_RDS_CAPTURE, the +V4L2_CAP_AUDIO flag indicates if the device has +any audio connectors, another I/O capability +V4L2_CAP_ASYNCIO can be flagged. In response to +these changes the type field became a bit +set and was merged into the flags field. +V4L2_FLAG_TUNER was renamed to +V4L2_CAP_TUNER, +V4L2_CAP_VIDEO_OVERLAY replaced +V4L2_FLAG_PREVIEW and +V4L2_CAP_VBI_CAPTURE and +V4L2_CAP_VBI_OUTPUT replaced +V4L2_FLAG_DATA_SERVICE. +V4L2_FLAG_READ and +V4L2_FLAG_WRITE were merged into +V4L2_CAP_READWRITE. + + The redundant fields +inputs, outputs +and audios were removed. These properties +can be determined as described in and . + + The somewhat volatile and therefore barely useful +fields maxwidth, +maxheight, +minwidth, +minheight, +maxframerate were removed. This information +is available as described in and +. + + V4L2_FLAG_SELECT 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 V4L2_FLAG_MONOCHROME flag was removed, +this information is available as described in . + + + + In &v4l2-input; the +assoc_audio field and the +capability field and its only flag +V4L2_INPUT_CAP_AUDIO was replaced by the new +audioset field. Instead of linking one +video input to one audio input this field reports all audio inputs +this video input combines with. + + New fields are tuner +(reversing the former link from tuners to video inputs), +std and +status. + + Accordingly &v4l2-output; lost its +capability and +assoc_audio fields. +audioset, +modulator and +std where added instead. + + + + The &v4l2-audio; field +audio was renamed to +index, for consistency with other +structures. A new capability flag +V4L2_AUDCAP_STEREO was added to indicated if the +audio input in question supports stereo sound. +V4L2_AUDCAP_EFFECTS and the corresponding +V4L2_AUDMODE flags where removed. This can be +easily implemented using controls. (However the same applies to AVL +which is still there.) + + Again for consistency the &v4l2-audioout; field +audio was renamed to +index. + + + + The &v4l2-tuner; +input field was replaced by an +index field, permitting devices with +multiple tuners. The link between video inputs and tuners is now +reversed, inputs point to their tuner. The +std substructure became a +simple set (more about this below) and moved into &v4l2-input;. A +type field was added. + + Accordingly in &v4l2-modulator; the +output was replaced by an +index field. + + In &v4l2-frequency; the +port field was replaced by a +tuner field containing the respective tuner +or modulator index number. A tuner type +field was added and the reserved field +became larger for future extensions (satellite tuners in +particular). + + + + 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 +videodev2.h header file. For details see . 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 +index field was added for &VIDIOC-ENUMSTD;. +A &v4l2-std-id; field named id was added as +machine readable identifier, also replacing the +transmission field. The misleading +framerate field was renamed +to frameperiod. The now obsolete +colorstandard information, originally +needed to distguish between variations of standards, were +removed. + + Struct v4l2_enumstd 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 std, +respectively. + + + + The &v4l2-queryctrl; fields +category and +group did not catch on and/or were not +implemented as expected and therefore removed. + + + + 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. + + In &v4l2-format; the fmt +union was extended to contain &v4l2-window;. All image format +negotiations are now possible with VIDIOC_G_FMT, +VIDIOC_S_FMT and +VIDIOC_TRY_FMT; ioctl. The +VIDIOC_G_WIN and +VIDIOC_S_WIN ioctls to prepare for a video +overlay were removed. The type field +changed to type &v4l2-buf-type; and the buffer type names changed as +follows. + + + + Old defines + &v4l2-buf-type; + + + + + V4L2_BUF_TYPE_CAPTURE + V4L2_BUF_TYPE_VIDEO_CAPTURE + + + V4L2_BUF_TYPE_CODECIN + Omitted for now + + + V4L2_BUF_TYPE_CODECOUT + Omitted for now + + + V4L2_BUF_TYPE_EFFECTSIN + Omitted for now + + + V4L2_BUF_TYPE_EFFECTSIN2 + Omitted for now + + + V4L2_BUF_TYPE_EFFECTSOUT + Omitted for now + + + V4L2_BUF_TYPE_VIDEOOUT + V4L2_BUF_TYPE_VIDEO_OUTPUT + + + - + V4L2_BUF_TYPE_VIDEO_OVERLAY + + + - + V4L2_BUF_TYPE_VBI_CAPTURE + + + - + V4L2_BUF_TYPE_VBI_OUTPUT + + + - + V4L2_BUF_TYPE_SLICED_VBI_CAPTURE + + + - + V4L2_BUF_TYPE_SLICED_VBI_OUTPUT + + + V4L2_BUF_TYPE_PRIVATE_BASE + V4L2_BUF_TYPE_PRIVATE + + + + + + + + In &v4l2-fmtdesc; a &v4l2-buf-type; field named +type was added as in &v4l2-format;. The +VIDIOC_ENUM_FBUFFMT ioctl is no longer needed and +was removed. These calls can be replaced by &VIDIOC-ENUM-FMT; with +type V4L2_BUF_TYPE_VIDEO_OVERLAY. + + + + In &v4l2-pix-format; the +depth 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 +V4L2_FMT_FLAG_COMPRESSED flag. The +V4L2_FMT_FLAG_SWCONVECOMPRESSED 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 +V4L2_FMT_FLAG_BYTESPERLINE flag was redundant. +Applications can set the bytesperline field +to zero to get a reasonable default. Since the remaining flags were +replaced as well, the flags field itself +was removed. + The interlace flags were replaced by a &v4l2-field; +value in a newly added field +field. + + + + Old flag + &v4l2-field; + + + + + V4L2_FMT_FLAG_NOT_INTERLACED + ? + + + V4L2_FMT_FLAG_INTERLACED += V4L2_FMT_FLAG_COMBINED + V4L2_FIELD_INTERLACED + + + V4L2_FMT_FLAG_TOPFIELD += V4L2_FMT_FLAG_ODDFIELD + V4L2_FIELD_TOP + + + V4L2_FMT_FLAG_BOTFIELD += V4L2_FMT_FLAG_EVENFIELD + V4L2_FIELD_BOTTOM + + + - + V4L2_FIELD_SEQ_TB + + + - + V4L2_FIELD_SEQ_BT + + + - + V4L2_FIELD_ALTERNATE + + + + + + The color space flags were replaced by a +&v4l2-colorspace; value in a newly added +colorspace field, where one of +V4L2_COLORSPACE_SMPTE170M, +V4L2_COLORSPACE_BT878, +V4L2_COLORSPACE_470_SYSTEM_M or +V4L2_COLORSPACE_470_SYSTEM_BG replaces +V4L2_FMT_CS_601YUV. + + + + In &v4l2-requestbuffers; the +type field was properly defined as +&v4l2-buf-type;. Buffer types changed as mentioned above. A new +memory field of type &v4l2-memory; was +added to distinguish between I/O methods using buffers allocated +by the driver or the application. See for +details. + + + + In &v4l2-buffer; the type +field was properly defined as &v4l2-buf-type;. Buffer types changed as +mentioned above. A field 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 +timestamp field changed back from type +stamp_t, an unsigned 64 bit integer expressing the sample time in +nanoseconds, to struct timeval. With the +addition of a second memory mapping method the +offset field moved into union +m, and a new +memory field of type &v4l2-memory; was +added to distinguish between I/O methods. See +for details. + + The V4L2_BUF_REQ_CONTIG +flag was used by the V4L compatibility layer, after changes to this +code it was no longer needed. The +V4L2_BUF_ATTR_DEVICEMEM 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. + + + + In &v4l2-framebuffer; the +base[3] array anticipating double- and +triple-buffering in off-screen video memory, however without defining +a synchronization mechanism, was replaced by a single pointer. The +V4L2_FBUF_CAP_SCALEUP and +V4L2_FBUF_CAP_SCALEDOWN flags were removed. +Applications can determine this capability more accurately using the +new cropping and scaling interface. The +V4L2_FBUF_CAP_CLIPPING flag was replaced by +V4L2_FBUF_CAP_LIST_CLIPPING and +V4L2_FBUF_CAP_BITMAP_CLIPPING. + + + + In &v4l2-clip; the x, +y, width and +height field moved into a +c substructure of type &v4l2-rect;. The +x and y fields +were renamed to left and +top, &ie; offsets to a context dependent +origin. + + + + In &v4l2-window; the x, +y, width and +height field moved into a +w substructure as above. A +field field of type %v4l2-field; was added +to distinguish between field and frame (interlaced) overlay. + + + + The digital zoom interface, including struct +v4l2_zoomcap, struct +v4l2_zoom, +V4L2_ZOOM_NONCAP and +V4L2_ZOOM_WHILESTREAMING was replaced by a new +cropping and scaling interface. The previously unused struct +v4l2_cropcap and +v4l2_crop where redefined for this purpose. +See for details. + + + + In &v4l2-vbi-format; the +SAMPLE_FORMAT field now contains a +four-character-code as used to identify video image formats and +V4L2_PIX_FMT_GREY replaces the +V4L2_VBI_SF_UBYTE define. The +reserved field was extended. + + + + In &v4l2-captureparm; the type of the +timeperframe 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 +readbuffers was added to control the driver +behaviour in read I/O mode. + + Similar changes were made to &v4l2-outputparm;. + + + + The struct v4l2_performance +and VIDIOC_G_PERF ioctl were dropped. Except when +using the read/write I/O method, which is +limited anyway, this information is already available to +applications. + + + + The example transformation from RGB to YCbCr color +space in the old V4L2 documentation was inaccurate, this has been +corrected in . + + +
+ +
+ V4L2 2003-06-19 + + + + A new capability flag +V4L2_CAP_RADIO was added for radio devices. Prior +to this change radio devices would identify solely by having exactly one +tuner whose type field reads V4L2_TUNER_RADIO. + + + + An optional driver access priority mechanism was +added, see for details. + + + + The audio input and output interface was found to be +incomplete. + 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 +VIDIOC_G_AUDIO was renamed to +VIDIOC_G_AUDIO_OLD, this ioctl was removed on +Kernel 2.6.39. The &VIDIOC-ENUMAUDIO; ioctl was added to enumerate +audio inputs, while &VIDIOC-G-AUDIO; now reports the current audio +input. + The same changes were made to &VIDIOC-G-AUDOUT; and +&VIDIOC-ENUMAUDOUT;. + 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. + + + + 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 VIDIOC_OVERLAY_OLD. The old +ioctl was removed on Kernel 2.6.39. Until further the "videodev" +kernel module will automatically translate to the new version, so drivers +must be recompiled, but not applications. + + + + incorrectly stated that +clipping rectangles define regions where the video can be seen. +Correct is that clipping rectangles define regions where +no video shall be displayed and so the graphics +surface can be seen. + + + + 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 +_OLD suffix was added to the write-only versions. +The old ioctls were removed on Kernel 2.6.39. Drivers and +applications assuming a constant parameter need an update. + + +
+ +
+ V4L2 2003-11-05 + + + In the following pixel +formats were incorrectly transferred from Bill Dirks' V4L2 +specification. Descriptions below refer to bytes in memory, in +ascending address order. + + + + Symbol + In this document prior to revision +0.5 + Corrected + + + + + V4L2_PIX_FMT_RGB24 + B, G, R + R, G, B + + + V4L2_PIX_FMT_BGR24 + R, G, B + B, G, R + + + V4L2_PIX_FMT_RGB32 + B, G, R, X + R, G, B, X + + + V4L2_PIX_FMT_BGR32 + R, G, B, X + B, G, R, X + + + + The +V4L2_PIX_FMT_BGR24 example was always +correct. + In the mapping +of the V4L VIDEO_PALETTE_RGB24 and +VIDEO_PALETTE_RGB32 formats to V4L2 pixel formats +was accordingly corrected. + + + + 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 . + + +
+ +
+ V4L2 in Linux 2.6.6, 2004-05-09 + + + 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 +VIDIOC_CROPCAP_OLD. The old ioctl was removed +on Kernel 2.6.39. + + +
+ +
+ V4L2 in Linux 2.6.8 + + + A new field input (former +reserved[0]) was added to the &v4l2-buffer; +structure. Purpose of this field is to alternate between video inputs +(⪚ cameras) in step with the video capturing process. This function +must be enabled with the new V4L2_BUF_FLAG_INPUT +flag. The flags field is no longer +read-only. + + +
+ +
+ V4L2 spec erratum 2004-08-01 + + + + The return value of the + function was incorrectly documented. + + + + Audio output ioctls end in -AUDOUT, not -AUDIOOUT. + + + + In the Current Audio Input example the +VIDIOC_G_AUDIO ioctl took the wrong +argument. + + + + The documentation of the &VIDIOC-QBUF; and +&VIDIOC-DQBUF; ioctls did not mention the &v4l2-buffer; +memory field. It was also missing from +examples. Also on the VIDIOC_DQBUF page the &EIO; +was not documented. + + +
+ +
+ V4L2 in Linux 2.6.14 + + + A new sliced VBI interface was added. It is documented +in and replaces the interface first +proposed in V4L2 specification 0.8. + + +
+ +
+ V4L2 in Linux 2.6.15 + + + The &VIDIOC-LOG-STATUS; ioctl was added. + + + + New video standards +V4L2_STD_NTSC_443, +V4L2_STD_SECAM_LC, +V4L2_STD_SECAM_DK (a set of SECAM D, K and K1), +and V4L2_STD_ATSC (a set of +V4L2_STD_ATSC_8_VSB and +V4L2_STD_ATSC_16_VSB) were defined. Note the +V4L2_STD_525_60 set now includes +V4L2_STD_NTSC_443. See also . + + + + The VIDIOC_G_COMP and +VIDIOC_S_COMP ioctl were renamed to +VIDIOC_G_MPEGCOMP and +VIDIOC_S_MPEGCOMP respectively. Their argument +was replaced by a struct +v4l2_mpeg_compression pointer. (The +VIDIOC_G_MPEGCOMP and +VIDIOC_S_MPEGCOMP ioctls where removed in Linux +2.6.25.) + + +
+ +
+ V4L2 spec erratum 2005-11-27 + The capture example in +called the &VIDIOC-S-CROP; ioctl without checking if cropping is +supported. In the video standard selection example in + the &VIDIOC-S-STD; call used the wrong +argument type. +
+ +
+ V4L2 spec erratum 2006-01-10 + + + The V4L2_IN_ST_COLOR_KILL 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.) + + + + &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. + + +
+ +
+ V4L2 spec erratum 2006-02-03 + + + In &v4l2-captureparm; and &v4l2-outputparm; the +timeperframe field gives the time in +seconds, not microseconds. + + +
+ +
+ V4L2 spec erratum 2006-02-04 + + + The clips field in +&v4l2-window; must point to an array of &v4l2-clip;, not a linked +list, because drivers ignore the struct +v4l2_clip.next +pointer. + + +
+ +
+ V4L2 in Linux 2.6.17 + + + New video standard macros were added: +V4L2_STD_NTSC_M_KR (NTSC M South Korea), and the +sets V4L2_STD_MN, +V4L2_STD_B, V4L2_STD_GH and +V4L2_STD_DK. The +V4L2_STD_NTSC and +V4L2_STD_SECAM sets now include +V4L2_STD_NTSC_M_KR and +V4L2_STD_SECAM_LC respectively. + + + + A new V4L2_TUNER_MODE_LANG1_LANG2 +was defined to record both languages of a bilingual program. The +use of V4L2_TUNER_MODE_STEREO for this purpose +is deprecated now. See the &VIDIOC-G-TUNER; section for +details. + + +
+ +
+ V4L2 spec erratum 2006-09-23 (Draft 0.15) + + + In various places +V4L2_BUF_TYPE_SLICED_VBI_CAPTURE and +V4L2_BUF_TYPE_SLICED_VBI_OUTPUT of the sliced VBI +interface were not mentioned along with other buffer types. + + + + In it was clarified +that the &v4l2-audio; mode field is a flags +field. + + + + did not mention the +sliced VBI and radio capability flags. + + + + In it was +clarified that applications must initialize the tuner +type field of &v4l2-frequency; before +calling &VIDIOC-S-FREQUENCY;. + + + + The reserved array +in &v4l2-requestbuffers; has 2 elements, not 32. + + + + In and the device file names +/dev/vout which never caught on were replaced +by /dev/video. + + + + 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 +/dev/vbi0 to /dev/vbi31 are +possible now. + + +
+ +
+ V4L2 in Linux 2.6.18 + + + 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 +V4L2_CTRL_TYPE_INTEGER64 and +V4L2_CTRL_TYPE_CTRL_CLASS (), and new control flags +V4L2_CTRL_FLAG_READ_ONLY, +V4L2_CTRL_FLAG_UPDATE, +V4L2_CTRL_FLAG_INACTIVE and +V4L2_CTRL_FLAG_SLIDER (). See for details. + + +
+ +
+ V4L2 in Linux 2.6.19 + + + 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 break the +compatibility with older drivers and applications. + + + + The ioctls &VIDIOC-ENUM-FRAMESIZES; and +&VIDIOC-ENUM-FRAMEINTERVALS; were added. + + + + A new pixel format V4L2_PIX_FMT_RGB444 () was added. + + +
+ +
+ V4L2 spec erratum 2006-10-12 (Draft 0.17) + + + V4L2_PIX_FMT_HM12 () is a YUV 4:2:0, not 4:2:2 format. + + +
+ +
+ V4L2 in Linux 2.6.21 + + + The videodev2.h header file is +now dual licensed under GNU General Public License version two or +later, and under a 3-clause BSD-style license. + + +
+ +
+ V4L2 in Linux 2.6.22 + + + Two new field orders + V4L2_FIELD_INTERLACED_TB and + V4L2_FIELD_INTERLACED_BT were + added. See for details. + + + + 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. + A new global_alpha field +was added to v4l2_window, +extending the structure. This may break +compatibility with applications using a struct +v4l2_window directly. However the VIDIOC_G/S/TRY_FMT ioctls, which take a +pointer to a v4l2_format parent +structure with padding bytes at the end, are not affected. + + + + The format of the chromakey +field in &v4l2-window; changed from "host order RGB32" to a pixel +value in the same format as the framebuffer. This may break +compatibility with existing applications. Drivers +supporting the "host order RGB32" format are not known. + + + +
+ +
+ V4L2 in Linux 2.6.24 + + + The pixel formats +V4L2_PIX_FMT_PAL8, +V4L2_PIX_FMT_YUV444, +V4L2_PIX_FMT_YUV555, +V4L2_PIX_FMT_YUV565 and +V4L2_PIX_FMT_YUV32 were added. + + +
+ +
+ V4L2 in Linux 2.6.25 + + + The pixel formats +V4L2_PIX_FMT_Y16 and +V4L2_PIX_FMT_SBGGR16 were added. + + + New controls +V4L2_CID_POWER_LINE_FREQUENCY, +V4L2_CID_HUE_AUTO, +V4L2_CID_WHITE_BALANCE_TEMPERATURE, +V4L2_CID_SHARPNESS and +V4L2_CID_BACKLIGHT_COMPENSATION were added. The +controls V4L2_CID_BLACK_LEVEL, +V4L2_CID_WHITENESS, +V4L2_CID_HCENTER and +V4L2_CID_VCENTER were deprecated. + + + + A Camera controls +class was added, with the new controls +V4L2_CID_EXPOSURE_AUTO, +V4L2_CID_EXPOSURE_ABSOLUTE, +V4L2_CID_EXPOSURE_AUTO_PRIORITY, +V4L2_CID_PAN_RELATIVE, +V4L2_CID_TILT_RELATIVE, +V4L2_CID_PAN_RESET, +V4L2_CID_TILT_RESET, +V4L2_CID_PAN_ABSOLUTE, +V4L2_CID_TILT_ABSOLUTE, +V4L2_CID_FOCUS_ABSOLUTE, +V4L2_CID_FOCUS_RELATIVE and +V4L2_CID_FOCUS_AUTO. + + + The VIDIOC_G_MPEGCOMP and +VIDIOC_S_MPEGCOMP ioctls, which were superseded +by the extended controls +interface in Linux 2.6.18, where finally removed from the +videodev2.h header file. + + +
+ +
+ V4L2 in Linux 2.6.26 + + + The pixel formats +V4L2_PIX_FMT_Y16 and +V4L2_PIX_FMT_SBGGR16 were added. + + + Added user controls +V4L2_CID_CHROMA_AGC and +V4L2_CID_COLOR_KILLER. + + +
+ +
+ V4L2 in Linux 2.6.27 + + + The &VIDIOC-S-HW-FREQ-SEEK; ioctl and the +V4L2_CAP_HW_FREQ_SEEK capability were added. + + + The pixel formats +V4L2_PIX_FMT_YVYU, +V4L2_PIX_FMT_PCA501, +V4L2_PIX_FMT_PCA505, +V4L2_PIX_FMT_PCA508, +V4L2_PIX_FMT_PCA561, +V4L2_PIX_FMT_SGBRG8, +V4L2_PIX_FMT_PAC207 and +V4L2_PIX_FMT_PJPG were added. + + +
+ +
+ V4L2 in Linux 2.6.28 + + + Added V4L2_MPEG_AUDIO_ENCODING_AAC and +V4L2_MPEG_AUDIO_ENCODING_AC3 MPEG audio encodings. + + + Added V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC MPEG +video encoding. + + + The pixel formats +V4L2_PIX_FMT_SGRBG10 and +V4L2_PIX_FMT_SGRBG10DPCM8 were added. + + +
+ +
+ V4L2 in Linux 2.6.29 + + + The VIDIOC_G_CHIP_IDENT ioctl was renamed +to VIDIOC_G_CHIP_IDENT_OLD and &VIDIOC-DBG-G-CHIP-IDENT; +was introduced in its place. The old struct v4l2_chip_ident +was renamed to v4l2_chip_ident_old. + + + The pixel formats +V4L2_PIX_FMT_VYUY, +V4L2_PIX_FMT_NV16 and +V4L2_PIX_FMT_NV61 were added. + + + Added camera controls +V4L2_CID_ZOOM_ABSOLUTE, +V4L2_CID_ZOOM_RELATIVE, +V4L2_CID_ZOOM_CONTINUOUS and +V4L2_CID_PRIVACY. + + +
+
+ V4L2 in Linux 2.6.30 + + + New control flag V4L2_CTRL_FLAG_WRITE_ONLY was added. + + + New control V4L2_CID_COLORFX was added. + + +
+
+ V4L2 in Linux 2.6.32 + + + 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. + + + Finalized the RDS capture API. See for +more information. + + + Added new capabilities for modulators and RDS encoders. + + + Add description for libv4l API. + + + Added support for string controls via new type V4L2_CTRL_TYPE_STRING. + + + Added V4L2_CID_BAND_STOP_FILTER documentation. + + + Added FM Modulator (FM TX) Extended Control Class: V4L2_CTRL_CLASS_FM_TX and their Control IDs. + + + Added Remote Controller chapter, describing the default Remote Controller mapping for media devices. + + +
+
+ V4L2 in Linux 2.6.33 + + + Added support for Digital Video timings in order to support HDTV receivers and transmitters. + + +
+
+ V4L2 in Linux 2.6.34 + + + Added +V4L2_CID_IRIS_ABSOLUTE and +V4L2_CID_IRIS_RELATIVE controls to the + Camera controls class. + + + +
+
+ V4L2 in Linux 2.6.37 + + + 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. + + + +
+
+ V4L2 in Linux 2.6.39 + + + The old VIDIOC_*_OLD symbols and V4L1 support were removed. + + + Multi-planar API added. Does not affect the compatibility of + current drivers and applications. See + multi-planar API + for details. + + +
+ +
+ Relation of V4L2 to other Linux multimedia APIs + +
+ X Video Extension + + 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 + This is not implemented in XFree86. + . With their implementation XFree86 makes the +extension available across many operating systems and +architectures. + + Because the driver is embedded into the X server Xv has a +number of advantages over the V4L2 video +overlay interface. 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. + + 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 +/etc/X11/XF86Config must contain these lines: + +Section "Module" + Load "v4l" +EndSection + + 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 apply. + + 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. +
+ +
+ Digital Video + + V4L2 does not support digital terrestrial, cable or +satellite broadcast. A separate project aiming at digital receivers +exists. You can find its homepage at http://linuxtv.org. The Linux DVB API +has no connection to the V4L2 API except that drivers for hybrid +hardware may support both. +
+ +
+ Audio Interfaces + + [to do - OSS/ALSA] +
+
+ +
+ Experimental API Elements + + The following V4L2 API elements are currently experimental +and may change in the future. + + + + Video Output Overlay (OSD) Interface, . + + + V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY, + &v4l2-buf-type;, . + + + V4L2_CAP_VIDEO_OUTPUT_OVERLAY, +&VIDIOC-QUERYCAP; ioctl, . + + + &VIDIOC-ENUM-FRAMESIZES; and +&VIDIOC-ENUM-FRAMEINTERVALS; ioctls. + + + &VIDIOC-G-ENC-INDEX; ioctl. + + + &VIDIOC-ENCODER-CMD; and &VIDIOC-TRY-ENCODER-CMD; +ioctls. + + + &VIDIOC-DBG-G-REGISTER; and &VIDIOC-DBG-S-REGISTER; +ioctls. + + + &VIDIOC-DBG-G-CHIP-IDENT; ioctl. + + +
+ +
+ Obsolete API Elements + + The following V4L2 API elements were superseded by new +interfaces and should not be implemented in new drivers. + + + + VIDIOC_G_MPEGCOMP and +VIDIOC_S_MPEGCOMP ioctls. Use Extended Controls, +. + + +
+
+ + -- cgit v1.2.3