lib/SDL.pm

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