ホーム › Graphics.Direct2D › ID2D1Properties

ID2D1Properties

COM

IID483473d7-cd46-4f9d-9d3a-3112aa80159d継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

データ駆動型アプリケーションが Direct2D エフェクトの状態を変更できるようにする、実行時にバインド可能かつ検出可能なプロパティのセットを表します。

解説(Remarks)

このインターフェイスは、インデックスまたはプロパティ名のいずれかによるアクセスをサポートします。トップレベルのプロパティに加えて、ID2D1Properties オブジェクト内の各プロパティは、親プロパティを説明するメタデータを格納する ID2D1Properties オブジェクトを含む場合があります。

概要

ID2D1Properties インターフェイスは、エフェクトグラフのオーサリングツールやアニメーションシステムのようなデータ駆動型アプリケーションが Direct2D エフェクトの状態を変更できるようにする、実行時にバインド可能かつ検出可能なプロパティのセットを公開します。

このインターフェイスは、インデックスまたはプロパティ名のいずれかによるアクセスをサポートします。トップレベルのプロパティに加えて、ID2D1Properties 内の各プロパティは、その親プロパティを説明するメタデータを格納するサブ ID2D1Properties インターフェイスを含む場合があります。サブプロパティには、プロパティインデックスによってこのサブインターフェイスを要求するか、ドット (.) で区切られたプロパティ名文字列を使用してアクセスします。

このインターフェイスは、実行時の依存関係を避けるよう意図的に設計されています。すべての割り当ては API の呼び出し側が行い、VARIANT 型は使用されません。プロパティインターフェイスは一般に、アプリケーションが呼び出し手順を簡単に変更することでその状況を回避できる場合には、失敗を返さないように設計されています。たとえば、インスタンスがサポートするプロパティの数は GetPropertyCount メソッドによって返されるため、プロパティインデックスを受け取る他のメソッドは、プラグインエフェクトのプロパティシステムも使用しない限り、失敗を返しません。

このインターフェイスは主にインデックスベースのアクセスモデルに基づいており、プロパティ内の入れ子になったサブプロパティをサポートします。ディレクトリ構造とは異なり、プロパティ自体は値と型を持ち、オプションでサブプロパティをサポートする場合があります(ディレクトリはファイルではありません)。これらは通常、プロパティを説明するメタデータですが、オブジェクトの配列を指定するためにも使用されます。サブプロパティへのアクセスを簡素化し、名前ベースのアクセスを可能にするために、2 つのヘルパーメソッド – GetValueByName – が定義されています。これらは、サブプロパティを直接指定できるように「ドット」表記を使用します。たとえば次のようになります。

alphaMode = pEffect->GetValueByName<UINT32>(L"Inputs.0.AlphaMode");

または:

pEffect->SetValueByName<UINT32>(
            L"Inputs.0.AlphaMode", 
            DXGI_ALPHA_MODE_PREMULTIPLIED);

標準エフェクトプロパティ

プロパティ名/インデックス	プロパティ型	プロパティの説明
CLSID / D2D1_PROPERTY_CLSID	D2D1_PROPERTY_TYPE_CLSID	エフェクトの CLSID。
DisplayName / D2D1_PROPERTY_DISPLAYNAME	D2D1_PROPERTY_TYPE_STRING	エフェクトの表示可能なローカライズされた名前。
Author / D2D1_PROPERTY_AUTHOR	D2D1_PROPERTY_TYPE_STRING	エフェクトの作者。
Category / D2D1_PROPERTY_CATEGORY	D2D1_PROPERTY_TYPE_STRING	エフェクトのカテゴリ。
Description / D2D1_PROPERTY_DESCRIPTION	D2D1_PROPERTY_TYPE_STRING	エフェクトの説明。
Inputs / D2D1_PROPERTY_INPUTS	D2D1_PROPERTY_TYPE_ARRAY Note この配列の要素は D2D1_PROPERTY_TYPE_STRING 型です。	エフェクトの入力の名前の配列。配列の各要素は、入力の名前を指定するローカライズされた文字列です。

標準サブプロパティ

以下は、メタデータのアクセスに使用できる標準サブプロパティであり、システムプロパティとカスタムプロパティの両方で利用できる場合があります。詳細については、D2D1_SUBPROPERTY および D2D1_PROPERTY_TYPE 列挙型を参照してください。

