ISpatialAudioMetadataWriter
COM公式ドキュメント
対応するオーディオフレームの範囲内に配置された空間オーディオメタデータ項目を格納するためのメソッドを提供します。
メソッド 4
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
ISpatialAudioMetadataItems オブジェクトを書き込み用に開きます。
| metadataItems | ISpatialAudioMetadataItems* | in | 書き込み用に開く ISpatialAudioMetadataItems オブジェクトへのポインター。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合、返される可能性のあるコードには、次の表に示す値が含まれますが、これらに限定されません。
| 戻り値 | 説明 |
|---|---|
| 指定された ISpatialAudioMetadataItems に対して、オブジェクトの作成後、または最後に Close を呼び出して以降、すでに Open が呼び出されています。 | |
| 指定されたポインターが有効ではありません。 |
指定されたオフセット位置に新しいメタデータ項目を開始します。
| frameOffset | WORD | in | ActivateSpatialAudioMetadataItems の frameCount パラメーターで指定された範囲内における、項目のフレームオフセット。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合、返される可能性のあるコードには、次の表に示す値が含まれますが、これらに限定されません。
| 戻り値 | 説明 |
|---|---|
| ISpatialAudioMetadataItems が Open の呼び出しによって書き込み用に開かれていないか、Close の呼び出しによって書き込み用に閉じられています。 | |
|
書き込みセッションで書き込まれた項目数が、ISpatialAudioClient::ActivateSpatialAudioStream に渡された SpatialAudioObjectRenderStreamForMetadataActivationParam の MaxMetadataItemCount フィールドで指定された値を超えています。
frameCount の値が ActivateSpatialAudioMetadataItems の frameCount パラメーターの値を超えており、かつオーバーフローモードが SpatialAudioMetadataWriterOverflow_Fail に設定されています。 |
|
| frameOffset の値が、同一の書き込みセッション内での直前の WriteNextItem の呼び出しで指定された値より大きくありません。 |
解説(Remarks)
WriteNextItem を呼び出す前に、オブジェクトの作成後、および Close が呼び出された後に、Open を呼び出して ISpatialAudioMetadataWriter を書き込み用に開く必要があります。Open と Close の呼び出しで区切られる書き込みセッション中は、frameOffset パラメーターの値は直前の呼び出しでの値より大きくなければなりません。
単一の書き込みセッション内で、ISpatialAudioClient::ActivateSpatialAudioStream に渡された SpatialAudioObjectRenderStreamForMetadataActivationParam の MaxMetadataItemCount フィールドで指定された値を超える数の項目を WriteNextItem で書き込んではいけません。超えた場合、SPTLAUD_MD_CLNT_E_FRAMEOFFSET_OUT_OF_RANGE エラーが発生します。
オーバーフローモードが SpatialAudioMetadataWriterOverflow_Fail に設定されている場合、frameOffset パラメーターの値は ActivateSpatialAudioMetadataItems の frameCount パラメーターの値より小さくなければなりません。そうでない場合、SPTLAUD_MD_CLNT_E_FRAMEOFFSET_OUT_OF_RANGE エラーが発生します。
WriteNextItem を呼び出した後、WriteNextItemCommand を呼び出して、項目のメタデータコマンドと値データを書き込みます。
現在の項目にメタデータコマンドと値データを書き込みます。
| commandID | BYTE | in | オブジェクトのメタデータ形式でサポートされるコマンド。コマンドがメタデータ形式で定義されていない場合、この呼び出しは失敗します。各コマンドは項目ごとに一度だけ書き込むことができます。 |
| valueBuffer | void* | inoptional | メタデータ形式定義で指定されたコマンド固有のデータを格納するバッファーへのポインター。 |
| valueBufferLength | DWORD | in | valueBuffer パラメーターで指定されたコマンドデータのサイズ (バイト単位)。このサイズはメタデータ形式で指定されたコマンド定義と一致していなければならず、そうでない場合は呼び出しが失敗します。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合、返される可能性のあるコードには、次の表に示す値が含まれますが、これらに限定されません。
| 戻り値 | 説明 |
|---|---|
| ISpatialAudioMetadataItems が Open の呼び出しによって書き込み用に開かれていないか、Close の呼び出しによって書き込み用に閉じられています。 | |
|
Open の呼び出し後、WriteNextItemCommand の呼び出し前に WriteNextItem が呼び出されていません。 |
解説(Remarks)
WriteNextItemCommand を呼び出す前に、Open を呼び出して ISpatialAudioMetadataWriter を書き込み用に開き、WriteNextItem を呼び出して現在のメタデータ項目のオフセットを設定する必要があります。
メタデータバッファーに対して必要な操作を完了し、指定された ISpatialAudioMetadataItems オブジェクトを解放します。
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合、返される可能性のあるコードには、次の表に示す値が含まれますが、これらに限定されません。
| 戻り値 | 説明 |
|---|---|
| 指定された ISpatialAudioMetadataItems が Open の呼び出しによって開かれていません。 | |
| 指定された ISpatialAudioMetadataItems にメタデータ項目が書き込まれていません。 | |
| 指定された ISpatialAudioMetadataItems にメタデータコマンドが書き込まれていません。 |
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_ISpatialAudioMetadataWriter "{1B17CA01-2955-444D-A430-537DC589A844}"
#usecom global ISpatialAudioMetadataWriter IID_ISpatialAudioMetadataWriter "{}"
#comfunc global ISpatialAudioMetadataWriter_Open 3 sptr
#comfunc global ISpatialAudioMetadataWriter_WriteNextItem 4 int
#comfunc global ISpatialAudioMetadataWriter_WriteNextItemCommand 5 int,sptr,int
#comfunc global ISpatialAudioMetadataWriter_Close 6
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。