ホーム › Graphics.CompositionSwapchain › IPresentationManager

IPresentationManager

COM

📘 Microsoft Learn (日本語) · English

IIDfb562f82-6292-470a-88b1-843661e7f20c継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

プレゼンテーションを管理するためのメソッドを定義します。

メソッド 13

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

vtbl 3 HRESULT AddBufferFromResource(IUnknown* resource, IPresentationBuffer** presentationBuffer)

resource	IUnknown*	in	提示バッファの元となるグラフィックスリソース(テクスチャ等)へのポインタ。
presentationBuffer	IPresentationBuffer**	out	生成された提示バッファIPresentationBufferを受け取る出力ポインタ。

vtbl 4 HRESULT CreatePresentationSurface(HANDLE compositionSurfaceHandle, IPresentationSurface** presentationSurface)

ビジュアルツリーにホストして単一のフロントバッファーを割り当てることができるコンテンツに対して、プレゼンテーションサーフェスを作成します。

compositionSurfaceHandle	HANDLE	in	プレゼンテーションサーフェスをバインドするコンポジションサーフェスへのハンドル。
presentationSurface	IPresentationSurface**	out	作成されたプレゼンテーションサーフェス。

戻り値

Type: HRESULT

関数が成功した場合は S_OK を返します。それ以外の場合は、エラーを示す HRESULT 値を返します。

vtbl 5 ULONGLONG GetNextPresentId()

次のプレゼントの識別子を取得します。そのプレゼントを参照する際、すべての同期フェンスがこの値までシグナル状態にされます。

戻り値

Type: UINT64

次のプレゼントの識別子。

vtbl 6 HRESULT SetTargetTime(SystemInterruptTime targetTime)

次のプレゼントの目標時刻を設定します。

targetTime

SystemInterruptTime

次のプレゼントの目標時刻。

戻り値

Type: HRESULT

関数が成功した場合は S_OK を返します。それ以外の場合は、エラーを示す HRESULT 値を返します。

解説(Remarks)

システムは、指定された時刻にできる限り近いタイミングでプレゼントを表示しようとします。

このパラメーター設定は、複数のプレゼントにわたって保持されます。

vtbl 7 HRESULT SetPreferredPresentDuration(SystemInterruptTime preferredDuration, SystemInterruptTime deviationTolerance)

推奨フレーム期間を設定します。

preferredDuration	SystemInterruptTime	in	要求する期間(割り込み時間単位)。
deviationTolerance	SystemInterruptTime	in	許容される公差。サポートされているシステム期間と `preferredDuration` パラメーターとの差の大きさが `deviationTolerance` パラメーター内に収まっている場合、そのシステム期間が使用されます。

戻り値

Type: HRESULT

関数が成功した場合は S_OK を返します。それ以外の場合は、エラーを示す HRESULT 値を返します。

解説(Remarks)

推奨フレーム期間は、指定されたフレームレートで出力をリフレッシュすることが望ましいというヒントとしてシステムに使用されることを意図しています。このレート、またはその倍数をサポートするディスプレイは、適切であればそのモードに設定されます。

このパラメーター設定は、複数のプレゼントにわたって保持されます。

vtbl 8 HRESULT ForceVSyncInterrupt(BYTE forceVsyncInterrupt)

プレゼントが表示される際に GPU が常に VSync 割り込みを発行すべきかどうかを示す値を設定します。

forceVsyncInterrupt BYTE in 常に VSync 割り込みを発行する場合は TRUE、それ以外の場合は FALSE。

戻り値

Type: HRESULT

関数が成功した場合は S_OK を返します。それ以外の場合は、エラーを示す HRESULT 値を返します。

解説(Remarks)

ハードウェアフリップキューをサポートするシステムを活用するために、プレゼントは CPU の関与なしに GPU が完全に処理できます。これには省電力の利点がありますが、一方で、バッファー利用可能イベント、プレゼントリタイアフェンス、およびプレゼント統計が、プレゼントが表示された時点で即座に更新されず、代わりに GPU が独立して実行した処理について定期的に CPU を更新する際に、かなり遅れて更新される可能性があることも意味します。

