SR Research Support Site
Data Structures | Macros | Typedefs | Functions
SDL2 Graphics Functions

Data Structures

struct  _CCDBS
 

Macros

#define SDLRGB(x, y)   SDL_MapRGB(x->format,(y).r,(y).g,(y).b)
 
#define SCREEN_LEFT   dispinfo.left
 
#define SCREEN_TOP   dispinfo.top
 
#define SCREEN_RIGHT   dispinfo.right
 
#define SCREEN_BOTTOM   dispinfo.bottom
 
#define SCRHEIGHT   dispinfo.height
 
#define SCRWIDTH   dispinfo.width
 
#define bitmap_save_and_backdrop   sdl_bitmap_save_and_backdrop
 
#define bitmap_to_backdrop   sdl_bitmap_to_backdrop
 
#define bitmap_save   sdl_bitmap_save
 
#define EXTERNAL_DEV_NONE   ((getExButtonStates)0)
 
#define EXTERNAL_DEV_CEDRUS   ((getExButtonStates)1)
 
#define EXTERNAL_DEV_SYS_KEYBOARD   ((getExButtonStates)2)
 

Typedefs

typedef struct _CCDBS CCDBS
 
typedef int(* getExButtonStates) (CCDBS *)
 

Functions

void set_calibration_colors (SDL_Color *fg, SDL_Color *bg)
 
void set_target_size (UINT16 diameter, UINT16 holesize)
 
void set_cal_sounds (char *ontarget, char *ongood, char *onbad)
 
void set_dcorr_sounds (char *ontarget, char *ongood, char *onbad)
 
INT16 set_camera_image_position (INT16 left, INT16 top, INT16 right, INT16 bottom)
 
int get_current_display_information (int *csw, int *csh, int *ccd)
 
void get_display_information (DISPLAYINFO *di)
 
INT16 init_expt_window (SDL_Window **window, DISPLAYINFO *info)
 
void close_expt_graphics (void)
 
void get_expt_window (SDL_Window **window)
 
int sdl_bitmap_save_and_backdrop (SDL_Surface *hbm, INT16 xs, INT16 ys, INT16 width, INT16 height, char *fname, char *path, INT16 sv_options, INT16 xd, INT16 yd, UINT16 bx_options)
 
int sdl_bitmap_to_backdrop (SDL_Surface *hbm, INT16 xs, INT16 ys, INT16 width, INT16 height, INT16 xd, INT16 yd, UINT16 bx_options)
 
int sdl_bitmap_save (SDL_Surface *hbm, INT16 xs, INT16 ys, INT16 width, INT16 height, char *fname, char *path, INT16 sv_options)
 
void set_cal_target_surface (SDL_Surface *surface)
 
void set_cal_background_surface (SDL_Surface *surface)
 
void reset_background_surface ()
 
void disable_custombackground_on_imagemode ()
 
int set_cal_animation_target (const char *aviName, int playCount, int options)
 
int enable_external_calibration_device (getExButtonStates buttonStatesfcn, const char *config, void *userData)
 

Detailed Description

Macro Definition Documentation

#define bitmap_save   sdl_bitmap_save
#define bitmap_save_and_backdrop   sdl_bitmap_save_and_backdrop
#define bitmap_to_backdrop   sdl_bitmap_to_backdrop

Function Documentation

void close_expt_graphics ( void  )

Call this function at the end of the experiment or before destroying the window registered with init_expt_graphics(). This call will disable calibration and drift correction until a new window is registered.

int enable_external_calibration_device ( getExButtonStates  buttonStatesfcn,
const char *  config,
void *  userData 
)

Enables non keyboard devices to be used for calibration control.

