File Coverage

lib/SDL2/HapticDirection.pm
Criterion Covered Total %
statement 3 3 100.0
branch n/a
condition n/a
subroutine 1 1 100.0
pod n/a
total 4 4 100.0


line stmt bran cond sub pod time code
1             package SDL2::HapticDirection {
2 2     2   14 use SDL2::Utils;
  2         4  
  2         20  
3             has
4             type => 'uint8',
5             dir => 'sint32[2]';
6              
7             =encoding utf-8
8              
9             =head1 NAME
10              
11             SDL2::HapticDirection - Structure that represents a haptic direction
12              
13             =head1 SYNOPSIS
14              
15             use SDL2 qw[:all];
16             my $direction = SDL2::HapticDirection->new(
17             { type => SDL_HAPTIC_CARTESIAN, # Using cartesian direction encoding
18             dir => [ 0, 1 ] # X and Y positions
19             }
20             );
21              
22             =head1 DESCRIPTION
23              
24             This is the direction where the force comes from, instead of the direction in
25             which the force is exerted.
26              
27             Directions can be specified by:
28              
29             =over
30              
31             =item C - Specified by polar coordinates
32              
33             =item C - Specified by cartesian coordinates
34              
35             =item C - Specified by spherical coordinates
36              
37             =back
38              
39             Cardinal directions of the haptic device are relative to the positioning of the
40             device. North is considered to be away from the user.
41              
42             The following diagram represents the cardinal directions:
43              
44             .--.
45             |__| .-------.
46             |=.| |.-----.|
47             |--| || ||
48             | | |'-----'|
49             |__|~')_____('
50             [ COMPUTER ]
51             North (0,-1)
52             ^
53             |
54             |
55             (-1,0) West <----[ HAPTIC ]----> East (1,0)
56             |
57             |
58             v
59             South (0,1)
60             [ USER ]
61             \|||/
62             (o o)
63             ---ooO-(_)-Ooo---
64              
65              
66             If type is C, direction is encoded by hundredths of a degree
67             starting north and turning clockwise. C only uses C
68             parameter. The cardinal directions would be:
69              
70             =over
71              
72             =item North - C<0> (0 degrees)
73              
74             =item East - C<9000> (90 degrees)
75              
76             =item South - C<18000> (180 degrees)
77              
78             =item West - C<27000> (270 degrees)
79              
80             =back
81            
82             If type is C, direction is encoded by three positions (X
83             axis, Y axis and Z axis (with 3 axes)). C uses the first
84             three C parameters. The cardinal directions would be:
85              
86             =over
87            
88             =item North - C<0,-1, 0>
89              
90             =item East - C<1, 0, 0>
91              
92             =item South - C<0, 1, 0>
93              
94             =item West - C<-1, 0, 0>
95            
96             =back
97              
98             The Z axis represents the height of the effect if supported, otherwise it's
99             unused. In cartesian encoding C<(1, 2)> would be the same as C<(2, 4)>, you
100             can use any multiple you want, only the direction matters.
101              
102             If type is C, direction is encoded by two rotations. The
103             first two C parameters are used. The C parameters are as follows
104             (all values are in hundredths of degrees):
105              
106             =over
107              
108             =item Degrees from C<(1, 0)> rotated towards C<(0, 1)>.
109              
110             =item Degrees towards C<(0, 0, 1)> (device needs at least 3 axes).
111              
112             =back
113              
114             Example of force coming from the south with all encodings (force coming from
115             the south means the user will have to pull the stick to counteract):
116              
117             # Cartesian directions
118             my $direction = SDL2::HapticDirection->new(
119             { type => SDL_HAPTIC_CARTESIAN, # Using cartesian direction encoding
120             dir => [ 0, 1 ] # X and Y positions
121             }
122             );
123             # Assuming the device has 2 axes, we don't need to specify third parameter.
124              
125             # Polar directions
126             $direction->type(SDL_HAPTIC_POLAR); # We'll be using polar direction encoding
127             $direction->dir->[0] = 18000; # Polar only uses first parameter
128              
129             # Spherical coordinates
130             $direction->type(SDL_HAPTIC_SPHERICAL); # Spherical encoding
131             $direction->dir->[0] = 9000; # Since we only have two axes we don't need more parameters
132              
133             =head1 Fields
134              
135             =over
136              
137             =item C - The type of encoding
138              
139             =item C - The encoded direction as a list of numbers
140              
141             =back
142              
143             =head1 AUTHOR
144              
145             Sanko Robinson Esanko@cpan.orgE
146              
147             =begin stopwords
148              
149             cartesian encodings
150              
151             =end stopwords
152              
153             =cut
154              
155             };
156             1;