/*
 *  @(#) MPEG Audio Player maplay 1.1, last edit of this file: 2/21/94 18:10:24
 *  @(#) Copyright (C) 1993, 1994 Tobias Bading (bading@cs.tu-berlin.de)
 *  @(#) Berlin University of Technology
 *
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; either version 2 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program; if not, write to the Free Software
 *  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 */


0) Already tested platforms

The source code of this first release of maplay has been successfully tested
with the following configurations:

 - SPARCstations with SunOS 4.1.3 or Solaris 2.2 (SunOS 5.2),
   GNU C++ 2.5.1, GCC 2.5.4
 - SGI with IRIX 4.0.5F, GNU C++ 2.5.1, GCC 2.5.4
 - DECstation with ULTRIX 4.2, GNU C++ 2.5.1, GCC 2.5.8


1) Compiling the sources

First of all, take a look at the shell script configuration.sh. This script
specifies values for the following environment variables:

  COMPILER		Put the name of your C++ compiler in here, "g++" for
			example. You may specify the full path for your
			compiler if the makefile doesn't find the compiler.
  COMPILERFLAGS		This variable contains compiler flags for your
			compiler. The -D flags together with #ifdefs in the
			sources create the (hopefully) correct program for your
			machine. You should not change these defines.
			Other flags are for optimizations, like "-O2" for the
			GNU g++, warning output control	etc.
			What the define "-DDAMN_INTEL_BYTE_ORDER" does
			should be obvious. It has to be defined on machines
			which use the same byte	order as Intel processors.
			(Intel byte order is lowest-byte-first)
  INCLUDEDIRS		Put -I options for include file paths for your compiler
			in here. The options are used by makedepend and make.
  LIBRARIES		This variable should contain -l options needed by
			your compiler for linking the program. The math
			library is automatically included in the makefile.
  AUDIO_INCLUDES	Audio include files, like audio.h or audioio.h, are
			often placed in different directories on different
			machines. Put the correct include directive for your
			machine in here, for example "#include <sys/audio.h>".

The script configuration.sh contains a big switch statement, which tests the
output of the command "uname -sr". This command should return the name and
release of your operating system. You should enter this command in a shell
first, to see if the output matches one of the already existing case entries.
If so, you can modify the environment settings of this entry according to your
needs. If your operating system and/or release hasn't been tested by now,
you may enter your own entry according to the "uname -sr" output and put in
your environment settings then (see 1.1: Compiling on new platforms).
If your operating system does not know a uname command, you may write a shell
script named "uname" containing
"echo Your_System 1.23"
and add an entry in the configuration.sh file. Or you can throw away the switch
statement and leave only your environment settings in the script file.

After you have modified configuration.sh, you can run "make" to start
compiling. I hope you will be rewarded with an executable after doing so.
If the compilation process didn't make it till the end, you may try to
fix the problem. If you need to adjust the environment settings mentioned
above, you should execute "make clean" thereafter and then "make" again.
If you don't get the problem fixed, you can send me an email (to
bading@cs.tu-berlin.de) wherein you describe your problem. You can also sent
me an email, if you successfully compiled the program, but needed to do
some changes to the sources. These changes may also be useful for other users,
so I can include your changes in the next release.

I am interested in any expiriences in compiling the program on other machines,
because I can't test the program on any existing type of machine myself.
Bug reports etc. should be send to bading@cs.tu-berlin.de, too.


1.1) Compiling on new platforms

Due to the fact that you are using a computer on which I have not tested the
program by now, everthing can happen while compiling the program (who knows?).
Besides, even if your computer has an audio device with CD quality, the program
cannot use it, because each device has a different programming interface, like
a library, or ioctls etc. and I wrote only routines for Indigos and SPARC 10
by now. But if you have enough informations about your device and some knowledge
in C/C++, who can write your own output class. If you are interested, take a
look at chapter 1.2. If you want to use the program as a decoder only, you do
not have to worry about this.

Ok, now here is what you should do to get the program running on your machine:
a) Create a new entry in configuration.sh according to your "uname -sr" output.
b) Set the environment variables COMPILER, INCLUDEDIRS and LIBRARIES to values
   usefull on your machine.
c) Leave AUDIO_INCLUDES empty. If you want to write your own output class, you
   may need this variable.
d) Include the following options into the variable COMPILERFLAGS:
   - the best possible optimization option(s) for your compiler
     (-O2 for example)
   - -DDAMN_INTEL_BYTE_ORDER, if your machine uses Intel byte order.
     If you do not know which byte order is used by your machine, try it
     without this define first. If the program	creates warnings like
     "WARNING: stream contains illegal ...", you should add the define, execute
     "make clean ; make" and try it again.
   Do not insert the defines "-DIRIX", "-DIndigo", "-DSolaris", "-DSunOS",
   "-DSPARC", "-DULTRIX" or "-DDEC" into COMPILERFLAGS. But you can create
   new define names for your machine.

I hope you get a working executable after modifying configuration.sh and
running make. If that is not the case, you have two options:
1. Try to fix the problem yourself with new #ifdefs in the sources.
2. Send me an email describing your problems.


1.2) Writing a new output class

First of all, I have to remind you of the computational effort the program
needs in this first version. Currently mono streams need a half Indigo or
SPARC 10 for realtime playback. Stereo stream need the whole machine.
So it might be possible that you are not able to play any streams even
if you have written a new output class for your device, because your computer
(or the program ;-) is too slow for realtime decoding. You should know the
power of your machine or ask someone who knows it before you start writing
a new output class.

Ok, you want to write a new output class?
Then take a look at the file obuffer.h first. The Class Obuffer is an
abstract base class for all audio output classes. Currently implemented
derived classes are:
- class ShortObuffer for raw PCM output to a filedescriptor
- class IndigoObuffer for audio playback on Silicon Graphics Indigo machines
- class SparcObuffer for audio playback on Sun SPARC 10 machines with the
  dbri device

To access your audio device, the program needs a new class derived from
Obuffer specifically for this device. The new class has to implement the
following methods:
- a constructor
  The constructor has configure the audio device. It should set the
  number of channels (mono or stereo) and the sample frequency (32, 44.1 or
  48 kHz) according to the mode of the audio stream. These informations should
  be included in the parameters of the constructor. The sample format is
  always 16 bit signed PCM.
- void append (uint32 channel, int16 value)
  This function takes a channel number (0 for left or 1 for right) and a
  PCM sample. The sample should be stored in an array for later output.
- void write_buffer (int fd)
  This function should transfer samples from previous calls to append() to the
  audio device. Samples are not written to the audio device in append(),
  because a syscall takes too much time. The parameter is a dummy in this case.

You can take the implementations in obuffer.c as a guideline.
To use your class, the main function in maplay.c has to be modified. Simply
remove the //s in lines 216-226 and fill in your class name, parameters etc.

If you have implemented a new output class, you will be rewarded with the
great audio quality of MPEG audio. And if you think that other users might
like your class too, sent me a copy of your sources and I will include it
in the next release.



Enjoy MPEG audio,
bye,
     Tobias Bading  (email: bading@cs.tu-berlin.de)
