path: root/doc/README.dxr3

   ----------------------
            xine
   ----------------------

     a free video player


Introduction
============

This documentation is intended for users of a dxr3 decoder card
from creative labs or a hollywood plus decoder card from sigma
designs.

This version of xine contains a plugin for the mentioned hardware
decoders "out of the box". The missing part is the linux kernel
driver. The driver can be obtained from the main dxr3/hw+ linux
development site at

	http://dxr3.sourceforge.net/

The various release formats (tarball, RPMs) are listed on

	http://dxr3.sourceforge.net/download.html

As setting up the dxr3/hw+ driver is a little bit tricky, please
consult also the HOWTO:

	http://dxr3.sourceforge.net/howto.html

The xine dxr3 plugin requires at least the version

	em8300-0.8.1 of the linux drivers.
	

Compilation
===========

It is important to compile and install the dxr3/hw+ driver
*before* compiling xine-lib. No doing so will cause the
configure script to exclude dxr3 support with a warning.

In order to activate the plugin, em8300.h must be available in 
/usr/include/linux. If you have non-standard linux
directory like /usr/src/linux-2.4.5, you can specify the
location with

./configure --with-linux-path=/usr/src/linux-2.4.5

otherwise a ./configure without parameters will do.

XINE dxr3 plugin
=================

There are two different ways in which xine can make use of the dxr3 
card.

1. mpeg-1/mpeg-2 (DVD, VCD, ...) decoding and displaying. 

This is the normal use.  Instead of doing the mpeg decoding in
software, xine sets up the display (TV or overlay) and sends the mpeg
data via the kernel driver to the mpeg decoder on the dxr3 card, very
much like the Windows player that you problably got with the card. In
this mode, you should be using the dxr3 video decoder plugin together
with the dxr3 video out plugin. 

Xine should select the dxr3 video decoder plugin automatically when it
encounters an mpeg stream, but it is possible it does not use the dxr3
video out plugin by default. In that case, start xine with the 
"-V dxr3" argument to specify the dxr3 video out plugin. If you use
another video out driver, such as Xv or XShm, xine won't be able
to use the mpeg decoding capability of the dxr3 hardware and will
use libmpeg2 instead. 

Here's a short overview what happens when you play a dvd with xine
using the dxr3 video out driver:

DVD -> split mpeg video and audio and audio streams 
-> send mpeg video to dxr3 -> image appears on screen

2. displaying non-mpeg video on dxr3 hardware. 

Non-mpeg video may be AVI, quicktime, windows media files or whatever 
else xine can decode. 

This option must be compiled in and requires a supported mpeg encoder. 
At the moment there are two:
- libfame from fame.sourceforge.net (very fast, good quality)
  (currently the 0.9 versions of libfame don't work, use the 0.8 versions)
- librte (version 0.4) from zapping.sourceforge.net (fast, very good quality)
If configure finds one or both it will compile in encoding support into
the dxr3 driver. 

In order to use this driver for output instead of, say, Xv, just start
xine with the command line option "-V dxr3", for example
% xine -V dxr3 my_movie.avi

Unlike in case 1), where the card does the video decoding, in this
case Xine does the decoding in software, as usual, and sends the
decompressed image to the video out driver.  The dxr3 video out
driver encodes, in real time, this image as an mpeg-1 intra frame and
sends it to the mpeg decoder on the card.

Using this trick, we can display arbitrary video formats via the
tv out port of the dxr3 card. Nifty huh? The only downside is that
it requires extra computational power, because we have to both
decode the original video and encode to mpeg-1 in software. The
cpu power needed depends of course on the resolution and the source
format, but as a rule of thumb it is recommended to do this on a
system with at least 128 MB of RAM and a P-III/Athlon at 800 MHz.

Here's an overview what happens when you play an AVI this way
(compare this with the previous overview!)

-> split video and audio streams -> decode video stream 
-> encode video as mpeg-1 -> send mpeg-1 stream to dxr3
-> image appears on screen


XINE run-time configuration
===========================

XINE has several configuration options in $HOME/.xine/config
(see also doc/README.config_en)

dxr3.devicename:
	/dev/em8300-0 The absolute path to the dxr3 control device.

dxr3.preferred_tvmode:
	default Keep the current driver setting
	ntsc    NTSC 60Hz
	pal     PAL 50Hz
	pal60   PAL 60Hz

dxr3.videoout_mode:
	letterboxed overlay
		Overlay Video output on the VGA screen
		with the option of switching on-the-fly
		to tvout (see 'VGA Overlay Feature' below).
		The overlay will be displayed with black borders
		if it is anamorphic. This is only useful in
		the rare case of a DVD subtitle that would
		only display properly in letterbox mode.
		A good example for that are the animated
		commentator's silhouettes on "Ghostbusters".
	widescreen overlay
		Overlay Video output on the VGA screen
		with the option of switching on-the-fly
		to tvout (see 'VGA Overlay Feature' below).
		The more common variant of dxr3 overlay.
	letterboxed tv
		Send video to the tv out connector only.
		This is the mode used for the standard 4:3
		television set. Anamorphic aspects will be displayed
		letterboxed, pan&scan material will have the image
		cropped.
	widescreen tv
		Send video to the tv out connector only.
		This mode is intended for 16:9 widescreen tv sets.
		Anamorphic and pan&scan content will fill the
		entire screen, but you have to set the tv's aspect
		manually.
	