プロパティ名/インデックス	プロパティ型	プロパティの説明
DisplayName / D2D1_SUBPROPERTY_DISPLAYNAME	D2D1_PROPERTY_TYPE_STRING	親プロパティの表示可能なローカライズされた名前。このサブプロパティは、すべてのトップレベルプロパティに存在します。
IsReadOnly / D2D1_SUBPROPERTY_ISREADONLY	D2D1_PROPERTY_TYPE_BOOL	親プロパティに書き込めるかどうかを示す値。このサブプロパティは、すべてのトップレベルプロパティに存在します。
Default / D2D1_SUBPROPERTY_DEFAULT	親プロパティと同じ。	プロパティのデフォルト値。このサブプロパティは、すべてのプロパティにオプションで存在します。
Min / D2D1_SUBPROPERTY_MIN	親プロパティと同じ。 Note 数値型のプロパティにのみ適用されます。	親プロパティに設定できる最小値。
Max / D2D1_SUBPROPERTY_MAX	親プロパティと同じ。 Note 数値型のプロパティにのみ適用されます。	親プロパティに設定できる最大値。
Fields / D2D1_SUBPROPERTY_FIELDS	Array / D2D1_PROPERTY_TYPE_ARRAY Note 親プロパティが Enum 型の場合にのみ適用されます。	親プロパティに設定できる有効な値のセット。この配列の各値は、名前とインデックスのペアです。インデックスは親に設定でき、名前は UI での使用を目的としたローカライズされた値です。詳細については、次のセクションを参照してください。

配列型サブプロパティ

詳細については、ID2D1Properties::GetType および D2D1_PROPERTY_TYPE を参照してください。プロパティ型が D2D1_PROPERTY_TYPE_ARRAY の場合、プロパティの値は配列要素の数を持つ UINT と見なされます。次のサブプロパティは、インデックスを要求されたプロパティ値に直接マッピングします。たとえば次のようになります。

Inputs: UINT32 – 2
        Inputs.0 : <Type> – 最初の入力
        Inputs.1 : <Type> – 2 番目の入力

上記の例では、ARRAY 型のプロパティに現れる次のサブプロパティを使用しています。番号付きのプロパティはシステムプロパティではなく、通常の (0x0 – 0x80000000) 範囲にあることに注意してください。

プロパティ名	プロパティインデックス	プロパティの説明
Property.0	0	プロパティ配列の最初の要素。
...	...	...
Property.N	N	プロパティ配列の N 番目の要素。

各サブ要素の型は、配列の型と同じになります。上記の例では、これは文字列の配列でした。

列挙型サブプロパティ

プロパティが D2D1_PROPERTY_TYPE_ENUM 型の場合、プロパティは対応する列挙値を持ちます。配列サブプロパティの一般的な規則に従い、名前と値のペアで構成されるフィールドのサブ配列が存在します。たとえば次のようになります。

PixelFormat: ENUM – ピクセルフォーマットの値
        PixelFormat.Fields: UINT32 – フィールドの数
        PixelFormat.Fields.0:String – 最初の列挙の名前
        PixelFormat.Fields.0.Index: UINT32 – 列挙の値。

上記の例では、次のサブプロパティを使用しています。詳細については、D2D1_SUBPROPERTY および D2D1_PROPERTY_TYPE 列挙型を参照してください。

プロパティ名	プロパティインデックス	プロパティの説明
Property.Fields	D2D1_SUBPROPERTY_FIELDS	列挙内の各フィールドに関する情報を提供する配列型のプロパティ。
Property.Fields.N	N	N 番目の列挙値の名前を提供する配列要素。
Property.Fields.N.Index	D2D1_SUBPROPERTY_INDEX	N 番目の列挙値に対応するインデックス。

メソッド 11

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

vtbl 3 DWORD GetPropertyCount()

トップレベルプロパティの数を取得します。

戻り値

型: UINT32

このメソッドは、オブジェクトがアクセスできるカスタム(非システム)プロパティの数を返します。

解説(Remarks)

このメソッドは、ID2D1Properties インターフェイス上のカスタムプロパティの数を返します。システムプロパティとサブプロパティは閉じたセットの一部であり、この閉じたセットを反復処理することで列挙できます。

vtbl 4 HRESULT GetPropertyName(DWORD index, LPWSTR name, DWORD nameCount)

index	DWORD	in	プロパティのインデックス。
name	LPWSTR	out	プロパティ名を受け取るワイド文字バッファ。
nameCount	DWORD	in	nameバッファの文字数(終端含む)。

vtbl 5 DWORD GetPropertyNameLength(DWORD index)

index

DWORD

プロパティのインデックス。

vtbl 6 D2D1_PROPERTY_TYPE GetType(DWORD index)

index

DWORD

プロパティのインデックス。

vtbl 7 DWORD GetPropertyIndex(LPWSTR name)

指定されたプロパティ名に対応するインデックスを取得します。

name

