Simple DirectMedia Layer is a cross playform development library designed to provide low level access to audio, keyboad, mouse, joystick, and graphics hardware via OpenDGL and Direct3D.


SDL Documentation

Useful Information

On Initalization

SDL begins with initalization, SDL_Init() must be called before other SDL functions. The role of SDL_Init() is to properly initalize the SDL Library and start each of the various subsystems requested with the call. The File I/O and Threading subsystems are initalized by default. To initalize other subsystems you must specifically call them. Multiple subsystems may be or'd with the OR operator in C, '|'. SDL_Init may fail if SDL_main() has not been defined as the entry for the program on certain operating systems. Calling SDL_SetMainReady() prior to SDL_Init() will circumvent this failure condition -- however, users should be careful when calling SDL_SetMainReady() as improper initalization may cause crashes and hard to diagnose problems.

SDL_Quit() should be called before an SDL application exits safely, to shut down all the subsystems. It is not necessary to specifc individual subsystems using SDL_Quit(), it will automatically shut down all active subsystems.

A window can be created by using SDL_CreateWindow(), which in term has a series of arguments that define the window position x and y, height and width, and the window state (shown, opengl usable with opengl windows, vulkan, ect.) SDL_WINDOW_SHOWN is ignored by SDL_CreateWindow(). The SDL_Window is implicity shown if WSDL_WINDOW_HIDDEN is not set. SDL_WINDOW_SHOWN may be quiered later using SDL_GetWindowsFlags(). Error checking is important, always check to see if the window is NULL or is not NULL. And always remember to destroy your window and ensure its destroyed by setting it to NULL when you're finished.

SDL_CreateRenderer() is a function that takes the data of your created window, the index of the rendering driver (-1 to initalize the first one supporting the requested flags), and 0, one, or more SDL_RendererFlags which can be OR'd together. Such as SDL_RENDERER_SOFTWARE, and SDL_RENDERER_ACCELERATED.

SDL_Surface and SDL_Texture are ways to represent pixel data. SDL_Surface is a struct that contains all raw pixel data along with some meta-information like size and pixel format. Since it's just raw pixel data, it's not optimized in anyway and should be avoided when rendering. SDL_Texture contains an efficient / optimized representation of the pixel data. SDL_Texture, it was introdued in SDL@.0 and enables hardware rendering.

On Events

The core of any application developed in SDL is the "application loop", this loop keeps running while the application is active, it's also called the "main loop". Typically at the top of the main loop, we have our event loop which processes the event queue until it is empty. The event queue will store events, such as key presses, in the order the events originally occured in, waiting to be processed. In order to find out what events occured so you can process them, you poll the event queue to get the most recent event by calling SDL_PollEvent().

SDL_PollEvent() takes the most recent event from the event queue and puts the data from the event into the SDL_Event we passed into the function. SDL_PollEvent will keep taking events off the queue until the queue is empty and returns 0. If an event from the event queue is an SDL_QUIT event, we set the quit flag to true so we can exit the application.