/*---------------------------------------------------------------------------* Project: Horizon File: mic_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: 32939 $ *---------------------------------------------------------------------------*/ #ifndef NN_MIC_CTR_MIC_API_H_ #define NN_MIC_CTR_MIC_API_H_ /*! @file @brief MIC に関する API の宣言 */ #include #include #define NN_MIC_AMP_GAIN_MAX 119 // 10.5dB #define NN_MIC_AMP_GAIN_MIN 0 // 70.0dB #define NN_MIC_BUFFER_ALIGNMENT_SIZE 4096 #define NN_MIC_BUFFER_ALIGNMENT_ADDRESS 4096 namespace nn { namespace mic { namespace CTR { /*! @brief マイクアンプの最大ゲインを表す定数です。119 (70.0dB) です。 */ const u8 AMP_GAIN_MAX = NN_MIC_AMP_GAIN_MAX; /*! @brief マイクアンプの最大ゲインを表す定数です。0 (10.5dB) です。 */ const u8 AMP_GAIN_MIN = NN_MIC_AMP_GAIN_MIN; /*! @brief SetBuffer で設定するメモリ領域のアドレスのアライメントを表す定数です。4096 Byte です。 */ const s32 BUFFER_ALIGNMENT_ADDRESS = NN_MIC_BUFFER_ALIGNMENT_ADDRESS; /*! @brief SetBuffer で設定するメモリ領域のサイズのアライメントを表す定数です。4096 Byte です。 */ const s32 BUFFER_ALIGNMENT_SIZE = NN_MIC_BUFFER_ALIGNMENT_SIZE; /*! @brief MIC ライブラリの初期化を行い、マイクを使用可能な状態にします。 @return 処理の結果を返します。 @retval 成功 成功しました。 @retval ResultAlreadyInitialized 既に初期化されています。 @retval ResultUsingOtherProcess 他のプロセスが使用中でありマイクを使用できません。@n アプレットではない通常のアプリケーションにおいてはこのエラーが返ることはありません。 */ Result Initialize(); /*! @brief MIC ライブラリを終了します。 Finalize を呼ぶと、サンプリング中であればサンプリングを止め、 マイクアンプのゲインは@ref nn::mic::CTR::AMP_GAIN_DEFAULT_VALUEに設定して、マイクの電源をOFFにします。 @return 処理の結果を返します。 @retval 成功 成功しました。 @retval ResultNotInitialized 初期化されていません。 */ Result Finalize(); /*! @brief サンプリング結果を格納するメモリ領域を設定します。 アプリケーションで取得したメモリを設定してください。 デバイスメモリは使用できません。 SetBuffer を複数回呼ぶことはできません。 再度SetBuffer を呼ぶ場合は一度@ref nn::mic::CTR::ResetBuffer を呼ぶ必要があります。 指定するメモリ領域のサイズは4096Byte アライメントしたサイズを指定してください。 指定するメモリ領域のアドレスは4096Byte アライメントしたアドレスを指定してください。 また指定したメモリ領域の終端部分を管理領域用に4Byte マイクライブラリが使用します。 終端4Byteを上書きするなどしないように気をつけてください。 実際にサンプリング結果が保存されるバッファのサイズは@ref nn::mic::CTR::GetSamplingBufferSize で取得したサイズです。 @param[in] address メモリブロックの先頭アドレスを指定します。 @param[in] size メモリ領域の大きさを指定します。 @return 処理の結果を返します。 @retval 成功 成功しました。 @retval ResultAlreadyInitialized メモリ領域が既に設定されています。 @retval ResultMisalignedSize 指定したメモリ領域のサイズは4096Byte アライメントしたサイズになっていません。 @retval ResultMisalignedAddress 指定したメモリ領域のアドレスが4096Byte アライメントしたアドレスになっていません。 @retval ResultInvalidHandle 指定したメモリ領域が不正です。 @retval ResultInvalidSize 指定したサイズが0であり、不正です。 */ Result SetBuffer( void* address, size_t size ); /*! @brief @ref nn::mic::CTR::SetBuffer で設定したメモリ領域をマイクライブラリが使用しないように設定します。 ResetBufferを 実行するにはマイクのサンプリングを停止してから行ってください。 @return 処理の結果を返します。 @retval 成功 成功しました。 @retval ResultNotInitialized メモリ領域が設定されていません。 @retval ResultBusy サンプリング中です。 */ Result ResetBuffer( ); /*! @brief @ref nn::mic::CTR::SetBuffer で設定したメモリ領域内で、サンプリング結果が保存されるサイズを返します @ref nn::mic::CTR::SetBuffer で設定したメモリ領域の0 Byte目から GetSamplingBufferSize で取得したサイズ - 1 Byte目までに サンプリング結果が保存されます。 @param[out] pSize サンプリング結果を保存するサイズを返します。単位はByteです。 @return 処理の結果を返します。 @retval 成功 成功しました。 @retval ResultNotInitialized メモリ領域が設定されていません。 */ Result GetSamplingBufferSize(size_t* pSize); /*! @brief マイクの自動サンプリングを開始します。 既にマイクの自動サンプリングが開始されている場合は停止して、新たに開始します。 @param[in] type サンプリング種別を指定します。 @param[in] rate サンプリング周波数を指定します。 @param[in] offset サンプリング結果を格納し始めるメモリ領域の先頭から位置。単位はByteで必ず2の倍数の位置を指定してください。 @param[in] size サンプリング結果を格納するメモリ領域上のサイズ。@ref nn::mic::CTR::GetSamplingBufferSize で取得したサイズ以下を指定してください。
また必ず2の倍数のサイズを指定してください。 @param[in] loop size 分サンプリングした後にメモリ領域をループさせるか指定するフラグ。
trueであればループして連続してサンプリングします。
size 分サンプリングした後、offset の位置から引き続きサンプリングが行われます。
falseであればsize 分サンプリングした後に自動的に止まります。 @return 処理の結果を返します。 @retval 成功 成功しました。 @retval ResultNotInitialized メモリ領域が確保されていません。 @retval ResultMisalignedSize 指定したoffset またはsize が2の倍数のサイズになっていません。 @retval ResultOutOfMemory 指定したoffset + size が確保したメモリ領域よりも大きいです。 @retval ResultShellClose ふたが閉じられているので、サンプリングを開始できません。 */ Result StartSampling( SamplingType type, SamplingRate rate, s32 offset, size_t size, bool loop ); /*! @brief マイクの自動サンプリングを停止します @return 処理の結果を返します。 @retval 成功 成功しました。 @retval ResultShellClose ふたが閉じられているので、サンプリングを停止できません。@n ふたが閉じられている時は、自動的にサンプリングが停止していますが、@n ふたが開くと、サンプリングが再開します。@n ふたが開いた後もサンプリングを停止したい場合は、ふたが開いた後に本関数を呼び出してください。 */ Result StopSampling( void ); /*! @brief マイクの自動サンプリングにおけるサンプリングレートを変更します。 既にマイクの自動サンプリングが開始されている場合は停止して、新たに開始します。 またマイクが停止している場合は、新たに開始します。 @ref StartSampling で設定したoffset とsize を使用してサンプリングを行います。 既にサンプリングが行われている場合は、現在書き込んでいる位置からサンプリングが再開します。 @param[in] rate サンプリング周波数を指定します。 @return 処理の結果を返します。 @retval 成功 成功しました。 @retval ResultShellClose ふたが閉じられているので、サンプリングを開始できません。 */ Result AdjustSampling( SamplingRate rate ); /*! @brief マイクのサンプリングが行われているかを判定します。 @param[out] pSampling サンプリングが行われていれば true, そうでなければ false を返します。 @return 処理の結果を返します。 @retval 成功 成功しました。 */ Result IsSampling( bool* pSampling ); /*! @brief 最新のマイクサンプリング結果の格納されたアドレスを取得します。 @param[out] pAddress 最新のマイクサンプリング結果の格納されたアドレスです。 @return 処理の結果を返します。 @retval 成功 成功しました。 */ Result GetLastSamplingAddress( uptr* pAddress ); /*! @brief マイクのバッファの飽和を検知するための手動リセットイベントを取得します。 @ref StartSampling で指定したsize のデータを書き込むと@ref nn::os::Event がシグナル状態になります。
@ref StartSampling でloop をtrue に設定した場合は、またoffset 位置からサンプリングを行い、 size 分のデータを書き込んだ状態で再度@ref nn::os::Event がシグナル状態になります。
手動リセットイベントですので、イベントがシグナル状態になっていて、 かつ再度イベントを取得したい場合は、@ref nn::os::Event::ClearSignal を呼ぶ必要があります。 @param[out] pEvent バッファの飽和時に起こされる手動リセットイベントです。 @return 処理の結果を返します。 @retval 成功 成功しました。 */ Result GetBufferFullEvent( nn::os::Event* pEvent ); /*! @brief マイクアンプのゲインを設定します。 マイクアンプのゲインの初期値は @ref nn::mic::CTR::AMP_GAIN_DEFAULT_VALUE に設定されています。 @param[in] gain マイクアンプのゲインを設定します。0 ～ 119 (10.5dB ～ 70.0dB)の範囲で指定します。 @return 処理の結果を返します。 @retval 成功 成功しました。 */ Result SetAmpGain( u8 gain ); /*! @brief マイクアンプのゲインを取得します。 @param[out] pGain マイクアンプのゲインを取得します。0 ～ 119 (10.5dB ～ 70.0dB)の範囲で取得します。 @return 処理の結果を返します。 @retval 成功 成功しました。 */ Result GetAmpGain( u8* pGain ); /*! @brief マイク電源のON/OFF設定を設定します。 マイク電源ON時や、スリープから復帰した直後は１秒間マイク入力が安定しないため 強制的に無音にしています。 サンプリング種別ごとの無音値は@ref nn::mic::CTR::SAMPLING_TYPE_8BIT_SILENT_DATA 、 @ref nn::mic::CTR::SAMPLING_TYPE_16BIT_SILENT_DATA 、 @ref nn::mic::CTR::SAMPLING_TYPE_SIGNED_8BIT_SILENT_DATA 、 @ref nn::mic::CTR::SAMPLING_TYPE_SIGNED_16BIT を参照してください。 @param[in] enable trueであればマイク電源をONにします。falseであればマイク電源をOFFにします。 @return 処理の結果を返します。 @retval 成功 成功しました。 */ Result SetAmp( bool enable ); /*! @brief マイク電源のON/OFF設定を取得します。 @param[out] pEnable マイク電源がONであればtrueが返ります。マイク電源がOFFであればfalseが返ります。 @return 処理の結果を返します。 @retval 成功 成功しました。 */ Result GetAmp( bool* pEnable ); /*! @brief ゲインとサンプリング種別に対応した、マイク入力あり判定禁止領域の上限と下限の値を取得します。 この上限と下限の間の値を、マイク入力ありと判定することは避けてください。 @param[out] upper 判定禁止領域の上限値です。 @param[out] lower 判定禁止領域の下限値です。 @param[in] type サンプリング種別を指定します。 @param[in] gain マイクアンプのゲインを設定します。0 ～ 119 (10.5dB ～ 70.0dB)の範囲で指定します。 @return 処理の結果を返します。 @retval true 領域を正しく取得できました。 @retval false 領域が正しく取得できませんでした。入力値が範囲内であるか確認して下さい。 */ bool GetForbiddenArea( s32* upper, s32* lower, SamplingType type, u8 gain ); /*! @brief マイク入力データへ適用するローパスフィルタの設定を行います。 ローパスフィルタのカットオフ周波数は、マイクサンプリングレートの45パーセントです。
SAMPLING_RATE_32730の場合はオリジナルデータがローパスフィルタ適用済みであるため 本関数でローパスフィルタを適用したとしても効果はありません。 @param[in] enable ローパスフィルタを有効にする場合trueを指定します。(デフォルトはfalseです) @return 処理の結果を返します。 @retval 成功 成功しました。 */ Result SetLowPassFilter( bool enable ); /*! @brief マイクデータをクランプ処理するかどうかの設定を行います。 マイクデータは全範囲の入力が得られることが理想ですが、実際には個体差があります。
どの個体でも入力されることが保証される範囲として「マイク入力保証範囲」が定義されています。
本関数を引数trueで実行した場合、「マイク入力保証範囲」で値がクランプ処理されます。
マイクの個体差に起因する問題を回避するため通常はクランプありで使用してください。
より広い入力範囲を必要とする場合はクランプ処理を無効にしてください。
その場合、個体によっては「マイク入力保証範囲」より外の値が取得できない可能性が あることに注意してください。 サンプリング種別ごとのマイク入力保証範囲は以下を参照してください。
@ref nn::mic::CTR::TYPE_8BIT_GUARANTEED_INPUT_MIN、
@ref nn::mic::CTR::TYPE_8BIT_GUARANTEED_INPUT_MAX、
@ref nn::mic::CTR::TYPE_16BIT_GUARANTEED_INPUT_MIN、
@ref nn::mic::CTR::TYPE_16BIT_GUARANTEED_INPUT_MAX、
@ref nn::mic::CTR::TYPE_SIGNED_8BIT_GUARANTEED_INPUT_MIN、
@ref nn::mic::CTR::TYPE_SIGNED_8BIT_GUARANTEED_INPUT_MAX、
@ref nn::mic::CTR::TYPE_SIGNED_16BIT_GUARANTEED_INPUT_MIN、
@ref nn::mic::CTR::TYPE_SIGNED_16BIT_GUARANTEED_INPUT_MAX、
本関数実行時に既にサンプリングが行われている場合、
現在書き込んでいる位置以降に設定が反映されます。
@param[in] enable trueであればクランプ処理を有効にします。（デフォルトはtrue） @return 処理の結果を返します。 @retval 成功 成功しました。 */ Result SetClamp( bool enable ); /*! @brief マイクデータのクランプ処理設定を取得します。 @param[out] pEnable クランプ処理が有効であればtrueが返ります。 @return 処理の結果を返します。 @retval 成功 成功しました。 */ Result GetClamp( bool* pEnable ); } } } #endif // ifndef NN_MIC_CTR_MIC_API_H_