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 which provides an X-Video extension port for video overlay.

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, {which is} 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.[1]

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

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. [3]

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.[4]

So, in summary, 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. [5] [6]

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. [7]

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

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)

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 devices which are able to handle video overlay. Most, if not all, modern GPUs 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 series gpus were the last to include a video overlay engine. All newer family of 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 commandline

• xdpyinfo utility (X server display info) - checks whether the X server driver for your video adapter supports {feature xxxx}' ...

The output from that command is rather lengthy, but if you scroll up to near the very begining, it will list both the number and which particular X extensions are supported. If you see XVideo listed (and almost all should) you've meet one of the criteria required to use video-v4l. However, don't get too excited just yet.

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 the commandline

• xvinfo – queries the XVideo extension capabilities of the attached graphics cards ...

With some older graphics hardware, before the gpu manufacturers fully transitioned to Texture Video, the device's driver may expose several different Xv rendering methods: Blitter, Overlay Video, Texture Video, ... and so on. But with modern graphics hardware, you're likely only to find one: Textured Video. An example of xvinfo output for a more contemporary graphics adapter/driver combination (a Radeon 4200 GPU, cirrca 2009/10, and the xorg Radeon driver) 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.

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 [8] [9] [10] (You can see what your graphics device driver supports from the output of the "xvinfo" command. For instance, as shown in the above supplied example, only PutImage is availabe).

The video playback software has to make use of this interface

Lastly, video-v4l won't just work with any 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 that supports this interface.[11] Efforts have been made to bring legacy Video4Linux applications Tvtime and the 3.9x branch of xawtv up to par with V4L2 specification [12] [13] [14], so, consequently, they should now be supportive of video-v4l functionality.

In Conclusion

By any means, Its not an "out of the box" experience, as there are a number of requirements to get video-v4l to work properly. Though, a number of test cases have been examined with the newly revamped version of the driver, and, when you line up all the stars so to speak, it does indeed seem to work correctly as intended [15].

In the Future...

video-v4l may become more widely useable if support for Textured Video can be added to the driver [16] [17]. Such feature support would certainly 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, while some apps such as Tvtime and xawtv would be able to make use of this extended capability in video-v4l, it may come just as the sun is setting in the case of using the module with others; for example, development plans for MythTV version 0.26, or later, call for dropping Xv support in favour of other rendering methods. [18]

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 video-v4l manpage
• Xorg wiki