Class SDL[in The SDL Falcon Module.]

SDL wrapper class

class SDL

more...

Summary

SDL wrapper class

This class acts as a module wrapper for SDL functions. The vast majority of the "SDL_" C namespace is provided by this module through access to SDL class.

In example, to initialize the system through SDL_Init(), Falcon users should do the following:

   load sdl

   SDL.Init( /\* parameters *\/ )

Note: When using functions repeatedly, it is advisable to cache them to a local variable.

Methods

CreateCursor()

Gets currently active cursor.

SDL.CreateCursor( mbData, mbMask, width, height, Xspot, Yspot )

See SDL_CreateCursor documentation. Method SDL.MakeCursor is probably simpler to use.

CreateRGBSurface()

Creates a paintable surface

SDL.CreateRGBSurface( flags, width, height, depth, [rMask], [gMask], [bMask], [aMask] )

The function can be called either with 4 or 8 parameters. 8 bits per pixel modes don't require bit masks, and they are ignored if provided; other modes require a bitmask. If the values are not provided, this function calculates them using a R,G,B,A evenly spaced bitmap, which will place the bits stored in the lowest address in the red space. On big endian machines, red will be placed in the most signficant bits, on little endian it will be place on the least significant bits.

You should provide your own bitmap values if you don't want alpha surfaces.

The flags can be a combination of the following:

• SDL.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.
• SDL.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).
• SDL.SRCCOLORKEY - This flag turns on colourkeying for blits from this surface. If SDL_HWSURFACE is also specified and colourkeyed blits are hardware-accelerated, then SDL will attempt to place the surface in video memory. Use SDL_SetColorKey to set or clear this flag after surface creation.
• SDL.SRCALPHA - This flag turns on alpha-blending for blits from this surface. If SDL_HWSURFACE is also specified and alpha-blending blits are hardware-accelerated, then the surface will be placed in video memory if possible. Use SDL_SetAlpha to set or clear this flag after surface creation.

CreateRGBSurfaceFrom()

Creates a paintable surface using existing data.

SDL.CreateRGBSurfaceFrom( pixels, width, height, depth, [rMask], [gMask], [bMask], [aMask] )

EnableKeyRepeat()

Enable or disable key repeat and set key rate.

SDL.EnableKeyRepeat( delay, interval )

Enables or disables the keyboard repeat rate. delay specifies how long the key must be pressed before it begins repeating, it then repeats at the speed specified by interval. Both delay and interval are expressed in milliseconds.

Setting delay to 0 disables key repeating completely. Good default values are SDL.DEFAULT_REPEAT_DELAY and SDL.DEFAULT_REPEAT_INTERVAL.

EnableUNICODE()

Enable or disable translation from keys to Unicode characters.

SDL.EnableUNICODE( mode )

The parameter can be:

• 1: enable unicode translation
• 0: Disable unicode translation
• -1: Query current unicode status.

Falcon tunrs unicode translation ON at initialization, as characters in Falcon as treated as Unicode values, but it is possible to turn this off for better performance if character values are not needed.

EventState()

Query or change processing ability.

SDL.EventState( type, state )

This method queries and/or changes the current processing status of an event. Disabling an event means that it won't be notified to event handlers anymore, and it will be silently discarded.

It will still be possible to see the effect of that event by querying directly the event interface.

State can be set to one of the following:

• SDL.IGNORE: indicated event type will be automatically dropped from the event queue and will not be filtered.
• SDL_ENABLE: indicated event type will be processed normally.
• SDL_QUERY: SDL_EventState will return the current processing state of the specified event type.

GetAppState()

Gets current application state.

SDL.GetAppState( )

This function may return one of the following values:

• SDL_APPMOUSEFOCUS: The application has mouse focus.
• SDL_APPINPUTFOCUS: The application has keyboard focus
• SDL_APPACTIVE: The application is visible

GetCursor()

Gets currently active cursor.

SDL.GetCursor( )

This method returns the currently active cursor. It can be used to store this away and set it later.

GetGammaRamp()

