ID2D1Properties interface

Represents a set of run-time bindable and discoverable properties that allow a data-driven application to modify the state of a Direct2D effect.

Methods

The ID2D1Properties interface has these methods.

Method Description
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.
ID2D1Properties::GetPropertyName Gets the property name that corresponds to the given index. This is a template overload. See Remarks.
ID2D1Properties::GetPropertyNameLength Gets the number of characters for the given property name.
ID2D1Properties::GetPropertyNameLength Gets the number of characters for the given property name. This is a template overload. See Remarks.
ID2D1Properties::GetSubProperties Gets the sub-properties of the provided property by index.
ID2D1Properties::GetSubProperties Gets the sub-properties of the provided property by index. This is a template overload.
ID2D1Properties::GetType Gets the D2D1_PROPERTY_TYPE of the selected property.
ID2D1Properties::GetType Gets the D2D1_PROPERTY_TYPE of the selected property. This is a template overload. See Remarks.
ID2D1Properties::GetValue Gets the value of the specified property by index.
ID2D1Properties::GetValue Gets the value of the specified property by index.
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.
ID2D1Properties::GetValue Gets the value of the property by index. This is a template overload. See Remarks.
ID2D1Properties::GetValueByName Gets the property value by name.
ID2D1Properties::GetValueByName Gets the property value by name.
ID2D1Properties::GetValueByName Gets the property value by name. This is a template overload. See Remarks.
ID2D1Properties::GetValueByName Gets the property value by name. This is a template overload. See Remarks.
ID2D1Properties::GetValueSize Gets the size of the property value in bytes, using the property index.
ID2D1Properties::GetValueSize Gets the size of the property value in bytes, using the property index. This is a template overload. See Remarks.
ID2D1Properties::SetValue Sets the corresponding property by index.
ID2D1Properties::SetValue Sets the corresponding property by index.
ID2D1Properties::SetValue Sets the corresponding property by index. This is a template overload.
ID2D1Properties::SetValue Sets the corresponding property by index. This is a template overload.
ID2D1Properties::SetValueByName Sets the named property to the given value.
ID2D1Properties::SetValueByName Sets the named property to the given value.
ID2D1Properties::SetValueByName Sets the named property to the given value. This is a template overload. See Remarks.

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 – SetValueByName and 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_MIN 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-Poperties

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

   
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

See Also

ID2D1Effect

IUnknown