Xine's xxmc plugin

# Compiling and installing Xine's xxmc plugin.

1. Compiling and installing Xine's xxmc plugin.
   1. Background
   2. Needed drivers and libs
   3. Configuring and installing
   4. Running the plugin
      1. General
      2. Caveats
      3. Optimizing
      4. Deinterlacing
   5. Chips supporting XvMC acceleration using the xxmc module.
      1. VIA Unichrome / Pro
      2. Nvidia
   6. FAQ

## Background

The xine xxmc plugin supports playback with

- Standard XvMC, as supported by many Nvidia chips.
- VLD XvMC, as supported by the VIA Unichrome / Pro chips, up to 1024x1024.
- Standard Xv. The xxmc plugin will fall back to Xv if any of the above fails.

There is no API or hardware feature called "xxmc". It is only the name of Xine's plugin, since the name "xvmc" was already taken. The name "xxmc" stands for eXtended XvMC, and it is extended in the sense that it also includes support for VLD XvMC, which is a nonstandard extension to XvMC, proposed by the Unichrome project.

## Needed drivers and libs

- You need an XvMC driver for the chip you want to run accelerated on. (This does not apply if you only want to run Xv on the accelerated driver). Drivers for Nvidia chips are on Nvidia's website. Drivers for the VIA CLE266 chip are present in Xorg CVS or downloadable as patches at The Unichrome project's site
- You need the XvMC wrapper, present in Xorg CVS, or downloadable from The Unichrome site

## Configuring and installing

Make sure you have the XvMC wrapper installed. The wrapper will try to figure out at run-time what xvmc-hardware specific driver to load. If it fails it will open the file /etc/X11/XvMCConfig or /usr/X11R6/lib/X11/XvMCConfig and try to load the hardware-specific library mentioned in that file. If you downloaded the XvMC wrapper from the unichrome site, the default XvMCConfig will make the XvMC wrapper try to load the Nvidia XvMC driver. If you want to use it with the VIA Unichrome /Pro chips, you will have to edit the XvMCConfig file to contain the single word
libviaXvMC.so.1
Now configure and compile xine-lib as usual. Make sure that the xxmc plugin got enabled by configure or autogen.sh.

## Running the plugin

### General

Start xine with xine -V xxmc, or kaffeine with kaffeine -x xxmc. If the XvMC wrapper fails to load a hardware specific library or fails to read the XvMCConfig file it will specifically tell you so. If you have the wrong hardware-specific library specified in the XvMCConfig file, the xxmc plugin will think that you are running against a remote X-server and fall back to software decoding. If the driver uses hardware acceleration it will specifically tell you so. At the moment, the XvMC implementation only accelerates mpeg1 and mpeg2 files, if the hardware advertises support for these file types.

### Caveats

Some Nvidia chips seem to use very much CPU when subtitles are displayed, and black areas of the screen are full of small white dots. These chips only use motion compensation accelaration, and are bad at it as well. You're better off running the Xv plugin with these chips. The white dots are due to hardware- or driver bugs. Nvidia chips that supports IDCT acceleration also seem to support motion compensation acceleration correctly.
OSD might be rendered in the wrong color with Nvidia chips. To work around this use the xine config option
video.device.xvmc_nvidia_color_fix:1
This is due to a bug in the Nvidia XvMC drivers, and this bug is probably also present in the i810 drivers.
There is also a bug in xine's XvMC support for interlaced streams with IDCT and motion compensation accelerations. The xxmc plugin will fall back to plain Xv for these streams. Hopefully this will be fixed in the not too distant future.

### Optimizing

If you are running VLD XvMC on the VIA Unichrome / Pros there are some options that may affect performance:
video.device.unichrome_cpu_save:1
Will save a lot of CPU-power if you are running a 2.6 series kernel. It does this by sleeping while the hardware decoder works. Otherwise it will spend a lot of CPU waiting for decoder completion.
video.device.xvmc_more_frames:1
Will allocate 15 XvMC surfaces instead of 8. This is very useful if you are using vdr-xine and want to avoid buffer-underrun stutters in xine. Don't use this with Nvidia cards since they only allow a maximum of 8 frames. If your driver does not allow 15 frames and you turn this option on, it will abruptly fall back to software rendering, causing some rendering glitches while doing so.
gui.osd_use_unscaled:0
Don't use unscaled overlays for OSD. Sometimes the X server will have severe problems painting the OSD surface when unscaled OSD:s are used. This will be visible as severe stutters when ANY overlay (OSD or subtitle) are displayed and removed. Use this option for scaled OSD which is considerably faster with CLE266, since blending is done in hardware. This option is usable also with Nvidia cards, but I've never seen problems with unscaled OSD with those.

### Deinterlacing

XvMC can only do very simple one-field deinterlacing in hardware. It's also impossible to use software deinterlacing, since XvMC does not allow xine to read the content of a decoded frame. Therefore, when you run a hardware accelerated stream, Interlacing will be toggled by pressing "i". If the xxmc plugin has fallen back to Xv and software decoding, post plugins will take care of deinterlacing.
BOB deinterlacing (alternating between top and bottom field at double the frame-rate) for XvMC accelerated streams is available as an experimental feature. It is activated using the config option
video.device.xvmc_bob_deinterlacing:1
If this option is enabled, The xxmc plugin will use bob as deinterlacing method when deinterlace is toggled pressing "i". To get the best results from this method, the screen update frequency should be a multiple of double the frame rate. For example, if the frame-rate is 25Hz, Your screen update frequency should be 50Hz or 100Hz. I have been able to get reasonable results using a 75Hz update frequency, however.

## Chips supporting XvMC acceleration using the xxmc module.

### VIA Unichrome / Pro

- CLE266: up to 1024x1024.
- K8M/N800: up to 1024x1024. Use Unichrome X drivers >= r31.
- CN400: HDTV capable. Driver support is under development.
- PM8X0: HDTV capable. Driver support is under development.

### Nvidia

- Quadro FX 1000 (IDCT / Mocomp)
- Please help me fill in here.

## FAQ

Q: The xxmc plugin is not enabled when I configure xine-lib
A: Check that you have installed the XvMC wrapper, and that you've run "ldconfig -v" as root after that.
Q: The XvMC wrapper complains when I start xine.
A: Check that you have created an XvMCConfig file specifying the relevant driver name.
Q: I'm running on a Nvidia card and my OSD colors are wrong.
A: See "caveats" above.
Q: I'm running VDR-xine and the playback stutters.
A: See "optimizing" above.
Q: I'm running on a CLE266 and I get severe stutter when subtitles are displayed.
A: See "optimizing" above.
Q: Can I use the xxmc plugin without the XvMC wrapper?
A: Yes, you can link directly with a hardware specific library, but this is not recommended. Run "./configure --help" to check which options to use.