Xf86-video-v4l

Note: There are portions of this article that are straight verbatim of content parsed from several different sources (cited inline or referenced at the end in the article's external links) -- that notable content has just been logically stitched together to form a more comprehensive overview of the topic.

xf86-video-v4l is an old Xv ddx driver for video4linux devices. It is not a conventional ddx and does not allow you to run X on your V4L device. Rather, its a special generic capture driver included in Xorg.

The Technical Mumbo-Jumbo

You see

The X Video Extension (abbreviated XVideo or just Xv) is an extension of the X Window system.... Its scope is similar to V4L2, an API to video capture and output devices for X clients {for further description, see the V4L2 API},. Xv allows applications to display live video in a window, send window contents to a TV output, and capture or output still images ... Because the {Xv} driver is embedded into the X server, Xv has a number of advantages over the V4L2 video overlay interface. The {Xv} driver can easily determine the overlay target, i.e. 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....{So,} to combine the advantages of {both} Xv and V4L, a special Xv driver exists in XFree86 and XOrg, {which} just programm{es} any overlay capable Video4Linux device it finds.

In essence, video-v4l is a Xv ddx that exposes V4L devices as Xv ports. It's basically a helper module so that the V4L devices can stream data directly to an Xv buffer in GPU accessible memory, saving some memcpys when displaying video from the v4l device.

What the driver basically does is to check the Xv extension of the screen, using xf86XVQueryOffscreenImages(), selecting a FOURCC mode that it is compatible with a video capture board. Then, it passes a memory address at the video board where the overlay should be placed to the kernel driver. The kernel driver will then program the device's DMA to do data transfer from the capture board into the video board.

When this driver is installed and configured properly, then an X11 client application can use the XvPutVideo function to cause a captured video stream to be directly written to the applicable screen's frame buffer or video overlay buffer. This permits the use of hardware DMA capabilities to transfer the captured video directly from {for example} a PCI {V4L} card via the PCI bus to the graphics adaptor's frame buffer memory. In contrast, if XvPutImage is used instead of XvPutVideo, then all video frames must first pass through system memory, placing a heavier burden on system memory throughput.

So its a special generic capture driver, that

• works with every piece of hardware which is supported by a video4linux (kernel-) device driver … it works with any hardware supported by a Video 4 Linux (V4L) driver ... and
• works with every piece of hardware which is able to handle video overlay.... i.e. it targets no specific graphics card and instead provides an X-Video extension port for video overlay.

To use video-v4l, all you have to do is ...

Unfortunately, with video-v4l, it isn't really the case of "just load the module", as is conveyed by a couple of sources. Rather, a number of things have to come together in order to make it work, and its all (currently) rather convoluted:

The X environment has to be configured properly

In order to do so, your /etc/X11/xorg.conf file will have to:

• enable the "extmod" module, which is required to activate Xvideo support (as well as other extensions too)...You should be able to check your Xorg log file (generated on each system boot up) to make sure that XVideo is loaded without error
• the video-v4l driver added to the module list within the module section. There are no config options for the video-v4l module.

So, within your xorg.conf file, this will look like:

Section "Module" 
    ...
    Load "extmod"
    Load "v4l"
    ...
EndSection

Note: Xorg has moved away from requiring a xorg.conf file, to a automatic configuration of hardware. However, to address cases where "automagic" configuration fails, users can:

• tailor configurations via the particular .conf files contained in the /etc/X11/xorg.conf.d/ directory, or
• similar as to the case in the past, fall back to the classic/legacy method of using an xorg.conf file to set up their hardware with their X environment

The Xorg configuration precidence is: xorg.conf file (if specified) > /etc/X11/xorg.conf.d/nn-yyyyy.conf files (if specified) > automatic Xorg configuration

You need to be using the new version of video-v4l

Up until Feb 2011, the existing, and long neglected, xf86-video-v4l driver only supported the V4L1 API. That wasn't a roadblock in of itself because,

{while}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.

However,

V4L1 API was dropped on kernel 2.6.38. Even the emulation layer inside kernel was dropped. While it might still be possible to use X with libv4l and a LD_PRELOADER setup, the proper way is to port the driver to use the V4L2 API.

So, in essence, you need to use the new, highly revamped, v4l2 supporting, version of video-v4l that was recently posted on the xorg ML.

But, wait, there is more fun to be had! Specifically:

video-v4l still (currently) only supports video overlay

Recall that while video-v4l is neutral/agnostic towards graphic adapters (i.e. it targets no specific graphics card) its functionality is only available to those graphic hardware which are able to handle video overlay. Most, if not all, modern graphics hardware no longer provide a traditional video overlay hardware engine, but, rather, rely upon Textured Video (part of the 3D engine) for rendering video streams. To the best of memory: nvidia 5xxx gpus were the last series to include a video overlay engine. All newer devices utilize texture video radeons had their overlay engine removed ? Intel, IIRC, moved to texture video exclusively with i915 and later SIS 300 supports overlay ... but what else ? Via ??... And so on. To check whether a particular feature is available to your graphics hardware, or, more correctly stated, whether it is even exposed/supported via its corresponding driver, you can use the xdpyinfo utility (X server display info) - checks whether the X server driver for your video adapter supports {feature xxxx}' ... The output is rather lengthy, but if you scroll up to near the very begining, it will list the number and which particular extentions are supported. If you see XVideo listed (and almost all should) you've meet the first part of the requirement to use video-v4l. Next, you have to drill down to see the specifics as to how Xv is supported by your hardware and its corresponding driver. This you can do using xvinfo – queries the XVideo extension capabilities of the attached graphics cards ... With some older hardware, before the gpu manufacturer's full transition to Texture Video, the device's driver will expose several Xv rendering methods: Blitter, Overlay Video, Texture Video, ... An example of xvinfo output for a more contemporary (cirrca 2009/2010) graphics adapter/driver combination is provided on the side. Clearly the adaptor is missing Overlay Video capabilities (relying instead only upon Texture Video), so, in such a case, the video-v4l driver is not useable.

Ex. xvinfo output for a combination of a Radeon 4200 GPU and the Radeon driver user:~> xvinfo X-Video Extension version 2.2 screen #0 Adaptor #0: "Radeon Textured Video" number of ports: 16 port base: 63 operations supported: PutImage supported visuals: depth 24, visualID 0x21 number of attributes: 7 "XV_VSYNC" (range 0 to 1) client settable attribute client gettable attribute (current value is 1) "XV_BRIGHTNESS" (range -1000 to 1000) client settable attribute client gettable attribute (current value is 0) "XV_CONTRAST" (range -1000 to 1000) client settable attribute client gettable attribute (current value is 0) "XV_SATURATION" (range -1000 to 1000) client settable attribute client gettable attribute (current value is 0) "XV_HUE" (range -1000 to 1000) client settable attribute client gettable attribute (current value is 0) "XV_COLORSPACE" (range 0 to 1) client settable attribute client gettable attribute (current value is 0) "XV_CRTC" (range -1 to 1) client settable attribute client gettable attribute (current value is -1)

The Graphics Adaptor device driver Must Support Xv offscreen images and putvideo functions

Further in the chain of requirements for video-v4l to work, the gpu X driver must support Xv offscreen images and putvideo functions. Apparently not many video drivers support these. Rather, most graphics drivers in Xorg support only the XvPutImage capability [1] [2] (as can be seen in the output of the "xvinfo" command).

The video playback software has to make use of this interface

Lastly, video-v4l won't just work with any tv viewing app; rather, to actually take advantage of the V4L Xv interface provided by xf86-video-v4l, you'll also need to be using an app like xawtv that supports this interface. Efforts have been made in a couple of cases to bring legacy Video4Linux applications up to par with V4L2 specification, and, consequently, should now be supportive of video-v4l functionality. (Tvtime,[3] and xawtv, for instance).

In Conclusion

Its not an "out of the box" experience, as there are a number of requirements to get video-v4l to work properly. A number of test cases have been examined with the newly revamped version of the driver [4]

In the Future...

video-v4l may gain a bunch of utility in the future if support for textured video can be added to the driver [5] [6]. This will open up the possibility of using the module (i.e. gaining the benefits it provides) with most modern graphics adaptors, provided the associated device driver for the hardware is also up to the task. However, despite the fact that some of the updated traditional apps, such as Tvtime and xawtv, will be able to make use of this extended capability, it may come just as the sun in setting in the case of using video-v4l in others; for example, MythTV development plans for version 0.26 or later call for dropping Xv support in favour of other rendering methods [7]

External Links

• Old version of the V4L2 API ... (current version available here)
• Archived article from the defunct ETV Cookbook
• former V4L mailing list thread
• Xorg ML ... Mauro's submit message ... note: the thread is discontinuous, so you have to drop to thread mode to follow allow
• Phoronix news brief
  • Phoronixs User Forum Thread
• online copy of the V4L manpage
• Xorg wiki