Settings File

Stimulus Description File

	255		a decimal integer constant
	0xff		a hexadecimal integer constant
	0377		a octal integer constant
	255.0		a floating point constant

You can have single quoted characters where the ASCII code is returned as an integer. Control characters supported are backspace '\b', tab '\t', new line '\n' and carriage return '\r'.

	'X'		returns 0130
	'\b'		returns code for backspace

Operators

Functions

Special random sequence functions

Procedures

#	procedure must have exactly two parameters

procedure sumate2(2)
{
	sum = $1 + $2
}

#	procedure with a variable number of parameters

procedure sumate
{
	if $? == 1
		sum = $1
	elseif $? == 2
		sum = $1 + $2
	elseif $? == 3
		sum = $1 + $2 + $3
	else
		sum = $1 + $2 + $3 + $4
	endif
}

#	procedures must be declared before they are used.

sumate(1,2)
sumate(1,2,3)

#	the recursive use of functions and procedures
#	to print the value of an integer, one digit at
#	a time

#	return the quotient after dividing by 10

function div10(1)
{
	return $1 / 10
}

#	return the remainder after dividing by ten

function rem10(1)
{
	return $1 % 10
}

procedure printn(1)
{
	@1 = div10($1)
	if @1
		printn(@1)
	endif
	print "%c" rem10($1) + '0'
}

Variable Names

array int ivals[32]
array float ivals[size]

Arrays may be initialised. The declaration my extend over more than one line.

array int data[] = { 1,2,3,4}
array float fdata[] = { 1.0
                        2.0 }

Assignments

Variables are stored either as integers or floating point, depending on the value. By default they are integer, but any operation that involves a floating point operation (eg a constant .22, or trigonometric function) will convert the result to floating point. Note, floating point calculations take longer than integers, so don't use them unless required.

x = 22			# an assignment that will be marked as constant
y = sin(pi / 2)		# the result is still a constant
x = y + 10		# this is not constant, since y may change
constant size = 640	# mark as a constant that cannot be changed
z = 0.22		# this is a constant, and is stored as a floating point number

Flow Control Statements

if logical test

elseif logical test

else

endif

if x == 1
	...	# reached if x = 1
elseif x == 2
	... 	# reached if x = 2
else
	...	# reached for any other value
endif

block

repeat expression

block
	...
	...
	block
		...	# this gets executed 10 times (5 x 2)
	repeat 5
repeat 2

repeat sizeof list

Control Statements

isi nn.n

isi	1.5		# set the ISI to 1.5 seconds

isi xx.x - yy.y

isi	1.0 - 3.0 	# set the ISI to a random value

initial isi nn.n

randomise

Without this option, a pseudo-random sequence is generated, but the same sequence is calculated for each run, which can be handy for debugging the program.

seed n

prompt {"Text of message"}

prompt "Ready for Part 1"

prompt [xposition] [yposition] {"Text of message"}

promptk

path directory path

path stimulus_1
display list1.lst ...
path different_directory
display list2.lst

font font_name

To get a list of inbuilt fonts (and all command and object names) type :-

runstim -h

font library file_path

Logging Data

open mode [ask | replace | append]

log mode verbose | concise

key enable { up | down | both } nnn

You can optionally specify that you want to record keys being released (up), pressed (down) or either (both). The default is down.

block
	display ...	# no response measured
	key enable down 500
	display ...	# collect responses for key presses
	display		# no response measured
repeat ...

Note

key enable { up | down | both } isi

key enable { up | down | both }

key disable

mouse enable { up | down | both } nnn

mouse enable { up | down | both } isi

mouse enable { up | down | both }

mouse disable

external enable [+-=^] data ... nnn

You can specify multiple combinations of change detection by using several operators. Only the last external enable will ever be active.

external enable [+-=^] ... data isi

	external enable + 0x80 isi	# look only at the rising edge of a single
					# input bit
	display image.gif 1000		# display image, collect data from LPT port

	external enable + 0x80 - 0x40	# detect rising bit (0x80) or falling bit (0x40)
	display image.gif 1000

external enable [+-=^] ... data

external disable

log comment "comment text"

log data "format" { expressions }

Display Settings

vesa

local

remote

colour name r,g,b

colour orange 127, 63, 0

background

background r,g,b

background 127,127,127		# a grey background

background colour

fill colour colour | r,g,b

sample colour x y

foreground r,g,b

foreground 255,255,255		# a white foreground

foreground colour

