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