Parameters
[in]buttonStatesfcncallback function reads the device and returns appropriate data.
Remarks
: Use EXTERNAL_DEV_NONE to disable the device. Use EXTERNAL_DEV_CEDRUS for built-in cedrus device support.
Parameters
[in]config- A character string of the config file content or config file name. Whether the config is the content or a file name is determined by looking for a new line character. If there is a new line character the content is assumed. To use the default config, set the parameter to NULL. The default config will be:
1 # User mode definition
2 # [MODE n]
3 # Defines a 'user' mode, where n is the mode ID
4 # Valid Commands for user mode:
5 # TEXT_LINE "This is a line of text"
6 # DISPLAY_IMAGE
7 # BUTTON id button_command [command args]
8 # Valid BUTTON button_commands:
9 # NO_ACTION
10 #
11 # AUTO_THRESH
12 # PUPIL_THRESH_UP
13 # PUPIL_THRESH_DOWN
14 # CR_THRESH_UP
15 # CR_THRESH_DOWN
16 #
17 # START_CALIBRATION
18 # START_VALIDATION
19 # START_DRIFT_CORRECT
20 #
21 # GOTO_MODE
22 # EXIT
23 #
24 # NEXT_IMAGE (only makes sense when DISPLAY_IMAGE is set for mode)
25 # PREV_IMAGE (only makes sense when DISPLAY_IMAGE is set for mode)
26 #
27 # Predefined modes
28 # [MODE C]
29 # Calibration mode
30 # Valid Commands
31 # REDO_LAST_TARGET
32 # ACCEPT_TARGET
33 #
34 # [MODE V]
35 # Validation mode
36 # Valid Commands
37 # REDO_LAST_TARGET
38 # ACCEPT_TARGET
39 #
40 # [MODE D]
41 # Drift Correction mode
42 # Valid Commands
43 # ACCEPT_TARGET
44 
45 [MODE 1]
46 TEXT_LINE "EyeLink Setup:"
47 TEXT_LINE "1 -> View Camera Images"
48 TEXT_LINE "2 -> Start Calibration"
49 TEXT_LINE "3 -> Start Validation"
50 TEXT_LINE "4 -> Exit EyeLink Setup"
51 
52 BUTTON 1 GOTO_MODE 2
53 BUTTON 2 GOTO_MODE C
54 BUTTON 3 GOTO_MODE V
55 BUTTON 4 EXIT
56 
57 
58 
59 
60 [MODE 2]
61 TEXT_LINE "Camera Views:"
62 TEXT_LINE "1 -> Next Camera View"
63 TEXT_LINE "2 -> Previous Camera View"
64 TEXT_LINE "3 -> Go To Pupil Threshold Adjustment Mode"
65 TEXT_LINE "4 -> Exit EyeLink Setup"
66 
67 
68 BUTTON 1 NEXT_IMAGE
69 BUTTON 2 PREV_IMAGE
70 BUTTON 3 GOTO_MODE 3
71 BUTTON 4 EXIT
72 DISPLAY_IMAGE TRUE
73 
74 
75 [MODE 3]
76 TEXT_LINE "Pupil Threshold Adjustment:"
77 TEXT_LINE "1 -> Increase Threshold"
78 TEXT_LINE "2 -> Decrease Threshold"
79 TEXT_LINE "3 -> Auto Threshold"
80 TEXT_LINE "4 -> Go To CR Threshold Adjustment Mode"
81 
82 BUTTON 1 PUPIL_THRESH_UP
83 BUTTON 2 PUPIL_THRESH_DOWN
84 BUTTON 3 AUTO_THRESH
85 BUTTON 4 GOTO_MODE 4
86 DISPLAY_IMAGE TRUE
87 
88 
89 [MODE 4]
90 TEXT_LINE "CR Threshold Adjustment:"
91 TEXT_LINE "1 -> Increase Threshold"
92 TEXT_LINE "2 -> Decrease Threshold"
93 TEXT_LINE "3 -> Auto Threshold"
94 TEXT_LINE "4 -> Go To EyeLink Setup Mode"
95 
96 
97 BUTTON 1 CR_THRESH_UP
98 BUTTON 2 CR_THRESH_DOWN
99 BUTTON 3 AUTO_THRESH
100 BUTTON 4 GOTO_MODE 1
101 DISPLAY_IMAGE TRUE
102 
103 
104 [MODE C]
105 BUTTON 1 ACCEPT_TARGET
106 BUTTON 2 REDO_LAST_TARGE
107 BUTTON 4 EXIT
108 
109 [MODE V]
110 BUTTON 1 ACCEPT_TARGET
111 BUTTON 2 REDO_LAST_TARGE
112 BUTTON 4 EXIT
113 
114 [MODE D]
115 BUTTON 1 ACCEPT_TARGET
116 BUTTON 4 EXIT
Parameters
[in]userDatauser data to pass back in the callback.
Returns
1 upon success, 0 otherwise
int get_current_display_information ( int *  csw,
int *  csh,
int *  ccd 
)

Returns screen resolution in pixels and colour depth in bits per pixel of the current display mode, and fills the respective pointers to integer arguments accordingly. The main purpose of this function is to obtain the current resolution of the desktop environment before the call to initialize the main window.

