Win32 API 日本語リファレンス
ホーム › Media.Audio › ISpatialAudioObjectForHrtf

ISpatialAudioObjectForHrtf

COM
📘 Microsoft Learn (日本語) · English
IIDd7436ade-1978-4e14-aba0-555bd8eb83b4継承元ISpatialAudioObjectBase自前メソッド開始 vtbl7

公式ドキュメント

3D空間内の、ユーザーに対する相対位置(頭部相対の伝達関数 (HRTF))からレンダリングされるオーディオデータを提供するオブジェクトを表します。

解説(Remarks)

Note このインターフェイスが提供するメソッドの多くは、継承元の ISpatialAudioObjectBase インターフェイスで実装されています。

メソッド 6

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 7 HRESULT SetPosition(FLOAT x, FLOAT y, FLOAT z)

ISpatialAudioObjectForHrtf のオーディオデータがレンダリングされる、リスナーに対する相対的な3D空間内の位置を設定します。

xFLOATinオーディオオブジェクトの x 位置(リスナーに対する相対値、メートル単位)。正の値はリスナーの右側、負の値は左側を表します。
yFLOATinオーディオオブジェクトの y 位置(リスナーに対する相対値、メートル単位)。正の値はリスナーの上側、負の値は下側を表します。
zFLOATinオーディオオブジェクトの z 位置(リスナーに対する相対値、メートル単位)。正の値はリスナーの後方、負の値は前方を表します。

戻り値

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

Return code Description
SPTLAUDCLNT_E_OUT_OF_ORDER

SetPosition の呼び出し前に ISpatialAudioObjectRenderStreamBase::BeginUpdatingAudioObjects が呼び出されていませんでした。
SPTLAUDCLNT_E_RESOURCES_INVALIDATED

以前のオーディオ処理パスで SetEndOfStream が明示的または暗黙的に呼び出されました。オーディオ処理パス内(ISpatialAudioObjectRenderStreamBase::BeginUpdatingAudioObjects と ISpatialAudioObjectRenderStreamBase::EndUpdatingAudioObjects の呼び出しの間)で GetBuffer が呼び出されなかった場合、システムによって SetEndOfStream が暗黙的に呼び出されます。
SPTLAUDCLNT_E_PROPERTY_NOT_SUPPORTED
ISpatialAudioObjectForHrtf の型が AudioObjectType_Dynamic ではありません。ISpatialAudioObjectRenderStreamBase::ActivateSpatialAudioObjectForHrtf メソッドの type パラメーターでオーディオオブジェクトの型を設定してください。

解説(Remarks)

このメソッドは、型が AudioObjectType_Dynamic である ISpatialAudioObjectForHrtf に対してのみ呼び出せます。ISpatialAudioObjectRenderStreamForHrtf::ActivateSpatialAudioObjectForHrtf メソッドの type パラメーターでオーディオオブジェクトの型を設定してください。

位置の値は右手系のデカルト座標系を使用し、各単位は 1 メートルを表します。座標系はリスナーに対する相対系であり、原点 (x=0.0, y=0.0, z=0.0) はリスナーの両耳の中心点を表します。

SetPosition が一度も呼び出されない場合、既定の位置として原点 (x=0.0, y=0.0, z=0.0) が使用されます。SetPosition の呼び出し後は、別の SetPosition の呼び出しで位置が変更されるまで、設定された位置がオーディオオブジェクトに使用されます。

vtbl 8 HRESULT SetGain(FLOAT gain)

ISpatialAudioObjectForHrtf のゲインを設定します。

gainFLOATinISpatialAudioObjectForHrtf のゲイン(dB 単位)。

戻り値

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

Return code Description
SPTLAUDCLNT_E_OUT_OF_ORDER

SetGain の呼び出し前に ISpatialAudioObjectRenderStreamBase::BeginUpdatingAudioObjects が呼び出されていませんでした。
SPTLAUDCLNT_E_RESOURCES_INVALIDATED

以前のオーディオ処理パスで SetEndOfStream が明示的または暗黙的に呼び出されました。オーディオ処理パス内(ISpatialAudioObjectRenderStreamBase::BeginUpdatingAudioObjects と ISpatialAudioObjectRenderStreamBase::EndUpdatingAudioObjects の呼び出しの間)で GetBuffer が呼び出されなかった場合、システムによって SetEndOfStream が暗黙的に呼び出されます。

解説(Remarks)

これは、SpatialAudioHrtfDistanceDecay_CustomDecay 減衰タイプを使用するように構成された空間オーディオオブジェクトに対してのみ有効です。ISpatialAudioObjectForHrtf オブジェクトの減衰タイプは、SetDistanceDecay を呼び出して設定します。HRTF レンダーストリーム内のすべてのオブジェクトの既定の減衰タイプは、ISpatialAudioClient::ActivateSpatialAudioStream に渡す SpatialAudioHrtfActivationParams の DistanceDecay フィールドを設定して指定します。

SetGain が一度も呼び出されない場合、既定値 0.0 が使用されます。SetGain の呼び出し後は、別の SetGain の呼び出しでゲインが変更されるまで、設定されたゲインがオーディオオブジェクトに使用されます。

vtbl 9 HRESULT SetOrientation(FLOAT** orientation)

ISpatialAudioObjectForHrtf のオーディオデータがレンダリングされる、リスナーの基準座標系に対する相対的な3D空間内の向きを設定します。

orientationFLOAT**in行優先の 3x3 回転行列を定義する float の配列。

戻り値

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

Return code Description
SPTLAUDCLNT_E_OUT_OF_ORDER

