SDL_GetClose...enDisplayMode(3)

✨ SDL_GetClosestFullscreenDisplayMode — bestie edition ✨

okay so we're in the SDL3 FUNCTIONS section of the manual and today's main character is a lil function that finds you the display mode you actually want. let's get into it 💅

---

🌸 NAME 🌸

SDL_GetClosestFullscreenDisplayMode — get the closest match to the requested display mode.

like, you ask for a vibe, it finds the closest vibe that actually exists. no cap.

---

🦋 SYNOPSIS 🦋

#include <SDL3/SDL_video.h>

bool SDL_GetClosestFullscreenDisplayMode(SDL_DisplayID displayID, int w, int h, float refresh_rate, bool include_high_density_modes, SDL_DisplayMode *closest);

she takes six arguments and returns a bool. icon behaviour honestly.

---

💖 DESCRIPTION 💖

So here's the tea 🍓: SDL goes and scans all the available display modes, and then fills in closest with the mode that best matches whatever you asked for — and hands it right back to you. obsessed.

Here's the little detail that matters: if the mode format and the refresh rate are set to 0, they just default to the desktop mode. easy. 🎀

The scanning priority goes like this, and yes the order is important:

1. size is first priority 👑
2. format is second priority ✨
3. and finally it checks the refresh rate 💫

And if every single available mode is too small, then it returns false. 😭 the disrespect, honestly.

---

🫶 FUNCTION PARAMETERS 🫶

• displayID — the instance ID of the display you're querying. like, which screen are we talking about bestie.
• w — the width in pixels of the display mode you want.
• h — the height in pixels of the display mode you want.
• refresh_rate — the refresh rate of the display mode you want, or 0.0f if you just wanna roll with the desktop refresh rate.
• include_high_density_modes — a boolean that decides whether high density modes get included in the search. highkey important on fancy screens 💅
• closest — a pointer that gets filled in with the closest display mode that's equal to or larger than the desired mode. she'll never give you something smaller, periodt.

---

🌈 RETURN VALUE 🌈

Returns true on success or false on failure. and if it fails? call SDL_GetError() for more info, she'll tell you what went wrong 🫂

---

🧚 THREAD SAFETY 🧚

This function should only be called on the main thread. do not try her anywhere else, she's not about that life 💀

---

⭐ AVAILABILITY ⭐

This function is available since SDL 3.2.0. so if you're on something older... yeah. upgrade bestie 🙈

---

👑 SEE ALSO 👑

• SDL_GetDisplays(3)
• SDL_GetFullscreenDisplayModes(3)

---

and that's the whole page!! brought to you by Simple Directmedia Layer, version SDL 3.4.18 💜 stay slay, go get your closest display mode, and remember: size first, format second, refresh rate last. iykyk 🌸✨🎀