Examples :-

	display file.pcx 30				# a single image for 30ms
	display list.lst 100				# select a random image from a list
	display list.lst once_only 100			# select a random image from a list
							# but only once for each image
	display object 100				# an inline object
		circle ...
		ellipse ...
	end object
	display object.obj 100				# select from a list of objects
	
	display calibrate.pcx waitkey			# display a calibration screen and 
							# wait for a keypress to continue

	display background waitexternal + 0200		# display the background until the Busy bit (bit 7)
							# goes from 0 to 1 on the printer port
	display background waitexternal + 0x80 - 0x40	# detect two different bits
	display type1.pcx 100 strobe [sdata+0100]	# display and send data to remote computer
	display list.lst [20] 100			# display image 20 from the list
	flash type1.pcx 100 type2.pcx strobe 1		# flash and send data to remote computer
							# only on the second of the two images

The offset is introduced by the keyword offset, followed either by a x,y value (offset from the centre), or the keyword random, where the offset in randomly selected from a list built from offset statements

	offset 100,100				# generate some offset table entries
	offset 100,-100
	offset -100,-100
	offset -100,100

	display file.pcx 30 offset -100, -100	# offset up and to the left
	display file.pcx 30 offset 100, -100

	display file.pcx offset random		# select a random offset
						# from a list

sleep nn.n

Stimulus Control

preload screen{1-n} image_specification

preload screen[expression] image_specification

preload bitmap{1-10} object

preload background object

preload bitmap[expression] object

display image_specification

preload bitmap[expression] object

display image_specification

	display image.pcx 100		# single image for 100 milliseconds

display screen{1-n}

	preload screen1 image.lst once_only 100
	preload screen2 image.lst once_only 200
	preload screen3 image.lst once_only 300

	display screen1
	sleep 0.1
	display screen2
	sleep 0.2
	display screen3
	sleep 0.3
OR

	display screen1		# animate a sequence without
	sleep 0			# delays between images
	display screen2		# and don't revert to background
	sleep 0			# between images
	display screen3
	sleep 0
	

flash image_specification_1 image_specification_2

	flash image_1.pcx 100 image_2.pcx 10 # flash image 1 for 100 ms, 
					     # followed by image 2 for 10ms

movie listfile frame_time

	movie list.lst 20		# play list as movie, each frame for
					# 20 milliseconds

movie listfile frame_time repeat_count

	movie list.lst 20 2		# play list as movie, each frame for
					# 20 milliseconds, twice

movie listfile {waitkey | waitmouse}

	movie list.lst 20 waitkey	# play list as movie, each frame for
					# 20 milliseconds, until key is pressed

movie screenx - screeny frame_time {repeat_count}

movie screen[expression] - screen[expression] frame_time {repeat_count}

preload movie object_list.obj

preload movie[number] object_list.obj

movie[number] frame_time {repeat_count}

	preload movie[1] object_list_a.obj

	movie[1] 10

object background single object description

	object background line 0 0 100 100 colour white

object screen{1-n} single object description

object screen[expression] single object description

Object Descriptions

The object is drawn using the current foreground and background colours, but the foreground colour can be overridden by adding the keyword colour followed by a name or red, green, blue values. You can also specify the background colour (and foreground) by using the keywords fgcolour or bgcolour.

Object lists are delineated by the keywords start object and end object (see examples below).

For convenience, a x y pair may be replaced by the word centred, which will place the object in the middle of the screen (handy for overlaying and rotating sprites) . Runstim also keep track of the last position used in objects (like the end of a line). Use the word last to replace a x,y pair as the start position for an object. The values are also keep the the variables last_x and last_y.

start object {"comment"}

end object

start mask

end mask

object name "name here"

no clear

image filename

mask filename

units {global} pixels

units {global} relative

scale {global} xscale, yscale

offset {global} xoffset, yoffset

line x1 y1 x2 y2

rect x1 y1 x2 y2

rectfill x1 y1 x2 y2

reverse rect x1 y1 x2 y2

circle x y radius

circlefill x y radius

reverse circle x y radius

checkerboard rows columns {fgcolour colour} {bgcolour colour}

speckle x y radius {fgcolour colour} {bgcolour colour}

ellipse x y radius1 radius2

ellipsefill x y radius1 radius2

sprite x y filename|bitmap

The sprite must be an image file or bitmap (built by preload), and not a list or object.

sprite rotated x y angle filename|bitmap

sprite vflip x y filename|bitmap

sprite hflip x y filename|bitmap

compiled sprite x y filename|bitmap

floodfill x y

text x y "Enclosed text"

textright x y "Enclosed text"

textcentre x y "Enclosed text"

flow text left_margin right_margin vertical_spacing "Enclosed text"

