Experimental functions
[Experimental]

Collaboration diagram for Experimental functions:

Miscellaneous auxiliary functions
string	I2S (int input)
	convert integer to string
string	F2S (float input)
	convert float to string
void	Error (string report)
	prints an error report into the terminal window and aborts the experiment
int	WinWidth ()
	returns window's width
int	WinHeight ()
	returns window's height
int	WinFramerate ()
	returns window's framerate, you better check that it returns correct values before using it!
int	Iran (int max)
	generates an integer random number [0 max]
double	Fran (double max)
	generates a double random number (0 max)
int	Iran1 (int max)
	a more advanced random number function (use if the random number should be random at all bits)
double	Fran1 (double max)
	a more advanced random number function
int	BinRan (int n_trials, double prob_success)
	returns a binomially distributed random variable, i.e. the number of successes in n_trials trials with the probability of success prob_success in each trial
int	PoissonRan (double poisson_rate)
	returns a Poisson distributed random variable for the Poisson process with rate poisson_rate
double	NormalRan (double mean, double stdv)
	returns a normally distributed random variable with mean mean and standard deviation stdv
double	GammaRan (int n_events, double poisson_rate)
	returns a gamma distributed random variable, i.e the waiting time for n_events in the Poisson process with rate poisson_rate
void	ShuffleArray (int i0, int n, int *arr)
	shuffle the next n elements starting from i0
void	ShuffleArray (int i0, int n, double *arr)
	shuffle the next n elements starting from i0
Output functions
void	SaveResults (string filename)
	save experimental results into a file defined by the filename parameter
void	SaveResults ()
	the same with the default filename (experiment-name_YYMMDD-HHMM.dat)
Functions controlling the main window
void	SetWindow (int x, int y, int width, int height, int argc, char **argv, double bgrR, double bgrG, double bgrB, double gamma=1, int video_fl=0, double src_alpha=1)
	open the main experimental window of the given size at the specified location
void	SetWindow (int x, int y, int width, int height, int argc, char **argv, double bgr=0, double gamma=1, int viedo_fl=0, double src_alpha=1)
	the same as above for a gray-scale background defined by the luminance parameter bgr
void	SetWindow (int argc, char **argv, double bgrR, double bgrG, double bgrB, double gamma=1, int video_fl=0, double src_alpha=1)
	open the main experimental window in the fullscreen mode
void	SetWindow (int argc, char **argv, double bgr=0, double gamma=1, int video_fl=0, double src_alpha=1)
	the same as above for for a gray-scale background defined by the luminance parameter bgr
void	MaskRectangle (double x, double y, double width, double height)
	places a rectangular occluder mask over the window
void	MaskCircle (double x, double y, double radius, int flag=OUTSIDE)
	places a circlular occluder mask over the window
void	MaskShape (double *x, double *y, unsigned int number_of_vertices, int flag=OUTSIDE)
	places an arbitraly shaped occluder mask over the window
void	SetObjects (void prepare())
	prepare user-defined pixmaps
void	Clear (double r, double g, double b)
	clear screen with color (r, g, b)
void	Clear (double l)
	clear screen with gray-scale color (l, l, l)
void	Clear ()
	clear with the background color (BgrR, BgrG, BgrB), or Bgr
void	ClearBoth ()
	clear both buffers with the background color
void	SwapBuffers ()
	swap back and front buffers
void	PostRedisplay ()
	demand to run display function in the next iteration of the main event loop
void	Show ()
	show the stimulus (swap the front and back buffers)
void	Show (double time)
	show for the specified time (in milliseconds)
void	ShowTestTiming (double time)
	test show timing (time in milliseconds)
void	ShowClear (double time)
	show for the specified time and clear screen afterwards
void	LineWidth (double width)
	set the line width in pixels for line objects
Functions controlling the experimental flow
void	Run (void display(), int exp_flags=0, int adapt=ADAPT_SETS, int adapt_fl=ADAPT_LOG, int n_signal=31, double signal_min=0.005, double signal_max=1., int n_thr=31, double thr_min=0.005, double thr_max=1., int n_slope=1, double slope_min=1.5, double slope_max=1.5, double miss_rate=0.01)
	run the experiment
void	Proceed ()
	wait for a user response
int	Confirm ()
	check that the next trial was initialized with a middle mouse button press
void	SetTrials (int n_sets, int n_configs, int n_trials, int shuffle_flag=RANDOM)
	shuffle the array of experimental trials
void	Beep (void)
	sound system alert once
void	MediumBeep (void)
	sound system alert twice
void	LongBeep (void)
	sound system alert three times in a row
void	Sleep (double time)
	sleep in milliseconds
int	GetTime ()
	time elapsed from the beginning of the experiment (milliseconds)
void	StartTimer (void)
	start the experiment timer
int	StopTimer (void)
	stop the experiment timer, return the elapsed time (milliseconds).
void	StartMotion (int)
	start stimulus motion
void	StopMotion (int)
	stop stimulus motion

---

Function Documentation

int Confirm

(

)

Use this function to allow observers initiate the next trial by middle mouse click, e.g. in the display function:

  if( Confirm() == CONFIRM_OK )
  {
     display the stimulus...
  }

