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