/*---------------------------------------------------------------------------* 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: 32540 $ *---------------------------------------------------------------------------*/ #ifndef NN_SND_API_H_ #define NN_SND_API_H_ #include #include #include #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 サウンドスレッドを作成します。 */ nn::Result StartSoundThread( const ThreadParameter* mainThreadParam, void (*mainThreadCallback)(uptr), uptr mainThreadArg, const ThreadParameter* userThreadParam, void (*userThreadCallback)(uptr), uptr userThreadArg, s32 coreNo ); /*! :private @brief StartSoundThread で作成したサウンドスレッドを終了します。 */ void FinalizeSoundThread(); /*! :private @brief StartUserSoundThread で作成したユーザーサウンドスレッドを終了します。 */ inline void FinalizeUserSoundThread() {} /*! :private @brief サウンドフレームの処理負荷を有効 / 無効にします。 デフォルトは無効です。 @param[in] enable true なら有効、false なら無効 */ void EnableSoundThreadTickCounter(bool enable); /*! :private @brief StartSoundThread で作成したサウンドスレッドの、1 サウンドフレームあたりの処理負荷を取得します。 コールバック内で呼び出した場合は、ひとつ前のサウンドフレームの処理負荷が得られます。 */ nn::os::Tick GetSoundThreadTick(); /*! :private @brief 自動 UpdateCommand の設定を行います。 @param[in] autoUpdateCommand true なら自動アップデート */ void SetAutoUpdateCommand(bool autoUpdateCommand); // TORIAEZU: CTR-SDK 0.14 を NintendoWare 1.1.1 と組み合わせて使用するための暫定措置 inline void EnableAuxBusProcessingOnCore1(bool /*enable*/) {} inline void EnableSoundThreadCallbackOnCore1(bool /*enable*/) {} inline void EnableVoiceDropCallbackOnCore1(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 ); /*! :private @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(); /*! :private @brief DSP で処理を行った結果を受信し、受信に要した処理時間を取得します。 サウンドフレームイベントが発生するまで待機します。 シグナルが通知された後、DSP からのデータを受信します。 @param[out] pTick 内部の Wait 以外の処理に要したサイクル数 @return なし。 */ void WaitForDspSync(nn::os::Tick* pTick); /*! @brief 設定されたパラメータをDSP に反映します。 @return なし。 */ void SendParameterToDsp(); /*! :private @brief 必要であれば内部で UpdateCommand を実行し、設定されたパラメータを DSP に反映します。 @param[in] autoUpdateCommand true なら内部で UpdateCommand を実行します。 */ void SendParameterToDsp(bool autoUpdateCommand); /*! :private @brief 発行したコマンドを DSP へ送信します。 */ void UpdateCommand(); /*! @} */ /*! @brief サンプルの長さを取得します。 @param[in] size サイズ（バイト単位） @param[in] format 形式 @param[in] channelCount チャンネル数 @return サンプルの長さを返します。 */ s32 GetSampleLength( s32 size, SampleFormat format, s32 channelCount ) ; /*! @name マスター操作、Aux バス操作 @{ */ /*! @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); /*! @} */ /*! @name 3D サラウンド @{ */ /*! @brief サウンド出力モードを設定します。 @param[in] mode サウンド出力モード @return 設定に成功すれば true を、失敗すれば false を返します。 */ bool SetSoundOutputMode(OutputMode mode); /*! @brief サウンド出力モードを取得します。 @return サウンド出力モード */ OutputMode GetSoundOutputMode(); /*! @brief クリッピングモードを設定します。 @param[in] mode モード @return 設定に成功すれば true を、失敗すれば false を返します。 */ bool SetClippingMode(ClippingMode mode); /*! @brief クリッピングモードを取得します。 @return モード */ ClippingMode GetClippingMode(); /*! :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(); /*! @brief 最後のオーディオフレーム作成でDSP が費やしたサイクル数を取得します。 @return DSP で消費したサイクル数を返します。 */ s32 GetDspCycles(); /*! :private @brief snd 処理を一時中断し、終了処理を行います。 */ void Sleep(); /*! :private @brief 一時中断した snd の処理を復元します。 */ void WakeUp(); /*! :private @brief 終了処理のための準備を行います。 */ void OrderToWaitForFinalize(); /*! @brief ヘッドホンの挿入状態を取得します。 @return 挿入されている場合は true を返します。 */ bool GetHeadphoneStatus(); /*! @brief ヘッドホンの挿入状態を更新し、取得します。 @return 挿入されている場合は true を返します。 */ bool UpdateHeadphoneStatus(); /*! :private @brief 蓋閉じ時に強制的にヘッドフォン出力にするかどうかを設定します。 @param[in] forceout true なら強制ヘッドフォン出力とします。 @return 処理の結果が返ります。 */ inline Result SetHeadphoneOutOnShellClose(bool forceout) { return dsp::ForceHeadphoneOut(forceout); } /*! @name DSP 最終出力取得 @{ */ /*! @brief Mix バスデータを指定のバッファにコピーします。 @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 処理落ち検出 @{ */ /*! @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); /*! @} */ /*! @name エフェクト @{ */ /*! @brief ディレイエフェクトを設定します。 AUX から出力されるデータを加工するには、 自前の加工処理関数を @ref RegisterAuxCallback で設定するほか、 本関数を用いて、ディレイやリバーブのエフェクトをかけることができます。 ディレイ (@ref FxDelay) やリバーブ (@ref FxReverb) は、 各バスにどちらか 1 つしか設定できないことに注意してください。 1 つ以上設定すると、後から設定したものが有効になります。 もともと設定されていたエフェクトは解除されます。 @ref ClearEffect を呼び出したり、 上記のようにもともと設定されていて解除された場合は、 @ref FxDelay::ReleaseWorkBuffer や @ref FxReverb::ReleaseWorkBuffer で、 当該エフェクトで使用していたメモリを解放することができます。 本関数を呼び出す前に、@ref FxDelay クラスの、 @ref FxDelay::SetParam, @ref FxDelay::GetRequiredMemSize, @ref FxDelay::AssignWorkBuffer を呼び出し、 ディレイエフェクトの準備を済ませておく必要があります。 @param[in] busId バスの ID @param[in] fx 設定するディレイエフェクト @return 設定に成功したら true を返します。 fx が NULL の場合、設定に失敗し false を返します。 @see ClearEffect @see RegisterAuxCallback @see FxDelay クラス @see FxReverb クラス @date 2010/10/20 初版 */ bool SetEffect(AuxBusId busId, FxDelay* fx); /*! @brief リバーブエフェクトを設定します。 AUX から出力されるデータを加工するには、 自前の加工処理関数を @ref RegisterAuxCallback で設定するほか、 本関数を用いて、ディレイやリバーブのエフェクトをかけることができます。 ディレイ (@ref FxDelay) やリバーブ (@ref FxReverb) は、 各バスにどちらか 1 つしか設定できないことに注意してください。 1 つ以上設定すると、後から設定したものが有効になります。 もともと設定されていたエフェクトは解除されます。 @ref ClearEffect を呼び出したり、 上記のようにもともと設定されていて解除された場合は、 @ref FxDelay::ReleaseWorkBuffer や @ref FxReverb::ReleaseWorkBuffer で、 当該エフェクトで使用していたメモリを解放することができます。 本関数を呼び出す前に、@ref FxReverb クラスの、 @ref FxReverb::SetParam, @ref FxReverb::GetRequiredMemSize, @ref FxReverb::AssignWorkBuffer を呼び出し、 ディレイエフェクトの準備を済ませておく必要があります。 @param[in] busId バスの ID @param[in] fx 設定するリバーブエフェクト @return 設定に成功したら true を返します。 fx が NULL の場合、設定に失敗し false を返します。 @see ClearEffect @see RegisterAuxCallback @see FxReverb クラス @see FxDelay クラス @date 2010/10/20 初版 */ bool SetEffect(AuxBusId busId, FxReverb* fx); /*! @brief エフェクトの設定を解除します。 @ref SetEffect 関数で設定したエフェクトを解除します。 @ref RegisterAuxCallback で設定したコールバックは解除されません (これは @ref ClearAuxCallback で解除することができます)。 @param[in] busId バスの ID @see SetEffect @see RegisterAuxCallback @see ClearAuxCallback @date 2010/10/20 初版 */ void ClearEffect(AuxBusId busId); /*! @} */ void UseOldSystem(bool enable = true); }}} // 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_