dxr3.keycolor: (overlay only)
	0x80a040 Hexadecimal RGB value of the key color. Should
		not need to be changed.

dxr3.color_interval: (overlay only)
	50.0	Tolerance for keycolor. A higher value allows higher
		range of keycolors. Intended for compensation of
		color errors on VGA output. Smaller value is better
		for not using the "wrong" colors as overlay.
		Meaningful range: 20.0 - 200.0

dxr3.scr_priority:
	10	Priority of the dxr3 scr plugin. <5 means that the
		unix system timer will be used. >5 forces to use
		dxr3 as sync source. If you don't understand this
		keep the default value.

dxr3.decoder_priority:
	10	Priority of the dxr3 video decoder plugin. <5 means
		that hardware decoding by the card will be disabled
		and libmpeg2 will be used instead. Therefore all video
		material including mpeg will pass the software
		decoding and mpeg re-encoding stages.
		(see also above explanation of the encoding mode)

dxr3.contrast:
dxr3.brightness:
dxr3.saturation:
	500	Should not need to be changed manually.  Use xine
		to adjust these as necessary.  Range: 100 - 900

dxr3.alt_play_mode:
	1	Enables or disables an 'enhanced' buffer mode available
		on at least some cards.  Noticable improvements have been
		seen with 'glitchy' streams with intermittant pauses. 

dxr3.sync_every_frame:
	0	Tries to set a synchronization timestamp for every frame.
		Normally this is not necessary, because sync is sufficent
		even when the timestamp is set only every now and then.

dxr3.correct_durations:
	0	Enables a small logic that corrects the frame durations of
		some mpeg streams with wrong framerate codes. Currently a
		correction for ntsc streams erroneously labeled as pal
		stream is implemented. Enable only, when you encounter
		such streams.

video.driver:
	dxr3	The dxr3 video driver does all the necessary card setup
		and the mpeg encoding when playing non-mpeg video.
		(see above)

audio.driver:
	oss	The em8300 audio output is available as an usual
		OSS device. Therefore the audio driver must be
		set to oss. Can also be specified using "-A oss"
		on the command line.

audio.oss_device_num:
	0-16	Machines with a dxr3 installed often have an usual
		soundcard too. If audio playback occurs on the
		wrong device, the demanded device can be set using
		this option.

The following settings only concern the mpeg encoding part:

dxr3.enc_alt_play_mode: 
	1	See dxr3.alt_play_mode. The difference is that it's
		used for the encoding mode.

dxr3.enc_swap_fields:
	0	Swaps the even and odd field of the image. Enable this
		option for material which produces a vertical jitter on
		screen.

dxr3.enc_add_bars:
	1	Add black bars when the image has an aspect ratio
		unhandled by the card. This is needed to maintain proper
		proportions.

dxr3.encoder:
		Mpeg encoder backend to use.
		Depending on what's compiled in, can be "fame" or "rte"
		As a rule of thumb, you should try rte first because
		it gives the best output quality. If you get much
		dropped frames, switch to "fame" and find the optimum
		fame_quality setting (see below) for your system.

dxr3.fame_quality: (libfame encoder only)
	0-100	The quality setting of the fame mpeg1 encoding. Lower
		is faster but gives noticeable artefacts. Higher is
		better but slower. Values between 0 and 100, 90
		is a good initial value.

dxr3.rte_bitrate: (librte encoder only)
	1000-20000 The bitrate in kbit/s of the librte mpeg1 encoder
		output. Lower is faster, but it the difference is not as
		big as with libfame's quality setting. If you get dropped
		frames, it's better to use the libfame encoder.

It is recommented to run XINE one time before editing the config,
since all options get written in .xine/config and have their default
values. The dxr3 video driver can be forced using the "-V dxr3"
command line option. Only the tvmode value has to be edited
if the default driver setting is not correct. Of course you can also
use xine-ui's setup dialog to edit your configuration.


Zooming Feature (TVout Only)
============================
Pressing the 'z' key enables another tv-only mode which zooms into the 
centre of a 16:9 video to display much smaller (or none) black bars 
top & bottom.  It crops the video on the left and right sides to 
maintain the correct aspect ratio. Use SHIFT-z to disable.


TV mode Cycling Feature
======================
Pressing CTRL-o repeatedly will allow you to cycle between tv modes PAL, 
PAL60, & NTSC.  The format selected will only remain valid for the 
current xine session, on startup the tv mode will revert to the default
in .xine/config


VGA overlay feature
===================

In previous versions of xine support, one had to use dxr3view in order
to use the em8300 overlay mechanism. Now, since the xine 0.5 version,
it is possible to output the em8300 overlay directly in the video
out window. 

In order to activate it, "dxr3.videoout_mode" must be set to "overlay".
But it won't work until the old dxr3view works too (just a check). Before
a first use, "autocal" has to be run. This will store the right overlay
parameters in "~/.overlay". For more information, please consult the
dxr3 howto too.

As of version 0.9.5, you can now switch between overlay and tv-out modes 
on-the-fly, simply by hiding the video_out window ('h' key by default, 
see the README file).  If you want to start xine with video on the tv, 
you can run xine with the -H option to auto-hide the vo window, instead 
of changing the configuration (although you can still do that instead if you 
prefer, of course).

Have a look at the previous explained configuration options dxr3.keycolor
and dxr3.color_interval too.


--- 
version of this file:
 $Id: README.dxr3,v 1.8 2003/03/15 20:57:53 mroi Exp $