ISpatialAudioObjectBase
COM公式ドキュメント
ユーザーを基準とした3次元空間内の位置からレンダリングされる音声データを提供するオブジェクトを表す基底インターフェイスです。
メソッド 4
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
ISpatialAudioObject に音声データを供給するために使用するバッファーを取得します。
| buffer | BYTE** | out | 音声データを書き込むバッファーです。 |
| bufferLength | DWORD* | out | バッファーの長さ(バイト単位)です。この長さは、ISpatialAudioObjectRenderStream::BeginUpdatingAudioObjects の frameCountPerBuffer パラメーターで返される値に、ISpatialAudioClient::ActivateSpatialAudioStream の パラメーターとして渡される SpatialAudioObjectRenderStreamActivationParams で渡される WAVEFORMATEX 構造体の nBlockAlign フィールドの値を乗じたものになります。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合、返される可能性のあるコードには、次の表に示す値が含まれますが、これらに限定されません。
| 戻り値のコード | 説明 |
|---|---|
|
GetBuffer の呼び出し前に ISpatialAudioObjectRenderStream::BeginUpdatingAudioObjects が呼び出されていません。このメソッドは、GetBuffer を初めて呼び出す前、および ISpatialAudioObjectRenderStream::EndUpdatingAudioObjects を呼び出すたびにその後で呼び出す必要があります。 |
|
|
SetEndOfStream が、直前の音声処理パスで明示的または暗黙的に呼び出されました。音声処理パス内(ISpatialAudioObjectRenderStream::BeginUpdatingAudioObjects と ISpatialAudioObjectRenderStream::EndUpdatingAudioObjects の呼び出しの間)で GetBuffer が呼び出されなかった場合、SetEndOfStream はシステムによって暗黙的に呼び出されます。 |
解説(Remarks)
ISpatialAudioObjectRenderStream::ActivateSpatialAudioObject の呼び出しによって ISpatialAudioObject がアクティブ化された後、 GetBuffer が初めて呼び出された時点で、空間音声オブジェクトのライフタイムが開始します。 その後も空間音声オブジェクトを有効なまま維持するには、この GetBuffer をすべての処理パス(ISpatialAudioObjectRenderStream::BeginUpdatingAudioObjects と ISpatialAudioObjectRenderStream::EndUpdatingAudioObjects の呼び出しの間)で呼び出す必要があります。音声処理パス内で GetBuffer が呼び出されなかった場合、非アクティブ化のために音声オブジェクトに対して SetEndOfStream が暗黙的に呼び出されます。この場合、音声オブジェクトは、オブジェクトに対して Release を呼び出した後、ActivateSpatialAudioObject を再度呼び出してオブジェクトを再アクティブ化することでのみ再利用できます。
GetBuffer で取得したポインターは、ISpatialAudioObjectRenderStream::EndUpdatingAudioObjects が呼び出された後は使用しないでください。
ISpatialAudioObject に対して音声データの最終ブロックが送信されたことをシステムに通知し、オブジェクトを非アクティブ化してそのリソースを再利用できるようにします。
| frameCount | DWORD | in | 最終処理パスに含める音声バッファー内の音声フレーム数です。この数は、ISpatialAudioObjectRenderStream::BeginUpdatingAudioObjects の frameCountPerBuffer パラメーターで返される値以下になる場合があります。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合、返される可能性のあるコードには、次の表に示す値が含まれますが、これらに限定されません。
| 戻り値のコード | 説明 |
|---|---|
|
SetEndOfStream の呼び出し前に ISpatialAudioObjectRenderStream::BeginUpdatingAudioObjects が呼び出されていません。 |
|
|
SetEndOfStream が、直前の音声処理パスで明示的または暗黙的に呼び出されました。音声処理パス内(ISpatialAudioObjectRenderStream::BeginUpdatingAudioObjects と ISpatialAudioObjectRenderStream::EndUpdatingAudioObjects の呼び出しの間)で GetBuffer が呼び出されなかった場合、SetEndOfStream はシステムによって暗黙的に呼び出されます。 |
解説(Remarks)
SetEndOfStream を呼び出した後は Release を呼び出して、音声オブジェクトのリソースを将来の使用のために解放してください。
ISpatialAudioObject が有効かどうかを示すブール値を取得します。
| isActive | BOOL* | out | 音声オブジェクトが現在有効な場合は TRUE、それ以外の場合は FALSE です。 |
戻り値
メソッドが成功した場合は S_OK を返します。
解説(Remarks)
この値が false の場合は、Release を呼び出して、音声オブジェクトのリソースを将来利用できるようにしてください。
SetEndOfStream が暗黙的または明示的に呼び出されると、IsActive は false に設定されます。音声処理パス内(ISpatialAudioObjectRenderStream::BeginUpdatingAudioObjects と ISpatialAudioObjectRenderStream::EndUpdatingAudioObjects の呼び出しの間)で GetBuffer が呼び出されなかった場合、SetEndOfStream はシステムによって暗黙的に呼び出されます。
また、音声オブジェクトのリソースが利用できなくなった場合、レンダリングエンジンは音声オブジェクトを非アクティブ化し、IsActive を false に設定します。この場合、オブジェクトが非アクティブ化される前に ISpatialAudioObjectRenderStreamNotify を介して通知が送信されます。ISpatialAudioObjectRenderStream::BeginUpdatingAudioObjects の availableDynamicObjectCount パラメーターで返される値は、各パスで処理されるオブジェクトの数を示します。
ISpatialAudioObject が表す音声オブジェクトの種類を指定する値を取得します。
| audioObjectType | AudioObjectType* | out | 表される音声オブジェクトの種類を指定する値です。 |
戻り値
メソッドが成功した場合は S_OK を返します。
解説(Remarks)
音声オブジェクトの種類は、ISpatialAudioObjectRenderStream::ActivateSpatialAudioObject メソッドの type パラメーターで設定します。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_ISpatialAudioObjectBase "{CCE0B8F2-8D4D-4EFB-A8CF-3D6ECF1C30E0}" #usecom global ISpatialAudioObjectBase IID_ISpatialAudioObjectBase "{}" #comfunc global ISpatialAudioObjectBase_GetBuffer 3 var,var #comfunc global ISpatialAudioObjectBase_SetEndOfStream 4 int #comfunc global ISpatialAudioObjectBase_IsActive 5 var #comfunc global ISpatialAudioObjectBase_GetAudioObjectType 6 var ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。#define global IID_ISpatialAudioObjectBase "{CCE0B8F2-8D4D-4EFB-A8CF-3D6ECF1C30E0}" #usecom global ISpatialAudioObjectBase IID_ISpatialAudioObjectBase "{}" #comfunc global ISpatialAudioObjectBase_GetBuffer 3 sptr,sptr #comfunc global ISpatialAudioObjectBase_SetEndOfStream 4 int #comfunc global ISpatialAudioObjectBase_IsActive 5 sptr #comfunc global ISpatialAudioObjectBase_GetAudioObjectType 6 sptr ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。