Add a timer which will call a callback after the specified number of milliseconds has elapsed

Adds a callback function to be run after the specified number of milliseconds has elapsed. The callback function is passed the current timer interval and the user supplied parameter from the add_timer call and returns the next timer interval. If the returned value from the callback is the same as the one passed in, the periodic alarm continues, otherwise a new alarm is scheduled.

To cancel a currently running timer call RemoveTimer with the timer ID returned from AddTimer.

The timer callback function may run in a different thread than your main program, and so shouldn't call any functions from within itself. You may always call PushEvent, however.

The granularity of the timer is platform-dependent, but you should count on it being at least 10 ms as this is the most common number. This means that if you request a 16 ms timer, your callback will run approximately 20 ms later on an unloaded system. If you wanted to set a flag signaling a frame update at 30 frames per second (every 33 ms), you might set a timer for 30 ms (see example below). If you use this function, you need to pass INIT_TIMER to Init.

Returns an ID value for the added timer or nil if there was an error.

Original name: SDL_AddTimer

Clears any previous error message for this thread.

Original name: SDL_ClearError

Shuts down audio processing and closes the audio device.

This function shuts down audio processing and closes the audio device.

Original name: SDL_CloseAudio

Create an empty Surface.

Allocate an empty surface (must be called after SetVideoMode).

If depth is 8 bits an empty palette is allocated for the surface, otherwise a 'packed-pixel' PixelFormat is created using the [RGBA]mask's provided (see PixelFormat). The flags specifies the type of surface that should be created, it is an OR'd combination of the following possible values.

SWSURFACE: SDL will create the surface in system memory. This improves the performance of pixel level access, however you may not be able to take advantage of some types of hardware blitting. HWSURFACE: SDL will attempt to create the surface in video memory. This will allow SDL to take advantage of Video->Video blits (which are often accelerated). SRCCOLORKEY: This flag turns on colourkeying for blits from this surface. If HWSURFACE is also specified and colourkeyed blits are hardware-accelerated, then SDL will attempt to place the surface in video memory. Use SetColorKey to set or clear this flag after surface creation. SRCALPHA: This flag turns on alpha-blending for blits from this surface. If HWSURFACE is also specified and alpha-blending blits are hardware-accelerated, then the surface will be placed in video memory if possible. Use SetAlpha to set or clear this flag after surface creation.

Returns the created surface, or nil upon error.

# Create a 32-bit surface with the bytes of each pixel in R,G,B,A order,
# as expected by OpenGL for textures.

# SDL interprets each pixel as a 32-bit number, so our masks must depend
# on the endianness (byte order) of the machine.
when cpuEndian == bigEndian:
  let rmask = 0xff000000
  let gmask = 0x00ff0000
  let bmask = 0x0000ff00
  let amask = 0x000000ff
else:
  let rmask = 0x000000ff
  let gmask = 0x0000ff00
  let bmask = 0x00ff0000
  let amask = 0xff000000

let surface = create_rgb_surface(SWSURFACE, width, height, 32,
                                 rmask, gmask, bmask, amask)
if surface == nil:
  echo "CreateRGBSurface failed: ", get_error()
  quit QuitFailure

Original name: SDL_CreateRGBSurface

Create an empty Surface with flags set to SWSURFACE.

See create_rgb_surface.

Create an Surface from pixel data.

Creates an Surface from the provided pixel data.

The data stored in pixels is assumed to be of the depth specified in the parameter list. The pixel data is not copied into the Surface structure so it should not be freed until the surface has been freed with a called to free. pitch is the length of each scanline in bytes.

See create_rgb_surface for a more detailed description of the other parameters.

Returns the created surface, or nil upon error.

Original name: SDL_CreateRGBSurfaceFrom

Wait a specified number of milliseconds before returning.

Wait a specified number of milliseconds before returning. Delay will wait at least the specified time, but possible longer due to OS scheduling.

Original name: SDL_Delay

Set the state of processing events.

Return true if the event was enable prior calling this function, false otherwise.

Uint8 SDL_EventState(Uint8 type, int state);

