NAME

SDL_perl - Simple DirectMedia Layer for Perl

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:

• INIT_AUDIO()

• INIT_VIDEO()

• INIT_CDROM()

• INIT_EVERYTHING()

• INIT_NOPARACHUTE()

• INIT_JOYSTICK()

• 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:

• CD_TRAYEMPTY

• CD_PLAYING

• CD_STOPPED

• CD_PAUSED

• 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

cpanm SDL

perl -MCPAN -e shell
install SDL