IAudioClient3

COM

IID7ed4ee07-8e67-4cd4-8c1a-2b7a5987ad42継承元IAudioClient2自前メソッド開始 vtbl18

公式ドキュメント

IAudioClient3 インターフェイスは IAudioClient2 インターフェイスから派生したもので、Windows Audio Session API (WASAPI) のオーディオクライアントが、オーディオエンジンがサポートする周期性および現在の周期性を照会したり、指定した周期性で共有オーディオストリームの初期化を要求したりできるようにする一連の追加メソッドを備えています。

メソッド 3

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

vtbl 18 HRESULT GetSharedModeEnginePeriod(WAVEFORMATEX* pFormat, DWORD* pDefaultPeriodInFrames, DWORD* pFundamentalPeriodInFrames, DWORD* pMinPeriodInFrames, DWORD* pMaxPeriodInFrames)

指定したストリーム形式に対してエンジンがサポートする周期性の範囲を返します。

pFormat	WAVEFORMATEX*	in	サポートされる周期性を照会する対象のストリーム形式。
pDefaultPeriodInFrames	DWORD*	out	オーディオサンプルを転送するために、エンジンがクライアントを起こす既定の周期。
pFundamentalPeriodInFrames	DWORD*	out	オーディオサンプルを転送するために、エンジンがクライアントを起こす基本周期。オーディオエンジンの周期性を設定する際には、この値の整数倍を使用する必要があります。
pMinPeriodInFrames	DWORD*	out	オーディオサンプルを転送するために、オーディオエンジンがクライアントを起こす最短の周期(オーディオフレーム単位)。
pMaxPeriodInFrames	DWORD*	out	オーディオサンプルを転送するために、オーディオエンジンがクライアントを起こす最長の周期(オーディオフレーム単位)。

戻り値

型: HRESULT

このメソッドは、正常に完了したことを示すために S_OK を返します。それ以外の場合は、適切なエラーコードを返します。

解説(Remarks)

オーディオクライアントは、IAudioClient3::InitializeSharedAudioStream の PeriodInFrames パラメーターを使用して、オーディオエンジンに特定の周期性を要求します。PeriodInFrames の値は、pFundamentalPeriodInFrames パラメーターで返された値の整数倍でなければなりません。また、PeriodInFrames は pMinPeriodInFrames で返された値以上、pMaxPeriodInFrames の値以下でなければなりません。

たとえば、44100 kHz 形式の場合、GetSharedModeEnginePeriod は次のような値を返すことがあります。

pDefaultPeriodInFrames = 448 フレーム(約 10.16 ミリ秒)
pFundamentalPeriodInFrames = 4 フレーム(約 0.09 ミリ秒)
pMinPeriodInFrames = 48 フレーム(約 1.09 ミリ秒)
pMaxPeriodInFrames = 448 フレーム(既定値と同じ)

この場合、InitializeSharedAudioStream の PeriodInFrames パラメーターに指定できる値には 48 や 448 が含まれます。また、96 や 128 なども含まれます。

一方、4(許容される最小値より小さい)、98(基本周期の倍数ではない)、1000(許容される最大値より大きい)は含まれません。

vtbl 19 HRESULT GetCurrentSharedModeEnginePeriod(WAVEFORMATEX** ppFormat, DWORD* pCurrentPeriodInFrames)

オーディオエンジンの現在の形式と周期性を返します。

ppFormat	WAVEFORMATEX**	out	オーディオエンジンが現在使用しているデバイス形式。
pCurrentPeriodInFrames	DWORD*	out	オーディオエンジンの現在の周期(オーディオフレーム単位)。

戻り値

型: HRESULT

このメソッドは、正常に完了したことを示すために S_OK を返します。それ以外の場合は、適切なエラーコードを返します。

解説(Remarks)

メモこのメソッドが返す値は瞬間的な値であり、たとえば別のオーディオクライアントが周期性や形式を異なる値に設定した場合など、呼び出しが返った直後に無効になることがあります。

メモこのメソッドによって設定された WAVEFORMATEX 構造体のメモリを解放するために、CoTaskMemFree を呼び出す責任は呼び出し元にあります。

vtbl 20 HRESULT InitializeSharedAudioStream(DWORD StreamFlags, DWORD PeriodInFrames, WAVEFORMATEX* pFormat, GUID* AudioSessionGuid)

指定した周期性で共有ストリームを初期化します。

