Changes since 6.00RC2 (from logs)
=====================

Many bug fixes and code improvements

New opcodes:  faustgen, array

Added 0dbfs and nchnls override

Added delete tree to the API

Greatly improve array arithmetic operations

Removed limit on number of instances in parallel code

Fixed schedwhen for named instrs

Change to escape characters in score strings -- they do not happen
(this is still subject to change)

Fixed dssi

Use thread-safe internal functions in compilaton etc

Thread-safe use of locales

String variables re-implemented


What is New, What has Changed
=============================

- Build system in cmake (and not scons as in Csound5). 

 - The loadable opcodes are found in the directory named in the
environment variables OPCODE6DIR64 or OPCODE6DIR (note the 6) so it
can co-exist with Csound5

- Support for old hardware and C compilers has been removed; this
includes Macintosh OS9 and earlier, Watcom, Borland and Symmantec C
compilers. 

- Note events can start and end in mid-kcycle.  As this is an
incompatible change it is only invoked with the command-line option
    --sample-accurate
is specified.  Not that this does not work for tied notes, and use of
skipping initialisation has questionable use.

- Instruments can run at local ksmps values using 

setksmps iksmps

as in Csound 5 UDOs.

- A number of table access opcodes have been rewritten but should behave
the same.  Similarly diskin and diskin2 now use the same code and so
diskin should be more stable

- Compilation can be done at any stage, new instruments are added or
replace old ones. Running instances of old instrument definitions are
not affected. Only limitation is that header constants in instr 0 are
read only once at the time of the first compilation. Init-time code
can be placed outside instruments in the global space, and this will
be executed once-only following the compilation. In this case, score
event generation can be completely replaced by orchestra code.

- Two i-time opcodes for compilation:
ires  compileorc   ifilename
compiles an orchestra in ifilename (instr0 ignored)

ires  compilestr    Sinstruments
compiles an orchestra defined in Sinstruments

ires is 0 if successful and non-0 if compilation failed.

 - An i-time opcode for score compilation:

ires readscore Sco
this opcode runs the score preprocessor on Sco and then schedules
new events via the RT event mechanism.

- The old parser is totally gone.

- New syntax in csound6 includes +=, -=, *= and /= operators
Please use += and -= for accumulating reverbs as it gives better
multicore behaviour.

- Multicore support is totally rewritten using a different algorithm for
task-dispatch, which should use less memory and fewer locks.

- Opcodes like add, sub, mul and div are no longer available in opcode
format, only via + - * /

- Any opcode that returns one answer and whose type is the same as the
first argument can be used as a function.  This incorporates all
functions in CS5, but also functions of two arguments such as taninv2
and divz, and opcodes like vco2.

- A statement can be broken across lines after a , = or arithmetic
operation.

- Arrays exist in multidimensional format.  They are created (usually)
with init opcode or fillarray
  k1[]  init 4
generates a k-rate 1-D array of length 4.  Similarly
  a2[][] init 4,4
create a square 4x4 a-rate array.
  k2[]  fillarray 1,2,3,4
creates a 4-element vector filled with 1,..4, which also defines the
length.

- Elements are used via indexing in [] such as k1[2] or a2[2][3]
One dimensional arrays replace tvars, and can be used in opcodes like
maxtab, mintab and sumtab (see below). Array setting can be done in
left-hand side of opcodes, i.e.:
  aSigs[0] vco2 .1, 440
  aSigs[1] vco2 .1, 880

- There are a range of new or recoded operations on k-valued arrays,
  most restricted to 1 dimensional arrays (vectors):
  kans minarray ktab       returns the smallest value in the
                         (possibly) multidimensional array
  kans maxarray ktab       is like mintab
  kabs sumarray ktab       returns sum of all values in the array
  ktab genarray imin, imax[, inc]
                         generates vector of values from imin to imax by
                         increments of inc (default 1)
  ktab2 maparray ktab1, "sin" maps the k-rate 1-arg function in the string to 
                         every element of the vector
  ktab2 maparray_i ktab1, "sin" maps the i-rate 1-arg function in the string 
                         to every element of the vector
  ktab2 slicearray ktab1, istart, iend
                         returns a slice of ktab1 from ktab1[istart]
                         to ktab1[iend]
        copyf2array ktab, kfn copies data from an ftable to a vector
        copya2ftab ktab, kfn copies data from a vector to an ftable.