アプリケーションは、即座のフィードバックを必要としない特定のプレゼントについて、それぞれが表示される際に GPU が VSync 割り込みを発行すべきかどうかを明示的に制御することで、この動作に参加させることができます。発行しない場合、そのようなプレゼントはフィードバックの遅延と引き換えに電力効率が向上します。

既定では、プレゼントは常に VSync 割り込みを強制します。アプリケーションは、このメソッドを呼び出すことで、一部のプレゼントに VSync 割り込みを強制しないことを許可できます。システムがハードウェアフリップキューをサポートしていない場合、この設定に関係なく、すべてのプレゼントが VSync 割り込みを発行して CPU を更新します。

このパラメーター設定は、複数のプレゼントにわたって保持されます。

vtbl 9 HRESULT Present()

このプレゼンテーションマネージャーをプレゼントします。

戻り値

Type: HRESULT

関数が成功した場合は S_OK を返します。それ以外の場合は、エラーを示す HRESULT 値を返します。

解説(Remarks)

プレゼンテーションマネージャーがロスト状態になっている場合、この呼び出しは PRESENTATION_ERROR_LOST を返します。アプリケーションがこのエラーを受け取った場合は、このプレゼンテーションマネージャーを破棄して新しいものを作成する必要があります。

vtbl 10 HRESULT GetPresentRetiringFence(GUID* riid, void** fence)

プレゼントがリタイアする際にシグナルを発するフェンスを取得します。

riid	GUID*	in	クエリ対象のインターフェイスのインターフェイス識別子 (IID) への参照。
fence	void**	out	`riid` パラメーターで指定された IID を持つインターフェイスへのポインターのアドレス。

戻り値

Type: HRESULT

関数が成功した場合は S_OK を返します。それ以外の場合は、エラーを示す HRESULT 値を返します。

解説(Remarks)

このフェンスは、各プレゼントがリタイアを開始したとき(つまり、後続のプレゼントがその代わりとしてキューに入れられたとき)に、そのプレゼントの Present ID までシグナル状態にされます。

vtbl 11 HRESULT CancelPresentsFrom(ULONGLONG presentIdToCancelFrom)

以前に発行され、まだ処理中で表示されておらず、Present ID が渡された presentIdToCancelFrom 以上であるすべてのプレゼントをキャンセルします。

presentIdToCancelFrom

ULONGLONG

発行済みでまだ表示されていないプレゼントのキャンセルを開始する起点となるプレゼントの識別子。

戻り値

Type: HRESULT

関数が成功した場合は S_OK を返します。それ以外の場合は、エラーを示す HRESULT 値を返します。

解説(Remarks)

過去のプレゼントが既に表示されている場合、この呼び出しは失敗しません。それらのプレゼントは単にキャンセルされないだけです。プレゼントがキャンセルされる場合、それらは現在表示されているプレゼントに影響を与えず、リタイアプロセスを開始させることもないため、キャンセルされたプレゼントに対してプレゼントリタイアフェンスがシグナル状態にされることはありません。このため、プレゼントの実行後、アプリケーションはバッファー利用可能イベントをクエリして、キャンセル後の最初のプレゼントで発行するための利用可能なバッファーを見つけることが推奨されます。そのプレゼントがキューに入れられると、以前に表示されていたプレゼントがリタイアプロセスを開始し、プレゼントリタイアフェンスをシグナル状態にできるようになります。

vtbl 12 HRESULT GetLostEvent(HANDLE* lostEventHandle)

プレゼンテーションマネージャーが回復不能なエラーに遭遇したときにシグナルを発するイベントへのハンドルを取得します。

lostEventHandle

HANDLE*

out

イベントへのハンドル。

戻り値

Type: HRESULT

関数が成功した場合は S_OK を返します。それ以外の場合は、エラーを示す HRESULT 値を返します。

解説(Remarks)

返されるイベントは、プレゼンテーションマネージャーが回復不能なエラーに遭遇したときにシグナル状態になります。この場合、アプリケーションはこのプレゼンテーションマネージャーを解放し、新しいものを作成する必要があります。

アプリケーションはこのイベントを待機したりクエリしたりできますが、その状態を変更することはできません。このイベントはプレゼンテーションマネージャーが制御します。

vtbl 13 HRESULT GetPresentStatisticsAvailableEvent(HANDLE* presentStatisticsAvailableEventHandle)

