CSRW_DOC.TXT  Master doco file for Robin Whittle's Csound activities

11 September 1995

Robin Whittle   firstpr@ozemail.com.au  rwhittle@ozonline.com.au
                http://www.ozemail.com.au/~firstpr


For Csound users and C programmers.


This file documents the features of my current release of CSOUND.EXE 
and the source code which produced it.  This source code can be easily 
added to Csound sources for compilation on machines other than MSDOS.

Following that is a list of all the relevant doco and .ZIP files.

Then there are some copyright notices.

After that I describe my priorities for extending Csound.  Then there 
is a "wish list" or things I want to do.


There are no example files in this release.  I have only been doing 
test files and programming recently.  Paris warned me about the "dark 
side" - so if you don't see any .org or .exe files appear in the next 
month or so, then you will know that I have been seduced by forces 
other than music.


Your comments, bug reports and carefully considered suggestions about 
new unit generators are welcome!

- Robin Whittle


For general info on Csound check out:

The MIT site:           ftp://cecelia.media.mit.edu/pub/Csound

The Bath ftp site:      ftp://ftp.maths.bath.ac.uk/pub/dream
 
The Leeds WWW site:     http://www.leeds.ac.uk/music/Man/c_front.html
(This has details and archives of the Csound mailing list.)
  

-----------------
|               |
|   FEATURES    |
|               |
-----------------


CSOUND.EXE for MSDOS
--------------------


This CSOUND.EXE (in CSRW_EXE.ZIP) is compiled with the DJGPP 1.12 
compiler, and contains a number of enhancements.  My work is based on 
John Fitch's release of Csound code on 17 April 1995.  I will attempt 
to keep up with bug fixes and well documented improvements from this 
and other sources.

This CSOUND.EXE has the following characteristics:

1 -     It needs a 386, 486 or Pentium with a maths coprocessor.  
        So a 386 DX or SX is OK if you have a 387 plugged in.  Any 
        Intel 486 DX will do - a 486 SX has no maths coprocessor.  

2 -     It does not do graphics.  I probably can get this working, but 
        it will be a lot of work I think.  Use one of John Fitch's 
        CSOUND.EXEs if you need to display graphs.

3 -     It has several bugs removed from the table and tablei ugens.

4 -     It has a whole swag of new ugens as documented below.

5 -     It runs under MSDOS, a Win3.1 DOS box, and I expect, a WIN95 
        DOS box.  I am not planning a Windows graphics version at 
        present.

6 -     I am only working with the main CSOUND program - not the 
        utilities.  I am not maintaining or distribute the the source 
        for them.


Features of this CSOUND.EXE
---------------------------

This carries the same MIT version (3.29) as John Fitch's source from 
which I worked.  I don't know anything about these version numbers.  
It also carries John's version 12.  To this I have added my version 
number 1.00 - for the 11 September 95 release. 


This CSOUND.EXE can handle instrument numbers up to 1200 and function 
table numbers up to 1000.  There are some limits on the length of the 
orchestra file.  I have not investigated this yet.


Environment variables to set
----------------------------

This CSOUND.EXE has a built in DOS extender which is part of DJGPP - 
it is called GO32.  This provides the 32 bit linear address space the 
program works in, and handles the interface to MSDOS.  It uses the 
386/486/586 memory management system to map physical memory wherever 
the program needs it.  It also needs to run under a DPMI server such 
as HIMEM.SYS or in a DOS box in Windows 3.1 or Windows 95.

GO32 then uses the DMPI system to access memory it needs.  If your 
CSOUND.EXE uses more memory than is available from RAM, then GO32 
will create a swap file on hard disk.  This will only occur if your 
 .orc and .sco files use lots of memory due to tables or delays.  If 
you want to tell GO32 where to put the swap file, put a line like the 
following in your autoexec.bat:

SET GO32TMP=F:/tmp

Note the forward slash - GO32 expects this - not a MSDOS backslash

Csound has some default directories which are also defined as 
environment variables.  It is best to make these sub-directories, 
rather than the root directory of a disk (like f:\).  In my 
autoexec.bat I have:

SET SFDIR=f:\0snd
SET SSDIR=f:\0snd
SET SADIR=f:\0snd


I use some batch files to edit files, run Csound and play the sound 
files.  I use an environment variable PROJ to store the name of the 
active files.  When I do this under Windows, I find that I cannot 
define PROJ, or redefine it to a longer name - due to some pesky 
problem with environment space.  The solution is to define PROJ to 
something quite long in the autoexec.bat:  

SET PROJ=AVERYLONGNAME




New features available as source code for any Csound implementation
-------------------------------------------------------------------

These are contained in new and modified files in CSRW_SRC.ZIP.  

All these features are built into the CSOUND.EXE in CSRW_EXE.ZIP.

A full listing of documentation files follows this list of features.  


UGENS2  Bugs in table read code fixed.  New versions of table and 
------  tablei enable the table number to be controlled by a k rate 
        variable.  

        See TABREAD.TXT. Modified code is in UGENS2.C and UGENS2.H.

        These bug fixes, clearer documentation and k rate control are 
        intended to be a lasting part of Csound if people like them.



UGRW1   Table write ugens - for writing directly into function tables 
-----   at i k or a rates - with i or k rate control of the table 
        number. (See TABREAD.TXT for krate control details.) 

        Ugens for manipulating data in tables: tablegpw, tableleng,     
        tablemix and tablecopy.

        Ugens for reading and writing to table locations sequentially 
        from a rate variables.  One of the uses of this is to read a 
        rate data into a table (or several a rates into several 
        tables), and use _any_ k rate code to process the data, before 
        converting it back to a rate.  This means that when you really 
        want to, you can use all of Csounds ugens and operations on a 
        rate code.  It is somewhat slow, but faster than running with 
        ksmps = 1 and using upsamp and downsamp.

        Global patching of i, k and a rate signals based on numbers 
        generated at i or k rate.  This is really a fudge until the 
        language supports arrays.  This is called the "zak" system. 
        However it is extremely useful.  There is a numbered set of 
        "zk" k rate patch points and another set of "za" a rate patch 
        points.  A variety of ugens read, write and mix to these - 
        with k rate control over which patch point is used.  This 
        enables the code in each instrument to decide where to get and 
        send a and k rate signals when working with other instruments.

        Simple ugens to read the time elapsed since the start of the 
        piece or the initialisation of the instrument.  

        Two ugens for printing k rate variables as numbers on the 
        screen.  The second of these allows four variables to be 
        printed in the midst of a text string - by printf().  It also 
        allows any byte to be printed and makes it easy to insert 
        escape codes into the text for cursor control.


        These, or something like them are intended to become 
        a lasting part of Csound if people like them.  The "zak" 
        system is very useful for patching things, but not as good as 
        a rewrite of Csound to support arrays - so it is only intended 
        to last *until* that happens.

        See UGRW1.TXT. New code in UGRW1.C and UGRW1.H. 


UGRW2   kport - a low pass filter for k rate variables like port, but 
-----   now with a k rate frequency control.

        Filters for k rate variables: ktone, katone, kreson & kareson 

        limit and ilimit ugens for setting k (or i) rate upper and 
        lower limits on (i,) k or a rate variables.

        See UGRW2.TXT.


CMATH   A 31 bit random number generator replaces the previous 15 bit 
-----   one.  A seed ugen is provided to set it.  

        This global random number generator is used for all of the new 
        set of noise (random number) ugens introduced early in 1995 
        by Paris Smarargdis - the zlinrand family.

        To complete the family, there is now an xunirand ugen for 
        uniform distribution of random numbers between 0 and the value 
        given to the ugen.

        See CS_RAND.TXT.

        Also a slight change has been made to entry.c to make the 
        inorm parameter of kpow and apow optional like README.csound 
        says it is.     



------------------
|                |
|  .ZIP  FILES   |
|                |
------------------


CSRW_EXE.ZIP    Just the CSOUND.EXE program.  Be sure to get 
                CSRW_DOC.ZIP as well.

