2 # Copyright (C) 2004 David J. Goehrig
3 # Copyright (C) 2009 Kartik Thakore
11 use vars qw($VERSION @ISA @EXPORT @EXPORT_OK);
20 @ISA = qw(Exporter DynaLoader);
21 @EXPORT = qw( in verify &NULL );
22 # reexport all SDL constants
23 for (@SDL::Constants::EXPORT) {
31 print "$VERSION" if (defined($ARGV[0]) && ($ARGV[0] eq '--SDLperl'));
41 (scalar grep { defined $_ && $_ eq $k } @t) <=> 0;
45 my ($options,@valid_options) = @_;
46 for (keys %$options) {
47 croak "Invalid option $_\n" unless in ($_, @valid_options);
57 SDL_perl - Simple DirectMedia Layer for Perl
65 SDL_perl is a package of perl modules that provides both functional and object orient
66 interfaces to the Simple DirectMedia Layer for Perl 5. This package does take some
67 liberties with the SDL API, and attempts to adhere to the spirit of both the SDL
68 and Perl. This document describes the low-level functional SDL_perl API. For the
69 object oriented programming interface please see the documentation provided on a
74 As with the C language API, SDL_perl initializes the SDL environment through
75 the C<SDL::Init> subroutine. This routine takes a mode flag constructed through
76 the bitwise OR product of the following functions:
103 C<SDL::Init> returns 0 on success, or -1 on error.
107 The last error message set by the SDL library can be retrieved using the subroutine
108 C<SDL::GetError>, which returns a scalar containing the text of the message if any.
112 This subroutine allows an application to delay further operations for atleast a
113 number of milliseconds provided as the argument. The actual delay may be longer
114 than the specified depending on the underlying OS.
118 An application may retrieve the number of milliseconds expired since the initilization
119 of the application through this subroutine. This value resets rougly ever 49 days.
121 =head2 AddTimer(interval,callback,param)
123 C<AddTimer> will register a SDL_NewTimerCallback function to be executed after
124 C<interval> milliseconds, with parameter C<param>. SDL_NewTimerCallback objects
125 can be constructed with the C<NewTimer> subroutine. C<SDL::PerlTimerCallback>
126 will return a valid callback for executing a perl subroutine or closure.
127 This subroutine returns a SDL_TimerID for the newly registered callback, or NULL
130 =head2 NewTimer(interval,subroutine)
132 The C<NewTimer> takes an interval in milliseconds and a reference to a subroutine
133 to call at that interval. The subroutine will be invoked in a void context
134 and accepts no parameters. The callback used is that returned by C<SDL::PerlTimerCallback>.
135 C<NewTimer> returns the SDL_TimerID for the new timer or NULL on error.
137 =head2 RemoveTimer(id)
139 This subroutine taks a SDL_TimerID and removes it from the list of active callbacks.
140 RemoveTimer returns false on failure.
144 This subroutine is depreciated, please use C<NewTimer> or C<AddTimer> instead.
148 C<SDL::CDNumDrives> returns the number of available CD-ROM drives in the system.
152 The subroutine C<SDL::CDName> returns the system specific human readable device name
153 for the given CD-ROM drive.
157 This subroutine opens a CD-ROM drive for access, returning NULL if the drive is busy
158 or otherwise unavailable. On success this subroutine returns a handle to the CD-ROM
161 =head2 CDTrackListing(cd)
163 C<SDL::CDTrackListing> returns a human readable description of a CD-ROM. For each
164 track one line will be produced with the following format:
166 Track index: %d, id %d, %2d.%2d
168 This is provided to ease the creation of human readable descriptions and debugging.
170 =head2 CDTrackId(track)
172 C<CDTrackId> returns the id field of the given SDL_CDtrack structure.
174 =head2 CDTrackType(track)
176 C<CDTrackType> returns the type field of the given SDL_CDtrack structure.
178 =head2 CDTrackLength(track)
180 C<CDTrackLength> returns the length field of the given SDL_CDtrack structure.
182 =head2 CDTrackOffset(track)
184 C<CDTrackOffset> returns the offset field of the given SDL_CDtrack structure.
188 The function C<CDStatus> returns the current status of the given SDL_CDrom.
189 C<CDStatus>'s return values are:
210 =head2 CDPlayTracks(cd,track,tracks,frame,frames)
212 To start playing from an arbitrary portion of a CD, one can provide
213 C<SDL::CDPlayTracks> with a CD, a starting track, the number of tracks,
214 a starting frame, and the number of frames to be played.
216 =head2 CDPlay(cd,track,length)
218 C<SDL::CDPlay> plays the next C<length> tracks starting from C<track>
222 This function will pause CD playback until resume is called.
226 This function will resume CD playback if paused.
230 C<SDL::CDStop> will stop CD playback if playing.
234 This function will eject the CD
238 This function will release an opened CD.
274 =head2 MOUSEBUTTONDOWN
284 =head2 ActiveEventGain
286 =head2 ActiveEventState
296 =head2 SDLK_BACKSPACE
318 =head2 SDLK_AMPERSAND
322 =head2 SDLK_LEFTPAREN
324 =head2 SDLK_RIGHTPAREN
360 =head2 SDLK_SEMICOLON
372 =head2 SDLK_LEFTBRACKET
374 =head2 SDLK_BACKSLASH
376 =head2 SDLK_RIGHTBRACKET
380 =head2 SDLK_UNDERSCORE
382 =head2 SDLK_BACKQUOTE
458 =head2 SDLK_KP_PERIOD
460 =head2 SDLK_KP_DIVIDE
462 =head2 SDLK_KP_MULTIPLY
470 =head2 SDLK_KP_EQUALS
524 =head2 SDLK_SCROLLOCK
590 =head2 KeyEventUnicode
592 =head2 KeyEventScanCode
594 =head2 MouseMotionState
600 =head2 MouseMotionXrel
602 =head2 MouseMotionYrel
604 =head2 MouseButtonState
616 =head2 EnableKeyRepeat
624 =head2 CreateRGBSurface
626 =head2 CreateRGBSurfaceFrom
632 =head2 SurfacePalette
634 =head2 SurfaceBitsPerPixel
636 =head2 SurfaceBytesPerPixel
654 =head2 SurfaceColorKey
674 =head2 GetVideoSurface
702 =head2 PaletteNColors
734 =head2 MapRGB (surface,r,g,b)
736 C<SDL::MapRGB> translates the composite red (r), green (g), blue (b)
737 colors according to the given surface to a interger color value. This
738 integer can be used in functions like C<SDL::FillRect>, and is not
739 the same as the format independent Color object returned by C<SDL::NewColor>.
741 =head2 MapRGBA (surface,r,g,b,a)
743 C<SDL::MapRGBA> works as C<SDL::MapRGB> but takes an additional alpha (a)
744 component for semi-transperant colors.
766 =head2 FillRect(surface,rect,color)
768 C<SDL::FillRect> draws a solid rectangle of color on the given surface.
769 If the rectangle is NULL, the entire surface will be painted.
809 =head2 ConvertAudioData
825 =head2 MIX_MAX_VOLUME
827 =head2 MIX_DEFAULT_FREQUENCY
829 =head2 MIX_DEFAULT_FORMAT
831 =head2 MIX_DEFAULT_CHANNELS
835 =head2 MIX_FADING_OUT
841 =head2 MixAllocateChannels
849 =head2 MixQuickLoadWAV
855 =head2 MixSetPostMixCallback
857 =head2 MixSetMusicHook
859 =head2 MixSetMusicFinishedHook
861 =head2 MixGetMusicHookData
863 =head2 MixReverseChannels
865 =head2 MixGroupChannel
867 =head2 MixGroupChannels
869 =head2 MixGroupAvailable
873 =head2 MixGroupOldest
877 =head2 MixPlayChannel
879 =head2 MixPlayChannelTimed
883 =head2 MixFadeInChannel
885 =head2 MixFadeInChannelTimed
887 =head2 MixFadeInMusic
891 =head2 MixVolumeChunk
893 =head2 MixVolumeMusic
895 =head2 MixHaltChannel
901 =head2 MixExpireChannel
903 =head2 MixFadeOutChannel
905 =head2 MixFadeOutGroup
907 =head2 MixFadeOutMusic
909 =head2 MixFadingMusic
911 =head2 MixFadingChannel
921 =head2 MixResumeMusic
923 =head2 MixRewindMusic
925 =head2 MixPausedMusic
929 =head2 MixPlayingMusic
949 =head2 GL_ACCUM_RED_SIZE
951 =head2 GL_ACCUM_GREEN_SIZE
953 =head2 GL_ACCUM_BLUE_SIZE
955 =head2 GL_ACCUM_ALPHA_SIZE
957 =head2 GL_BUFFER_SIZE
961 =head2 GL_STENCIL_SIZE
963 =head2 GL_DOUBLEBUFFER
965 =head2 GL_SetAttribute
967 =head2 GL_GetAttribute
969 =head2 GL_SwapBuffers
979 =head2 JoystickOpened
983 =head2 JoystickNumAxes
985 =head2 JoystickNumBalls
987 =head2 JoystickNumHats
989 =head2 JoystickNumButtons
991 =head2 JoystickUpdate
993 =head2 JoystickGetAxis
995 =head2 JoystickGetHat
997 =head2 JoystickGetButton
999 =head2 JoystickGetBall
1001 =head2 JoystickClose
1009 David J. Goehrig, Wayne Keenan, Guillaume Cottenceau
1013 perl(1) SDL::App(3) SDL::Surface(3) SDL::Event(3) SDL::Rect(3)
1014 SDL::Palette(3) SDL::Mixer(3) SDL::Cdrom(3)