Parameters
cswCurrent Screen Width in pixels.
cshCurrent Screen Height in pixels.
ccdCurrent colour depth in bits per pixel.
Returns
1 if success, 0 if failure to detect display mode.
Remarks
This function utilizes GDI under Windows, Quartz under Mac OS X and SDL under Ubuntu (requires SDL1.2.10 and up). It may fail if none of these combinations are present.
    Custom initialization of SDL using current display mode can be done in the following manner:
    <pre>
1 int customGraphicsSetup()
2 {
3  int screen_w, screen_h, pixel_d; // screen width, height and pixel depth
4  SDL_Surface *mainwindow = NULL;
5  if ( SDL_Init(SDL_INIT_VIDEO) < 0 ) // initialize SDL
6  {
7  printf("Couldn't initialize SDL: %s!",SDL_GetError());
8  return -1;
9  }
10  if (get_current_display_information(&screen_w, &screen_h, &pixel_d)){
11  printf("Setting video mode to: %dx%dx%d\n", screen_w, screen_h, pixel_d);
12  mainwindow = SDL_SetVideoMode(screen_w,screen_h,pixel_d,SDL_SWSURFACE|SDL_FULLSCREEN); // set video mode
13  }else{
14  printf("Failed to detect current video mode. Setting to default: 800x600x32");
15  mainwindow = SDL_SetVideoMode(800,600,32,SDL_SWSURFACE|SDL_FULLSCREEN); // set video mode
16  }
17  if(!mainwindow)
18  {
19  printf("Failed to set video mode: %s! ",SDL_GetError());
20  return -1;
21  }
22  if(init_expt_graphics(mainwindow, NULL)) // tell core graphics to use the set video mode.
23  return -1;
24  return 0;
25 }
void get_display_information ( DISPLAYINFO di)

Measures parameters of the current display mode, and fills a DISPLAYINFO structure with the data. This process may take over 100 milliseconds, as it measures actual refresh rate. The returned data can be used to compute sizes for drawing, and to check that the current display mode matches the requirements of the experiment. A global DISPLAYINFO structure called dispinfo should be set up at the start of the program if you wish to use the SCRWIDTH and SCRHEIGHT macros.

Remarks
This is the contents of the DISPLAYINFO structure:
1 typedef struct
2 {
3  INT32 left; // left of display
4  INT32 top; // top of display
5  INT32 right; // right of display
6  INT32 bottom; // bottom of display
7  INT32 width; // width of display
8  INT32 height; // height of display
9  INT32 bits; // bits per pixel
10  INT32 palsize; // total entries in palette (0 if not indexed)
11  INT32 palrsvd; // number of static entries in palette
12  INT32 pages; // pages supported
13  float refresh; // refresh rate in Hz
14  INT32 winnt; // 0 for 9x/Me, 1 for NT, 2 for 2000, 3 for XP
15 } DISPLAYINFO;
If refresh cannot be measured, the "refresh" field will contain a value less than 40.
Parameters
diPointer to DISPLAYINFO structure to fill.

This is an optional function to get information on video driver and current mode use this to determine if in proper mode for experiment.

Parameters
[out]diA valid pointer to DISPLAYINFO is passed in to return values.
Remarks
The prototype of this function can be changed to match one's need or if it is not necessary, one can choose not to implement this function also.
INT16 init_expt_window ( SDL_Window **  window,
DISPLAYINFO info 
)

You must always create a borderless, full-screen window for your experiment. This function registers the window with EXPTSPPT so it may be used for calibration and drift correction. The window should not be destroyed until it is released with close_expt_graphics(). This window will be subclassed (some messages intercepted) during calibration and drift correction.

Parameters
windowHandle of window that is to be used for calibration and drift correction. If NULL is passed in, SDL2 will be initialized and requested display mode is set.
infoNULL or pointer to a DISPLAYINFO structure to fill with display mode data. If NULL is passed in, current display mode is used.
Returns
0 if success, -1 if error occurred internally. If info->width and info->height is 0, then the current window size will be taken
Remarks
For windows and Linux, the SDL_CreateWindowAndRenderer() is used to initialized. For mac, SDL_CreateRenderer is created with SDL_RENDERER_SOFTWARE as the argument.

Default initialization of eyelink_core_library:

