CIGAL Workshop

Programming

Jim Voyvodic

August 11, 2008

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

CIGAL Variables

•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

Register variables

There are 10 “register” real number variables that arealways 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

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)

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 fnamedeclare global string list slistdeclare global byte array b1 b2 b3 b4declare global integer array i1 i2 i3 i4declare global array a1 a2 a3 a4declare global integer solid iii1 iii2 iii3 iii4declare global long image mm1 mm2 mm3 mm4

; standard shared memory variablesdeclare global byte array bbuf(512)declare global integer array ibuf(256) = bbufdeclare global long array lbuf(128) = bbufdeclare global real array rbuf(128) = bbuf

The scripts “pdigminit.imp” and “showplay.imp” also declare many commonly used variables.

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, lpt101cursx, cursy

• Variables assigned automatically by Initialize• Disk files can be used as implicit variables

e.g. ^^junk.txt~~names.txt

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 declareddimensions 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

Limited stack memory

When performing complex arithmetic, CIGALautomatically 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 saferto break up calculations using large variables intoseparate steps, to avoid the need for temporary datastorage. So if A, B, C, and Y are arrays, try:

a1 = b**2a2 = a * ca2 = 4 * a2a1 = a1 – a2a1 = sqrt(a1)a2 = 2 * aa1 = a1 / a2y = a1 - b

Common CIGAL commands

CIGAL has over 300 commands and functions.The most commonly used are:

declare - declare a data variabledefine - define a preprocessor aliasshow - show the status of a variableread - read a filewrite - write a filetype - print data valuesftype - formatted printformat - formatted print into a text stringexecute - execute a command stringmap - use data values as index to lookup tablemenu - load a GUI menuaccept - request user inputif - test conditionwhile - loop conditiondefault - assign default program argumentsreturn - return from a CIGAL programrealtime - run a real-time program

and arithmetic expressions

Real-time programming

The REALTIME command reads, compiles, and executesa 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 screenr_text 0 0 0 i1 s1 1 ; put textr_uwait 0 0 0 stemp ; wait for responser_ifeq 0 0 0 stemp 113 r_quitr_endifr_erase 0 0 0 0b3b3b3h ; gray screenr_repeat 0 0 0 7 50000 r_bfill 0 0 0 l1++ ii1 ; color in boxr_endr_wait 0 0 +0 300000r_quit

}

Combining Showplay real-time modules

; select default module filesfile_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.TMPif(?file_rtrig > 0) list file_rtrig 0 > rtime.tmpif(?file_raread > 0) list file_raread 0 >> rtime.tmpif(?file_ruread > 0) list file_ruread 0 >> rtime.tmpif(?file_rdread > 0) list file_rdread 0 >> rtime.tmpif(?file_rresp > 0) list file_rresp 0 >> rtime.tmpif(?file_rmain > 0) list file_rmain 0 >> rtime.tmpif(?file_rumain > 0) list file_rumain 0 >> rtime.tmpif(?file_rmain2 > 0) list file_rmain2 0 >> rtime.tmpif(?file_rquit > 0) list file_rquit 0 >> rtime.tmpif(?file_ruser > 0) list file_ruser 0 >> rtime.tmp

; run the realtime programrealtime rtime.tmp runlog pdflg

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) usedto create the RTIME.TMP real-time program.

There is an example Showplay PPF in the DEMO folderand also on the Wiki.

Showplay event programming

Currently limited to stimulus files, text, and a fewcommands:

font - change the text fontfix - draw a fiixation crosserase - fill the screen with back_colorreset - reset the clock to 0rwait - wait for a subject responseowait – wait for an operator response

Will soon add ability to jump between multiple stimulus lists and to step through preset lists ofstimuli.