ホーム › Media.Audio › ISpatialAudioObjectRenderStreamBase

ISpatialAudioObjectRenderStreamBase

COM

📘 Microsoft Learn (日本語) · English

IIDfeaaf403-c1d8-450d-aa05-e0ccee7502a8継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

空間オーディオオブジェクトのレンダーストリームを制御するためのメソッド(ストリームの開始、停止、リセットを含む)を提供する基底インターフェイスです。

メソッド 7

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

vtbl 3 HRESULT GetAvailableDynamicObjectCount(DWORD* value)

現在利用可能な動的空間オーディオオブジェクトの数を取得します。

value

DWORD*

out

現在利用可能な動的空間オーディオオブジェクトの数。

戻り値

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

解説(Remarks)

動的な ISpatialAudioObject とは、ActivateSpatialAudioObject メソッドの type パラメーターに AudioObjectType_Dynamic を設定してアクティブ化されたものを指します。システムには、同時にアクティブ化できる動的空間オーディオオブジェクトの最大数の制限があります。ISpatialAudioObject が使用されなくなった際には Release を呼び出してリソースを解放し、新しい動的空間オーディオオブジェクトを作成できるようにしてください。

ストリーミングの開始後にこのメソッドを呼び出すべきではありません。開始後は、この値が ISpatialAudioObjectRenderStreamBase::BeginUpdatingAudioObjects によって既に提供されるためです。このメソッドは、ISpatialAudioObjectRenderStreamBase::Start の呼び出し後に発生するストリーミングの開始前にのみ呼び出してください。

vtbl 4 HRESULT GetService(GUID* riid, void** service)

ISpatialAudioObjectRenderStream から追加のサービスを取得します。

戻り値	説明
SPTLAUDCLNT_E_DESTROYED	空間オーディオストリームに関連付けられた ISpatialAudioClient は破棄されています。
AUDCLNT_E_DEVICE_INVALIDATED	空間オーディオストリームに関連付けられたオーディオデバイスは、もはや有効ではありません。
AUDCLNT_E_DEVICE_INVALIDATED	オーディオエンドポイントデバイスが取り外されたか、オーディオハードウェアまたは関連するハードウェアリソースが再構成、無効化、削除、その他の理由で使用できなくなっています。
SPTLAUDCLNT_E_INTERNAL	内部エラーが発生しました。
AUDCLNT_E_UNSUPPORTED_FORMAT	空間オーディオストリームに関連付けられたメディアが、サポートされていない形式を使用しています。

riid

GUID*

要求するサービスのインターフェイス ID。クライアントはこのパラメーターに次の REFIID 値のいずれかを設定してください。

IID_IAudioClock

IID_IAudioClock2

IID_IAudioStreamVolume

service

void**

out

要求したインターフェイスのインスタンスのアドレスをメソッドが書き込むポインター変数へのポインター。このメソッドを通じて、呼び出し元はインターフェイスへの参照カウント付き参照を取得します。呼び出し元は、インターフェイスが不要になった際に、そのインターフェイスの Release メソッドを呼び出して解放する責任があります。GetService の呼び出しが失敗した場合、*ppv は NULL になります。

戻り値

戻り値	説明
E_POINTER	パラメーター ppv が NULL です。
SPTLAUDCLNT_E_DESTROYED	空間オーディオストリームに関連付けられた ISpatialAudioClient は破棄されています。
AUDCLNT_E_DEVICE_INVALIDATED	オーディオエンドポイントデバイスが取り外されたか、オーディオハードウェアまたは関連するハードウェアリソースが再構成、無効化、削除、その他の理由で使用できなくなっています。
SPTLAUDCLNT_E_INTERNAL	内部エラーが発生しました。
AUDCLNT_E_UNSUPPORTED_FORMAT	空間オーディオストリームに関連付けられたメディアが、サポートされていない形式を使用しています。

解説(Remarks)

GetService メソッドは次のサービスインターフェイスをサポートします。

vtbl 5 HRESULT Start()

空間オーディオストリームを開始します。

戻り値

戻り値	説明
SPTLAUDCLNT_E_STREAM_NOT_STOPPED	オーディオストリームが停止されていません。Stop を呼び出してストリームを停止してください。
SPTLAUDCLNT_E_DESTROYED	空間オーディオストリームに関連付けられた ISpatialAudioClient は破棄されています。
AUDCLNT_E_DEVICE_INVALIDATED	オーディオエンドポイントデバイスが取り外されたか、オーディオハードウェアまたは関連するハードウェアリソースが再構成、無効化、削除、その他の理由で使用できなくなっています。
SPTLAUDCLNT_E_INTERNAL	内部エラーが発生しました。
AUDCLNT_E_UNSUPPORTED_FORMAT	空間オーディオストリームに関連付けられたメディアが、サポートされていない形式を使用しています。

