ISpatialAudioClient

ISpatialAudioClient インターフェイスは、3D 空間内の位置から音声を発するオーディオストリームをクライアントが作成できるようにします。

次のサンプルコードは、IMMDevice を使用してこのインターフェイスを初期化する方法を示します。

HRESULT hr;
Microsoft::WRL::ComPtr<IMMDeviceEnumerator> deviceEnum;
Microsoft::WRL::ComPtr<IMMDevice> defaultDevice;

hr = CoCreateInstance(__uuidof(MMDeviceEnumerator), nullptr, CLSCTX_ALL, __uuidof(IMMDeviceEnumerator), (void**)&deviceEnum);
hr = deviceEnum->GetDefaultAudioEndpoint(EDataFlow::eRender, eMultimedia, &defaultDevice);

Microsoft::WRL::ComPtr<ISpatialAudioClient> spatialAudioClient;
hr = defaultDevice->Activate(__uuidof(ISpatialAudioClient), CLSCTX_INPROC_SERVER, nullptr, (void**)&spatialAudioClient);

IMMDevice にアクセスできない UWP アプリの場合は、ActivateAudioInterfaceAsync を呼び出して ISpatialAudioClient のインスタンスを取得してください。例については、WindowsAudioSession サンプルを参照してください。

指定された静的空間オーディオチャネルの 3D 空間内の位置を取得します。

メソッドが成功した場合は S_OK を返します。失敗した場合、返される可能性のあるコードには次の表に示す値が含まれますが、これらに限定されません。

位置の値は、各単位が 1 メートルを表す右手系デカルト座標系を使用します。この座標系はリスナーを基準としており、原点（x=0.0, y=0.0, z=0.0）はリスナーの両耳の中心点を表します。

現在のレンダリングエンジンにネイティブな静的スピーカーベッドチャネルのサブセットを表すチャネルマスクを取得します。

メソッドが成功した場合は S_OK を返します。

空間オーディオクライアントの動的オーディオオブジェクトの最大数を取得します。

メソッドが成功した場合は S_OK を返します。

動的な ISpatialAudioObject とは、ISpatialAudioObjectRenderStream::ActivateSpatialAudioObject メソッドの type パラメーターを AudioObjectType_Dynamic に設定してアクティブ化されたものです。クライアントには、同時にアクティブ化できる動的空間オーディオオブジェクトの最大数の上限があります。オーディオレンダリングパイプラインの容量が変化すると、システムは同時に使用できる動的空間オーディオオブジェクトの最大数を動的に調整します。その前に、システムは OnAvailableDynamicObjectCountChange を呼び出し、リソース上限の変更をクライアントに通知します。

ISpatialAudioObject が使用されなくなった場合は、その Release を呼び出してリソースを解放し、新しい動的空間オーディオオブジェクトを作成できるようにしてください。

Windows Sonic が利用できない場合（たとえば、ノートパソコンに内蔵されたステレオスピーカーで再生している場合や、ユーザーがデバイス上で Windows Sonic を明示的に有効にしていない場合）、GetMaxDynamicObjectCount がアプリケーションに返す利用可能な動的オブジェクトの数は 0 になります。

空間オーディオオブジェクトでサポートされているすべてのオーディオ形式を含む IAudioFormatEnumerator を取得します。リスト内の最初の項目が最も推奨される形式を表します。

メソッドが成功した場合は S_OK を返します。

1 回の処理パスあたりの最大フレーム数を取得します。このメソッドは、各処理パスでオーディオデータを伝送するために割り当てるべきソースバッファーのサイズを決定するために使用できます。

メソッドが成功した場合は S_OK を返します。

ISpatialAudioObjectRenderStream が指定された形式をサポートするかどうかを示す値を取得します。

指定された形式がサポートされている場合は S_OK を返します。指定された形式がサポートされていない場合、このメソッドは AUDCLNT_E_UNSUPPORTED_FORMAT を返します。

成功した場合、現在アクティブな空間レンダリングエンジンが指定された空間オーディオレンダーストリームをサポートするかどうかを示す値を取得します。

メソッドが成功した場合は S_OK を返します。失敗した場合、返される可能性のあるコードには次の表に示す値が含まれますが、これらに限定されません。

ISpatialAudioObjectRenderStreamForMetadata を照会する際、auxiliaryInfo パラメーターを使用して特定のメタデータ形式がサポートされているかどうかを照会できます。次のコード例は、メタデータ形式のサポートを確認するために PROPVARIANT 構造体を初期化する方法を示します。

PROPVARIANT auxiliaryInfo;  
auxiliaryInfo.vt = VT_CLSID;  
auxiliaryInfo.puuid = const_cast<CLSID*>(&CONTOSO_SPATIAL_METADATA_V1_0);  

指定されたメタデータ形式がサポートされていない場合、IsSpatialAudioStreamAvailable は SPTLAUDCLNT_E_METADATA_FORMAT_IS_NOT_SUPPORTED を返します。

空間オーディオストリームアクティブ化構造体のいずれかを使用して、空間オーディオストリームをアクティブ化して初期化します。

メソッドが成功した場合は S_OK を返します。

このメソッドは、次の空間オーディオストリームインターフェイスのアクティブ化をサポートします。

ISpatialAudioObjectRenderStream

ISpatialAudioObjectRenderStreamForMetadata

例

Microsoft::WRL::ComPtr<ISpatialAudioClient> spatialAudioClient;

// Activate ISpatialAudioClient on the desired audio-device 
hr = defaultDevice->Activate(__uuidof(ISpatialAudioClient), CLSCTX_INPROC_SERVER, nullptr, (void**)&spatialAudioClient);

hr = spatialAudioClient->IsAudioObjectFormatSupported(&format);

// Create the event that will be used to signal the client for more data
HANDLE bufferCompletionEvent = CreateEvent(nullptr, FALSE, FALSE, nullptr);

SpatialAudioObjectRenderStreamActivationParams streamParams;
streamParams.ObjectFormat = &format;
streamParams.StaticObjectTypeMask = ChannelMask_Stereo;
streamParams.MinDynamicObjectCount = 0;
streamParams.MaxDynamicObjectCount = 0;
streamParams.Category = AudioCategory_SoundEffects;
streamParams.EventHandle = bufferCompletionEvent;
streamParams.NotifyObject = nullptr;

PROPVARIANT activationParams;
PropVariantInit(&activationParams);
activationParams.vt = VT_BLOB;
activationParams.blob.cbSize = sizeof(streamParams);
activationParams.blob.pBlobData = reinterpret_cast<BYTE *>(&streamParams);

Microsoft::WRL::ComPtr<ISpatialAudioObjectRenderStream> spatialAudioStream;
hr = spatialAudioClient->ActivateSpatialAudioStream(&activationParams, __uuidof(spatialAudioStream), (void**)&spatialAudioStream);