[SDL] SDL 2.0: Evaluating API Usability (Long)

[Ryan C. Gordon]

Since I'm an SDL user as much as an SDL developer, I figured I'd fill 
this out.

> --------------
> CLASSIFICATION
> --------------
> EDUCATION - One of:
> 	- SELF-TAUGHT (No formal programming teaching / qualifications)

(I have an undergraduate degree, but it's not in Computer Sciences.)

> EXPERIENCE - One of:
> 	- GAME DEV professional (full-time) game developer with 2 or more years
> experience.


> 1. What do you like about the presentation of the SDL APIs? Which tasks
> do you find particularly easy, straightforward or simple? Which APIs do
> you feel work really well for the task they are intended for?

SDL_SetVideoMode() is the best thing, ever. I don't understand why every 
other platform takes dozens of lines of code to accomplish the same thing.

Good design either keeps the API dirt simple, or provides the "dirt 
simple" API layered over the more low-level one, for times when 
dirt-simple would be too limiting for legitimate cases...otherwise, you 
end up with the same boilerplate cut-and-paste in every application to 
build a DirectX window, or a GL context, etc.

I like that the API worked very well as an abstraction layer...SDL has 
shown up in some pretty exotic locations and retained source compatibility.

I think the philosophy of add-on libraries worked out, since it lets us 
throw away pieces that didn't work so well (SDL_mixer, SDL_net, 
SDL_image, etc, could all just be superceded by a totally different 
library...those that want the old stuff can still use it, since it 
doesn't break the SDL API abstractions to get the job done...also, it 
removes the bloat from the base library...I think SDL_rtf is awesome, 
but I'm happy it's not part of SDL itself. Basically, it gives us 
evolutionary wiggle room.

> 2. What DON'T you like about the presentation of the SDL APIs? Which
> task do you find particularly difficult, awkward or confusing? Which
> APIs do you feel make the task more difficult? What are your pet hates?

I think most of them are resolved for 1.3.

Probably the biggest killer in 1.2, from an API stance, was that the API 
dictates that we have to keep internal state for a single window...which 
led to an implementation with the same attitude...so we couldn't just 
add multiwindow support to the library. Not only would we need a whole 
new set of public functions, but we'd have to flush out a lot of 
internal code assumptions inside SDL.

The best parallel I could give is if the ANSI C functions had these 
signatures:

     int fopen(const char *fname, const char *mode);  // 0 on success!
     void fclose(void);

...what, you access more than one file at a time?   :)


I think there are a few things that are past their lifespan in the API: 
CD audio, for example.

> 3. How do you find error handling? What do you like about it? What don't
> you like about it? Are there particular examples of error handling in
> other APIs that you prefer? Why?

I can't ever find an error handling API that I like...my mind changes 
from day to day, but SDL seems to be least irritating in most cases:

- easy to get information in a single return value
- call a function to get a human-readable string.

The "human readable string" part is where it breaks down for 
me...someone has to deal with managing that memory (would you be happy 
if sin(NaN) called malloc())?, what do you do about localizing that 
string? What about character encodings? How do you show this error to 
the user when you don't know what might come out of the library (be it 
geek-speak or a curse word)?

As a resident of the en_US locale that likes to read debug output, it 
works for me, but I think that the C runtime "errno" concept works 
better (not the global variable. I mean having a giant enum of all 
possible errors)...then again, lots of meaning gets overloaded on some 
of those errno values, and there are a LOT of subtle ways SDL can fail.

Like I said, I haven't found anything I like anywhere.

> 4. If you use / have used SDL with C++, please answer the following:
> 	a. Do you wrap SDL in C++ class(es)?
> 		- If not, why not?
> 		- If so, what difficulties / gotchas have you encountered? Which APIs
> have been particularly troublesome?

I have called it from C++ classes that implement an abstraction:

    // one of these for each targeted platform.
    class SDLVideo : public Video
    {
         create_window();
         blit();
         get_mouse_xy();
    };  // or whatever.

But I haven't ever tried to do a real formal C++-ification of SDL. 
Frankly, I find that sort of thing to be a complete waste of time. It 
adds complexity for no obvious payout.

> 	b. Have you tried using exceptions in your SDL code? Which approach(es)
> have you used? Did you give-up and go back to traditional (C-style)
> error handling and if so, why?

C++ error handling only makes life harder, in my experience. I avoid it 
whenever possible. It makes it harder to walk through programs, it risks 
memory leaks...it's a structured GOTO, basically.

Despite working with it all day (maybe BECAUSE of working with it all 
day) I'm somewhat anti-C++. I probably skew the results.  :)

--ryan.