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