SDL_SetWindowAspectRatio(3)

✨ SDL_SetWindowAspectRatio ✨

okay bestie, welcome to the SDL3 FUNCTIONS cinematic universe 💖 today's episode: SDL_SetWindowAspectRatio — the girl who politely requests that your window's client area have a certain aspect ratio. she asks nicely. she does not command. iykyk.

---

🌸 NAME 🌸

SDL_SetWindowAspectRatio — request that the aspect ratio of a window's client area be set.

---

🎀 SYNOPSIS 🎀

#include <SDL3/SDL_video.h>

bool SDL_SetWindowAspectRatio(SDL_Window *window, float min_aspect, float max_aspect);

---

🦋 DESCRIPTION 🦋

so like, what even is an aspect ratio? it's width divided by height, periodt. so 2560x1600 would be 1.6. bigger aspect ratios are wider, smaller aspect ratios are narrower. that's the whole vibe. 💅

here's the tea tho: if the window is in a fixed-size state at the moment you ask — think maximized or fullscreen — the request gets deferred until the window exits that state and becomes resizable again. she's not ignoring you, she's just booked and busy. 🙈

also, on some windowing systems this request is asynchronous, meaning the new window aspect ratio may not have been applied immediately upon the return of this function. so if you need the change right now, call SDL_SyncWindow() to block until the changes have taken effect. blocking, but make it fashion. ✨

when the window size changes, an SDL_EVENT_WINDOW_RESIZED event gets emitted with the new window dimensions. but heads up — the new dimensions may not match the exact aspect ratio you requested, because some windowing systems can restrict the window size in certain scenarios (e.g. constraining the size of the content area to remain within the usable desktop bounds). and honestly? it's just a request. it can be denied by the windowing system. she's not the main character here, the window manager is. 😭

---

🌈 FUNCTION PARAMETERS 🌈

• window — the window to change. the one getting the glow-up.
• min_aspect — the minimum aspect ratio of the window, or 0.0f for no limit. no floor, no problem.
• max_aspect — the maximum aspect ratio of the window, or 0.0f for no limit. no ceiling, we're free.

---

💜 RETURN VALUE 💜

returns true on success or false on failure — and if it's a flop, call SDL_GetError() for more information. she will tell you exactly what went wrong, fr fr.

---

🧚 THREAD SAFETY 🧚

this function should only be called on the main thread. no side quests, no other threads. main character energy only. 👑

---

⭐ AVAILABILITY ⭐

this function is available since SDL 3.2.0. vintage-ish, but still iconic.

---

🫶 SEE ALSO 🫶

• SDL_GetWindowAspectRatio(3)
• SDL_SyncWindow(3)

---

lowkey reminder: this is a request, not a demand. the windowing system holds the aux cord. 🎧

---

and that's the page, bestie!! brought to you by Simple Directmedia Layer 💖 — the SDL 3.4.18 era, no cap — and this lil' SDL_SetWindowAspectRatio(3) moment was served up fresh in that same version/date energy. slay, stay resizable, and don't forget to SDL_SyncWindow() if you're impatient 🎀✨