CSRW_DOC.ZIP    All the doco you need, except for the Csound manual.
                Includes the README.csound which documents new ugens 
                added to April 95.  Also contains the new and modified 
                source code.  See full list below.

CSRW_SRC.ZIP    This is the complete set of source code I used for 
                making the CSOUND.EXE program with DJGPP. It contains 
                only a makefile for DJGPP (which should be fine for 
                any GNU C compiler).  It contains the original 
                versions of files I have modified.  It is only the 
                code for the CSOUND program itself - not the 
                utilities.  However all the code is there - not just 
                files needed for an MSDOS compilation.

                All new and modified code is extensively documented - 
                including details of how to patch it into another set 
                of source files.

                The contents of CSRW_SRC.ZIP are further documented in 
                the FILES.TXT file which is included in it.  

                (The above three files consititute everything you need 
                from me directly.)


CSJF_SRC.ZIP    John Fitch's source release of 17 April (actually all 
                the files are 14 April or earlier) - complete 
                with sources for all the utilities.  This is what my 
                work is based on.  See notes in CSDJGPP3.TXT on 
                tweaking this source to work with DJGPP.

                See the description of below of README.CSO for a list 
                of the ugens and fgens which are in this release.

                John probably does not support this source - see his 
                site for his latest work.       

CSJF_EXE.ZIP    .EXE files for the 486 (or 386) - co-processor 
                required.  CSOUND.EXE and the utilities:

                CSOUND   EXE       360,687 14-04-95   7:35p
                HETRO    EXE        85,307 14-04-95   8:15p
                LPCANAL  EXE       143,423 14-04-95   8:15p
                PVANAL   EXE       152,183 14-04-95   8:15p
                CSCORE   LIB        15,360 14-04-95   8:15p
                SCOT     EXE        51,123 14-04-95   8:15p
                SCSORT   EXE        43,404 14-04-95   8:15p
                EXTRACT  EXE        49,687 14-04-95   8:15p
                SNDINFO  EXE        69,167 14-04-95   8:16p
                SCALE    EXE        82,171 14-04-95   8:15p
                MIXER    EXE        84,647 14-04-95   8:16p
                MKGRAPH  EXE       102,771 14-04-95   8:16p

                Since I am not providing source or .EXEs of the 
                utilities, you may want to get this file.  The 
                CSOUND.EXE will draw graphs - using an 800 x 600 SVGA 
                mode if it can find one.  My CSOUND.EXE can't do this.

                These (I think) were compiled with Zortech C.  John is 
                now using Watcom for his later .EXE releases.  He 
                probably does not want to support these older files.    


CS_MAN.ZIP      Contains and MSDOS text file of Barry Varcoe's Csound 
                manual - see below.


------------------
|                |
|   DOCO FILES   |
|                |
------------------

                (First the two basic Csound doco files you definitely 
                need.  I have turned these into standard MSDOS text 
                files. Otherwise they are original.) 

CS_MAN.TXT      MSDOS text file derived from the original Csound 
                manual by Barry Vercoe.  This is was a Macintosh Word 
                file and is available at the MIT site.

                This file is the only one listed here which is not in 
                CSRW_DOC.ZIP.   

CS_MAN.ZIP      .ZIP of the above.


README.CSO      MSDOS text file.  A copy of John Fitch's README.csound 
                from April 95.  This documents the new ugens added to 
                that time. 

                These ugens and function generators include a granular 
                synthesizer, a new set of filters, a new variable 
                delay, a multitap delay, a new reverb, an envelope 
                follower, various noise generators, a power function 
                generator and two gen routines, GEN20 and GEN21.  
                There are also two ungens for convolution.

                grain   
                butterhp butterlp butterbp butterbr     
                vdelay  
                multitap        
                reverb2 
                follow
                xlinrand xtrirand xexprand xbexprnd xcauchy xpcauchy  
                xpoisson xgauss   xweibull xbeta 
                kpow     apow   

                GEN20 - f tables of 9 types of window: Hamming, 
                Hanning, Bartlett ( triangle), Blackman ( 3 - term),
                Blackman - Harris ( 4 - term), Gaussian, Kaiser,
                Rectangle and Sinc.

                GEN21 - f tables of different random distributions: 
                Uniform, Linear, Triangular, Exponential, 
                Biexponential, Gaussian, Cauchy, Positive Cauchy, 
                Beta, Weibull and Poisson.

                (The above were written by Paris Smarargdis.)   

                From Greg Sullivan, a convolution ugen and an an 
                analysis utility program to go with it:

                convolve        
                cvanal -   Impulse Response Fourier Analysis for 
                           convolve operator.


