SDL 0.6j API changes

This is fairly lengthy, so you may want to skim it if you’re not actively
developing SDL applications. If you are, I would like to hear any comments
you have.

Version 0.6:

SDL is put under RCS

If the environment variable “SDL_DEBUG” is set, any SDL error that
occurs will be printed to standard error by SDL_SetError().

    It is now possible to create surfaces in video memory with arbitrary
    surface formats.  Keep in mind that many video cards will not allow
    hardware surfaces of a format different than that returned by
    SDL_GetDisplayFormat(), and your surface may end up in system memory

    If you set the colorkey and/or alpha value of an accelerated surface,
    and then unset them, the acceleration may be lost until the next call
    to SDL_MapSurface()

    A new surface flag, SDL_HWACCEL is set when the blit from that
    surface will be hardware accelerated.  Do not set or clear this
    flag yourself.  It will automatically be set when you map a surface
    for blitting.

    The data types of the x,y coordinates for mouse events have been
    changed from Uint32 to Uint16 to match internal representation.

    The internal event state is now updated _after_ the event callback
    or filter function is run.  You can't change the event, but you can
    now compare it to the original state.

    A new function SDL_Linked_Version() returns a const pointer to the
    dynamically linked library version.  A macro SDL_VERSION(X) fills
    X with the compile-time version of SDL which you can pass to any
    SDL function that requires a version argument.

    There is a new function SDL_GetWMInfo() which fills a structure
    with custom window manager information (documented in SDL_syswm.h)
    It used like this:
    #include "SDL_version.h"
    #include "SDL_syswm.h"
            SDL_SysWMInfo info;

            info.version = SDL_VERSION;
            if ( SDL_GetWMInfo(&info) > 0 ) {
                    /* Do something */;

    There is a new event type SDL_SYSWMEVENT which can be used to get
    system-specific events, like clipboard events or multimedia events.
    This event is ignored by default and shouldn't be used except in
    special cases.

    There is a new event type SDL_ACTIVEEVENT which is received when
    your application is minimized, or otherwise disabled.
    The associated function to get the current state is SDL_AppActive()

    SDL_VideoModeOK() now returns the bit-depth of the supported mode
    instead of 1 or 2 if a given sized mode is supported.

SDL_SetColors() returns 0 instead of 1 if the surface passed is not
a palettized surface.

    SDL_CreateColorCursor() no longer frees the surface it is passed.
    You have to free it yourself, if you want to get rid of it.

    A new flag, SDL_THREADSAFE can be passed to SDL_AllocSurface(),
    and will enable thread-safe locking between SDL_LockSurface() and
    SDL_UnlockSurface() calls, so that only one thread can lock it at
    a time.  This flag does not cause SDL_MUSTLOCK() to return true.
    SDL_BlitSurface() will lock and unlock surfaces with this flag
    set (do not set the flag yourself -- pass it to SDL_AllocSurface()
    The video surface will have this flag set automatically.
    If you clear this flag, then blitting to the video surface will
    be slightly faster, but you will not be able to create color cursors
    and the color cursor blit routines will start interfering with your

    SDL_WM_FullScreen() has been replaced by the SDL_FULLSCREEN flag
    which can be passed to SDL_SetVideoMode().  This more accurately
    reflects the process of toggling fullscreen display modes.

    SDL_GetVideoMode(), SDL_ListModes(), and SDL_VideoModeOK() all
    take an additional "flags" parameter, which is the same parameter
    you would pass to SDL_SetVideoMode()

    SDL_GetPixelFormat() has been renamed to SDL_GetDisplayFormat()

    SDL_GetDisplayFormat() gives you the video format of the real
    display as opposed to the (possibly different) one in the current
    display surface.

    SDL_SetColors() takes a new argument 'screen', which is the surface
    description for the current display, or any other surface on which
    you want to set the colormap.

    SDL_UpdateRect() and SDL_UpdateRects() take a new argument 'screen',
    which is the surface description for the current display.

    SDL_LockSurface() no longer returns a surface. SDL_LockSurface()
    and SDL_UnlockSurface() update the surface in-place if necessary.

    New functions available in SDL_timer.h:

    SDL_SetAlpha() takes a new flag parameter, which can be one of:
    The new SDL_MULACCEL flag tells SDL to accelerate the software
    alpha blending by premultiplying the alpha values on the surface.
    If you use this flag, you will have to lock and unlock the surface
    when you access it.  Each time you lock and unlock the surface,
    you lose some precision in the image colors, so it's better to
    use this on static images with a set alpha value.

    If you want a surface with a built-in alpha channel to use
    premultiplied blending acceleration (reduces blending accuracy)
            SDL_SetAlpha(surface, SDL_SRCALPHA|SDL_MULACCEL, 0);
    If you want to disable alpha blending on a surface with an
    alpha channel, then call:
            SDL_SetAlpha(surface, 0, 0);
    To re-enable it:
            SDL_SetAlpha(surface, SDL_SRCALPHA, 0);

    The blit routines have been rewritten again. :)  It's more
    logical this time, and easier to modify and/or extend.

    SDL_BlitSurface() is still the official blit function, but
    the real blitter has been split into three levels:
            SDL_UpperBlit(), SDL_MiddleBlit(), and SDL_LowerBlit()
    -- use them at your own peril! :)

See ya!
-Sam Lantinga (slouken at–
Author of Simple DirectMedia Layer -