Module "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);
--------------------------------

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.
 