StreamFlags	DWORD	in	ストリームの作成を制御するフラグ。クライアントはこのパラメーターに 0 を設定するか、サポートされている 1 つ以上の AUDCLNT_STREAMFLAGS_XXX 定数または AUDCLNT_SESSIONFLAGS_XXX 定数のビットごとの OR を設定します。このメソッドを使用する際に、このパラメーターでサポートされる AUDCLNT_STREAMFLAGS_XXX 定数は次のとおりです。 AUDCLNT_STREAMFLAGS_EVENTCALLBACK
PeriodInFrames	DWORD	in	クライアントが要求する周期性。この値は、IAudioClient3::GetSharedModeEnginePeriod の pFundamentalPeriodInFrames パラメーターで返された値の整数倍でなければなりません。また、PeriodInFrames は pMinPeriodInFrames で返された値以上、pMaxPeriodInFrames で返された値以下でなければなりません。
pFormat	WAVEFORMATEX*	in	形式記述子へのポインター。このパラメーターは、WAVEFORMATEX 型または WAVEFORMATEXTENSIBLE 型の有効な形式記述子を指している必要があります。詳細については、IAudioClient::Initialize の「解説」セクションを参照してください。
AudioSessionGuid	GUID*	inoptional	セッション GUID へのポインター。このパラメーターは、ストリームが属するオーディオセッションを識別する GUID 値を指します。GUID が以前に開かれたセッションを識別する場合、このメソッドはそのセッションにストリームを追加します。GUID が既存のセッションを識別しない場合、このメソッドは新しいセッションを開き、そのセッションにストリームを追加します。ストリームは、その存続期間中、同じセッションのメンバーであり続けます。このパラメーターに NULL を設定することは、GUID_NULL 値へのポインターを渡すことと同じです。

戻り値

型: HRESULT

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

戻り値	説明
AUDCLNT_E_ALREADY_INITIALIZED	IAudioClient オブジェクトは既に初期化されています。
AUDCLNT_E_WRONG_ENDPOINT_TYPE	AUDCLNT_STREAMFLAGS_LOOPBACK フラグが設定されていますが、エンドポイントデバイスがレンダリングデバイスではなくキャプチャデバイスです。
AUDCLNT_E_CPUUSAGE_EXCEEDED	プロセスパスの所要時間が最大 CPU 使用率を超えたことを示します。オーディオエンジンは、プロセスパスの所要時間が最大 CPU 使用率を超えた回数を保持することで CPU 使用率を追跡します。最大 CPU 使用率は、エンジンの周期性に対する割合として計算されます。この割合の値は、システムの CPU スロットル値(10% から 90% の範囲)です。この値が見つからない場合は、既定値の 40% を使用して最大 CPU 使用率が計算されます。
AUDCLNT_E_DEVICE_INVALIDATED	オーディオエンドポイントデバイスが取り外されたか、オーディオハードウェアまたは関連するハードウェアリソースが再構成、無効化、削除、あるいはその他の理由で使用できない状態になりました。
AUDCLNT_E_DEVICE_IN_USE	エンドポイントデバイスは既に使用中です。デバイスが排他モードで使用されているか、またはデバイスが共有モードで使用されている状態で呼び出し元が排他モードでの使用を要求しました。
AUDCLNT_E_ENGINE_FORMAT_LOCKED	クライアントが IAudioClient2::SetClientProperties の呼び出し時に AUDCLNT_STREAMOPTIONS_MATCH_FORMAT を指定しましたが、オーディオエンジンの形式が別のクライアントによってロックされています。この場合、match format オプションを指定せずに IAudioClient2::SetClientProperties を呼び出し、オーディオエンジンの現在の形式を使用できます。
AUDCLNT_E_ENGINE_PERIODICITY_LOCKED	クライアントが IAudioClient2::SetClientProperties の呼び出し時に AUDCLNT_STREAMOPTIONS_MATCH_FORMAT を指定しましたが、オーディオエンジンの周期性が別のクライアントによってロックされています。この場合、match format オプションを指定せずに IAudioClient2::SetClientProperties を呼び出し、オーディオエンジンの現在の周期性を使用できます。
AUDCLNT_E_ENDPOINT_CREATE_FAILED	レンダリングデバイスまたはキャプチャデバイスのオーディオエンドポイントの作成にメソッドが失敗しました。これは、オーディオエンドポイントデバイスが取り外されたか、オーディオハードウェアまたは関連するハードウェアリソースが再構成、無効化、削除、あるいはその他の理由で使用できない状態になった場合に発生することがあります。
AUDCLNT_E_INVALID_DEVICE_PERIOD	PeriodInFrames で指定された要求デバイス周期が、オーディオエンジンの基本周期性の整数倍ではないか、エンジンの最小周期より短いか、またはエンジンの最大周期より長いことを示します。エンジンがサポートする周期性の値は、IAudioClient3::GetSharedModeEnginePeriod を呼び出して取得してください。
AUDCLNT_E_UNSUPPORTED_FORMAT	オーディオエンジン(共有モード)またはオーディオエンドポイントデバイス(排他モード)が、指定された形式をサポートしていません。
AUDCLNT_E_SERVICE_NOT_RUNNING	Windows オーディオサービスが実行されていません。
E_POINTER	pFormat パラメーターが NULL です。
E_INVALIDARG	pFormat パラメーターが無効な形式記述を指しています。または、AUDCLNT_STREAMFLAGS_LOOPBACK フラグが設定されているのに ShareMode が AUDCLNT_SHAREMODE_SHARED と等しくありません。または、AUDCLNT_STREAMFLAGS_CROSSPROCESS フラグが設定されているのに ShareMode が AUDCLNT_SHAREMODE_EXCLUSIVE と等しくなっています。以前に SetClientProperties の呼び出しが、オーディオ/レンダリングストリームに対して無効なカテゴリで行われました。
E_OUTOFMEMORY	メモリ不足です。
AUDCLNT_E_RESOURCES_INVALIDATED	ストリームのリソースが無効化されました。このエラーは、次の理由でスローされることがあります。 - ストリームが中断されている。 - 排他ストリームまたはオフロードストリームが切断された。 - 排他モードまたはオフロードストリームを持つパッケージ化されたアプリケーションが休止状態になった。 - 「保護された出力」ストリームが閉じられた。