解説(Remarks)

ストリームを開始すると、エンドポイントバッファーとオーディオエンジンの間でデータフローが発生します。
このメソッドが初めて呼び出されたときは、ストリームのオーディオクロック位置は 0 になります。
それ以外の場合、クロックは Stop の呼び出しによってストリームが最後に一時停止された時点の位置から再開します。
クロック位置を 0 にリセットし、アクティブなすべての ISpatialAudioObject インスタンスを取り消すには、Reset を呼び出してください。

ストリームは事前に Stop の呼び出しによって停止されている必要があります。そうでない場合、このメソッドは失敗し、SPTLAUDCLNT_E_STREAM_NOT_STOPPED を返します。

vtbl 6 HRESULT Stop()

実行中のオーディオストリームを停止します。

戻り値

戻り値	説明
SPTLAUDCLNT_E_DESTROYED	空間オーディオストリームに関連付けられた ISpatialAudioClient は破棄されています。
AUDCLNT_E_DEVICE_INVALIDATED	オーディオエンドポイントデバイスが取り外されたか、オーディオハードウェアまたは関連するハードウェアリソースが再構成、無効化、削除、その他の理由で使用できなくなっています。
SPTLAUDCLNT_E_INTERNAL	内部エラーが発生しました。
AUDCLNT_E_UNSUPPORTED_FORMAT	空間オーディオストリームに関連付けられたメディアが、サポートされていない形式を使用しています。

解説(Remarks)

ストリームを停止すると、エンドポイントバッファーとオーディオエンジンの間のデータフローが停止します。
この操作はストリームの一時停止と見なすことができます。ストリームのオーディオクロックを現在のストリーム位置に残し、0 にリセットしないためです。その後 Start を呼び出すと、ストリームは現在の位置から実行を再開します。
クロック位置を 0 にリセットし、アクティブなすべての ISpatialAudioObject インスタンスを取り消すには、Reset を呼び出してください。

vtbl 7 HRESULT Reset()

停止したオーディオストリームをリセットします。

戻り値

戻り値	説明
SPTLAUDCLNT_E_STREAM_NOT_STOPPED	オーディオストリームが停止されていません。Stop を呼び出してストリームを停止してください。
SPTLAUDCLNT_E_DESTROYED	空間オーディオストリームに関連付けられた ISpatialAudioClient は破棄されています。
AUDCLNT_E_DEVICE_INVALIDATED	オーディオエンドポイントデバイスが取り外されたか、オーディオハードウェアまたは関連するハードウェアリソースが再構成、無効化、削除、その他の理由で使用できなくなっています。
SPTLAUDCLNT_E_INTERNAL	内部エラーが発生しました。
AUDCLNT_E_UNSUPPORTED_FORMAT	空間オーディオストリームに関連付けられたメディアが、サポートされていない形式を使用しています。

解説(Remarks)

オーディオストリームをリセットすると、保留中のすべてのデータがフラッシュされ、オーディオクロックのストリーム位置が 0 にリセットされます。ストリームをリセットすると、アクティブなすべての ISpatialAudioObject インスタンスも取り消されます。
その後 Start を呼び出すと、ストリームは 0 の位置から開始します。

vtbl 8 HRESULT BeginUpdatingAudioObjects(DWORD* availableDynamicObjectCount, DWORD* frameCountPerBuffer)

オーディオオブジェクトデータを処理のために送信でき、ISpatialAudioObject の状態を変更できる状態にシステムを移行させます。

availableDynamicObjectCount	DWORD*	out	現在の処理パスでレンダリングに利用可能な動的オーディオオブジェクトの数。割り当てられたすべての静的オーディオオブジェクトは各パスでレンダリングできます。オーディオオブジェクトの種類については、AudioObjectType を参照してください。
frameCountPerBuffer	DWORD*	out	GetBuffer によって返されるバッファーのサイズ(オーディオフレーム単位)。

戻り値