1 int defaultGraphicsSetup()
2 {
3  SDL_Window *window=NULL;
4  DISPLAYINFO disp;
5  memset(&disp,0,sizeof(DISPLAYINFO));
6 
7  disp.width =640;
8  disp.height = 480;
9  disp.bits =32;
10  disp.refresh = 60;
11  if(init_expt_window(&window, disp)) // register window with EXPTSPPT
12  {
13  alert_printf("init_expt_window failed\n");
14  return exit_eyelink();
15  }
16  return 0;
17 }
void reset_background_surface ( )

Removes the custom background. equivalent of calling set_cal_background_surface(NULL);

int sdl_bitmap_save ( SDL_Surface *  hbm,
INT16  xs,
INT16  ys,
INT16  width,
INT16  height,
char *  fname,
char *  path,
INT16  sv_options 
)

This function saves the entire bitmap or selected part of a bitmap in an image file (with an extension of .png, .bmp, .jpg, or .tif). It creates the specified file if this file does not exist. If the file exists, it replaces the file unless SV_NOREPLACE is specified in the field of "sv_options". The directory to which the file will be written is specified in the path field.

Parameters
hbmHandle to the bitmap image.
xsSpecifies the x-coordinate of the upper-left corner of the source bitmap.
ysSpecifies the y-coordinate of the upper-left corner of the source bitmap.
widthSpecify the width of the source image to be copied (set to 0 to use all).
heightSpecify the height of the source image to be copied (set to 0 to use all).
fnameName of the image file to be saved. Currently, only .PNG, .BMP, .JPG, and .TIF files are saved.
pathDirectory or drive path in quotes ("." for current directory).
sv_optionsUse SV_NOREPLACE if not to replace an existing file; use SV_MAKEPATH to create a new path.
Returns
0 if successful, else -1.
int sdl_bitmap_save_and_backdrop ( SDL_Surface *  hbm,
INT16  xs,
INT16  ys,
INT16  width,
INT16  height,
char *  fname,
char *  path,
INT16  sv_options,
INT16  xd,
INT16  yd,
UINT16  bx_options 
)

This function saves the entire bitmap as a .BMP, .JPG, .PNG, or .TIF file, and transfers the image to tracker as backdrop for gaze cursors (See bitmap_save() and bitmap_to_backdrop() for more information).

Parameters
hbmHandle to the bitmap image.
xsSpecifies the x-coordinate of the upper-left corner of the source bitmap.
ysSpecifies the y-coordinate of the upper-left corner of the source bitmap.
widthSpecify the width of the source image to be copied (set to 0 to use all).
heightSpecify the height of the source image to be copied (set to 0 to use all).
fnameName of the image file to be saved. Currently, only .PNG, .BMP, .JPG, and .TIF files are saved.
pathDirectory or drive path in quotes ("." for current directory).
sv_optionsUse SV_NOREPLACE if not to replace an existing file; use SV_MAKEPATH to create a new path.
xdSpecifies the x-coordinate of the upper-left corner of the tracker screen.
ydSpecifies the y-coordinate of the upper-left corner of the tracker screen.
bx_optionsSet with a bitwise OR of the following constants: BX_MAXCONTRAST: Maximizes contrast for clearest image; BX_AVERAGE: averages combined pixels; BX_DARKEN: chooses darkest (keep thin dark lines); BX_LIGHTEN: chooses darkest (keep thin white lines); BX_NODITHER: disables dithering to get clearest text; BX_GREYSCALE: converts to grayscale.
Returns
0 if successful, -1 if couldn't save, -2 if couldn't transfer
int sdl_bitmap_to_backdrop ( SDL_Surface *  hbm,
INT16  xs,
INT16  ys,
INT16  width,
INT16  height,
INT16  xd,
INT16  yd,
UINT16  bx_options 
)

This function transfers the bitmap to the tracker PC as backdrop for gaze cursors. The field "bx_options", set with bitwise OR of the following constants, determines how bitmap is processed: BX_AVERAGE (averaging combined pixels), BX_DARKEN (choosing darkest and keep thin dark lines), and BX_LIGHTEN (choosing darkest and keep thin white lines) control how bitmap size is reduced to fit tracker display; BX_MAXCONTRAST maximizes contrast for clearest image; BX_NODITHER disables the dithering of the image; BX_GREYSCALE converts the image to grayscale (grayscale works best for EyeLink I, text, etc.)