In addition arithmetic on arrays is allowed.  In particular addition,
subtraction, multiplication, division on a element-by-element version
is provided in arithmetic format.  Similar operations between an array
and a scalar are allowed.

- The new realtime priority mode can be switched on with by passing the
--realtime or setting the CSOUND_PARAMS field realtime_mode to 1.

This has the following effects:
1) all opcode audio file reading/writing is handled asynchronously by
a separate thread
2) all init-pass operations are also performed asynchronously.

Functions for asynchronous audio file access have been added (see
below)


The k() fumction can take an a-rate argument in which case it is a
call to downsamp.


Analysis formats:
Hetro/adsyn analysis files can be machine byte-order independent if
created with -X.  Down side is a longer file and a little slower
loading.  The het_export utility will create the independent format
from the old, and het_import is no longer necessary.

cvanal and lpanal will produce machine independent files if -X option
is used.  The convolve and lpread etc opcodes will accept either
format.  You are encouraged to use the machine independent form.
Analysis files produced with -X can be used on other systems.

The number of strings that can be used in a score line is no longer
just one.  It is open ended.

Each instance of any instrument has a scratchpad of 4 values that
persist; allows values to carry to next use of the instrument; hope it
may be useful in legato etc.

If a table number is given as -1 then an internal sine wave equivalent
to "f. 0 16382 10 1" is used.  Attempts to write to this table will
give unpredictable results, but is not policed.  The 16382 can be
change by command line option --sine-size=# where the # is rounded up
to a power of two.

A number of oscil opcodes no have the f-table parameter as optional,
defaulting to the internal sine wave.
(oscil1, oscil1i, oscil, oscil3, oscili, foscil, foscil1,
loscil, loscil3)


in Linux and OSX the treatment of locales is now thread-safe and
local.

 
New API functions.....

    new configuration/parameter setting functions
    PUBLIC int csoundSetOption(CSOUND *csound, char *option);
    PUBLIC void csoundSetParams(CSOUND *csound, CSOUND_PARAMS *p);
    PUBLIC void csoundGetParams(CSOUND *csound, CSOUND_PARAMS *p);
    PUBLIC void csoundSetOutput(CSOUND *csound, char *name, char *type,
                                char *format);
    PUBLIC void csoundSetInput(CSOUND *csound, char *name);
    PUBLIC void csoundSetMIDIInput(CSOUND *csound, char *name);
    PUBLIC void csoundSetMIDIFileInput(CSOUND *csound, char *name);
    PUBLIC void csoundSetMIDIOutput(CSOUND *csound, char *name);
    PUBLIC void csoundSetMIDIFileOutput(CSOUND *csound, char *name);

    new parsing/compilation functions 
    PUBLIC TREE *csoundParseOrc(CSOUND *csound, char *str);
    PUBLIC int csoundCompileTree(CSOUND *csound, TREE *root);
	PUBLIC int csoundCompileOrc(CSOUND *csound, const char *str);
    PUBLIC int csoundReadScore(CSOUND *csound, char *str);
    PUBLIC int csoundCompileArgs(CSOUND *, int argc, char **argv);

    new function for starting csound after first compilation
    PUBLIC int csoundStart(CSOUND *csound);

    new software bus threadsafe getters/setters 
    PUBLIC MYFLT csoundGetControlChannel(CSOUND *csound, const char *name);
    PUBLIC void csoundSetControlChannel(CSOUND *csound, const char *name,
                                        MYFLT val);
    PUBLIC void csoundGetAudioChannel(CSOUND *csound, const char *name,
                                      MYFLT *samples);
    PUBLIC void csoundSetAudioChannel(CSOUND *csound, const char *name,
                                      MYFLT *samples);
    PUBLIC void csoundSetStringChannel(CSOUND *csound, const char *name,
                                       char *string);
    PUBLIC  void csoundGetStringChannel(CSOUND *csound, const char  *name,
                                        char *string);

    new table threadsafe copy functions
    PUBLIC void csoundTableCopyOut(CSOUND *csound, int table, MYFLT *dest);
    PUBLIC void csoundTableCopyIn(CSOUND *csound, int table, MYFLT *src);
    
    API has been made threadsafe so that performance and control can
    occur in separate threads (after a call to csoundStart() or
    csoundCompile()). Threadsafety is ensure by 1) use of atomic
    read/writing to control channels 2) spinlocks in audio and string
    channels 3) mutexes protecting compilation, score events and table access

