SDL(3p)

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.

  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_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

  CDCurTrack

  CDCurFrame

  CDTrack

  PumpEvents

  NewEvent

  FreeEvent

  PollEvent

  WaitEvent

  EventState

  IGNORE

  ENABLE

  QUERY

  ACTIVEEVENT

  KEYDOWN

  KEYUP

  MOUSEMOTION

  MOUSEBUTTONDOWN

  MOUSEBUTTONUP

  QUIT

  SYSWMEVENT

  EventType

  ActiveEventGain

  ActiveEventState

  APPMOUSEFOCUS

  APPINPUTFOCUS

  APPACTIVE

  KeyEventState

  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

  KeyEventMod

  KeyEventUnicode

  KeyEventScanCode

  MouseMotionState

  MouseMotionX

  MouseMotionY

  MouseMotionXrel

  MouseMotionYrel

  MouseButtonState

  MouseButton

  MouseButtonX

  MouseButtonY

  SysWMEventMsg

  EnableUnicode

  EnableKeyRepeat

  GetKeyName

  PRESSED

  RELEASED

  CreateRGBSurface

  CreateRGBSurfaceFrom

  IMG_Load

  FreeSurface

  SurfacePalette

  SurfaceBitsPerPixel

  SurfaceBytesPerPixel

  SurfaceRshift

  SurfaceGshift

  SurfaceBshift

  SurfaceAshift

  SurfaceRmask

  SurfaceGmask

  SurfaceBmask

  SurfaceAmask

  SurfaceColorKey

  SurfaceAlpha

  SurfaceW

  SurfaceH

  SurfacePitch

  SurfacePixels

  SurfacePixel

  MUSTLOCK

  SurfaceLock

  SurfaceUnlock

  GetVideoSurface

  VideoInfo

  NewRect

  FreeRect

  RectX

  RectY

  RectW

  RectH

  NewColor

  ColorR

  ColorG

  CologB

  FreeColor

  NewPalette

  PaletteNColors

  PaletteColors

  SWSURFACE

  HWSURFACE

  ANYFORMAT

  HWPALETTE

  DOUBLEBUF

  FULLSCREEN

  ASYNCBLIT

  OPENGL

  HWACCEL

  VideoModeOK

  SetVideoMode

  UpdateRects

  Flip

  SetColors

  MapRGB (surface,r,g,b)
"SDL::MapRGB" translates the composite red (r), green (g), blue (b) colors according to the given surface to a interger color value. This integer can be used in functions like "SDL::FillRect", and is not the same as the format independent Color object returned by "SDL::NewColor".

  MapRGBA (surface,r,g,b,a)
"SDL::MapRGBA" works as "SDL::MapRGB" but takes an additional alpha (a) component for semi-transperant colors.

  GetRGB

  GetRGBA

  SaveBMP

  SetColorKey

  SRCCOLORKEY

  RLEACCEL

  SRCALPHA

  SetAlpha

  DisplayFormat

  BlitSurface

  FillRect(surface,rect,color)
"SDL::FillRect" draws a solid rectangle of color on the given surface. If the rectangle is NULL, the entire surface will be painted.

  WMSetCaption

  WMGetCaption

  WMSetIcon

  WarpMouse

  NewCursor

  FreeCursor

  SetCursor

  GetCursor

  ShowCursor

  NewAudioSpec

  FreeAudioSpec

  AUDIO_U8

  AUDIO_S8

  AUDIO_U16

  AUDIO_S16

  AUDIO_U16MSB

  AUDIO_S16MSB

  NewAudioCVT

  FreeAudioCVT

  ConvertAudioData

  OpenAudio

  PauseAudio

  UnlockAudio

  CloseAudio

  FreeWAV

  LoadWAV

  MixAudio

  MIX_MAX_VOLUME

  MIX_DEFAULT_FREQUENCY

  MIX_DEFAULT_FORMAT

  MIX_DEFAULT_CHANNELS

  MIX_NO_FADING

  MIX_FADING_OUT

  MIX_FADING_IN

  MixOpenAudio

  MixAllocateChannels

  MixQuerySpec

  MixLoadWAV

  MixLoadMusic

  MixQuickLoadWAV

  MixFreeChunk

  MixFreeMusic

  MixSetPostMixCallback

  MixSetMusicHook

  MixSetMusicFinishedHook

  MixGetMusicHookData

  MixReverseChannels

  MixGroupChannel

  MixGroupChannels

  MixGroupAvailable

  MixGroupCount

  MixGroupOldest

  MixGroupNewer

  MixPlayChannel

  MixPlayChannelTimed

  MixPlayMusic

  MixFadeInChannel

  MixFadeInChannelTimed

  MixFadeInMusic

  MixVolume

  MixVolumeChunk

  MixVolumeMusic

  MixHaltChannel

  MixHaltGroup

  MixHaltMusic

  MixExpireChannel

  MixFadeOutChannel

  MixFadeOutGroup

  MixFadeOutMusic

  MixFadingMusic

  MixFadingChannel

  MixPause

  MixResume

  MixPaused

  MixPauseMusic

  MixResumeMusic

  MixRewindMusic

  MixPausedMusic

  MixPlaying

  MixPlayingMusic

  MixCloseAudio

  NewFont

  UseFont

  PutString

  TextWidth

  GL_RED_SIZE

  GL_GREEN_SIZE

  GL_BLUE_SIZE

  GL_ALPHA_SIZE

  GL_ACCUM_RED_SIZE

  GL_ACCUM_GREEN_SIZE

  GL_ACCUM_BLUE_SIZE

  GL_ACCUM_ALPHA_SIZE

  GL_BUFFER_SIZE

  GL_DEPTH_SIZE

  GL_STENCIL_SIZE

  GL_DOUBLEBUFFER

  GL_SetAttribute

  GL_GetAttribute

  GL_SwapBuffers

  BigEndian

  NumJoysticks

  JoystickName

  JoystickOpen

  JoystickOpened

  JoystickIndex

  JoystickNumAxes

  JoystickNumBalls

  JoystickNumHats

  JoystickNumButtons

  JoystickUpdate

  JoystickGetAxis

  JoystickGetHat

  JoystickGetButton

  JoystickGetBall

  JoystickClose

AUTHOR
David J. Goehrig

CONTRIBUTORS
David J. Goehrig, Wayne Keenan, Guillaume Cottenceau

SEE ALSO
        perl(1) SDL::App(3) SDL::Surface(3) SDL::Event(3) SDL::Rect(3)
        SDL::Palette(3) SDL::Mixer(3) SDL::Cdrom(3)

POD ERRORS
Hey! The above document had some coding errors, which are explained below:

Around line 100:
    =over should be: '=over' or '=over positive_number'