Swaps screen buffers.

On hardware that supports double-buffering, this function sets up a flip and returns. The hardware will wait for vertical retrace, and then swap video buffers before the next video surface blit or lock will return. On hardware that doesn't support double-buffering, this is equivalent to calling UpdateRect (screen, 0, 0, 0, 0).

The DOUBLEBUF flag must have been passed to SetVideoMode, when setting the video mode for this function to perform hardware flipping.

This function returns true if successful, or false if there was an error.

Original name: SDL_Flip

Frees (deletes) a Surface.

Frees the resources used by a previously created Surface. If the surface was created using CreateRGBSurfaceFrom then the pixel data is not freed.

Original name: SDL_FreeSurface

Get the current audio state.

Returns either AUDIO_STOPPED, AUDIO_PAUSED or AUDIO_PLAYING depending on the current audio state.

Original name: SDL_GetAudioStatus

Get SDL error string.

get_error returns a string containing information about the last internal SDL error.

get_error returns a string containing the last error.

Original name: SDL_GetError

Get the number of milliseconds since the SDL library initialization.

Get the number of milliseconds since the SDL library initialization. Note that this value wraps if the program runs for more than ~49 days.

Original name: SDL_GetTicks

Returns a pointer to information about the video hardware.

This function returns a read-only pointer to information about the video hardware. If this is called before SetVideoMode, the vfmt member of the returned structure will contain the pixel format of the "best" video mode.

Original name: SDL_GetVideoInfo

Returns a pointer to the current display surface.

This function returns a pointer to the current display surface. If SDL is doing format conversion on the display surface, this function returns the publicly visible surface, not the real video surface.

Original name: SDL_GetVideoSurface

Initializes SDL.

Initializes SDL. This should be called before all other SDL functions. The flags parameter specifies what part(s) of SDL to initialize.

• INIT_TIMER: Initializes the timer subsystem.
• INIT_AUDIO: Initializes the audio subsystem.
• INIT_VIDEO: Initializes the video subsystem.
• INIT_CDROM: Initializes the cdrom subsystem.
• INIT_JOYSTICK: Initializes the joystick subsystem.
• INIT_EVERYTHING: Initialize all of the above.
• INIT_NOPARACHUTE: Prevents SDL from catching fatal signals.
• INIT_EVENTTHREAD

Returns false on an error or true on success.

Original name: SDL_Init

Initialize subsystems.

After SDL has been initialized with Init you may initialize uninitialized subsystems with init_sub_system. The flags parameter is the same as that used in Init.

Returns false on an error or true on success.

Original name: SDL_InitSubSystem

Updates the state of all joysticks.

Updates the state(position, buttons, etc.) of all open joysticks. If joystick events have been enabled with JoystickEventState then this is called automatically in the event loop.

Original name: SDL_JoystickUpdate

Return SDL linked version.

Returns tuple of (major, minor, patch).

Original name: SDL_Linked_Version

Returns a seq of available screen dimensions for the given video flags.

Return a seq of available screen dimensions for the given video flags, sorted largest to smallest. Returns empty seq if there are no dimensions available for a particular flags, or seq of (-1, -1) if any dimension is okay for the given flags.

The mode list will be for the format returned by get_video_info().vfmt. The flag parameter is an OR'd combination of surface flags. The flags are the same as those used SetVideoMode and they play a strong role in deciding what modes are valid. For instance, if you pass HWSURFACE as a flag only modes that support hardware video surfaces will be returned.

Original name: SDL_ListModes

Returns a seq of available screen dimensions for the given format and video flags.

Return a seq of available screen dimensions for the given format and video flags, sorted largest to smallest. Returns empty seq if there are no dimensions available for a particular format, or seq of (-1, -1) if any dimension is okay for the given format.

The flag parameter is an OR'd combination of surface flags. The flags are the same as those used SetVideoMode and they play a strong role in deciding what modes are valid. For instance, if you pass HWSURFACE as a flag only modes that support hardware video surfaces will be returned.

Original name: SDL_ListModes

Lock a surface for directly access.

