libctru  v1.6.0
csnd.h
Go to the documentation of this file.
1 /**
2  * @file csnd.h
3  * @brief CSND service. Usage of this service is deprecated in favor of NDSP.
4  */
5 #pragma once
6 
7 #include <3ds/types.h>
8 
9 /// Maximum number of CSND channels.
10 #define CSND_NUM_CHANNELS 32
11 
12 /// Creates a CSND timer value from a sample rate.
13 #define CSND_TIMER(n) (0x3FEC3FC / ((u32)(n)))
14 
15 /**
16  * @brief Converts a vol-pan pair into a left/right volume pair used by the hardware.
17  * @param vol Volume to use.
18  * @param pan Pan to use.
19  * @return A left/right volume pair for use by hardware.
20  */
21 static inline u32 CSND_VOL(float vol, float pan)
22 {
23  float rpan;
24  u32 lvol, rvol;
25 
26  if (vol < 0.0f) vol = 0.0f;
27  else if (vol > 1.0f) vol = 1.0f;
28 
29  rpan = (pan+1) / 2;
30  if (rpan < 0.0f) rpan = 0.0f;
31  else if (rpan > 1.0f) rpan = 1.0f;
32 
33  lvol = vol*(1-rpan) * 0x8000;
34  rvol = vol*rpan * 0x8000;
35  return lvol | (rvol << 16);
36 }
37 
38 /// CSND encodings.
39 enum
40 {
41  CSND_ENCODING_PCM8 = 0, ///< PCM8
42  CSND_ENCODING_PCM16, ///< PCM16
43  CSND_ENCODING_ADPCM, ///< IMA-ADPCM
44  CSND_ENCODING_PSG, ///< PSG (Similar to DS?)
45 };
46 
47 /// CSND loop modes.
48 enum
49 {
50  CSND_LOOPMODE_MANUAL = 0, ///< Manual loop.
51  CSND_LOOPMODE_NORMAL, ///< Normal loop.
52  CSND_LOOPMODE_ONESHOT, ///< Do not loop.
53  CSND_LOOPMODE_NORELOAD, ///< Don't reload.
54 };
55 
56 /// Creates a sound channel value from a channel number.
57 #define SOUND_CHANNEL(n) ((u32)(n) & 0x1F)
58 
59 /// Creates a sound format value from an encoding.
60 #define SOUND_FORMAT(n) ((u32)(n) << 12)
61 
62 /// Creates a sound loop mode value from a loop mode.
63 #define SOUND_LOOPMODE(n) ((u32)(n) << 10)
64 
65 /// Sound flags.
66 enum
67 {
68  SOUND_LINEAR_INTERP = BIT(6), ///< Linear interpolation.
70  SOUND_ONE_SHOT = SOUND_LOOPMODE(CSND_LOOPMODE_ONESHOT), ///< Play the sound once.
75  SOUND_ENABLE = BIT(14), ///< Enable sound.
76 };
77 
78 /// Capture modes.
79 enum
80 {
81  CAPTURE_REPEAT = 0, ///< Repeat capture.
82  CAPTURE_ONE_SHOT = BIT(0), ///< Capture once.
83  CAPTURE_FORMAT_16BIT = 0, ///< PCM16
84  CAPTURE_FORMAT_8BIT = BIT(1), ///< PCM8
85  CAPTURE_ENABLE = BIT(15), ///< Enable capture.
86 };
87 
88 /// Duty cycles for a PSG channel.
89 typedef enum
90 {
91  DutyCycle_0 = 7, ///< 0.0% duty cycle
92  DutyCycle_12 = 0, ///< 12.5% duty cycle
93  DutyCycle_25 = 1, ///< 25.0% duty cycle
94  DutyCycle_37 = 2, ///< 37.5% duty cycle
95  DutyCycle_50 = 3, ///< 50.0% duty cycle
96  DutyCycle_62 = 4, ///< 62.5% duty cycle
97  DutyCycle_75 = 5, ///< 75.0% duty cycle
98  DutyCycle_87 = 6 ///< 87.5% duty cycle
100 
101 /// Channel info.
102 typedef union
103 {
104  u32 value[3]; ///< Raw values.
105  struct
106  {
107  u8 active; ///< Channel active.
108  u8 _pad1; ///< Padding.
109  u16 _pad2; ///< Padding.
110  s16 adpcmSample; ///< Current ADPCM sample.
111  u8 adpcmIndex; ///< Current ADPCM index.
112  u8 _pad3; ///< Padding.
113  u32 unknownZero; ///< Unknown.
114  };
115 } CSND_ChnInfo;
116 
117 /// Capture info.
118 typedef union
119 {
120  u32 value[2]; ///< Raw values.
121  struct
122  {
123  u8 active; ///< Capture active.
124  u8 _pad1; ///< Padding.
125  u16 _pad2; ///< Padding.
126  u32 unknownZero; ///< Unknown.
127  };
128 } CSND_CapInfo;
129 
130 // See here regarding CSND shared-mem commands, etc: http://3dbrew.org/wiki/CSND_Shared_Memory
131 
132 extern vu32* csndSharedMem; ///< CSND shared memory.
133 extern u32 csndSharedMemSize; ///< CSND shared memory size.
134 extern u32 csndChannels; ///< Bitmask of channels that are allowed for usage.
135 
136 /**
137  * @brief Acquires a capture unit.
138  * @param capUnit Pointer to output the capture unit to.
139  */
140 Result CSND_AcquireCapUnit(u32* capUnit);
141 
142 /**
143  * @brief Releases a capture unit.
144  * @param capUnit Capture unit to release.
145  */
147 
148 /**
149  * @brief Flushes the data cache of a memory region.
150  * @param adr Address of the memory region.
151  * @param size Size of the memory region.
152  */
153 Result CSND_FlushDataCache(const void* adr, u32 size);
154 
155 /**
156  * @brief Stores the data cache of a memory region.
157  * @param adr Address of the memory region.
158  * @param size Size of the memory region.
159  */
160 Result CSND_StoreDataCache(const void* adr, u32 size);
161 
162 /**
163  * @brief Invalidates the data cache of a memory region.
164  * @param adr Address of the memory region.
165  * @param size Size of the memory region.
166  */
167 Result CSND_InvalidateDataCache(const void* adr, u32 size);
168 
169 /**
170  * @brief Resets CSND.
171  * Note: Currently breaks sound, don't use for now!
172  */
173 Result CSND_Reset(void);
174 
175 /// Initializes CSND.
176 Result csndInit(void);
177 
178 /// Exits CSND.
179 void csndExit(void);
180 
181 /**
182  * @brief Adds a command to the list, returning a buffer to write arguments to.
183  * @param cmdid ID of the command to add.
184  * @return A buffer to write command arguments to.
185  */
186 u32* csndAddCmd(int cmdid);
187 
188 /**
189  * @brief Adds a command to the list, copying its arguments from a buffer.
190  * @param cmdid ID of the command to add.
191  * @param cmdparams Buffer containing the command's parameters.
192  */
193 void csndWriteCmd(int cmdid, u8* cmdparams);
194 
195 /**
196  * @brief Executes pending CSND commands.
197  * @param waitDone Whether to wait until the commands have finished executing.
198  */
199 Result csndExecCmds(bool waitDone);
200 
201 /**
202  * @brief Sets a channel's play state, resetting registers on stop.
203  * @param channel Channel to use.
204  * @param value Play state to set.
205  */
206 void CSND_SetPlayStateR(u32 channel, u32 value);
207 
208 /**
209  * @brief Sets a channel's play state.
210  * @param channel Channel to use.
211  * @param value Play state to set.
212  */
213 void CSND_SetPlayState(u32 channel, u32 value);
214 
215 /**
216  * @brief Sets a channel's encoding.
217  * @param channel Channel to use.
218  * @param value Encoding to set.
219  */
220 void CSND_SetEncoding(u32 channel, u32 value);
221 
222 /**
223  * @brief Sets the data of a channel's block.
224  * @param channel Channel to use.
225  * @param block Block to set.
226  * @param physaddr Physical address to set the block to.
227  * @param size Size of the block.
228  */
229 void CSND_SetBlock(u32 channel, int block, u32 physaddr, u32 size);
230 
231 /**
232  * @brief Sets whether to loop a channel.
233  * @param channel Channel to use.
234  * @param value Whether to loop the channel.
235  */
236 void CSND_SetLooping(u32 channel, u32 value);
237 
238 /**
239  * @brief Sets bit 7 of a channel.
240  * @param channel Channel to use.
241  * @param set Value to set.
242  */
243 void CSND_SetBit7(u32 channel, bool set);
244 
245 /**
246  * @brief Sets whether a channel should use interpolation.
247  * @param channel Channel to use.
248  * @param interp Whether to use interpolation.
249  */
250 void CSND_SetInterp(u32 channel, bool interp);
251 
252 /**
253  * @brief Sets a channel's duty.
254  * @param channel Channel to use.
255  * @param duty Duty to set.
256  */
257 void CSND_SetDuty(u32 channel, CSND_DutyCycle duty);
258 
259 /**
260  * @brief Sets a channel's timer.
261  * @param channel Channel to use.
262  * @param timer Timer to set.
263  */
264 void CSND_SetTimer(u32 channel, u32 timer);
265 
266 /**
267  * @brief Sets a channel's volume.
268  * @param channel Channel to use.
269  * @param chnVolumes Channel volume data to set.
270  * @param capVolumes Capture volume data to set.
271  */
272 void CSND_SetVol(u32 channel, u32 chnVolumes, u32 capVolumes);
273 
274 /**
275  * @brief Sets a channel's ADPCM state.
276  * @param channel Channel to use.
277  * @param block Current block.
278  * @param sample Current sample.
279  * @param index Current index.
280  */
281 void CSND_SetAdpcmState(u32 channel, int block, int sample, int index);
282 
283 /**
284  * @brief Sets a whether channel's ADPCM data should be reloaded when the second block is played.
285  * @param channel Channel to use.
286  * @param reload Whether to reload ADPCM data.
287  */
288 void CSND_SetAdpcmReload(u32 channel, bool reload);
289 
290 /**
291  * @brief Sets CSND's channel registers.
292  * @param flags Flags to set.
293  * @param physaddr0 Physical address of the first buffer to play.
294  * @param physaddr1 Physical address of the second buffer to play.
295  * @param totalbytesize Total size of the data to play.
296  * @param chnVolumes Channel volume data.
297  * @param capVolumes Capture volume data.
298  */
299 void CSND_SetChnRegs(u32 flags, u32 physaddr0, u32 physaddr1, u32 totalbytesize, u32 chnVolumes, u32 capVolumes);
300 
301 /**
302  * @brief Sets CSND's PSG channel registers.
303  * @param flags Flags to set.
304  * @param chnVolumes Channel volume data.
305  * @param capVolumes Capture volume data.
306  * @param duty Duty value to set.
307  */
308 void CSND_SetChnRegsPSG(u32 flags, u32 chnVolumes, u32 capVolumes, CSND_DutyCycle duty);
309 
310 /**
311  * @brief Sets CSND's noise channel registers.
312  * @param flags Flags to set.
313  * @param chnVolumes Channel volume data.
314  * @param capVolumes Capture volume data.
315  */
316 void CSND_SetChnRegsNoise(u32 flags, u32 chnVolumes, u32 capVolumes);
317 
318 /**
319  * @brief Sets whether a capture unit is enabled.
320  * @param capUnit Capture unit to use.
321  * @param enable Whether to enable the capture unit.
322  */
323 void CSND_CapEnable(u32 capUnit, bool enable);
324 
325 /**
326  * @brief Sets whether a capture unit should repeat.
327  * @param capUnit Capture unit to use.
328  * @param repeat Whether the capture unit should repeat.
329  */
330 void CSND_CapSetRepeat(u32 capUnit, bool repeat);
331 
332 /**
333  * @brief Sets a capture unit's format.
334  * @param capUnit Capture unit to use.
335  * @param eightbit Format to use.
336  */
337 void CSND_CapSetFormat(u32 capUnit, bool eightbit);
338 
339 /**
340  * @brief Sets a capture unit's second bit.
341  * @param capUnit Capture unit to use.
342  * @param set Value to set.
343  */
344 void CSND_CapSetBit2(u32 capUnit, bool set);
345 
346 /**
347  * @brief Sets a capture unit's timer.
348  * @param capUnit Capture unit to use.
349  * @param timer Timer to set.
350  */
351 void CSND_CapSetTimer(u32 capUnit, u32 timer);
352 
353 /**
354  * @brief Sets a capture unit's buffer.
355  * @param capUnit Capture unit to use.
356  * @param addr Buffer address to use.
357  * @param size Size of the buffer.
358  */
359 void CSND_CapSetBuffer(u32 capUnit, u32 addr, u32 size);
360 
361 /**
362  * @brief Sets a capture unit's capture registers.
363  * @param capUnit Capture unit to use.
364  * @param flags Capture unit flags.
365  * @param addr Capture unit buffer address.
366  * @param size Buffer size.
367  */
368 void CSND_SetCapRegs(u32 capUnit, u32 flags, u32 addr, u32 size);
369 
370 /**
371  * @brief Sets up DSP flags.
372  * @param waitDone Whether to wait for completion.
373  */
374 Result CSND_SetDspFlags(bool waitDone);
375 
376 /**
377  * @brief Updates CSND information.
378  * @param waitDone Whether to wait for completion.
379  */
380 Result CSND_UpdateInfo(bool waitDone);
381 
382 /**
383  * @brief Plays a sound.
384  * @param chn Channel to play the sound on.
385  * @param flags Flags containing information about the sound.
386  * @param sampleRate Sample rate of the sound.
387  * @param vol The volume, ranges from 0.0 to 1.0 included.
388  * @param pan The pan, ranges from -1.0 to 1.0 included.
389  * @param data0 First block of sound data.
390  * @param data1 Second block of sound data. This is the block that will be looped over.
391  * @param size Size of the sound data.
392  *
393  * In this implementation if the loop mode is used, data1 must be in the range [data0 ; data0 + size]. Sound will be played once from data0 to data0 + size and then loop between data1 and data0+size.
394  */
395 Result csndPlaySound(int chn, u32 flags, u32 sampleRate, float vol, float pan, void* data0, void* data1, u32 size);
396 
397 /**
398  * @brief Gets CSND's DSP flags.
399  * Note: Requires previous CSND_UpdateInfo()
400  * @param outSemFlags Pointer to write semaphore flags to.
401  * @param outIrqFlags Pointer to write interrupt flags to.
402  */
403 void csndGetDspFlags(u32* outSemFlags, u32* outIrqFlags);
404 
405 /**
406  * @brief Gets a channel's information.
407  * Note: Requires previous CSND_UpdateInfo()
408  * @param channel Channel to get information for.
409  * @return The channel's information.
410  */
412 
413 /**
414  * @brief Gets a capture unit's information.
415  * Note: Requires previous CSND_UpdateInfo()
416  * @param capUnit Capture unit to get information for.
417  * @return The capture unit's information.
418  */
420 
421 /**
422  * @brief Gets a channel's state.
423  * @param channel Channel to get the state of.
424  * @param out Pointer to output channel information to.
425  */
426 Result csndGetState(u32 channel, CSND_ChnInfo* out);
427 
428 /**
429  * @brief Gets whether a channel is playing.
430  * @param channel Channel to check.
431  * @param status Pointer to output the channel status to.
432  */
433 Result csndIsPlaying(u32 channel, u8* status);
PSG.
Definition: csnd.h:74
void CSND_SetInterp(u32 channel, bool interp)
Sets whether a channel should use interpolation.
volatile u32 vu32
32-bit volatile unsigned integer.
Definition: types.h:33
Manual loop.
Definition: csnd.h:50
Various system types.
PSG (Similar to DS?)
Definition: csnd.h:44
s32 Result
Function result.
Definition: types.h:42
IMA-ADPCM.
Definition: csnd.h:43
75.0% duty cycle
Definition: csnd.h:97
u32 unknownZero
Unknown.
Definition: csnd.h:126
Capture once.
Definition: csnd.h:82
Result CSND_Reset(void)
Resets CSND.
uint16_t u16
16-bit unsigned integer
Definition: types.h:22
u16 _pad2
Padding.
Definition: csnd.h:125
12.5% duty cycle
Definition: csnd.h:92
void CSND_SetChnRegsPSG(u32 flags, u32 chnVolumes, u32 capVolumes, CSND_DutyCycle duty)
Sets CSND's PSG channel registers.
void CSND_SetLooping(u32 channel, u32 value)
Sets whether to loop a channel.
void csndWriteCmd(int cmdid, u8 *cmdparams)
Adds a command to the list, copying its arguments from a buffer.
void CSND_SetChnRegsNoise(u32 flags, u32 chnVolumes, u32 capVolumes)
Sets CSND's noise channel registers.
u8 _pad1
Padding.
Definition: csnd.h:108
Repeat the sound.
Definition: csnd.h:69
void CSND_SetEncoding(u32 channel, u32 value)
Sets a channel's encoding.
uint8_t u8
would be nice if newlib had this already
Definition: types.h:21
Enable sound.
Definition: csnd.h:75
25.0% duty cycle
Definition: csnd.h:93
#define SOUND_FORMAT(n)
Creates a sound format value from an encoding.
Definition: csnd.h:60
#define SOUND_LOOPMODE(n)
Creates a sound loop mode value from a loop mode.
Definition: csnd.h:63
void csndGetDspFlags(u32 *outSemFlags, u32 *outIrqFlags)
Gets CSND's DSP flags.
Result CSND_FlushDataCache(const void *adr, u32 size)
Flushes the data cache of a memory region.
PCM8.
Definition: csnd.h:41
Don't reload.
Definition: csnd.h:53
u8 adpcmIndex
Current ADPCM index.
Definition: csnd.h:111
PCM16.
Definition: csnd.h:83
CSND_CapInfo * csndGetCapInfo(u32 capUnit)
Gets a capture unit's information.
uint32_t u32
32-bit unsigned integer
Definition: types.h:23
Result CSND_StoreDataCache(const void *adr, u32 size)
Stores the data cache of a memory region.
Result CSND_InvalidateDataCache(const void *adr, u32 size)
Invalidates the data cache of a memory region.
void CSND_CapEnable(u32 capUnit, bool enable)
Sets whether a capture unit is enabled.
u32 * csndAddCmd(int cmdid)
Adds a command to the list, returning a buffer to write arguments to.
void CSND_CapSetFormat(u32 capUnit, bool eightbit)
Sets a capture unit's format.
void CSND_SetCapRegs(u32 capUnit, u32 flags, u32 addr, u32 size)
Sets a capture unit's capture registers.
Result csndInit(void)
Initializes CSND.
Result CSND_ReleaseCapUnit(u32 capUnit)
Releases a capture unit.
Repeat capture.
Definition: csnd.h:81
void CSND_SetPlayState(u32 channel, u32 value)
Sets a channel's play state.
ADPCM.
Definition: csnd.h:73
void CSND_SetChnRegs(u32 flags, u32 physaddr0, u32 physaddr1, u32 totalbytesize, u32 chnVolumes, u32 capVolumes)
Sets CSND's channel registers.
Play the sound once.
Definition: csnd.h:70
PCM8.
Definition: csnd.h:84
Normal loop.
Definition: csnd.h:51
void CSND_SetAdpcmState(u32 channel, int block, int sample, int index)
Sets a channel's ADPCM state.
vu32 * csndSharedMem
CSND shared memory.
s16 adpcmSample
Current ADPCM sample.
Definition: csnd.h:110
0.0% duty cycle
Definition: csnd.h:91
void CSND_CapSetBuffer(u32 capUnit, u32 addr, u32 size)
Sets a capture unit's buffer.
void CSND_SetPlayStateR(u32 channel, u32 value)
Sets a channel's play state, resetting registers on stop.
Result CSND_AcquireCapUnit(u32 *capUnit)
Acquires a capture unit.
PCM16.
Definition: csnd.h:42
void CSND_SetBlock(u32 channel, int block, u32 physaddr, u32 size)
Sets the data of a channel's block.
void csndExit(void)
Exits CSND.
Result csndExecCmds(bool waitDone)
Executes pending CSND commands.
50.0% duty cycle
Definition: csnd.h:95
void CSND_SetTimer(u32 channel, u32 timer)
Sets a channel's timer.
CSND_ChnInfo * csndGetChnInfo(u32 channel)
Gets a channel's information.
#define BIT(n)
Creates a bitmask from a bit number.
Definition: types.h:47
u32 csndSharedMemSize
CSND shared memory size.
Do not loop.
Definition: csnd.h:52
Result CSND_UpdateInfo(bool waitDone)
Updates CSND information.
37.5% duty cycle
Definition: csnd.h:94
Result CSND_SetDspFlags(bool waitDone)
Sets up DSP flags.
u16 _pad2
Padding.
Definition: csnd.h:109
Channel info.
Definition: csnd.h:102
u8 active
Capture active.
Definition: csnd.h:123
void CSND_SetDuty(u32 channel, CSND_DutyCycle duty)
Sets a channel's duty.
Result csndGetState(u32 channel, CSND_ChnInfo *out)
Gets a channel's state.
void CSND_SetAdpcmReload(u32 channel, bool reload)
Sets a whether channel's ADPCM data should be reloaded when the second block is played.
Result csndIsPlaying(u32 channel, u8 *status)
Gets whether a channel is playing.
62.5% duty cycle
Definition: csnd.h:96
Enable capture.
Definition: csnd.h:85
void CSND_CapSetBit2(u32 capUnit, bool set)
Sets a capture unit's second bit.
Linear interpolation.
Definition: csnd.h:68
Capture info.
Definition: csnd.h:118
u32 unknownZero
Unknown.
Definition: csnd.h:113
PCM16.
Definition: csnd.h:72
void CSND_SetBit7(u32 channel, bool set)
Sets bit 7 of a channel.
static u32 CSND_VOL(float vol, float pan)
Converts a vol-pan pair into a left/right volume pair used by the hardware.
Definition: csnd.h:21
void CSND_CapSetTimer(u32 capUnit, u32 timer)
Sets a capture unit's timer.
Result csndPlaySound(int chn, u32 flags, u32 sampleRate, float vol, float pan, void *data0, void *data1, u32 size)
Plays a sound.
CSND_DutyCycle
Duty cycles for a PSG channel.
Definition: csnd.h:89
u32 csndChannels
Bitmask of channels that are allowed for usage.
u8 active
Channel active.
Definition: csnd.h:107
void CSND_CapSetRepeat(u32 capUnit, bool repeat)
Sets whether a capture unit should repeat.
u8 _pad3
Padding.
Definition: csnd.h:112
u8 _pad1
Padding.
Definition: csnd.h:124
int16_t s16
16-bit signed integer
Definition: types.h:27
PCM8.
Definition: csnd.h:71
void CSND_SetVol(u32 channel, u32 chnVolumes, u32 capVolumes)
Sets a channel's volume.
87.5% duty cycle
Definition: csnd.h:98