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

IAudioMeterInformation

COM
📘 Microsoft Learn (日本語) · English
IIDc02216f6-8c67-4b5b-9d00-d008e73e0064継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

IAudioMeterInformation インターフェースは、オーディオ エンドポイント デバイスとの間のオーディオ ストリーム上のピーク メーターを表します。

メソッド 4

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

vtbl 3 HRESULT GetPeakValue(FLOAT* pfPeak)

GetPeakValue メソッドは、オーディオ ストリーム内のチャネルのピーク サンプル値を取得します。

pfPeakFLOAT*outfloat 変数へのポインター。このメソッドは、この変数にオーディオ ストリームのピーク サンプル値を書き込みます。ピーク値は 0.0 から 1.0 までの正規化された範囲の数値です。

戻り値

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

リターン コード 説明
E_POINTER
 パラメーター pfPeak が NULL です。

解説(Remarks)

このメソッドは、ストリーム内のすべてのチャネルにわたって記録されたピーク サンプル値を取得します。各チャネルのピーク値は 1 つのデバイス期間にわたって記録され、その次のデバイス期間中に利用可能になります。したがって、このメソッドは常に前のデバイス期間中に記録されたピーク値を取得します。デバイス期間を取得するには、IAudioClient::GetDevicePeriod メソッドを呼び出します。

GetPeakValue メソッドを使用するコード例については、「ピーク メーター」をご覧ください。

vtbl 4 HRESULT GetMeteringChannelCount(DWORD* pnChannelCount)

GetMeteringChannelCount メソッドは、ピーク メーターによって監視されるオーディオ ストリーム内のチャネル数を取得します。

pnChannelCountDWORD*outUINT 変数へのポインター。このメソッドは、この変数にチャネル数を書き込みます。

戻り値

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

リターン コード 説明
E_POINTER
 パラメーター pnChannelCount が NULL です。
vtbl 5 HRESULT GetChannelsPeakValues(DWORD u32ChannelCount, FLOAT* afPeakValues)

GetChannelsPeakValues メソッドは、オーディオ ストリーム内のすべてのチャネルのピーク サンプル値を取得します。

u32ChannelCountDWORDinチャネル数。このパラメーターは、afPeakValues 配列の要素数も指定します。指定した数がストリーム内のチャネル数と一致しない場合、このメソッドはエラー コード E_INVALIDARG を返します。
afPeakValuesFLOAT*outピーク サンプル値の配列へのポインター。このメソッドは、この配列に各チャネルのピーク値を書き込みます。配列には、ストリーム内のチャネルごとに 1 つの要素が含まれます。ピーク値は 0.0 から 1.0 までの正規化された範囲の数値です。

戻り値

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

リターン コード 説明
E_INVALIDARG
 パラメーター u32ChannelCount がオーディオ ストリーム内のチャネル数と一致しません。
E_POINTER
 パラメーター afPeakValues が NULL です。

解説(Remarks)

このメソッドは、ストリーム内の各チャネルのピーク サンプル値を取得します。各チャネルのピーク値は 1 つのデバイス期間にわたって記録され、その次のデバイス期間中に利用可能になります。したがって、このメソッドは常に前のデバイス期間中に記録されたピーク値を取得します。デバイス期間を取得するには、IAudioClient::GetDevicePeriod メソッドを呼び出します。

パラメーター afPeakValues は、呼び出し元が割り当てた float 配列を指します。ストリームに n 個のチャネルが含まれる場合、チャネルには 0 から n– 1 までの番号が付けられます。このメソッドは、各チャネルのピーク値を、チャネル番号と一致する配列インデックスの要素に格納します。ピーク メーターによって監視されるオーディオ ストリーム内のチャネル数を取得するには、IAudioMeterInformation::GetMeteringChannelCount メソッドを呼び出します。

vtbl 6 HRESULT QueryHardwareSupport(DWORD* pdwHardwareSupportMask)

QueryHardwareSupport メソッドは、オーディオ エンドポイント デバイスに対して、ハードウェアでサポートされている機能を照会します。(IAudioMeterInformation.QueryHardwareSupport)

pdwHardwareSupportMaskDWORD*outDWORD 変数へのポインター。このメソッドは、この変数にオーディオ エンドポイント デバイスのハードウェア機能を示すハードウェア サポート マスクを書き込みます。このメソッドは、マスクを 0、または 1 つ以上の ENDPOINT_HARDWARE_SUPPORT_XXX 定数のビットごとの OR の組み合わせに設定できます。

戻り値

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

リターン コード 説明
E_POINTER
 パラメーター pdwHardwareSupportMask が NULL です。

解説(Remarks)

このメソッドは、オーディオ エンドポイント デバイスが次の機能をハードウェアで実装しているかどうかを示します。

上記の一覧のうち、エンドポイント デバイスがハードウェアで実装していない機能については、システムが自動的にソフトウェア実装で代替します。
出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IAudioMeterInformation "{C02216F6-8C67-4B5B-9D00-D008E73E0064}"
#usecom global IAudioMeterInformation IID_IAudioMeterInformation "{}"
#comfunc global IAudioMeterInformation_GetPeakValue             3 var
#comfunc global IAudioMeterInformation_GetMeteringChannelCount  4 var
#comfunc global IAudioMeterInformation_GetChannelsPeakValues    5 int,var
#comfunc global IAudioMeterInformation_QueryHardwareSupport     6 var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。