SDL Programming

From wikiPodLinux

First of all, if you haven't built a working iPod SDL, do so before reading this page.

With SDL available for the iPod, some applications should be much easier to port. However, the iPod SDL implementation has a few idiosyncracies that will be detailed below.

Table of contents

1 Setting the Video Mode 2 2-bit Color 3 The Mouse 4 Events 5 The Log

Setting the Video Mode

On a monochrome iPod, you'll need to call SDL_SetVideoMode() with bpp as 8. (Not 2!) On an iPod photo, nano, or video, you would correctly set bpp to 16. In order to set the correct mode for your iPod, use a function like this one.

// Set exactly one of the following macros to 1; this will
// determine what mode is set if you're running this function
// on a desktop computer in X.
#define X11_IPODSTD   1
#define X11_IPODMINI  0
#define X11_IPODPHOTO 0

SDL_Surface *SetiPodVideoMode() 
{
    SDL_Rect **rs = SDL_ListModes (0, SDL_SWSURFACE);
    int w, h, bpp;
    SDL_Surface *scrn;
    
    if (rs == (SDL_Rect **)-1) { // any mode
        if (X11_IPODSTD) {
            w = 160; h = 128; bpp = 8;
        } else if (X11_IPODMINI) {
            w = 138; h = 110; bpp = 8;
        } else {
            w = 220; h = 176; bpp = 16;
        }
    } else { // iPod mode
        w = (*rs)->w;
        h = (*rs)->h;
        if ((w == 220) && (h == 176))
            bpp = 16;
        else
            bpp = 8;
    }
   
    scrn = SDL_SetVideoMode (w, h, bpp, SDL_SWSURFACE);
    return scrn;
}

You can now check scrn->w, scrn->h, scrn->format->BitsPerPixel to see what format you got.

2-bit Color

Since the iPod standard only supports 4 colors (white, light grey, dark grey, black), and SDL supports surfaces with, at minimum, a 256-color palette, we had to cheat a bit. The iPod video driver sets an unchangeable palette of constant repetitions of these four colors for the screen. (Yes, 0 is white.) To convert other surfaces to this palette, use a function like this one.

void palettize (SDL_Surface *surf)
{
    SDL_Color colors[] = { {255,255,255}, {160,160,160}, {80,80,80}, {0,0,0} };

    for (int grp = 0; grp < 256; grp += 4) {
        SDL_SetColors (surf, colors, grp, 4);
    }

    SDL_FillRect (surf, 0, 0);
}

Note that "light gray" is not exactly 66% RGB, nor is "dark gray" exactly 33%. (That would be 170 and 85 instead of 160 and 80.)

The Mouse

SDL insists on having a mouse, even if it doesn't make sense. Unless you hide the cursor, it'll show up in the upper left corner of your screen. So be sure to execute

SDL_ShowCursor (SDL_DISABLE);

just after setting the video mode.

Events

You'll only ever receive two events from the iPod: SDL_KEYDOWN and SDL_KEYUP. The keys are

• SDLK_w is left/previous/rewind;
• SDLK_f is right/next/fast forward;
• SDLK_m is up/menu;
• SDLK_d is down/play/pause;
• SDLK_r is scroll wheel right;
• SDLK_l is scroll wheel left;
• SDLK_h is hold; and
• SDLK_RETURN is center/action/enter.

The scroll wheel events are roughly 100 to a full rotation. You may want to modulate this in your program, only doing something every third or every fifth scroll.

Key repeat should work as expected.

The Log

If SDL isn't working as expected, create the file /etc/sdlpod.log on the iPod (just touch it) and messages will be written there. If you're getting a blank screen, the log should explain why. It will also list the detected generation and LCD dimensions; any keys pressed; and a whole lot of "Selecting" messages :-) Note that with the log file enabled, SDL is very slow, so events (especially scroll events) will take a long time (as much as 200ms!) to process.