Get Gamma ramps for this hardware.

SDL.GetGammaRamp( [aRet] )

This functions returns three membuf that maps directly the gamma correction table for the red, green and blue value.

Each membuf is a 2 bytes memory vector of 256 binary values.

GetKeyName()

Gets a SDL specific name for a ceratin key

SDL.GetKeyName( key )

GetKeyState()

Gets a memory buffer which reflects current keyboard scancodes status.

SDL.GetKeyState( )

This method returns a memory buffer in which each element represents the status of a key scan code. The index of the code is provided by the SDLK enumeration; if a given item in the membuf is 1, then the key is currently pressed, else it it is released.

This memory buffer is automaitcally updated when SDL.WaitEvent or SDL.PollEvent are called. If the program doesn't call those function, the SDL.PumpEvents method can be used to update current keyboard status.

Note: Calling this method more than once per program will cause cause useless duplication of the memory buffer.

GetModState()

Gets current keyboard modifier state.

SDL.GetModState( )

The returned integer is a bitfield where active modifiers bits are turned on. The values are those listed by the SDLKMOD enumeration.

GetMouseState()

Retreive mouse state

SDL.GetMouseState( MouseBuf, interval )

Enables or disables the keyboard repeat rate. delay specifies how long the key must be pressed before it begins repeating, it then repeats at the speed specified by interval. Both delay and interval are expressed in milliseconds.

Setting delay to 0 disables key repeating completely. Good default values are SDL.DEFAULT_REPEAT_DELAY and SDL.DEFAULT_REPEAT_INTERVAL.

GetVideoInfo()

Returns details about underlying video system.

SDL.GetVideoInfo( )

This function returns a read-only SDLVideoInfo instance containing informations about the video hardware.

If this is called before SDL_SetVideoMode, the vfmt member of the returned structure will contain the pixel format of the "best" video mode.

GetVideoSurface()

Retreives the current video surface.

SDL.GetVideoSurface( )

Init()

Initialize SDL system.

SDL.Init( flags )

This method initializes SDL. After initialization, it is necessary to call SDL.Quit() to clear the application state on exit; to avoid this need, it is possible to use the SDL.InitAuto Falcon extension.

Note: This "Init" method is not to be confused with Falcon language init statement.

The following initialization flags can be provided; to specify more than one flag, use bitwise or (pipe "|" operator):

• SDL.INIT_VIDEO: Initialize video subsystem.
• SDL.INIT_AUDIO: Initialize audio subsystem.
• SDL.INIT_TIMER: Prepare timers.
• SDL.INIT_CDROM: Initialize CDROM interface.
• SDL.INIT_JOYSTICK: Open joystick device.
• SDL.INIT_EVERYTHING: ... initialize everything...
• SDL.INIT_NOPARACHUTE: Do not intercept application critical signals (forced shutdowns).

As Falcon strings and character manipulation is mainly unicode, this init method automatically enables SDL unicode in event generation. If this is not desired, it is possible to call SDL.EnableUNICODE to disable it after init.

InitAuto()

Initialize SDL system and provide automatic cleanup.

SDL.InitAuto( flags )

This method initializes SDL, and sets up an handle for SDL cleanup. The returned handle has a Quit() method that can be called autonomously by the application i.e. to return to text mode and perform final screen output. In case of abnormal termination (i.e. on exception raise), the handle calls its Quit() method automatically right before being collected at VM termination. If the handle is stored in a global variable of the main module, it will stay alive until the VM exits, and then it will be called to properly reset SDL status.

IsBigEndian()

Returns true if the host system is big endian.

SDL.IsBigEndian( )

JoystickEventState()

Changes joystick event propagation settings.

SDL.JoystickEventState( mode )

This function is used to enable or disable joystick event processing. With joystick event processing disabled you will have to update joystick states with SDL.JoystickUpdate and read the joystick information manually. state is either SDL.QUERY, SDL.ENABLE or SDL.IGNORE.

Note: Joystick event handling is prefered

JoystickUpdate()