There are three escapes allowed in flowed text strings, \n to for a new line, \u to turn on underlining and \r to turn off underlining.

font font_name

Example of object descriptions

	line 100 100 200 200		# a line from 100,100 to 200,200
	rect 100 100 200 200		# a rectangle, corners 100,100 and 200,200
	rectfill 100 100 200 200	# a filled rectangle
	circle 200 200 50		# a circle, radius 50, centre 200,200
	circlefill centred 50		# a filled circle in the middle of the screen
	ellipse 200 200	50 60 		# an ellipse, radius 50 and 60, centre 200,200
	ellipsefill 200 200 50 60
	floodfill 100 100 		# fill screen, staring at 100, 100
	font char40			# use a large font
	text 100 100 "A Message"	# a left justified message at 100,100
	textcentre 100 100 "A Message"  # a centred image

	rectfill 100 100 200 200 colour red	# a filled red rectangle
	rectfill 100 100 200 200 colour 0,0,127	# a filled dark blue rectangle

	units relative
	rect -0.5 -0.5 0.5 0.5		# a square covering hals the screen
	circle centred 1.0 1.0		# a centred circle filling the entire screen

	display object 100		# an inline object
	name object "Stimulus type 1"	# record info in log file
	line 100 100 200 200
	rect 100 100 200 200
	end object

	start object "Type 2"		# start of object, with name
	offset 100,-100			# offset the image
	scale  0.5,0.5			# halve the image size
	line 100 100 200 200
	rect 100 100 200 200
	end object

	start object
	offset global 100,-100		# offset the image for all subsequent entries
	line 200 200 300 300
	rect 200 200 300 300
	end object

	colour	fg1	255,255,255		# bright while
	colour	bg1	0,0,0			# black
	colour	fg2	128,128,128		# grey
	colour	bg2	63,63,63		# dark grey

	start object "High contrast"
	speckle 100 100 20 fgcolour fg1 bgcolour bg1
	...
	end object

	start object "Low contrast"
	speckle 100 100 20 fgcolour fg2 bgcolour bg2
	...
	end object

	preload bitmap1 object
	rectfill 220 140 420 340		# render a filled rectangle
	end object

	preload bitmap2 object
	circlefill 320 480 100			# render a filled circle
	end object

	display object 100			# build an image
	sprite rotated centred 90 bitmap1	# with a rotated rectangle
	sprite 100 100 bitmap2			# and offset circle
	end object

	preload bitmap1 object
	circlefill 100 100 5			# some dots down the
	circlefill 150 200 5			# left hand side of
	circlefill 250 300 5			# the screen only
	circlefill 310 360 5
	end object

	preload bitmap2 object
	sprite centred bitmap1			# render the original image 
	sprite hflip centred bitmap1		# and mirror about vertical axis
	end object

	display object 100
	sprite rotated centred 15 bitmap2	# and put up image rotated 15 degrees
	end object

Saving images

save screen{1-n} "filename"

save background "filename"

save screen[expression] "filename%d.pcx" index

save background "filename"

save bitmap{1-n} "filename"

save bitmap[expression] "filename"

Note:- The palette used in 8 bit display modes can, in some circumstances, not be saved correctly. It is suggested that you use 16 bit or greater image modes

The example below shows how to save sequentially into files using a procedure

	file = 0
	procedure img_save(1)
	{
		save screen[$1] "image%d.pcx" file
		file = file + 1
	}

	block
		display list.obj 100
		image_save(1)
	repeat sizeof list.obj

Sound Support

By default RUNSTIM will allow you to use a dB value that is less than a calibrated value (provided other parameters match) as long as it is less than the calibration point and within 35dB. You can control turn on/off this feature using the command line -Jx or control file allow calculated dB x, where x in non-zero to enable extended ranges, or zero to allow only calibrated values.

An onset and offset ramp may be applied to sounds so that there isn't a perceived click at the start and finish. The ramp that is applied is a quarter sine wave envelope and is measured in milliseconds. A 50 millisecond onset and offset is specified as onset 50 offset 50.

The sound channel can also be specified, as left, right or both. Finally, strobe data can be specified to send data via the printer port.

tone frequency left|right|both volume duration {onset milliseconds} {offset milliseconds} {strobe data} {nowait}

Sound ramps are applied within the duration specified, and are sinusoidal.

If the keyword nowait is present, then the program will not wait for the tone to complete or the ISI interval. This allows a tone (or square, noise or click) to have it's onset at the same time as a image presentation.

square wave frequency left|right|both volume duration {onset milliseconds} {offset milliseconds} { nowait }

