SDL Guide 中文译版 序言

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

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

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

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

Sam Lantinga, [email protected]

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_Quit（和SDL_QuitSubSystem）。SDL_Quit关闭所有子系统，必须在程序关闭前调用。

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

视频是最常用的部分，也是SDL最完整的子系统。下面的初始化过程是每个SDL程序都要做的，即使可能有些不同。

如果你希望某种色深（颜色数）但如果用户的显示器不支持也可以接受其他色深，使用加SDL_ANYFORMAT参数的SDL_SetVideoMode。您还可以用SDL_VideoModeOK来找到与请求模式最接近的模式。

当SDL已经初始化，视频模式已经选择，下面的函数将读取并显示指定的BMP文件。

下面两个函数实现在图像平面的像素读写。它们被细心设计成可以用于所有色深。记住在使用前要先锁定图像平面，之后要解锁。

在像素值和其红、绿、蓝值间转换，使用SDL_GetRGB()和SDL_MapRGB()。

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属性指定

除了初始化，在SDL程序中使用OpenGL和其他情况基本相同，是同样函数和数据类型。但是如果您使用双缓冲，则必须用SDL_GL_SwapBuffers()来交换前后缓冲，而不是glxSwapBuffers()（GLX）或SwapBuffers()（Windows）。

使用游戏杆的第一步是初始化游戏杆子系统。即在SDL_Init时使用参数SDL_INIT_JOYSTICK。

此例启动SDL并带视频和游戏杆支持。

至此，我们可以假定初始化以完成。但我们还需指导有没有、有几个游戏杆。即使您指导有一个游戏杆可用，也最好经常检查，因为这样可以帮助检测游戏杆被拔掉的情况。

检查游戏杆的函数是SDL_NumJoysticks()。此函数简单的返回系统中游戏杆的数量。下一步是决定用户想用哪一个。当然，如果只有一个就不用决定了。SDL_JoystickName取得系统赋给游戏杆的名字。游戏杆用序号指定，第一个为0，最后一个为SDL_NumJoysticks - 1。

SDL使用事件架构，游戏杆可以触发四种事件。

SDL_JoyAxisEvent 轴改变

SDL_JoyBallEvent 轨迹球坐标改变

SDL_JoyHatEvent hat（sorry，在下不解何为hat）方向改变

SDL_JoyButtonEvent 按钮按下或释放

所有启动的游戏杆都会触发事件。为了收到事件，首先要用SDL_ENABLE调用SDL_JoystickEventState，以允许事件。其次要启动指定的游戏杆，用SDL_JoystickOpen()。

游戏杆对象的指针只在查询和关闭游戏杆时有用。

现在为了响应事件，我们需要一个消息循环。所有的SDL程序至少要接受系统退出消息。设想我们的消息循环象这样：

要响应游戏杆事件，只需添加一个case。轴检测得有些技巧，因为大部分事件是垃圾。摇杆动一点就会有事件。所以必须设定一个阈值，并且忽略未达到阈值的事件。一般10%是个比较好的阈值。

另一个技巧是上下和左右是两组不同的运动。最重要的轴是轴0（左右）和轴1（上下）。按如下方法作不同处理：

理想情况下，应该用event.jaxis.value来调整一些值。例如你在用游戏杆控制飞船，将摇杆推一点则慢速前进，推很多则快速前进。这样设计会使用户的体验更好。如果你的游戏杆有更多的轴，可用于其他控制，用法完全一样，event.jaxis.axis会有不同的值。

按钮检测很简单，因为只有按下和放开两个状态。按下时SDL_JOYBUTTONDOWN触发，放开时SDL_JOYBUTTONUP触发。event.jbutton.button指示是哪个按钮。

最后，程序结束时用SDL_JoystickClose()关闭游戏杆。例如关闭前面启动的0号游戏杆：

轨迹球消息包含X和Y方向的改变量。

此例检测第一个轨迹球。坐标改变量在event.jball.xrel和event.jball.yrel中。

最后是hat事件。hat只报告方向。我们通过位掩码检测：

预定义的组合：

除了游戏杆的数量，还可查询：

SDL_JoystickNumAxes 轴数量

SDL_JoystickNumButtons 按钮数量

SDL_JoystickNumBalls 轨迹球数量

SDL_JoystickNumHats hat数量

只需将启动游戏杆时得到的指针传给这些函数即可。

SDLKey 枚举类型，每一个符号代表一个键，如SDLK_a、SDLK_SPACE，在SDL_keysym.h中定义。

SDLMod 枚举类型，类似SDLKey，但用于修饰键，如Control、Alt、Shift，可以组合。

SDL_keysym

用于按键和放开消息。scancode是硬件相关键码。除非你有特殊用途，否则忽略。sym指示键，mod为修饰键集合，例如KMOD_NUM | KMOD_CAPS | KMOD_LSHIFT 为Numlock、Capslock和左Shift组合。最后unicode为对应字符。注意，仅当是按键消息时unicode才有效，放开消息时无效。Unicode变换必须用SDL_EnableUNICODE()打开。

SDL_KeyboardEvent

描述一个键盘消息。type指示按键（SDL_KEYDOWN）或放开（SDL_KEYUP）。state是冗余的，和含义type相同只是符号不同（SDL_PRESSED，SDL_RELEASED）。

使用消息循环用SDL_PollEvent()从消息队列里读取，并用switch-case检测SDL_KEYUP和SDL_KEYDOWN。下面是个基本的例子。

我们已经知道要用SDL_Init和SDL_SetVideoMode初始化，但我们还得用另外两个函数取得必要信息。要调用SDL_EnableUNICODE(1)以允许unicode变换，还要用SDL_GetKeyName将SDLKey转换成可打印字符。注意：小于0x80的unicode字符直接映射到ASCII码。下例用到这一点。

键盘消息仅在键的状态在按下和放开间变化时才触发。

设想你用光标键控制飞船运动以改变眼前看到的太空景象，当你按左键并希望镜头向左转时。看看下面的代码，并注意它为什么是错的。

问题在于你必须按100次左以便得到100次键盘消息，才能向左转100像素。正确的方法是收到事件时设定标志，根据标志来移动。

如您所见，我们用了两个变量alien_xvel和alien_yvel来表示飞船的运动，并在响应键盘消息时更新它们。

注：重复的例子没有列出

将图像画到屏幕上有三种方式：1.创建一个图像平面并用SDL_BlitSurface传送到屏幕；2.在系统内存创建视频平面并调用SDL_UpdateRect；3.在显存创建视频平面并调用SDL_LockSurface。最好的方法是混合方式：