[转载]SDL Guide 中文译版

SDL即Simple DirectMedia Layer，类似DirectX，是完整的游戏、多媒体开发包，但不同的是它跨越几乎所有的平台，有各种语言的接口，多种语言的文档，而这一切都是广大志愿者完成的。目前扩展部分还没有正式的文档，以下为核心部分文档的向导部分。

序言

关于SDL

SDL为方便制作能跨跃Linux、BSD、MacOS、Win32和BeOS平台，使用本地高性能媒体接口，并且让您可以只需使用一份源代码级API而设计。SDL是相当低层的API，但使用它可以让你以极大的灵活性写出完全跨平台的程序。

 SDL:http://www.libsdl.org/

关于SDL文档

SDLdoc项目即要重新编写SDL文档并同步更新。项目组有使用SDL的志愿者组成。

最新版本可在http://sdldoc.sourceforge.net下载

谢启

Sam Lantinga, [e-mail]

Martin Donlon, [e-mail]

Mattias Engdeg?rd

Julian Peterson

Ken Jordan

Maxim Sobolev

Wesley Poole

Michael Vance

Andreas Umbach

Andreas Hofmeister

---

第一章 基础

初始化

SDL由八个子系统组成——音频、CDROM、事件处理、文件I/O、游戏杆、线程、记时器和视频。使用前必须调用SDL_Init或SDL_InitSubSystem初始化。SDL_Init必须早于其他所有SDL调用，它将自动初始化事件处理、文件I/O和线程子系统，并根据参数选择启动其他子系统。例如，初始化缺省和视频子系统：

SDL_Init(SDL_INIT_VIDEO);

初始化缺省、视频和记时器子系统：

SDL_Init(SDL_INIT_VIDEO | SDL_INIT_TIMER);

SDL_Init对应SDL_Quit（和SDL_QuitSubSystem）。SDL_Quit关闭所有子系统，必须在程序关闭前调用。

除此之外，我们还必须进行错误处理。很多SDL函数返回一个值指示成功与否。例如SDL_Init失败时返回-1。每当SDL出错时，错误信息被保存，并可用SDL_GetError取得。

例1-1 初始化SDL

#include "SDL.h"   /* All SDL App's need this */#include <stdio.h>int main() {        printf("Initializing SDL./n");        /* Initialize defaults, Video and Audio */    if((SDL_Init(SDL_INIT_VIDEO|SDL_INIT_AUDIO)==-1)) {         printf("Could not initialize SDL: %s./n", SDL_GetError());        exit(-1);    }    printf("SDL initialized./n");    printf("Quiting SDL./n");        /* Shutdown all subsystems */    SDL_Quit();        printf("Quiting..../n");    exit(0);}
第二章 图像和视频
初始化SDL Video显示
视频是最常用的部分，也是SDL最完整的子系统。下面的初始化过程是每个SDL程序都要做的，即使可能有些不同。
例2-1 初始化视频
    SDL_Surface *screen;    /* Initialize the SDL library */    if( SDL_Init(SDL_INIT_VIDEO) < 0 ) {        fprintf(stderr,                "Couldn't initialize SDL: %s/n", SDL_GetError());        exit(1);    }    /* Clean up on exit */    atexit(SDL_Quit);        /*     * Initialize the display in a 640x480 8-bit palettized mode,     * requesting a software surface     */    screen = SDL_SetVideoMode(640, 480, 8, SDL_SWSURFACE);    if ( screen == NULL ) {        fprintf(stderr, "Couldn't set 640x480x8 video mode: %s/n",                        SDL_GetError());        exit(1);    }
初始化最佳视频模式
如果你希望某种色深（颜色数）但如果用户的显示器不支持也可以接受其他色深，使用加SDL_ANYFORMAT参数的SDL_SetVideoMode。您还可以用SDL_VideoModeOK来找到与请求模式最接近的模式。
例2-2 初始化最佳视频模式
    /* Have a preference for 8-bit, but accept any depth */    screen = SDL_SetVideoMode(640, 480, 8, SDL_SWSURFACE|SDL_ANYFORMAT);    if ( screen == NULL ) {        fprintf(stderr, "Couldn't set 640x480x8 video mode: %s/n",                        SDL_GetError());        exit(1);    }    printf("Set 640x480 at %d bits-per-pixel mode/n",           screen->format->BitsPerPixel);
