Wiki Page Content

Differences between revisions 30 and 31
Revision 30 as of 2013-06-15 14:45:59
Size: 7886
Comment: Changed info about SDL_SetVideoMode().
Revision 31 as of 2013-07-25 16:59:01
Size: 8355
Editor: JonasThiem
Comment: moving new features info here (from the Introduction page)
Deletions are marked like this. Additions are marked like this.
Line 13: Line 13:
== Looking for information == === Overview of new features ===
These are the most important new features SDL 2 introduces:

 * Full 3D hardware acceleration
 * Support for OpenGL 3.0+
 * Support for multiple windows
 * Support for multiple displays
 * Support for multiple mice, tablets, etc.
 * Force Feedback available on Windows, Mac OS X and Linux

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

=== Looking for information ===
Line 19: Line 31:

DRAFT

SDL 1.2 to 2.0 Migration Guide

Introduction

This page describes what changed from SDL 1.2 to SDL 2.0, the new features, and upgrade tips. Most code written for SDL 1.2 will need to be updated (perhaps only slightly) to work properly with the new API.

Overview of new features

These are the most important new features SDL 2 introduces:

  • Full 3D hardware acceleration
  • Support for OpenGL 3.0+
  • Support for multiple windows
  • Support for multiple displays
  • Support for multiple mice, tablets, etc.
  • Force Feedback available on Windows, Mac OS X and Linux

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

Looking for information

The best place for information are:

Video

Hardware surfaces

The main change is the separation between software surfaces and hardware (accelerated) surfaces. Previously both were SDL_Surface structures, and hardware surfaces had the SDL_HWSURFACE flag on.

Now, we have two structures:

  • SDL_Surface: software surfaces, working like in 1.2, but never accelerated

  • SDL_Texture: hardware surfaces, whose pixels are not directly accessible (no ->pixels field)

Textures are typically OpenGL textures or X11 pixmaps, stored as near to the graphics hardware as possible.

You can create textures from an SDL_Surface by using SDL_CreateTextureFromSurface. Textures cannot be blit on each others, so you should do your manipulations on the surfaces first. They can be blit to the screen using SDL_RenderCopy.

Textures are created with a SDL_TextureAccess SDL_TEXTUREACCESS_STATIC or SDL_TEXTUREACCESS_STREAMING. Static means the texture doesn't change often, streaming means you can access its pixels using SDL_QueryTexturePixels. It's used by the SDL engine to manage memory.

Textures may be stored in unaccelerated memory, for instance if there's not enough memory in the graphics card.

Screen(s)

You now can create multiple screens (for instance: multiple windows). Each window has an associated Renderer. Each Renderer is managed by one of the built-in graphics drivers.

There is a complete example at SDL_RenderPresent.

The renderer replaces your previous SDL_Surface *screen object. It has a few methods to draw points, lines, rectangles, blit textures, etc. It also has a few dedicated post-processors for alpha-blending, masks, as well as add/multiply mode, cf. SDL_BlendMode and SDL_SetRenderDrawBlendMode. Introspection can be achieved using SDL_RendererInfo.

Instead of passing around a pointer to the current screen everywhere in your code, you pass a pointer to the renderer.

You update the physical screen using SDL_RenderPresent, which replaces SDL_Flip and SDL_UpdateRects.

SDL_SetVideoMode from 1.2 was just a compatibility function in 1.3, you will not use it anymore. It is no more available in 2.0. You can use SDL_GetWindowSurface to get a 1.2 style surface for a window if necessary.

Alpha-blending

Use SDL_SetSurfaceAlphaMod and SDL_SetTextureAlphaMod instead of SDL_SetAlpha. Alpha-blending on surfaces can be disabled via SDL_SetSurfaceBlendMode and on textures with SDL_SetTextureBlendMode.

Colorkey

When calling SDL_SetColorKey(), you should pass SDL_TRUE instead of SDL_SRCCOLORKEY

Color modulation

Some renderer now support a global color alteration (srcC = srcC * color), check SDL_SetTextureColorMod for details.

Color alpha

