/*---------------------------------------------------------------------------* Project: Horizon File: snd_Api.h Copyright (C)2009 Nintendo Co., Ltd. All rights reserved. These coded instructions, statements, and computer programs contain proprietary information of Nintendo of America Inc. and/or Nintendo Company Ltd., and are protected by Federal copyright law. They may not be disclosed to third parties or copied or duplicated in any form, in whole or in part, without the prior written consent of Nintendo. $Rev: 26219 $ *---------------------------------------------------------------------------*/ #ifndef NN_SND_API_H_ #define NN_SND_API_H_ #include #include #include #ifdef __cplusplus /*! @file @brief サウンド（SND）に関する API の宣言 */ namespace nn { namespace snd { namespace CTR { /*! @brief 1 サウンドフレームあたりの DSP のサイクル数の最大値です。 */ static const s32 NN_SND_DSP_MAXIMUM_CYCLES = 622535; /*! @name Initialize/Finalize @{ */ /*! @brief サウンドライブラリの初期化処理を行います。 @ref nn::dsp::Initialize() によりDSP プロセスとのセッション確立後に使用できます。 @return 処理の結果が返ってきます。
LEVEL_SUCCESS:SUMMARY_SUCCESS:MODULE_COMMON:DESCRIPTION_SUCCESS・・・成功しました。 */ nn::Result Initialize(); /*! @brief サウンドライブラリの終了処理を行います。 @return 処理の結果が返ってきます。
LEVEL_SUCCESS:SUMMARY_SUCCESS:MODULE_COMMON:DESCRIPTION_SUCCESS・・・成功しました。 */ nn::Result Finalize(); /*! @brief バッファ情報構造体の初期化を行います。 @ref nn::snd::Voice::AppendWaveBuffer を呼び出す前に、本関数で構造体を初期化して下さい。 @param[in] pWaveBuffer バッファ情報構造体へのポインタ @return なし。 */ void InitializeWaveBuffer(WaveBuffer * pWaveBuffer); /*! :private @brief サウンドスレッドを作成します。 */ nn::Result StartSoundThread( void (*callback)(uptr), uptr arg, uptr stackBuffer, size_t stackSize, s32 prio, s32 coreNo = NN_OS_CORE_NO_USE_PROCESS_VALUE ); /*! :private @brief ユーザーサウンドスレッドを作成します。 */ nn::Result StartUserSoundThread(uptr stackBuffer, size_t stackSize, s32 prio); /*! :private @brief StartSoundThread で作成したサウンドスレッドを終了します。 */ void FinalizeSoundThread(); /*! :private @brief StartUserSoundThread で作成したユーザーサウンドスレッドを終了します。 */ void FinalizeUserSoundThread(); /*! :private @brief サウンドフレームの処理負荷を有効 / 無効にします。 デフォルトは無効です。 @param[in] enable true なら有効、false なら無効 */ void EnableSoundThreadTickCounter(bool enable); /*! :private @brief StartSoundThread で作成したサウンドスレッドの、1 サウンドフレームあたりの処理負荷を取得します。 コールバック内で呼び出した場合は、ひとつ前のサウンドフレームの処理負荷が得られます。 */ nn::os::Tick GetSoundThreadTick(); /*! :private @brief コア 1 での Aux バス処理を有効 / 無効にします。 コア 1 でサウンドフレームを走らせる場合、Aux バス処理はコア 0 のユーザー サウンドスレッドで行われますが、この API を用いることで、コア 1 の サウンドスレッドで Aux バスを処理するよう設定することができます。 この API はデバグ目的で用意されたものであり、動作の保証はされていません。 本 API は将来的に削除され、コア 1 での Aux バス処理は制限される予定です。 デフォルトは無効です。 */ void EnableAuxBusProcessingOnCore1(bool enable); /*! @} */ /*! @name キャッシュ操作 @{ */ /*! @brief 指定された範囲のデータをキャッシュからメモリに書き戻し、キャッシュを無効にします。 動作は @ref nn::dsp::CTR::FlushDataCache と同じです。 @param[in] addr メモリアドレス @param[in] size メモリサイズ @return 処理の結果が返ります。
LEVEL_SUCCESS:SUMMARY_SUCCESS:MODULE_COMMON:DESCRIPTION_SUCCESS・・・成功しました。
LEVEL_STATUS:SUMMARY_INVALID_STATE:MODULE_NN_DSP:DESCRIPTION_NOT_INITIALIZED・・・DSP ライブラリが初期化されていません。
*/ nn::Result FlushDataCache( uptr addr, size_t size ); /*! @brief 指定された範囲のキャッシュを無効にします。 動作は @ref nn::dsp::CTR::InvalidateDataCache と同じです。 @param[in] addr メモリアドレス @param[in] size メモリサイズ @return 処理の結果が返ります。
LEVEL_SUCCESS:SUMMARY_SUCCESS:MODULE_COMMON:DESCRIPTION_SUCCESS・・・成功しました。
LEVEL_STATUS:SUMMARY_INVALID_STATE:MODULE_NN_DSP:DESCRIPTION_NOT_INITIALIZED・・・DSP ライブラリが初期化されていません。
*/ nn::Result InvalidateDataCache( uptr addr, size_t size ); /*! @} */ /*! @name 同期処理 @{ */ /*! @brief DSP で処理を行った結果を受信します。 サウンドフレームイベントが発生するまで待機します。 シグナルが通知された後、DSP からのデータを受信します。 @return なし。 */ void WaitForDspSync(void); /*! @brief DSP で処理を行った結果を受信します。 タイムアウト時間までにサウンドフレームイベントを待ちます。 シグナルが通知された場合、DSP からのデータを受信します。 @param[in] timeout タイムアウト時間を指定します。0 を指定すると即座に処理を返します。 @return タイムアウト時間までにサウンドフレームイベントが発生したかを返します。 */ bool WaitForDspSync(nn::fnd::TimeSpan timeout); /*! :private @brief DSP で処理を行った結果を受信し、受信に要した処理時間を取得します。 サウンドフレームイベントが発生するまで待機します。 シグナルが通知された後、DSP からのデータを受信します。 @param[out] pTick 内部の Wait 以外の処理に要したサイクル数 @return なし。 */ void WaitForDspSync(nn::os::Tick* pTick); /*! @brief 設定されたパラメータをDSP に反映します。 @return なし。 */ void SendParameterToDsp( void ); /*! @} */ /*! @brief サンプルの長さを取得します。 @param[in] size サイズ（バイト単位） @param[in] format 形式 @param[in] channelCount チャンネル数 @return サンプルの長さを返します。 */ s32 GetSampleLength( s32 size, SampleFormat format, s32 channelCount ) ; /*! @brief マスターボリュームを設定します。 @param[in] volume マスターボリューム（1.0 が等倍） @return なし。 */ void SetMasterVolume ( f32 volume ); /*! @brief Aux バスボリュームを設定します。 等倍は 1.0 です。 デフォルト値は 1.0 です。 @param[in] busId バスの ID @param[in] volume エフェクト 0 バスボリューム（1.0 が等倍） @return なし。 */ void SetAuxReturnVolume ( AuxBusId busId, f32 volume ); /*! @brief Aux バスボリュームを取得します。 等倍は 1.0 です。 デフォルト値は 1.0 です。 @param[in] busId バスの ID @return バスボリューム。 */ f32 GetAuxReturnVolume ( AuxBusId busId ) ; /*! @brief Aux バスのコールバック関数を設定します。 @param[in] busId バスの ID @param[in] callback コールバック関数 @param[in] userData ユーザ定義データ @return なし。 */ void RegisterAuxCallback( AuxBusId busId, AuxCallback callback, uptr userData ); /*! @brief Aux バスのコールバック関数を取得します。 @param[in] busId バスの ID @param[out] pCallback コールバック関数の格納先 @param[out] pUserData ユーザ定義データの格納先 @return なし。 */ void GetAuxCallback( AuxBusId busId, AuxCallback* pCallback, uptr* pUserData ); /*! @brief Aux バスのコールバック関数を解除します。 @param[in] busId バスの ID @return なし。 */ void ClearAuxCallback( AuxBusId busId ); /*! @brief Aux バスのフロントバイパスを設定します。 @param[in] busId バスの ID @param[in] flag フロントバイパスの有効 / 無効フラグ @return 設定に成功すれば true を、失敗すれば false を返します。 */ bool SetAuxFrontBypass(AuxBusId busId, bool flag); /*! @brief Mix バスデータを指定のバッファにコピーします。 データはインターリーブされて pData から始まるアドレスにコピーされます。 Mix バスデータは 16bit ステレオ PCM 波形を含んでいるので、 コピーされるデータ長は sizeof(s16) * nSamplesPerFrame * 2 となります。 @param[out] pData Mix バスデータの内容をコピーするバッファアドレス @param[in] nSamplesPerFrame チャンネルあたりのサンプル数（通常は NN_SND_SAMPLES_PER_FRAME を指定します） @return データ取得に成功すれば true を、失敗すれば false を返します。 */ bool GetMixedBusData(s16* pData, s32 nSamplesPerFrame = NN_SND_SAMPLES_PER_FRAME); /*! @name 3D サラウンド @{ */ /*! @brief サウンド出力モードを設定します。 @param[in] mode サウンド出力モード @return 設定に成功すれば true を、失敗すれば false を返します。 */ bool SetSoundOutputMode(OutputMode mode); /*! @brief サウンド出力モードを取得します。 @return サウンド出力モード */ OutputMode GetSoundOutputMode(void); /*! @brief クリッピングモードを設定します。 @param[in] mode モード @return 設定に成功すれば true を、失敗すれば false を返します。 */ bool SetClippingMode(ClippingMode mode); /*! @brief クリッピングモードを取得します。 @return モード */ ClippingMode GetClippingMode(void); /*! :private @brief ミックス時のリア成分への重みを設定します。サラウンドモードでは無視されます。 @param[in] depth 重み (0 以上 1 以下の値でなければなりません） @return 設定に成功すれば true を、失敗すれば false を返します。 */ bool SetRearRatio(f32 depth); /*! @brief サラウンドデプスを設定します。 サラウンドデプスは、スピーカー出力時の 3D サラウンドの効果の大小を 表すパラメータです。値が大きい程、効果が大きくなります。 サラウンドデプスはヘッドフォン出力時の効果には影響しません。 デフォルト値は 1.0f です。 @param[in] depth サラウンドデプス（0 <= depth <= 1.0f） @return 設定に成功すれば true を、失敗すれば false を返します。 */ bool SetSurroundDepth(f32 depth); /*! @brief 3D サラウンドの仮想スピーカー位置を設定します。 @param[in] pos 仮想スピーカー位置 @return 設定に成功すれば true を、失敗すれば false を返します。 */ bool SetSurroundSpeakerPosition(SurroundSpeakerPosition pos); /*! :private @brief 3D サラウンド用空間フィルタを設定します。 @param[in] pSrc フィルタ係数バッファアドレス @param[in] nCoeffs フィルタのタップ数 @return 設定に成功すれば true を、失敗すれば false を返します。 */ bool SetSurroundSpacialFilter(s16* pSrc, s32 nCoeffs); /*! :private @brief 3D サラウンド用方向フィルタを設定します。 @param[in] pSrc フィルタ係数バッファアドレス @param[in] nCoeffs フィルタのタップ数 @param[in] mode モード（NN_SND_DEBUG_3DS_SPEAKER / NN_SND_DEBUG_3DS_HEADPHONE のいずれか） @return 設定に成功すれば true を、失敗すれば false を返します。 */ bool SetSurroundDirectionFilter(s16* pSrc, s32 nCoeffs, s32 mode); /*! :private @brief 3D サラウンド用 IIR フィルタを設定します。 @param[in] pSrc フィルタ係数バッファアドレス @param[in] nCoeffs フィルタのタップ数 @param[in] mode モード（NN_SND_DEBUG_3DS_SPEAKER / NN_SND_DEBUG_3DS_HEADPHONE のいずれか） @return 設定に成功すれば true を、失敗すれば false を返します。 */ bool SetSurroundIirFilterCoeffs(s32* pSrc, s32 nCoeffs, s32 mode); /*! :private @brief 3D サラウンド用 IIR フィルタの On/Off を設定します。 @param[in] flag true なら On, false なら Off @return 設定に成功すれば true を、失敗すれば false を返します。 */ bool SetSurroundIirFilterFlag(bool flag); /*! @} */ /*! @brief サウンドが使用できるDSP サイクル数を設定します。 初期状態ではNN_SND_DSP_MAXIMUM_CYCLES が設定されています。 NN_SND_DSP_MAXIMUM_CYCLES 以上の値が入力された場合は NN_SND_DSP_MAXIMUM_CYCLES が設定されます。 @param[in] cycles サイクル数 @return なし。 */ void SetMaximumDspCycles( s32 cycles ); /*! @brief サウンドに割り当てているDSP サイクル数を取得します。 @return サイクル数を返します。 */ s32 GetMaximumDspCycles( void ); /*! @brief 最後のオーディオフレーム作成でDSP が費やしたサイクル数を取得します。 @return DSP で消費したサイクル数を返します。 */ s32 GetDspCycles( void ); /*! :private @brief snd 処理を一時中断し、終了処理を行います。 */ void Sleep(); /*! :private @brief 一時中断した snd の処理を復元します。 */ void WakeUp(); /*! :private @brief 終了処理のための準備を行います。 */ void OrderToWaitForFinalize(); /*! @brief ヘッドホンの挿入状態を取得します。 @return 挿入されている場合は true を返します。 */ bool GetHeadphoneStatus( void ); /*! @brief ヘッドホンの挿入状態を更新し、取得します。 @return 挿入されている場合は true を返します。 */ bool UpdateHeadphoneStatus( void ); /*! @name 処理落ち検出 @{ */ /*! @brief 処理落ちしたサウンドフレームの数を取得します。 @return 処理落ちしたサウンドフレームの数を返します。 */ s32 GetDroppedSoundFrameCount(); /*! @brief 処理落ちしたサウンドフレームの数を初期化します。 */ void ClearDroppedSoundFrameCount(); /*! @} */ /*! @name DSP-ADPCM 関連 @{ */ /*! @brief 16bit PCM データを DSP-ADPCM フォーマットにエンコードします。 @param[in] pInput 入力バッファアドレス @param[out] pOutput 出力バッファアドレス（4 バイトアラインされている必要があります） @param[in] nSamples 入力サンプル数 @param[in] sampleRate サンプル周波数 @param[in] loopStart ループ開始サンプル位置（0 オリジン） @param[in] loopEnd ループ終了サンプル位置（0 オリジン） @param[out] pInfo ヘッダ構造体アドレス @return なし */ s32 EncodeAdpcmData(s16* pInput, u8* pOutput, s32 nSamples, s32 sampleRate, s32 loopStart, s32 loopEnd, DspsndAdpcmHeader* pInfo); /*! @brief DSP-ADPCM データをデコードします。 @param[in] pInput 入力バッファアドレス @param[out] pOutput 出力バッファアドレス @param[in] param ADPCM パラメータ @param[in] context ADPCM コンテキスト @param[in] nSamples 入力サンプル数 */ void DecodeAdpcmData(u8* pInput, s16* pOutput, AdpcmParam& param, AdpcmContext& context, s32 nSamples); /*! @brief エンコード時に必要な出力バッファのサイズを返します。 @param[in] nSamples 入力サンプル数 @return 出力バッファのサイズ */ s32 GetAdpcmOutputBufferSize(s32 nSamples); /*! @brief サンプル位置をニブル数に変換します。 @param[in] nPos サンプル位置 @return ニブル数 */ u32 ConvertAdpcmPos2Nib(u32 nPos); /*! @brief ニブル数をサンプル位置に変換します。 @param[in] nNib ニブル数 @return サンプル位置 */ u32 ConvertAdpcmNib2Pos(u32 nNib); /*! @} */ }}} // namespace nn::snd::CTR #endif // __cplusplus // 以下、C 用宣言 /*! @addtogroup nn_snd snd @{ */ /*! @brief 対応する C++ 関数 @ref nn::snd::CTR::Initialize を参照してください。 */ NN_EXTERN_C nnResult nnsndInitialize(); /*! @} */ #endif //NN_SND_API_H_