SDL 3.2
Function reference
Every function used in the lessons, explained one by one: what it does, what each parameter means, which values it accepts, common mistakes and a short example.
Init, errors & main callbacks
SDL_InitSDL 3.2Starts the parts of SDL you ask for (video, audio, gamepads…). The first SDL call of a program.SDL_InitSubSystemSDL 3.2Starts more subsystems after SDL is already running, e.g. audio only when the game reaches its menu.SDL_QuitSDL 3.2Shuts down every SDL subsystem that is still running. The last SDL call of a program.SDL_GetErrorSDL 3.2Returns a readable message about the last SDL error on this thread.SDL_SetHintSDL 3.2Changes one of SDL's many fine-tuning options, given as a name and a text value.SDL_freeSDL 3.2Frees memory that an SDL function allocated and handed to you.SDL_AppInitSDL 3.2A function YOU write: SDL calls it once at startup when you use the main callbacks instead of main().SDL_AppIterateSDL 3.2A function YOU write: SDL calls it once per frame to update and draw.SDL_AppEventSDL 3.2A function YOU write: SDL calls it once for every event (key, mouse, quit…).SDL_AppQuitSDL 3.2A function YOU write: SDL calls it once at the end, so you can free everything.
Logging & time
SDL_LogSDL 3.2Prints a message, printf-style, to wherever this platform shows logs.SDL_LogInfoSDL 3.2Logs an informational message in a category of your choice.SDL_LogErrorSDL 3.2Logs an error message in a category. Errors are shown at the default levels.SDL_SetLogPrioritySDL 3.2Sets the lowest priority that is still printed for one category.SDL_GetTicksSDL 3.2Milliseconds since SDL started. Simple, but too coarse to time a frame.SDL_GetTicksNSSDL 3.2Nanoseconds since SDL started. The clock to compute deltaTime with.SDL_GetPerformanceCounterSDL 3.2Reads the finest timer the system has, in ticks of unknown size. For profiling.SDL_GetPerformanceFrequencySDL 3.2How many SDL_GetPerformanceCounter ticks make one second on this machine.SDL_DelayNSSDL 3.2Sleeps for at least the given number of nanoseconds.
Windows & displays
SDL_CreateWindowSDL 3.2Opens a window. Flags choose how it can be drawn into (OpenGL, Vulkan…) and how it behaves.SDL_DestroyWindowSDL 3.2Closes a window and frees it.SDL_GetWindowSizeSDL 3.2Reads the size of the window's content area in WINDOW coordinates (the units of mouse events).SDL_GetWindowSizeInPixelsSDL 3.2Reads the size of the window's drawing area in real PIXELS: what OpenGL, Vulkan and SDL_GPU draw into.SDL_SetWindowTitleSDL 3.2Changes the text in the window's title bar.SDL_SetWindowPositionSDL 3.2Asks to move the window. SDL_WINDOWPOS_CENTERED centers it on its display.SDL_GetWindowDisplayScaleSDL 3.2The scale at which content in this window should be drawn, e.g. 2.0 on a Retina screen or at 200%.SDL_GetDisplayForWindowSDL 3.2Tells which monitor (display) the window is on.SDL_GetCurrentDisplayModeSDL 3.2Reads a monitor's current resolution and refresh rate.SDL_GetWindowFlagsSDL 3.2Reads the window's current state as flags: minimized, full screen, has focus…
Events, keyboard & mouse
SDL_PollEventSDL 3.2Takes the next event out of the queue, if there is one. Never waits.SDL_WaitEventSDL 3.2Sleeps until an event arrives, then takes it out. For tools that only redraw on input.SDL_PushEventSDL 3.2Adds an event to the queue yourself. Safe from any thread: the way a worker thread talks to the main loop.SDL_RegisterEventsSDL 3.2Reserves event type numbers for your own events, so they never clash with SDL's or a library's.SDL_GetKeyboardStateSDL 3.2Returns SDL's array of key states: `keys[SDL_SCANCODE_W]` is true while W is held.SDL_GetMouseStateSDL 3.2Reads where the mouse is (in the focused window) and which buttons are held.SDL_SetWindowRelativeMouseModeSDL 3.2Hides and locks the cursor and reports pure mouse movement. For first-person cameras.SDL_StartTextInputSDL 3.2Turns on text input for a window: SDL starts sending SDL_EVENT_TEXT_INPUT with typed characters.SDL_StopTextInputSDL 3.2Turns text input off again: no more SDL_EVENT_TEXT_INPUT, and the on-screen keyboard closes.
Gamepads
SDL_OpenGamepadSDL 3.2Opens a connected gamepad so you can read its sticks and buttons.SDL_CloseGamepadSDL 3.2Closes a gamepad you opened, e.g. when it is unplugged.SDL_GetGamepadAxisSDL 3.2Reads a stick or trigger position as a 16-bit integer.SDL_GetGamepadButtonSDL 3.2Asks whether a gamepad button is held right now.SDL_RumbleGamepadSDL 3.2Makes the gamepad vibrate for a given time.
2D renderer
SDL_CreateWindowAndRendererSDL 3.2Creates a window and its 2D renderer in one call. The shortest start for a 2D program.SDL_CreateRendererSDL 3.2Creates a 2D renderer for a window: the object that draws rectangles, lines and textures with the GPU.SDL_DestroyRendererSDL 3.2Destroys a renderer and every texture it created.SDL_GetRendererNameSDL 3.2Tells which backend the renderer ended up using, e.g. "direct3d11" or "metal".SDL_SetRenderVSyncSDL 3.2Turns vsync on or off for the renderer: whether SDL_RenderPresent waits for the monitor's refresh.SDL_SetRenderLogicalPresentationSDL 3.2Lets you draw at a fixed size (e.g. 640×360) and have SDL scale it to whatever the window is.SDL_RenderCoordinatesFromWindowSDL 3.2Converts a window position (e.g. the mouse) into the renderer's drawing coordinates.SDL_SetRenderTargetSDL 3.2Makes the renderer draw into a texture instead of the window. NULL switches back to the window.
Drawing shapes
SDL_SetRenderDrawColorSDL 3.2Chooses the colour for the next clear, rectangle, line or point.SDL_SetRenderDrawBlendModeSDL 3.2Chooses how shapes drawn with the draw colour mix with what is already there (e.g. transparency).SDL_RenderClearSDL 3.2Fills the whole render target with the current draw colour. The first draw call of every frame.SDL_RenderPresentSDL 3.2Shows the finished frame on screen. Nothing you drew is visible before this call.SDL_RenderFillRectSDL 3.2Draws a filled rectangle in the current draw colour.SDL_RenderRectSDL 3.2Draws only the outline of a rectangle, one pixel thick.SDL_RenderLineSDL 3.2Draws a one-pixel line between two points.SDL_RenderPointSDL 3.2Draws a single pixel in the current draw colour.SDL_RenderGeometrySDL 3.2Draws triangles from your own vertices, each with a position, a colour and texture coordinates.
Textures & surfaces
SDL_CreateTextureFromSurfaceSDL 3.2Copies an image from CPU memory (a surface) into a texture the renderer can draw.SDL_CreateTextureSDL 3.2Creates an empty texture: to draw into (target) or to fill with your own pixels every frame (streaming).SDL_DestroyTextureSDL 3.2Frees a texture's GPU memory.SDL_DestroySurfaceSDL 3.2Frees a surface (an image in CPU memory). SDL2 called it SDL_FreeSurface.SDL_RenderTextureSDL 3.2Draws a texture, or part of it, into a rectangle on screen. The sprite-drawing call (SDL_RenderCopy in SDL2).SDL_RenderTextureRotatedSDL 3.2Like SDL_RenderTexture, plus rotation around a point and horizontal/vertical mirroring.SDL_SetTextureColorModSDL 3.2Tints a texture: every pixel's colour is multiplied by (r, g, b) / 255 when drawn.SDL_SetTextureAlphaModSDL 3.2Makes a whole texture more transparent when drawn: alpha is multiplied by alpha / 255.SDL_SetTextureBlendModeSDL 3.2Chooses how the texture mixes with what is behind it: transparency, additive glow, none…SDL_SetTextureScaleModeSDL 3.2Chooses how a texture is filtered when drawn bigger or smaller: smooth (linear) or sharp pixels (nearest).SDL_LockTextureSDL 3.2Gives you a pointer to write a STREAMING texture's pixels directly from the CPU.SDL_UnlockTextureSDL 3.2Finishes writing a locked texture and uploads the new pixels.
Audio
SDL_OpenAudioDeviceStreamSDL 3.2The one-call way to play sound: opens a device and gives you a stream already connected to it.SDL_ResumeAudioStreamDeviceSDL 3.2Unpauses the device behind a stream opened with SDL_OpenAudioDeviceStream, so sound starts flowing.SDL_PutAudioStreamDataSDL 3.2Queues sound samples into a stream. SDL copies them and plays them in order.SDL_DestroyAudioStreamSDL 3.2Frees a stream. If it came from SDL_OpenAudioDeviceStream, its device closes too.SDL_LoadWAVSDL 3.2Loads a .wav file: fills in its format and gives you a buffer with the samples.SDL_OpenAudioDeviceSDL 3.2Opens an audio device you can bind several streams to. SDL mixes them for you.SDL_CreateAudioStreamSDL 3.2Creates a standalone audio stream that converts from one format to another.SDL_BindAudioStreamSDL 3.2Connects a stream to an opened device, so the device plays what you put into the stream.SDL_SetAudioStreamGainSDL 3.2Sets a stream's volume: 1.0 unchanged, 0.5 half, 0.0 silent.SDL_ResumeAudioDeviceSDL 3.2Unpauses a device paused with SDL_PauseAudioDevice.
Files & storage
SDL_GetBasePathSDL 3.2The folder the program was started from (next to the executable). Where your read-only assets live.SDL_GetPrefPathSDL 3.2A folder where your program may write: settings, save games, logs. Created if missing.SDL_LoadFileSDL 3.2Reads a whole file into memory in one call.SDL_OpenTitleStorageSDL 3.2Opens the game's own read-only files through SDL's storage API, which also works on consoles.SDL_OpenUserStorageSDL 3.2Opens the player's writable storage (save games, settings) through SDL's storage API.
OpenGL & Vulkan windows
SDL_GL_SetAttributeSDL 3.2Requests one property of the OpenGL context and framebuffer (version, profile, depth bits…) BEFORE the window is created.SDL_GL_CreateContextSDL 3.2Creates an OpenGL context for an OpenGL window and makes it current.SDL_GL_DestroyContextSDL 3.2Destroys an OpenGL context (SDL_GL_DeleteContext in SDL2).SDL_GL_GetProcAddressSDL 3.2Finds an OpenGL function in the driver by name. Handed to glad to load them all.SDL_GL_SetSwapIntervalSDL 3.2Turns vsync on or off for the current OpenGL context.SDL_GL_SwapWindowSDL 3.2Shows the OpenGL frame you just drew (swaps the back and front buffers).SDL_Vulkan_GetInstanceExtensionsSDL 3.2Lists the Vulkan instance extensions needed to show images in an SDL window on this system.SDL_Vulkan_CreateSurfaceSDL 3.2Creates the VkSurfaceKHR for an SDL window: the bridge between Vulkan and the window.
GPU: device & frame
SDL_CreateGPUDeviceSDL 3.2Opens the GPU through SDL's modern 3D API, which runs on Vulkan, Direct3D 12 or Metal.SDL_DestroyGPUDeviceSDL 3.2Destroys the GPU device. Release everything created from it first.SDL_GetGPUDeviceDriverSDL 3.2Tells which backend the device uses: "vulkan", "direct3d12" or "metal".SDL_GetGPUShaderFormatsSDL 3.2Tells which shader formats the chosen backend accepts, so you load the right file.SDL_ClaimWindowForGPUDeviceSDL 3.2Connects a window to the GPU device by creating its swapchain, so you can draw into it.SDL_AcquireGPUCommandBufferSDL 3.2Gets a command buffer: a list you record GPU work into, then submit all at once.SDL_WaitAndAcquireGPUSwapchainTextureSDL 3.2Gets this frame's window image to draw into, waiting if all of them are still busy.SDL_SubmitGPUCommandBufferSDL 3.2Sends everything recorded in the command buffer to the GPU (and presents the swapchain image, if one was acquired).SDL_BeginGPURenderPassSDL 3.2Starts a render pass: says which textures you draw into and how to treat their old contents.SDL_EndGPURenderPassSDL 3.2Ends a render pass. After it you may start another pass or submit.SDL_BindGPUGraphicsPipelineSDL 3.2Selects the pipeline (shaders + fixed settings) for the next draw calls in this pass.SDL_BindGPUVertexBuffersSDL 3.2Tells the next draws which GPU buffers to read vertices from.SDL_DrawGPUPrimitivesSDL 3.2Draws: runs the bound pipeline over num_vertices vertices, num_instances times.
GPU: shaders, pipelines & buffers
SDL_CreateGPUShaderSDL 3.2Loads one compiled shader (vertex or fragment) into the device.SDL_CreateGPUGraphicsPipelineSDL 3.2Builds a pipeline: shaders, vertex layout, primitive type, blending and target formats, fixed together.SDL_CreateGPUBufferSDL 3.2Creates a buffer in GPU memory for vertices, indices or shader data. It starts empty.SDL_ReleaseGPUBufferSDL 3.2Frees a GPU buffer as soon as the GPU has finished using it.SDL_CreateGPUTransferBufferSDL 3.2Creates a staging buffer the CPU CAN write into, used to move data to (or from) the GPU.SDL_MapGPUTransferBufferSDL 3.2Gives you a CPU pointer into a transfer buffer, so you can memcpy your data in.SDL_UnmapGPUTransferBufferSDL 3.2Ends CPU access to a mapped transfer buffer. Required before copying from it.SDL_BeginGPUCopyPassSDL 3.2Starts a copy pass: the part of a command buffer where data moves between buffers and textures.SDL_UploadToGPUBufferSDL 3.2Records a copy from a transfer buffer into a GPU buffer.SDL_EndGPUCopyPassSDL 3.2Ends a copy pass.SDL_ReleaseGPUTransferBufferSDL 3.2Frees a transfer buffer as soon as it is safe (after the GPU finished copying from it).