UGRW1.TXT       Full doco of the new ugens mentioned above for 
                UGRW1.C.  Also a discussion of how good it would be to 
                have arrays in Csound, and why I wrote the "zak" 
                system in the interim.

UGRW2.TXT       Describes kport and the new k rate controlable 
                filters: ktone, katone, kreson & kareson 


CS_RAND.TXT     Describes the changes to the random noise functions in 
                CMATH.C.


FILES.TXT       Describes the files in CSRW_SRC.ZIP.


CSDJGPP3.TXT    Describes how I obtained DJGPP, fired it up, got the 
                Csound source in April and tweaked to to produce a 
                CSOUND.EXE.  Basic reading for anyone interested in 
                using DJGPP to invent their own variants of Csound.


CSRW_HIS.TXT    History file of my Csound work.


CSRW_DOC.TXT    This file.


 
-------------------------
|                       |
|   COPYRIGHT NOTICES   |
|                       |
-------------------------

CSOUND was originally written by Barry Vercoe at MIT Media Lab.
Other people have made contributions, and some of them have
their copyright notices in the source code.
I started with the source from John Fitch.
Here are the relevant copyright notices.  Barry's is from
the Csound manual 1992.  John's is from his README.csound
(README.CSO) file of April 1995.


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

Copyright 1986, 1992 by the Massachusetts Institute of
Technology.  All rights reserved.

Developed by Barry L. Vercoe at the Experimental Music Studio,
Media Laboratory, M.I.T., Cambridge, Massachusetts,
with partial support from the System Development Foundation
and from National Science Foundation Grant # IRI-8704665.

Permission to use, copy, or modify these programs and their
documentation for educational and research purposes only and
without fee is hereby granted, provided that this copyright and
permission notice appear on all copies and supporting
documentation.  For any other uses of this software, in original
or modified form, including but not limited to distribution in
whole or in part, specific prior permission from M.I.T. must be
obtained.  M.I.T. makes no representations about the suitability
of this software for any purpose.  It is provided "as is" without
express or implied warranty.

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

                              John Fitch
                   School of Mathematical Sciences
                          University of Bath
                             Bath BA2 7AY
                               England
                         Tel: +44-1225-826820
                         FAX: +44-1225-826492
                    E-mail: jpff@maths.bath.ac.uk
                       or  J.P.Fitch@bath.ac.uk
                                   
            (also Codemist Ltd, Tel/FAX: +44-1225-837430)

The mixer, graphing and SoundBlaster support are probably my
copyright, and I hereby give permission to use, copy, or modify this
code for any purpose whatsoever.  I would like my name to remain in
there, but I do not insist.

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

Modifications and new code provided by Robin Whittle are provided
without warranty etc. etc.  They are copyright 1995 Robin Whittle.

Use of this code for non-commercial software products is permitted, 
provided the source code is made freely available according to the 
principles of the Free Sofware Foundation, with this copyright notice
attached - and those of Barry Vercoe and John Fitch.

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

---------------------
|                   |   
|   MY PRIORITIES   |
|                   |
---------------------


When a publicly available program is altered and extended by someone 
other than the original author, there is cause for concern about 
trouble arising from incompatible versions of the same program being 
in circulation  - leading to:

1 -     .SCO and .ORC files which work with one Csound and not 
        another.

2 -     The original author getting asked to help with bugs or 
        difficulties unrelated to his own work.

3 -     The new version developing enough momentum and differences to 
        draw a significant number of people from the original - so 
        blunting the momentum of the program, and making it harder for 
        anyone to maintain a version with the best possible features 
        of the two paths of development.

