ホーム › Media.Audio › IPerChannelDbLevel

IPerChannelDbLevel

COM

📘 Microsoft Learn (日本語) · English

IIDc2f8e001-f205-4bc9-99bc-c13b1e048ccb継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

IPerChannelDbLevel インターフェイスは、オーディオストリーム、またはオーディオストリーム内の周波数帯域について、音量レベル(デシベル単位)をチャネルごとに制御する汎用サブユニット制御インターフェイスを表します。

メソッド 6

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

vtbl 3 HRESULT GetChannelCount(DWORD* pcChannels)

GetChannelCount メソッドは、オーディオストリーム内のチャネル数を取得します。(IPerChannelDbLevel.GetChannelCount)

pcChannels

DWORD*

out

メソッドがチャネル数(オーディオストリーム内のチャネルの数)を書き込む UINT 変数へのポインター。

戻り値

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

戻り値	説明
E_POINTER	ポインター pcChannels が NULL です。

vtbl 4 HRESULT GetLevelRange(DWORD nChannel, FLOAT* pfMinLevelDB, FLOAT* pfMaxLevelDB, FLOAT* pfStepping)

GetLevelRange メソッドは、指定したチャネルの音量レベルの範囲(デシベル単位)を取得します。

nChannel	DWORD	in	選択したチャネルの番号。オーディオストリームが n 個のチャネルを持つ場合、チャネルは 0 から n– 1 までの番号が付けられます。ストリーム内のチャネル数を取得するには、IPerChannelDbLevel::GetChannelCount メソッドを呼び出します。
pfMinLevelDB	FLOAT*	out	メソッドが最小音量レベル(デシベル単位)を書き込む float 変数へのポインター。
pfMaxLevelDB	FLOAT*	out	メソッドが最大音量レベル(デシベル単位)を書き込む float 変数へのポインター。
pfStepping	FLOAT*	out	メソッドが、pfMinLevelDB から pfMaxLevelDB までの範囲における連続する音量レベル間のステップ値を書き込む float 変数へのポインター。最大音量レベルと最小音量レベルの差が d デシベルで、その範囲が n ステップ(均等な間隔)に分割されている場合、音量は n + 1 個の離散レベルを取ることができ、連続するレベル間のステップの大きさは d / n デシベルとなります。

戻り値

戻り値	説明
E_INVALIDARG	パラメーター nChannel が範囲外です。
E_POINTER	ポインター pfminLevelDB、pfmaxLevelDB、または pfmaxLevelDB が NULL です。

vtbl 5 HRESULT GetLevel(DWORD nChannel, FLOAT* pfLevelDB)

GetLevel メソッドは、指定したチャネルの音量レベル(デシベル単位)を取得します。

nChannel	DWORD	in	チャネル番号。オーディオストリームが N 個のチャネルを持つ場合、チャネルは 0 から N– 1 までの番号が付けられます。ストリーム内のチャネル数を取得するには、IPerChannelDbLevel::GetChannelCount メソッドを呼び出します。
pfLevelDB	FLOAT*	out	メソッドが、指定したチャネルの音量レベル(デシベル単位)を書き込む float 変数へのポインター。

戻り値

戻り値	説明
E_INVALIDARG	パラメーター nChannel が範囲外です。
E_POINTER	ポインター pfLevelDB が NULL です。

vtbl 6 HRESULT SetLevel(DWORD nChannel, FLOAT fLevelDB, GUID* pguidEventContext)

SetLevel メソッドは、指定したチャネルの音量レベル(デシベル単位)を設定します。

nChannel	DWORD	in	選択したチャネルの番号。オーディオストリームが N 個のチャネルを持つ場合、チャネルは 0 から N– 1 までの番号が付けられます。ストリーム内のチャネル数を取得するには、IPerChannelDbLevel::GetChannelCount メソッドを呼び出します。
fLevelDB	FLOAT	in	新しい音量レベル(デシベル単位)。正の値はゲインを表し、負の値は減衰を表します。
pguidEventContext	GUID*	inoptional	IControlChangeNotify::OnNotify メソッドのコンテキスト値。このパラメーターはイベントコンテキスト GUID を指します。SetLevel の呼び出しがレベルコントロールの状態を変更した場合、そのコントロールに対して IControlChangeNotify インターフェイスを登録しているすべてのクライアントが通知を受け取ります。OnNotify メソッドの実装内で、クライアントはイベントコンテキスト GUID を調べることで、自身とほかのクライアントのどちらがコントロール変更イベントの発生源であるかを判別できます。呼び出し元がこのパラメーターに NULL ポインターを指定した場合、クライアントの通知メソッドは NULL のコンテキストポインターを受け取ります。

戻り値

戻り値	説明
E_INVALIDARG	パラメーター nChannel が範囲外です。
E_OUTOFMEMORY	メモリ不足です。

解説(Remarks)

呼び出し元が fLevelDB にステップ値と正確に一致する値を指定した場合、SetLevel メソッドは正常に完了します。その後の IPerChannelDbLevel::GetLevel メソッドの呼び出しは、設定された値、または次のいずれかの値を返します。

設定値が最小値を下回っていた場合、GetLevel メソッドは最小値を返します。
設定値が最大値を上回っていた場合、GetLevel メソッドは最大値を返します。
設定値が 2 つのステップ値の間にあった場合、GetLevel メソッドは、設定値の 1 つ上のステップ値または 1 つ下のステップ値のいずれかとなり得る値を返します。設定値から隣接する各ステップ値までの相対的な距離は関係ありません。GetLevel メソッドが返す値は、信号経路への影響がより大きい方の値です。