读取并显示BMP文件
当SDL已经初始化，视频模式已经选择，下面的函数将读取并显示指定的BMP文件。
例2-3 读取并显示BMP文件
void display_bmp(char *file_name){    SDL_Surface *image;    /* Load the BMP file into a surface */    image = SDL_LoadBMP(file_name);    if (image == NULL) {        fprintf(stderr, "Couldn't load %s: %s/n", file_name, SDL_GetError());        return;    }    /*     * Palettized screen modes will have a default palette (a standard     * 8*8*4 colour cube), but if the image is palettized as well we can     * use that palette for a nicer colour matching     */    if (image->format->palette && screen->format->palette) {    SDL_SetColors(screen, image->format->palette->colors, 0,                  image->format->palette->ncolors);    }    /* Blit onto the screen surface */    if(SDL_BlitSurface(image, NULL, screen, NULL) < 0)        fprintf(stderr, "BlitSurface error: %s/n", SDL_GetError());    SDL_UpdateRect(screen, 0, 0, image->w, image->h);    /* Free the allocated BMP surface */    SDL_FreeSurface(image);}
直接在显示上绘图
下面两个函数实现在图像平面的像素读写。它们被细心设计成可以用于所有色深。记住在使用前要先锁定图像平面，之后要解锁。
在像素值和其红、绿、蓝值间转换，使用SDL_GetRGB()和SDL_MapRGB()。
例2-4 getpixel()
/* * Return the pixel value at (x, y) * NOTE: The surface must be locked before calling this! */Uint32 getpixel(SDL_Surface *surface, int x, int y){    int bpp = surface->format->BytesPerPixel;    /* Here p is the address to the pixel we want to retrieve */    Uint8 *p = (Uint8 *)surface->pixels + y * surface->pitch + x * bpp;    switch(bpp) {    case 1:        return *p;    case 2:        return *(Uint16 *)p;    case 3:        if(SDL_BYTEORDER == SDL_BIG_ENDIAN)            return p[0] << 16 | p[1] << 8 | p[2];        else            return p[0] | p[1] << 8 | p[2] << 16;    case 4:        return *(Uint32 *)p;    default:        return 0;       /* shouldn't happen, but avoids warnings */    }}
例2-5 putpixel()
/* * Set the pixel at (x, y) to the given value * NOTE: The surface must be locked before calling this! */void putpixel(SDL_Surface *surface, int x, int y, Uint32 pixel){    int bpp = surface->format->BytesPerPixel;    /* Here p is the address to the pixel we want to set */    Uint8 *p = (Uint8 *)surface->pixels + y * surface->pitch + x * bpp;    switch(bpp) {    case 1:        *p = pixel;        break;    case 2:        *(Uint16 *)p = pixel;        break;    case 3:        if(SDL_BYTEORDER == SDL_BIG_ENDIAN) {            p[0] = (pixel >> 16) & 0xff;            p[1] = (pixel >> 8) & 0xff;            p[2] = pixel & 0xff;        } else {            p[0] = pixel & 0xff;            p[1] = (pixel >> 8) & 0xff;            p[2] = (pixel >> 16) & 0xff;        }        break;    case 4:        *(Uint32 *)p = pixel;        break;    }}
例2-6 使用上面的putpixel()在屏幕中心画一个黄点
    /* Code to set a yellow pixel at the center of the screen */    int x, y;    Uint32 yellow;    /* Map the color yellow to this display (R=0xff, G=0xFF, B=0x00)       Note:  If the display is palettized, you must set the palette first.    */    yellow = SDL_MapRGB(screen->format, 0xff, 0xff, 0x00);    x = screen->w / 2;    y = screen->h / 2;    /* Lock the screen for direct access to the pixels */    if ( SDL_MUSTLOCK(screen) ) {        if ( SDL_LockSurface(screen) < 0 ) {            fprintf(stderr, "Can't lock screen: %s/n", SDL_GetError());            return;        }    }    putpixel(screen, x, y, yellow);    if ( SDL_MUSTLOCK(screen) ) {        SDL_UnlockSurface(screen);    }    /* Update just the part of the display that we've changed */    SDL_UpdateRect(screen, x, y, 1, 1);    return;
并用SDL和OpenGL
SDL可以在多种平台（Linux/X11, Win32, BeOS, MacOS Classic/Toolbox, MacOS X, FreeBSD/X11 and Solaris/X11）上创建和使用OpenGL上下文。这允许你在OpenGL程序中使用SDL的音频、事件、线程和记时器，而这些通常是GLUT的任务。
和普通的初始化类似，但有三点不同：必须传SDL_OPENGL参数给SDL_SetVideoMode；必须使用SDL_GL_SetAttribute指定一些GL属性（深度缓冲区位宽，帧缓冲位宽等）；如果您想使用双缓冲，必须作为GL属性指定
例2-7 初始化SDL加OpenGL
    /* Information about the current video settings. */    const SDL_VideoInfo* info = NULL;    /* Dimensions of our window. */    int width = 0;    int height = 0;    /* Color depth in bits of our window. */    int bpp = 0;    /* Flags we will pass into SDL_SetVideoMode. */    int flags = 0;    /* First, initialize SDL's video subsystem. */    if( SDL_Init( SDL_INIT_VIDEO ) < 0 ) {        /* Failed, exit. */        fprintf( stderr, "Video initialization failed: %s/n",             SDL_GetError( ) );        quit_tutorial( 1 );    }    /* Let's get some video information. */    info = SDL_GetVideoInfo( );    if( !info ) {        /* This should probably never happen. */        fprintf( stderr, "Video query failed: %s/n",             SDL_GetError( ) );        quit_tutorial( 1 );    }    /*     * Set our width/height to 640/480 (you would     * of course let the user decide this in a normal     * app). We get the bpp we will request from     * the display. On X11, VidMode can't change     * resolution, so this is probably being overly     * safe. Under Win32, ChangeDisplaySettings     * can change the bpp.     */    width = 640;    height = 480;    bpp = info->vfmt->BitsPerPixel;    /*     * Now, we want to setup our requested     * window attributes for our OpenGL window.     * We want *at least* 5 bits of red, green     * and blue. We also want at least a 16-bit     * depth buffer.     *     * The last thing we do is request a double     * buffered window. '1' turns on double     * buffering, '0' turns it off.     *     * Note that we do not use SDL_DOUBLEBUF in     * the flags to SDL_SetVideoMode. That does     * not affect the GL attribute state, only     * the standard 2D blitting setup.     */    SDL_GL_SetAttribute( SDL_GL_RED_SIZE, 5 );    SDL_GL_SetAttribute( SDL_GL_GREEN_SIZE, 5 );    SDL_GL_SetAttribute( SDL_GL_BLUE_SIZE, 5 );    SDL_GL_SetAttribute( SDL_GL_DEPTH_SIZE, 16 );    SDL_GL_SetAttribute( SDL_GL_DOUBLEBUFFER, 1 );    /*     * We want to request that SDL provide us     * with an OpenGL window, in a fullscreen     * video mode.     *     * EXERCISE:     * Make starting windowed an option, and     * handle the resize events properly with     * glViewport.     */    flags = SDL_OPENGL | SDL_FULLSCREEN;    /*     * Set the video mode     */    if( SDL_SetVideoMode( width, height, bpp, flags ) == 0 ) {        /*          * This could happen for a variety of reasons,         * including DISPLAY not being set, the specified         * resolution not being available, etc.         */        fprintf( stderr, "Video mode set failed: %s/n",             SDL_GetError( ) );        quit_tutorial( 1 );    }