void MaskCircle	(	double	x,
		double	y,
		double	radius,
		int	flag = OUTSIDE
	)

Places a circular occluder mask over the window using the OpenGL stencil test. Stencil buffering has to be supported by the videocard. This function should be called just once from the SetObjects() function.

Parameters:

	x	x-coordinate of the circle's center
	y	y-coordinate of the circle's center
	radius	the circle's radius
	occlusion	mask's visibility scheme: if flag=OUTSIDE (default) the inside of the circle is transparent, the outside is opaque, if flag=INSIDE then the outside is transparent, the inside is opaque

void MaskRectangle	(	double	x,
		double	y,
		double	width,
		double	height
	)

Places a rectangular occluder mask over the window using the OpenGL scissor test. This function might work faster than the other masking functions based on the OpenGL stencil test. This function should be called just once from the SetObjects() function.

Parameters:

	x	x-coordinate of the rectangle's center
	y	y-coordinate of the rectangle's center
	width	rectangle's width
	height	rectangle's height n the outside is transparent, the inside is opaque

void MaskShape	(	double *	x,
		double *	y,
		unsigned int	number_of_vertices,
		int	flag = OUTSIDE
	)

Places an arbitraly shaped occluder mask over the window using the OpenGL stencil test. The shape is defined by an array of vertices, which are connected by straight line segments. The last vertex is connected to the first vertex to form a closed shape. This function should be called just once from the SetObjects() function.

Parameters:

	x	an array of x-coordinates of the shape's vertices
	y	an array of y-coordinates of the shape's vertices
	number_of_vertices	the number of vertices in the polygon
	mask	mask's visibility scheme: if OUTSIDE (default) the inside of the shape is transparent, the outside is opaque, if flag=INSIDE then the outside is transparent, the inside is opaque

void Run	(	void	display(),
		int	exp_flags = 0,
		int	adapt = ADAPT_SETS,
		int	adapt_fl = ADAPT_LOG,
		int	n_signal = 31,
		double	signal_min = 0.005,
		double	signal_max = 1.,
		int	n_thr = 31,
		double	thr_min = 0.005,
		double	thr_max = 1.,
		int	n_slope = 1,
		double	slope_min = 1.5,
		double	slope_max = 1.5,
		double	miss_rate = 0.01
	)

Run the experiment according to the following parameters:

Parameters:

	display()	the name of the display function
	exp_flags	various Experimental flags linked together by the '|' symbol
	adapt	what thresholds will be adaptively measured ADAPT_SETS, ADAPT_CONFIGS, ADAPT_SETS_CONFIGS
	adapt_fl	ADAPT_LIN or ADAPT_LOG (default) adaptation scheme
	n_signal	number of steps for signal sampling
	signal_min	minimal signal
	signal_max	maximal signal
	n_thr	number of bins for the threshold probability distribution
	thr_min	minimal threshold in the pdf
	thr_max	maximal threshold in the pdf
	n_slope	number of bins for the slope probability distribution
	slope_min	minimal slope
	slope_max	maximal slope
	miss_rate	a parameter that defines the observer's error rate

void SetObjects

(

void

prepare()

)

This function should be called only after the SetTrials() and SetWindow() functions were called. It allocates memory (either ordinary or video) and fills it with object pixmaps for the objects in the prepare() function.

Parameters:

prepare

The name of the function which calls MakeObject() functions to create various objects. The prepare function should not have any parameters.

void SetTrials	(	int	n_sets,
		int	n_configs,
		int	n_trials,
		int	shuffle_flag = RANDOM
	)

This function allocates various experimental arrays and does all the necessary trial shuffling as specified by the shuffle_flag. An experiment is organized at the three levels:

• Sets
• Configurations (the same number for each set)
• Trials (the same number for each configuration)

Thus, an experiment has Sets x Configurations x Trials exponential design, the total number of trials given by n_sets x n_configs x n_trials.

Parameters:

	n_sets	number of sets
	n_configs	number of configurations in each set
	n_trials	number of trials in each configuration
	shuffle_flag	one of the Trials setting flags, e.g. RANDOM, ORDERED, ...

void SetWindow	(	int	x,
		int	y,
		int	width,
		int	height,
		int	argc,
		char **	argv,
		double	bgrR,
		double	bgrG,
		double	bgrB,
		double	gamma = 1,
		int	video_fl = 0,
		double	src_alpha = 1
	)

Set position, dimensions, and properties of the main experimental window.

Parameters:

	x	x-coordinate of the upper left corner
	y	y-coordinate of the upper left corner
	width	window width
	height	window height
	argc	counter for the main() function arguments
	argv	this parameter is passed by the main() function. It determines the name of the experiment and other parameters
	bgrR	background Red component
	bgrG	background Green component
	bgrB	background Blue component
	gamma	gamma correction coefficient for the screen
	video_fl	various Video settings flags linked together by the '|' symbol
	src_alpha	transparency of the object being overlayed. This parameter is only effective when BLEND_ADD or BLEND_TRANSPARENT video flags are chosen.