Use the SDL1.2 version of the students to note that the SDL2.0 version of the changes

SDL 1.2 to 2.0 migration Guide translations Introduction Overview of the new features looking for the more information from SDL 1.2 to 2.0 Some General Truths video Setting up a game with the new video API If your game just wants to get fully-re Ndered frames to the "If your game wants to blit surfaces to the" "If your game wants to does both other Renderer API notes OpenGL Input Events Audio joysticks Threads Audio CDs Dead platforms Mobile platforms Rwops Add-on Libraries Su Mmary of some renamed or replaced things other stuff

Translations

Une traduction de cette page par developpez.com est disponible ici.

If you want to translate this page to the other languages, let Ryan know:icculus@icculus.org

Introduction

After many years in development, SDL 2.0 has finally been released!

We are quite proud of it, and we ' d like games that are using SDL 1.2 to move up right away. As this can feel like a daunting task, this document is a simple walkthrough of the I-migrate to the new library. We'd find you'll find it's not as hard as you'd, and often times, you'll be either replacing function calls with direct equivalents or undoing some hacks in your code to deal with 1.2 deficiencies.

We'd be very happy with SDL 2.0, both for the new features and the better over SDL 1.2. This document doesn ' t try to cover all the awesome new things in Sdl2--and there are many--but just the things your need to Do-get-running right now. Once ' ve ported your code, definitely check out the new stuff, and you'll probably want to add some of it to your Applicati On, too.

Overview of new features

These are the most important new features at SDL 2.0:full 3D hardware acceleration Support for OpenGL 3.0+ in various Profiles (core, compatibility, debug, robust, etc) Support for OpenGL ES Support for multiple windows Support for multiple Displays Support for multiple audio Devices Android and IOS Support simple 2D rendering API so can use Direct3D, OpenGL , OpenGL ES, or software rendering behind the scenes Force Feedback available on Windows, Mac OS X and Linux XInput and XA Udio2 support for Windows Atomic Operations Power Management (exposes battery life remaining, etc) shaped Windows 32-bit A Udio (int and float) simplified Game Controller API (the joystick API is still here, too!) Touch Support (multitouch, gestures, etc) Better fullscreen support Better keyboard support (scancodes vs Keycodes, etc). Message boxes Clipboard support Basic Drag ' n ' Drop support Proper Unicode input and IME support

A really powerful ASSERT macro zlib license instead of LGPL. Lots of annoyances from 1.2 are gone Many other things!

The Introduction page has a more extensive listing about what features SDL offers in overall (including old 1.2 features).

looking for more information

The best places for information are:

This wiki

The tests included in SDL, in the Test/directory (browse online)

The SDL mailing list

moving from SDL 1.2 to 2.0

Some General Truths

There is no compatibility layer built in to SDL2. If an APIs changed for 2.0, we ' ve changed or removed the old functions where it makes sense. If you are your 1.2 at the 2.0 headers, it would probably fail to compile. This document would try to talk your through the most important changes, and the ones most to trips to your up.

There ' s no sdl_main! So, okay, there are, and it now does what it was always meant to:be a small piece of code that hides the difference Een main () and WinMain () on Windows. There ' s no initialization code in it, and it ' s completely optional. This means your can use SDL without it taking over your mainline, which are nice for plugins-use SDL, or scripting Lang Uages with an SDL module. All of the stuff you ' d want the 1.2 Sdl_main for are now in Sdl_init () where it belongs.

There ' s no SDL parachute anymore. What 1.2 called Sdl_init_noparachute is a default and only. This would cause problems if something other than the main thread crashed, and it would interfere with apps IR own signal/exception handlers. On the downside, some platforms don ' t clean up fullscreen a when crashing. You are should install your own crash handler, or call Sdl_quit () in a atexit () function or whatnot if it is a concern. Note This on Unix platforms, SDL still catches SIGINT and maps it to a sdl_quit event.

Video

Setting up a game with the new video API

