CIGAL Workshop Programming

1. CIGAL Workshop Programming Jim Voyvodic August 11, 2008

2. CIGAL Programming • Main CIGAL scripting language • Vaguely C-like syntax • Operate on whole variable in single instruction • Commands (e.g. “read”, “write”, “initialize”) • Functions (e.g. “sqrt()”, “random()”) • Arithmetic (e.g. “a = (b + c)/d”) • Structured language (If/else, while, subroutines) • Real-time processor language • Assembly language-like syntax • Simple command repertoire • Fast, accurate execution timing • Asynchronous & parallel processing • Showplay programming • Limited event repertoire

3. Number formats • bit 1-bit integer • nibble 2-bit integer • quad 4-bit integer • byte 8-bit integer • integer 16-bit integer • long 32-bit integer • real 32 bit floating point • Variables • Number single value (#) • Array 1-D number list (^) • Matrix 2-D number matrix (^^) • Solid 3-D number matrix (^^^) • Image 2-D pixel number matrix (%) • String null-terminated text (~) • String list array of text strings (~~) • Pointer pointer to another variable CIGAL Variables

4. Register variables There are 10 “register” real number variables that are always defined locally: r0-r9 R1-R9 are typically used for storing R0 is used to return error status for some commands. For example, “read” and “write” will return with the number of records successfully transferred in R0, or a negative number if there was an error. The “initialize” command will return a negative value if there was a problem initializing a device. e.g. read fname mm1 if(r0 <= 0) type “error reading file:” fname

5. Declaring variables • DECLARE – create a new variable • Variable names are limited to 12 characters • UNDECLARE – destroy a data variable • Allocating memory -- ARRAY(), MATRIX(), SOLID() • e.g. aa1 = matrix(20,400) • bbb1 = solid(100,200,50) • aa1 = matrix(400,20) • RELEASE – deallocate memory without undeclaring • Local versus global • Global – values available to any subroutine • Local – values only available in this routine • Declare in command window is global • Declare in script defaults to local • DEFINE – preprocessor alias (like in C)

6. Standard pre-defined variables • The standard CIGAL startup script (sysstart.imp) • declares several variables of each type, which can be • used as handy general-purpose data variables. • declare global string s1 s2 s3 s4 fname • declare global string list slist • declare global byte array b1 b2 b3 b4 • declare global integer array i1 i2 i3 i4 • declare global array a1 a2 a3 a4 • declare global integer solid iii1 iii2 iii3 iii4 • declare global long image mm1 mm2 mm3 mm4 • ; standard shared memory variables • declare global byte array bbuf(512) • declare global integer array ibuf(256) = bbuf • declare global long array lbuf(128) = bbuf • declare global real array rbuf(128) = bbuf • The scripts “pdigminit.imp” and “showplay.imp” also • declare many commonly used variables.

7. User-defined variables • Explicitly declared variables • e.g. declare real x y z • declare integer array jdata(4,200) • declare byte matrix bmatrix • Stack – Automatically allocated (800 Kb) • High stack – User allocated (RAM limited) • Intrinsic pseudo-variables • Provide access to status and control variables • See http://fourier.biac.duke.edu/wiki/doku.php/jvs:cigal:manual:chapter4 • Hardware device pseudo-variables • Number variables associated with data channels • e.g. adc0, adc1, digio, lpt100, lpt101 • cursx, cursy • Variables assigned automatically by Initialize • Disk files can be used as implicit variables • e.g. ^^junk.txt • ~~names.txt Variables – Data storage locations

8. Data variable subsets In general, CIGAL commands or functions can operate on whole variables, or subsets of variables. Examples: aa2(3,4) A single element of matrix aa2 aa2(3) A single row of matrix aa2 aa2(,4) A single column of matrix aa2 aa2(2:5,4:99) A 3x96 matrix subset of aa2 Assigning data to a variable without explicitly declared dimensions automatically allocates memory. aa3 = aa2(100:199,200:249) ;Create 100x50 aa3 Assigning data to a subset only affects those elements. aa2(50:149,100:149) = aa3

9. Limited stack memory When performing complex arithmetic, CIGAL automatically allocates temporary stack storage space for intermediate results. e.g. y = -b + sqrt(b**2-4*a*c)/2*a Because stack storage space is limited, it is safer to break up calculations using large variables into separate steps, to avoid the need for temporary data storage. So if A, B, C, and Y are arrays, try: a1 = b**2 a2 = a * c a2 = 4 * a2 a1 = a1 – a2 a1 = sqrt(a1) a2 = 2 * a a1 = a1 / a2 y = a1 - b

10. Common CIGAL commands • CIGAL has over 300 commands and functions. • The most commonly used are: • declare - declare a data variable • define - define a preprocessor alias • show - show the status of a variable • read - read a file • write - write a file • type - print data values • ftype - formatted print • format - formatted print into a text string • execute - execute a command string • map - use data values as index to lookup table • menu - load a GUI menu • accept - request user input • if - test condition • while - loop condition • default - assign default program arguments • return - return from a CIGAL program • realtime - run a real-time program • and arithmetic expressions

11. The REALTIME command reads, compiles, and executes • a real-time program. There are over 100 real-time • commands in CIGAL. They all start with “r_”. • Example: • s1 = “Press a button” • l1 = { 0ff0000h 0ff00h 0ffh 0ffff00h 0ffffh 0ffffffh 0 } • i1 = { scrwid/2 100 } • ii1= { 100 100 699 499 } • realtime { • r_erase 0 0 0 0ff00h ; green screen • r_text 0 0 0 i1 s1 1 ; put text • r_uwait 0 0 0 stemp ; wait for response • r_ifeq 0 0 0 stemp 113 • r_quit • r_endif • r_erase 0 0 0 0b3b3b3h ; gray screen • r_repeat 0 0 0 7 50000 • r_bfill 0 0 0 l1++ ii1 ; color in box • r_end • r_wait 0 0 +0 300000 • r_quit • } Real-time programming

12. Combining Showplay real-time modules ; select default module files file_rtrig = dir_rtcode // "rt_trigger.txt" file_raread = dir_rtcode // "rt_aread.txt" file_ruread = dir_rtcode // "rt_uwait.txt" file_rdread = dir_rtcode // "rt_dwait.txt" file_rresp = dir_rtcode // "rt_response.txt" file_rmain = dir_rtcode // "rt_stimon.txt" file_rmain2 = dir_rtcode // "rt_stimoff.txt" file_rquit = dir_rtcode // "rt_finish.txt" ; create the realtime program RTIME.TMP if(?file_rtrig > 0) list file_rtrig 0 > rtime.tmp if(?file_raread > 0) list file_raread 0 >> rtime.tmp if(?file_ruread > 0) list file_ruread 0 >> rtime.tmp if(?file_rdread > 0) list file_rdread 0 >> rtime.tmp if(?file_rresp > 0) list file_rresp 0 >> rtime.tmp if(?file_rmain > 0) list file_rmain 0 >> rtime.tmp if(?file_rumain > 0) list file_rumain 0 >> rtime.tmp if(?file_rmain2 > 0) list file_rmain2 0 >> rtime.tmp if(?file_rquit > 0) list file_rquit 0 >> rtime.tmp if(?file_ruser > 0) list file_ruser 0 >> rtime.tmp ; run the realtime program realtime rtime.tmp runlog pdflg

13. Programming examples The PDIGM and IMP subfolders in the CIGAL system directory are full of examples of simple CIGAL programs. The CODEBLOCKS subfolder contains all of the preprocessing and postprocessing subroutines (.IMP) as well as the default real-time modules (RT_*.txt) used to create the RTIME.TMP real-time program. There is an example Showplay PPF in the DEMO folder and also on the Wiki.

14. Showplay event programming • Currently limited to stimulus files, text, and a few • commands: • font - change the text font • fix - draw a fiixation cross • erase - fill the screen with back_color • reset - reset the clock to 0 • rwait - wait for a subject response • owait – wait for an operator response • Will soon add ability to jump between multiple • stimulus lists and to step through preset lists of • stimuli.