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