Welcome to release of the Linux driver for Netstream2000.

DISCLAIMER
----------
This program has (for some parts) to operate as root and in kernel
land. As a result, it can crash your system and you may loose
critical data on your hard disk. Sigma Designs cannot be held
responsible for that.

LICENSING
---------
- shared object libraries (libEM84xx.so, libosd.so) in lib/ 
  are only available in binary form.
  Copyrighted (C) 1999-2000 Sigma Designs

- kernel land driver in directory kernelmode is distributed 
  under the terms of the GNU general public license.

- remote control client in directory RMREMOTE is distributed 
  under the terms of the GNU general public license
  [For convenience a remotecontrol binary is included]

- trivial file player client in directory RMPLAYFILE is distributed 
  under the terms of the GNU general public license
  [For convenience a playfile_binary binary is included]

- calibration application in directory analogoverlay/RMCALIBRATION 
  and simple libraries are distributed 
  under the terms of the GNU general public license
  [For convenience a calibration binary is included. This binary
  is statically linked with libXxf86vm.a from XFree3.3.6 and
  should be recompiled if you run XFree4.0.1]

- file player windowing application in directory analogoverlay/RMFILEPLAYER is distributed 
  under the terms of the GNU general public license
  [For convenience a fileplayer binary is included]

- tv player with on screen display CelesteApp is distributed
  under the terms of the GNU general public license
  [For convenience a celesteapp binary is included]

SUPPORTED PLATFORMS
-------------------
Linux on x86 processor, with kernel 2.2.x (2.3.x may work).
Any recent distribution should do.

Users of RedHat7.0: this distribution default installation is broken,
kernel is 2.2.16-22 and kernel headers are from 2.4.0-0.26. To correct this
just install kernel-source-2.2.16-22 RPM:
# rpm -i kernel-source-2.2.16-22

Kernel 2.4.0-testx is supported (tested on 2.4.0-test9).

All ATAPI DVD drives are supported.

If your kernel has the CDROM_SEND_PACKET ioctl (Linux >= 2.2.16)
SCSI DVD drives are supported.

You must have a NetStream2000.

LOADING THE KERNEL MODE DRIVER
------------------------------
As root, type

# ./loaddriver

then leave the root shell (exit).

_Afterwards_, run

$ source NetStream2000.env

to get a correct environment.

``loaddriver'' must be run once at each boot.

You *have to* source the environment before
calling one of the following programs (especially if you open a new window).

USAGE (DVD PLAYBACK WITH RMREMOTE ON TV OUTPUT)
-----------------------------------------------
You must have a REALmagic remote control connected to the first
serial port (default).

Insert a DVD in your drive. Then issue

$ ./remotecontrol

Then, press the ``PLAYER'' button (maybe labelled ``PROGRAM'' on
some versions; this it the top right button) on the remote.
If you wish to stop it press Control-C.

You must first exit a running player to start over.

Note: if you want to use the second serial port type
$ export REMOTECONTROLPORT=/dev/ttyS1
at the shell, as user, before launching remotecontrol (bash or zsh syntax).

USAGE (VCD2.0 PLAYBACK)
-----------------------
Follow the same steps as DVD playback.

USAGE (FILE PLAYBACK)
--------------------
Follow the steps until leaving the root shell then

$ ./playfile s /samplempeg/movie.mpg

's' means system stream, also 'd' for dvd (.vob),
and 't' for transport stream. See source code.

For on screen example, issue the following command:

$ ./playfile

If you filename has white spaces, use "...".

To interrupt press Control-C.

File playback is not very stable, and interrupting/playing bogus
files/using wrong type will easily crash your computer.

CHANGING THE REGION CODE
------------------------
You can change the region code only five times.

- insert the DVD of the region code that you want to change to
- issue ./remotecontrol command (assuming that the driver is already loaded)
- press Player from Remote Control
- get another terminal window or console (Alt-F2)
- login again and go to the directory of the Linux driver
- issue ./regioncodechange 4 (assuming the region code wanting to change is 4)
- hit Enter to confirm

An unconfigured NetStream2000 will allow playing region code 1 DVDs
before first change.

If you have more than one NetStream2000, be careful to launch remotecontrol
with the appropriate environment so that the right board is changed.

DISPLAYING ON VGA MONITOR
-------------------------
Video can be output on VGA monitor using the analog overlay capability
of the NetStream2000, instead of tv output.

*** Make sure the pass-through cable is connected between your videocard
output and the connector labelled ``VGA IN'' on the NetStream2000. The
monitor must be plugged on the ``VGA OUT'' connector on the NetStream2000. ***

The analog overlay must be calibrated before used, if you use
different resolutions it must be calibrated for each resolution.

The fileplayer allows a convenient video displaying using GTK+ : 
- windowed file selection.
- Play, Pause and Stop commands on an independant and removable toolbar.
- windowed options panel : sound volume and balance levels, image settings (B/S/C), 
  video output mode (NTSC, PAL, PAL60, PALM).