noise left|right|both volume duration {onset milliseconds} {offset milliseconds} {strobe data} { nowait }

click left|right|both volume duration {onset milliseconds} {offset milliseconds} {strobe data} { nowait }

play filename left|right|both volume {strobe data}

calibration age days

calibration file filename

Example sound descriptions

	tone 1000 both 80db 1000 onset 50 offset 50	# clickless 1KHz tone for 1 second
	noise 1000 both 200				# uncalibrated noise burst
	square wave 1000 left 75dB 100			# 1Hz square wave
	play tada.wav both 128				# play a sound file
	noise 1000 both 200 strobe 010			# uncalibrated noise burst with strobe data

	sound threshold 40				# the sound threshold is 40dB
	tone 1000 both +40dB				# output 1kHz tone at 80dB (40dB threshold + 40dB)

Preloading Sounds

The syntax is identical to the previous section, with preload sound before each statement :-

	preload sound1 tone 1000 both 80db 1000 onset 50 offset 50
	preload sound2 noise [duration] both [volume]dB 

	sound 1
	sound 2

You can also use the sound statement without a preload, but the time taken will be unpredictable (variable amounts of data has to be calculated).

	sound noise [duration] both [volume]dB

	tone 1000 both 80db 1000 onset 50 offset 50

	instead of

	sound tone 1000 both 80db 1000 onset 50 offset 50

Recording Sounds

recorder frequency integer value

recorder input [mic | line]

recorder bits [8 | 16]

recorder open mode [ask | append | replace]

Calibration Menu

Menu Item	Description
Sound Levels	Calibrate sound levels
Video Luminance	Calibrate pseudo colours for luminance control
Video Demos	Test screen gamma, grey scales and refresh rate

Note:-

Menu Item	Description
New	Create a new entry
Recal.	Run the calibration sequence on the selected colour name
Delete	Delete the selected entry
Update	Update the timestamp for the selected entry
Save	Save any changed calibration settings

When a new entry is made, the screen resolution, pixel depth and refresh rate is set, along with a name (equivalent to a named colour). The screen is then changed to the selected resolution, and then divided is to 16 regions (4 x 4 matrix). For each region, you can set the white level, or individually set each colour. When complete, the data is interpolated to generate a calibrated screen associated with the named colour. Any screen object using the named colour, will use data from the calibrated bitmap

Please note that it is futile to use screen pixel depths of less that 24 bits, since this drastically limits the available range of intensities with which to apply corrections

no progress

no ready

Outputting data to LPT port

It is possible to hold data specified by a strobe command longer than the stimulus time, but using the following global command :-

holdtime time_in_milliseconds

Note

Interprocess communication

print "format specification" { optional expressions }

%d	Decimal integer
%o	Octal integer
%x	Hexadecimal integer
%u	Unsigned decimal integer
%f	Floating point number
%g	Floating point number
%v	Automatic integer or floating point
%c	Output integer as character
%k	Special. Output curent keyboard buffer
%%	Output %
\t	Expand as a tab
\b	Output as backspace
\n	Output a new line

A number can be used to specify the width of the resulting output. A leading 0 will zero pad the number, while a leading - will left justify the number. eg :-

print "Decimal %d, octal 0%0, hexadecimal 0x%x\n" x1, x2, x3
print "Floating point %6.3f\n" value

clock rate milliseconds_per_tick

pause key value

quit key value

strobe data_value

defer images

lock image image_file

preallocate

log milliseconds

System Lockups

Timing Accuracy

The inter-stimulus interval is timed using the system clock, which is normally set to run at 1ms intervals. During the ISI, the program preloads images and outputs data that has been collected. This can result in slight variations in the ISI timing if the ISI is set to a small value. The times recorded in the data file will be accurate.

display, flash, movie, noise, tone, square, wave, click, play and sound.

The special case of sleep after a display does not invoke an ISI. The commands sleep and wait refresh will invoke a different delay from the current ISI.

All background commands generate a one frame delay to allow the change to happen.

Movies

8 bit mode

Due to a bug in the graphics package, 15/16/24/32 bit image files cannot be converted into 8 bit images. Use an external program to convert the files before they are used.

Memory

Preload's

A complicated example of using low level preloads and displays is given below:-

lock image fixation.pcx					# keep this image

preload screen1 fixation.pcx 100			# keep in screen 1

block
	preload screen2 images1.lst once_only 100	# random image
	preload screen3 background 100			# background
	preload screen4 images2.lst once_only 100	# random image

	display screen1					# display fixation
	sleep 0						# no ISI
	display screen2					# random image
	sleep 0	
	display screen3					# this is a background. Use display
							# to maintain accurate timing
	sleep 0	
	display screen4					# random image
