Tutorial 1

Creating an openGL window

This tutorial explains the .csd file syntax and the creation and clearing of an openGL window in CsoundAV. It might be complicated at first, specially if you're new to programming, but you'll soon see the benefits.

The csound program should include only the parts in italics. Type only those parts into the text editor. Be careful with uppercase and lower case characters in openGL instructions, flags and section headers. CsoundAV is case sensitive with these instructions (though not with the common sound instructions).

I have deliberately not included the original file....

All .csd programs start like this:

This just tells the compiler (i.e. CsoundAV) that this is the start and that the file is in .csd (unified) format. The different sections in a csd file begin <Section> and end </Section>. You can see this clearly in this example. The sections are: CsOptions, CsInstruments and CsScore. The only other section the compiler will recognize is CsVersion, which limits the minimum version needed to run the csd file, but is rarely used.

This section contains the command line flags that are used when compiling the csd file. They are added to the command line when a front end calls csound to compile.

This flag tells csound not to render audio. This is useful for video only programs. See the Csound Manual and the CsoundAV html help for more command line flags.

This marks the end of the CsOptions section.

Here's where everything starts:

This section defines the 'instruments' that will be created when the program compiles. It is also referred to as the Orchestra. The term 'instrument' might be a little confusing because a csound instrument doesn't necessarily produce sound. An instrument can be thought of as any process or group of processes made by csound. An instrument can be a control instrument, an input instrument, an effects instrument (among others), or like in this case a graphic instrument. Instruments are written to be called later in the Score. Just creating an instrument in the Orchestra has no effect.

This line must be present if you will be using CsoundAV openGL capabilities. It contains macro definitions that will make later programming more intuitive. Don't worry about this line, just put it there.

This is the standard Csound header. It states the sample rate (sr), control rate (kr), the control samples per second (ksmps) and the number of output channels. This affects only the audio engine, so the values are very low in this case. This header is a requirement of Csound. It must always be there.

This is where the graphics part starts:

Here you set the number of frames per second for the GL window. A usual value is 30.

Here you define the openGL window name and size of the openGL window to be created. Experiment with other values.

This command must accompany the previous GLpanel.

Here we define the first instrument:

instr is the csound command to define an instrument. Every instrument must have a unique number, and must end with an endin instruction.

This instruction creates the window. The previous GL instructions just defined the window, while this command creates it.

Here we set the background color. The values used are from 0 to 1 and represent the red, green and blue (RGB) values. The fourth value sets the alpha value. Don't worry about it for now. Try using different values to produce different colours.

glClear is an openGL instruction to clear the window. You generally want to use the value $GL_COLOR_BUFFER_BIT + $GL_DEPTH_BUFFER_BIT, which will completely clear the window.

This tells CsoundAV where in the graphic render chain to put the GL instructions above. A common value is 1.5. This value is fine for most cases. If this command is missing, the openGL instructions don't enter the rendering chain and therefore have no effect. Always remember to put it after a set of openGL instructions.

This is the end of the instrument.

The end of the CsInstruments section. With this program only one instrument (instr 1) will be available.

The score starts. Score in csound means 'instrument calls'. The score command i calls an instrument. The numbers following i , specify the instrument number, the start time (in seconds)and the duration (in seconds). The i command below calls instrument 1 at second 4, for a length of 100 seconds. Try changing the start time and the duration.

The score section ends and then the .csd file ends