SDL_CreateWindow(3)

💖 SDL_CreateWindow 💖

okay bestie, welcome to the SDL3 video era, this is SDL_CreateWindow(3) and it is literally how you make a window. yes. a whole window. your lil rectangle of destiny. let's go 🪟✨

---

🌸 NAME 🌸

SDL_CreateWindow — spawn a window with the dimensions and flags you want, no cap.

---

✨ SYNOPSIS ✨

#include <SDL3/SDL_video.h>

SDL_Window * SDL_CreateWindow(const char *title, int w, int h, SDL_WindowFlags flags);

---

🦋 DESCRIPTION 🦋

so here's the tea: the size you ask for? it's a request, bestie. it might not be what you get, because desktop layout and window manager policies have opinions, and honestly? they're the main character here. your app needs to be prepared to handle a window of any size. any. size. it's giving "flexible or perish" 😭

flags can be any of the following, OR'd together (yes, mix and match, it's a vibe):

• SDL_WINDOW_FULLSCREEN — fullscreen window at desktop resolution 🖥️
• SDL_WINDOW_OPENGL — window usable with an OpenGL context
• SDL_WINDOW_HIDDEN — window is not visible 🙈
• SDL_WINDOW_BORDERLESS — no window decoration, clean face, no frame 💅
• SDL_WINDOW_RESIZABLE — window can be resized
• SDL_WINDOW_MINIMIZED — window is minimized
• SDL_WINDOW_MAXIMIZED — window is maximized
• SDL_WINDOW_MOUSE_GRABBED — window has grabbed mouse focus
• SDL_WINDOW_INPUT_FOCUS — window has input focus
• SDL_WINDOW_MOUSE_FOCUS — window has mouse focus
• SDL_WINDOW_EXTERNAL — window not created by SDL
• SDL_WINDOW_MODAL — window is modal
• SDL_WINDOW_HIGH_PIXEL_DENSITY — window uses high pixel density back buffer if possible ✨
• SDL_WINDOW_MOUSE_CAPTURE — window has mouse captured (unrelated to MOUSE_GRABBED, do not confuse them, they are different girls)
• SDL_WINDOW_ALWAYS_ON_TOP — window should always be above others 👑
• SDL_WINDOW_UTILITY — window should be treated as a utility window, not showing in the task bar and window list
• SDL_WINDOW_TOOLTIP — window should be treated as a tooltip and does not get mouse or keyboard focus, requires a parent window
• SDL_WINDOW_POPUP_MENU — window should be treated as a popup menu, requires a parent window
• SDL_WINDOW_KEYBOARD_GRABBED — window has grabbed keyboard input
• SDL_WINDOW_VULKAN — window usable with a Vulkan instance
• SDL_WINDOW_METAL — window usable with a Metal instance
• SDL_WINDOW_TRANSPARENT — window with transparent buffer 🫥
• SDL_WINDOW_NOT_FOCUSABLE — window should not be focusable

the SDL_Window will be shown if SDL_WINDOW_HIDDEN is not set. and if you did hide it at creation time? no worries babe, SDL_ShowWindow() can show it later. delayed slay 💅

on Apple's macOS, you must set the NSHighResolutionCapable Info.plist property to YES, otherwise you will not receive a High-DPI OpenGL canvas. periodt. don't skip this one.

the window pixel size may differ from its window coordinate size if the window is on a high pixel density display. use SDL_GetWindowSize() to query the client area's size in window coordinates, and SDL_GetWindowSizeInPixels() or SDL_GetRenderOutputSize() to query the drawable size in pixels. note that the drawable size can vary after the window is created and should be queried again if you get an SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED event. yeah it moves, she's dynamic, keep up 🦋

if the window is created with any of the SDL_WINDOW_OPENGL or SDL_WINDOW_VULKAN flags, then the corresponding LoadLibrary function (SDL_GL_LoadLibrary or SDL_Vulkan_LoadLibrary) is called, and the corresponding UnloadLibrary function is called by SDL_DestroyWindow(). it's a whole situationship, they come as a pair.

if SDL_WINDOW_VULKAN is specified and there isn't a working Vulkan driver, SDL_CreateWindow() will fail, because SDL_Vulkan_LoadLibrary() will fail. chain reaction, bestie 💀

if SDL_WINDOW_METAL is specified on an OS that does not support Metal, SDL_CreateWindow() will fail.

if you intend to use this window with an SDL_Renderer, you should use SDL_CreateWindowAndRenderer() instead of this function, to avoid window flicker. fr fr, save yourself the flicker.

on non-Apple devices, SDL requires you to either not link to the Vulkan loader or link to a dynamic library version. this limitation may be removed in a future version of SDL. so like, it's a thing for now, iykyk.

---

🎀 FUNCTION PARAMETERS 🎀

• title — the title of the window, in UTF-8 encoding.
• w — the width of the window.
• h — the height of the window.
• flags — 0, or one or more SDL_WindowFlags OR'd together.

---

⭐ RETURN VALUE ⭐

returns the window that was created, or NULL on failure 😭 — in which case, call SDL_GetError() for more information. she'll tell you what went wrong.

---

🧚 THREAD SAFETY 🧚

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

---

🌈 AVAILABILITY 🌈

this function is available since SDL 3.2.0.

---

💜 SEE ALSO 💜

• SDL_CreateWindowAndRenderer(3)
• SDL_CreatePopupWindow(3)
• SDL_CreateWindowWithProperties(3)
• SDL_DestroyWindow(3)

---

and that's the whole page, bestie 🫶 this lil drop is from Simple Directmedia Layer, version SDL 3.4.18, and yeah it's SDL_CreateWindow(3) — go make a window, you're gonna eat 💅✨🍓