1 /*---------------------------------------------------------------------------*
2   Project:  TwlSDK - include - nitro - vib
3   File:     vib_system.h
4 
5   Copyright 2003-2008 Nintendo. All rights reserved.
6 
7   These coded instructions, statements, and computer programs contain
8   proprietary information of Nintendo of America Inc. and/or Nintendo
9   Company Ltd., and are protected by Federal copyright law. They may
10   not be disclosed to third parties or copied or duplicated in any form,
11   in whole or in part, without the prior written consent of Nintendo.
12 
13   $Date:: 2008-09-18#$
14   $Rev: 8573 $
15   $Author: okubata_ryoma $
16 
17  *---------------------------------------------------------------------------*/
18 
19 #ifndef PULSE_VIB_H
20 #define PULSE_VIB_H
21 
22 #include <nitro.h>
23 
24 #ifdef __cplusplus
25 extern "C" {
26 #endif
27 
28 /*-----------------------------------------------------------------------*
29                     Types and Constants
30  *-----------------------------------------------------------------------*/
31 
32 /*!
33     Maximum number of pulses in the pulse set. Rebuild the library if changes are made.
34 */
35 #define VIB_PULSE_NUM_MAX   6
36 
37 /*!
38     Maximum value of on_time in one cycle (0.1-ms units)
39 */
40 #define VIB_ON_TIME_MAX 15
41 
42 /*!
43     Minimum value of rest_time (0.1-ms units)
44 */
45 #define VIB_REST_TIME_MIN   15
46 
47 /*!
48     Displays the status of the pulse rumble.
49 
50     The standard rumble is a pulse that is 1.5 ms ON, 1.5 ms OFF, and 1.5 ms ON. This allows generation of the strongest vibration.
51 
52 
53     The hardware specifications demand that the value of VIBPulseState must obey the rules below.
54 
55     @li A single on_time must not exceed 1.5ms.
56     @li off_time[n] must be set equal or longer to the value of the previous on_time[n].
57     @li rest_time must be equal to or longer than 1.5ms.
58 
59     Note that these conditions are checked when the VIB_StartPulse function is called.
60 
61     @image html pulse_vib.jpg "Pulse rumble example (when pulse count is three)"
62 */
63 typedef struct
64 {
65     u32     pulse_num;                  /*! How many pulses to generate in a single pulse set. This must be at least 1 and no more than VIB_PULSE_NUM_MAX. */
66     u32     rest_time;                  /*! Length of pause during pulse-set period. 1=0.1 millisecond. */
67     u32     on_time[VIB_PULSE_NUM_MAX]; /*! Length of the activation time. Set a value larger than 0. 1=0.1 millisecond. */
68     u32     off_time[VIB_PULSE_NUM_MAX];/*! Length of the stop time. Set a value larger than 0. 1=0.1 millisecond. */
69     u32     repeat_num;                 /*! Number of times to repeat pulse set. When 0, repeats endlessly. */
70 }
71 VIBPulseState;
72 
73 /*! This is a Rumble Pak-removal callback type */
74 typedef void (*VIBCartridgePulloutCallback) (void);
75 
76 /*-----------------------------------------------------------------------*
77                     External Function Declarations
78  *-----------------------------------------------------------------------*/
79 /*---------------------------------------------------------------------------*
80   Name:         VIB_Init
81 
82   Description:  Initializes Rumble Pak library.
83                 If this function is called again after it has been called once, it is equivalent to the VIB_IsCartridgeEnabled function.
84 
85 
86                 This function internally calls the PM_AppendPreSleepCallback function and registers the callback to end the rumble before entering sleep mode.
87 
88 
89                 This function also internally registers the callback that stops rumbling when cartridge removal is detected. Accordingly, after calling this function, if you set the cartridge removal callback with the CTRDG_SetPulledOutCallback function, the cartridge removal detection callback set with VIB_Init is overwritten.
90 
91 
92                 In that case, you will need to stop the rumbling inside the cartridge removal callback that you set.
93                 If you want to perform processing inside the cartridge removal callback that goes beyond stopping rumbling, register the callback using the VIB_SetCartridgePulloutCallback function, and make it so the processing is performed inside that callback.
94 
95 
96 
97   Arguments:    None.
98 
99   Returns:      None.
100  *---------------------------------------------------------------------------*/
101 extern BOOL VIB_Init(void);
102 
103 /*---------------------------------------------------------------------------*
104   Name:         VIB_End
105 
106   Description:  Ends usage of the Rumble Pak library.
107 
108   Arguments:    None.
109 
110   Returns:      None.
111  *---------------------------------------------------------------------------*/
112 extern void VIB_End(void);
113 
114 /*---------------------------------------------------------------------------*
115   Name:         VIB_StartPulse
116 
117   Description:  Starts the pulse rumble.
118                 If the previous pulse rumble has not been completed, this lets it complete and then starts.
119                 Because the status is copied by the library, there is no need to allocate memory.
120 
121   Arguments:    state: Pulse rumble status
122 
123   Returns:      None.
124  *---------------------------------------------------------------------------*/
125 extern void VIB_StartPulse(const VIBPulseState * state);
126 
127 /*---------------------------------------------------------------------------*
128   Name:         VIB_StopPulse
129 
130   Description:  Stops pulse rumble.
131 
132   Arguments:    None.
133 
134   Returns:      None.
135  *---------------------------------------------------------------------------*/
136 extern void VIB_StopPulse(void);
137 
138 /*---------------------------------------------------------------------------*
139   Name:         VIB_IsExecuting
140 
141   Description:  Determines whether pulse rumble is in progress.
142                 Returns TRUE from the time when rumble is turned on using the VIB_StartPulse function until the time when rumble is turned off using the VIB_StopPulse function.
143 
144   Arguments:    None.
145 
146   Returns:      TRUE: State in which pulse rumble is in progress
147                 FALSE: State in which pulse rumble is not in progress
148  *---------------------------------------------------------------------------*/
149 extern BOOL VIB_IsExecuting(void);
150 
151 /*---------------------------------------------------------------------------*
152   Name:         VIB_SetCartridgePulloutCallback
153 
154   Description:  Registers the Game Pak removal callback.
155                 When the Game Pak is pulled out, the library immediately stops the pulse rumble.
156                 If a callback was registered using this function, it will be called afterwards.
157 
158   Arguments:    func: Cartridge removal callback
159 
160   Returns:      None.
161  *---------------------------------------------------------------------------*/
162 extern void VIB_SetCartridgePulloutCallback(VIBCartridgePulloutCallback func);
163 
164 /*---------------------------------------------------------------------------*
165   Name:         VIB_IsCartridgeEnabled
166 
167   Description:  Determines whether a Rumble Pak is inserted.
168 
169   Arguments:    None.
170 
171   Returns:      TRUE: State in which rumble pack was inserted at startup
172                 FALSE: State in which rumble pack was not inserted at startup
173  *---------------------------------------------------------------------------*/
174 extern BOOL VIB_IsCartridgeEnabled(void);
175 
176 
177 #ifdef __cplusplus
178 } /* extern "C" */
179 #endif
180 
181 #endif  /* PULSE_VIB_H */
182