lock sets up a surface for directly accessing the pixels. Between calls to LockSurface and UnlockSurface, you can write to and read from surface.pixels, using the pixel format stored in surface.format. Once you are done accessing the surface, you should use UnlockSurface to release it.

Not all surfaces require locking. If MUSTLOCK (surface) evaluates to false, then you can read and write to the surface at any time, and the pixel format of the surface will not change.

No operating system or library calls should be made between lock/unlock pairs, as critical system locks may be held during this time.

It should be noted, that since SDL 1.1.8 surface locks are recursive. This means that you can lock a surface multiple times, but each lock must have a match unlock.

lock surface

# Surface is locked.
# Direct pixel access on surface here.

lock surface

# More direct pixel access on surface.

unlock surface
# Surface is still locked.
# Note: Is versions < 1.1.8, the surface would have been
# no longer locked at this stage.

unlock surface
# Surface is now unlocked.

Returns true, or false if the surface couldn't be locked.

Original name: SDL_LockSurface

Map a RGB color value to a pixel format.

Maps the RGB color value to the specified pixel format and returns the pixel value as a 32-bit int.

If the format has a palette (8-bit) the index of the closest matching color in the palette will be returned.

If the specified pixel format has an alpha component it will be returned as all 1 bits (fully opaque).

Returns a pixel value best approximating the given RGB color value for a given pixel format. If the pixel format bpp (color depth) is less than 32-bpp then the unused upper bits of the return value can safely be ignored (e.g., with a 16-bpp format the return value can be assigned to a uint16, and similarly a uint8 for an 8-bpp format).

Original name: SDL_MapRGB

Map a RGBA color value to a pixel format.

Maps the RGBA color value to the specified pixel format and returns the pixel value as a 32-bit int.

If the format has a palette (8-bit) the index of the closest matching color in the palette will be returned.

If the specified pixel format has no alpha component the alpha value will be ignored (as it will be in formats with a palette).

