SDL(3) User Contributed Perl Documentation SDL(3)
NAME
SDL_perl - Simple DirectMedia Layer for Perl
DISCLAIMER
First to clarify:
THIS IS THE LAST RELEASE OF THIS API.
That said we are actively redesigning the SDL Bindings on the redesign branch here:
git://github.com/kthakore/SDL_perl.git
The newrelease will break backwards compatibility. We recommend you try the redesign branch to get a head start on any new code you are
developing.
SYNOPSIS
use SDL;
DESCRIPTION
SDL_perl is a package of perl modules that provides both functional and object orient interfaces to the Simple DirectMedia Layer for Perl
5. This package does take some liberties with the SDL API, and attempts to adhere to the spirit of both the SDL and Perl. This document
describes the low-level functional SDL_perl API. For the object oriented programming interface please see the documentation provided on a
per class basis.
The SDL Perl 2009 Development Team
Documentation
Nick: magnet
Perl Development
Nick: Garu
Name: Breno G. de Oliveira
Nick: Dngor
Name: Rocco Caputo
Nick: nferraz
Name: Nelson Ferraz
Maintainance
Nick: kthakore
Name: Kartik Thakore
MacOSX Experimental Usage
Please get libsdl packages from Fink
perl Build.PL
perl Build test
perl Build bundle
perl Build install
Running SDL Perl Scripts in MacOSX
First set the PERL5LIB environment variable to the dependencies of your script
%export PERL5LIB=$PERL5LIB:./lib
Use the SDLPerl executable made in the bundle and call your scripts
%SDLPerl.app/Contents/MacOS/SDLPerl yourScript.pl
Functions exported by SDL.pm
Init(flags)
As with the C language API, SDL_perl initializes the SDL environment through the "SDL::Init" subroutine. This routine takes a mode flag
constructed through the bitwise OR product of the following functions:
o INIT_AUDIO()
o INIT_VIDEO()
o INIT_CDROM()
o INIT_EVERYTHING()
o INIT_NOPARACHUTE()
o INIT_JOYSTICK()
o INIT_TIMER()
"SDL::Init" returns 0 on success, or -1 on error.
GetError()
The last error message set by the SDL library can be retrieved using the subroutine "SDL::GetError", which returns a scalar containing the
text of the message if any.
Delay(ms)
This subroutine allows an application to delay further operations for atleast a number of milliseconds provided as the argument. The
actual delay may be longer than the specified depending on the underlying OS.
GetTicks()
An application may retrieve the number of milliseconds expired since the initilization of the application through this subroutine. This
value resets rougly ever 49 days.
AddTimer(interval,callback,param)
"AddTimer" will register a SDL_NewTimerCallback function to be executed after "interval" milliseconds, with parameter "param".
SDL_NewTimerCallback objects can be constructed with the "NewTimer" subroutine. "SDL::PerlTimerCallback" will return a valid callback for
executing a perl subroutine or closure. This subroutine returns a SDL_TimerID for the newly registered callback, or NULL on error.
NewTimer(interval,subroutine)
The "NewTimer" takes an interval in milliseconds and a reference to a subroutine to call at that interval. The subroutine will be invoked
in a void context and accepts no parameters. The callback used is that returned by "SDL::PerlTimerCallback". "NewTimer" returns the
SDL_TimerID for the new timer or NULL on error.
RemoveTimer(id)
This subroutine taks a SDL_TimerID and removes it from the list of active callbacks. RemoveTimer returns false on failure.
SetTimer
This subroutine is depreciated, please use "NewTimer" or "AddTimer" instead.
CDNumDrives()
"SDL::CDNumDrives" returns the number of available CD-ROM drives in the system.
CDName(drive)
The subroutine "SDL::CDName" returns the system specific human readable device name for the given CD-ROM drive.
CDOpen(drive)
This subroutine opens a CD-ROM drive for access, returning NULL if the drive is busy or otherwise unavailable. On success this subroutine
returns a handle to the CD-ROM drive.
CDTrackListing(cd)
"SDL::CDTrackListing" returns a human readable description of a CD-ROM. For each track one line will be produced with the following
format:
Track index: %d, id %d, %2d.%2d
This is provided to ease the creation of human readable descriptions and debugging.
CDTrackId(track)
"CDTrackId" returns the id field of the given SDL_CDtrack structure.
CDTrackType(track)
"CDTrackType" returns the type field of the given SDL_CDtrack structure.
CDTrackLength(track)
"CDTrackLength" returns the length field of the given SDL_CDtrack structure.
CDTrackOffset(track)
"CDTrackOffset" returns the offset field of the given SDL_CDtrack structure.
CDStatus(cd)
The function "CDStatus" returns the current status of the given SDL_CDrom. "CDStatus"'s return values are:
o CD_TRAYEMPTY
o CD_PLAYING
o CD_STOPPED
o CD_PAUSED
o CD_ERROR
CDPlayTracks(cd,track,tracks,frame,frames)
To start playing from an arbitrary portion of a CD, one can provide "SDL::CDPlayTracks" with a CD, a starting track, the number of tracks,
a starting frame, and the number of frames to be played.
CDPlay(cd,track,length)
"SDL::CDPlay" plays the next "length" tracks starting from "track"
CDPause(cd)
This function will pause CD playback until resume is called.
CDResume(cd)
This function will resume CD playback if paused.
CDStop(cd)
"SDL::CDStop" will stop CD playback if playing.
CDEject(cd)
This function will eject the CD.
CDClose(cd)
This function will release an opened CD.
CDNumTracks
This function return the number of tracks on a CD, it take a SDL_CD as first parameter.
CDCurTrack
This function return the number of the current track on a CD, it take a SDL_CD as first parameter.
CDCurFrame
this function return the frame offset within the current track on a CD. it take a SDL_CD as first parameter.
CDTrack
CDtrack stores data on each track on a CD, its fields should be pretty self explainatory. CDtrack take a SDL::CD as input and return a
SDL_CDTrack.
PumpEvents
Pumps the event loop, gathering events from the input devices.
PumpEvents gathers all the pending input information from devices and places it on the event queue. Without calls to PumpEvents no events
would ever be placed on the queue. Often the need for calls to PumpEvents is hidden from the user since " PollEvent" and WaitEvent
implicitly call PumpEvents. However, if you are not polling or waiting for events (e.g. you are filtering them), then you must call
PumpEvents to force an event queue update. PumpEvents doesn't return any value and doesn't take any parameters.
Note: You can only call this function in the thread that set the video mode.
NewEvent
Create a new event.It return a SDL::Event.
FreeEvent
FreeEvent delete the SDL::Event given as first parameter. it doesn't return anything.
PollEvent
Polls for currently pending events. If event is not undef, the next event is removed from the queue and returned as a " SDL::Event". As
this function implicitly calls " PumpEvents", you can only call this function in the thread that set the video mode. it take a SDL::Event
as first parameter.
WaitEvent
Waits indefinitely for the next available event, returning undef if there was an error while waiting for events, a " SDL::Event" otherwise.
If event is not NULL, the next event is removed. As this function implicitly calls " PumpEvents", you can only call this function in the
thread that set the video mode. WaitEvent take a SDL::Event as first parameter.
EventState
This function allows you to set the state of processing certain event types.
it take an event type as first argument, and a state as second.
If state is set to SDL_IGNORE, that event type will be automatically dropped from the event queue and will not be filtered. If state is
set to SDL_ENABLE, that event type will be processed normally. If state is set to SDL_QUERY, SDL_EventState will return the current
processing state of the specified event type.
A list of event types can be found in the " SDL_Event section".
it returns a state(?).
IGNORE
ENABLE
QUERY
ACTIVEEVENT
KEYDOWN
KEYUP
MOUSEMOTION
MOUSEBUTTONDOWN
MOUSEBUTTONUP
QUIT
SYSWMEVENT
EventType
EventType return the type of the SDL::Event given as first parameter.
ActiveEventGain
ActiveEventGain return the active gain from the SDL::Event given as first parameter. see " SDL::Event" for more informations about the
active state.
ActiveEventState
ActiveEventState return the active state from the SDL::Event given as first parameter. see " SDL::Event" for more informations about the
active state.
APPMOUSEFOCUS
APPINPUTFOCUS
APPACTIVE
KeyEventState
KeyEventState return the active key state from the SDL::Event given as first parameter. see " SDL::Event" for me more informations about
the active key.
SDLK_BACKSPACE
SDLK_TAB
SDLK_CLEAR
SDLK_RETURN
SDLK_PAUSE
SDLK_ESCAPE
SDLK_SPACE
SDLK_EXCLAIM
SDLK_QUOTEDBL
SDLK_HASH
SDLK_DOLLAR
SDLK_AMPERSAND
SDLK_QUOTE
SDLK_LEFTPAREN
SDLK_RIGHTPAREN
SDLK_ASTERISK
SDLK_PLUS
SDLK_COMMA
SDLK_MINUS
SDLK_PERIOD
SDLK_SLASH
SDLK_0
SDLK_1
SDLK_2
SDLK_3
SDLK_4
SDLK_5
SDLK_6
SDLK_7
SDLK_8
SDLK_9
SDLK_COLON
SDLK_SEMICOLON
SDLK_LESS
SDLK_EQUALS
SDLK_GREATER
SDLK_QUESTION
SDLK_AT
SDLK_LEFTBRACKET
SDLK_BACKSLASH
SDLK_RIGHTBRACKET
SDLK_CARET
SDLK_UNDERSCORE
SDLK_BACKQUOTE
SDLK_a
SDLK_b
SDLK_c
SDLK_d
SDLK_e
SDLK_f
SDLK_g
SDLK_h
SDLK_i
SDLK_j
SDLK_k
SDLK_l
SDLK_m
SDLK_n
SDLK_o
SDLK_p
SDLK_q
SDLK_r
SDLK_s
SDLK_t
SDLK_u
SDLK_v
SDLK_w
SDLK_x
SDLK_y
SDLK_z
SDLK_DELETE
SDLK_KP0
SDLK_KP1
SDLK_KP2
SDLK_KP3
SDLK_KP4
SDLK_KP5
SDLK_KP6
SDLK_KP7
SDLK_KP8
SDLK_KP9
SDLK_KP_PERIOD
SDLK_KP_DIVIDE
SDLK_KP_MULTIPLY
SDLK_KP_MINUS
SDLK_KP_PLUS
SDLK_KP_ENTER
SDLK_KP_EQUALS
SDLK_UP
SDLK_DOWN
SDLK_RIGHT
SDLK_LEFT
SDLK_INSERT
SDLK_HOME
SDLK_END
SDLK_PAGEUP
SDLK_PAGEDOWN
SDLK_F1
SDLK_F2
SDLK_F3
SDLK_F4
SDLK_F5
SDLK_F6
SDLK_F7
SDLK_F8
SDLK_F9
SDLK_F10
SDLK_F11
SDLK_F12
SDLK_F13
SDLK_F14
SDLK_F15
SDLK_NUMLOCK
SDLK_CAPSLOCK
SDLK_SCROLLOCK
SDLK_RSHIFT
SDLK_LSHIFT
SDLK_RCTRL
SDLK_LCTRL
SDLK_RALT
SDLK_LALT
SDLK_RMETA
SDLK_LMETA
SDLK_LSUPER
SDLK_RSUPER
SDLK_MODE
SDLK_HELP
SDLK_PRINT
SDLK_SYSREQ
SDLK_BREAK
SDLK_MENU
SDLK_POWER
SDLK_EURO
KMOD_NONE
KMOD_NUM
KMOD_CAPS
KMOD_LCTRL
KMOD_RCTRL
KMOD_RSHIFT
KMOD_LSHIFT
KMOD_RALT
KMOD_LALT
KMOD_CTRL
KMOD_SHIFT
KMOD_ALT
KeyEventSym
KeyEventSym return the key pressed/released information from the SDL::Event given as first parameter. see " SDL::Event" for more
informations about the keyboard events.
KeyEventMod
KeyEventMod return the mod keys pressed information from the SDL::Event given as first parameter. see " SDL::Event" for more informations
about the keyboard events.
KeyEventUnicode
KeyEventMod return the unicode translated keys pressed/released information from the SDL::Event given as first parameter. see "
SDL::Event" for more informations about the keyboard events.
KeyEventScanCode
MouseMotionState
MouseMotionX
MouseMotionY
MouseMotionXrel
MouseMotionYrel
MouseButtonState
MouseButton
MouseButtonX
MouseButtonY
SysWMEventMsg
EnableUnicode
EnableKeyRepeat
GetKeyName
PRESSED
RELEASED
CreateRGBSurface
CreateRGBSurfaceFrom
IMG_Load
FreeSurface
SurfacePalette
SurfaceBitsPerPixel
SurfaceBy
perl v5.12.1 2010-07-05 SDL(3)