
CSL README

This directory contains the source code and documentation for the 
CREATE Signal Library (CSL, pronounced "sizzle," previously called the 
CREATE Oscillator, CO). It is a work in progress; this is release 4.2,
March, 2007 - June, 2009.

The home page for CSL is http://FASTLabInc.com/CSL.

CSL is known to work on Mac OSX, most flavors of UNIX/Linux, and (with 
somewhat limited features) on MS-Windows.

About CSL

CSL is a C++ class library, to use it, you write and compile C++ programs like 
the ones in the CSL/Tests directory. These programs will generally use the CSL 
class library, and may read input files or respond to in-coming MIDI or OSC commands.

This means that the target users for CSL are C++ programmers (familiar with the 
development tools of their platforms, e.g., Xcode on the Mac, KDevelop on Linux, or 
Visual Studio on MS-Windows) who also know some software sound synthesis language 
such as Csound or SuperCollider (see Curtis Roads' "Computer Music Tutorial").

The best way to get started is to look at the Doxygen-generated API documentation in 
	./Doc/api_doc.tgz
You can untar this file to get the full HTML doc and to print out and study the files 
	CSL/Kernel/CSL_Types.h 
	CSL/Kernel/CSL_Core.h 
and 
	CSL/Sources/SimpleSines.{h,cpp}

Linking with the CSL Libraries

To link CSL programs, you'll need the following packages installed on your machine:
	Cross-platform audio I/O: PortAudio (http://www.portaudio.com) V19 or newer;
	Cross-platform MIDI I/O: PortMIDI (http://www-2.cs.cmu.edu/~music/portmusic);
	Cross-platform sound file I/O: libsndfile (http://www.zip.com.au/~erikd/libsndfile) 
		V1.04 or newer; 
and
	Fast Fourier Transform: FFTW (http://www.fftw.org) package V3.X;
	
The auralizer also requires 
	VRML parser: libcX3D (http://www.cybergarage.org/vrml/cx3d/cx3dcc/index.html)
	(cd CyberX3D; ./bootstrap; ./configure; make)

For testing OSC, grab the sendOSC and dumpOSC tools from
	OpenSoundControl tools: OSC (http://www.opensoundcontrol.org)

The CREATE CSL web site includes pre-compiled versions of these libraries for 
Mac OS X and MS-Windows.

FFTW needs to be compiled in the way described in Sources/Spectral.h. 

CSL main() functions

Note that there are several versions of the main() function; if you're not using
one of the prepared project files, try compiling the library (most of the sources)
with the file Beep_main.cpp as the main. Alternatively, take a look at the bottom 
of Test_main.cpp (or Test_all.cpp) and select a couple of tests to run.

Test targets
	Beep_Test -- simplest FM beep
	CSL_Test -- basic test suite; uses Test_main.cpp
	OSC_Test -- Several; OSC tests, see OSC_main.cpp
	MIDI_Test -- Reads MIDI in
	CSL Client_Server -- compiles 2 executables for remote c/s streaming
	Sensor_Test -- Test OSC-based gesture sensors

Source Code Organization

The subdirectories of CSL are reflected in the project file categories:

	 Tests - Test/demo main() driver functions
	 Kernel - Bufers and FrameStreams
	 Sources - Oscillators, noise, envelopes, PhysMod
	 Processors - Operators, filters, mixers, panners
	 IO - IO drivers and LAN streaming
	 Utilities - Thread and buffer support classes
	 Instruments - OSC/MIDI instrument wrappers
	 Spatializers - Panners and spatializers
	 Documentation - README, etc.
	 Data - Test sounds, HRTF data, etc.

Reading the source

	Set tabs to 4 spaces so comments line up
	Use a syntax-coloring editor, if available;
	Note the naming conventions

Coding Conventions

Naming
	Class, member, and method names are written in "camelCase" as in "UnitGenerator."
	Data members (instance variables) are written with initial "m" followed by embedded caps 
		as in "mOffset."
	Enumeration constants are written with initial "k" followed by embedded caps as in "kDone."

Privacy
	In general data members are protected and have accessor functions where appropriate. 
	The one exception is Buffer which is considered a record class and has public members.

Documentation

See the PDF files in the Doc/ directory. (RTFM)

For further information, please join the CSL mailing list at
	http://create.ucsb.edu/mailman/listinfo/CSL

stp et al. -- January, 1998 - June, 2009