The video API was the most dramatic change from 1.2. Needs have changed a great deal since SDL ' s API was designed in the late ' s. To deal with modern hardware and OS features, we have the almost completely the "old replaced" video API.

Don ' t worry, the new one is pretty great, and once your understand what ' changed, you ' re going to be very happy with the N EW features it can bring to your 1.2 game. We ' ll discuss those later.

The good news:if your game used OpenGL, you probably don ' t have much to do:change a handful of function calls to their S DL2 equivalents, and you ' re good to go.

For 2D Graphics, SDL 1.2 offered a concept called "surfaces," which were memory of buffers. The screen itself is a "surface," if you were doing 2D software rendering, and we provided functions to copy ("Blit") pix Els between surfaces, converting formats as necessary. You are were almost always working on the CPU in System RAM and not on the GPU in video memory. SDL 2.0 changes this; You are almost always get hardware acceleration now, and the API has changed to reflect this.

If you are have a 2D game, chances are you ' ve taken one of the three approaches to rendering. We'll go to through them all, but I, let ' s talk about introductory stuff.

Remember Sdl_setvideomode ()? It ' s completely gone. SDL 2.0 allows you to have multiple windows, so the "old" function didn ' t make sense no more.

So your might have had something like this:

Toggle Line Number Display

Sdl_wm_setcaption ("My Game Window", "Game");
Sdl_surface *screen = Sdl_setvideomode (640, 0, Sdl_fullscreen | SDL_OPENGL);

Which is now this:

Toggle Line Number Display

Sdl_window *screen = Sdl_createwindow ("My Game window",
                          sdl_windowpos_undefined,
                          sdl_windowpos_undefined,
                          640,
                          the Sdl_window_fullscreen | SDL_WINDOW_OPENGL);