In my case, I have split off from John Fitch's MSDOS Csound lineage 
and chosen his April 95 source release as the basis for my own.  So 
now we have my Csound, John Fitch's and whatever is going on with 
Barry and others at MIT.  

It seems (according to a recent post by Paris) that Barry Vercoe and 
others are working on a Mac version with ugens in files rather than 
built into a single executable program.  Paris reports that this is 
not an ANSI C compatible approach.  He also reports that it is very 
impressive.  I cannot think of an approach with ANSI C of having ugens 
in files - unless there was significant rewriting of the ugens and 
extra code which would inevitably slow the program down.  

I chose John Fitch's April release as my starting point because:

1 -     It worked.  (I made a piece of music I really like with it!)

2 -     John's subsequent release in August contained undocumented 
        changes to dozens of files.  Most (but apparently not all) of 
        this was to make a Windows version.  However the Windows 
        version is very awkward to use, so I am not interested in a 
        Windows version unless a more sophisitcated interface is 
        developed.  For now, I am quite happy with MSDOS or a DOS box 
        under Win3.1 or Windows 95.  The altered files had tabs 
        expanded to spaces and so it was going to take an awfully long 
        time to figure out which changes were not related to the 
        Windows mods.  I asked for some guidance in which files had 
        been changed for other reasons and to date have not had a 
        reply.  Life is too short to be trying to keep up with poorly 
        documented mods to a complex program.


My reasons for altering and extending Csound:

1 -     I wanted the table read bugs fixed and wanted all the features 
        which I have now added.  Virtually all of these will help me 
        make music.  The rest are just there for completeness - for 
        instance I may never use some of the init time versions of 
        these ugens, but since I was working on them I figured I 
        should make all useful versions of them.

2 -     I want to be able to use this as a reliable tool for making 
        music.  There are a few flaky things about it and ultimately I 
        want to comment (and bug fix) as much of the program as I can.  
        The table read bugs were only uncovered as I commented the 
        code in preparation to doing table write - but the bugs had 
        certainly been causing some people trouble and would have 
        upset my music.

3 -     I am really excited about Csound.  My background is in 
        modifying musical instruments and Csound is like a wonderful 
        instrument that can be cleanly modified to a very high degree 
        - with the cost of time rather than hardware.

 
Csound is an immensely flexible tool.  There is enormous variation 
between people in their musical tastes.  It is not surprising that any 
flexible instrument will be used in differing and incompatible ways.  

One of the wildest, weirdest musical instruments (I think the weirdest 
invented in the Western World) is the pedal steel guitar.  With ten 
strings, no soundboard, a magnetic pickup, it looks more like an 
ironing board than a guitar.  It is played with finger picks, and a 
foot pedal for volume control.  Up to a dozen foot pedals and knee 
levers stretch and slacken the strings in complex ways, and the pitch 
of the strings is controlled by a "steel" a lead filled chrome plated 
tube held in the left hand and pressed to the strings.  There are no 
frets. 

Pedal steel guitars have a number of possible standard tunings and 
pedal configurations.  Some have two sets of strings and pedals so two 
completely different arrangements can be used.  I read that most 
players start with a standard tuning - Nashville E9.  Many of the keen 
ones get frustrated at what they can't do with the standard approach 
(there are a daunting array of things you _can_ do with the standard 
setup).  So they think of another arrangement, redesigning and 
retuning their machine - engaging a technician to custom modify the 
levers and cams to their exact requirements - which are likely to be 
different from anyone elses.  This may go through several cycles as 
they refine their instrument design.

Pedal steel playing requires extraordinary physical skill - with 
precision movement and delicacy.  These players have to keep their 
chops up and are constantly practicing.  However they can only play 
properly on their own instruments.

Csound is my pedal steel guitar! (I bought and sold a student model 
pedal steel guitar - the optionitis and physical skills were beyond 
me).

I will attempt to make Csound into what I want it to be, including 
external programs to process another file type into an orchestra and 
score.