OpenGL绘图
除了初始化，在SDL程序中使用OpenGL和其他情况基本相同，是同样函数和数据类型。但是如果您使用双缓冲，则必须用SDL_GL_SwapBuffers()来交换前后缓冲，而不是glxSwapBuffers()（GLX）或SwapBuffers()（Windows）。
例2-8 SDL和OpenGL
/* * SDL OpenGL Tutorial. * (c) Michael Vance, 2000 * [e-mail] * * Distributed under terms of the LGPL.  */#include <SDL/SDL.h>#include <GL/gl.h>#include <GL/glu.h>#include <stdio.h>#include <stdlib.h>static GLboolean should_rotate = GL_TRUE;static void quit_tutorial( int code ){    /*     * Quit SDL so we can release the fullscreen     * mode and restore the previous video settings,     * etc.     */    SDL_Quit( );    /* Exit program. */    exit( code );}static void handle_key_down( SDL_keysym* keysym ){    /*      * We're only interested if 'Esc' has     * been presssed.     *     * EXERCISE:      * Handle the arrow keys and have that change the     * viewing position/angle.     */    switch( keysym->sym ) {    case SDLK_ESCAPE:        quit_tutorial( 0 );        break;    case SDLK_SPACE:        should_rotate = !should_rotate;        break;    default:        break;    }}static void process_events( void ){    /* Our SDL event placeholder. */    SDL_Event event;    /* Grab all the events off the queue. */    while( SDL_PollEvent( &event ) ) {        switch( event.type ) {        case SDL_KEYDOWN:            /* Handle key presses. */            handle_key_down( &event.key.keysym );            break;        case SDL_QUIT:            /* Handle quit requests (like Ctrl-c). */            quit_tutorial( 0 );            break;        }    }}static void draw_screen( void ){    /* Our angle of rotation. */    static float angle = 0.0f;    /*     * EXERCISE:     * Replace this awful mess with vertex     * arrays and a call to glDrawElements.     *     * EXERCISE:     * After completing the above, change     * it to use compiled vertex arrays.     *     * EXERCISE:     * Verify my windings are correct here ;).     */    static GLfloat v0[] = { -1.0f, -1.0f,  1.0f };    static GLfloat v1[] = {  1.0f, -1.0f,  1.0f };    static GLfloat v2[] = {  1.0f,  1.0f,  1.0f };    static GLfloat v3[] = { -1.0f,  1.0f,  1.0f };    static GLfloat v4[] = { -1.0f, -1.0f, -1.0f };    static GLfloat v5[] = {  1.0f, -1.0f, -1.0f };    static GLfloat v6[] = {  1.0f,  1.0f, -1.0f };    static GLfloat v7[] = { -1.0f,  1.0f, -1.0f };    static GLubyte red[]    = { 255,   0,   0, 255 };    static GLubyte green[]  = {   0, 255,   0, 255 };    static GLubyte blue[]   = {   0,   0, 255, 255 };    static GLubyte white[]  = { 255, 255, 255, 255 };    static GLubyte yellow[] = {   0, 255, 255, 255 };    static GLubyte black[]  = {   0,   0,   0, 255 };    static GLubyte orange[] = { 255, 255,   0, 255 };    static GLubyte purple[] = { 255,   0, 255,   0 };    /* Clear the color and depth buffers. */    glClear( GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT );    /* We don't want to modify the projection matrix. */    glMatrixMode( GL_MODELVIEW );    glLoadIdentity( );    /* Move down the z-axis. */    glTranslatef( 0.0, 0.0, -5.0 );    /* Rotate. */    glRotatef( angle, 0.0, 1.0, 0.0 );    if( should_rotate ) {        if( ++angle > 360.0f ) {            angle = 0.0f;        }    }    /* Send our triangle data to the pipeline. */    glBegin( GL_TRIANGLES );    glColor4ubv( red );    glVertex3fv( v0 );    glColor4ubv( green );    glVertex3fv( v1 );    glColor4ubv( blue );    glVertex3fv( v2 );    glColor4ubv( red );    glVertex3fv( v0 );    glColor4ubv( blue );    glVertex3fv( v2 );    glColor4ubv( white );    glVertex3fv( v3 );    glColor4ubv( green );    glVertex3fv( v1 );    glColor4ubv( black );    glVertex3fv( v5 );    glColor4ubv( orange );    glVertex3fv( v6 );    glColor4ubv( green );    glVertex3fv( v1 );    glColor4ubv( orange );    glVertex3fv( v6 );    glColor4ubv( blue );    glVertex3fv( v2 );    glColor4ubv( black );    glVertex3fv( v5 );    glColor4ubv( yellow );    glVertex3fv( v4 );    glColor4ubv( purple );    glVertex3fv( v7 );    glColor4ubv( black );    glVertex3fv( v5 );    glColor4ubv( purple );    glVertex3fv( v7 );    glColor4ubv( orange );    glVertex3fv( v6 );    glColor4ubv( yellow );    glVertex3fv( v4 );    glColor4ubv( red );    glVertex3fv( v0 );    glColor4ubv( white );    glVertex3fv( v3 );    glColor4ubv( yellow );    glVertex3fv( v4 );    glColor4ubv( white );    glVertex3fv( v3 );    glColor4ubv( purple );    glVertex3fv( v7 );    glColor4ubv( white );    glVertex3fv( v3 );    glColor4ubv( blue );    glVertex3fv( v2 );    glColor4ubv( orange );    glVertex3fv( v6 );    glColor4ubv( white );    glVertex3fv( v3 );    glColor4ubv( orange );    glVertex3fv( v6 );    glColor4ubv( purple );    glVertex3fv( v7 );    glColor4ubv( green );    glVertex3fv( v1 );    glColor4ubv( red );    glVertex3fv( v0 );    glColor4ubv( yellow );    glVertex3fv( v4 );    glColor4ubv( green );    glVertex3fv( v1 );    glColor4ubv( yellow );    glVertex3fv( v4 );    glColor4ubv( black );    glVertex3fv( v5 );    glEnd( );    /*     * EXERCISE:     * Draw text telling the user that 'Spc'     * pauses the rotation and 'Esc' quits.     * Do it using vetors and textured quads.     */    /*     * Swap the buffers. This this tells the driver to     * render the next frame from the contents of the     * back-buffer, and to set all rendering operations     * to occur on what was the front-buffer.     *     * Double buffering prevents nasty visual tearing     * from the application drawing on areas of the     * screen that are being updated at the same time.     */    SDL_GL_SwapBuffers( );}static void setup_opengl( int width, int height ){    float ratio = (float) width / (float) height;    /* Our shading model--Gouraud (smooth). */    glShadeModel( GL_SMOOTH );    /* Culling. */    glCullFace( GL_BACK );    glFrontFace( GL_CCW );    glEnable( GL_CULL_FACE );    /* Set the clear color. */    glClearColor( 0, 0, 0, 0 );    /* Setup our viewport. */    glViewport( 0, 0, width, height );    /*     * Change to the projection matrix and set     * our viewing volume.     */    glMatrixMode( GL_PROJECTION );    glLoadIdentity( );    /*     * EXERCISE:     * Replace this with a call to glFrustum.     */    gluPerspective( 60.0, ratio, 1.0, 1024.0 );}int main( int argc, char* argv[] ){    /* Information about the current video settings. */    const SDL_VideoInfo* info = NULL;    /* Dimensions of our window. */    int width = 0;    int height = 0;    /* Color depth in bits of our window. */    int bpp = 0;    /* Flags we will pass into SDL_SetVideoMode. */    int flags = 0;    /* First, initialize SDL's video subsystem. */    if( SDL_Init( SDL_INIT_VIDEO ) < 0 ) {        /* Failed, exit. */        fprintf( stderr, "Video initialization failed: %s/n",             SDL_GetError( ) );        quit_tutorial( 1 );    }    /* Let's get some video information. */    info = SDL_GetVideoInfo( );    if( !info ) {        /* This should probably never happen. */        fprintf( stderr, "Video query failed: %s/n",             SDL_GetError( ) );        quit_tutorial( 1 );    }    /*     * Set our width/height to 640/480 (you would     * of course let the user decide this in a normal     * app). We get the bpp we will request from     * the display. On X11, VidMode can't change     * resolution, so this is probably being overly     * safe. Under Win32, ChangeDisplaySettings     * can change the bpp.     */    width = 640;    height = 480;    bpp = info->vfmt->BitsPerPixel;    /*     * Now, we want to setup our requested     * window attributes for our OpenGL window.     * We want *at least* 5 bits of red, green     * and blue. We also want at least a 16-bit     * depth buffer.     *     * The last thing we do is request a double     * buffered window. '1' turns on double     * buffering, '0' turns it off.     *     * Note that we do not use SDL_DOUBLEBUF in     * the flags to SDL_SetVideoMode. That does     * not affect the GL attribute state, only     * the standard 2D blitting setup.     */    SDL_GL_SetAttribute( SDL_GL_RED_SIZE, 5 );    SDL_GL_SetAttribute( SDL_GL_GREEN_SIZE, 5 );    SDL_GL_SetAttribute( SDL_GL_BLUE_SIZE, 5 );    SDL_GL_SetAttribute( SDL_GL_DEPTH_SIZE, 16 );    SDL_GL_SetAttribute( SDL_GL_DOUBLEBUFFER, 1 );    /*     * We want to request that SDL provide us     * with an OpenGL window, in a fullscreen     * video mode.     *     * EXERCISE:     * Make starting windowed an option, and     * handle the resize events properly with     * glViewport.     */    flags = SDL_OPENGL | SDL_FULLSCREEN;    /*     * Set the video mode     */    if( SDL_SetVideoMode( width, height, bpp, flags ) == 0 ) {        /*          * This could happen for a variety of reasons,         * including DISPLAY not being set, the specified         * resolution not being available, etc.         */        fprintf( stderr, "Video mode set failed: %s/n",             SDL_GetError( ) );        quit_tutorial( 1 );    }    /*     * At this point, we should have a properly setup     * double-buffered window for use with OpenGL.     */    setup_opengl( width, height );    /*     * Now we want to begin our normal app process--     * an event loop with a lot of redrawing.     */    while( 1 ) {        /* Process incoming events. */        process_events( );        /* Draw the screen. */        draw_screen( );    }    /*     * EXERCISE:     * Record timings using SDL_GetTicks() and     * and print out frames per second at program     * end.     */    /* Never reached. */    return 0;}
第三章上 游戏杆输入处理
初始化
使用游戏杆的第一步是初始化游戏杆子系统。即在SDL_Init时使用参数SDL_INIT_JOYSTICK。
例3-1 初始化SDL并带游戏杆支持
    if ( ! SDL_Init( SDL_INIT_VIDEO | SDL_INIT_JOYSTICK ) )    {        fprintf(stderr, "Couldn't initialize SDL: %s/n", SDL_GetError());        exit(1);    }
