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