# SPL Module Reference: sdl

load "sdl";

    A module for doing multimedia using the SDL library.

    Note: Only one SDL window can be opened by one host program at a time.
    This is a limitation from SDL.

builtin sdl_init(width, height);
builtin sdl_quit();
builtin sdl_title(title, icon);
builtin sdl_delay(ms);
builtin sdl_flip();
builtin sdl_update(x, y, w, h);
builtin sdl_image_load(filename);
builtin sdl_image_create(w, h);
builtin sdl_blit(dstimg, srcimg, x, y);
builtin sdl_blitrect(dstimg, srcimg, dest_x, dest_y, src_x, src_y, w, h);
builtin sdl_copy(srcimg, x, y, w, h);
builtin sdl_fill(dstimg, x, y, w, h, r, g, b, a);
builtin sdl_fill_pattern(dstimg, x, y, w, h, patternimg);
builtin sdl_keystat(keyname);
builtin sdl_sprite_create();
builtin sdl_sprite_redraw();
builtin sdl_sprite_update();

object SdlEx
{
var description;
}

builtin sdl_init(width, height);

    Initialize SDL and open a window with the specified size.

    The window is opened in fullscreen when the named parameter 'fullscreen'
    is passed and has a 'true' (non-zero) value.

    The window is double-buffered when the named parameter 'doublebf'
    is passed and has a 'true' (non-zero) value.

builtin sdl_quit();

    Terminate the SDL context and close the window.

builtin sdl_title(title, icon);

    Set the window and icon name.

builtin sdl_delay(ms);

    Delay program execution for the specified number of milliseconds.

    Note that the given number of ms is relative to the end of the last call
    to sdl_delay(). The return code is the effective number of ms the
    program execution has been delayed.

    A zero or negative return code means that the function did not sleep and
    you are likely to have a timing/performance problem in your application.

builtin sdl_flip();

    Update the window (switch backend framebuffers if the window is created
    in doublebuffering mode).

builtin sdl_update(x, y, w, h);

    Update the specified area of the window.

builtin sdl_image_load(filename);

    Load the image from the specified filename and return the image handler.

builtin sdl_image_create(w, h);

    Create an empty image with the specified size.

builtin sdl_blit(dstimg, srcimg, x, y);

    Blit the source image to the specified coordinates in the destination
    image. If 'undef' is passed as destination image, the image is blitted to
    the window and will be displayed after the next call to sdl_flip().

builtin sdl_blitrect(dstimg, srcimg, dest_x, dest_y, src_x, src_y, w, h);

    Like sdl_blit(), but only blit the specified rectangle.

builtin sdl_copy(srcimg, x, y, w, h);

    Copy the the specified rectangle to a new image. The new image is returned.

builtin sdl_fill(dstimg, x, y, w, h, r, g, b, a);

    Fill the specified rectangle in the destination image with the specified
    RGBA values. (The RGBA values are in the range from 0 to 255.)

builtin sdl_fill_pattern(dstimg, x, y, w, h, patternimg);

    Fill the specified rectangle in the destination image with a
    pattern.

builtin sdl_keystat(keyname);

    Return '1' if the specified key is pressed and '0' if it isn't. The keynames
    are listed at:

    	http://www.libsdl.org/cgi/docwiki.cgi/SDLKey

    (lowercase versions of the SDLK_* strings without the SDLK_ prefix and with
    blanks instead of underscores)

builtin sdl_sprite_create();

    Usually, when doing SDL programming in C, everyone is creating his own SDL
    sprite library. This is possible when doing SDL programming with SDL to. But
    for performance reasons I recommend to use the built-in sprites of this
    module.

    This function returns a new sprite object. Such a sprite object has the
    following attributes:

    	.x
    		x-coordinate of the sprite (upper left corner)
    	.y
    		y-coordinate of the sprite (upper left corner)

    	.z
    		z-coordinate of the sprite.
    		sprites with higher values overlap sprites with lower values

    	.image
    		the image data for the sprite.
    		this must be set to one of SDL Image the object such as
    		returned by sdl_image_create().

builtin sdl_sprite_redraw();

    This redraws all sprites, also those which haven't been updated.

    This function is only needed if you are mixing sprites with direct blitting
    to the window. Usually sdl_sprite_update() is used instead.

    In some corner cases (when many sprites have been updated) this function
    might be faster than sdl_sprite_update(). But this is a very seldom
    case.

builtin sdl_sprite_update();

    This redraws all the updated sprites.

object SdlEx

    An instance of this object is thrown on SDL errors.

var SdlEx.description;

    A description text describing the error.

Generated by SPLDOC. | http://www.clifford.at/spl/