printk kval, ispace [, itime] printks "txtstring", itime, kval1, kval2, kval3, kval4
itime - How much time in seconds is to elapse between printings. (Default 1 second.)
However (at least with DJGPP) the \n style of character codes are not interpreted by printf. This ugen therefore provides certain specific codes which are expanded:
\n or \N Newline \t or \T Tab ^ Escape character ^^ ^ ~ Escape and '[' These are the lead in codes for MSDOS ANSI.SYS screen control characters. ~~ ~An init error is generated if the first parameter is not a string of length > 0 enclosed in double quotes.
[For some reason (at least with the DJGPP version, the program crashes if a null string - "" - is given. This seems not to be due to this ugen. This should be tidied up sometime.]
A special mode of operation allows this ugen to convert kval1 input parameter into a 0 to 255 value and to use it as the first character to be printed.
This enables a Csound program to send arbitrary characters to the console - albeit with a little awkwardness.
[printf() does not have a format specifier to read a float and turn it into a byte for direct output. We could add extra code to do this if we really wanted to put arbitrary characters out with ease.]
To acheive this, make the first character of the string a # and then, if desired continue with normal text and format specifiers. Three more format specifers may be used - they access kval2, kval3 and kval4. 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.
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.
printks \"Volume = %6.2f Freq = %8.3f\n\", 0.1, kvol, kfreq, 0, 0This would print:
Volume = 1234.56 Freq = 12345.678
printks \"#x\\y = %6.2\n\", 0.1, kxy, 0, 0, 0This would print a tab character followed by:
x\y = 1234.56
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 12345There 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.