プレゼント統計がレポート可能になったときにシグナルを発するイベントへのハンドルを取得します。

presentStatisticsAvailableEventHandle

HANDLE*

out

イベントへのハンドル。

戻り値

Type: HRESULT

関数が成功した場合は S_OK を返します。それ以外の場合は、エラーを示す HRESULT 値を返します。

解説(Remarks)

返されるイベントを閉じる責任は呼び出し元にあります。

vtbl 14 HRESULT EnablePresentStatisticsKind(PresentStatisticsKind presentStatisticsKind, BYTE enabled)

指定したプレゼント統計の種類を有効または無効にします。

presentStatisticsKind	PresentStatisticsKind	in	有効または無効にするプレゼント統計の種類。
enabled	BYTE	in	プレゼント統計の種類を有効にする場合は `TRUE`、それ以外の場合は `FALSE`。

戻り値

Type: HRESULT

関数が成功した場合は S_OK を返します。それ以外の場合は、エラーを示す HRESULT 値を返します。

解説(Remarks)

要求された変更はできる限り速やかに反映されますが、効果が遅延する場合があります。プレゼントを発行する前に必要なすべてのプレゼント統計を登録し、使用中は変更しないことを推奨します。これは、後方互換性を損なうことなく、将来的に統計を拡張・変更できるようにするための方法でもあります。

vtbl 15 HRESULT GetNextPresentStatistics(IPresentStatistics** nextPresentStatistics)

キュー内の次のプレゼント統計項目を取得します。

nextPresentStatistics IPresentStatistics** out キュー内の次のプレゼント統計項目へのポインター。キューが空の場合は nullptr。

戻り値

Type: HRESULT

関数が成功した場合は S_OK を返します。それ以外の場合は、エラーを示す HRESULT 値を返します。

解説(Remarks)

プレゼント統計キューが空の場合、エラーは返されません。代わりに、出力パラメーターに nullptr が返されます。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IPresentationManager "{FB562F82-6292-470A-88B1-843661E7F20C}"
#usecom global IPresentationManager IID_IPresentationManager "{}"
#comfunc global IPresentationManager_AddBufferFromResource               3 sptr,sptr
#comfunc global IPresentationManager_CreatePresentationSurface           4 sptr,sptr
#comfunc global IPresentationManager_GetNextPresentId                    5
#comfunc global IPresentationManager_SetTargetTime                       6 int
#comfunc global IPresentationManager_SetPreferredPresentDuration         7 int,int
#comfunc global IPresentationManager_ForceVSyncInterrupt                 8 int
#comfunc global IPresentationManager_Present                             9
#comfunc global IPresentationManager_GetPresentRetiringFence             10 var,sptr
#comfunc global IPresentationManager_CancelPresentsFrom                  11 int64
#comfunc global IPresentationManager_GetLostEvent                        12 sptr
#comfunc global IPresentationManager_GetPresentStatisticsAvailableEvent  13 sptr
#comfunc global IPresentationManager_EnablePresentStatisticsKind         14 int,int
#comfunc global IPresentationManager_GetNextPresentStatistics            15 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IPresentationManager "{FB562F82-6292-470A-88B1-843661E7F20C}"
#usecom global IPresentationManager IID_IPresentationManager "{}"
#comfunc global IPresentationManager_AddBufferFromResource               3 sptr,sptr
#comfunc global IPresentationManager_CreatePresentationSurface           4 sptr,sptr
#comfunc global IPresentationManager_GetNextPresentId                    5
#comfunc global IPresentationManager_SetTargetTime                       6 int
#comfunc global IPresentationManager_SetPreferredPresentDuration         7 int,int
#comfunc global IPresentationManager_ForceVSyncInterrupt                 8 int
#comfunc global IPresentationManager_Present                             9
#comfunc global IPresentationManager_GetPresentRetiringFence             10 sptr,sptr
#comfunc global IPresentationManager_CancelPresentsFrom                  11 int64
#comfunc global IPresentationManager_GetLostEvent                        12 sptr
#comfunc global IPresentationManager_GetPresentStatisticsAvailableEvent  13 sptr
#comfunc global IPresentationManager_EnablePresentStatisticsKind         14 int,int
#comfunc global IPresentationManager_GetNextPresentStatistics            15 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。