You can have a maps pretty closely to 1.2. The difference is this can have multiple windows (if you want), and your can control them more. Sdl_wm_setcaption is gone, because "we want to allow" each windows to have its own title (your can change it later with Sdl_se Twindowtitle ()), and we want to let you specify a Windows position (or, in this case, use sdl_windowpos_undefined Since we don ' t care where the system places it. sdl_windowpos_centered is also a good choice).

Extra letting users specify a display for the WINDOW:SDL2 also allows your to manage systems with multiple Moni Tors. Don ' t worry about that right now, though.

So now this your window is back on the screen and let ' s talk strategy. SDL2 still has sdl_surface, but what you-want, if possible, is the new sdl_texture. Surfaces are always in System RAM now, and are always operated on by the CPU, so we want to get away from there. SDL2 has a new rendering API. It's meant for use with simple 2D games, but most notably, it's meant to get all this software into the video RAM and onto the GPU. And even if you are just want to use it to get your software renderer's work to the screens, it brings some nice very: If possible, it would use OpenGL or Direct3D behind the scenes, which means you'll get faster blits, a working Steam Overl Ay, and scaling for free.

The setup looks like this.

Sdl_setvideomode () becomes Sdl_createwindow (), as we discussed before. But What do we put for the resolution? If your game is hardcoded to 640x480, for example, your probably were running into monitors and that couldn ' t does that fullscre En resolution at this point, and in windowed mode, your game probably looked-like, animated postage stamp on really -end monitors. There ' s A better solution in SDL2.

We don ' t call Sdl_listmodes () anymore. There ' s a equivalent in SDL2 (call Sdl_getdisplaymode () in a loop, sdl_getnumdisplaymodes () times), but instead we ' re goi Ng to use a new feature called "Fullscreen desktop, which tells SDL" give me the whole screens and don t change the Resolu tion. " For our hypothetical 640x480 game, it might look like this:

Toggle Line Number Display

Sdl_window *sdlwindow = Sdl_createwindow (title,
                             sdl_windowpos_undefined,
                             sdl_windowpos_undefined,
                             0, 0 ,
                             sdl_window_fullscreen_desktop);

Notice how we didn ' t specify 640 or 480...fullscreen desktop gives your whole display and ignores any dimensions your SP Ecify. The game window should come up immediately, without waiting for the monitor to click into a new resolution, and we'll be u Sing the GPU to scale to the desktop size, which tends to was faster and cleaner-looking than if a LCD is faking a lower R Esolution. Added Bonus:none of your background windows are resizing right now.

Now we need a rendering the context.

Toggle Line Number Display

Sdl_renderer *renderer = Sdl_createrenderer (Sdlwindow,-1, 0);

A renderer hides the details of how we draw into the window. This might is using Direct3D, OpenGL, OpenGL ES, or software surfaces behind the scenes, depending on what the system Offe Rs Your code doesn ' t change, regardless of what SDL chooses (although-are welcome to force One kind of renderer or anothe R). If you are want to attempt to force Sync-to-vblank to reduce tearing, your can use sdl_renderer_presentvsync inste Ad of zero for the third parameter. You shouldn ' t create a Windows with the SDL_WINDOW_OPENGL flag. If Sdl_createrenderer () decides it wants to use OpenGL, it's ll update the window appropriately for you.

Now so you understand how this works, you can also does this all in one step with Sdl_createwindowandrenderer (), if your do N ' t want anything fancy:

Toggle Line Number Display

Sdl_window *sdlwindow;
Sdl_renderer *sdlrenderer;
Sdl_createwindowandrenderer (0, 0, sdl_window_fullscreen_desktop, &sdlwindow, &sdlrenderer);

Assuming these functions didn ' t fail (always check for nulls!), in are ready to start drawing to the screen. Let's get started by clearing the "screen" to black.

Toggle Line Number Display

Sdl_setrenderdrawcolor (sdlrenderer, 0, 0, 0, 255);
Sdl_renderclear (sdlrenderer);
Sdl_renderpresent (Sdlrenderer);

This is you might. Draw in Black (r,g,b all zero, alpha full), clear the whole window, put the cleared window on the screen. That's right, if you ' ve been using Sdl_updaterect () or sdl_flip () to get your bits to, the render API uses Renderpresent ().

One more general thing to set up here. Since we ' re using sdl_window_fullscreen_desktop, we don ' t actually know how much screens we ' ve got to draw to. Fortunately, we don ' t have to know. One of the nice things about 1.2 is this you could say "I want a 640x480 window and I don ' t care how do you do it," Eve N if getting it does meant centering the window in a larger resolution on behalf of your.

For 2.0, the render API lets.

Toggle Line Number Display

Sdl_sethint (sdl_hint_render_scale_quality, "linear");  Make the scaled rendering look smoother.
Sdl_rendersetlogicalsize (Sdlrenderer, 640, 480);

... and it'll do the right thing for you. This is the logical rendering size to achieve various effects, but the primary use is This:in Stead of trying to make the system work with your rendering size, we can now make your rendering size work with the system . On I 1920x1200 monitor, this app thinks it's talking to a 640x480 resolution now, but SDL are using the GPU to scale it up To use the all those pixels. Note this 640x480 and 1920x1200 aren ' t the same aspect RATIO:SDL takes care of that, too, scaling as much as possible and Letterboxing the difference.

Now we ' re ready to start drawing.

If Your game just wants to get fully-rendered frames to the screen

A special case for old school software rendered games:the application wants to draw every pixel itself and get that final Set of pixels to the screens efficiently in one big blit. An example of a game like this is Doom, or Duke Nukem, or many others.

For this, "re going to want a single sdl_texture that would represent the screen." Let ' s create one now for our 640x480 game:

Toggle Line Number Display

Sdltexture = Sdl_createtexture (Sdlrenderer,
                               sdl_pixelformat_argb8888,
                               sdl_textureaccess_streaming,
                               640, 480);

This represents a texture on the GPU. The gameplan is to finish each frame by uploading pixels to this texture, drawing the texture to the window, and flipping This is drawing onto the screen. sdl_textureaccess_streaming tells SDL this texture ' s contents are going to change