Failure reasons

SDL Development
1

I’m calling into SDL from a higher-level Swift framework and I’m trying to understand when and why certain SDL functions may fail. The API docs usually say “returns 0 on success or a negative error code on failure; call SDL_GetError() for more information” with no information about when or why a failure may occur.

Other than reading the source code for every single function, how am I supposed to understand the reasons for failure? In particular, I’m wondering if I can skip error checking on some functions because my code can, for example, guarantee that all pointers are non-null.

2

With something that works across multiple APIs on multiple platforms (and sometimes multiple drivers/backends on the same platform) it can be difficult to document every possible failure condition. Combinatorial explosion, etc. The possible failure reasons just for creating a window would be pages and pages if you include all supported platforms and video drivers.

Stuff like initialization and creation of objects should always be error checked. Something like SDL_RenderCopy() is probably safe to skip the error checking, though if you want a really bullet-proof system you should still do it.

3

Thanks @sjr

I’m mostly wondering about functions like SDL_SetRenderDrawColor and SDL_SetRenderDrawColor. If both SDL and the renderer are properly initialized, should this ever fail?

In the source code, I see there’s a check for a “magic” properly, but I can’t really see what that does.

4

SDL_SetRenderDrawColor isn’t capable of failing, so long as the renderer is valid.

If you have a bunch of calls that shouldn’t fail, but you want to make sure, you could always do the Swift equivalent of

int result = 0;
result |= SDL_Whatever();
result |= SDL_Whatever2();
...
result |= SDL_WhateverN();
if(result != 0) {
    LogError(result, __FUNCTION__, SDL_GetError());
}

The CHECK_RENDERER_MAGIC thing is just a macro that checks if the renderer is non-null, and then checks to see if it’s magic pointer has been set to the address of a private variable inside SDL_render.c (this makes sure the function has been passed an actual SDL renderer, rather than some random non-null value).