Psylib references

   arg1: int bitmap (if 0, no bitmap will be shown)

   Use: This function should be called at the end of your program.  It
   cleans up used resources.  It requires a press on the button 'q' of
   the PC keyboard to end.  This is useful, because you don't want
   that the program returns to the shell before the subject leaves the
   terminal.  If argument 1 equals 0 then no bitmaps will be shown and
   not button press will be required.  A number > 0 will show the
   associated bitmaps number (given this is loaded, see
   psy_load_bitmap).  Currently, the return value is not used and can
   be ignored.  

   arg1: screen width in pixels.
   arg2: screen width in height.
   arg3: rendering mode. PSY_VIDEO_STANDARD,PSY_VIDEO_DOUBLEBUFFER,PSY_VIDEO_OPENGL
   arg4: fullscreen (1=fullscreen,0=not fullscreen). This ONLY used if
         the rights are not "root".

   Use: This function initializes all important resources for running
   an experiment.  It 'opens' a video screen with the resolution given
   in the arguments (width x height) and initializes the sound card.
   Make sure your video card/Xwindows supports the choosen resolution.
   There are different rendering modes. In principle, they all do the
   same, but they take advantage from hardware accceration in quite
   different ways.

   psy_screen( 800 , 600 , PSY_VIDEO_STANDARD );

   Use: Show the PsyToolkit splash screen and wait for space bar press

   Initialises the audio system. This needs to be called for the audio
   to work. It has been separated from the psy_screen function,
   because this way you can just code without using the audio
   system. Under certain conditions, this might be needed.

   arg1: screen (projected area) width in millimeters
   arg2: screen (projected area) height in millimeters
   arg3: eye-screen distance in millimeters
   arg4: eye-center vertical offset

   Use: This function initializes parameters necessary for working
   with polar coordinates.

   psy_init_polar( 1000 , 820 , 500 );

   Use: All graphics functions will use polar coordinates

   psy_use_polar();

   Use: All graphics functions will use cartesian coordinates

   psy_use_cartesian();

   arg1: char filename[]

   Returns: An integer which is the number associated with the sound.

   Use: Load a soundfile into memory.  Use the return value in
   psy_play to play the sound.  You can use this function if you have
   just one sound in your program.  If you need more sounds, it is
   more convenient to read soundfiles using psy_load_sounds.

   arg1: char filename[]

   Use: Load soundfiles into memory.  The filename refers to a text
   file which has on each line a number (starting with 1 and strictly
   increasing with one at the time!) and a soundfile name (not in
   quotes).  You play the files with using the associated number in
   the function psy_play.

   TIP: Instead of using numbers, you can use strings.  Create a file,
   for example sound_files.txt and put on each line a decription name
   of the sound and the soundfile.  During compilation call
   "psy_compile_sounds_define sound_files.txt" and just call
   psy_load_sound(SOUNDFILE); to load your sounds.

   arg1: char filename[]

   Returns: An integer which is the number associated with the bitmap.
   You do not really to know these numbers.  But interestingly, the
   first bitmap is 1 (and not 0, as might have been the case in the c
   world).

   Use: Load a bitmap-file into memory.  Use the return value in
   psy_show_bitmap to show it.  You can use this function if you have
   just one bitmap in your program.  If you need more bitmaps, it is
   more convenient to read bitmapfiles using psy_load_bitmaps.

   arg1: char filename[]

   Use: Load bitmapfiles into memory.  The filename refers to a text
   file which has on each line a number (starting with 1 and strictly
   increasing with one at the time!) and a bitmapfile name (not in
   quotes).  You show the bitmaps with using the associated number in
   the function psy_show_bitmap.

   TIP: Instead of using numbers, you can use strings.  Create a file,
   for example bitmap_files.txt and put on each line a decription name
   of the bitmap and the bitmapfile.  During compilation call
   "psy_compile_bitmaps_define bitmap_files.txt" and just call
   psy_load_bitmap(BITMAPFILE); to load your bitmaps.

   arg1: sound

   Use: Play a sound. The number is explained in psy_load_sound(s).

   arg1: sound

   Use: stop sounds

   Use: Clear the entire screen.

   Use: Clear the entire screen in rendering mode doublebuffer

   Use: A call to this function runs the experiment in test mode.  All
   it does is to run the experiment in a window instead of in full
   screen.

   arg1: bitmap
   arg2: SDL key code

   Use: Show a display and wait until the space bar is pressed.  The
   bitmap disappears as soon as the key is being pressed.  This is
   useful for showing a "pause" signal or an explanation of the
   upcoming task.  If key equals 0, it uses the keycode of the space
   key.

   returns: the time to wait until the next vertical retrace.

   Use: Computer screens take about 15 ms to "draw" all the pixels on
   the screen.  This time depends on the frequency of your monitor
   (1000/Hz).  If you don't check the vertical retrace before you
   present a stimulus, you don't know exactly when the stimulus
   appears on the screen.  When you call this function, there is a
   constant delay across trials between the time of the function call
   and the stimulus appearance.  Most stimulus presentation programs
   use a similar function.  If timing is not critical, you can leave
   this out, although it never hurts to use it.

   The vsync signal is not available on all computers, and if it is
   available, it can only be accessed by user root. Therefore,
   internally, psytoolkit can ignore this call. It will either map
   this function on a real wait function, or it will map it on an
   empty placeholder. This mapping occurs during psy_screen.
   (This is a bit similar to using psy_nap.)

   The global variable psy_vsync_mode determines how psy_wait_vsync is
   set. It only really does something if this value is set to one and
   if the programme has root rights.

   Tells the library not the access the computers vsync
   variables. This is necessary on computers that do not have these,
   or cannot give user access to it.

   This must be called before you use psy_screen, otherwise it won't
   have effect.

   arg1: filename
   arg2: size

   returns: number of font which needs to be used in the call
   psy_show_text_rgb.

   Use: If you want to use true type fonts, you need to load a true
   type font from disk and specify the size you will use for text
   display.  You cannot change font size in the text display function
   call.

   arg1: int number
   arg2: int x
   arg3: int y
   arg4: int update

   return: an index which can be used with psy_clear_rectangle to
   remove the bitmap from the screen.

   Use: Shows a bitmap on the screen.  The number is explained in
   psy_load_bitmaps.  The x,y position is where the top left corner of
   the bitmap is.  Thus, if you want to center a bitmap you need to
   know how large the bitmap is and then use those value to calculate
   where the center will be.  Use psy_show_centered_bitmap to this.
   The update value should be 0 or 1.  If it is 1 it will be drawn
   immedeately, if it is 0, it will be drawn the next time
   psy_update_rectangles() is being called.

   arg1: int number
   arg2: int x
   arg3: int y
   arg4: int update

   Use: Shows a bitmap on the screen.  The number is explained in
   psy_load_bitmaps.  The x,y position is where the center of the
   bitmap is.  The update value should be 0 or 1.  If it is 1 it will
   be drawn immedeately, if it is 0, it will be drawn the next time
   psy_update_rectangles() is being called.

   arg1: int number
   arg2: int x
   arg3: int y
   arg4: double zoom
   arg5: double angle
   arg6: int update

   return: an index which can be used with psy_clear_rectangle to
   remove the bitmap from the screen.

   Use: Shows a bitmap on the screen, with optional scaling and
   rotation.  The number is explained in psy_load_bitmaps.  The x,y
   position is where the center of the bitmap is.  The update value
   should be 0 or 1.  If it is 1 it will be drawn immedeately, if it
   is 0, it will be drawn the next time psy_update_rectangles() is
   being called.  The zoom is the zoom fraction (e.g., 0.5 halves the
   bitmap, 2.0 doubles it), and the angle is in degrees.

   arg1: int x
   arg2: int y
   arg3: int w
   arg4: int h
   arg5: int r
   arg6: int g
   arg7: int b
   arg8: int update

   return: an index which can be used with psy_clear_rectangle to
   remove the rectangle from the screen.

   Use: Shows a rectangle on the screen. rgb color are set with r, g,
   and b, values should be between 0 and 255.  The x,y position is
   where the top left corner of the rectangle is, w and h are widht
   and height.  The update value should be 0 or 1.  If it is 1 it will
   be drawn immedeately, if it is 0, it will be drawn the next time
   psy_update_rectangles() is being called.

   See psy_show_rectangle_rgb.
   The only difference is that x,y is the center of the rectangle.

   arg1: int fontno
   arg2: int x
   arg3: int y
   arg4: int centerx
   arg5: int centery
   arg6: int r
   arg7: int g
   arg8: int b
   arg9: char *text
   arg10: int update

   return: an index which can be used with psy_clear_rectangle to
   remove the text from the screen.

   Use: Shows a text (*text) on a rectangle on the screen.  rgb color
   are set with r, g, and b, values should be between 0 and 255.  The
   x,y position is where the top left corner of the rectangle is,
   widht and height depend on the lenght of text and are automatically
   set. (centerx and centery can be set to -1 or PSY_CENTRAL, which
   means that the x and/or y dimension, the text will be centered on
   the x,y; other values of centerx and centery will be ignored).  The
   update value should be 0 or 1.  If it is 1 it will be drawn
   immedeately, if it is 0, it will be drawn the next time
   psy_update_rectangles() is being called.

   arg1: sound

   Use: Play a sound. The number is explained in psy_load_sound(s).

   Use: Clear the entire screen.

   Use: A call to this function runs the experiment in test mode.  All
   it does is to run the experiment in a window instead of in full
   screen.

   arg1: bitmap
   arg2: SDL key code

   Use: Show a display and wait until the space bar is pressed.  The
   bitmap disappears as soon as the key is being pressed.  This is
   useful for showing a "pause" signal or an explanation of the
   upcoming task.  If key equals 0, it uses the keycode of the space
   key.

   arg1: filename
   arg2: size

   returns: number of font which needs to be used in the call
   psy_show_text_rgb.

   Use: If you want to use true type fonts, you need to load a true
   type font from disk and specify the size you will use for text
   display.  You cannot change font size in the text display function
   call.

   arg1: int number
   arg2: int x
   arg3: int y
   arg4: int update

   return: an index which can be used with psy_clear_rectangle to
   remove the bitmap from the screen.

   Use: Shows a bitmap on the screen.  The number is explained in
   psy_load_bitmaps.  The x,y position is where the top left corner of
   the bitmap is.  Thus, if you want to center a bitmap you need to
   know how large the bitmap is and then use those value to calculate
   where the center will be.  Use psy_show_centered_bitmap to this.
   The update value should be 0 or 1.  If it is 1 it will be drawn
   immedeately, if it is 0, it will be drawn the next time
   psy_update_rectangles() is being called.

   arg1: int number
   arg2: int x
   arg3: int y
   arg4: int update

   Use: Shows a bitmap on the screen.  The number is explained in
   psy_load_bitmaps.  The x,y position is where the center of the
   bitmap is.  The update value should be 0 or 1.  If it is 1 it will
   be drawn immedeately, if it is 0, it will be drawn the next time
   psy_update_rectangles() is being called.

   arg1: int number
   arg2: int x
   arg3: int y
   arg4: double zoom
   arg5: double angle
   arg6: int update

   return: an index which can be used with psy_clear_rectangle to
   remove the bitmap from the screen.

   Use: Shows a bitmap on the screen, with optional scaling and
   rotation.  The number is explained in psy_load_bitmaps.  The x,y
   position is where the center of the bitmap is.  The update value
   should be 0 or 1.  If it is 1 it will be drawn immedeately, if it
   is 0, it will be drawn the next time psy_update_rectangles() is
   being called.  The zoom is the zoom fraction (e.g., 0.5 halves the
   bitmap, 2.0 doubles it), and the angle is in degrees.

   arg1: int x
   arg2: int y
   arg3: int w
   arg4: int h
   arg5: int r
   arg6: int g
   arg7: int b
   arg8: int update

   return: an index which can be used with psy_clear_rectangle to
   remove the rectangle from the screen.

   Use: Shows a rectangle on the screen. rgb color are set with r, g,
   and b, values should be between 0 and 255.  The x,y position is
   where the top left corner of the rectangle is, w and h are widht
   and height.  The update value should be 0 or 1.  If it is 1 it will
   be drawn immedeately, if it is 0, it will be drawn the next time
   psy_update_rectangles() is being called.

   arg1: int fontno
   arg2: int x
   arg3: int y
   arg4: int centerx
   arg5: int centery
   arg6: int r
   arg7: int g
   arg8: int b
   arg9: char *text
   arg10: int update

   return: an index which can be used with psy_clear_rectangle to
   remove the text from the screen.

   Use: Shows a text (*text) on a rectangle on the screen.  rgb color
   are set with r, g, and b, values should be between 0 and 255.  The
   x,y position is where the top left corner of the rectangle is,
   widht and height depend on the lenght of text and are automatically
   set. (centerx and centery can be set to -1 or PSY_CENTRAL, which
   means that the x and/or y dimension, the text will be centered on
   the x,y; other values of centerx and centery will be ignored).  The
   update value should be 0 or 1.  If it is 1 it will be drawn
   immedeately, if it is 0, it will be drawn the next time
   psy_update_rectangles() is being called.

   arg1: delay time in ms

   returns: nothing

   Use: when you want the computer to wait

   Note: This function runs a fast loop continuously checking the
   time.  Initially, I used SDL_Delay for this delay, but that is
   potentially less precise, due to various scheduling issues.

   arg1: lowest possible value
   arg2: highest possible value

   returns: integer between the lowest and highest possible values

   Use: gives you a random number

   arg1: lowest possible value
   arg2: highest possible value
   arg3: step size

   returns: integer between the lowest and highest possible values, divisale by the step size

   Use: gives you a random number.

   int x = psy_random_by(10,20,2); // returns an even number between 10 and 20

   arg1: surface, this is the variable screen
   arg2: x coordinate of top left corner of rectangle
   arg3: y coordinate of top left corner of rectangle
   arg4: width of rectagle
   arg5: height of rectangle

   Use: Drawing commands do not always really present something on the
   screen; you need to update it.

   arg1: timer1
   arg2: timer2

   returns: difference in ms

   Use: The timers in psylib are variable containing a timestamp.  The
   timestamp gets set to the current time with psy_update_timer.  This
   function returns the difference between two timers.

   arg1: timer

   Use: The timers in psylib are variable containing a timestamp.
   This function "updates" the value of the time stamp to the current
   time.

   arg1: int *keys
   arg2: int n
   arg3: int correct
   arg4: maxwait

   returns: struct psy_key

   Use: If you want that the subject presses one key out of one of
   more choices.  The array keys contains the keys, which are SDL
   defined keys.  Specify the size of the array with n, and say which
   array entry is the one that should be pressed by the sbject.  After
   maxwait the function returns and sets psy_key.status to
   PSY_KEY_STATUS_TIMEOUT.  If the correct key is being pressed, the
   status variable is set to PSY_KEY_STATUS_CORRECT, and to
   PSY_KEY_STATUS_WRONG when another key from the array is being
   pressed.  Set the maximum decision time with maxwait
   (milliseconds).

   int mykeys[]={SDLK_LSHIFT,SDLK_RSHIFT,SDLK_x};
   psy_key the_pressed_key;
   psy_keyboard( mykeys, 3, 0, 2000 );
   if ( the_pressed_key.status == PSY_KEY_STATUS_CORRECT )
     print("Great!");
   if ( the_pressed_key.status == PSY_KEY_STATUS_WRONG )
     print("BAD!");
   if ( the_pressed_key.status == PSY_KEY_STATUS_TIMEOUT )
     print("So slow!");
   printf("Your response time was: %d ms\n", the_pressed_key.time);

   arg1: int *keys
   arg2: int n
   arg3: int test (if PSY_UNDEFINED, do not test)

   returns: key_status (.status will not be set with PSY_UNDEFINED)

   Use: Just check whether one of the keys has been pressed.  Unlike
   psy_key, this function immedeately returns.  The return value is
   key_status.  The key points at the index of key, or is
   PSY_UNDEFINED if no key was pressed.

   This function is useful in situations where you do *not* have a
   more standard experimental design in which a stimulus should be
   followed by a specific response.  For example, in a synchronous
   tapping experiment, a participant might press a button both BEFORE
   and after a stimulus onset.  In such a situation, waiting for a
   response using the psy_key function is not useful.

   Use: Draws all the rectangles for which you had set the update
   variable to 0.  Internally, functions like psy_show_bitmap save the
   rectangle coordinates and when this function gets called, all those
   rectangles are being updated.

   arg1: int rindex
   arg2: int update

   Use: Clear the bitmap, text, or the rectangle numbered rindex (use
   the return value of psy_show_bitmap, .  If update is 1, the clearning
   will be done immedeately, if zero, it will be done during the
   following call psy_update_rectangles().

   If rindex has a negative value, the reference works as follows: -1
   is last presented stimulus, -2 secondlast, etc.

   arg1: float *chances
   arg2: int n

   returns: int

   Use: Picks a number between (and including) 0 and n-1.  The chance
   of picking one of these values depend on the chance values.  For
   example, if chances[0]=0.5, there is a 0.5 chance of returning 0.
   The function assumes that the sum of chances = 1.0.

   float mychances[]={ 0.1 , 0.5 , 0.4 };
   changevalue = psy_random_weigthed( mychances , 3 );

   arg1: number of numbers to choose from
   ... : numbers to choose from

   returns: int (one of the values of ...)

   Use: Sometimes is it nice to choose a number at random from a range
   of numbers.

   mytime = psy_random_from( 5 , 10, 30, 100, 500 , 10000) ;

   arg1: int key

   Use: Wait until one particular key is pressed.  If key is 0 is
   means the space bar.  This key is good for use in blocks, it is not
   really meant for waiting for keys for critical timing (see
   psy_keyboard for that, among others).

   psy_wait_for_unique_key(0);

   arg1: *char hostname or ip address
   arg2: portnumber (note that EGI default is 55513)

   Use: Initialize Ethernet connection with the EGI NetStation
   system. This initialization sets the connection, begins recording,
   and also synchronized the time with NetStation.

   psy_init_egi( "10.0.0.42" , 55513 );
   psy_init_egi( "myhost.com" , 55514 );

   arg1: *char code (maximally 4 characters)
   arg2: *char label
   arg3: long duration

   Use: send label with NOW as timestamp, plus duration (ms)

   psy_send_egi_now ( "STIM" , "red square", 100 );

   Use: At end of program, closes the file associated with the EGI
   communication.

   psy_close_egi();

   Use: For internal use only.  Easy way to set up Ethernet
   connection.

   psy_socket_connect( "10.0.0.42", 55513);
   psy_socket_connect( "myhost.org", 55513);

   Returns: Integer with time in ms since start timer was started
   (which was when the screen was setup).

   msec = psy_time_since_start();

   Makes computer wait for 0.49 ms.

   Use: This call needs to be made in loops that wait for some event.
   For example, when you wait for a keyboard event, you want to make
   this call, otherwise the computer does nothing else than looping,
   and actually never getting any keyboard event from the X windows
   keyboard routines.

   psy_nap();

   while( is_time() < 1000 )
   {
     see_wether_keyboard_was_pressed();
     psy_nap();
   }

   Arg1: 1=visible, 0=invisible

   Use: Set mouse cursor visibility.

   Gets the mouse button (l,m,r) and puts it in the key field of the key_status.
   Gets the mouse position and puts it in the mouse_xy fileds of the key_status.

   Use: Moves mouse to a certain x,y position.  If centerzero is used,
   x=0,y=0 is center of screen.  Note: This will make mouse
   automatically visible.

   Arg1: x position (relative to coordinate system being used!)
   Arg2: y position (relative to coordinate system being used!)

   Use: Wait for input from the mouse device.  The code waits until
   user clicks the mouse button.

   Returns: Key status. Status is correct if the correct mouse button
   in the correct location was pressed.

   arg1: which mousebutton needs to be clicked? 1, 2, or 3, for left, middle, right
   arg2: which rectangle (corresponds to bitmap number
   arg3: maximum wait time in milliseconds.

   Use: Wait for input from the mouse device.  The code waits until
   user clicks the mouse button. If the clicked bitmap is not between
   first and last, nothing will be done.

   Returns: Key status.  Status is correct if the correct mouse button
   in the correct location was pressed.

   arg1: which mousebutton needs to be clicked? 1, 2, or 3, for left, middle, right
   arg2: which rectangle (corresponds to bitmap number
   arg3: maximum wait time in milliseconds.
   arg4: first of bitmap range
   arg5: last of bitmap range

   Use: Wait for the subject to move the mouse over a spefied rectangle

   arg1: The rectangle number (as elsewhere)
   arg2: The maximum wait time in ms

   arg1: searchdirection
   arg2: first bitmap to consider (or -1 if you want to include the first bitmap)
   arg3: last bitmap to consider (or -1 if you want to include the last bitmap)
   arg3: x position
   arg4: y position

   Use: Find which bitmap is located under a certain x,y position.
   The x,y position is the screen position.  The x,y position is
   independent from the coordinate system and screen offset you may
   use.

   Per default, with searchdirection = 0, first = -1, last = -1 this
   function will compare the x,y position with the locations of all
   bitmaps and give the number of the bitmap that matches the x,y
   function first.

   Sometimes, you want something more complex.  For example, you might
   want to start looking for the last bitmap you used first, and then
   search in a backwards direction.  In that case, set search
   direction to a value other than 0.

   Sometimes, you want to consider only a range of bitmaps.  If so,
   say which is the first and the last.  If you use reversed search
   direction, make sure that the first value is higher than the last
   value.  This function does not give a warning if you do not do
   that.

   Returns: If no bitmap was under the position, the return value is
   -1.  Otherwise it corresponds to the bitmap number, counting from 0.

   arg1: searchdirection
   arg2: first sprite to consider (or -1 if you want to include the first bitmap)
   arg3: last sprite to consider (or -1 if you want to include the last bitmap)
   arg3: x position
   arg4: y position

   This is identical to psy_bitmap_under_mouse, except that it is for
   sprites (i.e., moving bitmaps).

   Returns: If no sprite was under the position, the return value is
   -1.  Otherwise it corresponds to the bitmap number, counting from 0.

   Use: Wait for input from the mouse device.  The code waits until
   user clicks the mouse button.

   Returns: Key status.  Status is correct if the correct mouse button
   in the correct location was pressed.

   arg1: which mousebutton needs to be clicked? 1, 2, or 3, for left, middle, right
   arg2: which sprite number needs to be clicked
   arg3: maximum wait time in milliseconds.

   arg1: number of images
   args: Variable number of images (as specified in args1, up to 100)

   Use: For displaying multiple bitmaps between which users can flip
   (and even can go backwards). This is practical for giving on screen
   instructions through multiple pages.  The keys used are
   q,page-up,up,page-down,down,space.

   returns: nothing.

   Use: Initialises Cedrus keyboard.

   returns: nothing.

   Use: Needed for ending use of Cedrus keyboard

   returns: nothing.

   Use: Tests the delay in the cedrus communication
        For testing the device only

   returns: nothing, but writes to terminal

   see http://www.cedrus.com/xid/test_procedures.htm

   Use: Tests delays in the cedrus communication
        For testing the device only

   returns: nothing, but writes to terminal

   see http://www.cedrus.com/xid/test_procedures.htm

   arg1: the key that is correct (starts with 1)
   arg2: maximum duration

   Use: Similar to psy_readkey.

   returns: nothing.

   arg1: key that should be pressed

   returns: keystatus

   Use: This can be used to check the keystatus, but the function will
   not wait for a response.

   returns: nothing.

   Use: If you press the cedrus keyboard, and if you do not read out
   the key events, you will receive those events next time. Thus, you
   should flush the keyboard if it has not been used for a while (but
   while attached), and somebody might have pressed the button.

   returns: nothing.

   Use: Resets the cedrus timer

   returns: nothing.

   Use: Initialize the iolab device

   returns: nothing.

   arg1: the key that is correct (starts with 1)
   arg2: maximum duration

   Use: Similar to psy_readkey.

   returns: nothing.

   arg1: the key that should be pressed (starts with 1)

   returns: keystatus.

   Use: Needed for ending use of iolab device

   returns: nothing.

   Use: Resets the internal iolab timer

   returns: nothing.

   arg1: key that should be pressed
   args: maximum time this function will wait for a key press

   Use: similar to all other readkey functions

   returns: nothing.

   arg1: key that should be pressed

   Use: Check the status of the iolab device without waiting for a response

   returns: nothing.

   Use: Clears the buffer (any keys that were pressed until now will
   be ignored)

   returns: nothing.

   arg1: Duration
   arg2: Silence
   arg3: Trigger
   arg4: Gain1
   arg5: Gain2
   arg6: If 1, the signal will be passed through to the output on the back of device

   Use: For understanding this function, please read the iolab manual

   returns: nothing.

   Use: This command checks the refreshrate using software.

   returns: number of screen refreshes per second, -1 if not available
   or -2 if not root.

   Use: This command checks the vsync measurement availabitliy using
   software. Does only work if compiled as root.

   returns: -1 if not available, -2 if user not root.

   Use: This command checks whether tasks are running that likely
   interfere with psytoolkit, including:
   Firefox,epiphany,konqueror,openoffice,network,memoryuse, and appends
   this to file name or standard if file name is NULL.

   returns: number indicates the number of positive tests.

   Use: Check whether psytoolkit programme has compiled in test mode
   (i.e., no real time use and no root rights and no vsyncing).

   returns: 1 if compiled in test mode, or 0 if not.

   Use: if you know which bitmap/rectangle has been clicked, you may
   want to find out the exact (centered) x y coordinates.

   returns: x position of the center of the rectangle/bitmap with index argument 1

   Use: if you know which bitmap/rectangle has been clicked, you may
   want to find out the exact (centered) x y coordinates.

   returns: y position of the center of the rectangle/bitmap with index argument 1

   Use: this function is regularly called to check on the dynamic
   bitmaps (sprites).

   returns: nothing

   Use: Create a new sprite
   arg1: the number of the bitmap to be used
   arg2: x position (in psytoolkit coordinate system, whatever that is)
   arg3: y position
   /// arg4: 0 = do not show now, 1 = do show immedeately (sets visibility flag)
   returns: the number of the sprite to be used in other sprite commands

   Use: Move a sprite to an x,y location at speed 

   Use: Move a sprite to an x,y location, and continue moving even if it
   reached the position

   Use: reposition a sprite directly to a new x,y location
   arg1: sprite number (starting at 1)
   arg2: x
   arg2: y

   Use: Move a sprite to an x,y location

   Use: Make existing sprite visible

   Use: Stop moving a sprite

   Use: Continue moving a sprite, after it was stopped

   Use: Change the bitmap of a sprite
   arg1: the spritenumber (counting from 1)
   arg2: the bitmap number (counting from 1/as read in at beginning)

   Use: Move the bitmap in a direction (deg)
   arg1: the spritenumber (counting from 1)
   arg2: start position x
   arg3: start position y
   arg4: angle (0-360)
   arg5: speed

   Use: Delete all or one sprite
   arg1: the spritenumber (counting from 1), or 0 for all

   Use: All sprites stop moving, but all there other properties, including speed, change unmodified.
        This is handy to temporarily stop the movements, which can be undone by unfreeze.

   Use: see psy_sprites_freeze_all

   Use: see psy_sprites_freeze_all

   arg1: sprite number (starting with 1)
   arg2: speed

   Use: This is a wrapper function to set the speed to a specific variable.

   arg1: sprite number (starting with 1)
   arg2: speed change

   Use: This is a wrapper function to change the speed.

   arg1: sprite number
   arg2: no/yes (0/1)

   Use: This is a wrapper function to have it bounce off other sprites

   apply bouncing status to all sprites
   arg1: no/yes (0/1)

   Use: This is a wrapper function to have it bounce off other sprites

   arg1: sprite number
   arg2: no/yes (0/1)

   Use: This is a wrapper function to have it bounce off other sprites

   apply bouncing status to all sprites
   arg1: no/yes (0/1)

   Use: This is a wrapper function to have it bounce off other sprites

   Use:
   arg1: sprite number (starting at 1)
   arg2: speed
   arg3: x1
   arg4: y1
   ...   x1,y1 variable