戻り値	説明
SPTLAUDCLNT_E_OUT_OF_ORDER	2 回の呼び出しの間に対応する EndUpdatingAudioObjects の呼び出しがないまま、BeginUpdatingAudioObjects が 2 回呼び出されました。
SPTLAUDCLNT_E_DESTROYED	空間オーディオストリームに関連付けられた ISpatialAudioClient は破棄されています。
AUDCLNT_E_DEVICE_INVALIDATED	オーディオエンドポイントデバイスが取り外されたか、オーディオハードウェアまたは関連するハードウェアリソースが再構成、無効化、削除、その他の理由で使用できなくなっています。
AUDCLNT_E_RESOURCES_INVALIDATED	空間オーディオストリームに関連付けられたリソースは、もはや有効ではありません。
SPTLAUDCLNT_E_INTERNAL	内部エラーが発生しました。
AUDCLNT_E_UNSUPPORTED_FORMAT	空間オーディオストリームに関連付けられたメディアが、サポートされていない形式を使用しています。

解説(Remarks)

このメソッドは、ISpatialAudioClient::ActivateSpatialAudioStream に SpatialAudioObjectRenderStreamActivationParams で渡されたイベントがシグナル状態になるたびに、送信するオーディオオブジェクトデータがない場合でも呼び出す必要があります。

各 BeginUpdatingAudioObjects の呼び出しには、対応する EndUpdatingAudioObjects の呼び出しが必要です。
BeginUpdatingAudioObjects が EndUpdatingAudioObjects の呼び出しを間に挟まずに 2 回呼び出された場合、2 回目の BeginUpdatingAudioObjects の呼び出しは SPTLAUDCLNT_E_OUT_OF_ORDER を返します。

vtbl 9 HRESULT EndUpdatingAudioObjects()

ActivateSpatialAudioObject でアクティブ化された空間オーディオオブジェクトへのオーディオデータの供給がアプリで完了したことをシステムに通知します。

戻り値

戻り値	説明
SPTLAUDCLNT_E_OUT_OF_ORDER	EndUpdatingAudioObjects が BeginUpdatingAudioObjects より前に呼び出されました。
SPTLAUDCLNT_E_DESTROYED	空間オーディオストリームに関連付けられた ISpatialAudioClient は破棄されています。
AUDCLNT_E_DEVICE_INVALIDATED	オーディオエンドポイントデバイスが取り外されたか、オーディオハードウェアまたは関連するハードウェアリソースが再構成、無効化、削除、その他の理由で使用できなくなっています。
AUDCLNT_E_RESOURCES_INVALIDATED	空間オーディオストリームに関連付けられたリソースは、もはや有効ではありません。
SPTLAUDCLNT_E_INTERNAL	内部エラーが発生しました。
AUDCLNT_E_UNSUPPORTED_FORMAT	空間オーディオストリームに関連付けられたメディアが、サポートされていない形式を使用しています。

解説(Remarks)

ISpatialAudioObjectBase::GetBuffer で取得したポインターは、このメソッドが呼び出された後は使用できなくなります。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_ISpatialAudioObjectRenderStreamBase "{FEAAF403-C1D8-450D-AA05-E0CCEE7502A8}"
#usecom global ISpatialAudioObjectRenderStreamBase IID_ISpatialAudioObjectRenderStreamBase "{}"
#comfunc global ISpatialAudioObjectRenderStreamBase_GetAvailableDynamicObjectCount  3 var
#comfunc global ISpatialAudioObjectRenderStreamBase_GetService                      4 var,sptr
#comfunc global ISpatialAudioObjectRenderStreamBase_Start                           5
#comfunc global ISpatialAudioObjectRenderStreamBase_Stop                            6
#comfunc global ISpatialAudioObjectRenderStreamBase_Reset                           7
#comfunc global ISpatialAudioObjectRenderStreamBase_BeginUpdatingAudioObjects       8 var,var
#comfunc global ISpatialAudioObjectRenderStreamBase_EndUpdatingAudioObjects         9
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_ISpatialAudioObjectRenderStreamBase "{FEAAF403-C1D8-450D-AA05-E0CCEE7502A8}"
#usecom global ISpatialAudioObjectRenderStreamBase IID_ISpatialAudioObjectRenderStreamBase "{}"
#comfunc global ISpatialAudioObjectRenderStreamBase_GetAvailableDynamicObjectCount  3 sptr
#comfunc global ISpatialAudioObjectRenderStreamBase_GetService                      4 sptr,sptr
#comfunc global ISpatialAudioObjectRenderStreamBase_Start                           5
#comfunc global ISpatialAudioObjectRenderStreamBase_Stop                            6
#comfunc global ISpatialAudioObjectRenderStreamBase_Reset                           7
#comfunc global ISpatialAudioObjectRenderStreamBase_BeginUpdatingAudioObjects       8 sptr,sptr
#comfunc global ISpatialAudioObjectRenderStreamBase_EndUpdatingAudioObjects         9
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。