ISpatialAudioMetadataReader
COM公式ドキュメント
ISpatialAudioMetadataItems オブジェクトから空間オーディオのメタデータ項目、および項目のコマンドと値のペアを抽出するためのメソッドを提供します。
メソッド 4
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
ISpatialAudioMetadataItems オブジェクトを読み取り用に開きます。
| metadataItems | ISpatialAudioMetadataItems* | in | 読み取り用に開く ISpatialAudioMetadataItems オブジェクトへのポインター。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合、戻り値には次の表に示す値が含まれますが、これらに限定されません。
| 戻り値 | 説明 |
|---|---|
| 指定した ISpatialAudioMetadataItems に対して、オブジェクトの作成以降、または最後に Close を呼び出して以降、すでに Open が呼び出されています。 | |
| 指定されたポインターが無効です。 |
読み取り中のメタデータ項目について、コマンドの数とサンプルオフセットを取得します。
| commandCount | BYTE* | out | 読み取り中のメタデータ項目に含まれるコマンド／値のペアの数を受け取ります。 |
| frameOffset | WORD* | out | 読み取り中のメタデータ項目に関連付けられたフレームオフセットを取得します。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合、戻り値には次の表に示す値が含まれますが、これらに限定されません。
| 戻り値 | 説明 |
|---|---|
| ISpatialAudioMetadataItems が Open の呼び出しによって読み取り用に開かれていないか、Close の呼び出しによって書き込み用に閉じられています。 | |
| ReadItemCountInFrames の呼び出しで指定したフレーム範囲内に、これ以上メタデータ項目がありません。 | |
| 指定されたポインターのいずれかが無効です。 |
解説(Remarks)
ReadNextItem を呼び出す前に、オブジェクトの作成後、および Close が呼び出された後に、Open を呼び出して ISpatialAudioMetadataReader を読み取り用に開く必要があります。また、ReadNextItem を呼び出す前に ReadItemCountInFrames も呼び出す必要があります。
ISpatialAudioMetadataReader は、リーダーが関連付けられている ISpatialAudioMetadataItems が保持するフレームの全範囲内での現在位置を指す内部ポインターを保持します。このメソッドを呼び出すたびに、ポインターは readFrameCount パラメーターで指定されたフレーム数だけ前進します。
コマンドおよび関連する値を読み取る処理は再帰的です。ReadItemCountInFrames を呼び出すたびに、ReadNextItem を呼び出して次の項目に含まれるコマンドの数を取得します。ReadNextItem を呼び出すたびに、ReadNextItemCommand を呼び出して、その項目の各コマンドを読み取ります。ISpatialAudioMetadataItems のフレーム範囲全体を読み取り終えるまで、この処理を繰り返します。
現在の項目のメタデータコマンドと値データを読み取ります。
| commandID | BYTE* | out | 現在のコマンドのコマンド ID を受け取ります。 |
| valueBuffer | void* | out | メタデータ形式の定義で指定された、コマンド固有のデータを受け取るバッファーへのポインター。すべてのコマンドを確実に取得できるようにするため、バッファーのサイズは少なくとも maxValueBufferLength 以上である必要があります。 |
| maxValueBufferLength | DWORD | in | コマンド値の最大サイズ。 |
| valueBufferLength | DWORD* | out | valueBuffer パラメーターに書き込まれたデータのサイズ (バイト単位)。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合、戻り値には次の表に示す値が含まれますが、これらに限定されません。
| 戻り値 | 説明 |
|---|---|
| ISpatialAudioMetadataItems が Open の呼び出しによって読み取り用に開かれていないか、Close の呼び出しによって書き込み用に閉じられています。 | |
| 指定されたポインターのいずれかが無効です。 |
解説(Remarks)
ReadNextItem を呼び出す前に、オブジェクトの作成後、および Close が呼び出された後に、Open を呼び出して ISpatialAudioMetadataReader を読み取り用に開く必要があります。また、ReadNextItem を呼び出す前に ReadItemCountInFrames を呼び出し、続いて ReadNextItem を呼び出す必要があります。
ISpatialAudioMetadataReader は、リーダーが関連付けられている ISpatialAudioMetadataItems が保持するフレームの全範囲内での現在位置を指す内部ポインターを保持します。このメソッドを呼び出すたびに、ポインターは readFrameCount パラメーターで指定されたフレーム数だけ前進します。
コマンドおよび関連する値を読み取る処理は再帰的です。ReadItemCountInFrames を呼び出すたびに、ReadNextItem を呼び出して次の項目に含まれるコマンドの数を取得します。ReadNextItem を呼び出すたびに、ReadNextItemCommand を呼び出して、その項目の各コマンドを読み取ります。ISpatialAudioMetadataItems のフレーム範囲全体を読み取り終えるまで、この処理を繰り返します。
SpatialAudioMetadataItems オブジェクトに対して必要な操作を完了し、オブジェクトを解放します。(ISpatialAudioMetadataReader.Close)
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合、戻り値には次の表に示す値が含まれますが、これらに限定されません。
| 戻り値 | 説明 |
|---|---|
| ISpatialAudioMetadataItems が Open の呼び出しによって読み取り用に開かれていないか、Close の呼び出しによって書き込み用に閉じられています。 |
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_ISpatialAudioMetadataReader "{B78E86A2-31D9-4C32-94D2-7DF40FC7EBEC}" #usecom global ISpatialAudioMetadataReader IID_ISpatialAudioMetadataReader "{}" #comfunc global ISpatialAudioMetadataReader_Open 3 sptr #comfunc global ISpatialAudioMetadataReader_ReadNextItem 4 var,var #comfunc global ISpatialAudioMetadataReader_ReadNextItemCommand 5 var,sptr,int,var #comfunc global ISpatialAudioMetadataReader_Close 6 ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_ISpatialAudioMetadataReader "{B78E86A2-31D9-4C32-94D2-7DF40FC7EBEC}" #usecom global ISpatialAudioMetadataReader IID_ISpatialAudioMetadataReader "{}" #comfunc global ISpatialAudioMetadataReader_Open 3 sptr #comfunc global ISpatialAudioMetadataReader_ReadNextItem 4 sptr,sptr #comfunc global ISpatialAudioMetadataReader_ReadNextItemCommand 5 sptr,sptr,int,sptr #comfunc global ISpatialAudioMetadataReader_Close 6 ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。