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: 33219 $ 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 ResultSuccess 成功しました。 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 ResultSuccess 成功しました。 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 ResultSuccess 成功しました。 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 ResultSuccess 成功しました。 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 ResultSuccess 成功しました。 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 ResultSuccess 成功しました。 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 ResultSuccess 成功しました。 159 */ 160 Result StopSampling( void ); 161 162 /*! 163 @brief マイクの自動サンプリングにおけるサンプリングレートを変更します。 164 165 既にマイクの自動サンプリングが開始されている場合は停止して、新たに開始します。 166 またマイクが停止している場合は、新たに開始します。 167 168 @ref StartSampling で設定したoffset とsize を使用してサンプリングを行います。 169 既にサンプリングが行われている場合は、現在書き込んでいる位置からサンプリングが再開します。 170 171 @param[in] rate サンプリング周波数を指定します。 172 173 @return 処理の結果を返します。 174 @retval ResultSuccess 成功しました。 175 @retval ResultShellClose ふたが閉じられているので、サンプリングを開始できません。 176 */ 177 Result AdjustSampling( SamplingRate rate ); 178 179 /*! 180 @brief マイクのサンプリングが行われているかを判定します。 181 182 @param[out] pSampling サンプリングが行われていれば true, そうでなければ false を返します。 183 184 @return 処理の結果を返します。 185 @retval ResultSuccess 成功しました。 186 */ 187 Result IsSampling( bool* pSampling ); 188 189 /*! 190 @brief 最新のマイクサンプリング結果の格納されたアドレスを取得します。 191 192 @param[out] pAddress 最新のマイクサンプリング結果の格納されたアドレスです。 193 194 @return 処理の結果を返します。 195 @retval ResultSuccess 成功しました。 196 */ 197 Result GetLastSamplingAddress( uptr* pAddress ); 198 199 /*! 200 @brief マイクのバッファの飽和を検知するための手動リセットイベントを取得します。 201 202 @ref StartSampling で指定したsize のデータを書き込むと@ref nn::os::Event がシグナル状態になります。<BR> 203 @ref StartSampling でloop をtrue に設定した場合は、またoffset 位置からサンプリングを行い、 204 size 分のデータを書き込んだ状態で再度@ref nn::os::Event がシグナル状態になります。<BR> 205 206 手動リセットイベントですので、イベントがシグナル状態になっていて、 207 かつ再度イベントを取得したい場合は、@ref nn::os::Event::ClearSignal を呼ぶ必要があります。 208 209 @param[out] pEvent バッファの飽和時に起こされる手動リセットイベントです。 210 211 @return 処理の結果を返します。 212 @retval ResultSuccess 成功しました。 213 */ 214 Result GetBufferFullEvent( nn::os::Event* pEvent ); 215 216 /*! 217 @brief マイクアンプのゲインを設定します。 218 219 マイクアンプのゲインの初期値は 220 @ref nn::mic::CTR::AMP_GAIN_DEFAULT_VALUE に設定されています。 221 222 @param[in] gain マイクアンプのゲインを設定します。0 ～ 119 (10.5dB ～ 70.0dB)の範囲で指定します。 223 224 @return 処理の結果を返します。 225 @retval ResultSuccess 成功しました。 226 */ 227 Result SetAmpGain( u8 gain ); 228 229 /*! 230 @brief マイクアンプのゲインを取得します。 231 232 @param[out] pGain マイクアンプのゲインを取得します。0 ～ 119 (10.5dB ～ 70.0dB)の範囲で取得します。 233 234 @return 処理の結果を返します。 235 @retval ResultSuccess 成功しました。 236 */ 237 Result GetAmpGain( u8* pGain ); 238 239 /*! 240 @brief マイク電源のON/OFF設定を設定します。 241 242 マイク電源ON時や、スリープから復帰した直後は１秒間マイク入力が安定しないため 243 強制的に無音にしています。 244 245 サンプリング種別ごとの無音値は@ref nn::mic::CTR::SAMPLING_TYPE_8BIT_SILENT_DATA 、 246 @ref nn::mic::CTR::SAMPLING_TYPE_16BIT_SILENT_DATA 、 247 @ref nn::mic::CTR::SAMPLING_TYPE_SIGNED_8BIT_SILENT_DATA 、 248 @ref nn::mic::CTR::SAMPLING_TYPE_SIGNED_16BIT を参照してください。 249 250 @param[in] enable trueであればマイク電源をONにします。falseであればマイク電源をOFFにします。 251 252 @return 処理の結果を返します。 253 @retval ResultSuccess 成功しました。 254 */ 255 Result SetAmp( bool enable ); 256 257 /*! 258 @brief マイク電源のON/OFF設定を取得します。 259 260 @param[out] pEnable マイク電源がONであればtrueが返ります。マイク電源がOFFであればfalseが返ります。 261 262 @return 処理の結果を返します。 263 @retval ResultSuccess 成功しました。 264 */ 265 Result GetAmp( bool* pEnable ); 266 267 /*! 268 @brief ゲインとサンプリング種別に対応した、マイク入力あり判定禁止領域の上限と下限の値を取得します。 269 この上限と下限の間の値を、マイク入力ありと判定することは避けてください。 270 271 @param[out] upper 判定禁止領域の上限値です。 272 @param[out] lower 判定禁止領域の下限値です。 273 @param[in] type サンプリング種別を指定します。 274 @param[in] gain マイクアンプのゲインを設定します。0 ～ 119 (10.5dB ～ 70.0dB)の範囲で指定します。 275 276 @return 処理の結果を返します。 277 @retval true 領域を正しく取得できました。 278 @retval false 領域が正しく取得できませんでした。入力値が範囲内であるか確認して下さい。 279 */ 280 bool GetForbiddenArea( s32* upper, s32* lower, SamplingType type, u8 gain ); 281 282 /*! 283 @brief マイク入力データへ適用するローパスフィルタの設定を行います。 284 285 ローパスフィルタのカットオフ周波数は、マイクサンプリングレートの45パーセントです。<BR> 286 SAMPLING_RATE_32730の場合はオリジナルデータがローパスフィルタ適用済みであるため 287 本関数でローパスフィルタを適用したとしても効果はありません。 288 289 @param[in] enable ローパスフィルタを有効にする場合trueを指定します。(デフォルトはfalseです) 290 291 @return 処理の結果を返します。 292 @retval ResultSuccess 成功しました。 293 */ 294 Result SetLowPassFilter( bool enable ); 295 296 /*! 297 @brief マイクデータをクランプ処理するかどうかの設定を行います。 298 299 マイクデータは全範囲の入力が得られることが理想ですが、実際には個体差があります。<BR> 300 どの個体でも入力されることが保証される範囲として「マイク入力保証範囲」が定義されています。<BR> 301 302 本関数を引数trueで実行した場合、「マイク入力保証範囲」で値がクランプ処理されます。<BR> 303 マイクの個体差に起因する問題を回避するため通常はクランプありで使用してください。<BR> 304 305 より広い入力範囲を必要とする場合はクランプ処理を無効にしてください。<BR> 306 その場合、個体によっては「マイク入力保証範囲」より外の値が取得できない可能性が 307 あることに注意してください。 308 309 サンプリング種別ごとのマイク入力保証範囲は以下を参照してください。<BR> 310 @ref nn::mic::CTR::TYPE_8BIT_GUARANTEED_INPUT_MIN、<BR> 311 @ref nn::mic::CTR::TYPE_8BIT_GUARANTEED_INPUT_MAX、<BR> 312 @ref nn::mic::CTR::TYPE_16BIT_GUARANTEED_INPUT_MIN、<BR> 313 @ref nn::mic::CTR::TYPE_16BIT_GUARANTEED_INPUT_MAX、<BR> 314 @ref nn::mic::CTR::TYPE_SIGNED_8BIT_GUARANTEED_INPUT_MIN、<BR> 315 @ref nn::mic::CTR::TYPE_SIGNED_8BIT_GUARANTEED_INPUT_MAX、<BR> 316 @ref nn::mic::CTR::TYPE_SIGNED_16BIT_GUARANTEED_INPUT_MIN、<BR> 317 @ref nn::mic::CTR::TYPE_SIGNED_16BIT_GUARANTEED_INPUT_MAX、<BR> 318 319 本関数実行時に既にサンプリングが行われている場合、<BR> 320 現在書き込んでいる位置以降に設定が反映されます。<BR> 321 322 @param[in] enable trueであればクランプ処理を有効にします。（デフォルトはtrue） 323 324 @return 処理の結果を返します。 325 @retval ResultSuccess 成功しました。 326 */ 327 Result SetClamp( bool enable ); 328 329 /*! 330 @brief マイクデータのクランプ処理設定を取得します。 331 332 @param[out] pEnable クランプ処理が有効であればtrueが返ります。 333 334 @return 処理の結果を返します。 335 @retval ResultSuccess 成功しました。 336 */ 337 Result GetClamp( bool* pEnable ); 338 339 } 340 } 341 } 342 343 #endif // ifndef NN_MIC_CTR_MIC_API_H_ 344