Linux DXR2 driver
Copyright 1999, 2000 Creative Labs, Inc.
Released under the Gnu Public License v2.


Introduction
------------

Welcome to the dxr2 driver for linux. This is currently still a development
driver, although it is now pretty stable. 

This driver ONLY supports Creative's dxr2 card. It does not support any of
Creative's other DVD products (e.g. it does not support the dxr3, or the DVD
inlay card).

This code is being actively developed by adq@tardis.ed.ac.uk, e-van@nwu.edu, 
and lucien@martincurrie.com.

Note that currently VGA overlay is NOT supported, output is to a TV only.
VGA overlay is now top of the development list, and should be available soon.


Help!
-----

The FAQ for the dxr2 driver under linux is maintained by Ben Von Handorf 
(handorf@penguinpowered.com), and is available from 
http://home.fuse.net/DaigoFukuru/dxr2-faq.html

The next source for help is the dxr2 mailing list, details of which are 
available at http://opensource.creative.com/mailman/listinfo/dxr2-devel

You may also find the generic dxr2 FAQ 
(http://members.tripod.com/wmania/creafaq.htm) of some use, although it is not
specifically about the linux driver.

Information and firmware upgrades for region locked drives may be found at 
http://www.visualdomain.net/

If you are looking for programming help on how to use the IOCTL interface,
look in dxr2/ioctls.c. Each of the ioctls is implemented in a seperate function
here, and full documentation on the parameters and buffer contents for calling 
each ioctl is given at the start of each function.


Required Files
--------------

* You'll need a recent linux kernel 
    (the driver has been tested with kernels 2.2.5, 2.2.9, 2.2.12, 2.2.13,
     available from your local ftp://ftp.kernel.org/ mirror)

* You'll need the CSS IOCTL patches
    (available from http://www.kernel.dk)

* You'll need the UDF filing system patches, 
    (available form http://www.csc.calpoly.edu/~bfennema/udf.html)

* dvd1.ux firmware file
    (available from http://opensource.creative.com/binaries.html)



Compilation/Setup
-----------------

1) Make sure you've recompiled your kernel with all patches mentioned above.
2) Decompress the tgz file/use CVS to get the latest source into a directory.
3) Make the dxr2 device ("mknod /dev/dxr2 c 120 0")
4) Go into the source directory and type "make".
5) Use "make insert" to insert all the necessary modules, and "make remove" 
   to remove them all again.


Basic playing DVDs
------------------

The "DVD player" is in the "player" directory. Due to the DVD standards being 
foolishly secret, this is not a full featured DVD player: you will not get
any of the fancy interactive features, but you will be able to play the movies 
back.

The following should all be done as root

1) Before using the player for the first time, you should copy the 
   "dxr2player.conf" file into your /etc directory, and modify it for your
   particular configuration (see below).

2) Mount the DVD.

3) The video files are held on the DVD, in the "video_ts" directory. The interesting
   ones are VTS_XX_Y.VOB. A film is usually broken up into several large files, each
   with the same number for XX in the filename.

4) The files are separated into different 'titles' the XX in the file name(see #3) is
   the title number.  to play it:  ./dvdplay -cT<#>  where <#> is the title number.
   eg:  ./dvdplay -cT1         to play the first title.  See below for more options and
   their meanings.
 
5) Some movies don't work with the -T<#> option(don't have accessible IFO files).  To pley
   them, try:  ./dvdplay -c <filename>   where <filename> is the full path to the _first_
   file in the title you wish to play.




Player Command line switches
----------------------------

  -c		Turns CSS decryption ON. 
		You will need to be running the player as root to use this.
                This will be deprecated shortly.

  -a X		Select audio Stream. 
		X should be between 0 and 7 inclusively (by default audio 
		stream 0 is played)

  -r X		Select Picture ratio. 
		0 = Letterbox, 1 = normal, 2 = Pan/Scan. 

  -t X		Select TV output format.
		0 = NTSC, 1= NTSC 60Hz, 2=PAL-M, 3=PAL-M 60Hz, 4=PAL BDGHI, 
		5 = PAL-N, 6 = PAL-Nc. (0 = US NTSC, 4 = w-european PAL)
 
  -q X		Select audio frequency.
		0 = 44.1 kHz, 2 = 48 kHz, 3 = 96 kHz, 4 = 22.05 kHz, 5 = 32 kHz.
		(You should choose 3 (96 kHz) for most DVD AC-3 movies.)

  -w X		Select audio width.
		0 = 16 bits, 1 = 20bits, 2 = 24 bits.
		I'm not sure why this is here.

  -s X		Select bitstream type.
		0 = DVD. 1 = CDROM VCD, 2 = MPEG VCD, 3 = CDDA, 4 = Unknown
		(Choose 0 (DVD) for playing .VOB files, and 2 (MPEG VCD) for 
		playing VCD .mpg/.dat files)

  -u X          Select audio format type.
                0 = AC3, 1 = MPEG, 2 = PCM
                Usually -s will also choose the right audio type, but some DVDs
                have PCM.  If you use this option with -s, put -s first.

  -T X		Enable multi-angle compensation. Some DVDs have "multiple 
		angles" encoded in them. When you play these without the -T
		switch you often get little pieces of scenes repeating each
		other in quick succession. Using this switch should solve this
                X is the number of the title you wish to play.

The full set of command line switches is displayed when you run the player without any arguments.


dxr2player.conf Configuration
-----------------------------

drive: /dev/cdrom
		DVD device
		You should set the above to be whatever DVD device you use. This is used
		for CSS authentication.

dxr2:  /dev/dxr2
		DXR2 device
		The dxr2 device to use.

firmware: /usr/src/dvd1.ux
                The place where you keep your firmware file.

mountpoint: /dvd
                The directory where you mount your DVD drive.

audio_format: AC3
		Audio Format
	        You can set this to AC3 or MPEG

audio_freq: 96
		Audio Frequency
	        You can set this to 44.1 / 48 / 96 / 2205 / 32

audio_width: 16
		Audio Bitstream Width
		You can set this to 16 / 20 / 24

tv_format: PAL
		Output TV format
		You can set this to NTSC, NTSC_60, PAL_M, PAL_M_60, PAL_BDGHI, PAL_N, PAL_Nc

video_format: letterbox
		Video format
		You can set this to letterbox / normal / pan_scan

subpicture: OFF
		Subpicture ON/OFF
		You can set this to ON / OFF

The following options only pertain to the VGA overlay:

overlay: OFF
                The default Overlay mode.  ON or OFF

overlay_geom: <width>x<height>+<x>+<y>
                The gemoetry parameters for the default overlay window.
                X/Y specify the top-left corner of the display.

overlay_crop: <left>x<right>x<top>x<bottom>
                The number of pixels to chop off of each side of the image.

red: <min>-<max>
green: <min>-<max>
blue: <min>-<max>
                The min-max red values for overlay.  the color on your display must be within
                these values for the video to show up.  The nubmers are in hex.



Notes
-----

  Since this is a development driver, certain things WILL be changing:

  * The major device node (currently 120) will be changing.

  * When linuxtv.org finalise their API, the existing temporary API will be 
    removed in favour of this.