此例启动SDL并带视频和游戏杆支持。
查询
至此，我们可以假定初始化以完成。但我们还需指导有没有、有几个游戏杆。即使您指导有一个游戏杆可用，也最好经常检查，因为这样可以帮助检测游戏杆被拔掉的情况。
检查游戏杆的函数是SDL_NumJoysticks()。此函数简单的返回系统中游戏杆的数量。下一步是决定用户想用哪一个。当然，如果只有一个就不用决定了。SDL_JoystickName取得系统赋给游戏杆的名字。游戏杆用序号指定，第一个为0，最后一个为SDL_NumJoysticks - 1。
例3-2 打印所有游戏杆的名字
    printf("%i joysticks were found./n/n", SDL_NumJoysticks() );    printf("The names of the joysticks are:/n");    for( i=0; i < SDL_NumJoysticks(); i++ )     {        printf("    %s/n", SDL_JoystickName(i));    }
启动游戏杆取得事件
SDL使用事件架构，游戏杆可以触发四种事件。
SDL_JoyAxisEvent 轴改变 
SDL_JoyBallEvent 轨迹球坐标改变 
SDL_JoyHatEvent hat（sorry，在下不解何为hat）方向改变 
SDL_JoyButtonEvent 按钮按下或释放 
所有启动的游戏杆都会触发事件。为了收到事件，首先要用SDL_ENABLE调用SDL_JoystickEventState，以允许事件。其次要启动指定的游戏杆，用SDL_JoystickOpen()。
例3-3 启动第一个游戏杆
    SDL_Joystick *joystick;    SDL_JoystickEventState(SDL_ENABLE);    joystick = SDL_JoystickOpen(0);