Returns a pixel value best approximating the given RGBA color value for a given pixel format. If the pixel format bpp (color depth) is less than 32-bpp then the unused upper bits of the return value can safely be ignored (e.g., with a 16-bpp format the return value can be assigned to a uint16, and similarly a uint8 for an 8-bpp format.

Original name: SDL_MapRGBA

Mix audio data.

This function takes two audio buffers of len bytes each of the playing audio format and mixes them, performing addition, volume adjustment, and overflow clipping. The volume ranges from 0 to MIX_MAXVOLUME and should be set to the maximum value for full audio volume. Note this does not change hardware volume. This is provided for convenience -- you can mix your own audio data.

Do not use this function for mixing together more than two streams of sample data. The output from repeated application of this function may be distorted by clipping, because there is no accumulator with greater range than the input (not to mention this being an inefficient way of doing it). Use mixing functions from SDL_mixer, OpenAL, or write your own mixer instead.

Original name: SDL_MixAudio.

Pauses and unpauses the audio callback processing.

This function pauses and unpauses the audio callback processing. It should be called with pause_on=false after opening the audio device to start playing sound. This is so you can safely initialize data for your callback function after opening the audio device. Silence will be written to the audio device during the pause.

Original name: SDL_PauseAudio.

Pushes an event onto the event queue.

The event queue can actually be used as a two way communication channel. Not only can events be read from the queue, but the user can also push their own events onto it. event is a pointer to the event structure you wish to push onto the queue.

Returns true on success or false if the event couldn't be pushed.

Original name: SDL_PushEvent

Shut down SDL.

quit_sdl shuts down all SDL subsystems and frees the resources allocated to them. This should always be called before you exit.

Original name: SDL_Quit

Shut down a subsystem.

QuitSubSystem allows you to shut down a subsystem that has been previously initialized by Init or InitSubSystem. The flags tells quit_sub_system which subsystems to shut down, it uses the same values that are passed to Init.

Original name: SDL_QuitSubSystem

Sets the color key (transparent pixel) in a blittable surface and RLE acceleration.

Sets the color key (transparent pixel) in a blittable surface and enables or disables RLE blit acceleration.

RLE acceleration can substantially speed up blitting of images with large horizontal runs of transparent pixels (i.e., pixels that match the key value). The key must be of the same pixel format as the surface, MapRGB is often useful for obtaining an acceptable value.

If flag is SRCCOLORKEY then key is the transparent pixel value in the source image of a blit.

If flag is OR'd with RLEACCEL then the surface will be draw using RLE acceleration when drawn with BlitSurface. The surface will actually be encoded for RLE acceleration the first time BlitSurface or DisplayFormat is called on the surface.

If flag is SWSURFACE, this function clears any current color key.

This function returns true, or false if there was an error.

Original name: SDL_SetColorKey

Set the SDL error message for the current thread.

Original name: SDL_SetError

Sets the color gamma function for the display.

Sets the "gamma function" for the display of each color component. Gamma controls the brightness/contrast of colors displayed on the screen. A gamma value of 1.0 is identity (i.e., no adjustment is made).

This function adjusts the gamma based on the "gamma function" parameter, you can directly specify lookup tables for gamma adjustment with SetGammaRamp.

Not all display hardware is able to change gamma.

Returns false on error (or if gamma adjustment is not supported).

Original name: SDL_SetGamma

Sets the color gamma lookup tables for the display.

Sets the gamma lookup tables for the display for each color component. Each table is an array of 256 uint16 values, representing a mapping between the input and output for that channel. The input is the index into the array, and the output is the 16-bit gamma value at that index, scaled to the output color precision. You may pass NULL (@@@) to any of the channels to leave them unchanged.

This function adjusts the gamma based on lookup tables, you can also have the gamma calculated based on a "gamma function" parameter with SetGamma.

Not all display hardware is able to change gamma.

Returns false on error (or if gamma adjustment is not supported.

Original name: SDL_SetGammaRamp

int SDL_SetPalette(SDL_Surface *surface, int flags, SDL_Color *colors,
                   int firstcolor, int ncolors);

Set a callback to run after the specified number of milliseconds has elapsed.

Set a callback to run after the specified number of milliseconds has elapsed. The callback function is passed the current timer interval and returns the next timer interval. If the returned value is the same as the one passed in, the periodic alarm continues, otherwise a new alarm is scheduled.

To cancel a currently running timer, call set_timer(0, nil).

The timer callback function may run in a different thread than your main constant, and so shouldn't call any functions from within itself.

The maximum resolution of this timer is 10 ms, which means that if you request a 16 ms timer, your callback will run approximately 20 ms later on an unloaded system. If you wanted to set a flag signaling a frame update at 30 frames per second (every 33 ms), you might set a timer for 30 ms (see example below).

If you use this function, you need to pass INIT_TIMER to Init.

set_timer((33 div 10) * 10, my_callback)

Original name: SDL_SetTimer

Set up a video mode with the specified width, height and bits-per-pixel.

If bpp is 0, it is treated as the current display bits per pixel.

The flags parameter is the same as the flags field of the SurfacePtr structure. OR'd combinations of the following values are valid.

• SWSURFACE: Create the video surface in system memory
• HWSURFACE: Create the video surface in video memory
• ASYNCBLIT: Enables the use of asynchronous updates of the display surface. This will usually slow down blitting on single CPU machines, but may provide a speed increase on SMP systems.
• ANYFORMAT: Normally, if a video surface of the requested bits-per-pixel (bpp) is not available, SDL will emulate one with a shadow surface. Passing ANYFORMAT prevents this and causes SDL to use the video surface, regardless of its pixel depth.
• HWPALETTE: Give SDL exclusive palette access. Without this flag you may not always get the the colors you request with SetColors or SetPalette.
• DOUBLEBUF: Enable hardware double buffering; only valid with HWSURFACE. Calling Flip will flip the buffers and update the screen. All drawing will take place on the surface that is not displayed at the moment. If double buffering could not be enabled then Flip will just perform a UpdateRect on the entire screen.
• FULLSCREEN: SDL will attempt to use a fullscreen mode. If a hardware resolution change is not possible (for whatever reason), the next higher resolution will be used and the display window centered on a black background.
• OPENGL: Create an OpenGL rendering context. You should have previously set OpenGL video attributes with gl_set_attribute.
• OPENGLBLIT: Create an OpenGL rendering context, like above, but allow normal blitting operations. The screen (2D) surface may have an alpha channel, and UpdateRects must be used for updating changes to the screen surface. NOTE: This option is kept for compatibility only, and is not recommended for new code.
• RESIZABLE: Create a resizable window. When the window is resized by the user a VIDEORESIZE event is generated and SetVideoMode can be called again with the new size.
• NOFRAME: If possible, NOFRAME causes SDL to create a window with no title bar or frame decoration. Fullscreen modes automatically have this flag set.

Returns the framebuffer surface, or nil if it fails. The surface returned is freed by Quit and should nt be freed by the caller.

Original name: SDL_SetVideoMode

Toggle whether or not the cursor is shown on the screen.

Toggle whether or not the cursor is shown on the screen. Passing true displays the cursor and passing false hides it.

The cursor starts off displayed, but can be turned off.

Returns the current state of the cursor.

Original name: SDL_ShowCursor

Unlocks a previously locked surface.

Surfaces that were previously locked using LockSurface must be unlocked with UnlockSurface. Surfaces should be unlocked as soon as possible.

It should be noted that since 1.1.8, surface locks are recursive. See LockSurface.

Original name: SDL_UnlockSurface

Returns a pointer to information about the video hardware.

This function returns a read-only pointer to information about the video hardware. If this is called before SetVideoMode, the vfmt member of the returned structure will contain the pixel format of the "best" video mode.

Original name: SDL_VideoDriverName

Set the position of the mouse cursor.

Set the position of the mouse cursor (generates a mouse motion event).

Original name: SDL_WarpMouse

Check which subsystems are initialized.

was_init allows you to see which SDL subsytems have been initialized. flags is a bitwise OR'd combination of the subsystems you wish to check (see Init for a list of subsystem flags).

WasInit returns a bitwised OR'd combination of the initialized subsystems.

Original name: SDL_WasInit

Gets the window title and icon name.

Returns window title and icon name.

Original name: SDL_WM_GetCaption

Grabs mouse and keyboard input.

Grabbing means that the mouse is confined to the application window, and nearly all keyboard input is passed directly to the application, and not interpreted by a window manager, if any.

When mode is GRAB_QUERY the grab mode is not changed, but the current grab mode is returned.

Original name: SDL_WM_GrabInput

Iconify/minimize the window.

If the application is running in a window managed environment SDL attempts to iconify/minimize it. If wm_iconify_window is successful, the application will receive a APPACTIVE loss event.

Returns true on success or false if iconification is not support or was refused by the window manager

Original name: SDL_WM_IconifyWindow

Sets the window tile and icon name.

Sets the title-bar and icon name of the display window.

Original name: SDL_WM_SetCaption

Sets the icon for the display window.

Sets the icon for the display window. Win32 icons must be 32x32.

This function must be called before the first call to SetVideoMode.

The shape is determined by the colorkey of icon, if any, or makes the icon rectangular (no transparency) otherwise.

wm_set_icon load_bmp("icon.bmp)

Original name: SDL_WM_SetIcon

Sets the icon for the display window.

Sets the icon for the display window. Win32 icons must be 32x32.

This function must be called before the first call to SetVideoMode.

The mask is a bitmask that describes the shape of the icon.

The mask points to a bitmap with bits set where the corresponding pixel should be visible. The format of the bitmap is as follows: Scanlines come in the usual top-down order. Each scanline consists of (width div 8) bytes, rounded up. The most significant bit of each byte represents the leftmost pixel.

Original name: SDL_WM_SetIcon

Toggles fullscreen mode.

Toggles the application between windowed and fullscreen mode, if supported. (X11 is the only target currently supported, BeOS support is experimental).

Returns false on failure or true on success.

Original name: SDL_WM_ToggleFullScreen

#define SDL_AllocSurface SDL_CreateRGBSurface