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 driver package can be downloaded from

	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

This driver requires the (not yet released) version

	em8300-0.8 of the linux drivers. (CVS only for now)
	

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/src/linux/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 run-time configuration
===========================

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

Some of them are important for dxr3 playback:
*) dxr3_tvmode:
	default Keep the current driver setting
	ntsc    NTSC 60Hz
	pal     PAL 50Hz
	pal60   PAL 60Hz
	overlay Video output on the VGA screen
	
*) 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
	
*) video_driver_name:
	dxr3    Needed for setting the tv_mode, brightness, contrast,
		saturation and the aspect ratio. If not, these features
		will be missing but playback will still work.

		This is only a "dummy" driver which cannot output
		frames. The frames are done by the hardware decoder.
		When *not* playing MPEG1/2 content, it must be set
		to a "real" video driver like "Xv" or "Xshm".

*) audio_driver_name:
	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.

*) 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.

It is recommented to run XINE one time before editing the config,
since all options get written in .xinerc 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.


Running XINE with dxr3/hw+
==========================

The hardware decoder is activated automatically if the driver
can be opened correctly. Mpeg1/2 videos (e.g. DVDs) are played
on the hardware decoder, whereas other content is played on the
screen. Remember to activate a different video out than "dxr3"
in that case!


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

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

The initial idea and the first working sample code came from 
Mike Lampard <mjl@datafast.net.au>. Kudos to him for this new feature.

In order to activate it, "dxr3_tvmode" 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.

Have a look at the previous explained xinerc options dxr3_keycolor
and dxr3_color_interval too.

________________________
docu version information
$Id: README.dxr3,v 1.3 2001/08/05 12:19:54 ehasenle Exp $