I’ve been using and reading some SDL code for a month or 2 now…
I’m “often” seeing code that calls something like SDL_SetRenderDrawColor and just moves on. Not just for that though, another one that comes to mind is SDL_SetRenderDrawBlendMode.
For the first weeks, i just thought that those were just bad-ish code not checking errors. However, for some of those functions, like the set render draw color, from looking at the source code, it seems like they won’t error unless the caller pass in invalid parameters.
Code:
int
SDL_SetRenderDrawColor(SDL_Renderer * renderer,
Uint8 r, Uint8 g, Uint8 b, Uint8 a)
{
CHECK_RENDERER_MAGIC(renderer, -1);
renderer->r = r;
renderer->g = g;
renderer->b = b;
renderer->a = a;
return 0;
}
It pretty much checks if parameters are valid, do the thing, and return 0 indicating success. A fair number of other functions are also like that.
It’s pretty tedious to have dozens and dozens conditionals for every little call that I know the parameters will be valid (valid at least according to the check done by this CHECK_RENDERER_MAGIC macro). So, I’m wondering about if it’d be interesting to have some explanation in a wiki page for a function saying “errors only on invalid parameters” so that callers can know that if they can guarantee they have valid parameters, error checking won’t be needed for things like (for example) getting the alpha mod out of a texture.
side-note:
Code:
int
SDL_GetTextureAlphaMod(SDL_Texture * texture, Uint8 * alpha)
{
CHECK_TEXTURE_MAGIC(texture, -1);
if (alpha) {
*alpha = texture->a;
}
return 0;
}
SDL_GetTextureAlphaMod actually makes the API a bit less clear because of output parameters even though it’s not necessary in here.
/side-note
I imagine the design decision to make these many things possibly fail has to do with “the future”, as in “things could change in the future and then, all of the sudden, SDL_GetTextureAlphaMod will need to signal errors”. But given SDL is more than a decade old, I guess accumulated experience with earlier versions could help in here finding things like this that could realistic change in the future and things that are unlikely to do so.
And just so we stay on point, I’m not asking for an API change. I’m asking about if it’d be interesting to place in the wiki indicators saying that a given function will only error on invalid parameters. I’d be happy, also, to help add those comments in the wiki.
Thanks.