SetOrientation の呼び出し前に ISpatialAudioObjectRenderStreamBase::BeginUpdatingAudioObjects が呼び出されていませんでした。
SPTLAUDCLNT_E_RESOURCES_INVALIDATED

以前のオーディオ処理パスで SetEndOfStream が明示的または暗黙的に呼び出されました。オーディオ処理パス内(ISpatialAudioObjectRenderStreamBase::BeginUpdatingAudioObjects と ISpatialAudioObjectRenderStreamBase::EndUpdatingAudioObjects の呼び出しの間)で GetBuffer が呼び出されなかった場合、システムによって SetEndOfStream が暗黙的に呼び出されます。

解説(Remarks)

SetOrientation が一度も呼び出されない場合、既定値として単位行列が使用されます。SetOrientation の呼び出し後は、別の SetOrientation の呼び出しで向きが変更されるまで、設定された向きがオーディオオブジェクトに使用されます。

vtbl 10 HRESULT SetEnvironment(SpatialAudioHrtfEnvironmentType environment)

ISpatialAudioObjectForHrtf のオーディオ処理時にシミュレートされる音響環境の種類を設定します。

environmentSpatialAudioHrtfEnvironmentTypeinISpatialAudioObjectForHrtf のオーディオ処理時にシミュレートされる音響環境の種類を指定する値。

戻り値

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

Return code Description
SPTLAUDCLNT_E_OUT_OF_ORDER

SetEnvironment の呼び出し前に ISpatialAudioObjectRenderStreamBase::BeginUpdatingAudioObjects が呼び出されていませんでした。
SPTLAUDCLNT_E_RESOURCES_INVALIDATED

以前のオーディオ処理パスで SetEndOfStream が明示的または暗黙的に呼び出されました。オーディオ処理パス内(ISpatialAudioObjectRenderStreamBase::BeginUpdatingAudioObjects と ISpatialAudioObjectRenderStreamBase::EndUpdatingAudioObjects の呼び出しの間)で GetBuffer が呼び出されなかった場合、システムによって SetEndOfStream が暗黙的に呼び出されます。

解説(Remarks)

SetEnvironment が呼び出されない場合、既定値の SpatialAudioHrtfEnvironment_Small が使用されます。

vtbl 11 HRESULT SetDistanceDecay(SpatialAudioHrtfDistanceDecay* distanceDecay)

ISpatialAudioObjectForHrtf の位置からリスナーの位置までの距離に応じて適用される減衰モデルを設定します。

distanceDecaySpatialAudioHrtfDistanceDecay*in減衰モデル。

戻り値

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

Return code Description
SPTLAUDCLNT_E_OUT_OF_ORDER

SetDistanceDecay の呼び出し前に ISpatialAudioObjectRenderStreamBase::BeginUpdatingAudioObjects が呼び出されていませんでした。
SPTLAUDCLNT_E_RESOURCES_INVALIDATED

以前のオーディオ処理パスで SetEndOfStream が明示的または暗黙的に呼び出されました。オーディオ処理パス内(ISpatialAudioObjectRenderStreamBase::BeginUpdatingAudioObjects と ISpatialAudioObjectRenderStreamBase::EndUpdatingAudioObjects の呼び出しの間)で GetBuffer が呼び出されなかった場合、システムによって SetEndOfStream が暗黙的に呼び出されます。

解説(Remarks)

SetEnvironment が呼び出されない場合、既定値が使用されます。

vtbl 12 HRESULT SetDirectivity(SpatialAudioHrtfDirectivityUnion* directivity)

ISpatialAudioObjectForHrtf の空間オーディオ指向性モデルを設定します。

directivitySpatialAudioHrtfDirectivityUnion*in

空間オーディオ指向性モデル。この値は次のいずれかの構造体を指定できます。

戻り値

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

Return code Description
SPTLAUDCLNT_E_OUT_OF_ORDER

SetDirectivity の呼び出し前に ISpatialAudioObjectRenderStreamBase::BeginUpdatingAudioObjects が呼び出されていませんでした。
SPTLAUDCLNT_E_RESOURCES_INVALIDATED

以前のオーディオ処理パスで SetEndOfStream が明示的または暗黙的に呼び出されました。オーディオ処理パス内(ISpatialAudioObjectRenderStreamBase::BeginUpdatingAudioObjects と ISpatialAudioObjectRenderStreamBase::EndUpdatingAudioObjects の呼び出しの間)で GetBuffer が呼び出されなかった場合、システムによって SetEndOfStream が暗黙的に呼び出されます。

解説(Remarks)

SpatialAudioHrtfDirectivity 構造体は、カーディオイドモデルまたはコーンモデルと線形補間できる全指向性モデルを表します。

SetDirectivity が呼び出されない場合、既定の型 SpatialAudioHrtfDirectivity_OmniDirectional が補間なしで使用されます。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

出力引数: 
#define global IID_ISpatialAudioObjectForHrtf "{D7436ADE-1978-4E14-ABA0-555BD8EB83B4}"
#usecom global ISpatialAudioObjectForHrtf IID_ISpatialAudioObjectForHrtf "{}"
#comfunc global ISpatialAudioObjectForHrtf_SetPosition       7 float,float,float
#comfunc global ISpatialAudioObjectForHrtf_SetGain           8 float
#comfunc global ISpatialAudioObjectForHrtf_SetOrientation    9 var
#comfunc global ISpatialAudioObjectForHrtf_SetEnvironment    10 int
#comfunc global ISpatialAudioObjectForHrtf_SetDistanceDecay  11 var
#comfunc global ISpatialAudioObjectForHrtf_SetDirectivity    12 var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。