ホーム › Graphics.Direct2D › ID2D1SpriteBatch

ID2D1SpriteBatch

COM

IID4dc583bf-3a10-438a-8722-e9765224f1f1継承元ID2D1Resource自前メソッド開始 vtbl4

公式ドキュメント

関連する描画プロパティを持つ、スプライトの単一グループを表します。

解説(Remarks)

新しいスプライトバッチは ID2D1DeviceContext3::CreateSpriteBatch を使用して作成します。描画するには ID2D1DeviceContext3::DrawSpriteBatch を使用します。

スプライトは、アプリが多数の画像を非常に効率的に描画するための手段です。一般的には、2D ゲームでキャラクターや背景を描画したり、煙や炎などのパーティクルシステムを描画したりするために使用されます。アプリにパフォーマンス上の要求があり、フレームごとに数百から数千の画像を描画する必要がある場合は、汎用の DrawImage メソッドの代わりに、スプライトバッチとそれが提供するきめ細かな制御を活用することを検討してください。

メソッド 5

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

vtbl 4 HRESULT AddSprites(DWORD spriteCount, D2D_RECT_F* destinationRectangles, D2D_RECT_U* sourceRectangles, D2D1_COLOR_F* colors, D2D_MATRIX_3X2_F* transforms, DWORD destinationRectanglesStride, DWORD sourceRectanglesStride, DWORD colorsStride, DWORD transformsStride)

指定したスプライトをこのスプライトバッチの末尾に追加します。

spriteCount	DWORD	in	追加するスプライトの数。これにより、Direct2D が各配列を何ストライド分読み取るかが決まります。
destinationRectangles	D2D_RECT_F*	in	スプライトを描画先のデバイスコンテキスト上のどこに描画するかを指定する、描画先矩形の配列へのポインター。
sourceRectangles	D2D_RECT_U*	inoptional	スプライトとして描画するソースビットマップの領域を指定する、ソース矩形の配列へのポインター。 null 値または InfiniteRectU が割り当てられたスプライトについては、Direct2D はソースビットマップ全体を使用します。このパラメーターを完全に省略するか null 値に設定した場合、Direct2D は追加されるすべてのスプライトにソースビットマップ全体を使用します。
colors	D2D1_COLOR_F*	inoptional	各スプライトに適用する色の配列へのポインター。出力色は、ソースビットマップの色と指定した色を成分ごとに乗算した結果です。出力色はクランプされません。 null 値が割り当てられたスプライトの色は、Direct2D によって変更されません。このパラメーターを完全に省略するか null 値に設定した場合、 Direct2D は追加されるスプライトの色を一切変更しません。
transforms	D2D_MATRIX_3X2_F*	inoptional	各スプライトの描画先矩形に適用する変換の配列へのポインター。 null 値が割り当てられたスプライトの描画先矩形は、Direct2D によって変換されません。このパラメーターを完全に省略するか null 値に設定した場合、 Direct2D は追加されるスプライトの描画先矩形を一切変換しません。
destinationRectanglesStride	DWORD	in	destinationRectangles 配列内の各矩形間の距離をバイト単位で指定します。ストライドに 0 を指定すると、追加されるすべてのスプライトに同じ描画先矩形が使用されます。
sourceRectanglesStride	DWORD	in	sourceRectangles 配列(指定されている場合)内の各矩形間の距離をバイト単位で指定します。ストライドに 0 を指定すると、追加されるすべてのスプライトに同じソース矩形が使用されます。
colorsStride	DWORD	in	colors 配列(指定されている場合)内の各色間の距離をバイト単位で指定します。ストライドに 0 を指定すると、追加されるすべてのスプライトに同じ色が使用されます。
transformsStride	DWORD	in	transforms 配列(指定されている場合)内の各変換間の距離をバイト単位で指定します。ストライドに 0 を指定すると、追加されるすべてのスプライトに同じ変換が使用されます。

戻り値

Type: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

Direct2D では、スプライトは 4 つのプロパティ、すなわち描画先矩形、ソース矩形、色、変換によって定義されます。描画先矩形は必須ですが、残りのプロパティは省略可能です。

Note 使用しないプロパティは、常に省略するか null 値を渡してください。これにより、Direct2D はそれらのプロパティの値を格納せずに済み、その処理を完全にスキップできるため、描画速度が向上します。たとえば、500 個のスプライトからなるバッチがあり、そのいずれの描画先矩形も変換したくないとします。単位行列の配列を渡す代わりに、transforms パラメーターを単に省略してください。これにより、Direct2D は変換を一切格納せずに済み、最速の描画パフォーマンスが得られます。一方、バッチ内のいずれかのスプライトにあるプロパティの値が設定されている場合、Direct2D は内部的にそのプロパティ配列用の領域を確保し、すべてのスプライトにそのプロパティの値(たとえ既定値であっても)を割り当てる必要があります。

vtbl 5 HRESULT SetSprites(DWORD startIndex, DWORD spriteCount, D2D_RECT_F* destinationRectangles, D2D_RECT_U* sourceRectangles, D2D1_COLOR_F* colors, D2D_MATRIX_3X2_F* transforms, DWORD destinationRectanglesStride, DWORD sourceRectanglesStride, DWORD colorsStride, DWORD transformsStride)

このスプライトバッチ内の指定したスプライトのプロパティを更新します。

