1 /*---------------------------------------------------------------------------*
2 Project: Horizon
3 File: snd_Api.h
4
5 Copyright (C)2009 Nintendo Co., Ltd. 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 $Rev: 30947 $
14 *---------------------------------------------------------------------------*/
15
16 #ifndef NN_SND_API_H_
17 #define NN_SND_API_H_
18
19 #include <nn/Result.h>
20 #include <nn/snd/CTR/Common/snd_Types.h>
21 #include <nn/snd/CTR/MPCore/snd_Voice.h>
22 #include <nn/snd/CTR/MPCore/snd_OutputCapture.h>
23 #include <nn/snd/CTR/MPCore/snd_FxDelay.h>
24 #include <nn/snd/CTR/MPCore/snd_FxReverb.h>
25
26 #ifdef __cplusplus
27
28 /*! @file
29 @brief サウンド（SND）に関する API の宣言
30 */
31
32 namespace nn { namespace snd { namespace CTR {
33
34 /*!
35 @brief 1 サウンドフレームあたりの DSP のサイクル数の最大値です。
36 */
37 static const s32 NN_SND_DSP_MAXIMUM_CYCLES = 622535;
38
39
40 /*!
41 @name Initialize/Finalize
42
43 @{
44 */
45 /*!
46 @brief サウンドライブラリの初期化処理を行います。
47
48 @ref nn::dsp::Initialize() によりDSP プロセスとのセッション確立後に使用できます。
49
50 @return 処理の結果が返ってきます。<BR>
51 LEVEL_SUCCESS:SUMMARY_SUCCESS:MODULE_COMMON:DESCRIPTION_SUCCESS・・・成功しました。
52 */
53 nn::Result Initialize();
54
55 /*!
56 @brief サウンドライブラリの終了処理を行います。
57
58 @return 処理の結果が返ってきます。<BR>
59 LEVEL_SUCCESS:SUMMARY_SUCCESS:MODULE_COMMON:DESCRIPTION_SUCCESS・・・成功しました。
60 */
61 nn::Result Finalize();
62
63 /*!
64 @brief バッファ情報構造体の初期化を行います。
65
66 @ref nn::snd::Voice::AppendWaveBuffer を呼び出す前に、本関数で構造体を初期化して下さい。
67
68 @param[in] pWaveBuffer バッファ情報構造体へのポインタ
69 @return なし。
70 */
71 void InitializeWaveBuffer(WaveBuffer * pWaveBuffer);
72
73 /*! :private
74 @brief サウンドスレッドを作成します。
75 */
76 nn::Result StartSoundThread(
77 void (*callback)(uptr),
78 uptr arg,
79 uptr stackBuffer,
80 size_t stackSize,
81 s32 prio,
82 s32 coreNo = NN_OS_CORE_NO_USE_PROCESS_VALUE
83 );
84
85 /*! :private
86 @brief ユーザーサウンドスレッドを作成します。
87 */
88 nn::Result StartUserSoundThread(uptr stackBuffer, size_t stackSize, s32 prio);
89
90 /*! :private
91 @brief サウンドスレッドを作成します。
92 */
93 nn::Result StartSoundThread(
94 const ThreadParameter* mainThreadParam,
95 void (*mainThreadCallback)(uptr),
96 uptr mainThreadArg,
97 const ThreadParameter* userThreadParam,
98 void (*userThreadCallback)(uptr),
99 uptr userThreadArg,
100 s32 coreNo
101 );
102
103 /*! :private
104 @brief StartSoundThread で作成したサウンドスレッドを終了します。
105 */
106 void FinalizeSoundThread();
107
108 /*! :private
109 @brief StartUserSoundThread で作成したユーザーサウンドスレッドを終了します。
110 */
FinalizeUserSoundThread()111 inline void FinalizeUserSoundThread() {}
112
113 /*! :private
114 @brief サウンドフレームの処理負荷を有効 / 無効にします。
115
116 デフォルトは無効です。
117
118 @param[in] enable true なら有効、false なら無効
119 */
120 void EnableSoundThreadTickCounter(bool enable);
121
122 /*! :private
123 @brief StartSoundThread で作成したサウンドスレッドの、1 サウンドフレームあたりの処理負荷を取得します。
124
125 コールバック内で呼び出した場合は、ひとつ前のサウンドフレームの処理負荷が得られます。
126 */
127 nn::os::Tick GetSoundThreadTick();
128
129 /*! :private
130 @brief 自動 UpdateCommand の設定を行います。
131 @param[in] autoUpdateCommand true なら自動アップデート
132 */
133 void SetAutoUpdateCommand(bool autoUpdateCommand);
134
135 // TORIAEZU: CTR-SDK 0.14 を NintendoWare 1.1.1 と組み合わせて使用するための暫定措置
EnableAuxBusProcessingOnCore1(bool)136 inline void EnableAuxBusProcessingOnCore1(bool /*enable*/) {}
EnableSoundThreadCallbackOnCore1(bool)137 inline void EnableSoundThreadCallbackOnCore1(bool /*enable*/) {}
EnableVoiceDropCallbackOnCore1(bool)138 inline void EnableVoiceDropCallbackOnCore1(bool /*enable*/) {}
139
140 /*!
141 @}
142 */
143
144 /*!
145 @name キャッシュ操作
146
147 @{
148 */
149 /*!
150 @brief 指定された範囲のデータをキャッシュからメモリに書き戻し、キャッシュを無効にします。
151
152 動作は @ref nn::dsp::CTR::FlushDataCache と同じです。
153
154 @param[in] addr メモリアドレス
155 @param[in] size メモリサイズ
156 @return 処理の結果が返ります。<BR>
157 LEVEL_SUCCESS:SUMMARY_SUCCESS:MODULE_COMMON:DESCRIPTION_SUCCESS・・・成功しました。<BR>
158 LEVEL_STATUS:SUMMARY_INVALID_STATE:MODULE_NN_DSP:DESCRIPTION_NOT_INITIALIZED・・・DSP ライブラリが初期化されていません。<BR>
159 */
160 nn::Result FlushDataCache( uptr addr, size_t size );
161
162 /*! :private
163 @brief 指定された範囲のキャッシュを無効にします。
164
165 動作は @ref nn::dsp::CTR::InvalidateDataCache と同じです。
166
167 @param[in] addr メモリアドレス
168 @param[in] size メモリサイズ
169 @return 処理の結果が返ります。<BR>
170 LEVEL_SUCCESS:SUMMARY_SUCCESS:MODULE_COMMON:DESCRIPTION_SUCCESS・・・成功しました。<BR>
171 LEVEL_STATUS:SUMMARY_INVALID_STATE:MODULE_NN_DSP:DESCRIPTION_NOT_INITIALIZED・・・DSP ライブラリが初期化されていません。<BR>
172 */
173 nn::Result InvalidateDataCache( uptr addr, size_t size );
174
175 /*!
176 @}
177 */
178
179 /*!
180 @name 同期処理
181
182 @{
183 */
184
185 /*!
186 @brief DSP で処理を行った結果を受信します。
187
188 サウンドフレームイベントが発生するまで待機します。
189 シグナルが通知された後、DSP からのデータを受信します。
190
191 @return なし。
192 */
193 void WaitForDspSync();
194
195 /*! :private
196 @brief DSP で処理を行った結果を受信し、受信に要した処理時間を取得します。
197
198 サウンドフレームイベントが発生するまで待機します。
199 シグナルが通知された後、DSP からのデータを受信します。
200
201 @param[out] pTick 内部の Wait 以外の処理に要したサイクル数
202 @return なし。
203 */
204 void WaitForDspSync(nn::os::Tick* pTick);
205
206 /*!
207 @brief 設定されたパラメータをDSP に反映します。
208
209 @return なし。
210 */
211 void SendParameterToDsp();
212
213 /*! :private
214 @brief 必要であれば内部で UpdateCommand を実行し、設定されたパラメータを DSP に反映します。
215 @param[in] autoUpdateCommand true なら内部で UpdateCommand を実行します。
216 */
217 void SendParameterToDsp(bool autoUpdateCommand);
218
219 /*! :private
220 @brief 発行したコマンドを DSP へ送信します。
221 */
222 void UpdateCommand();
223
224 /*!
225 @}
226 */
227
228 /*!
229 @brief サンプルの長さを取得します。
230
231 @param[in] size サイズ（バイト単位）
232 @param[in] format 形式
233 @param[in] channelCount チャンネル数
234 @return サンプルの長さを返します。
235 */
236 s32 GetSampleLength( s32 size, SampleFormat format, s32 channelCount ) ;
237
238 /*!
239 @name マスター操作、Aux バス操作
240 @{
241 */
242 /*!
243 @brief マスターボリュームを設定します。
244
245 @param[in] volume マスターボリューム（1.0 が等倍）
246 @return なし。
247 */
248 void SetMasterVolume ( f32 volume );
249
250 /*!
251 @brief Aux バスボリュームを設定します。
252
253 等倍は 1.0 です。
254
255 デフォルト値は 1.0 です。
256
257 @param[in] busId バスの ID
258 @param[in] volume エフェクト 0 バスボリューム（1.0 が等倍）
259 @return なし。
260 */
261 void SetAuxReturnVolume ( AuxBusId busId, f32 volume );
262
263 /*!
264 @brief Aux バスボリュームを取得します。
265
266 等倍は 1.0 です。
267
268 デフォルト値は 1.0 です。
269
270 @param[in] busId バスの ID
271 @return バスボリューム。
272 */
273 f32 GetAuxReturnVolume ( AuxBusId busId ) ;
274
275 /*!
276 @brief Aux バスのコールバック関数を設定します。
277
278 @param[in] busId バスの ID
279 @param[in] callback コールバック関数
280 @param[in] userData ユーザ定義データ
281 @return なし。
282 */
283 void RegisterAuxCallback( AuxBusId busId, AuxCallback callback, uptr userData );
284
285 /*!
286 @brief Aux バスのコールバック関数を取得します。
287
288 @param[in] busId バスの ID
289 @param[out] pCallback コールバック関数の格納先
290 @param[out] pUserData ユーザ定義データの格納先
291 @return なし。
292 */
293 void GetAuxCallback( AuxBusId busId, AuxCallback* pCallback, uptr* pUserData );
294
295 /*!
296 @brief Aux バスのコールバック関数を解除します。
297
298 @param[in] busId バスの ID
299 @return なし。
300 */
301 void ClearAuxCallback( AuxBusId busId );
302
303 /*!
304 @brief Aux バスのフロントバイパスを設定します。
305 @param[in] busId バスの ID
306 @param[in] flag フロントバイパスの有効 / 無効フラグ
307 @return 設定に成功すれば true を、失敗すれば false を返します。
308 */
309 bool SetAuxFrontBypass(AuxBusId busId, bool flag);
310 /*!
311 @}
312 */
313
314 /*!
315 @name 3D サラウンド
316 @{
317 */
318 /*!
319 @brief サウンド出力モードを設定します。
320
321 @param[in] mode サウンド出力モード
322 @return 設定に成功すれば true を、失敗すれば false を返します。
323 */
324 bool SetSoundOutputMode(OutputMode mode);
325
326 /*!
327 @brief サウンド出力モードを取得します。
328
329 @return サウンド出力モード
330 */
331 OutputMode GetSoundOutputMode();
332
333 /*!
334 @brief クリッピングモードを設定します。
335 @param[in] mode モード
336 @return 設定に成功すれば true を、失敗すれば false を返します。
337 */
338 bool SetClippingMode(ClippingMode mode);
339
340 /*!
341 @brief クリッピングモードを取得します。
342 @return モード
343 */
344 ClippingMode GetClippingMode();
345
346 /*! :private
347 @brief ミックス時のリア成分への重みを設定します。サラウンドモードでは無視されます。
348
349 @param[in] depth 重み (0 以上 1 以下の値でなければなりません）
350 @return 設定に成功すれば true を、失敗すれば false を返します。
351 */
352 bool SetRearRatio(f32 depth);
353
354 /*!
355 @brief サラウンドデプスを設定します。
356
357 サラウンドデプスは、スピーカー出力時の 3D サラウンドの効果の大小を
358 表すパラメータです。値が大きい程、効果が大きくなります。
359 サラウンドデプスはヘッドフォン出力時の効果には影響しません。
360
361 デフォルト値は 1.0f です。
362
363 @param[in] depth サラウンドデプス（0 <= depth <= 1.0f）
364 @return 設定に成功すれば true を、失敗すれば false を返します。
365 */
366 bool SetSurroundDepth(f32 depth);
367
368 /*!
369 @brief 3D サラウンドの仮想スピーカー位置を設定します。
370
371 @param[in] pos 仮想スピーカー位置
372 @return 設定に成功すれば true を、失敗すれば false を返します。
373 */
374 bool SetSurroundSpeakerPosition(SurroundSpeakerPosition pos);
375
376 /*! :private
377 @brief 3D サラウンド用空間フィルタを設定します。
378
379 @param[in] pSrc フィルタ係数バッファアドレス
380 @param[in] nCoeffs フィルタのタップ数
381 @return 設定に成功すれば true を、失敗すれば false を返します。
382 */
383 bool SetSurroundSpacialFilter(s16* pSrc, s32 nCoeffs);
384
385 /*! :private
386 @brief 3D サラウンド用方向フィルタを設定します。
387
388 @param[in] pSrc フィルタ係数バッファアドレス
389 @param[in] nCoeffs フィルタのタップ数
390 @param[in] mode モード（NN_SND_DEBUG_3DS_SPEAKER / NN_SND_DEBUG_3DS_HEADPHONE のいずれか）
391 @return 設定に成功すれば true を、失敗すれば false を返します。
392 */
393 bool SetSurroundDirectionFilter(s16* pSrc, s32 nCoeffs, s32 mode);
394
395 /*! :private
396 @brief 3D サラウンド用 IIR フィルタを設定します。
397
398 @param[in] pSrc フィルタ係数バッファアドレス
399 @param[in] nCoeffs フィルタのタップ数
400 @param[in] mode モード（NN_SND_DEBUG_3DS_SPEAKER / NN_SND_DEBUG_3DS_HEADPHONE のいずれか）
401 @return 設定に成功すれば true を、失敗すれば false を返します。
402 */
403 bool SetSurroundIirFilterCoeffs(s32* pSrc, s32 nCoeffs, s32 mode);
404
405 /*! :private
406 @brief 3D サラウンド用 IIR フィルタの On/Off を設定します。
407
408 @param[in] flag true なら On, false なら Off
409 @return 設定に成功すれば true を、失敗すれば false を返します。
410 */
411 bool SetSurroundIirFilterFlag(bool flag);
412
413 /*!
414 @}
415 */
416
417 /*!
418 @brief サウンドが使用できるDSP サイクル数を設定します。
419
420 初期状態ではNN_SND_DSP_MAXIMUM_CYCLES が設定されています。
421 NN_SND_DSP_MAXIMUM_CYCLES 以上の値が入力された場合は
422 NN_SND_DSP_MAXIMUM_CYCLES が設定されます。
423
424 @param[in] cycles サイクル数
425 @return なし。
426 */
427 void SetMaximumDspCycles( s32 cycles );
428
429 /*!
430 @brief サウンドに割り当てているDSP サイクル数を取得します。
431
432 @return サイクル数を返します。
433 */
434 s32 GetMaximumDspCycles();
435
436 /*!
437 @brief 最後のオーディオフレーム作成でDSP が費やしたサイクル数を取得します。
438
439 @return DSP で消費したサイクル数を返します。
440 */
441 s32 GetDspCycles();
442
443 /*! :private
444 @brief snd 処理を一時中断し、終了処理を行います。
445 */
446 void Sleep();
447
448 /*! :private
449 @brief 一時中断した snd の処理を復元します。
450 */
451 void WakeUp();
452
453 /*! :private
454 @brief 終了処理のための準備を行います。
455 */
456 void OrderToWaitForFinalize();
457
458 /*!
459 @brief ヘッドホンの挿入状態を取得します。
460 @return 挿入されている場合は true を返します。
461 */
462 bool GetHeadphoneStatus();
463
464 /*!
465 @brief ヘッドホンの挿入状態を更新し、取得します。
466 @return 挿入されている場合は true を返します。
467 */
468 bool UpdateHeadphoneStatus();
469
470 /*! :private
471 @brief 蓋閉じ時に強制的にヘッドフォン出力にするかどうかを設定します。
472 @param[in] forceout true なら強制ヘッドフォン出力とします。
473 @return 処理の結果が返ります。
474 */
SetHeadphoneOutOnShellClose(bool forceout)475 inline Result SetHeadphoneOutOnShellClose(bool forceout)
476 {
477 return dsp::ForceHeadphoneOut(forceout);
478 }
479
480 /*!
481 @name DSP 最終出力取得
482 @{
483 */
484 /*!
485 @brief Mix バスデータを指定のバッファにコピーします。
486 @param[out] pData Mix バスデータの内容をコピーするバッファアドレス
487 @param[in] nSamplesPerFrame チャンネルあたりのサンプル数（通常は NN_SND_SAMPLES_PER_FRAME を指定します）
488 @return データ取得に成功すれば true を、失敗すれば false を返します。
489 */
490 bool GetMixedBusData(s16* pData, s32 nSamplesPerFrame = NN_SND_SAMPLES_PER_FRAME);
491 /*!
492 @}
493 */
494
495 /*!
496 @name 処理落ち検出
497 @{
498 */
499 /*!
500 @brief 処理落ちしたサウンドフレームの数を取得します。
501 @return 処理落ちしたサウンドフレームの数を返します。
502 */
503 s32 GetDroppedSoundFrameCount();
504
505 /*!
506 @brief 処理落ちしたサウンドフレームの数を初期化します。
507 */
508 void ClearDroppedSoundFrameCount();
509
510 /*!
511 @}
512 */
513
514 /*!
515 @name DSP-ADPCM 関連
516 @{
517 */
518 /*!
519 @brief 16bit PCM データを DSP-ADPCM フォーマットにエンコードします。
520
521 @param[in] pInput 入力バッファアドレス
522 @param[out] pOutput 出力バッファアドレス（4 バイトアラインされている必要があります）
523 @param[in] nSamples 入力サンプル数
524 @param[in] sampleRate サンプル周波数
525 @param[in] loopStart ループ開始サンプル位置（0 オリジン）
526 @param[in] loopEnd ループ終了サンプル位置（0 オリジン）
527 @param[out] pInfo ヘッダ構造体アドレス
528 @return なし
529 */
530 s32 EncodeAdpcmData(s16* pInput, u8* pOutput, s32 nSamples, s32 sampleRate, s32 loopStart, s32 loopEnd, DspsndAdpcmHeader* pInfo);
531
532 /*!
533 @brief DSP-ADPCM データをデコードします。
534
535 @param[in] pInput 入力バッファアドレス
536 @param[out] pOutput 出力バッファアドレス
537 @param[in] param ADPCM パラメータ
538 @param[in] context ADPCM コンテキスト
539 @param[in] nSamples 入力サンプル数
540 */
541 void DecodeAdpcmData(u8* pInput, s16* pOutput, AdpcmParam& param, AdpcmContext& context, s32 nSamples);
542
543 /*!
544 @brief エンコード時に必要な出力バッファのサイズを返します。
545
546 @param[in] nSamples 入力サンプル数
547 @return 出力バッファのサイズ
548 */
549 s32 GetAdpcmOutputBufferSize(s32 nSamples);
550
551 /*!
552 @brief サンプル位置をニブル数に変換します。
553
554 @param[in] nPos サンプル位置
555 @return ニブル数
556 */
557 u32 ConvertAdpcmPos2Nib(u32 nPos);
558 /*!
559 @brief ニブル数をサンプル位置に変換します。
560
561 @param[in] nNib ニブル数
562 @return サンプル位置
563 */
564 u32 ConvertAdpcmNib2Pos(u32 nNib);
565 /*!
566 @}
567 */
568
569 /*!
570 @name エフェクト
571
572 @{
573 */
574
575 /*!
576 @brief ディレイエフェクトを設定します。
577
578 AUX から出力されるデータを加工するには、
579 自前の加工処理関数を @ref RegisterAuxCallback で設定するほか、
580 本関数を用いて、ディレイやリバーブのエフェクトをかけることができます。
581
582 ディレイ (@ref FxDelay) やリバーブ (@ref FxReverb) は、
583 各バスにどちらか 1 つしか設定できないことに注意してください。
584
585 1 つ以上設定すると、後から設定したものが有効になります。
586 もともと設定されていたエフェクトは解除されます。
587
588 @ref ClearEffect を呼び出したり、
589 上記のようにもともと設定されていて解除された場合は、
590 @ref FxDelay::ReleaseWorkBuffer
591 や @ref FxReverb::ReleaseWorkBuffer で、
592 当該エフェクトで使用していたメモリを解放することができます。
593
594 本関数を呼び出す前に、@ref FxDelay クラスの、
595 @ref FxDelay::SetParam, @ref FxDelay::GetRequiredMemSize,
596 @ref FxDelay::AssignWorkBuffer を呼び出し、
597 ディレイエフェクトの準備を済ませておく必要があります。
598
599 @param[in] busId バスの ID
600 @param[in] fx 設定するディレイエフェクト
601
602 @return 設定に成功したら true を返します。
603 fx が NULL の場合、設定に失敗し false を返します。
604
605 @see ClearEffect
606 @see RegisterAuxCallback
607 @see FxDelay クラス
608 @see FxReverb クラス
609 @date 2010/10/20 初版
610 */
611 bool SetEffect(AuxBusId busId, FxDelay* fx);
612
613 /*!
614 @brief リバーブエフェクトを設定します。
615
616 AUX から出力されるデータを加工するには、
617 自前の加工処理関数を @ref RegisterAuxCallback で設定するほか、
618 本関数を用いて、ディレイやリバーブのエフェクトをかけることができます。
619
620 ディレイ (@ref FxDelay) やリバーブ (@ref FxReverb) は、
621 各バスにどちらか 1 つしか設定できないことに注意してください。
622
623 1 つ以上設定すると、後から設定したものが有効になります。
624 もともと設定されていたエフェクトは解除されます。
625
626 @ref ClearEffect を呼び出したり、
627 上記のようにもともと設定されていて解除された場合は、
628 @ref FxDelay::ReleaseWorkBuffer
629 や @ref FxReverb::ReleaseWorkBuffer で、
630 当該エフェクトで使用していたメモリを解放することができます。
631
632 本関数を呼び出す前に、@ref FxReverb クラスの、
633 @ref FxReverb::SetParam, @ref FxReverb::GetRequiredMemSize,
634 @ref FxReverb::AssignWorkBuffer を呼び出し、
635 ディレイエフェクトの準備を済ませておく必要があります。
636
637
638 @param[in] busId バスの ID
639 @param[in] fx 設定するリバーブエフェクト
640
641 @return 設定に成功したら true を返します。
642 fx が NULL の場合、設定に失敗し false を返します。
643 @see ClearEffect
644 @see RegisterAuxCallback
645 @see FxReverb クラス
646 @see FxDelay クラス
647
648 @date 2010/10/20 初版
649 */
650 bool SetEffect(AuxBusId busId, FxReverb* fx);
651
652 /*!
653 @brief エフェクトの設定を解除します。
654
655 @ref SetEffect 関数で設定したエフェクトを解除します。
656
657 @ref RegisterAuxCallback で設定したコールバックは解除されません
658 (これは @ref ClearAuxCallback で解除することができます)。
659
660
661 @param[in] busId バスの ID
662
663 @see SetEffect
664 @see RegisterAuxCallback
665 @see ClearAuxCallback
666
667 @date 2010/10/20 初版
668 */
669 void ClearEffect(AuxBusId busId);
670
671 /*!
672 @}
673 */
674
675 }}} // namespace nn::snd::CTR
676
677 #endif // __cplusplus
678
679 // 以下、C 用宣言
680 /*!
681 @addtogroup nn_snd snd
682
683 @{
684 */
685
686 /*!
687 @brief 対応する C++ 関数 @ref nn::snd::CTR::Initialize を参照してください。
688 */
689 NN_EXTERN_C nnResult nnsndInitialize();
690
691 /*!
692 @}
693 */
694
695 #endif //NN_SND_API_H_
696