KallistiOS  2.0.0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
purupuru.h
Go to the documentation of this file.
1 /* KallistiOS 2.0.0
2 
3  dc/maple/purupuru.h
4  Copyright (C) 2003 Dan Potter
5  Copyright (C) 2005, 2010 Lawrence Sebald
6 
7 */
8 
9 /** \file dc/maple/purupuru.h
10  \brief Definitions for using the Puru Puru (Jump) Pack.
11 
12  This file contains the definitions needed to access maple jump pack devices.
13  Puru Puru was Sega's internal name for the device, hence why its referred to
14  in this way here.
15 
16  This driver is largely based off of information provided by Kamjin on the
17  DCEmulation forums. See
18  http://dcemulation.org/phpBB/viewtopic.php?f=29&t=48462 if you're interested
19  in the original documentation.
20 
21  Also, its important to note that not all Jump Packs are created equal. Some
22  of the stuff in here does not do what it seems like it should on many
23  devices. The "decay" setting, for instance, does not seem to work on Sega
24  Puru Purus, and actually makes most (if not all) effects do absolutely
25  nothing. Basically, its all a big guess-and-test game to get things to work
26  the way you might like. Don't be surprised if you manage to set up something
27  that does absolutely nothing on the first try.
28 
29  \author Lawrence Sebald
30 */
31 
32 #ifndef __DC_MAPLE_PURUPURU_H
33 #define __DC_MAPLE_PURUPURU_H
34 
35 #include <sys/cdefs.h>
36 __BEGIN_DECLS
37 
38 #include <arch/types.h>
39 #include <dc/maple.h>
40 
41 /** \brief Effect generation structure.
42 
43  This structure is used for convenience to send an effect to the jump pack.
44  This, along with the various macros in this file can give a slightly better
45  idea of the effect being generated than using the raw values.
46 */
47 typedef struct purupuru_effect {
48  /** \brief The duration of the effect. No idea on units... */
50 
51  /** \brief 2nd effect field. */
53 
54  /** \brief 1st effect field. */
56 
57  /** \brief Special effects field. */
60 
61 /* Set one of each of the following in the effect2 field of the
62  purupuru_effect_t. Valid values for each are 0-7. The LINTENSITY
63  value works with the INTENSITY of effect1 to increase the intensity
64  of the rumble, where UINTENSITY apparently lowers the rumble's
65  intensity somewhat. */
66 
67 /** \brief Upper-nibble of effect2 convenience macro.
68 
69  This macro is for setting the upper nibble of the effect2 field of the
70  purupuru_effect_t. This apparently lowers the rumble's intensity somewhat.
71  Valid values are 0-7.
72 */
73 #define PURUPURU_EFFECT2_UINTENSITY(x) (x << 4)
74 
75 /** \brief Lower-nibble of effect2 convenience macro.
76 
77  This macro is for setting the lower nibble of the effect2 field of the
78  purupuru_effect_t. This value works with the upper nibble of the effect1
79  field to increase the intensity of the rumble effect. Valid values are 0-7.
80 
81  \see PURUPURU_EFFECT1_INTENSITY
82 */
83 #define PURUPURU_EFFECT2_LINTENSITY(x) (x)
84 
85 /* OR these in with your effect2 value if you feel so inclined.
86  if you or the PULSE effect in here, you probably should also
87  do so with the effect1 one below. */
88 /** \brief Give a decay effect to the rumble on some packs. */
89 #define PURUPURU_EFFECT2_DECAY (8 << 4)
90 
91 /** \brief Give a pulse effect to the rumble.
92 
93  This probably should be used with PURUPURU_EFFECT1_PULSE as well.
94 
95  \see PURUPURU_EFFECT1_PULSE
96 */
97 #define PURUPURU_EFFECT2_PULSE (8)
98 
99 /* Set one value for this in the effect1 field of the effect structure. */
100 /** \brief Upper nibble of effect1 convenience macro.
101 
102  This macro is for setting the upper nibble of the effect1 field of the
103  purupuru_effect_t. This value works with the lower nibble of the effect2
104  field to increase the intensity of the rumble effect. Valid values are 0-7.
105 
106  \see PURUPURU_EFFECT2_LINTENSITY
107 */
108 #define PURUPURU_EFFECT1_INTENSITY(x) (x << 4)
109 
110 /* OR these in with your effect1 value, if you need them. PULSE
111  should probably be used with the PULSE in effect2, as well.
112  POWERSAVE will probably make your purupuru ignore that command. */
113 /** \brief Give a pulse effect to the rumble.
114 
115  This probably should be used with PURUPURU_EFFECT2_PULSE as well.
116 
117  \see PURUPURU_EFFECT2_PULSE
118 */
119 #define PURUPURU_EFFECT1_PULSE (8 << 4)
120 
121 /** \brief Ignore this command.
122 
123  Most jump packs will ignore commands with this set in effect1, apparently.
124 */
125 #define PURUPURU_EFFECT1_POWERSAVE (15)
126 
127 /* Special Effects and motor select. The normal purupuru packs will
128  only have one motor. Selecting MOTOR2 for these is probably not
129  a good idea. The PULSE setting here supposably creates a sharp
130  pulse effect, when ORed with the special field. */
131 /** \brief Select motor #1.
132 
133  Most jump packs only have one motor, but on things that do have more than
134  one motor (like PS1->Dreamcast controller adapters that support rumble),
135  this selects the first motor.
136 */
137 #define PURUPURU_SPECIAL_MOTOR1 (1 << 4)
138 
139 /** \brief Select motor #2.
140 
141  Most jump packs only have one motor, but on things that do have more than
142  one motor (like PS1->Dreamcast controller adapters that support rumble),
143  this selects the second motor.
144 */
145 #define PURUPURU_SPECIAL_MOTOR2 (1 << 7)
146 
147 /** \brief Yet another pulse effect.
148 
149  This supposedly creates a sharp pulse effect.
150 */
151 #define PURUPURU_SPECIAL_PULSE (1)
152 
153 /** \brief Send an effect to a jump pack.
154 
155  This function sends an effect created with the purupuru_effect_t structure
156  to a jump pack to be executed.
157 
158  \param dev The device to send the command to.
159  \param effect The effect to send.
160  \retval MAPLE_EOK On success.
161  \retval MAPLE_EAGAIN If the command couldn't be sent. Try again later.
162  \retval MAPLE_ETIMEOUT If the command timed out while blocking.
163 */
165 
166 /** \brief Send a raw effect to a jump pack.
167 
168  This function sends an effect to a jump pack to be executed. This is for if
169  you (for some reason) don't want to use purupuru_effect_t to build the
170  effect up.
171 
172  \param dev The device to send the command to.
173  \param effect The effect to send.
174  \retval MAPLE_EOK On success.
175  \retval MAPLE_EAGAIN If the command couldn't be sent. Try again later.
176  \retval MAPLE_ETIMEOUT If the command timed out while blocking.
177 */
178 int purupuru_rumble_raw(maple_device_t *dev, uint32 effect);
179 
180 /* \cond */
181 /* Init / Shutdown */
182 int purupuru_init();
183 void purupuru_shutdown();
184 /* \endcond */
185 
186 __END_DECLS
187 
188 #endif /* __DC_MAPLE_PURUPURU_H */
189