ID2D1Properties interface (d2d1_1.h)
Represents a set of run-time bindable and discoverable properties that allow a data-driven application to modify the state of a Direct2D effect.
Inheritance
The ID2D1Properties interface inherits from the IUnknown interface. ID2D1Properties also has these types of members:
Methods
The ID2D1Properties interface has these methods.
| ID2D1Properties::GetPropertyCount Gets the number of top-level properties. |
| ID2D1Properties::GetPropertyIndex Gets the index corresponding to the given property name. |
| ID2D1Properties::GetPropertyName Gets the property name that corresponds to the given index. This is a template overload. See Remarks. |
| ID2D1Properties::GetPropertyName Gets the property name that corresponds to the given index. |
| ID2D1Properties::GetPropertyNameLength Gets the number of characters for the given property name. This is a template overload. See Remarks. |
| ID2D1Properties::GetPropertyNameLength Gets the number of characters for the given property name. |
| ID2D1Properties::GetSubProperties Gets the sub-properties of the provided property by index. This is a template overload. |
| ID2D1Properties::GetSubProperties Gets the sub-properties of the provided property by index. |
| ID2D1Properties::GetType Gets the D2D1_PROPERTY_TYPE of the selected property. This is a template overload. See Remarks. |
| ID2D1Properties::GetType Gets the D2D1_PROPERTY_TYPE of the selected property. |
| ID2D1Properties::GetValue Gets the value of the property by index. This is a template overload. See Remarks. (overload 1/2) |
| ID2D1Properties::GetValue Gets the value of the specified property by index. This is a template overload. See Remarks. |
| ID2D1Properties::GetValue Gets the value of the property by index. This is a template overload. See Remarks. (overload 2/2) |
| ID2D1Properties::GetValue Gets the value of the specified property by index. (overload 1/2) |
| ID2D1Properties::GetValue Gets the value of the specified property by index. (overload 2/2) |
| ID2D1Properties::GetValueByName Gets the property value by name. This is a template overload. See Remarks. (overload 2/2) |
| ID2D1Properties::GetValueByName Gets the property value by name. (overload 2/2) |
| ID2D1Properties::GetValueByName Gets the property value by name. (overload 1/2) |
| ID2D1Properties::GetValueByName Gets the property value by name. This is a template overload. See Remarks. (overload 1/2) |
| ID2D1Properties::GetValueSize Gets the size of the property value in bytes, using the property index. This is a template overload. See Remarks. |
| ID2D1Properties::GetValueSize Gets the size of the property value in bytes, using the property index. |
| ID2D1Properties::SetValue Sets the corresponding property by index. This is a template overload. (overload 2/2) |
| ID2D1Properties::SetValue Sets the corresponding property by index. This is a template overload. (overload 1/2) |
| ID2D1Properties::SetValue Sets the corresponding property by index. (overload 1/2) |
| ID2D1Properties::SetValue Sets the corresponding property by index. (overload 2/2) |
| ID2D1Properties::SetValueByName Sets the named property to the given value. (overload 1/2) |
| ID2D1Properties::SetValueByName Sets the named property to the given value. This is a template overload. See Remarks. |
| ID2D1Properties::SetValueByName Sets the named property to the given value. (overload 2/2) |
Remarks
This interface supports access through either indices or property names. In addition to top-level properties, each property in an ID2D1Properties object may contain an ID2D1Properties object, which stores metadata describing the parent property.
Overview
The ID2D1Properties interface exposes a set of run-time bindable and discoverable properties that allow a data-driven application such as an effect graph authoring tool or an animation system to modify the state of a Direct2D effect.The interface supports access through either indices or property names. In addition to top-level properties, each property in an ID2D1Properties may contain a sub-ID2D1Properties interface, which stores metadata describing its parent property. Sub-properties are accessed by requesting this sub-interface by property index, or by using a property name string separated by a dot (.).
The interface is intentionally designed to avoid dependencies on a run-time basis. All allocation is done by the caller of the API and VARIANT types are not used. The property interface generally is designed not to return failures where the application could trivially change their calling sequence in order to avoid the condition. For example, since the number of properties supported by the instance is returned by the GetPropertyCount method, other methods that take a property index do not return a failure, unless they also use the plug-in effect's property system.
The interface is primarily based upon an index-based access model, and it supports nested sub-properties within properties. Unlike a directory structure, the property itself has a value and a type and might optionally support sub-properties (directories are not files). These are normally metadata that describe the property, but, this is also used to specify arrays of objects. In order to simplify accessing sub-properties and to allow name-based access, two helper methods – GetValueByName – are defined. These use a "dotted" notation in order to allow sub-properties to be directly specified, for example:
alphaMode = pEffect->GetValueByName<UINT32>(L"Inputs.0.AlphaMode");
Or:
pEffect->SetValueByName<UINT32>(
L"Inputs.0.AlphaMode",
DXGI_ALPHA_MODE_PREMULTIPLIED);
Standard Effect Properties
| Property name/index | Property type | Property description |
|---|---|---|
| CLSID / D2D1_PROPERTY_CLSID | D2D1_PROPERTY_TYPE_CLSID | The CLSID of the effect. |
| DisplayName / D2D1_PROPERTY_DISPLAYNAME | D2D1_PROPERTY_TYPE_STRING | A displayable, localized name for the effect. |
| Author / D2D1_PROPERTY_AUTHOR | D2D1_PROPERTY_TYPE_STRING | The author of the effect. |
| Category / D2D1_PROPERTY_CATEGORY | D2D1_PROPERTY_TYPE_STRING | The category of the effect. |
| Description / D2D1_PROPERTY_DESCRIPTION | D2D1_PROPERTY_TYPE_STRING | A description of the effect. |
| Inputs / D2D1_PROPERTY_INPUTS | D2D1_PROPERTY_TYPE_ARRAY
Note Elements of this array are of type D2D1_PROPERTY_TYPE_STRING.
|
An array of names for the effect’s inputs. Each element of the array is a localized string specifying the name of an input. |
Standard Sub-Properties
The following are standard sub-properties that can be used for meta-data access, and may be available on both system and custom properties. Please see the D2D1_SUBPROPERTY and D2D1_PROPERTY_TYPE enumerations for more information.| Property name/index | Property type | Property description |
|---|---|---|
| DisplayName / D2D1_SUBPROPERTY_DISPLAYNAME | D2D1_PROPERTY_TYPE_STRING |
A displayable, localized name for the parent property.
This sub-property is present on all top-level properties. |
| IsReadOnly / D2D1_SUBPROPERTY_ISREADONLY | D2D1_PROPERTY_TYPE_BOOL |
A value indicating whether the parent property can be written to.
This sub-property is present on all top-level properties. |
| Default / D2D1_SUBPROPERTY_DEFAULT | Same as parent property. |
The default value for the property.
This sub-property is optionally present on all properties. |
| Min / D2D1_SUBPROPERTY_MIN | Same as parent property.
Note Applicable only to numeric-type properties.
|
The minimum value that the parent property supports being set to. |
| Max / D2D1_SUBPROPERTY_MAX | Same as parent property.
Note Applicable only to numeric-type properties.
|
The maximum value that the parent property supports being set to. |
| Fields / D2D1_SUBPROPERTY_FIELDS | Array / D2D1_PROPERTY_TYPE_ARRAY
Note Applicable only when the parent property is of type Enum.
|
The set of valid values that can be set to the parent property.
Each value in this array is a name/index pair. The indices can be set to the parent and the names are localized values designed for consumption by UI. See the following section for more details. |
Array-Type Sub-Properties
See ID2D1Properties::GetType and D2D1_PROPERTY_TYPE for more information. If the property type is D2D1_PROPERTY_TYPE_ARRAY, the value of the property will be considered to be a UINT that has the count of array elements. The next sub-property will directly map the index to the requested property value. For example:Inputs: UINT32 – 2
Inputs.0 : <Type> – First input
Inputs.1 : <Type> – Second input
The above example makes use of the following sub-properties, which will appear on ARRAY-type properties. Note that the numbered properties are not system properties, and are in the normal (0x0 – 0x80000000) range.
| Property name | Property index | Property description |
|---|---|---|
| Property.0 | 0 | First element of the property array. |
| ... | ... | ... |
| Property.N | N | Nth element of the property array. |
The type of each sub-element will be whatever the type of the array is. In the example above, this was an array of strings.
Enum-Type Sub-Properties
If the property has type D2D1_PROPERTY_TYPE_ENUM then the property will have the value of the corresponding enumeration. There will be a sub-array of fields that will conform to the general rules for array sub-properties and consist of the name/value pairs. For example:PixelFormat: ENUM – The pixel format value
PixelFormat.Fields: UINT32 – The number of fields
PixelFormat.Fields.0:String – The name of the first enum
PixelFormat.Fields.0.Index: UINT32 – The value of the enumeration.
The above example makes use of the following sub-properties. Please see the D2D1_SUBPROPERTY and D2D1_PROPERTY_TYPE enumerations for more information.
| Property name | Property index | Property description |
|---|---|---|
| Property.Fields | D2D1_SUBPROPERTY_FIELDS | An array type property that gives information about each field in the enumeration. |
| Property.Fields.N | N | An array element that gives the name of the Nth enumeration value. |
| Property.Fields.N.Index | D2D1_SUBPROPERTY_INDEX | The index which corresponds to the Nth enumeration value. |
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 8 and Platform Update for Windows 7 [desktop apps | UWP apps] |
| Minimum supported server | Windows Server 2012 and Platform Update for Windows Server 2008 R2 [desktop apps | UWP apps] |
| Target Platform | Windows |
| Header | d2d1_1.h |