====== (This is the documentation for SDL3, which is under heavy development and the API is changing! [https://wiki.libsdl.org/SDL2/ SDL2] is the current stable version!) ======
= SDL_GetClosestDisplayMode =

Get the closest match to the requested display mode.

== Syntax ==

<syntaxhighlight lang='c'>
SDL_DisplayMode* SDL_GetClosestDisplayMode(int displayIndex, const SDL_DisplayMode *mode, SDL_DisplayMode *closest);
</syntaxhighlight>

== Function Parameters ==

{|
|'''displayIndex'''
|the index of the display to query
|-
|'''mode'''
|an [[SDL_DisplayMode]] structure containing the desired display mode
|-
|'''closest'''
|an [[SDL_DisplayMode]] structure filled in with the closest match of the available display modes
|}

== Return Value ==

Returns the passed in value <code>closest</code> or NULL if no matching
video mode was available; call [[SDL_GetError]]() for more information.

== Remarks ==

The available display modes are scanned and <code>closest</code> is filled
in with the closest mode matching the requested mode and returned. The mode
format and refresh rate default to the desktop mode if they are set to 0.
The modes are scanned with size being first priority, format being second
priority, and finally checking the refresh rate. If all the available modes
are too small, then NULL is returned.

== Version ==

This function is available since SDL 3.0.0.

== Code Examples ==

<syntaxhighlight lang='c++'>
// Using SDL2's SDL_GetClosestDisplayMode()

#include "SDL.h"
#include <stdio.h>

int main(int argc, char* argv[]) {

  // Declare structures to be filled in.
  SDL_DisplayMode target, closest;

  SDL_Init(SDL_INIT_VIDEO);

  // Set the desired resolution, etc.
  target.w = 600;
  target.h = 500;
  target.format = 0;  // don't care
  target.refresh_rate = 0; // don't care
  target.driverdata   = 0; // initialize to 0
  printf("Requesting: \t%dx%dpx @ %dhz \n", target.w, target.h, target.refresh_rate);

  // Pass the display mode structures by reference to SDL_GetClosestDisplay
  // and check whether the result is a null pointer.
  if (SDL_GetClosestDisplayMode(0, &target, &closest) == NULL)

    // If the returned pointer is null, no match was found.
    printf("\nNo suitable display mode was found!\n\n");

  else
    // Otherwise, a display mode close to the target is available.
    // Access the SDL_DisplayMode structure to see what was received.
    printf("  Received: \t%dx%dpx @ %dhz \n", closest.w, closest.h, closest.refresh_rate);

  // Clean up and exit the program.
  SDL_Quit();
  return 0;

}
</syntaxhighlight>

== Related Functions ==

:[[SDL_GetDisplayMode]]
:[[SDL_GetNumDisplayModes]]

----
[[CategoryAPI]], [[CategoryVideo]]