XAudio 2.9 の再頒布可能バージョンに関する開発者向けガイド

xaudio 2.9 のバージョンは、 NuGet パッケージとして入手できます。 開発者は、このバージョンの XAudio 2.9 をアプリと共に再頒布できます。 これにより、オペレーティングシステムイメージの一部として xaudio 2.9 を含まない古いバージョンの Windows で、アプリで xaudio 2.9 を使用できるようになります。 XAudio 2.7 が2010以降に更新されていないため、この再頒布可能パッケージの使用は DirectX SDK からの XAudio 2.7 の再配布よりも優先されます。

DirectX 開発者向けのその他のリソースについては、 directx のランディングページ を参照してください。

サポートされているプラットフォーム

xaudio 2.9 NuGet パッケージ (XAudio2. * .nupkg には、XAudio 2.9 API を実装する32ビット版と64ビット版の DLL が含まれています。 DLL は XAUDIO29REDIST.DLL と呼ばれ _ ます。 この DLL は Windows 7 SP1、Windows 8、Windows 8.1、および Windows 10 で動作します。

DLL が Windows 10 システムで使用されている場合は、オペレーティングシステムの一部である XAUDIO29.DLL のバージョン番号が確認さ _ れます。オペレーティングシステムの方が新しい場合は、オペレーティングシステムのすべての API 呼び出しが XAUDIO29.DLL に委任され _ ます。 これにより、アプリは常に最新バージョンの XAudio 2.9 を使用します。これは現在のプラットフォームで利用できます。

DLL は Xbox One を意図していません。 Xbox One で使用する場合、DLL は常に Xbox One オペレーティングシステムの XAUDIO29.DLL へのすべての API 呼び出しを委任し _ ます。

DLL は UWP アプリを対象としていません。 UWP アプリで _ は、オペレーティングシステムの一部である XAUDIO29.DLL を使用する必要があります。

NuGet パッケージのインストール

NuGet パッケージをインストールする最も簡単な方法は、Microsoft Visual Studio でパッケージマネージャー NuGetを使用することです。 これを行うと、Visual Studio プロジェクトファイルが自動的に更新され、 XAudio2 が含まれるようになります。 .Targets ファイルによって、XAudio2 のヘッダーファイルを含むインクルードフォルダーがプロジェクトインクルードパスのコレクションに追加されます。 .Targets ファイルによって、.DLL または .EXE XAUDIO2REDIST とのリンクも作成されます。LIB と XAPOBASEREDIST。変数.

ライブラリ XAPOBASEREDIST。LIB は、カスタム XAudio 処理オブジェクト (XAUDIO) を impement する場合にのみ必要であり、使用されていない場合は XAudio2 から削除できます。

また、他のツールを使用して NuGet パッケージの内容を抽出したり、ファイル拡張子の名前を .zip に変更したり、ZIP エクストラクターツールを使用してファイルを抽出したりすることもできます。

xaudio2redist VC++ パッケージマネージャーに使用できるポートもあります。

アプリのコンパイル

含めるヘッダーの選択

xaudio 2.9 NuGet パッケージには、Windows 10 SDK に含まれているのと同じ XAudio2 ヘッダーファイルが含まれています。 ただし、以前のバージョンの Windows を含め、サポートされているすべてのプラットフォームを明示的に対象にしている間は、ヘッダーファイルに調整が加えられていることを確認してください。

Microsoft Visual Studio で NuGet パッケージマネージャーを使用してNuGet パッケージをインストールすると、ヘッダーファイルへのパスが Windows SDK ヘッダーファイルへのパスの前に配置されます。 これは、プロジェクト内のコードに XAUDIO2 が含まれている場合に使用されることを意味します。H ヘッダーは、NuGet パッケージからクロスプラットフォームヘッダーを取得します。 これは通常、必要な動作です。

インクルードヘッダーへのパスをプロジェクトに手動で追加する場合は注意が必要です。誤った順序で指定すると、OS バージョン固有の XAUDIO2 が発生する可能性があります。XAUDIO2 のクロスプラットフォームバージョンではなく、Windows SDK に含まれる H。

ヘッダーにエラーが発生しにくくなるように、NuGet パッケージには、"REDIST" が追加された各ヘッダーのバージョンが含まれています。 たとえば、XAUDIO2 に加えて、また、NuGet パッケージには XAUDIO2REDIST も含まれています。 必要に応じて、コードに XAUDIO2REDIST を直接含めることができます。使用されているヘッダーファイルがあいまいにならないようにします。 -REDIST を含める場合。H ヘッダーファイルのバージョン。インクルードファイルディレクトリがプロジェクトファイルに表示される順序は関係ありません。

アプリが Xbox One 用にコンパイルされている場合は、引き続き XAUDIO2 を含める必要があることに注意してください。Xbox One に対してコンパイルする場合、一部の Xbox One 固有の api は XAUDIO2REDIST から除外されるためです。 この NuGet パッケージは、Xbox One を目的としたものではありません。

DLL を読み込んでいます

アプリを XAUDIO2REDIST にリンクすることをお勧めします。_ アプリの実行可能ファイルと同じフォルダーに XAUDIO29REDIST.DLL をインストールします。 これにより _ 、実行可能ファイルが起動されるとすぐに XAUDIO29REDIST.DLL が読み込まれます。 ただし、必要に応じて、 LoadLibraryExGetProcAddress を使用して、必要に応じて XAUDIO29REDIST.DLL を読み込むこともでき _ ます。 これは、アプリが常に XAudio2 Api を使用する必要がない場合に適したソリューションです。 ただし、これを行う場合は、アプリが終了するまで XAUDIO29REDIST.DLL 読み込まれたままにしておく必要があり _ ます。 dll をアンロードしようとすると、バックグラウンドスレッドが dll 内のコードを実行しているときにクラッシュが発生する可能性があります。

古い XAudio 2.7 とは異なり、CoCreateInstance を使用して DLL を読み込むことはできません。

DLL 署名を確認しています

XAUDIO2 _9REDIST.DLL バイナリは、sha-1 署名を使用して Microsoft によって署名されます。 そのため、署名の検証を試みるコード (ゲームのためのマルウェア対策モジュールなど) では、SHA-1 をサポートする必要があります。 Windows 7 SP1 では、最初は sha-1 がサポートされておらず、その機能を追加するための更新が必要であることに注意してください。 更新プログラムは KB4474419として入手できます。

テスト

新しいバージョンの Windows 10 での空間サウンド

Windows 10 1903 update 以降では、特定の条件が満たされた場合、xaudio 2.9 は仮想サラウンドサウンドを自動的に使用します。 ゲームが想定どおりに動作することを確認するために、Windows 10 1903 (またはそれ以降) でマルチチャネルサウンドを生成するゲームのテストをお勧めします。

空間サウンドの有効化

ユーザーは、Windows システムトレイのスピーカーアイコンを右クリックして、空間サウンド形式を有効にすることができます。

xaudio 2.9 では、XAudio2 API を使用しているプロセスが Windows ゲームバーによってゲームとして認識される場合にのみ、ユーザーが選択した空間サウンド形式が使用されます。 開発中、このプロセスがゲームバーによってまだゲームとして認識されていない可能性があります。 これを変更するには、Win + G キーボードショートカットキーを使用して、ゲームの実行中にゲームバーを立ち上げます。 次に、[設定] アイコンをクリックし、[これはゲームであることを思い出してください] というチェックボックスをオンにします。

空間サウンドからオプトアウト

IXAudio2:: CreateMasteringVoiceAUDIO_STREAM_CATEGORYパラメーターに特定の値を指定することで、XAudio2 を使用して空間サウンドエンコーダーを使用しないようにする方法があります。

次のカテゴリでは、空間サウンドが有効になっています。

  • AudioCategory_ForegroundOnlyMedia
  • AudioCategory_GameEffects
  • AudioCategory_GameMedia
  • AudioCategory_Movie
  • AudioCategory_Media

次のいずれかのカテゴリが指定されている場合、[空間サウンド] は有効になりません。

  • AudioCategory_Other
  • AudioCategory_Communications
  • AudioCategory_Alerts
  • AudioCategory_SoundEffects
  • AudioCategory_GameChat
  • AudioCategory_Speech

エラー処理

ゲームでオーディオデバイスの変更を処理できることをテストすることが重要です。たとえば、ヘッドホンが接続されている場合や、取り外されている場合などです。 これは、44.1 kHz サンプリングレートのみをサポートするヘッドホンでテストする必要があります。 多くのローエンド USB ヘッドホンと Bluetooth ヘッドセットは 44.1 kHz のみをサポートしています。 仮想オーディオエンドポイント機能が使用されている場合でも、48 khz サンプリングレートと 44.1 khz サンプリングレートの間の切り替えによってエラーが発生することがあります。 ヘッドホンが 48 kHz もサポートしている場合、このエラーは発生しません。 Windows 7 SP1 では、仮想オーディオエンドポイント機能が使用できないことに注意してください。

オーディオエンドポイントの変更から自動的に回復できない場合に XAudio 2.9 によって返されるエラーコードは、 XAUDIO2 _ E _ デバイスが _ 無効になっていることを示します。 ただし、アプリでは、特定の値を持つエラーコードに対する依存関係をハードコーディングしないことをお勧めします。

このエラーを通知するには、アプリで IXAudio2EngineCallback インターフェイスを実装し、 IXAudio2:: registerforcallbacks バック メソッドを呼び出してそのインターフェイスへのポインターを提供する必要があります。 再生中にエラーが発生した場合、 IXAudio2EngineCallback:: OnCriticalError のアプリの実装は XAudio2 API によって呼び出されます。

オーディオパイプラインが一時停止されている場合、 IXAudio2EngineCallback:: OnCriticalError は必ずしも呼び出されないことに注意してください。 たとえば、ユーザーがアプリを最小化した場合、またはアプリが何らかの理由で中断された場合、オーディオ再生が一時停止している可能性があります。 この時間内にオーディオデバイスの変更が発生した場合、このエラーは、アプリが IXAudio2:: StartEngine を呼び出したとき、または IXAudio2SourceVoice:: Startを呼び出したときにのみ返されます。 アプリで再生を一時停止できる場合は、再生が一時停止されている間にオーディオデバイスの変更をテストして、アプリがこの状況から引き続き回復できることを確認する必要があります。

Xaudio 2.9 API の相違点と XAudio 2.7 の違い

このセクションでは、XAudio 2.7 と再頒布可能バージョンの XAudio 2.9 の API の相違点の概要について説明します。

サポートされるフォーマット

XAudio 2.9 では、次の入力形式が PC でサポートされています。

  • 線形16ビット PCM
  • 線形32ビット浮動 PCM
  • 16ビットの ADPCM
  • xWMA

XMA 形式は、Xbox One でのみサポートされています。

優先 CPU コア

オーディオ処理のスレッドに使用する CPU コア2.9 を指定することができます。 ただし、通常は XAudio 2.9 でこの値だけを選択することをお勧めします。 これを行うには、 XAudio2Createへの呼び出しで XAudio2Processor パラメーターを設定し、XAUDIO2 を使用して _ 既定のプロセッサを使用 _ _ します。

xaudio 2.9 では、Xbox One で PC とは異なる CPU コアが選択されます。 IXAudio2Extension:: GetProcessor メソッドを使用して、どの CPU コア XAudio2 が選択されているかを判断できます。

仮想オーディオエンドポイント

xaudio 2.9 では、Windows 8 以降で実行する場合、既定で仮想オーディオエンドポイントが使用されます。 これは、XAudio 2.9 を使用しているときに既定のオーディオエンドポイントが変更された場合、自動的に新しいオーディオエンドポイントに切り替わるようにすることを意味します。 既定のオーディオエンドポイントが USB 経由で接続されているヘッドホンのペアであり、ユーザーがヘッドホンを unplugs たときに発生する可能性のあるの例を次に示します。 これにより、スピーカーが新しい既定のオーディオエンドポイントになります。

IXAudio2:: CreateMasteringVoiceを呼び出すときにアプリが特定のオーディオ形式を指定した場合、xaudio 2.9 がこのスイッチを実行できない可能性があります。 たとえば、マスタリングで 48 kHz のサンプリングレートを使用するように指定した場合、新しいオーディオデバイスでは 44.1 kHz しかサポートしていない場合、自動スイッチは失敗し、XAudio 2.9 は XAUDIO2 _ E _ device _ 無効化 エラーを報告します。

アプリは、 XAUDIO2 _ NO _ virtual _ Audio _ クライアント フラグを IXAudio2:: CreateMasteringVoiceに渡すことによって、仮想オーディオエンドポイントを使用しないようにすることができます。

仮想オーディオエンドポイントは Windows 7 SP1 では使用できません。 XAUDIO2 _ no _ VIRTUAL _ AUDIO _ CLIENT フラグは、Windows 7 SP1 には影響しません。

オーディオカテゴリ

アプリでは、オーディオストリームのカテゴリを指定する必要があります。 これを行うには、 IXAudio2:: CreateMasteringVoice メソッドを呼び出すときに、AudioCategory 列挙体の値を指定します。 たとえば、AudioCategory_GameEffects のようにします。 オーディオカテゴリは、Windows がサウンドを処理する方法、またはボリュームコントロールパネルでオーディオストリームをどのように表すかに影響を与える可能性があります。 また、[オーディオ] カテゴリは、 仮想サラウンドサウンド が自動的に有効になっている場合にも影響を及ぼします。

オーディオ処理のクォンタムの期間

ほとんどの Pc では、XAudio 2.9 は10ミリ秒のチャンクでオーディオを処理します。 これを処理クォンタムと呼びます。 ただし、一部のハードウェアでは、このクォンタムの期間が10ミリ秒と異なる場合があります。 正確なクォンタムを知る必要があるアプリでは、IXAudio2Extension:: GetProcessingQuantum メソッドを呼び出して値を取得できます。

空間サウンドと仮想サラウンド

Windows 10 1903 update 以降では、特定の条件が満たされた場合、xaudio 2.9 は仮想サラウンドサウンドを自動的に使用します。 ゲームが想定どおりに動作することを確認するために、Windows 10 1903 (またはそれ以降) でマルチチャネルサウンドを生成するゲームのテストをお勧めします。 この機能をテストする方法の詳細については、「 空間サウンドのテスト 」セクションを参照してください。

通常、XAudio 2.9 では、オーディオエンドポイントでサポートされているオーディオチャネルの "物理" 数と一致するように、マルチチャネルオーディオのフォールダウンが実行されます。 たとえば、ゲームで7.1 チャンネルのオーディオソースが提供されているにもかかわらず、ヘッドホンでサウンドが再生されている場合、XAudio 2.9 は、業界標準のフォールダウンマトリックスを使用して7.1 チャネルオーディオをステレオにフォールダウンします。 PC が HDMI オーディオエンドポイントに接続されている場合、7.1 チャネルオーディオは、HDMI 接続を介してその状態で送信されます。

Windows 10 は、オーディオをユーザーが選択した空間サウンド形式にエンコードする集中エンコーダーを使用して、空間オーディオのサポートを追加します。 Windows 10 には、Windows Sonic と呼ばれる空間サウンド形式が付属しています。 Dolby Atmos for Headphones などの他の形式は、Microsoft Store からダウンロードできます。 Windows の音響や Dolby Atmos for Headphones など、一部の空間サウンド形式は、ステレオオーディオエンドポイントで使用するように設計されています。 これらの形式では、"仮想" のサラウンドサウンド効果を実現する独自のアルゴリズムを使用して、サラウンドサウンドをステレオに分解します。 言い換えると、リスナーは、ヘッドホンのみを搭載している場合や、1組のステレオスピーカーでリッスンしている場合でも、3D 空間内のさまざまな位置から音を感じることができます。

XAudio 2.9 に含まれている X3DAudio api を使用して、同様の効果を実現できます。 主な違いは、X3DAudio では、アプリ開発者が3D オーディオを明示的にプログラミングする必要があるのに対し、仮想サラウンドサウンドは tradional チャネルベースのサウンドソースに自動的に適用されるという点です。

Windows 10 1903 以降では、xaudio 2.9 を使用するゲームでは、ユーザーがオーディオエンドポイントで有効にしているシステム全体の空間サウンド形式 (存在する場合) が使用されます。 これは、XAudio 2.9 では、ステレオへのサラウンドサウンドの通常のフォールダウンを実行しないことを意味します。 代わりに、サラウンドサウンド信号は、仮想サラウンドサウンド効果を実現するために、空間サウンドエンコーダー (たとえば、Windows Sonic) に配信されます。

CreateHrtfApo

Createhrtfapo関数は、Windows 10 でのみ使用できます。 XAudio 2.9 再頒布可能パッケージには実装されていません。