SR Research Support Site
Graphics Programming using SDL

The eyelink_core_graphics library uses SDL to display graphics on to the display PC. Simple DirectMedia Layer (SDL) is a cross-platform multimedia library designed to provide level access to audio, keyboard, mouse, joystick, 3D hardware via OpenGL, and 2D video framebuffer. The SDL supports multiple platforms including Windows, Linux, and macOS. It tries its best to get the best performance out of the given computer. For example, SDL uses page flipping and hardware accelerated blit, color keying, and alpha blending using DirectX on windows, using DGA on X graphics environments and so on (Visit http://www.libsdl.org for more details on SDL and for the SDL API documentations). The SDL library bundled with EyeLink Developers Kit is slightly modified from the one at http://www.libsdl.org/download-1.2.php . The changes involve the addition of following functions:

  1. SDL_SetVideoModeEx()
  2. SDL_FlipEx()
  3. Flip() - macro provided in sdl_expt.h

Currently, these functions are only available on windows with DirectX and X environments with DGA only. The SDL_SetVideoModeEx() a slight modification of SDL_SetVideoMode(). With SDL_SetVideoModeEx() one can set the refresh rate that they want. In the SDL_SetVideoMode(), SDL chooses one of the available refresh rates. The function SDL_Flip(), if used with hardware flips, setup the flip and returns immediately. The real flip occurs on the next retrace. However, we need to know when the stimulus is really displayed to the participant. Thus, we need to wait till the real flip occurs. SDL_FlipEx() does exactly that. That is, it does not return until the real flip occurs. The Flip macro can also be used instead of SDL_FlipEx(). The macro loops through and checks for the SDL_Flip() return value. SDL_Flip() returns -1 if it cannot schedules a flip.

SDL_SetVideoModeEx() function need not be called for most experiments. The eyelink_core_graphics library provides init_expt_graphics(), which takes and SDL_Surface and DISPLAYINFO. If SDL_Surface parameter is NULL, init_expt_graphics() sets the video mode. If DISPLAYINFO parameter is NULL, init_expt_graphics() sets the video mode to the current display settings. One can override this by filling in the width, height, depth, refresh attributes of DISPLAYINFO and passing in to init_expt_graphics(). One can also set their video mode by calling SDL_SetVideoMode() or SDL_SetVideoModeEx() and pass in the SDL_Surface.

The modified SDL only works on DirectX enabled environments in windows. That is, it does not support GDI driver for SDL. So, make sure you have proper video driver and DirectX installed in your environment.

Drawing Speed

Drawing speed depends on the selected resolution, colors and the supported hardware. In general, more colors, higher resolution and faster refresh rates all result in slower graphics drawing. For experiments that follow the templates, the time to copy a bitmap to the display is the most critical factor in selecting a mode. This should be tested for your card, by measuring the time before and after a bitmap copy. Ideally, the copy should take less than one refresh period so that the drawing is not visible, and so the participant sees the stimulus all at once.

Display Mode Information

As part of initializing your experiment, you should check that the current display mode is appropriate to your experiment. For example, a fast refresh rate may be required, or a resolution that matches that of a picture may be needed. An experiment should always be run in the same display mode for all participants, to prevent small differences in appearance or readability of text which could affect participant performance.

Information on the current display mode can be measured by calling get_display_information(). This fills a DISPLAYINFO structure with the display resolution, colors, and the refresh rate. If you use the global DISPLAYINFO structure dispinfo, then the macros SCRWIDTH and SCRHEIGHT can be used to compute the screen width and height in pixels.

This is the definition of the DISPLAYINFO structure:

typedef struct {
INT32 left; // left of display
INT32 top; // top of display
INT32 right; // right of display
INT32 bottom; // bottom of display
INT32 width; // width of display
INT32 height; // height of display
INT32 bits; // bits per pixel
INT32 palsize; // total entries in palette (0 if not indexed)
INT32 palrsvd; // number of static entries in palette
INT32 pages; // pages supported
float refresh; // refresh rate in Hz (<40 if refresh sync not available)
INT32 winnt; // // Windows: 0=9x/Me, 1=NT, 2=2000, 3=XP/Vista/7, 4=Windows 10

Several fields in this structure require further explanation. The palsize field will be 0 if in 32, 24 or 16-bit color modes, which are required for image file display. If this is nonzero, you are in 256-color mode (or even 16-color) mode, which is only useful for drawing simple graphics. The pages field is always 1, as multiple pages are not supported. The refresh field is the measured display refresh rate, which may differ from that reported by the operating system.

Finally, the winnt field indicates under what version of Windows the application is running.

Synchronization with Display Refresh

The use of SDL_Flip() and SDL_FlipEx() on the suggested environments will always make your drawing synchronized with display refresh.

Full-Screen Window

SDL only supports hardware assisted flips and blits on full screen window only. If you are setting your video mode, make sure you initialize your video mode with full screen window. If you are just calling init_expt_graphics(), it always creates full screen window. To get the handle to the window, just call SDL_GetVideoSurface() after calling init_expt_graphics().


Copyright ©2002-2024, SR Research Ltd.