Updates the state(position, buttons, etc.) of all open joysticks.

SDL.JoystickUpdate( )

If joystick events have been enabled with SDL_JoystickEventState then this is called automatically in the event loop.

ListModes()

Returns a list of possible modes.

SDL.ListModes( [format], [flags] )

The function mimics the workings of SDL_ListModes, returning an array of pairs (2 element arrays) with x, y items, if a set of mode was found, nil if no mode is available and -1 if SDL says "all the modes" are available.

If passing nil as the desired pixel format, then the default screen pixel format will be used.

LoadBMP()

Loads an image from a BMP file.

SDL.LoadBMP( filename )

Loads an image from a BMP file and returns a new SDLSurface instance that can be manipulated through blit and similar functions.

The filename is totally subject to SDL rules, as it is simply passed to SDL engine. No Falcon URI parsing is perfomred before invoking SDL; as such, it is advisable to use this function only in simple applications.

MakeCursor()

Builds an SDL cursor taking an array of strings as input.

SDL.MakeCursor( aImage, hotX, hotY )

As it is generally quite hard to build a cursor writing directly its binary data, this helper method takes a set of strings in input and convers their visual representation to a valid cursor.

The strings must have a lenght mutliple of 8, as each of its element will fill a bit in the final cursor.

The hotspot coordinates must be equal to or smaller than the width and the height of the cursor. The width of the cursor is determined by the width of the strings, while its height is determined the size of the vector.

The characters in the image are considered as follows:

• "\@": white opaque pixel
• ".": black opaque pixel
• "X": reverse pixel (not always available)
• " ": transparent pixel.

In example, the following code generates a small cross with white borders, a reverse inner part and a small black shadow:

   strImage = [
      "         @XXX@          ",
      "         @XXX@          ",
      "         @XXX@          ",
      "         @X.X@          ",
      "  @@@@@@@@X.X@@@@@@@@   ",
      "  XXXXXXXXX.XXXXXXXXX.  ",
      "  XXXXXXXXX.XXXXXXXXX.  ",
      "  @@@@@@@@X.X@@@@@@@@.  ",
      "         @X.X@........  ",
      "         @XXX@.         ",
      "         @XXX@.         ",
      "         @XXX@.         ",
      "          ....          " ]

   SDL.MakeCursor( strImage, 12, 7 ).SetCursor()

PollEvent()

Polls for event and calls handlers if events are incoming.

SDL.PollEvent( )

This method checks the SDL event queue, and if an event is ready for processing, it calls the handler provided by this instance.

To provide event handlers, it is necessary to derive a subclass from SDLEventHandler overloading the callbacks that must be handled, and then call PollEvent or WaitEvent on the instance.

If there isn't any event to be processed, this method returns immediately false.

PumpEvents()

Update event listing and queueing during long operations.

SDL.PumpEvents( )

Normally, a responsive SDL-Falcon program should issue a SDL.WaitEvent loop in its main code to start marshalling events to listeners, but it is also possible to periodically poll the status of keyboard and other devices with direct query functions.

To ensure the status is updated even when not calling WaitEvents, this method can be called. This will update all the internal device status representation, that will be then accurate if queried soon after.

Quit()

Turns off SDL system.

SDL.Quit( )

This call shuts down SDL and resets system status. It is possible to turn off only some subsystems using the \a SDL.QuitSubSystem function.

QuitSubSystem()

Shuts down a subset of SDL.

SDL.QuitSubSystem( subsys )

This call shuts down one or more SDL subsystems.

SetGamma()

Sets the gamma function values for the active SDL output.

SDL.SetGamma( red, green, blue )

SetGammaRamp()

Set Gamma ramps for this hardware.

SDL.SetGammaRamp( redbuf, greenbuf, bluebuf )

Each membuf is a 2 bytes memory vector of 256 binary values. If one of the channels needs not to be changed, nil can be placed instead.

SetModState()

Sets current keyboard modifier state.

SDL.SetModState( state )

This method will alter the keyboard modifier state for the application. The state parameter can be a or'd combination of SDLKMOD enumeration elements.

