Wiki Page Content

Differences between revisions 3 and 4
Revision 3 as of 2010-11-11 22:11:06
Size: 5292
Comment: Section "Looking for information" + fix typos
Revision 4 as of 2010-11-11 22:12:03
Size: 5303
Comment: We seriously lack a Preview feature
Deletions are marked like this. Additions are marked like this.
Line 16: Line 16:
* this wiki :)
* the tests included in SDL, in the {{{test/}}} directory ([[http://hg.libsdl.org/SDL/file/tip/test|browse online]])
* the SDL [[http://lists.libsdl.org/listinfo.cgi/sdl-libsdl.org|mailing list]]
 * this wiki :)
 * the tests included in SDL, in the {{{test/}}} directory ([[http://hg.libsdl.org/SDL/file/tip/test|browse online]])
 * the SDL [[http://lists.libsdl.org/listinfo.cgi/sdl-libsdl.org|mailing list]]
Line 58: Line 58:
{{{SDL_SetVideoMode}}} from 1.2 is now just a compatibility function, you will not use it. {{{SDL_SetVideoMode}}} from 1.2 is now just a compatibility function, you will not use it anymore.

DRAFT

SDL 1.2 to 1.3 Migration Guide

Introduction

This page describes what changed from SDL 1.2 to SDL 1.3, the new features, and upgrade tips.

Looking for information

The best place for information are:

Compatibility mode

There are good chances that your current 1.2 code will directly compile under 1.3. Check include/SDL_compat.h and SDL/src/SDL_compat.c to get an idea.

Your code will probably run slower though; in particular there will be no hardware surfaces.

Compatibility is not 100% correct though; for instance SDL_SetPalette flags are currently ignored.

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 (not ->pixels field)

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

Textures cannot be blit on each others. 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 specify the currently active screen using SDL_SelectRenderer.

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

SDL_SetVideoMode from 1.2 is now just a compatibility function, you will not use it anymore.

Alpha-blending

Use SDL_SetSurfaceAlphaMod and SDL_SetTextureAlphaMod instead of SDL_SetAlpha.

Color modulation

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

Events

Events mask are now specified using intervals:

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

becomes:

# 1.3
SDL_PeepEvents(&event, 1, SDL_GETEVENT, SDL_MOUSEBUTTONDOWN, SDL_MOUSEBUTTONDOWN) > 0)

Keys

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

  • SDLKey: key codes, using SDL_Key'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-independant key locations

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

Audio

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

CD-ROM

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

Extensions compatibility

The official extensions SDL_image, SDL_ttf, SDL_mixer and SDL_net can be compiled with both 1.2 and 1.3. You may need to download them from the mercurial repositories for the latest fixes.

SDL_gfx can also be compiled with 1.3 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 1.3 game links against libSDL_image-1.2.so.0, it will not be able to know whether SDL_image is itself linked against SDL 1.2 or SDL 1.3, especially if SDL_image is provided by the distro and not compiled by you.

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