游戏杆对象的指针只在查询和关闭游戏杆时有用。
现在为了响应事件，我们需要一个消息循环。所有的SDL程序至少要接受系统退出消息。设想我们的消息循环象这样：
    SDL_Event event;    /* Other initializtion code goes here */       /* Start main game loop here */    while(SDL_PollEvent(&event))    {          switch(event.type)        {              case SDL_KEYDOWN:            /* handle keyboard stuff here */            break;            case SDL_QUIT:            /* Set whatever flags are necessary to */            /* end the main game loop here */            break;        }    }    /* End loop here */
要响应游戏杆事件，只需添加一个case。轴检测得有些技巧，因为大部分事件是垃圾。摇杆动一点就会有事件。所以必须设定一个阈值，并且忽略未达到阈值的事件。一般10%是个比较好的阈值。
例3-4 游戏杆轴事件
    case SDL_JOYAXISMOTION:  /* Handle Joystick Motion */    if ( ( event.jaxis.value < -3200 ) || (event.jaxis.value > 3200 ) )     {      /* code goes here */    }    break;
另一个技巧是上下和左右是两组不同的运动。最重要的轴是轴0（左右）和轴1（上下）。按如下方法作不同处理：
例3-5 
    case SDL_JOYAXISMOTION:  /* Handle Joystick Motion */    if ( ( event.jaxis.value < -3200 ) || (event.jaxis.value > 3200 ) )     {        if( event.jaxis.axis == 0)         {            /* Left-right movement code goes here */        }        if( event.jaxis.axis == 1)         {            /* Up-Down movement code goes here */        }    }    break;
理想情况下，应该用event.jaxis.value来调整一些值。例如你在用游戏杆控制飞船，将摇杆推一点则慢速前进，推很多则快速前进。这样设计会使用户的体验更好。如果你的游戏杆有更多的轴，可用于其他控制，用法完全一样，event.jaxis.axis会有不同的值。
例3-6 游戏杆按钮事件
    case SDL_JOYBUTTONDOWN:  /* Handle Joystick Button Presses */    if ( event.jbutton.button == 0 )     {        /* code goes here */    }    break;
按钮检测很简单，因为只有按下和放开两个状态。按下时SDL_JOYBUTTONDOWN触发，放开时SDL_JOYBUTTONUP触发。event.jbutton.button指示是哪个按钮。
最后，程序结束时用SDL_JoystickClose()关闭游戏杆。例如关闭前面启动的0号游戏杆：
SDL_JoystickClose(joystick);
高级游戏杆函数
轨迹球消息包含X和Y方向的改变量。
例3-7 轨迹球事件
    case SDL_JOYBALLMOTION:  /* Handle Joyball Motion */    if( event.jball.ball == 0 )    {      /* ball handling */    }    break;
此例检测第一个轨迹球。坐标改变量在event.jball.xrel和event.jball.yrel中。
最后是hat事件。hat只报告方向。我们通过位掩码检测： 
SDL_HAT_CENTERED SDL_HAT_UP SDL_HAT_RIGHT SDL_HAT_DOWN SDL_HAT_LEFT 
预定义的组合：
SDL_HAT_RIGHTUP SDL_HAT_RIGHTDOWN SDL_HAT_LEFTUP SDL_HAT_LEFTDOWN 
例3-8 游戏杆hat事件
    case SDL_JOYHATMOTION:  /* Handle Hat Motion */    if ( event.jhat.hat | SDL_HAT_UP )    {        /* Do up stuff here */    }    if ( event.jhat.hat | SDL_HAT_LEFT )    {        /* Do left stuff here */    }    if ( event.jhat.hat | SDL_HAT_RIGHTDOWN )    {        /* Do right and down together stuff here */    }    break;
除了游戏杆的数量，还可查询：
SDL_JoystickNumAxes 轴数量 
SDL_JoystickNumButtons 按钮数量 
SDL_JoystickNumBalls 轨迹球数量 
SDL_JoystickNumHats hat数量 
只需将启动游戏杆时得到的指针传给这些函数即可。
例3-9 查询游戏杆特性
    int number_of_buttons;    SDL_Joystick *joystick;    joystick = SDL_JoystickOpen(0);    number_of_buttons = SDL_JoystickNumButtons(joystick);
第三章下 键盘输入
键盘相关数据结构
SDLKey 枚举类型，每一个符号代表一个键，如SDLK_a、SDLK_SPACE，在SDL_keysym.h中定义。 
SDLMod 枚举类型，类似SDLKey，但用于修饰键，如Control、Alt、Shift，可以组合。 
SDL_keysym 
typedef struct{  Uint8 scancode;  SDLKey sym;  SDLMod mod;  Uint16 unicode;} SDL_keysym;
用于按键和放开消息。scancode是硬件相关键码。除非你有特殊用途，否则忽略。sym指示键，mod为修饰键集合，例如KMOD_NUM | KMOD_CAPS | KMOD_LSHIFT 为Numlock、Capslock和左Shift组合。最后unicode为对应字符。注意，仅当是按键消息时unicode才有效，放开消息时无效。Unicode变换必须用SDL_EnableUNICODE()打开。 
SDL_KeyboardEvent 
typedef struct{  Uint8 type;  Uint8 state;  SDL_keysym keysym;} SDL_KeyboardEvent;
描述一个键盘消息。type指示按键（SDL_KEYDOWN）或放开（SDL_KEYUP）。state是冗余的，和含义type相同只是符号不同（SDL_PRESSED，SDL_RELEASED）。 
读取键盘消息
使用消息循环用SDL_PollEvent()从消息队列里读取，并用switch-case检测SDL_KEYUP和SDL_KEYDOWN。下面是个基本的例子。
例3-10 读键盘消息
  SDL_Event event;  .  .  /* Poll for events. SDL_PollEvent() returns 0 when there are no  */  /* more events on the event queue, our while loop will exit when */  /* that occurs.                                                  */  while( SDL_PollEvent( &event ) ){    /* We are only worried about SDL_KEYDOWN and SDL_KEYUP events */    switch( event.type ){      case SDL_KEYDOWN:        printf( "Key press detected/n" );        break;      case SDL_KEYUP:        printf( "Key release detected/n" );        break;      default:        break;    }  }