LPWSTR

取得するプロパティの名前。

戻り値

型: UINT32

対応するプロパティ名のインデックス。

解説(Remarks)

プロパティが存在しない場合、このメソッドは D2D1_INVALID_PROPERTY_INDEX を返します。この予約値は有効なインデックスにマッピングされることはなく、プロパティインターフェイスの他の部分から NULL またはセンチネル値が返される原因となります。

vtbl 8 HRESULT SetValueByName(LPWSTR name, D2D1_PROPERTY_TYPE type, BYTE* data, DWORD dataSize)

name	LPWSTR	in	値を設定する対象プロパティ名へのワイド文字ポインタ。
type	D2D1_PROPERTY_TYPE	in	設定する値のデータ型を指定する列挙値。
data	BYTE*	in	設定する値のバイト列へのポインタ。
dataSize	DWORD	in	dataのバイト数。

vtbl 9 HRESULT SetValue(DWORD index, D2D1_PROPERTY_TYPE type, BYTE* data, DWORD dataSize)

index	DWORD	in	値を設定するプロパティのインデックス。
type	D2D1_PROPERTY_TYPE	in	設定する値のデータ型を指定する列挙値。
data	BYTE*	in	設定する値のバイト列へのポインタ。
dataSize	DWORD	in	dataのバイト数。

vtbl 10 HRESULT GetValueByName(LPWSTR name, D2D1_PROPERTY_TYPE type, BYTE* data, DWORD dataSize)

name	LPWSTR	in	値を取得する対象プロパティ名へのワイド文字ポインタ。
type	D2D1_PROPERTY_TYPE	in	取得する値のデータ型を指定する列挙値。
data	BYTE*	out	取得した値を受け取るバイトバッファ。
dataSize	DWORD	in	dataバッファのバイト数。

vtbl 11 HRESULT GetValue(DWORD index, D2D1_PROPERTY_TYPE type, BYTE* data, DWORD dataSize)

index	DWORD	in	値を取得するプロパティのインデックス。
type	D2D1_PROPERTY_TYPE	in	取得する値のデータ型を指定する列挙値。
data	BYTE*	out	取得した値を受け取るバイトバッファ。
dataSize	DWORD	in	dataバッファのバイト数。

vtbl 12 DWORD GetValueSize(DWORD index)

index

DWORD

サイズを取得するプロパティのインデックス。

vtbl 13 HRESULT GetSubProperties(DWORD index, ID2D1Properties** subProperties)

index	DWORD	in	サブプロパティを取得する親プロパティのインデックス。
subProperties	ID2D1Properties**	out	サブプロパティ集合を受け取る出力ポインタ。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_ID2D1Properties "{483473D7-CD46-4F9D-9D3A-3112AA80159D}"
#usecom global ID2D1Properties IID_ID2D1Properties "{}"
#comfunc global ID2D1Properties_GetPropertyCount       3
#comfunc global ID2D1Properties_GetPropertyName        4 int,var,int
#comfunc global ID2D1Properties_GetPropertyNameLength  5 int
#comfunc global ID2D1Properties_GetType                6 int
#comfunc global ID2D1Properties_GetPropertyIndex       7 wstr
#comfunc global ID2D1Properties_SetValueByName         8 wstr,int,var,int
#comfunc global ID2D1Properties_SetValue               9 int,int,var,int
#comfunc global ID2D1Properties_GetValueByName         10 wstr,int,var,int
#comfunc global ID2D1Properties_GetValue               11 int,int,var,int
#comfunc global ID2D1Properties_GetValueSize           12 int
#comfunc global ID2D1Properties_GetSubProperties       13 int,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_ID2D1Properties "{483473D7-CD46-4F9D-9D3A-3112AA80159D}"
#usecom global ID2D1Properties IID_ID2D1Properties "{}"
#comfunc global ID2D1Properties_GetPropertyCount       3
#comfunc global ID2D1Properties_GetPropertyName        4 int,sptr,int
#comfunc global ID2D1Properties_GetPropertyNameLength  5 int
#comfunc global ID2D1Properties_GetType                6 int
#comfunc global ID2D1Properties_GetPropertyIndex       7 wstr
#comfunc global ID2D1Properties_SetValueByName         8 wstr,int,sptr,int
#comfunc global ID2D1Properties_SetValue               9 int,int,sptr,int
#comfunc global ID2D1Properties_GetValueByName         10 wstr,int,sptr,int
#comfunc global ID2D1Properties_GetValue               11 int,int,sptr,int
#comfunc global ID2D1Properties_GetValueSize           12 int
#comfunc global ID2D1Properties_GetSubProperties       13 int,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。