lib/SDL.pm

   1 #!/usr/bin/env perl
   2 #
   3 # SDL.pm
   4 #
   5 # Copyright (C) 2005 David J. Goehrig <dgoehrig@cpan.org>
   6 # Copyright (C) 2009 Kartik Thakore   <kthakore@cpan.org>
   7 # ------------------------------------------------------------------------------
   8 #
   9 # This library is free software; you can redistribute it and/or
  10 # modify it under the terms of the GNU Lesser General Public
  11 # License as published by the Free Software Foundation; either
  12 # version 2.1 of the License, or (at your option) any later version.
  13 #
  14 # This library is distributed in the hope that it will be useful,
  15 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17 # Lesser General Public License for more details.
  18 #
  19 # You should have received a copy of the GNU Lesser General Public
  20 # License along with this library; if not, write to the Free Software
  21 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
  22 #
  23 # ------------------------------------------------------------------------------
  24 #
  25 # Please feel free to send questions, suggestions or improvements to:
  26 #
  27 #       Kartik Thakore
  28 #       kthakore@cpan.org
  29 #
  30
  31 package SDL;
  32
  33 use strict;
  34 use warnings;
  35 use Carp;
  36
  37 use vars qw($VERSION @ISA @EXPORT @EXPORT_OK);
  38
  39 require Exporter;
  40 require DynaLoader;
  41
  42 use SDL_perl;
  43 use SDL::Constants;
  44
  45 BEGIN {
  46         @ISA = qw(Exporter DynaLoader);
  47         @EXPORT = qw( in verify &NULL );
  48 };
  49
  50 # Give our caller SDL::Constant's stuff as well as ours.
  51 sub import {
  52   my $self = shift;
  53
  54   $self->export_to_level(1, @_);
  55   SDL::Constants->export_to_level(1);
  56 }
  57 $VERSION = '2.2.3';
  58
  59 print "$VERSION" if (defined($ARGV[0]) && ($ARGV[0] eq '--SDLperl'));
  60
  61 $SDL::DEBUG=0;
  62
  63 sub NULL {
  64         return 0;
  65 }
  66
  67 sub in {
  68         my ($k,@t) = @_;
  69         return 0 unless defined $k;
  70         my $r = ((scalar grep { defined $_ && $_ eq $k } @t) <=> 0);
  71         return 0 if $r eq '';
  72         return $r;
  73
  74 }
  75
  76 sub verify (\%@) {
  77         my ($options,@valid_options) = @_;
  78         for (keys %$options) {
  79                 croak "Invalid option $_\n" unless in ($_, @valid_options);
  80         }
  81 }
  82
  83
  84 1;
  85 __END__
  86
  87 =head1 NAME
  88
  89 SDL_perl - Simple DirectMedia Layer for Perl
  90
  91 =head1 SYNOPSIS
  92
  93   use SDL;
  94
  95 =head1 DESCRIPTION
  96
  97 SDL_perl is a package of perl modules that provides both functional and object orient
  98 interfaces to the Simple DirectMedia Layer for Perl 5.  This package does take some
  99 liberties with the SDL API, and attempts to adhere to the spirit of both the SDL
 100 and Perl.  This document describes the low-level functional SDL_perl API.  For the
 101 object oriented programming interface please see the documentation provided on a
 102 per class basis.
 103
 104 =head1 The SDL Perl 2009 Development Team
 105
 106 =head2 Documentation
 107
 108         Nick: magnet
 109
 110 =head2 Perl Development
 111
 112         Nick: Garu
 113         Name: Breno G. de Oliveira
 114
 115         Nick: Dngor
 116         Name: Rocco Caputo
 117
 118         Nick: nferraz
 119         Name: Nelson Ferraz
 120
 121 =head2 Maintainance
 122
 123         Nick: kthakore
 124
 125         Name: Kartik Thakore
 126
 127 =head1 MacOSX Experimental Usage
 128
 129 Please get libsdl packages from Fink
 130
 131         perl Build.PL
 132         perl Build test
 133         perl Build Bundle
 134         perl Build install
 135
 136 =head2 Running SDL Perl Scripts in MacOSX
 137
 138 First set the PERL5LIB environment variable to the dependencies of your script
 139
 140         %export PERL5LIB=$PERL5LIB:./lib
 141
 142 Use the SDLPerl executable made in the bundle and call your scripts
 143
 144         %SDLPerl.app/Contents/MacOS/SDLPerl yourScript.pl
 145
 146 =head1 Functions exported by SDL.pm
 147
 148 =head2 Init(flags)
 149
 150 As with the C language API, SDL_perl initializes the SDL environment through
 151 the C<SDL::Init> subroutine.  This routine takes a mode flag constructed through
 152 the bitwise OR product of the following functions:
 153
 154 =over 4
 155
 156 =item *
 157 INIT_AUDIO()
 158
 159 =item *
 160 INIT_VIDEO()
 161
 162 =item *
 163 INIT_CDROM()
 164
 165 =item *
 166 INIT_EVERYTHING()
 167
 168 =item *
 169 INIT_NOPARACHUTE()
 170
 171 =item *
 172 INIT_JOYSTICK()
 173
 174 =item *
 175 INIT_TIMER()
 176
 177 =back
 178
 179 C<SDL::Init> returns 0 on success, or -1 on error.
 180
 181 =head2 GetError()
 182
 183 The last error message set by the SDL library can be retrieved using the subroutine
 184 C<SDL::GetError>, which returns a scalar containing the text of the message if any.
 185
 186 =head2 Delay(ms)
 187
 188 This subroutine allows an application to delay further operations for atleast a
 189 number of milliseconds provided as the argument.  The actual delay may be longer
 190 than the specified depending on the underlying OS.
 191
 192 =head2 GetTicks()
 193
 194 An application may retrieve the number of milliseconds expired since the initilization
 195 of the application through this subroutine.  This value resets rougly ever 49 days.
 196
 197 =head2 AddTimer(interval,callback,param)
 198
 199 C<AddTimer> will register a SDL_NewTimerCallback function to be executed after
 200 C<interval> milliseconds, with parameter C<param>.  SDL_NewTimerCallback objects
 201 can be constructed with the C<NewTimer> subroutine.   C<SDL::PerlTimerCallback>
 202 will return a valid callback for executing a perl subroutine or closure.
 203 This subroutine returns a SDL_TimerID for the newly registered callback, or NULL
 204 on error.
 205
 206 =head2 NewTimer(interval,subroutine)
 207
 208 The C<NewTimer> takes an interval in milliseconds and a reference to a subroutine
 209 to call at that interval.  The subroutine will be invoked in a void context
 210 and accepts no parameters.  The callback used is that returned by C<SDL::PerlTimerCallback>.
 211 C<NewTimer> returns the SDL_TimerID for the new timer or NULL on error.
 212
 213 =head2 RemoveTimer(id)
 214
 215 This subroutine taks a SDL_TimerID and removes it from the list of active callbacks.
 216 RemoveTimer returns false on failure.
 217
 218 =head2 SetTimer
 219
 220 This subroutine is depreciated, please use C<NewTimer> or C<AddTimer> instead.
 221
 222 =head2 CDNumDrives()
 223
 224 C<SDL::CDNumDrives> returns the number of available CD-ROM drives in the system.
 225
 226 =head2 CDName(drive)
 227
 228 The subroutine C<SDL::CDName> returns the system specific human readable device name
 229 for the given CD-ROM drive.
 230
 231 =head2 CDOpen(drive)
 232
 233 This subroutine opens a CD-ROM drive for access, returning NULL if the drive is busy
 234 or otherwise unavailable.  On success this subroutine returns a handle to the CD-ROM
 235 drive.
 236
 237 =head2 CDTrackListing(cd)
 238
 239 C<SDL::CDTrackListing> returns a human readable description of a CD-ROM.  For each
 240 track one line will be produced with the following format:
 241
 242         Track index: %d, id %d, %2d.%2d
 243
 244 This is provided to ease the creation of human readable descriptions and debugging.
 245
 246 =head2 CDTrackId(track)
 247
 248 C<CDTrackId> returns the id field of the given SDL_CDtrack structure.
 249
 250 =head2 CDTrackType(track)
 251
 252 C<CDTrackType> returns the type field of the given SDL_CDtrack structure.
 253
 254 =head2 CDTrackLength(track)
 255
 256 C<CDTrackLength> returns the length field of the given SDL_CDtrack structure.
 257
 258 =head2 CDTrackOffset(track)
 259
 260 C<CDTrackOffset> returns the offset field of the given SDL_CDtrack structure.
 261
 262 =head2 CDStatus(cd)
 263
 264 The function C<CDStatus> returns the current status of the given SDL_CDrom.
 265 C<CDStatus>'s return values are:
 266
 267 =over 4
 268
 269 =item *
 270 CD_TRAYEMPTY
 271
 272 =item *
 273 CD_PLAYING
 274
 275 =item *
 276 CD_STOPPED
 277
 278 =item *
 279 CD_PAUSED
 280
 281 =item *
 282 CD_ERROR
 283
 284 =back
 285
 286 =head2 CDPlayTracks(cd,track,tracks,frame,frames)
 287
 288 To start playing from an arbitrary portion of a CD, one can provide
 289 C<SDL::CDPlayTracks> with a CD, a starting track, the number of tracks,
 290 a starting frame, and the number of frames to be played.
 291
 292 =head2 CDPlay(cd,track,length)
 293
 294 C<SDL::CDPlay> plays the next C<length> tracks starting from C<track>
 295
 296 =head2 CDPause(cd)
 297
 298 This function will pause CD playback until resume is called.
 299
 300 =head2 CDResume(cd)
 301
 302 This function will resume CD playback if paused.
 303
 304 =head2 CDStop(cd)
 305
 306 C<SDL::CDStop> will stop CD playback if playing.
 307
 308 =head2 CDEject(cd)
 309
 310 This function will eject the CD.
 311
 312 =head2 CDClose(cd)
 313
 314 This function will release an opened CD.
 315
 316 =head2 CDNumTracks
 317
 318 This function return the number of tracks on a CD,
 319 it take a SDL_CD as first parameter.
 320
 321 =head2 CDCurTrack
 322
 323 This function return the number of the current track on a CD,
 324 it take a SDL_CD as first parameter.
 325
 326 =head2 CDCurFrame
 327
 328 this function return the frame offset within the current track on a CD.
 329 it take a SDL_CD as first parameter.
 330
 331 =head2 CDTrack
 332
 333 CDtrack stores data on each track on a CD, its fields should be pretty self explainatory.
 334 CDtrack take a SDL::CD as input and  return a SDL_CDTrack.
 335
 336 =head2 PumpEvents
 337
 338 Pumps the event loop, gathering events from the input devices.
 339
 340 PumpEvents gathers all the pending input information from devices and places
 341 it on the event queue.
 342 Without calls to PumpEvents no events would ever be placed on the queue.
 343 Often the need for calls to PumpEvents is hidden from the user
 344 since L</ PollEvent> and WaitEvent implicitly call PumpEvents.
 345 However, if you are not polling or waiting for events (e.g. you are filtering them),
 346 then you must call PumpEvents to force an event queue update.
 347 PumpEvents doesn't return any value and doesn't take any parameters.
 348
 349 Note: You can only call this function in the thread that set the video mode.
 350
 351 =head2 NewEvent
 352
 353 Create a new event.It return a SDL::Event.
 354
 355 =head2 FreeEvent
 356
 357 FreeEvent delete the SDL::Event given as first parameter.
 358 it doesn't return anything.
 359
 360 =head2 PollEvent
 361
 362 Polls for currently pending events.
 363 If event is not undef, the next event is removed from the queue and returned as a L< SDL::Event>.
 364 As this function implicitly calls L</ PumpEvents>, you can only call this function in the thread that set the video mode.
 365 it take a SDL::Event as first parameter.
 366
 367 =head2 WaitEvent
 368
 369 Waits indefinitely for the next available event, returning undef if there was an error while waiting for events,
 370 a L< SDL::Event> otherwise.
 371 If event is not NULL, the next event is removed.
 372 As this function implicitly calls L</ PumpEvents>, you can only call this function in the thread that set the video mode.
 373 WaitEvent take a SDL::Event as first parameter.
 374
 375 =head2 EventState
 376
 377 This function allows you to set the state of processing certain event types.
 378
 379 it take an event type as first argument, and a state as second.
 380
 381 If state is set to SDL_IGNORE, that event type will be automatically
 382 dropped from the event queue and will not be filtered.
 383 If state is set to SDL_ENABLE, that event type will be processed
 384 normally.
 385 If state is set to SDL_QUERY, SDL_EventState will return the current
 386 processing state of the specified event type.
 387
 388 A list of event types can be found in the L</ SDL_Event section>.
 389
 390 it returns a state(?).
 391
 392 =head2 IGNORE
 393
 394 =head2 ENABLE
 395
 396 =head2 QUERY
 397
 398 =head2 ACTIVEEVENT
 399
 400 =head2 KEYDOWN
 401
 402 =head2 KEYUP
 403
 404 =head2 MOUSEMOTION
 405
 406 =head2 MOUSEBUTTONDOWN
 407
 408 =head2 MOUSEBUTTONUP
 409
 410 =head2 QUIT
 411
 412 =head2 SYSWMEVENT
 413
 414 =head2 EventType
 415
 416 EventType return the type of the SDL::Event given as first parameter.
 417
 418 =head2 ActiveEventGain
 419
 420 ActiveEventGain return the active gain from the SDL::Event given as first parameter.
 421 see L</ SDL::Event> for more informations about the active state.
 422
 423 =head2 ActiveEventState
 424
 425 ActiveEventState return the active state from the SDL::Event given as first parameter.
 426 see L</ SDL::Event> for more informations about the active state.
 427
 428 =head2 APPMOUSEFOCUS
 429
 430 =head2 APPINPUTFOCUS
 431
 432 =head2 APPACTIVE
 433
 434 =head2 KeyEventState
 435
 436 KeyEventState return the active key state from the SDL::Event given as first parameter.
 437 see L</ SDL::Event> for me more informations about the active key.
 438
 439 =head2 SDLK_BACKSPACE
 440
 441 =head2 SDLK_TAB
 442
 443 =head2 SDLK_CLEAR
 444
 445 =head2 SDLK_RETURN
 446
 447 =head2 SDLK_PAUSE
 448
 449 =head2 SDLK_ESCAPE
 450
 451 =head2 SDLK_SPACE
 452
 453 =head2 SDLK_EXCLAIM
 454
 455 =head2 SDLK_QUOTEDBL
 456
 457 =head2 SDLK_HASH
 458
 459 =head2 SDLK_DOLLAR
 460
 461 =head2 SDLK_AMPERSAND
 462
 463 =head2 SDLK_QUOTE
 464
 465 =head2 SDLK_LEFTPAREN
 466
 467 =head2 SDLK_RIGHTPAREN
 468
 469 =head2 SDLK_ASTERISK
 470
 471 =head2 SDLK_PLUS
 472
 473 =head2 SDLK_COMMA
 474
 475 =head2 SDLK_MINUS
 476
 477 =head2 SDLK_PERIOD
 478
 479 =head2 SDLK_SLASH
 480
 481 =head2 SDLK_0
 482
 483 =head2 SDLK_1
 484
 485 =head2 SDLK_2
 486
 487 =head2 SDLK_3
 488
 489 =head2 SDLK_4
 490
 491 =head2 SDLK_5
 492
 493 =head2 SDLK_6
 494
 495 =head2 SDLK_7
 496
 497 =head2 SDLK_8
 498
 499 =head2 SDLK_9
 500
 501 =head2 SDLK_COLON
 502
 503 =head2 SDLK_SEMICOLON
 504
 505 =head2 SDLK_LESS
 506
 507 =head2 SDLK_EQUALS
 508
 509 =head2 SDLK_GREATER
 510
 511 =head2 SDLK_QUESTION
 512
 513 =head2 SDLK_AT
 514
 515 =head2 SDLK_LEFTBRACKET
 516
 517 =head2 SDLK_BACKSLASH
 518
 519 =head2 SDLK_RIGHTBRACKET
 520
 521 =head2 SDLK_CARET
 522
 523 =head2 SDLK_UNDERSCORE
 524
 525 =head2 SDLK_BACKQUOTE
 526
 527 =head2 SDLK_a
 528
 529 =head2 SDLK_b
 530
 531 =head2 SDLK_c
 532
 533 =head2 SDLK_d
 534
 535 =head2 SDLK_e
 536
 537 =head2 SDLK_f
 538
 539 =head2 SDLK_g
 540
 541 =head2 SDLK_h
 542
 543 =head2 SDLK_i
 544
 545 =head2 SDLK_j
 546
 547 =head2 SDLK_k
 548
 549 =head2 SDLK_l
 550
 551 =head2 SDLK_m
 552
 553 =head2 SDLK_n
 554
 555 =head2 SDLK_o
 556
 557 =head2 SDLK_p
 558
 559 =head2 SDLK_q
 560
 561 =head2 SDLK_r
 562
 563 =head2 SDLK_s
 564
 565 =head2 SDLK_t
 566
 567 =head2 SDLK_u
 568
 569 =head2 SDLK_v
 570
 571 =head2 SDLK_w
 572
 573 =head2 SDLK_x
 574
 575 =head2 SDLK_y
 576
 577 =head2 SDLK_z
 578
 579 =head2 SDLK_DELETE
 580
 581 =head2 SDLK_KP0
 582
 583 =head2 SDLK_KP1
 584
 585 =head2 SDLK_KP2
 586
 587 =head2 SDLK_KP3
 588
 589 =head2 SDLK_KP4
 590
 591 =head2 SDLK_KP5
 592
 593 =head2 SDLK_KP6
 594
 595 =head2 SDLK_KP7
 596
 597 =head2 SDLK_KP8
 598
 599 =head2 SDLK_KP9
 600
 601 =head2 SDLK_KP_PERIOD
 602
 603 =head2 SDLK_KP_DIVIDE
 604
 605 =head2 SDLK_KP_MULTIPLY
 606
 607 =head2 SDLK_KP_MINUS
 608
 609 =head2 SDLK_KP_PLUS
 610
 611 =head2 SDLK_KP_ENTER
 612
 613 =head2 SDLK_KP_EQUALS
 614
 615 =head2 SDLK_UP
 616
 617 =head2 SDLK_DOWN
 618
 619 =head2 SDLK_RIGHT
 620
 621 =head2 SDLK_LEFT
 622
 623 =head2 SDLK_INSERT
 624
 625 =head2 SDLK_HOME
 626
 627 =head2 SDLK_END
 628
 629 =head2 SDLK_PAGEUP
 630
 631 =head2 SDLK_PAGEDOWN
 632
 633 =head2 SDLK_F1
 634
 635 =head2 SDLK_F2
 636
 637 =head2 SDLK_F3
 638
 639 =head2 SDLK_F4
 640
 641 =head2 SDLK_F5
 642
 643 =head2 SDLK_F6
 644
 645 =head2 SDLK_F7
 646
 647 =head2 SDLK_F8
 648
 649 =head2 SDLK_F9
 650
 651 =head2 SDLK_F10
 652
 653 =head2 SDLK_F11
 654
 655 =head2 SDLK_F12
 656
 657 =head2 SDLK_F13
 658
 659 =head2 SDLK_F14
 660
 661 =head2 SDLK_F15
 662
 663 =head2 SDLK_NUMLOCK
 664
 665 =head2 SDLK_CAPSLOCK
 666
 667 =head2 SDLK_SCROLLOCK
 668
 669 =head2 SDLK_RSHIFT
 670
 671 =head2 SDLK_LSHIFT
 672
 673 =head2 SDLK_RCTRL
 674
 675 =head2 SDLK_LCTRL
 676
 677 =head2 SDLK_RALT
 678
 679 =head2 SDLK_LALT
 680
 681 =head2 SDLK_RMETA
 682
 683 =head2 SDLK_LMETA
 684
 685 =head2 SDLK_LSUPER
 686
 687 =head2 SDLK_RSUPER
 688
 689 =head2 SDLK_MODE
 690
 691 =head2 SDLK_HELP
 692
 693 =head2 SDLK_PRINT
 694
 695 =head2 SDLK_SYSREQ
 696
 697 =head2 SDLK_BREAK
 698
 699 =head2 SDLK_MENU
 700
 701 =head2 SDLK_POWER
 702
 703 =head2 SDLK_EURO
 704
 705 =head2 KMOD_NONE
 706
 707 =head2 KMOD_NUM
 708
 709 =head2 KMOD_CAPS
 710
 711 =head2 KMOD_LCTRL
 712
 713 =head2 KMOD_RCTRL
 714
 715 =head2 KMOD_RSHIFT
 716
 717 =head2 KMOD_LSHIFT
 718
 719 =head2 KMOD_RALT
 720
 721 =head2 KMOD_LALT
 722
 723 =head2 KMOD_CTRL
 724
 725 =head2 KMOD_SHIFT
 726
 727 =head2 KMOD_ALT
 728
 729 =head2 KeyEventSym
 730
 731 KeyEventSym return the key pressed/released  information from the SDL::Event given as first parameter.
 732 see L</ SDL::Event> for more informations about the keyboard events.
 733
 734 =head2 KeyEventMod
 735
 736 KeyEventMod return the mod keys pressed information from the SDL::Event given as first parameter.
 737 see L</ SDL::Event> for more informations about the keyboard events.
 738
 739 =head2 KeyEventUnicode
 740
 741 KeyEventMod return the unicode translated keys pressed/released information from the SDL::Event given as first parameter.
 742 see L</ SDL::Event> for more informations about the keyboard events.
 743
 744 =head2 KeyEventScanCode
 745
 746 =head2 MouseMotionState
 747
 748 =head2 MouseMotionX
 749
 750 =head2 MouseMotionY
 751
 752 =head2 MouseMotionXrel
 753
 754 =head2 MouseMotionYrel
 755
 756 =head2 MouseButtonState
 757
 758 =head2 MouseButton
 759
 760 =head2 MouseButtonX
 761
 762 =head2 MouseButtonY
 763
 764 =head2 SysWMEventMsg
 765
 766 =head2 EnableUnicode
 767
 768 =head2 EnableKeyRepeat
 769
 770 =head2 GetKeyName
 771
 772 =head2 PRESSED
 773
 774 =head2 RELEASED
 775
 776 =head2 CreateRGBSurface
 777
 778 =head2 CreateRGBSurfaceFrom
 779
 780 =head2 IMG_Load
 781
 782 =head2 FreeSurface
 783
 784 =head2 SurfacePalette
 785
 786 =head2 SurfaceBitsPerPixel
 787
 788 =head2 SurfaceBy