SDL | Usage: [options]

This post introduces useful functions, structures, and constants in the SDL 2.0 API. It covers basic details such as return values and parameters of functions and names and data types of members of structs. For more detailed info, visit the links in the references.

Initialization

To use SDL 2.0 in your program, call the SDL_Init() function.^[1]

int SDL_Init(Uint32 flags);

Returns: 0 if successful or a negative error code if unsuccessful

The flags parameter specifies which subsystems should be initialized. It can be one or more of the following:

SDL_INIT_TIMER: timer subsystem
SDL_INIT_AUDIO: audio subsystem
SDL_INIT_VIDEO: video subsystem; automatically initializes the events subsystem
SDL_INIT_JOYSTICK: joystick subsystem; automatically initializes the events subsystem
SDL_INIT_HAPTIC: haptic (force feedback) subsystem
SDL_INIT_GAMECONTROLLER: controller subsystem; automatically initializes the joystick subsystem
SDL_INIT_EVENTS: events subsystem
SDL_INIT_EVERYTHING: all of the above subsystems
SDL_INIT_NOPARACHUTE: compatibility; this flag is ignored

Use a logical OR to use more than one flag, e.g.,

SDL_Init(SDL_INIT_VIDEO | SDL_INIT_AUDIO);

There is another function called SDL_InitSubSystem() that is identical to SDL_Init() in all but the name of the function.^[2]

Shutdown Cleanup

Call the SDL_Quit() function to perform final cleanup of all initialized subsystems.

void SDL_Quit(void);

This function can be used with atexit() to ensure that it is called when your program shuts down.^[3]

atexit(SDL_Quit);

Error Handling

SDL_GetError()

SDL_GetError() gets a message about the last error on the current thread and returns it as a string.^[4]

const char* SDL_GetError(void);

Returns: a string with information about the last error, or an empty string if there hasn't been an error since the last call to SDL_ClearError()

SDL_GetError() should be called if an SDL function signals that an error occurred. It should not be used to determine whether an error occurred since some SDL functions will set an error string even when successful.

SDL_ClearError()

SDL_ClearError() clears the error message for the current thread.^[5]

void SDL_ClearError(void);

SDL_SetError()

SDL_SetError() sets the SDL error message for the current thread. Its arguments work similarly to printf().^[6]

int SDL_SetError(SDL_PRINTF_FORMAT_STRING const char *fmt, …);

Returns: always returns -1

fmt is the desired error message. It is a printf-style format string.

... means that there can be any number of additional parameters matching % tokens in the fmt string.

Example code:

[6]
if (error_code) {
    return SDL_SetError("This operation has failed: %d", error_code);
}

Creating and Destroying Windows

SDL_CreateWindow()

SDL_CreateWindow() createDL_CreateWindow()s a new window with the given title, size, and position.^[7]

SDL_Window *SDL_CreateWindow(const char *title,
int x, int y, int w,
int h, Uint32 flags);

Returns: on success, a pointer to the new window instance created; on failure, NULL

title is a string that will be the title of the window.
x is the x position of the window, SDL_WINDOWPOS_CENTERED, or SDL_WINDOWPOS_UNDEFINED.
y is the y position of the window, SDL_WINDOWPOS_CENTERED, or SDL_WINDOWPOS_UNDEFINED.
w is the width of the window in screen coordinates.
h is the height of the window in screen coordinates.
flags is either 0 or one or more of the following SDL_WindowFlags OR’d together:

SDL_WINDOW_FULLSCREEN: fullscreen window
SDL_WINDOW_FULLSCREEN_DESKTOP: fullscreen window at desktop resolution
SDL_WINDOW_OPENGL: window usable with an OpenGL context
SDL_WINDOW_VULKAN: window usable with a Vulkan instance
SDL_WINDOW_METAL: window usable with a Metal instance
SDL_WINDOW_HIDDEN: window is not visible
SDL_WINDOW_BORDERLESS: no window decoration
SDL_WINDOW_RESIZABLE: window can be resized
SDL_WINDOW_MINIMIZED: window is minimized
SDL_WINDOW_MAXIMIZED: window is maximized
SDL_WINDOW_INPUT_GRABBED: window has grabbed input focus
SDL_WINDOW_ALLOW_HIGHDPI: window should be created in high-DPI mode if supported (>= SDL 2.0.1)

SDL_DestroyWindow

SDL_DestroyWindow() destroys the given window instance.^[8]

void SDL_DestroyWindow(SDL_Window *window);

window is the window to destroy. If window is NULL, the SDL error message will be set.

Getters and Setters

You can associate a name and other data with a window instance using SDL_SetWindowData().^[9]

void* SDL_SetWindowData(SDL_Window *window,
const char *name,
void *userdata);

Returns: the previous data associated with name

window is the window to associate with the pointer to the data.
name is the name of the pointer to the data.
userdata is the associated pointer to the data.

You can then retrieve that data using SDL_GetWindowData().^[10]

void* SDL_GetWindowData(SDL_Window *window,
const char *name);

Returns: the data associated with name

window is the window to query.
name is the name of the pointer to the data.

Each window instance has an ID associated with it, which is used by SDL_WindowEvent structure. To work with that structure, it is often necessary to be able to convert from a window instance to its ID and vice versa. Fortunately, there are functions to facilitate both conversions.

SDL_GetWindowID() retrieves the ID of the given window.^[11]

Uint32 SDL_GetWindowID(SDL_Window *window);

Returns: the ID of the window on success or 0 on failure

window is the window to query.

SDL_GetWindowFromID() retrieves the window instance with the given ID.^[12]

SDL_Window *SDL_GetWindowFromID(Uint32 id);

Returns: the window associated with id or NULL if it doesn't exist

id is the ID of the window.

References

Stay tuned for part 2.

Usage: [options]

Tag Archives: SDL

Using SDL Part 1