1 /*---------------------------------------------------------------------------* 2 Project: Horizon 3 File: mic_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: 29205 $ 14 *---------------------------------------------------------------------------*/ 15 16 #ifndef NN_MIC_CTR_MIC_API_H_ 17 #define NN_MIC_CTR_MIC_API_H_ 18 19 /*! @file 20 @brief MIC に関する API の宣言 21 */ 22 23 #include <nn/os.h> 24 #include <nn/mic/CTR/mic_Types.h> 25 26 #define NN_MIC_AMP_GAIN_MAX 119 // 10.5dB 27 #define NN_MIC_AMP_GAIN_MIN 0 // 70.0dB 28 #define NN_MIC_BUFFER_ALIGNMENT_SIZE 4096 29 #define NN_MIC_BUFFER_ALIGNMENT_ADDRESS 4096 30 31 namespace nn { 32 namespace mic { 33 namespace CTR { 34 35 /*! 36 @brief マイクアンプの最大ゲインを表す定数です。119 (70.0dB) です。 37 */ 38 const u8 AMP_GAIN_MAX = NN_MIC_AMP_GAIN_MAX; 39 40 /*! 41 @brief マイクアンプの最大ゲインを表す定数です。0 (10.5dB) です。 42 */ 43 const u8 AMP_GAIN_MIN = NN_MIC_AMP_GAIN_MIN; 44 45 /*! 46 @brief SetBuffer で設定するメモリ領域のアドレスのアライメントを表す定数です。4096 Byte です。 47 */ 48 const s32 BUFFER_ALIGNMENT_ADDRESS = NN_MIC_BUFFER_ALIGNMENT_ADDRESS; 49 50 /*! 51 @brief SetBuffer で設定するメモリ領域のサイズのアライメントを表す定数です。4096 Byte です。 52 */ 53 const s32 BUFFER_ALIGNMENT_SIZE = NN_MIC_BUFFER_ALIGNMENT_SIZE; 54 55 /*! 56 @brief MIC ライブラリの初期化を行い、マイクを使用可能な状態にします。 57 58 @return 処理の結果が返ってきます。<BR> 59 LEVEL_SUCCESS:SUMMARY_SUCCESS:MODULE_COMMON:DESCRIPTION_SUCCESS ・・・ 成功しました。<BR> 60 LEVEL_SUCCESS:SUMMARY_NOTHING_HAPPENED:MODULE_NN_MIC:DESCRIPTION_ALREADY_INITIALIZED ・・・ 既に初期化されています。<BR> 61 LEVEL_STATUS:SUMMARY_NOTHING_HAPPENED:MODULE_NN_MIC:DESCRIPTION_BUSY ・・・ 他のプロセスが使用中です。 62 */ 63 Result Initialize(); 64 65 /*! 66 @brief MIC ライブラリを終了します。 67 68 Finalize を呼ぶと、サンプリング中であればサンプリングを止め、 69 マイクアンプのゲインは@ref nn::mic::CTR::AMP_GAIN_DEFAULT_VALUEに設定して、マイクの電源をOFFにします。 70 71 @return 処理の結果が返ってきます。<BR> 72 LEVEL_SUCCESS:SUMMARY_SUCCESS:MODULE_COMMON:DESCRIPTION_SUCCESS ・・・ 成功しました。<BR> 73 LEVEL_SUCCESS:SUMMARY_NOTHING_HAPPENED:MODULE_NN_MIC:DESCRIPTION_NOT_INITIALIZED ・・・ 初期化されていません。 74 */ 75 Result Finalize(); 76 77 /*! 78 @brief サンプリング結果を格納するメモリ領域を設定します。 79 80 アプリケーションで取得したメモリを設定してください。 81 デバイスメモリは使用できません。 82 83 SetBuffer を複数回呼ぶことはできません。 84 再度SetBuffer を呼ぶ場合は一度@ref nn::mic::CTR::ResetBuffer を呼ぶ必要があります。 85 86 指定するメモリ領域のサイズは4096Byte アライメントしたサイズを指定してください。 87 指定するメモリ領域のアドレスは4096Byte アライメントしたアドレスを指定してください。 88 また指定したメモリ領域の終端部分を管理領域用に4Byte マイクライブラリが使用します。 89 終端4Byteを上書きするなどしないように気をつけてください。 90 実際にサンプリング結果が保存されるバッファのサイズは@ref nn::mic::CTR::GetSamplingBufferSize で取得したサイズです。 91 92 @param[in] address メモリブロックの先頭アドレスを指定します。 93 @param[in] size メモリ領域の大きさを指定します。 94 @return 処理の結果が返ってきます。<BR> 95 LEVEL_SUCCESS:SUMMARY_SUCCESS:MODULE_COMMON:DESCRIPTION_SUCCESS ・・・ 成功しました。<BR> 96 LEVEL_PERMANENT:SUMMARY_NOTHING_HAPPENED:MODULE_NN_MIC:DESCRIPTION_ALREADY_INITIALIZED ・・・ メモリ領域が既に設定されています。<BR> 97 LEVEL_USAGE:SUMMARY_NOTHING_HAPPENED:MODULE_NN_MIC:DESCRIPTION_MISALIGNED_SIZE ・・・ 指定したメモリ領域のサイズは4096Byte アライメントしたサイズになっていません。<BR> 98 LEVEL_USAGE:SUMMARY_NOTHING_HAPPENED:MODULE_NN_MIC:DESCRIPTION_MISALIGNED_ADDRESS ・・・ 指定したメモリ領域のアドレスが4096Byte アライメントしたアドレスになっていません。 99 */ 100 Result SetBuffer( void* address, size_t size ); 101 102 /*! 103 @brief @ref nn::mic::CTR::SetBuffer で設定したメモリ領域をマイクライブラリが使用しないように設定します。 104 105 ResetBufferを 実行するにはマイクのサンプリングを停止してから行ってください。 106 107 @return 処理の結果が返ってきます。<BR> 108 LEVEL_SUCCESS:SUMMARY_SUCCESS:MODULE_COMMON:DESCRIPTION_SUCCESS ・・・ 成功しました。<BR> 109 LEVEL_PERMANENT:SUMMARY_NOTHING_HAPPENED:MODULE_NN_MIC:DESCRIPTION_NOT_INITIALIZED ・・・ メモリ領域が設定されていません。<BR> 110 LEVEL_STATUS:SUMMARY_NOTHING_HAPPENED:MODULE_NN_MIC:DESCRIPTION_BUSY ・・・ サンプリング中です。 111 */ 112 Result ResetBuffer( ); 113 114 /*! 115 @brief @ref nn::mic::CTR::SetBuffer で設定したメモリ領域内で、サンプリング結果が保存されるサイズを返します 116 117 @ref nn::mic::CTR::SetBuffer で設定したメモリ領域の0 Byte目から GetSamplingBufferSize で取得したサイズ - 1 Byte目までに 118 サンプリング結果が保存されます。 119 120 @param[out] pSize サンプリング結果を保存するサイズを返します。単位はByteです。 121 @return 処理の結果が返ってきます。<BR> 122 LEVEL_SUCCESS:SUMMARY_SUCCESS:MODULE_COMMON:DESCRIPTION_SUCCESS ・・・ 成功しました。<BR> 123 LEVEL_PERMANENT:SUMMARY_NOTHING_HAPPENED:MODULE_NN_MIC:DESCRIPTION_NOT_INITIALIZED ・・・ メモリ領域が設定されていません。 124 */ 125 Result GetSamplingBufferSize(size_t* pSize); 126 127 /*! 128 @brief マイクの自動サンプリングを開始します。 129 130 既にマイクの自動サンプリングが開始されている場合は停止して、新たに開始します。 131 132 @param[in] type サンプリング種別を指定します。 133 @param[in] rate サンプリング周波数を指定します。 134 @param[in] offset サンプリング結果を格納し始めるメモリ領域の先頭から位置。単位はByteで必ず2の倍数の位置を指定してください。 135 @param[in] size サンプリング結果を格納するメモリ領域上のサイズ。@ref nn::mic::CTR::GetSamplingBufferSize で取得したサイズ以下を指定してください。<BR> 136 また必ず2の倍数のサイズを指定してください。 137 @param[in] loop size 分サンプリングした後にメモリ領域をループさせるか指定するフラグ。<BR> 138 trueであればループして連続してサンプリングします。<BR> 139 size 分サンプリングした後、offset の位置から引き続きサンプリングが行われます。<BR> 140 falseであればsize 分サンプリングした後に自動的に止まります。 141 @return 処理の結果が返ってきます。<BR> 142 LEVEL_SUCCESS:SUMMARY_SUCCESS:MODULE_COMMON:DESCRIPTION_SUCCESS ・・・ 成功しました。<BR> 143 LEVEL_PERMANENT:SUMMARY_NOTHING_HAPPENED:MODULE_NN_MIC:DESCRIPTION_NOT_INITIALIZED ・・・ メモリ領域が確保されていません。<BR> 144 LEVEL_USAGE:SUMMARY_NOTHING_HAPPENED:MODULE_NN_MIC:DESCRIPTION_MISALIGNED_SIZE ・・・ 指定したoffset またはsize が2の倍数のサイズになっていません。<BR> 145 LEVEL_USAGE:SUMMARY_NOTHING_HAPPENED:MODULE_NN_MIC:DESCRIPTION_OUT_OF_MEMORY ・・・ 指定したoffset + size が確保したメモリ領域よりも大きいです。 146 */ 147 Result StartSampling( SamplingType type, SamplingRate rate, s32 offset, size_t size, bool loop ); 148 149 /*! 150 @brief マイクの自動サンプリングを停止します 151 152 @return 処理の結果が返ってきます。<BR> 153 LEVEL_SUCCESS:SUMMARY_SUCCESS:MODULE_COMMON:DESCRIPTION_SUCCESS ・・・ 成功しました。 154 */ 155 Result StopSampling( void ); 156 157 /*! 158 @brief マイクの自動サンプリングにおけるサンプリングレートを変更します。 159 160 既にマイクの自動サンプリングが開始されている場合は停止して、新たに開始します。 161 またマイクが停止している場合は、新たに開始します。 162 163 @ref StartSampling で設定したoffset とsize を使用してサンプリングを行います。 164 既にサンプリングが行われている場合は、現在書き込んでいる位置からサンプリングが再開します。 165 166 @param[in] rate サンプリング周波数を指定します。 167 @return 処理の結果が返ってきます。<BR> 168 LEVEL_SUCCESS:SUMMARY_SUCCESS:MODULE_COMMON:DESCRIPTION_SUCCESS ・・・ 成功しました。 169 */ 170 Result AdjustSampling( SamplingRate rate ); 171 172 /*! 173 @brief マイクのサンプリングが行われているかを判定します。 174 175 @param[out] pSampling サンプリングが行われていれば true, そうでなければ false を返します。 176 @return 処理の結果が返ってきます。<BR> 177 LEVEL_SUCCESS:SUMMARY_SUCCESS:MODULE_COMMON:DESCRIPTION_SUCCESS ・・・ 成功しました。 178 */ 179 Result IsSampling( bool* pSampling ); 180 181 /*! 182 @brief 最新のマイクサンプリング結果の格納されたアドレスを取得します。 183 184 @param[out] pAddress 最新のマイクサンプリング結果の格納されたアドレスです。 185 @return 処理の結果が返ってきます。<BR> 186 LEVEL_SUCCESS:SUMMARY_SUCCESS:MODULE_COMMON:DESCRIPTION_SUCCESS ・・・ 成功しました。 187 */ 188 Result GetLastSamplingAddress( uptr* pAddress ); 189 190 /*! 191 @brief マイクのバッファの飽和を検知するための手動リセットイベントを取得します。 192 193 @ref StartSampling で指定したsize のデータを書き込むと@ref nn::os::Event がシグナル状態になります。<BR> 194 @ref StartSampling でloop をtrue に設定した場合は、またoffset 位置からサンプリングを行い、 195 size 分のデータを書き込んだ状態で再度@ref nn::os::Event がシグナル状態になります。<BR> 196 197 手動リセットイベントですので、イベントがシグナル状態になっていて、 198 かつ再度イベントを取得したい場合は、@ref nn::os::Event::ClearSignal を呼ぶ必要があります。 199 200 @param[out] pEvent バッファの飽和時に起こされる手動リセットイベントです。 201 @return 処理の結果が返ってきます。<BR> 202 LEVEL_SUCCESS:SUMMARY_SUCCESS:MODULE_COMMON:DESCRIPTION_SUCCESS ・・・ 成功しました。 203 */ 204 Result GetBufferFullEvent( nn::os::Event* pEvent ); 205 206 /*! 207 @brief マイクアンプのゲインを設定します。 208 209 マイクアンプのゲインの初期値は 210 @ref nn::mic::CTR::AMP_GAIN_DEFAULT_VALUE に設定されています。 211 212 @param[in] gain マイクアンプのゲインを設定します。0 ～ 119 (10.5dB ～ 70.0dB)の範囲で指定します。 213 @return 処理の結果が返ってきます。<BR> 214 LEVEL_SUCCESS:SUMMARY_SUCCESS:MODULE_COMMON:DESCRIPTION_SUCCESS ・・・ 成功しました。 215 */ 216 Result SetAmpGain( u8 gain ); 217 218 /*! 219 @brief マイクアンプのゲインを取得します。 220 221 @param[out] pGain マイクアンプのゲインを取得します。0 ～ 119 (10.5dB ～ 70.0dB)の範囲で取得します。 222 @return 処理の結果が返ってきます。<BR> 223 LEVEL_SUCCESS:SUMMARY_SUCCESS:MODULE_COMMON:DESCRIPTION_SUCCESS ・・・ 成功しました。 224 */ 225 Result GetAmpGain( u8* pGain ); 226 227 /*! 228 @brief マイク電源のON/OFF設定を設定します。 229 230 マイク電源ON時や、スリープから復帰した直後は１秒間マイク入力が安定しないため 231 強制的に無音にしています。 232 233 サンプリング種別ごとの無音値は@ref nn::mic::CTR::SAMPLING_TYPE_8BIT_SILENT_DATA 、 234 @ref nn::mic::CTR::SAMPLING_TYPE_16BIT_SILENT_DATA 、 235 @ref nn::mic::CTR::SAMPLING_TYPE_SIGNED_8BIT_SILENT_DATA 、 236 @ref nn::mic::CTR::SAMPLING_TYPE_SIGNED_16BIT を参照してください。 237 238 @param[in] enable trueであればマイク電源をONにします。falseであればマイク電源をOFFにします。 239 @return 処理の結果が返ってきます。<BR> 240 LEVEL_SUCCESS:SUMMARY_SUCCESS:MODULE_COMMON:DESCRIPTION_SUCCESS ・・・ 成功しました。 241 */ 242 Result SetAmp( bool enable ); 243 244 /*! 245 @brief マイク電源のON/OFF設定を取得します。 246 247 @param[out] pEnable マイク電源がONであればtrueが返ります。マイク電源がOFFであればfalseが返ります。 248 @return 処理の結果が返ってきます。<BR> 249 LEVEL_SUCCESS:SUMMARY_SUCCESS:MODULE_COMMON:DESCRIPTION_SUCCESS ・・・ 成功しました。 250 */ 251 Result GetAmp( bool* pEnable ); 252 253 /*! 254 @brief ゲインとサンプリング種別に対応した、マイク入力あり判定禁止領域の上限と下限の値を取得します。 255 この上限と下限の間の値を、マイク入力ありと判定することは避けてください。 256 257 @param[out] upper 判定禁止領域の上限値です。 258 @param[out] lower 判定禁止領域の下限値です。 259 @param[in] type サンプリング種別を指定します。 260 @param[in] gain マイクアンプのゲインを設定します。0 ～ 119 (10.5dB ～ 70.0dB)の範囲で指定します。 261 @return 領域が正しく取得できれば true, そうでなければ false を返します。 262 */ 263 bool GetForbiddenArea( s32* upper, s32* lower, SamplingType type, u8 gain ); 264 265 /*! 266 @brief マイク入力データへ適用するローパスフィルタの設定を行います。 267 268 ローパスフィルタのカットオフ周波数は、マイクサンプリングレートの45パーセントです。<BR> 269 SAMPLING_RATE_32730の場合はオリジナルデータがローパスフィルタ適用済みであるため 270 本関数でローパスフィルタを適用したとしても効果はありません。 271 272 @param[in] enable ローパスフィルタを有効にする場合trueを指定します。(デフォルトはfalseです) 273 @return 処理の結果が返ってきます。<BR> 274 LEVEL_SUCCESS:SUMMARY_SUCCESS:MODULE_COMMON:DESCRIPTION_SUCCESS ・・・ 成功しました。 275 */ 276 Result SetLowPassFilter( bool enable ); 277 278 /*! 279 @brief マイクデータをクランプ処理するかどうかの設定を行います。 280 281 マイクデータは全範囲の入力が得られることが理想ですが、実際には個体差があります。<BR> 282 どの個体でも入力されることが保証される範囲として「マイク入力保証範囲」が定義されています。<BR> 283 284 本関数を引数trueで実行した場合、「マイク入力保証範囲」で値がクランプ処理されます。<BR> 285 マイクの個体差に起因する問題を回避するため通常はクランプありで使用してください。<BR> 286 287 より広い入力範囲を必要とする場合はクランプ処理を無効にしてください。<BR> 288 その場合、個体によっては「マイク入力保証範囲」より外の値が取得できない可能性が 289 あることに注意してください。 290 291 サンプリング種別ごとのマイク入力保証範囲は以下を参照してください。<BR> 292 @ref nn::mic::CTR::TYPE_8BIT_GUARANTEED_INPUT_MIN、<BR> 293 @ref nn::mic::CTR::TYPE_8BIT_GUARANTEED_INPUT_MAX、<BR> 294 @ref nn::mic::CTR::TYPE_16BIT_GUARANTEED_INPUT_MIN、<BR> 295 @ref nn::mic::CTR::TYPE_16BIT_GUARANTEED_INPUT_MAX、<BR> 296 @ref nn::mic::CTR::TYPE_SIGNED_8BIT_GUARANTEED_INPUT_MIN、<BR> 297 @ref nn::mic::CTR::TYPE_SIGNED_8BIT_GUARANTEED_INPUT_MAX、<BR> 298 @ref nn::mic::CTR::TYPE_SIGNED_16BIT_GUARANTEED_INPUT_MIN、<BR> 299 @ref nn::mic::CTR::TYPE_SIGNED_16BIT_GUARANTEED_INPUT_MAX、<BR> 300 301 本関数実行時に既にサンプリングが行われている場合、<BR> 302 現在書き込んでいる位置以降に設定が反映されます。<BR> 303 304 @param[in] enable trueであればクランプ処理を有効にします。（デフォルトはtrue） 305 @return 処理の結果が返ってきます。<BR> 306 LEVEL_SUCCESS:SUMMARY_SUCCESS:MODULE_COMMON:DESCRIPTION_SUCCESS ・・・ 成功しました。 307 */ 308 Result SetClamp( bool enable ); 309 310 /*! 311 @brief マイクデータのクランプ処理設定を取得します。 312 313 @param[out] pEnable クランプ処理が有効であればtrueが返ります。 314 @return 処理の結果が返ってきます。<BR> 315 LEVEL_SUCCESS:SUMMARY_SUCCESS:MODULE_COMMON:DESCRIPTION_SUCCESS ・・・ 成功しました。 316 */ 317 Result GetClamp( bool* pEnable ); 318 319 } 320 } 321 } 322 323 #endif // ifndef NN_MIC_CTR_MIC_API_H_ 324