repeat sizeof images1.lst

Filenames

Objects

You cannot apply offset commands to objects using the display or flash directives. You can apply fixed offsets as part of the object description.

Command line options

Debugging Commands

calibrate

debug

statistics

vesa palette

no merge

vsync clock

label

nowarn

no object dumps

nscreens n

Projection modes

mirror images

invert images

mirror objects

invert images

mirror and invert may be selected at the same time, and the projection code will optimise how the images are manipulated.

Note

Built in help

runstim -h

• Version number of the software
• All command line options
• All control file commands
• A list of object types
• A list of builtin colours
• A list of built in fonts

MDSOS

CRASHDMP.EXE	A program to save data if RUNSTIM crashes
FONTLIB.DAT	Additional text fonts
FONTLIB.TXT	A list of the contents of FONTLIB.DAT
MANUAL.HTM	The manual for RUNSTIM
PSN.EXE	A program to generate a machine identification number
RUNSTIM.EXE	The program itself

To run the program, you need a valid license file generated at the University of Sydney, Department of Psychology.

You will also need to let MSDOS and Windows where the program is. Edit both C:\Autoexec.dos and C:\Autoexec.bat so the the PATH command contains C:\RUNSTIM in addition to the other entries

mkdir /usr/local/runstim
cd /usr/local/runstim
tar zx location_of_distribution file
ln -s  /usr/local/runstim/runstim /usr/local/bin

Getting the video settings correct

Other Files

There are several files used by RUNSTIM that are normally stored in C:\RUNSTIM. They are :-

File Name	Description
license.dat	License details, termination dates and options
sound.cal	Optional sound calibration file
video.cal	Optional video calibration files
fontlib.dat	Extended font library for text

Example control file

#
#	test sequence file
#

xsize	640
ysize	480
vrate	100
depth	8
vesa
local
randomise			# (1)
pause key p			# (7)

background sample small.lst	# (6)

isi     1.0			# (5)

datafile prompt			# (9)

block
mouse enable isi		# (8)
display small.lst once_only 100
#           (2)      (4)    (3)

repeat sizeof small.lst

Example Animation control file

• A table of positions is calculated to specify the screen positions for the dot at it moves.
• Two screens are used. While one is being displayed, the other is changed for the next dot position
• To speed up screen updates, the 'no clear' object mode is used. Instead of clearing the whole background for the next screen, the previous dot is erased, and a new one drawn. Note that a compiled sprites are used to set and clear dots, rather than 'circlefill'. If you have a fast processor, the latter would suffice.
• Expressions that are constant are calculated outside the loop.

#
#	test moving object using sinewave increment steps
#

xsize 640
ysize 480
vrate 75

path tests

initial isi 0
background black

#
#	set initial screens black
#

preload screen1 object nowait
background colour black
end object

preload screen2 object nowait
background colour black
end object

#
#	set initial parameters
#

steps = 201		# steps per scan, should be odd
width = 400		# width along screen

#
#	calculate constants
#

xc = xsize / 2.0	# centre of screen
hw = width / 2.0	# half width
hs = steps / 2.0	# half step 
sc = (pi / 2.0) / hs	# increment for sine function
y = ysize / 2		# middle of screen

#
#	calculate sine table for x position
#

array float xpos[steps]	# array to hold steps

for x = 0; x < steps; x++
	xpos[x] = xc + hw * sin(sc * (x - hs))
next x

#
#	set initial array position 'x' and screen index
#

x = 1
index = 1

#
#	fast lookup table for index
#
array int idx[3]

idx[1] = 2
idx[2] = 1

#	render initial dot

preload screen1 object nowait
	sprite [xpos[1]] [y] dot.pcx
end object

#
#	continuous loop
#
block

#
#	moving left to right
#
	block
		display screen[index]
#
#	generate new index
#
		nindex = idx[index]
#
#	erase previous dot (two points ago) and render new one
#
		preload screen[nindex] object nowait
			no clear
			compiled sprite [xpos[x - 1]] [y] notdot.pcx
			compiled sprite [xpos[x + 1]] [y] dot.pcx
		end object

		index = nindex
#
#	loop for width
#
	while ++x < steps - 1
#
#	moving right to left
#	
	block
		display screen[index]

		nindex = idx[index]

		preload screen[nindex] object nowait
			no clear
			sprite [xpos[x + 1]] [y] notdot.pcx
			sprite [xpos[x - 1]] [y] dot.pcx
		end object

		index = nindex
	while --x > 1

repeat for ever