解説(Remarks)

IAudioClient::Initialize とは異なり、このメソッドではバッファーサイズを指定できません。バッファーサイズは、PeriodInFrames パラメーターで要求された周期性に基づいて計算されます。オーディオサンプルがバッファーに対して適時に入出力されるようにするのは、クライアントアプリの責任です。

オーディオクライアントは、IAudioClient3::GetSharedModeEnginePeriod を呼び出して、PeriodInFrames パラメーターに許容される値を確認する必要があります。PeriodInFrames の値は、pFundamentalPeriodInFrames パラメーターで返された値の整数倍でなければなりません。また、PeriodInFrames は pMinPeriodInFrames で返された値以上、pMaxPeriodInFrames の値以下でなければなりません。

たとえば、44100 kHz 形式の場合、GetSharedModeEnginePeriod は次のような値を返すことがあります。

pDefaultPeriodInFrames = 448 フレーム(約 10.16 ミリ秒)
pFundamentalPeriodInFrames = 4 フレーム(約 0.09 ミリ秒)
pMinPeriodInFrames = 48 フレーム(約 1.09 ミリ秒)
pMaxPeriodInFrames = 448 フレーム(既定値と同じ)

この場合、InitializeSharedAudioStream の PeriodInFrames パラメーターに指定できる値には 48 や 448 が含まれます。また、96 や 128 なども含まれます。

一方、4(許容される最小値より小さい)、98(基本周期の倍数ではない)、1000(許容される最大値より大きい)は含まれません。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IAudioClient3 "{7ED4EE07-8E67-4CD4-8C1A-2B7A5987AD42}"
#usecom global IAudioClient3 IID_IAudioClient3 "{}"
#comfunc global IAudioClient3_GetSharedModeEnginePeriod         18 var,var,var,var,var
#comfunc global IAudioClient3_GetCurrentSharedModeEnginePeriod  19 var,var
#comfunc global IAudioClient3_InitializeSharedAudioStream       20 int,int,var,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。#define global IID_IAudioClient3 "{7ED4EE07-8E67-4CD4-8C1A-2B7A5987AD42}"
#usecom global IAudioClient3 IID_IAudioClient3 "{}"
#comfunc global IAudioClient3_GetSharedModeEnginePeriod         18 sptr,sptr,sptr,sptr,sptr
#comfunc global IAudioClient3_GetCurrentSharedModeEnginePeriod  19 sptr,sptr
#comfunc global IAudioClient3_InitializeSharedAudioStream       20 int,int,sptr,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。