SDL_Color struct now contains a fourth, "alpha" component. Your 1.2 code that deals with SDL_Colors might be not copying/setting that value, in 2.0, you should.

Events

SDL_PushEvent() now returns 1 on success instead of 0.

Events mask are now specified using intervals:

# 1.2
SDL_PeepEvents(&event, 1, SDL_GETEVENT, SDL_EVENTMASK(SDL_MOUSEBUTTONDOWN))

becomes:

# 2.0
SDL_PeepEvents(&event, 1, SDL_GETEVENT, SDL_MOUSEBUTTONDOWN, SDL_MOUSEBUTTONDOWN)

Keys

Types

You'll note that there are two kinds of key numbers:

  • SDL_Keycode (previously SDLKey): key codes, using SDL_Keycode's SDLK constants; note that SDLK_LAST disappeared, because new values cover most of 32bits. Keys associated with printable characters are compatible with Unicode UTF16.

  • SDL_Scancode: scan codes, representing layout-independent key locations. Keyboard events have this value in event.key.keysym.scancode.

SDLMod is now SDL_Keymod.

Functions

There is now a dedicated API for textual input (e.g. to enter a small text, rather than combining keys); check Tutorials/TextInput for an introduction.

SDL_GetKeyState has been renamed to SDL_GetKeyboardState. The returned array should now be indexed by SDL_SCANCODE_* values (see SDL_Scancode) instead of SDL_Keysym values.

Audio

Audio is very similar to 1.2. The driver detection/priority changed, you may need to test again your target configurations.

In 2.0 the buffer passed to the audio callback is no more filled with silence (as it used to be on some platforms in 1.2). If SDL_MixAudio() should be used inside the audio callback then the buffer now must be manually filled with silence before mixing.

CD-ROM

CD-ROM support was dropped in 2.0. There is no replacement.

RWops

SDL_RWread() and SDL_RWwrite() now return 0 on error instead of -1. Also the return types are now size_t instead of int.

Extensions compatibility

The official extensions SDL_image, SDL_ttf, SDL_mixer and SDL_net have a version dedicated to SDL2.0 : SDL2_image, SDL2_ttf, SDL2_mixer and SDL2_net. You may need to download them from the mercurial repositories for the latest fixes. Subsequently, of course, you will have to link e.g. SDL2_image, not SDL_image, to compile your program.

SDL_gfx can also be compiled with 2.0 starting since 2.0.21 (May 2010).

Changes related to software surfaces manipulation are usually trivial, so more extensions should be rebuildable.

However, this multi-support can lead to delicate situations in the context of shared libraries (when using GNU/Linux distros package dependencies, or when using ms windows .dll's). For example, if your new 2.0 game links against libSDL_gfx.2.0.23.so.0, it will not be able to know whether SDL_gfx is itself linked against SDL 1.2 or SDL 2.0, especially if SDL_gfx is provided by the distro and not compiled by you.

Strategies

Here we discuss migration strategies for your code base.

Basic technique: here's how to detect the current SDL version:

#if SDL_VERSION_ATLEAST(2,0,0)
/* SDL 2.0 code */
#else
/* SDL 1.2 code */
#endif

Rewrite

The most obvious one: drop SDL 1.2 and rewrite everything for 2.0.

Backward-compatibility

Backward-compatibility was dropped from SDL 2.0, since such an interface would be imperfect and the API and performance would both suffer.

Forward-compatibility

You may want to support both libraries, for instance because SDL 1.2 is currently better supported on your platform, or better packaged in GNU/Linux distros.

The AlienBlaster code, in the Android port repository, uses a few additional functions on top of SDL, that will use either SDL 1.2 or 2.0 seamlessly, and minimise the amount of #ifdef. It's not completely fool-proof though, for instance blits between hardware surfaces will result in a no-op under 2.0. Check the C++ code at:

http://github.com/pelya/commandergenius/blob/sdl_android/project/jni/application/alienblaster/SdlForwardCompat.h

None: MigrationGuide (last edited 2017-07-15 21:53:17 by PhilippWiesemann)

Feedback
Please include your contact information if you'd like to receive a reply.
Submit