Invalue/outvalue and channel callbacks and callback setters have been removed.
csoundQueryInterface() has been removed

New internal functions in CSOUND:

    void (*FlushCircularBuffer)(CSOUND *, void *);
     flush circular buffer.
    void *(*FileOpenAsync)(CSOUND *, void *, int, const char *, void *,
                           const char *, int, int, int);
    unsigned int (*ReadAsync)(CSOUND *, void *, MYFLT *, int);
    unsigned int (*WriteAsync)(CSOUND *, void *, MYFLT *, int);
    int  (*FSeekAsync)(CSOUND *, void *, int, int);
      async file access.
    char *(*GetString)(CSOUND *, MYFLT);
       Extract a string originating from a score-event argument.

functions removed
    void *(*FileOpen)(CSOUND *,
                      void*, int, const char*, void*, const char*);

The "private" parts of the API have been changed considerably.  Also
structures like EVTBLK have changed



The LINKAGE1/FLINKAGE1 macros are renamed as LINKAGE_BUILTIN/FLINKAGE_BUILTIN



Template for arate perf-pass opcodes is
------------------------------------------------------------------------
int perf_myopcode(CSOUND *csound, MYOPCODE *p)
{
    uint32_t offset = p->h.insdshead->ksmps_offset;
    uint32_t early  = p->h.insdshead->ksmps_no_end;
    uint32_t nsmps = CS_KSMPS;
    ...
    if (UNLIKELY(offset)) memset(p->res, '\0', offset*sizeof(MYFLT));
    if (UNLIKELY(early))  {
      nsmps -= early;
      memset(&p->res[nsmps], '\0', early*sizeof(MYFLT));
    }
    for (n=offset; n<nsmps; n++) {
        .....
        p->res[n] = ....
    }
    return OK;
}
------------------------------------------------------------------------


for opcode developers.....

TECHNICAL CHANGES
=================

OENTRY structure has changed and has a new dependency field; please
use this field as it is required for multicore semantics.  You could
set it to -1 and disallow all parallelism, but at least it is safe.

All opcodes that touch audio should take note of sample-accurate code

A number of previous API functions are removed; OpenFile and OpenFile2
both replaced by new OpenFile2 with additional argument.

Additions have been made for arg type specifications for opcodes.
  * Any-types have been added, as follows:
    * '.' signifies a required arg of any-type
    * '?' signifies an optional arg of any-type
    * '*' signifies a var-arg list of any-type
  * Arrays are now specified using "[x]" where x is a type-specifier.
    The type-specifier can be any of the of the current specifiers, 
    including any-types.  See Opcodes/arrays.c for example usage.

New Type System
===============
A new type system has been added to Csound6, and significant changes
have been made to the compiler. The previous system for handling types 
involved depending on the first-letter of a variable's name every time
it was used to determine type. This meant there was a lot of re-checking
of types. Also, adding new types was difficult, as there was a lot of
custom code that had to be updated to check for new type letters. 

In Csound6, a separate system of types was added.  Types are defined as
CS_TYPE's.  The creation of variables from types and the initialisation
of memory has been encapsulated within the CS_TYPE's. This change 
allows easier addition of new types, as well as generic calculations of
memory pools, amongst other things.  

The compiler has been modified since Csound5 to now use the type system
as an integral part of its semantic checking phase.  Variables are now
registered into a CS_VAR_POOL when they are first defined, with the
CS_VARIABLE having a reference to its CS_TYPE.  After first time
definition within the pool, the type information is then looked up in
consequent variable lookups, rather than re-calculated from the variable
name.  This opens up possibilities for new variable naming and typing 
strategies, i.e. using "myVar:K" to denote a k-rate arg.  This also 
opens up possibilities for user-defined types, such as 
"data myType kval, aval", then using "myVar:myType" to define a var
of that type.  (The previous is speculative, and is not an active 
proposal at this time.)

The addition of the type system has formalised the static type system 
that has existed in Csound prior to Csound6. It has, arguably, simplified
the code-base in terms of type handling, as well as laid the ground work
for future type-related research to be integrated into Csound. 


