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. CIGAL Variables Number formats bit1-bit integer nibble2-bit integer quad4-bit integer byte8-bit integer integer16-bit integer long32-bit integer real32 bit floating point Variables Number single value (#) Array1-D number list (^) Matrix2-D number matrix (^^) Solid3-D number matrix (^^^) Image2-D pixel number matrix (%) Stringnull-terminated text (~) String listarray of text strings (~~) Pointerpointer to another variable

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. Variables – Data storage locations 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

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. Real-time programming 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_erase0 0 0 0ff00h; green screen r_text0 0 0 i1 s1 1; put text r_uwait0 0 0 stemp; wait for response r_ifeq0 0 0stemp 113 r_quit r_endif r_erase0 0 0 0b3b3b3h; gray screen r_repeat0 0 07 50000 r_bfill0 0 0l1++ ii1; color in box r_end r_wait0 0 +0300000 r_quit }

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.