Release notes for MIT saolc v 0.7
   (CD software MPEG release)

Eric Scheirer, 20 Nov 1997
-----------------------------------

This is the first widely-distributed release of the 'saolc' implementation
of SAOL, the MPEG-4 standard audio processing language.  This version is
about 85% complete, and has full functionality on all core features.

It is NOT completely debugged yet; this release is to get it out into
wide distribution so that people who want to use it to make music
can help me find bugs.

The biggest lack right now is documentation.  The Committee Draft ISO
standard is available, but that's overkill for users (it's aimed at
implementors).  I hope to have someone working on this soon; if you're
interested in helping out to make WWW-based user documentation for
SAOL, please contact me.  Unlike with some other languages, once the
standard is set, the language won't change, so maybe the WWW documentation
won't have to be in a continuously evolving state.

There's a new mailing list for SAOL users.  I'll be active on this
list for a while answering questions and helping out with the
lack of documentation.  Email to saol-users-request@media.mit.edu to be
added.

The 'sa_encoder' program and '-bitstream' option to saolc allow you
to pack orc/sco/samples into a single compact file so that you can
use saolc as a helper app and put music in SAOL on your WWW page.
Put a line like 'saolc -bitstream %s -out /tmp/foo.aiff; sfplay
/tmp/foo.aiff' as the MIME helper line.

SAOL WWW site:  http://sound.media.mit.edu/~eds/mpeg4

------------------------------

SPECIAL NOTE FOR CD MPEG RELEASE:

Note that two different copyright statements are on the code.  The
parts written at MIT are placed in the public domain; please do whatever
you like with them.  However, the parts written at E-Mu are 
under the *regular* ISO copyright; that is, you may only use them
to develop compliant MPEG-4 implementations.  If you want a "clean"
version for distribution, there's one on the SAOL WWW site.


---------------------
Current known limitations, bugs, eccentricities:

The following core opcodes are not yet implemented:
  pluck(), fof(), port(), chorus(), reverb(),
  sblock(), fracdelay(), ftsetloop(),
  ftsetend(), ftsetbase()

The following ctg's are not yet implemented:
  expseg, cubicseg, spline, polynomial, buzz, concat

The 'return' statement doesn't short-circuit flow of control.
fft() and ifft() are broken for non-power-of-two sizes.
MIDI functionality is not yet implemented.
sequence() is not yet implemented.
spatialize() is not yet implemented.

---------------------

Here is a short primer on cool new features of the language.

 - Opcode arrays.

   If you use a declaration like  'oparray comb[10]', this allows access
   to the internal state of each of the comb filters in a bank of 10.

   This is useful for two big reasons.  First, you can write code like this.

     oparray comb[10];
     asig i;

     i = 0; while (i < 10) { a = a + comb[i](b,i/100); i = i + 1; }

   You can't do this easily in csound.

   Second, you can refer to the same internal state in different calls.  This
   is most useful with fracdelay() and with similarly "object-oriented"
   user opcodes.

   Assume a UDO like

     kopcode inc() {
       ksig x;

       x = x + 1;
       return(x);
       }

   Then if you do

     oparray inc[2];

     a = inc[0](); b = inc[0](); c = inc[1](); d = inc[1]();

   you get
     a == 1,  b == 2,  c == 1,  d == 2

 - Vector arithmetic.

   All of the following are legal:

     asig x[4], y[4];
     x = y;
     x = y * 2;
     x = y * x;  // pointwise, like MATLAB y .* x
     x = foo(y); // if foo() has "return(1,2,3,4)" or "return(z)"
                    where z is length 4
     x = foo(y) * y;
     return(x)
     return(x,y);
     output(x,y);  // if it's an 8-channel orchestra

  - Table maps

  The declaration "tablemap foo(a,b,c,d)" where a,b,c,d are each wavetables
  in the local scope allows the use of array syntax "foo[i]" to select
  between multiple wavetables.

   
  - kdump(), adump()

  Debugging statements.  They dump all of their parameters to stdout each
  k-cycle, or a-cycle, respectively.

------------------------------------------

Compiling tips...

  Currently, the SBF code is not 64-bit enabled; that is, you can't build
it on an Alpha or in 64-bit mode on an SGI R10000.  This is being worked
on.

  If your compiler doesn't support throw(), just comment them out.  They're
not being caught, and only represent error conditions anyway.

  To compile a decoder on a system that can't use the provided Makefile, 
use all of the c/cpp files except sa_encode.cpp, saol_encoder.c,
sa_encode.yy.c, and lex.yy.c.  Compile each of them and link them together.
If you're on a big-endian platform (SGI, Alpha) set the flag __BYTE_INCOHERENT.
If you're using the full MPEG code-base, set _SASBF, and on the sources
matching "sf*", set CPP_MEMORY.

  On a WIN32 platform, you need the following flags set on the compile :
 __SYS_WINDOWS, __BYTE_COHERENT, and CPP_MEMORY.

You can find ready-made decoders for several platforms on the WWW site.

To compile an encoder, you need to use the following:

  sa_encode.cpp sa_encode.yy.c saol_tok_table.cpp bitstream.cpp aifif.c
saol_score.c byteswap.c IEEE80.c 

Compile each and them link them together.

