SR Research Support Site
Macros | Functions | Variables
GDI Graphics Functions

Macros

#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 process_key_messages   gdi_process_key_messages
 
#define bitmap_save_and_backdrop   gdi_bitmap_save_and_backdrop
 
#define bitmap_to_backdrop   gdi_bitmap_to_backdrop
 
#define bitmap_save   gdi_bitmap_save
 
#define message_pump(x)   message_pump()
 
#define CALLTYPE   ELCALLTYPE
 
#define HOOK_ERROR   -1 /* if error occurred */
 
#define HOOK_CONTINUE   0 /* if drawing to continue after return from hook */
 
#define HOOK_NODRAW   1 /* if drawing should not be done after hook */
 
#define CAL_TARG_BEEP   1
 
#define CAL_GOOD_BEEP   0
 
#define CAL_ERR_BEEP   -1
 
#define DC_TARG_BEEP   3
 
#define DC_GOOD_BEEP   2
 
#define DC_ERR_BEEP   -2
 

Functions

void set_calibration_colors (COLORREF fg, COLORREF 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 set_calibration_monitor_index (int monitor_index)
 
void get_display_information (DISPLAYINFO *di)
 
INT16 init_expt_graphics (HWND hwnd, DISPLAYINFO *info)
 
void close_expt_graphics (void)
 
void wait_for_video_refresh (void)
 
UINT16 gdi_process_key_messages (HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam)
 
void wait_for_drawing (HWND hwnd)
 
int gdi_bitmap_save_and_backdrop (HBITMAP hbm, INT16 xs, INT16 ys, INT16 width, INT16 height, char *fname, char *path, INT16 sv_options, INT16 xd, INT16 yd, UINT16 bx_options)
 
int gdi_bitmap_to_backdrop (HBITMAP hbm, INT16 xs, INT16 ys, INT16 width, INT16 height, INT16 xd, INT16 yd, UINT16 bx_options)
 
int gdi_bitmap_save (HBITMAP hbm, INT16 xs, INT16 ys, INT16 width, INT16 height, char *fname, char *path, INT16 sv_options)
 
INT16 set_setup_cal_display_hook (INT16(*hookfn)(void), INT16 options)
 
INT16 set_clear_cal_display_hook (INT16(*hookfn)(HDC hdc), INT16 options)
 
INT16 CALLTYPE set_erase_cal_target_hook (INT16(*hookfn)(HDC hdc), INT16 options)
 
INT16 CALLTYPE set_draw_cal_target_hook (INT16(*hookfn)(HDC hdc, INT16 *x, INT16 *y), INT16 options)
 
INT16 set_exit_cal_display_hook (INT16(*hookfn)(void), INT16 options)
 
INT16 CALLTYPE set_cal_sound_hook (INT16(*hookfn)(INT16 *error), INT16 options)
 
INT16 set_record_abort_hide_hook (INT16(*hookfn)(void), INT16 options)
 
INT16 set_setup_image_display_hook (INT16(*hookfn)(INT16 width, INT16 height), INT16 options)
 
INT16 set_image_title_hook (INT16(*hookfn)(INT16 threshold, char *cam_name), INT16 options)
 
INT16 set_draw_image_line_hook (INT16(*hookfn)(INT16 width, INT16 line, INT16 totlines, byte *pixels), INT16 options)
 
INT16 set_set_image_palette_hook (INT16(*hookfn)(INT16 ncolors, byte r[], byte g[], byte b[]), INT16 options)
 
INT16 set_exit_image_display_hook (INT16(*hookfn)(void), INT16 options)
 
void initialize_gc_window (int wwidth, int wheight, HBITMAP window_bitmap, HBITMAP background_bitmap, HWND window, RECT display_rect, int is_mask, int deadband)
 
void redraw_gc_window (int x, int y)
 
HDC get_window_dc (void)
 
INT16 release_window_dc (HDC hdc)
 
INT16 edit_dialog (HWND hwnd, LPSTR title, LPSTR msg, LPSTR txt, INT16 maxsize)
 
INT16 ask_session (HWND hw, LPSTR title, LPSTR msg, LPSTR path, INT16 pathmax, LPSTR txt, INT16 maxsize)
 

Variables

DISPLAYINFO dispinfo
 

Detailed Description

Macro Definition Documentation

#define bitmap_save   gdi_bitmap_save
#define bitmap_save_and_backdrop   gdi_bitmap_save_and_backdrop
#define bitmap_to_backdrop   gdi_bitmap_to_backdrop
#define message_pump (   x)    message_pump()
#define process_key_messages   gdi_process_key_messages

Function Documentation

INT16 ask_session ( HWND  hw,
LPSTR  title,
LPSTR  msg,
LPSTR  path,
INT16  pathmax,
LPSTR  txt,
INT16  maxsize 
)

This function accepts path and session name from the user.

Parameters
hwndThe "parent" window, usually the experiment window or NULL if no window exists.
titleText to be displayed in the frame of the dialog box.
msgInstructions to be displayed in the dialog box.
txtThe buffer into which text will be entered. Any text in this buffer will be displayed as the initial contents of the edit box.
maxsizeThe maximum buffer length of txt.
[in,out]pathThe default path and selected path upon return. If "" used as default path the default documents directory will be used as the default path.
pathmaxsize of the path parameter.
Returns
0 if the ENTER key was pressed or "OK" was clicked. 1 if 'ESC' pressed or "Cancel" clicked. -1 if ALT-F4 pressed to destroy the dialog box.
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.

INT16 edit_dialog ( HWND  hwnd,
LPSTR  title,
LPSTR  msg,
LPSTR  txt,
INT16  maxsize 
)

All experiments require the input of information: EDF file name, randomization file, and so on. This function implements a simple text-entry dialog box for this purpose. A title in the window frame and a message can be set, and the initial text set. The length of the text to be entered can also be limited.

Parameters
hwndThe "parent" window, usually the experiment window or NULL if no window exists.
titleText to be displayed in the frame of the dialog box.
msgInstructions to be displayed in the dialog box.
txtThe buffer into which text will be entered. Any text in this buffer will be displayed as the initial contents of the edit box.
maxsizeThe maximum buffer length of txt.
Returns
0 if the ENTER key was pressed or "OK" was clicked. 1 if 'ESC' pressed or "Cancel" clicked. -1 if ALT-F4 pressed to destroy the dialog box.
int gdi_bitmap_save ( HBITMAP  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 gdi_bitmap_save_and_backdrop ( HBITMAP  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 gdi_bitmap_to_backdrop ( HBITMAP  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.
UINT16 gdi_process_key_messages ( HWND  hWnd,
UINT  message,
WPARAM  wParam,
LPARAM  lParam 
)

Call this function in your window message processing function to handle WM_CHAR and WM_KEYDOWN messages. These will be translated to an EyeLink key code and saved for getkey().

Parameters
hWndHandle to window. This message may be NULL.
messageWindows message.
wParamFirst message parameter.
lParamSecond windows parameter.
Returns
0 or JUNK_KEY if no key generated.

Example:

1 // The following code illustrates the use of process_key_messages().
2 // This would usually be called from a message or event handler (see the
3 // w32_demo_window.c module) for a complete example
4 
5 #include <eyelink.h>
6 switch (message)
7 {
8 case WM_KEYDOWN:
9 case WM_CHAR:
10  // Processes key messages: these can be accessed by getkey()
11  process_key_messages(hwnd, message, wparam, lparam);
12  break;
13 
14  ...
15  // Other windows messages and events
16 }
See also
getkey() and translate_key_messages()
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.
HDC get_window_dc ( void  )

Gets a display context to draw on the page. This is a static DC, so all settings from your last use are preserved.

INT16 init_expt_graphics ( HWND  hwnd,
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
hwndHandle of window that is to be used for calibration and drift correction. This should be a borderless, full-screen window. If your language can't give you a window handle, use NULL and the topmost window will be detected.
infoNULL or pointer to a DISPLAYINFO structure to fill with display mode data.
Returns
0 if success, -1 if error occurred internally.
void initialize_gc_window ( int  wwidth,
int  wheight,
HBITMAP  window_bitmap,
HBITMAP  background_bitmap,
HWND  window,
RECT  display_rect,
int  is_mask,
int  deadband 
)
  • To initialize a gaze contengent window.
  • Initial setup of gaze-contingent window before drawing it.
  • Sets size of window, and whether it is a foveal mask.
  • If height or width is -1, the window will be a bar covering the display.
Parameters
wwidth
wheight
window_bitmap
background_bitmap
windowThe window to display in.
display_rectArea of display in window.
is_mask
deadbandSets number of pixels of anti-jitter applied.
void redraw_gc_window ( int  x,
int  y 
)

Set the location of the gaze window to this new position. The first time window is drawn, the background outside the window will be filled in too. If x or y is MISSING_DATA (defined in eyelink.h), window is hidden.

Parameters
xX location.
yY location.
INT16 release_window_dc ( HDC  hdc)

Release the page DC

INT16 CALLTYPE set_cal_sound_hook ( INT16(*)(INT16 *error)  hookfn,
INT16  options 
)

To modify the behaviour of cal_sound() function.

Parameters
hookfnFunction to replace cal_sound().
optionsFor future use.
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_calibration_colors ( COLORREF  fg,
COLORREF  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()
int set_calibration_monitor_index ( int  monitor_index)

Set calibration monitor index

Parameters
indexof the monitor Eg. 1 is main monitor When the monitor index is set, that index will be used to get the display information.
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.
INT16 set_clear_cal_display_hook ( INT16(*)(HDC hdc)  hookfn,
INT16  options 
)

To modify the behaviour of clear_cal_display() function.

Parameters
hookfnFunction to replace clear_cal_display().
optionsFor future use.
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()
INT16 CALLTYPE set_draw_cal_target_hook ( INT16(*)(HDC hdc, INT16 *x, INT16 *y)  hookfn,
INT16  options 
)
Parameters
hookfnFunction to replace draw_cal_target().
optionsFor future use.
INT16 set_draw_image_line_hook ( INT16(*)(INT16 width, INT16 line, INT16 totlines, byte *pixels)  hookfn,
INT16  options 
)

To modify the behaviour of draw_image_line() function.

Parameters
hookfnFunction to replace draw_image_line().
optionsFor future use.
INT16 CALLTYPE set_erase_cal_target_hook ( INT16(*)(HDC hdc)  hookfn,
INT16  options 
)

To modify the behaviour of erase_cal_target() function.

Parameters
hookfnFunction to replace erase_cal_target().
optionsFor future use.
INT16 set_exit_cal_display_hook ( INT16(*)(void)  hookfn,
INT16  options 
)

To modify the behaviour of exit_cal_display() function.

Parameters
hookfnFunction to replace exit_cal_display().
optionsFor future use.
INT16 set_exit_image_display_hook ( INT16(*)(void)  hookfn,
INT16  options 
)

To modify the behaviour of exit_image_display() function.

Parameters
hookfnFunction to replace exit_image_display().
optionsFor future use.
INT16 set_image_title_hook ( INT16(*)(INT16 threshold, char *cam_name)  hookfn,
INT16  options 
)

To modify the behaviour of image_title() function.

Parameters
hookfnFunction to replace image_title().
optionsFor future use.
INT16 set_record_abort_hide_hook ( INT16(*)(void)  hookfn,
INT16  options 
)

To modify the behaviour of record_abort_hide() function.

Parameters
hookfnFunction to replace record_abort_hide().
optionsFor future use.
INT16 set_set_image_palette_hook ( INT16(*)(INT16 ncolors, byte r[], byte g[], byte b[])  hookfn,
INT16  options 
)

To modify the behaviour of set_image_palette() function.

Parameters
hookfnFunction to replace set_image_palette().
optionsFor future use.
INT16 set_setup_cal_display_hook ( INT16(*)(void)  hookfn,
INT16  options 
)

To modify the behaviour of setup_cal_display() function.

Parameters
hookfnFunction to replace setup_cal_display().
optionsFor future use.
INT16 set_setup_image_display_hook ( INT16(*)(INT16 width, INT16 height)  hookfn,
INT16  options 
)

To modify the behaviour of setup_image_display() function.

Parameters
hookfnFunction to replace setup_image_display().
optionsFor future use.
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()
void wait_for_drawing ( HWND  hwnd)

Forces start of drawing, waits for drawing to finish hwnd may be NULL for all displays together

Parameters
hwndHandle to the window.
void wait_for_video_refresh ( void  )

This function will not return until the current refresh of the monitor has completed (at the start of vertical retrace). This can be used to synchronize drawing to the scanning out of the display, and to determine when a stimulus was first seen by the subject. The DriverLinx PortIO driver must be installed for this function to work.

Remarks
This is function is only applicable for the GDI version.

Copyright ©2002-2024, SR Research Ltd.