/lib/pods/SDL/Joystick.pod

http://github.com/PerlGameDev/SDL · Unknown · 245 lines · 139 code · 106 blank · 0 comment · 0 complexity · 8dcea05e7247a503d824f53dbac10257 MD5 · raw file

  1. =pod
  2. =head1 NAME
  3. SDL::Joystick -- SDL Bindings for the Joystick device
  4. =head1 CATEGORY
  5. Core, Joystick
  6. =head1 SYNOPSIS
  7. use SDL;
  8. use SDL::Joystick;
  9. SDL::init_sub_system(SDL_INIT_JOYSTICK);
  10. die('no joystick found') unless(SDL::Joystick::num_joysticks());
  11. my $joystick = SDL::Joystick->new(0);
  12. =head1 METHODS
  13. =head2 num_joysticks
  14. int SDL::Joystick::num_joysticks( void );
  15. Counts and returns available joysticks.
  16. =head2 name
  17. string SDL::Joystick::name( index );
  18. Get the implementation dependent name of joystick. The C<index> parameter refers to the N'th joystick on the system.
  19. my $num_joysticks = SDL::Joystick::num_joysticks();
  20. printf("%d joysticks found\n", $num_joysticks);
  21. for($i = 0; $i < $num_joysticks; $i++)
  22. {
  23. printf("%s\n", SDL::Joystick::name($i));
  24. }
  25. =head2 new
  26. object SDL::Joystick->new( index );
  27. Opens a joystick for use within SDL. The C<index> refers to the N'th joystick in the system.
  28. A joystick must be opened before it can be used.
  29. # Initialize the joystick subsystem
  30. SDL::init_sub_system(SDL_INIT_JOYSTICK);
  31. # Check for joystick
  32. if(SDL::Joystick::num_joysticks() > 0)
  33. {
  34. # Open joystick
  35. my $joystick = SDL::Joystick->new(0);
  36. if($joystick)
  37. {
  38. printf("Opened Joystick 0\n");
  39. printf("Name: %s\n", SDL::Joystick::name(0));
  40. printf("Number of Axes: %d\n", SDL::Joystick::num_axes($joystick));
  41. printf("Number of Buttons: %d\n", SDL::Joystick::num_buttons($joystick));
  42. printf("Number of Balls: %d\n", SDL::Joystick::num_balls($joystick));
  43. }
  44. else
  45. {
  46. printf("Couldn't open Joystick 0\n");
  47. }
  48. # Close if opened
  49. SDL::Joystick::close($joystick) if SDL::Joystick::opened(0);
  50. }
  51. =head2 opened
  52. int SDL::Joystick::opened( index );
  53. Determines whether a joystick has already been opened within the application. C<index> refers to the N'th joystick on the system.
  54. Returns 1 if the joystick has been opened, or 0 if it has not.
  55. =head2 index
  56. int SDL::Joystick::index( object );
  57. Returns the C<index> of a given C<SDL_Joystick> structure. See L<SDL::Joystick::new|/new>
  58. =head2 num_axes
  59. int SDL::Joystick::num_axes( object );
  60. Return the number of axes available from a previously opened joystick. See L<SDL::Joystick::new|/new>
  61. =head2 num_balls
  62. int SDL::Joystick::num_balls( object );
  63. Return the number of trackballs available from a previously opened joystick. See L<SDL::Joystick::new|/new>
  64. =head2 num_hats
  65. int SDL::Joystick::num_hats( object );
  66. Gets the number of joystick hats from a previously opened joystick. See L<SDL::Joystick::new|/new>
  67. =head2 num_buttons
  68. int SDL::Joystick::num_buttons( object );
  69. Gets the number of joystick buttons from a previously opened joystick. See L<SDL::Joystick::new|/new>
  70. =head2 update
  71. void SDL::Joystick::update();
  72. Updates the state(position, buttons, etc.) of all open joysticks. If joystick events have been enabled
  73. with C<SDL::Joystick::event_state> then this is called automatically in the event loop.
  74. =head2 get_axis
  75. C<get_axis> returns the current state of the given axis on the given joystick.
  76. On most modern joysticks the X axis is usually represented by axis 0 and the Y axis by axis 1.
  77. The value returned by C<get_axis> is a signed integer (-32768 to 32767) representing the current position of the axis,
  78. it may be necessary to impose certain tolerances on these values to account for jitter.
  79. B<Note>: Some joysticks use axes 2 and 3 for extra buttons.
  80. Returns a 16-bit signed integer representing the current position of the axis.
  81. my $joystick = SDL::Joystick->new(0);
  82. my $x_move = SDL::Joystick::get_axis($joystick, 0);
  83. my $y_move = SDL::Joystick::get_axis($joystick, 1);
  84. =head2 get_hat
  85. int SDL::Joystick::get_hat( object, int );
  86. C<get_hat> returns the current state of the given C<hat> on the given C<joystick>.
  87. The current state is returned which is an OR'd combination of one or more of the following:
  88. =over 4
  89. =item *
  90. C<SDL_HAT_CENTERED>
  91. =item *
  92. C<SDL_HAT_UP>
  93. =item *
  94. C<SDL_HAT_RIGHT>
  95. =item *
  96. C<SDL_HAT_DOWN>
  97. =item *
  98. C<SDL_HAT_LEFT>
  99. =item *
  100. C<SDL_HAT_RIGHTUP>
  101. =item *
  102. C<SDL_HAT_RIGHTDOWN>
  103. =item *
  104. C<SDL_HAT_LEFTUP>
  105. =item *
  106. C<SDL_HAT_LEFTDOWN>
  107. =back
  108. my $joystick = SDL::Joystick->new(0);
  109. my $position = SDL::Joystick::get_hat($joystick, 0);
  110. print("hat is in position UP\n") if $position & SDL_HAT_UP;
  111. =head2 get_button
  112. int SDL::Joystick::get_button( object, int );
  113. C<get_button> returns the current state of the given button on the given joystick.
  114. Returns 1 if the button is pressed. Otherwise, 0.
  115. my $joystick = SDL::Joystick->new(0);
  116. my $num_buttons = SDL::Joystick::num_buttons($joystick);
  117. for(my $i = 0; $i < $num_buttons; $i++)
  118. {
  119. printf("button %d is %s\n", $i, SDL::Joystick::get_button($joystick, $i) ? 'pressed' : 'not pressed');
  120. }
  121. SDL::Joystick::close($joystick) if SDL::Joystick::opened(0);
  122. =head2 get_ball
  123. int SDL::Joystick::get_ball(SDL_Joystick $joystick, int $ball, int $dx, int $dy);
  124. Get the ball axis change.
  125. Trackballs can only return relative motion since the last call to SDL::Joystick::get_ball, these motion deltas are placed into C<dx> and C<dy>.
  126. Returns 0 on success or -1 on failure
  127. my $delta_x = 0;
  128. my $delta_y = 0;
  129. my $joystick = SDL::Joystick->new(0);
  130. SDL::Joystick::update();
  131. printf("TrackBall Read Error!\n") if(SDL::JoystickGetBall($joystick, 0, $delta_x, $delta_y) == -1);
  132. printf("Trackball Delta- X:%d, Y:%d\n", delta_x, delta_y);
  133. =head2 close
  134. void SDL::Joystick::close( object );
  135. Closes a previously opened joystick. See L<SDL::Joystick::new|/new>
  136. SDL::Joystick::close($joystick) if SDL::Joystick::opened(0);
  137. =head1 AUTHORS
  138. See L<SDL/AUTHORS>.
  139. =cut