更详细的内容
我们已经知道要用SDL_Init和SDL_SetVideoMode初始化，但我们还得用另外两个函数取得必要信息。要调用SDL_EnableUNICODE(1)以允许unicode变换，还要用SDL_GetKeyName将SDLKey转换成可打印字符。注意：小于0x80的unicode字符直接映射到ASCII码。下例用到这一点。
例3-11 解释按键消息
    #include "SDL.h"    /* Function Prototypes */    void PrintKeyInfo( SDL_KeyboardEvent *key );    void PrintModifiers( SDLMod mod );    /* main */    int main( int argc, char *argv[] ){                SDL_Event event;        int quit = 0;                /* Initialise SDL */        if( SDL_Init( SDL_INIT_VIDEO ) ){            fprintf( stderr, "Could not initialise SDL: %s/n", SDL_GetError() );            exit( -1 );        }        /* Set a video mode */        if( !SDL_SetVideoMode( 320, 200, 0, 0 ) ){            fprintf( stderr, "Could not set video mode: %s/n", SDL_GetError() );            SDL_Quit();            exit( -1 );        }        /* Enable Unicode translation */        SDL_EnableUNICODE( 1 );        /* Loop until an SDL_QUIT event is found */        while( !quit ){            /* Poll for events */            while( SDL_PollEvent( &event ) ){                                switch( event.type ){                    /* Keyboard event */                    /* Pass the event data onto PrintKeyInfo() */                    case SDL_KEYDOWN:                    case SDL_KEYUP:                        PrintKeyInfo( &event.key );                        break;                    /* SDL_QUIT event (window close) */                    case SDL_QUIT:                        quit = 1;                        break;                    default:                        break;                }            }        }        /* Clean up */        SDL_Quit();        exit( 0 );    }    /* Print all information about a key event */    void PrintKeyInfo( SDL_KeyboardEvent *key ){        /* Is it a release or a press? */        if( key->type == SDL_KEYUP )            printf( "Release:- " );        else            printf( "Press:- " );        /* Print the hardware scancode first */        printf( "Scancode: 0x%02X", key->keysym.scancode );        /* Print the name of the key */        printf( ", Name: %s", SDL_GetKeyName( key->keysym.sym ) );        /* We want to print the unicode info, but we need to make */        /* sure its a press event first (remember, release events */        /* don't have unicode info                                */        if( key->type == SDL_KEYDOWN ){            /* If the Unicode value is less than 0x80 then the    */            /* unicode value can be used to get a printable       */            /* representation of the key, using (char)unicode.    */            printf(", Unicode: " );            if( key->keysym.unicode < 0x80 && key->keysym.unicode > 0 ){                printf( "%c (0x%04X)", (char)key->keysym.unicode,                        key->keysym.unicode );            }            else{                printf( "? (0x%04X)", key->keysym.unicode );            }        }        printf( "/n" );        /* Print modifier info */        PrintModifiers( key->keysym.mod );    }    /* Print modifier info */    void PrintModifiers( SDLMod mod ){        printf( "Modifers: " );        /* If there are none then say so and return */        if( mod == KMOD_NONE ){            printf( "None/n" );            return;        }        /* Check for the presence of each SDLMod value */        /* This looks messy, but there really isn't    */        /* a clearer way.                              */        if( mod & KMOD_NUM ) printf( "NUMLOCK " );        if( mod & KMOD_CAPS ) printf( "CAPSLOCK " );        if( mod & KMOD_LCTRL ) printf( "LCTRL " );        if( mod & KMOD_RCTRL ) printf( "RCTRL " );        if( mod & KMOD_RSHIFT ) printf( "RSHIFT " );        if( mod & KMOD_LSHIFT ) printf( "LSHIFT " );        if( mod & KMOD_RALT ) printf( "RALT " );        if( mod & KMOD_LALT ) printf( "LALT " );        if( mod & KMOD_CTRL ) printf( "CTRL " );        if( mod & KMOD_SHIFT ) printf( "SHIFT " );        if( mod & KMOD_ALT ) printf( "ALT " );        printf( "/n" );    }
游戏式键盘输入
键盘消息仅在键的状态在按下和放开间变化时才触发。
设想你用光标键控制飞船运动以改变眼前看到的太空景象，当你按左键并希望镜头向左转时。看看下面的代码，并注意它为什么是错的。
    /* Alien screen coordinates */    int alien_x=0, alien_y=0;    .    .    /* Initialise SDL and video modes and all that */    .    /* Main game loop */    /* Check for events */    while( SDL_PollEvent( &event ) ){        switch( event.type ){            /* Look for a keypress */            case SDL_KEYDOWN:                /* Check the SDLKey values and move change the coords */                switch( event.key.keysym.sym ){                    case SDLK_LEFT:                        alien_x -= 1;                        break;                    case SDLK_RIGHT:                        alien_x += 1;                        break;                    case SDLK_UP:                        alien_y -= 1;                        break;                    case SDLK_DOWN:                        alien_y += 1;                        break;                    default:                        break;                }            }        }    }