I don't know how many people will want to approach things my way, but 
I will try to assist those who can benefit from my work.  I have 
benefited from other people's Csound work.

So in working on Csound I will attempt to:

1 -     Work on the margins of the program - the unit 
        generators - rather than in the core of the language.  

        This means that my code can easily be installed in someone 
        else's Csound source.


2 -     Try to keep my version up to date with improvements made to 
        other versions.  This will only happen if:

        a -     Other people's changes are worth incorporating - in 
                my opinion, primarily for my purposes.  

        b -     The new code is well documented. (most of Csound is 
                extremely poorly documented.)

        c -     The changes are relatively modular - rather than 
                dozens of changes all over the place.  (The exception 
                would be if someone did a really good Windows 
                version - which would require many changes.)

3 -     Document my changes, my code and the operation of the new unit 
        generators fully - so that I and other people will have 
        minimal trouble using and maintaining the code.


If a fabulous new version of Csound comes along, my changes should be 
pretty easy to add to it.  Since I have no idea when there will be a 
significant upgrade, and since I doubt that anyone else's ideal Csound 
would be ideal for me, I will get on with making my own.

I also hope that the new features I add will stimulate thought about 
what might go into an upgraded version of Csound - or into another 
language.

Of course I hope the changes will help other people make music too - I 
would be keen to hear the results!


-----------------
|               | 
|   WISH LIST   |
|               |
-----------------

Modify RDORC.C to get rid of the pesky bug in which spaces are ignored 
when reading orchestra code.  This does not seem to be a useful 
feature and can cause confusion when a comma is left out and two 
separate variable numbers or names are truncated into one.


Investigate reports of Csound reading strange values when more than 6 
or 7 decimal places are used.

Write a pre-processor so that a single file can be worked on, and from 
it orchestra and score files will be generated to drive Csound.  
Amongst other things I want to have variables (like # define) which 
work in both the score and the orchestra.  I also want instruments to 
be automatically numbered (with potentially multiple numbers) so they 
will execute in the order they appear in the score.  There is a lot 
more to this plan.


Finish the layout updates to my Word for Windows 2.0 version of the 
Csound Manual - based on Barry's Mac Word version.  Layout of manuals 
is very important, and while I have made improvements, it is not 
finished enough to release.  Maybe add in the new ugens, and my new 
ugens to the end - or perhaps the main part of the manual.


Refine my binaural model instrument - making its X, Y and Z input 
parameters be driven from zk variables and the audio input from a za 
variable.

Then rewrite it as a unit generator to speed up processing.  Then 
write a simplified version which sounds nearly as good but is even 
faster - use this for "draft" mode.

Maybe get hold of some head/pinnae transform impulse responses and 
make a ugen which did a really fine job of binarual placement, using 
actual transforms from recordings and full three dimensional 
placement.

Get a Zefiro digital audio input/output board, and a DAT, so I can do 
recordings and direct digital out.  Also use the board with supplied 
software to do backups of hard disk to DAT.  This board comes with 
full source code for the drivers - so I should be able to write a 
Csound driver for it.  It can do input and output at the same time, 
so maybe Csound could be used to do some very simple real-time audio 
processing.  There are two boards - the simple one is US$350.  The 
fancy one has a DAC on it, and a 24 bit DSP for sample rate conversion 
etc.  Contact Greg <Hanssen@netcom.com>.

Get the graphic display happening, and make a ugen to display table 
contents during performance.

Provide ugens for reading and writing two dimensional tables - with or 
without interpolation.

Provide a ugen for writing a table out to a files.

Provide a way of spitting out short files of the sound made so far - 
so that in a long Csound "cooking" session, you can hear the progress 
without stopping the process.  Mayby use a LAN to send the file to 
another machine which can play it indepenedantly. This may work fine 
on a single machine with Csound in a Windows DOS box.

Look at ways of generating a MIDI file from within Csound - so the 
compositional structures I create with instruments can write to the 
MIDI file - to drive MIDI synthesisers and analog equipment via a MIDI 
to control voltage converter.


Of course there is lots of music to make and instruments to create - I 
don't want to dwell on the "dark side".

<<<<