startIndex	DWORD	in	このスプライトバッチ内で更新する最初のスプライトのインデックス。
spriteCount	DWORD	in	新しいプロパティで更新するスプライトの数。これにより、Direct2D が各配列を何ストライド分読み取るかが決まります。
destinationRectangles	D2D_RECT_F*	inoptional	スプライトを描画先のデバイスコンテキスト上のどこに描画するかを指定する、描画先矩形の配列へのポインター。
sourceRectangles	D2D_RECT_U*	inoptional	スプライトとして描画するソースビットマップの領域を指定する、ソース矩形の配列へのポインター。 null 値または InfiniteRectU が割り当てられたスプライトについては、Direct2D はソースビットマップ全体を使用します。このパラメーターを完全に省略するか null 値に設定した場合、Direct2D は更新されるすべてのスプライトにソースビットマップ全体を使用します。
colors	D2D1_COLOR_F*	inoptional	各スプライトに適用する色の配列へのポインター。出力色は、ソースビットマップの色と指定した色を成分ごとに乗算した結果です。出力色はクランプされません。 null 値が割り当てられたスプライトの色は、Direct2D によって変更されません。このパラメーターを完全に省略するか null 値に設定した場合、 Direct2D は更新されるスプライトの色を一切変更しません。
transforms	D2D_MATRIX_3X2_F*	inoptional	各スプライトの描画先矩形に適用する変換の配列へのポインター。 null 値が割り当てられたスプライトの描画先矩形は、Direct2D によって変換されません。このパラメーターを完全に省略するか null 値に設定した場合、Direct2D は更新されるスプライトの描画先矩形を一切変換しません。
destinationRectanglesStride	DWORD	in	destinationRectangles 配列内の各矩形間の距離をバイト単位で指定します。ストライドに 0 を指定すると、更新されるすべてのスプライトに同じ描画先矩形が使用されます。
sourceRectanglesStride	DWORD	in	sourceRectangles 配列(指定されている場合)内の各矩形間の距離をバイト単位で指定します。ストライドに 0 を指定すると、更新されるすべてのスプライトに同じソース矩形が使用されます。
colorsStride	DWORD	in	colors 配列(指定されている場合)内の各色間の距離をバイト単位で指定します。ストライドに 0 を指定すると、更新されるすべてのスプライトに同じ色が使用されます。
transformsStride	DWORD	in	transforms 配列(指定されている場合)内の各変換間の距離をバイト単位で指定します。ストライドに 0 を指定すると、更新されるすべてのスプライトに同じ変換が使用されます。

戻り値

Type: HRESULT

成功した場合は S_OK を返します。無効な値がメソッドに渡された場合は E_INVALIDARG を返します。この場合、この SetSprites の呼び出しによってスプライトは一切変更されません。

vtbl 6 HRESULT GetSprites(DWORD startIndex, DWORD spriteCount, D2D_RECT_F* destinationRectangles, D2D_RECT_U* sourceRectangles, D2D1_COLOR_F* colors, D2D_MATRIX_3X2_F* transforms)

このスプライトバッチから、指定したスプライトのサブセットを取得します。最良のパフォーマンスを得るには、取得する必要のないプロパティには nullptr を使用してください。

startIndex	DWORD	in	このスプライトバッチ内で取得する最初のスプライトのインデックス。
spriteCount	DWORD	in	取得するスプライトの数。
destinationRectangles	D2D_RECT_F*	outoptional	このメソッドが返るときに、取得されたスプライトの描画先矩形を格納した配列へのポインターが格納されます。
sourceRectangles	D2D_RECT_U*	outoptional	このメソッドが返るときに、取得されたスプライトのソース矩形を格納した配列へのポインターが格納されます。ソース矩形が割り当てられていないスプライトについては、InfiniteRectU が返されます。
colors	D2D1_COLOR_F*	outoptional	このメソッドが返るときに、取得されたスプライトに適用される色を格納した配列へのポインターが格納されます。色が割り当てられていないスプライトについては、色 {1.0f, 1.0f, 1.0f, 1.0f} が返されます。
transforms	D2D_MATRIX_3X2_F*	outoptional	このメソッドが返るときに、取得されたスプライトに適用される変換を格納した配列へのポインターが格納されます。変換が割り当てられていないスプライトについては、単位行列が返されます。

戻り値

Type: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

vtbl 7 DWORD GetSpriteCount()

このスプライトバッチ内のスプライトの数を取得します。

戻り値

Type: UINT32

このスプライトバッチ内のスプライトの数を返します

vtbl 8 void Clear()

このスプライトバッチからすべてのスプライトを削除します。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_ID2D1SpriteBatch "{4DC583BF-3A10-438A-8722-E9765224F1F1}"
#usecom global ID2D1SpriteBatch IID_ID2D1SpriteBatch "{}"
#comfunc global ID2D1SpriteBatch_AddSprites      4 int,var,var,var,var,int,int,int,int
#comfunc global ID2D1SpriteBatch_SetSprites      5 int,int,var,var,var,var,int,int,int,int
#comfunc global ID2D1SpriteBatch_GetSprites      6 int,int,var,var,var,var
#comfunc global ID2D1SpriteBatch_GetSpriteCount  7
#comfunc global ID2D1SpriteBatch_Clear           8
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。#define global IID_ID2D1SpriteBatch "{4DC583BF-3A10-438A-8722-E9765224F1F1}"
#usecom global ID2D1SpriteBatch IID_ID2D1SpriteBatch "{}"
#comfunc global ID2D1SpriteBatch_AddSprites      4 int,sptr,sptr,sptr,sptr,int,int,int,int
#comfunc global ID2D1SpriteBatch_SetSprites      5 int,int,sptr,sptr,sptr,sptr,int,int,int,int
#comfunc global ID2D1SpriteBatch_GetSprites      6 int,int,sptr,sptr,sptr,sptr
#comfunc global ID2D1SpriteBatch_GetSpriteCount  7
#comfunc global ID2D1SpriteBatch_Clear           8
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。