问题在于你必须按100次左以便得到100次键盘消息，才能向左转100像素。正确的方法是收到事件时设定标志，根据标志来移动。
例3-12 正确的运动控制
    /* Alien screen coordinates */    int alien_x=0, alien_y=0;    int alien_xvel=0, alien_yvel=0;    .    .    /* Initialise SDL and video modes and all that */    .    /* Main game loop */    /* Check for events */    while( SDL_PollEvent( &event ) ){        switch( event.type ){            /* Look for a keypress */            case SDL_KEYDOWN:                /* Check the SDLKey values and move change the coords */                switch( event.key.keysym.sym ){                    case SDLK_LEFT:                        alien_xvel = -1;                        break;                    case SDLK_RIGHT:                        alien_xvel =  1;                        break;                    case SDLK_UP:                        alien_yvel = -1;                        break;                    case SDLK_DOWN:                        alien_yvel =  1;                        break;                    default:                        break;                }                break;            /* We must also use the SDL_KEYUP events to zero the x */            /* and y velocity variables. But we must also be       */            /* careful not to zero the velocities when we shouldn't*/            case SDL_KEYUP:                switch( event.key.keysym.sym ){                    case SDLK_LEFT:                        /* We check to make sure the alien is moving */                        /* to the left. If it is then we zero the    */                        /* velocity. If the alien is moving to the   */                        /* right then the right key is still press   */                        /* so we don't tocuh the velocity            */                        if( alien_xvel < 0 )                            alien_xvel = 0;                        break;                    case SDLK_RIGHT:                        if( alien_xvel > 0 )                            alien_xvel = 0;                        break;                    case SDLK_UP:                        if( alien_yvel < 0 )                            alien_yvel = 0;                        break;                    case SDLK_DOWN:                        if( alien_yvel > 0 )                            alien_yvel = 0;                        break;                    default:                        break;                }                break;                        default:                break;        }    }    .    .    /* Update the alien position */    alien_x += alien_xvel;    alien_y += alien_yvel;
如您所见，我们用了两个变量alien_xvel和alien_yvel来表示飞船的运动，并在响应键盘消息时更新它们。
第四章 样例
注：重复的例子没有列出
最快的图像平面块传送
将图像画到屏幕上有三种方式：1.创建一个图像平面并用SDL_BlitSurface传送到屏幕；2.在系统内存创建视频平面并调用SDL_UpdateRect；3.在显存创建视频平面并调用SDL_LockSurface。最好的方法是混合方式：
#include <stdio.h>#include <stdlib.h>#include "SDL.h"#include "SDL_timer.h"void ComplainAndExit(void){    fprintf(stderr, "Problem: %s/n", SDL_GetError());    exit(1);}int main(int argc, char *argv[]){    SDL_PixelFormat fmt;    SDL_Surface *screen, *locked;    SDL_Surface *imagebmp, *image;    SDL_Rect dstrect;    int i;    Uint8 *buffer;    /* Initialize SDL */    if ( SDL_Init(SDL_INIT_VIDEO) < 0 ) {        ComplainAndExit();    }    atexit(SDL_Quit);    /* Load a BMP image into a surface */    imagebmp = SDL_LoadBMP("image.bmp");    if ( imagebmp == NULL ) {        ComplainAndExit();    }    /* Set the video mode (640x480 at native depth) */    screen = SDL_SetVideoMode(640, 480, 0, SDL_HWSURFACE|SDL_FULLSCREEN);    if ( screen == NULL ) {        ComplainAndExit();    }    /* Set the video colormap */    if ( imagebmp->format->palette != NULL ) {        SDL_SetColors(screen,                      imagebmp->format->palette->colors, 0,                      imagebmp->format->palette->ncolors);    }    /* Convert the image to the video format (maps colors) */    image = SDL_DisplayFormat(imagebmp);    SDL_FreeSurface(imagebmp);    if ( image == NULL ) {        ComplainAndExit();    }    /* Draw bands of color on the raw surface */    if ( SDL_MUSTLOCK(screen) ) {        if ( SDL_LockSurface(screen) < 0 )            ComplainAndExit();    }    buffer=(Uint8 *)screen->pixels;    for ( i=0; ih; ++i ) {        memset(buffer,(i*255)/screen->h,               screen->w*screen->format->BytesPerPixel);               buffer += screen->pitch;    }    if ( SDL_MUSTLOCK(screen) ) {        SDL_UnlockSurface(screen);    }    /* Blit the image to the center of the screen */    dstrect.x = (screen->w-image->w)/2;    dstrect.y = (screen->h-image->h)/2;    dstrect.w = image->w;    dstrect.h = image->h;    if ( SDL_BlitSurface(image, NULL, screen, &dstrect) < 0 ) {        SDL_FreeSurface(image);        ComplainAndExit();    }    SDL_FreeSurface(image);    /* Update the screen */    SDL_UpdateRects(screen, 1, &dstrect);    SDL_Delay(5000);        /* Wait 5 seconds */    exit(0);}
过滤和处理事件
#include <stdio.h>#include <stdlib.h>#include "SDL.h"/* This function may run in a separate event thread */int FilterEvents(const SDL_Event *event) {    static int boycott = 1;    /* This quit event signals the closing of the window */    if ( (event->type == SDL_QUIT) && boycott ) {        printf("Quit event filtered out -- try again./n");        boycott = 0;        return(0);    }    if ( event->type == SDL_MOUSEMOTION ) {        printf("Mouse moved to (%d,%d)/n",                event->motion.x, event->motion.y);        return(0);    /* Drop it, we've handled it */    }    return(1);}int main(int argc, char *argv[]){    SDL_Event event;    /* Initialize the SDL library (starts the event loop) */    if ( SDL_Init(SDL_INIT_VIDEO) < 0 ) {        fprintf(stderr,                "Couldn't initialize SDL: %s/n", SDL_GetError());        exit(1);    }    /* Clean up on exit, exit on window close and interrupt */    atexit(SDL_Quit);    /* Ignore key events */    SDL_EventState(SDL_KEYDOWN, SDL_IGNORE);    SDL_EventState(SDL_KEYUP, SDL_IGNORE);    /* Filter quit and mouse motion events */    SDL_SetEventFilter(FilterEvents);    /* The mouse isn't much use unless we have a display for reference */    if ( SDL_SetVideoMode(640, 480, 8, 0) == NULL ) {        fprintf(stderr, "Couldn't set 640x480x8 video mode: %s/n",                        SDL_GetError());        exit(1);    }    /* Loop waiting for ESC+Mouse_Button */    while ( SDL_WaitEvent(&event) >= 0 ) {        switch (event.type) {            case SDL_ACTIVEEVENT: {                if ( event.active.state & SDL_APPACTIVE ) {                    if ( event.active.gain ) {                        printf("App activated/n");                    } else {                        printf("App iconified/n");                    }                }            }            break;                                case SDL_MOUSEBUTTONDOWN: {                Uint8 *keys;                keys = SDL_GetKeyState(NULL);                if ( keys[SDLK_ESCAPE] == SDL_PRESSED ) {                    printf("Bye bye.../n");                    exit(0);                }                printf("Mouse button pressed/n");            }            break;            case SDL_QUIT: {                printf("Quit requested, quitting./n");                exit(0);            }            break;        }    }    /* This should never happen */    printf("SDL_WaitEvent error: %s/n", SDL_GetError());    exit(1);}
打开音频设备
    SDL_AudioSpec wanted;    extern void fill_audio(void *udata, Uint8 *stream, int len);    /* Set the audio format */    wanted.freq = 22050;    wanted.format = AUDIO_S16;    wanted.channels = 2;    /* 1 = mono, 2 = stereo */    wanted.samples = 1024;  /* Good low-latency value for callback */    wanted.callback = fill_audio;    wanted.userdata = NULL;    /* Open the audio device, forcing the desired format */    if ( SDL_OpenAudio(&wanted, NULL) < 0 ) {        fprintf(stderr, "Couldn't open audio: %s/n", SDL_GetError());        return(-1);    }    return(0);