vtbl 7 HRESULT SetLevelUniform(FLOAT fLevelDB, GUID* pguidEventContext)

SetLevelUniform メソッドは、オーディオストリーム内のすべてのチャネルを同一の均一な音量レベル(デシベル単位)に設定します。

fLevelDB	FLOAT	in	新しい均一なレベル(デシベル単位)。
pguidEventContext	GUID*	inoptional	IControlChangeNotify::OnNotify メソッドのコンテキスト値。このパラメーターはイベントコンテキスト GUID を指します。SetLevelUniform の呼び出しがレベルコントロールの状態を変更した場合、そのコントロールに対して IControlChangeNotify インターフェイスを登録しているすべてのクライアントが通知を受け取ります。OnNotify メソッドの実装内で、クライアントはイベントコンテキスト GUID を調べることで、自身とほかのクライアントのどちらがコントロール変更イベントの発生源であるかを判別できます。呼び出し元がこのパラメーターに NULL ポインターを指定した場合、クライアントの通知メソッドは NULL のコンテキストポインターを受け取ります。

戻り値

戻り値	説明
E_OUTOFMEMORY	メモリ不足です。

解説(Remarks)

指定した均一なレベルが、特定のチャネルについて IPerChannelDbLevel::GetLevelRange メソッドが報告する範囲を超えている場合、SetLevelUniform の呼び出しはそのチャネルの値をサポートされる範囲にクランプし、正常に完了します。その後の IPerChannelDbLevel::GetLevel メソッドの呼び出しにより、そのチャネルに実際に使用された値を取得できます。

vtbl 8 HRESULT SetLevelAllChannels(FLOAT* aLevelsDB, DWORD cChannels, GUID* pguidEventContext)

SetLevelAllChannels メソッドは、オーディオストリーム内のすべてのチャネルの音量レベル(デシベル単位)を設定します。

aLevelsDB	FLOAT*	in	音量レベルの配列へのポインター。このパラメーターは、メソッドがすべてのチャネルの新しい音量レベル(デシベル単位)を書き込む、呼び出し元が割り当てた float 配列を指します。メソッドは、特定のチャネルのレベルを、そのチャネル番号に一致するインデックスの配列要素に書き込みます。オーディオストリームが n 個のチャネルを含む場合、チャネルは 0 から n– 1 までの番号が付けられます。ストリーム内のチャネル数を取得するには、IPerChannelDbLevel::GetChannelCount メソッドを呼び出します。
cChannels	DWORD	in	aLevelsDB 配列内の要素数。このパラメーターがオーディオストリーム内のチャネル数と一致しない場合、メソッドは aLevelsDB 配列を変更せずに失敗します。
pguidEventContext	GUID*	inoptional	IControlChangeNotify::OnNotify メソッドのコンテキスト値。このパラメーターはイベントコンテキスト GUID を指します。SetLevelAllChannels の呼び出しがレベルコントロールの状態を変更した場合、そのコントロールに対して IControlChangeNotify インターフェイスを登録しているすべてのクライアントが通知を受け取ります。OnNotify メソッドの実装内で、クライアントはイベントコンテキスト GUID を調べることで、自身とほかのクライアントのどちらがコントロール変更イベントの発生源であるかを判別できます。呼び出し元がこのパラメーターに NULL ポインターを指定した場合、クライアントの通知メソッドは NULL のコンテキストポインターを受け取ります。

戻り値

戻り値	説明
E_INVALIDARG	パラメーター cChannels がチャネル数と一致しません。
E_POINTER	ポインター aLevelsDB が NULL です。
E_OUTOFMEMORY	メモリ不足です。

解説(Remarks)

いずれかのチャネルについて指定したレベル値が、そのチャネルに対して IPerChannelDbLevel::GetLevelRange メソッドが報告する範囲を超えている場合、SetLevelAllChannels の呼び出しはその値をサポートされる範囲にクランプし、正常に完了します。その後の IPerChannelDbLevel::GetLevel メソッドの呼び出しにより、そのチャネルに実際に使用された値を取得できます。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IPerChannelDbLevel "{C2F8E001-F205-4BC9-99BC-C13B1E048CCB}"
#usecom global IPerChannelDbLevel IID_IPerChannelDbLevel "{}"
#comfunc global IPerChannelDbLevel_GetChannelCount      3 var
#comfunc global IPerChannelDbLevel_GetLevelRange        4 int,var,var,var
#comfunc global IPerChannelDbLevel_GetLevel             5 int,var
#comfunc global IPerChannelDbLevel_SetLevel             6 int,float,var
#comfunc global IPerChannelDbLevel_SetLevelUniform      7 float,var
#comfunc global IPerChannelDbLevel_SetLevelAllChannels  8 var,int,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。#define global IID_IPerChannelDbLevel "{C2F8E001-F205-4BC9-99BC-C13B1E048CCB}"
#usecom global IPerChannelDbLevel IID_IPerChannelDbLevel "{}"
#comfunc global IPerChannelDbLevel_GetChannelCount      3 sptr
#comfunc global IPerChannelDbLevel_GetLevelRange        4 int,sptr,sptr,sptr
#comfunc global IPerChannelDbLevel_GetLevel             5 int,sptr
#comfunc global IPerChannelDbLevel_SetLevel             6 int,float,sptr
#comfunc global IPerChannelDbLevel_SetLevelUniform      7 float,sptr
#comfunc global IPerChannelDbLevel_SetLevelAllChannels  8 sptr,int,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。