SDL 0.6j API changes

Sam Lantinga slouken at devolution.com
Tue Apr 28 19:54:30 PDT 1998


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:

0.6j:
        SDL is put under RCS

0.6i:
        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
        anyway.

        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.

0.6h:
        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
        blitting.

        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_StartTicks()
                SDL_GetTicks()

        SDL_SetAlpha() takes a new flag parameter, which can be one of:
                        0, SDL_SRCALPHA, SDL_SRCALPHA|SDL_MULACCEL
        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)
        call:
                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 devolution.com)

--
Author of Simple DirectMedia Layer -
	http://www.devolution.com/~slouken/SDL/
--



More information about the SDL mailing list