2 # Copyright (C) 2004 David J. Goehrig
8 use vars qw($VERSION @ISA @EXPORT @EXPORT_OK);
17 @ISA = qw(Exporter DynaLoader);
18 @EXPORT = qw( in verify &NULL );
19 # reexport all SDL constants
20 for (@SDL::Constants::EXPORT) {
28 print "$VERSION" if (defined($ARGV[0]) && ($ARGV[0] eq '--SDLperl'));
38 (scalar grep { defined $_ && $_ eq $k } @t) <=> 0;
42 my ($options,@valid_options) = @_;
43 for (keys %$options) {
44 die "Invalid option $_\n" unless in ($_, @valid_options);
54 SDL_perl - Simple DirectMedia Layer for Perl
62 SDL_perl is a package of perl modules that provides both functional and object orient
63 interfaces to the Simple DirectMedia Layer for Perl 5. This package does take some
64 liberties with the SDL API, and attempts to adhere to the spirit of both the SDL
65 and Perl. This document describes the low-level functional SDL_perl API. For the
66 object oriented programming interface please see the documentation provided on a
71 As with the C language API, SDL_perl initializes the SDL environment through
72 the C<SDL::Init> subroutine. This routine takes a mode flag constructed through
73 the bitwise OR product of the following functions:
99 C<SDL::Init> returns 0 on success, or -1 on error.
103 The last error message set by the SDL library can be retrieved using the subroutine
104 C<SDL::GetError>, which returns a scalar containing the text of the message if any.
108 This subroutine allows an application to delay further operations for atleast a
109 number of milliseconds provided as the argument. The actual delay may be longer
110 than the specified depending on the underlying OS.
114 An application may retrieve the number of milliseconds expired since the initilization
115 of the application through this subroutine. This value resets rougly ever 49 days.
117 =head2 AddTimer(interval,callback,param)
119 C<AddTimer> will register a SDL_NewTimerCallback function to be executed after
120 C<interval> milliseconds, with parameter C<param>. SDL_NewTimerCallback objects
121 can be constructed with the C<NewTimer> subroutine. C<SDL::PerlTimerCallback>
122 will return a valid callback for executing a perl subroutine or closure.
123 This subroutine returns a SDL_TimerID for the newly registered callback, or NULL
126 =head2 NewTimer(interval,subroutine)
128 The C<NewTimer> takes an interval in milliseconds and a reference to a subroutine
129 to call at that interval. The subroutine will be invoked in a void context
130 and accepts no parameters. The callback used is that returned by C<SDL::PerlTimerCallback>.
131 C<NewTimer> returns the SDL_TimerID for the new timer or NULL on error.
133 =head2 RemoveTimer(id)
135 This subroutine taks a SDL_TimerID and removes it from the list of active callbacks.
136 RemoveTimer returns false on failure.
140 This subroutine is depreciated, please use C<NewTimer> or C<AddTimer> instead.
144 C<SDL::CDNumDrives> returns the number of available CD-ROM drives in the system.
148 The subroutine C<SDL::CDName> returns the system specific human readable device name
149 for the given CD-ROM drive.
153 This subroutine opens a CD-ROM drive for access, returning NULL if the drive is busy
154 or otherwise unavailable. On success this subroutine returns a handle to the CD-ROM
157 =head2 CDTrackListing(cd)
159 C<SDL::CDTrackListing> returns a human readable description of a CD-ROM. For each
160 track one line will be produced with the following format:
162 Track index: %d, id %d, %2d.%2d
164 This is provided to ease the creation of human readable descriptions and debugging.
166 =head2 CDTrackId(track)
168 C<CDTrackId> returns the id field of the given SDL_CDtrack structure.
170 =head2 CDTrackType(track)
172 C<CDTrackType> returns the type field of the given SDL_CDtrack structure.
174 =head2 CDTrackLength(track)
176 C<CDTrackLength> returns the length field of the given SDL_CDtrack structure.
178 =head2 CDTrackOffset(track)
180 C<CDTrackOffset> returns the offset field of the given SDL_CDtrack structure.
184 The function C<CDStatus> returns the current status of the given SDL_CDrom.
185 C<CDStatus>'s return values are:
206 =head2 CDPlayTracks(cd,track,tracks,frame,frames)
208 To start playing from an arbitrary portion of a CD, one can provide
209 C<SDL::CDPlayTracks> with a CD, a starting track, the number of tracks,
210 a starting frame, and the number of frames to be played.
212 =head2 CDPlay(cd,track,length)
214 C<SDL::CDPlay> plays the next C<length> tracks starting from C<track>
218 This function will pause CD playback until resume is called.
222 This function will resume CD playback if paused.
226 C<SDL::CDStop> will stop CD playback if playing.
230 This function will eject the CD
234 This function will release an opened CD.
270 =head2 MOUSEBUTTONDOWN
280 =head2 ActiveEventGain
282 =head2 ActiveEventState
292 =head2 SDLK_BACKSPACE
314 =head2 SDLK_AMPERSAND
318 =head2 SDLK_LEFTPAREN
320 =head2 SDLK_RIGHTPAREN
356 =head2 SDLK_SEMICOLON
368 =head2 SDLK_LEFTBRACKET
370 =head2 SDLK_BACKSLASH
372 =head2 SDLK_RIGHTBRACKET
376 =head2 SDLK_UNDERSCORE
378 =head2 SDLK_BACKQUOTE
454 =head2 SDLK_KP_PERIOD
456 =head2 SDLK_KP_DIVIDE
458 =head2 SDLK_KP_MULTIPLY
466 =head2 SDLK_KP_EQUALS
520 =head2 SDLK_SCROLLOCK
586 =head2 KeyEventUnicode
588 =head2 KeyEventScanCode
590 =head2 MouseMotionState
596 =head2 MouseMotionXrel
598 =head2 MouseMotionYrel
600 =head2 MouseButtonState
612 =head2 EnableKeyRepeat
620 =head2 CreateRGBSurface
622 =head2 CreateRGBSurfaceFrom
628 =head2 SurfacePalette
630 =head2 SurfaceBitsPerPixel
632 =head2 SurfaceBytesPerPixel
650 =head2 SurfaceColorKey
670 =head2 GetVideoSurface
698 =head2 PaletteNColors
730 =head2 MapRGB (surface,r,g,b)
732 C<SDL::MapRGB> translates the composite red (r), green (g), blue (b)
733 colors according to the given surface to a interger color value. This
734 integer can be used in functions like C<SDL::FillRect>, and is not
735 the same as the format independent Color object returned by C<SDL::NewColor>.
737 =head2 MapRGBA (surface,r,g,b,a)
739 C<SDL::MapRGBA> works as C<SDL::MapRGB> but takes an additional alpha (a)
740 component for semi-transperant colors.
762 =head2 FillRect(surface,rect,color)
764 C<SDL::FillRect> draws a solid rectangle of color on the given surface.
765 If the rectangle is NULL, the entire surface will be painted.
805 =head2 ConvertAudioData
821 =head2 MIX_MAX_VOLUME
823 =head2 MIX_DEFAULT_FREQUENCY
825 =head2 MIX_DEFAULT_FORMAT
827 =head2 MIX_DEFAULT_CHANNELS
831 =head2 MIX_FADING_OUT
837 =head2 MixAllocateChannels
845 =head2 MixQuickLoadWAV
851 =head2 MixSetPostMixCallback
853 =head2 MixSetMusicHook
855 =head2 MixSetMusicFinishedHook
857 =head2 MixGetMusicHookData
859 =head2 MixReverseChannels
861 =head2 MixGroupChannel
863 =head2 MixGroupChannels
865 =head2 MixGroupAvailable
869 =head2 MixGroupOldest
873 =head2 MixPlayChannel
875 =head2 MixPlayChannelTimed
879 =head2 MixFadeInChannel
881 =head2 MixFadeInChannelTimed
883 =head2 MixFadeInMusic
887 =head2 MixVolumeChunk
889 =head2 MixVolumeMusic
891 =head2 MixHaltChannel
897 =head2 MixExpireChannel
899 =head2 MixFadeOutChannel
901 =head2 MixFadeOutGroup
903 =head2 MixFadeOutMusic
905 =head2 MixFadingMusic
907 =head2 MixFadingChannel
917 =head2 MixResumeMusic
919 =head2 MixRewindMusic
921 =head2 MixPausedMusic
925 =head2 MixPlayingMusic
945 =head2 GL_ACCUM_RED_SIZE
947 =head2 GL_ACCUM_GREEN_SIZE
949 =head2 GL_ACCUM_BLUE_SIZE
951 =head2 GL_ACCUM_ALPHA_SIZE
953 =head2 GL_BUFFER_SIZE
957 =head2 GL_STENCIL_SIZE
959 =head2 GL_DOUBLEBUFFER
961 =head2 GL_SetAttribute
963 =head2 GL_GetAttribute
965 =head2 GL_SwapBuffers
975 =head2 JoystickOpened
979 =head2 JoystickNumAxes
981 =head2 JoystickNumBalls
983 =head2 JoystickNumHats
985 =head2 JoystickNumButtons
987 =head2 JoystickUpdate
989 =head2 JoystickGetAxis
991 =head2 JoystickGetHat
993 =head2 JoystickGetButton
995 =head2 JoystickGetBall
1005 David J. Goehrig, Wayne Keenan, Guillaume Cottenceau
1009 perl(1) SDL::App(3) SDL::Surface(3) SDL::Event(3) SDL::Rect(3)
1010 SDL::Palette(3) SDL::Mixer(3) SDL::Cdrom(3)