- fullscreen on VGA video output.

AUTOCALIBRATION
---------------
To be able to autocalibrate you must run X at a resolution less
than 1280x1024. Better supported resolution are 1024x768 and under.

*** You cannot run the autocalibration process while the card is
playing. The script will first kill other applications
accessing the device ***

Be sure the loaddriver script has been run.
Then leave the root shell and issue the command:

$ ./autocalibrate

Run the auto calibrate button then adjust border to have a clean image.
Don't forget to push the ``ok'' button to leave and have your settings
saved (they are saved in $HOME/.realmagicanalogoverlayrc0).
You can also by-pass the graphic interface and go directly through the automatic
calibration process by using the '-a' option of the autocalibrate command :

$ ./autocalibrate -a

Please, take in note that automatic calibration depends on analog signal value comparisons and may
fail. You may still have to adjust border to have a clean image.

USING RMFILEPLAYER (FILE PLAYER WINDOWING APPLICATION ON VGA MONITOR)
----------------------------------------------------------------
You can use this application to play file either on your VGA screen or on your TV set.

$ ./dummy &
$ ./fileplayer

Some features :
  - fileplayer try to auto-detect the type of the file you want to play, however, on failure,
  the file will be played as a mpeg1 system stream (in the menu, "File" then "Open").
  - fileplayer goes automatically through the auto calibration process if needed. Note that you 
  may still have to adjust border with the autocalibrate command.
  - the image is displayed on the VGA screen and can be resized up to fullscreen (in the menu, "View", then "Fullscreen").
  - you can also have a display on your TV screen, an options window permit you to switch between
  NTSC, PAL, PAL60 or PALM (in the menu, "View" then "Options ...").
  - The same options window give you access to the image settings (brightness, saturation and contrast) 
  and to the sound output balance and volume level.

Dummy acts as a server for the fileplayer client application (for the autocalibration application as well). The implementation
of the client/server architecture is in novaserver and novaclient libs.
You have to run dummy before executing fileplayer.

TV OUTPUT (YUV / RGB / NTSC / PAL)
----------------------------------

$ ./remotecontrol --yuv

"yuv" means YUV, "rgb" means RGB,
"ntsc" means NTSC, and "pal" means PAL output.

Two parameters can be issued in the same command line as needed:

$ ./remotecontrol --yuv --pal

That will give you YUV PAL output.

For on screen example, issue the following command:

$ ./remotecontrol -h

NEW API FUNCTIONS
-----------------
We have included more API functions in this build.

ChapterPlay
TimePlay
ChapterSearch
Karaoke - audio presentation
GoUp - a dvdsearch
TopSearch
TimeSearch
DVD Domain
MenuLanguageSelect

ADDITIONAL INFORMATION
----------------------
* objects are tested with dynamic link against libc-2.1.3.so (RedHat 6.2)

* loaddriver must be run after each boot (script that executes insmod)

* it's not necessary and not advised to run everything as root. Create
  a user account (adduser joe)

* You can monitor CPU load with the following shell command:
  (computed by adding the CPU usage of all threads)

$ while true; do sleep 10; echo DVD playback CPU load is about `ps auxw |grep remotecontrol |awk '{u+=$3} END {print u}'`; done

* normal load after some minutes playing DVDs is
  about 2.6% CPU on PIII 450MHz (3.5% with PCM audio)
  about 5% CPU on PII 266MHz
  about 12% CPU with two NetStreams and two DVD playing at the same
   time on PIII 519MHz
  Please report any abnormal observation.

* the loaddriver script will make your /dev/ttyS0 and /dev/ttyS1 a+rw,
  and also change rights on the appropriate dvd drive device

* region code change is implemented by signal reception on remotecontrol.
  Signal patterns are quite unusual, so an unwanted region change is
  really unlikely to happen.

KNOWN BUGS
----------
* the program can *really* hang your computer, requiring a hard reset
  This is rare now (especially with dvd playback, very stable)

* after a process crash there are still message queues
  listed by ipcs. You can remove them (and any other owned by the user) with:

$ for x in `ipcs -q |grep $USER |awk '{print $2}'`; do ipcrm msg $x; done

* for kernel<=2.2.15, if the first IDE connector has no devices, the
  IDE scanning function of dvdpc.c will fail (only one hwif).

* SMP kernels are not supported --- have to patch the kernel modules for
  SMP compatibility.

* serial port fails to read() characters in raw mode in linux 2.4.5
  and maybe others: remote control does not work for this kernel

REPORTING BUGS
--------------
As root, run the script

./bugreport

and send as an attachment the bugreport.log.gz file to linux@sdesigns.com

Since we cannot guess it easily, include also:
* your distribution identification and version (RedHat, Debian, Slackware...)
* the DVD you tried (complete title identification, region code).

LEARNING MORE
-------------
If this file is not enough, also read README.advanced, and the ChangeLog.

Join the newsgroup nntp://news.sigmadesigns.com/REALmagic.linux.
