QUICK-REF - CsoundManual - Top of this section - Previous - Contents - Index - Next 

printk, printks

   printk       kval, ispace [, itime]
   printks      "txtstring", itime, kval1, kval2, kval3, kval4

DESCRIPTION

These ugens are intended to facilitate the debugging of orchestra code.

INITIALIZATION

ispace - How many spaces to insert before it is printed. (Max 130.)

itime - How much time in seconds is to elapse between printings. (Default 1 second.)

txtstring - itime - How much time in seconds is to elapse between printings. (Default 1 second.)

kvalx - The k rate values to be printed. Use 0 for those which are not used.

PERFORMANCE

printk prints one k rate value on every k cycle, every second or at intervals specified. First the instrument number is printed, then the absolute time in seconds, then a specified number of spaces, then the kval value. The variable number of spaces enables different values to be spaced out across the screen - so they are easier to view.

printks is a completely different ugen - similar to printf() in C.

It is highly flexible, and if used together with cursor positioning codes, could be used to write specific values to locations in the screen as the Csound processing proceeds. With MSDOS, a colour screen and ANSI.SYS, it would be possible to have multiple colours, flashing displays - looking like NASA mission control, with k rate variables controlling the values displayed, the location on the screen where they are displayed, their colour etc.

There is also a special mode where a float variable is rounded to the next lowest integer, and ANDed with 0 1111 1111 to produce a character between 0 and 255 to be sent to be printed.

This elaborate use is a bit over the top - a hacker's paradise. But printks can be used simply, just to print variables for debugging.

printks prints numbers and text, with up to four printable numbers - which can be i or k rate values.

For instance:

printks \"Volume = %6.2f Freq = %8.3f\n\", 0.1, kvol, kfreq, 0, 0
This would print:
Volume = 1234.56 Freq = 12345.678
printks \"#x\\y = %6.2\n\", 0.1, kxy, 0, 0, 0
This would print a tab character followed by:
x\y = 1234.56

DISCUSSION:

Both these printing ugens can be made to run on every k cycle - or at least every k cycle they are run in the instrument. Conditional goto statements can be used to run them only at certain times or when something goes wrong. To make them run on every k cycle like this, set itime to 0.

When itime is not 0, then (if the orchestra code runs the ugen on every k cycle) then the ugen will decide when to print. It will always print on the first k cycle it is called. This means that if you set one of these to print only every 10 seconds, and conditional code in the instrument causes it to be run for the very first time at 3 seconds, then it will print at 3 seconds.

Subsequent runs of the ugen at between 3 and 9.999 seconds would not cause it to print. This could be very useful - set the time to longer than the piece and conditional code in the instrument can be used to report a bug just once, on its first occurrence. You almost certainly do not want a print operation happening every k cycle - it slows the program down too much.

Staying with the 10 second cycle example, if such a printk or printks ugen was called every k cycle, then it would print at 0 seconds (actually the first k cycle after 0), at 10.0 seconds, at 20.0 seconds etc.

The time cycles start from the time the ugen is initialized - typically the initialisation of the instrument.

Damien Miller pointed out an interesting application of these ugens - get the output of the program and sort the lines with a line sorter. The result would be the printed lines sorted first by instrument number, and then by time - for printk. However printks can be made to produce almost anything. The instrument is available as p1 and the time can easily be found and made available as a printks parameter.

One option I have considered but not implemented is for these printed lines to be written to a file as well as to the screen. Let me know if you like this idea, or have any other ideas about debugging.

printf() style %f formatting

One of the less enjoyable parts of C programming is trying to figure out what magic incantations to offer to printf()

All the parameters are floats, so this reduces our decisions to two main issues:

1 -     How many decimal points of precision do we want?  (0 means
        no decimal point.)

2 -     How many digits (or spaces) do we want printed in total - 
        _including_ those after the decimal point?


%f      Just prints with full precision - 123.123456

%6.2f   Prints 1234.12

%5.0f   Prints 12345
There is more to the printf() codes than this - see an ANSI C library reference. Instead of 'f', you can use 'e' to get scientific notation. Using any other format specifiers than f, e, g, E and G will cause unpredictable results, because the parameters are always floating point numbers.

AUTHOR:

Robin Whittle
Australia
May 1997 


QUICK-REF - CsoundManual - Top of this section - Previous - Contents - Index - Next 
HTML Csound Manual - © Jean Piché & Peter J. Nix, 1994-97