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 パッケージ (Microsoft.XAudio2.Redist.*.nupkg) には、XAudio 2.9 API を実装する 32 ビットバージョンと 64 ビット バージョンの DLL が含まれています。 DLL は XAUDIO2_9REDIST.DLL と呼ばれます。 この DLL は、Windows 7 SP1、Windows 8、Windows 8.1、Windows 10で動作します。

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

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

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

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

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

ライブラリ XAPOBASEREDIST。LIB は、カスタム XAudio 処理オブジェクト (XAPO) を補完する予定で、使用されていない場合は Microsoft.XAudio2.Redist.targets から削除できる場合にのみ必要です。

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

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

アプリのコンパイル

含めるヘッダーの選択

XAudio 2.9 NuGet パッケージには、Windows 10 SDK に含まれているのと同じ XAudio2 ヘッダー ファイルが含まれています。 ただし、ヘッダー ファイルには、以前のバージョンの Windows を含め、 サポートされているすべてのプラットフォームを明示的にターゲットにしながら使用できるように、いくつかの調整が行われます。

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

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

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

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

DLL の読み込み

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

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

DLL 署名の確認

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

テスト

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

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

空間サウンドの有効化

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

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

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

IXAudio2::CreateMasteringVoice で AUDIO_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_DEVICE_INVALIDATED。 ただし、特定の値を持つエラー コードに依存するコードをアプリでハードコーディングしないことをお勧めします。

このエラーを通知するには、アプリで 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 ビット Float PCM
  • 16 ビット ADPCM
  • Xwma

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

優先 CPU コア

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

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

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

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

IXAudio2::CreateMasteringVoice を呼び出すときにアプリで特定のオーディオ形式が指定されている場合、XAudio 2.9 でこのスイッチを実行できないことがあります。 たとえば、マスタリング音声で 48 kHz のサンプリング レートを使用し、新しいオーディオ デバイスが 44.1 kHz のみをサポートすることをアプリで指定した場合、自動スイッチは失敗し、XAudio 2.9 は XAUDIO2_E_DEVICE_INVALIDATED エラーを報告します。

XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT フラグを 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 更新プログラム以降、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 Sonic や Dolby Atmos for Headphones などの一部の空間サウンド形式は、ステレオ オーディオ エンドポイントで使用するように設計されています。 これらのフォーマットは、"仮想"サラウンドサウンドエフェクトを実現する独自のアルゴリズムを使用して、サラウンドサウンドをステレオに折りたたみます。 言い換えると、リスナーは、ヘッドフォンのみを装着している間、またはステレオスピーカーの単一のペアで聞いている間でも、3D空間の異なる位置から現れる音を知覚することができます。

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

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

CreateHrtfApo

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