SetVideoMode()

Changes the video mode and/or starts SDL context window.

SDL.SetVideoMode( width, height, [bpp], [flags] )

This function starts a graphic video mode and, on success, returns a SDLScreen class instance. This class is a Falcon object which encapsulate SDL_Surface structures, and has specific accessors and methods to handle the special SDL_Surface that is considered a "screen" by SDL.

Flags can be one of the following value; also, some or'd combinations are possible.

• SDL.SWSURFACE
• SDL.HWSURFACE
• SDL.ASYNCBLIT
• SDL.ANYFORMAT
• SDL.HWPALETTE
• SDL.DOUBLEBUF
• SDL.FULLSCREEN
• SDL.OPENGL
• SDL.OPENGLBLIT
• SDL.RESIZABLE
• SDL.NOFRAME

For a complete explanation of the flags, please refer to SDL official documentation.

ShowCursor()

Changes or query the visibility of the mouse cursor.

SDL.ShowCursor( [request] )

Toggle whether or not the cursor is shown on the screen. Passing SDL.ENABLE displays the cursor and passing SDL.DISABLE hides it. The current state of the mouse cursor can be queried by passing SDL.QUERY, either SDL.DISABLE or SDL.ENABLE will be returned.

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

If the request parameter is not given, it defaults to SDL.ENABLE.

StartEvents()

Stats dispatching of SDL events to this VM.

SDL.StartEvents( )

This automatically starts an event listen loop on this virtual machine. Events are routed through the standard broadcasts.

If a previous event listener thread, eventually on a different virtual machine, was active, it is stopped.

Events are generated as broadcast message that can be received via standard subscribe.

StopEvents()

Stops dispatching of SDL events.

SDL.StopEvents( )

This immediately stops dispatching events. It is NOT necessary to perform this call before closing a program, but a VM may want to start manage events on its own, or to ignore them.

If asynchronous event dispatching wasn't active, this call has no effect.

VideoDriverName()

Returns the name of the used video driver.

SDL.VideoDriverName( )

VideoModeOK()

Verifies if a given video mode is ok

SDL.VideoModeOK( width, height, [bpp], [flags] )

The function can be used to checked if a video mode can be used prior to starting it. If the mode is available, a preferred bit per pixel value is returned, otherwise the function returns zero.

WM_GetCaption()

Get Caption for SDL window and for window icon.

SDL.WM_GetCaption( )

WM_GrabInput()

Grabs window and mouse input.

SDL.WM_GrabInput( [grab] )

The request can be one of the following:

• SDL.GRAB_QUERY - requests current status without changing it.
• SDL.GRAB_OFF - disable grabbing.
• SDL.GRAB_ON - enable grabbing.

Grab request defaults to SDL.GRAB_ON

WM_IconifyWindow()

Get Caption for SDL window and for window icon.

SDL.WM_IconifyWindow( )

WM_SetCaption()

Set Caption for SDL window and for window icon.

SDL.WM_SetCaption( caption, [icon] )

If the icon caption is not given, it will default to caption.

WaitEvent()

Waits forever until an event is received.

SDL.WaitEvent( )

This method blocks the current coroutine until a SDL event is received. However, the VM is able to proceed with other coroutines.

As soon as a message is received and processed, the function returns, so it is possible to set a global flag in the message processors to communicate new program status to the subsequent code.

In example, the following is a minimal responsive SDL Falcon application.

   object handler
      shouldQuit = false

      function on_sdl_Quit()
         self.shouldQuit = true
      end
   end

   ...
   ...
   
   // main code
   subscribe( "sdl_Quit", handler )
   
   while not handler.shouldQuit
      SDL.WaitEvent()
   end

Note: You can also start an automatic event listener and dispatcher in a parallel thread with SDL.StartEvents. This will oviate the need for a polling or waiting loop.

WasInit()

Detects if some SDL subsystem was initialized.

SDL.WasInit( [flags] )

The parameter defautls to SDL_INIT_EVERYTHING if not provided.