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, slouken@libsdl.org
Martin Donlon, [email protected]
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 * [email protected] * * 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 30
Uint32 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());
}