Parameters
hbmHandle to the bitmap image.
xsSpecifies the x-coordinate of the upper-left corner of the source bitmap.
ysSpecifies the y-coordinate of the upper-left corner of the source bitmap.
widthSpecify the width of the source image to be copied (set to 0 to use all).
heightSpecify the height of the source image to be copied (set to 0 to use all).
xdSpecifies the x-coordinate of the upper-left corner of the tracker screen.
ydSpecifies the y-coordinate of the upper-left corner of the tracker screen.
bx_optionsSet with a bitwise OR of the following constants: BX_MAXCONTRAST: Maximizes contrast for clearest image; BX_AVERAGE: averages combined pixels; BX_DARKEN: chooses darkest (keep thin dark lines); BX_LIGHTEN: chooses darkest (keep thin white lines); BX_NODITHER: disables dithering to get clearest text; BX_GREYSCALE: converts to grayscale.
Returns
0 if successful, else -1 or -2
int set_cal_animation_target ( const char *  aviName,
int  playCount,
int  options 
)

Allow one to set target with animation. The expected video can be loadable using VFW(type 1 avi) also, both audio and video streams must be present. The audio stream must be of pcm type. To support more codecs, please install ffdshow from 3rdparty folder under SR Research installation. Both 32 bit / 64 bit version can be installed and codec selection can be made with Win7DFilterTweaker app.

Parameters
aviNameName of the avi to use
playCountHow many time to loop through the video. Specify -1 to loop indefinitely. for future use.
void set_cal_background_surface ( SDL_Surface *  surface)

Allow one to set arbituary background in place of flat background

Parameters
surface
void set_cal_sounds ( char *  ontarget,
char *  ongood,
char *  onbad 
)

Selects the sounds to be played during do_tracker_setup(), including calibration, validation and drift correction. These events are the display or movement of the target, successful conclusion of calibration or good validation, and failure or interruption of calibration or validation.

Remarks
If no sound card is installed, the sounds are produced as "beeps" from the PC speaker. Otherwise, sounds can be selected by passing a string. If the string is "" (empty), the default sounds are played. If the string is "off", no sound will be played for that event. Otherwise, the string should be the name of a .WAV file to play.
Parameters
ontargetSets sound to play when target moves.
ongoodSets sound to play on successful operation.
onbadSets sound to play on failure or interruption.

Example: See do_tracker_setup()

See also
do_tracker_setup() and set_dcorr_sounds()
void set_cal_target_surface ( SDL_Surface *  surface)

Allow one to set arbituary target in place of circle target. Eg. a custom cursor.

Parameters
surface
void set_calibration_colors ( SDL_Color *  fg,
SDL_Color *  bg 
)

Passes the colors of the display background and fixation target to the EXPTSPPT library. During calibration, camera image display, and drift correction, the display background should match the brightness of the experimental stimuli as closely as possible, in order to maximize tracking accuracy. This function passes the colors of the display background and fixation target to the EXPTSPPT library. This also prevents flickering of the display at the beginning and end of drift correction.

Parameters
fgColor used for drawing calibration target.
bgColor used for drawing calibration background.

Example: See do_tracker_setup()

See also
do_tracker_setup()
INT16 set_camera_image_position ( INT16  left,
INT16  top,
INT16  right,
INT16  bottom 
)

To adjust camera image position. By default the camera is placed at the centre of the screen.

Parameters
leftLeft position.
topTop position.
rightRight position.
bottomBottom position.
void set_dcorr_sounds ( char *  ontarget,
char *  ongood,
char *  onbad 
)

Selects the sounds to be played during do_drift_correct(). These events are the display or movement of the target, successful conclusion of drift correction, and pressing the 'ESC' key to start the Setup menu.

Remarks
If no sound card is installed, the sounds are produced as "beeps" from the PC speaker. Otherwise, sounds can be selected by passing a string. If the string is "" (empty), the default sounds are played. If the string is "off", no sound will be played for that event. Otherwise, the string should be the name of a .WAV file to play.
Parameters
ontargetSets sound to play when target moves.
ongoodSets sound to play on successful operation.
onbadSets sound to play on failure or interruption.

Example: See do_tracker_setup()

See also
do_tracker_setup() and set_cal_sounds()
void set_target_size ( UINT16  diameter,
UINT16  holesize 
)

The standard calibration and drift correction target is a disk (for peripheral delectability) with a central "hole" target (for accurate fixation). The sizes of these features may be set with this function.

Parameters
diameterSize of outer disk, in pixels.
holesizeSize of central feature. If <holesize> is 0, no central feature will be drawn.

Example: See do_tracker_setup()

See also
do_tracker_setup()

Copyright ©2002-2023, SR Research Ltd.