播放音频
    static Uint8 *audio_chunk;    static Uint32 audio_len;    static Uint8 *audio_pos;    /* The audio function callback takes the following parameters:       stream:  A pointer to the audio buffer to be filled       len:     The length (in bytes) of the audio buffer    */    void fill_audio(void *udata, Uint8 *stream, int len)    {        /* Only play if we have data left */        if ( audio_len == 0 )            return;        /* Mix as much data as possible */        len = ( len > audio_len ? audio_len : len );        SDL_MixAudio(stream, audio_pos, len, SDL_MIX_MAXVOLUME)        audio_pos += len;        audio_len -= len;    }    /* Load the audio data ... */    ;;;;;    audio_pos = audio_chunk;    /* Let the callback function play the audio chunk */    SDL_PauseAudio(0);    /* Do some processing */    ;;;;;    /* Wait for sound to complete */    while ( audio_len > 0 ) {        SDL_Delay(100);         /* Sleep 1/10 second */    }    SDL_CloseAudio();
列出所有CDROM
    #include "SDL.h"    /* Initialize SDL first */    if ( SDL_Init(SDL_INIT_CDROM) < 0 ) {        fprintf(stderr, "Couldn't initialize SDL: %s/n",SDL_GetError());        exit(1);    }    atexit(SDL_Quit);    /* Find out how many CD-ROM drives are connected to the system */    printf("Drives available: %d/n", SDL_CDNumDrives());    for ( i=0; i<SDL_CDNumDrives(); ++i ) {        printf("Drive %d:  /"%s/"/n", i, SDL_CDName(i));    }
打开缺省CDROM驱动器
    SDL_CD *cdrom;    CDstatus status;    char *status_str;    cdrom = SDL_CDOpen(0);    if ( cdrom == NULL ) {        fprintf(stderr, "Couldn't open default CD-ROM drive: %s/n",                        SDL_GetError());        exit(2);    }    status = SDL_CDStatus(cdrom);    switch (status) {        case CD_TRAYEMPTY:            status_str = "tray empty";            break;        case CD_STOPPED:            status_str = "stopped";            break;        case CD_PLAYING:            status_str = "playing";            break;        case CD_PAUSED:            status_str = "paused";            break;        case CD_ERROR:            status_str = "error state";            break;    }    printf("Drive status: %s/n", status_str);    if ( status >= CD_PLAYING ) {        int m, s, f;        FRAMES_TO_MSF(cdrom->cur_frame, &m, &s, &f);        printf("Currently playing track %d, %d:%2.2d/n",        cdrom->track[cdrom->cur_track].id, m, s);    }
列出CD上所有音轨
    SDL_CD *cdrom;          /* Assuming this has already been set.. */    int i;    int m, s, f;    SDL_CDStatus(cdrom);    printf("Drive tracks: %d/n", cdrom->numtracks);    for ( i=0; i<cdrom->numtracks; ++i ) {        FRAMES_TO_MSF(cdrom->track[i].length, &m, &s, &f);        if ( f > 0 )            ++s;        printf("/tTrack (index %d) %d: %d:%2.2d/n", i,        cdrom->track[i].id, m, s);    }
播放CD
    SDL_CD *cdrom;          /* Assuming this has already been set.. */    // Play entire CD:    if ( CD_INDRIVE(SDL_CDStatus(cdrom)) )        SDL_CDPlayTracks(cdrom, 0, 0, 0, 0);        // Play last track:        if ( CD_INDRIVE(SDL_CDStatus(cdrom)) ) {            SDL_CDPlayTracks(cdrom, cdrom->numtracks-1, 0, 0, 0);        }        // Play first and second track and 10 seconds of third track:        if ( CD_INDRIVE(SDL_CDStatus(cdrom)) )            SDL_CDPlayTracks(cdrom, 0, 0, 2, 10);
基于时间的游戏主循环
#define TICK_INTERVAL    30Uint32 TimeLeft(void){    static Uint32 next_time = 0;    Uint32 now;    now = SDL_GetTicks();    if ( next_time <= now ) {        next_time = now+TICK_INTERVAL;        return(0);    }    return(next_time-now);}/* main game loop    while ( game_running ) {        UpdateGameState();        SDL_Delay(TimeLeft());    }