SDL_ListModes

SDL_ListModes -- Returns a pointer to an array of available screen dimensions for the given format and video flags

Syntax

SDL_Rect** SDL_ListModes(SDL_PixelFormat* format, Uint32 flags);

Description

The returned pointer is an array of SDL_Rect pointers to available screen dimensions for the given pixel format and video flags. The array is not guaranteed to be sorted in any particular order. The function returns NULL if there is not any mode available for the particular format, or -1 if any dimension is okay for the given format.

Parameters

format [in]

The SDL_PixelFormat of the modes to look up. If format is NULL, the current format of the video device is used. The current format of the video device is retrieved through SDL_GetVideoInfo.

flags [in]

The flags parameter is an OR'd combination of surface flags which are the same as those used by SDL_SetVideoMode and they play a strong role in deciding which modes are valid. For instance, if you pass SDL_HWSURFACE as a flag, only the modes that support hardware video surfaces will be returned.

Return value

NULL

There is not any mode available for the particular format

-1

Any dimension is okay for the given format

The pointer to the array of SDL_Rect

On success. The pointer to the video dimensions array is managed by SDL itself. The caller must not free the returned pointer.

Example

   1 SDL_Rect** modes;
   2 int i;
   3 
   4 /* Get available fullscreen/hardware modes */
   5 modes = SDL_ListModes(NULL, SDL_FULLSCREEN|SDL_HWSURFACE);
   6 
   7 /* Check if there are any modes available */
   8 if (modes == (SDL_Rect**)0) {
   9     printf("No modes available!\n");
  10     exit(-1);
  11 }
  12 
  13 /* Check if our resolution is restricted */
  14 if (modes == (SDL_Rect**)-1) {
  15     printf("All resolutions available.\n");
  16 }
  17 else{
  18     /* Print valid modes */
  19     printf("Available Modes\n");
  20     for (i=0; modes[i]; ++i)
  21       printf("  %d x %d\n", modes[i]->w, modes[i]->h);
  22 }

Requirements

Header	SDL.h
Version	1.2.13
Shared object	libSDL.so
DLL	SDL.dll

CategorySDLVideo

User comments

From digging through the source: the list returned by this call is statically allocated. You do not need to free it. Now, somebody help me out here for future reference, should I have just assumed that because it wasn't otherwise mentioned or should that sort of thing be documented explicitly?
-- cid 2005-??-??

SDL_ListModes doesn't quite give the list of all the modes that would work (X11). I was briefly filtering the available resolutions based on the values returned and removed it from Quake4 as it was way too restrictive. I don't know if it's a problem with SDL, or with Xxf86vm.
-- TTimo 2006-04-24

The example program crashes for me. It seems like SDL_ListModes uses an unitialized(?) NULL pointer current_video (as a part of expanding the preprocessor macro SDL_VideoSurface).

T 2009-08-31