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.

When to implement

Custom implementations are not supported.

Members

The ID2D1Properties interface inherits from the IUnknown interface. ID2D1Properties also has these types of members:

Methods

The ID2D1Properties interface has these methods.

MethodDescription
GetPropertyCount

Gets the number of top-level properties.

GetPropertyIndex

Gets the index corresponding to the given property name.

GetPropertyName overload methods

Gets the property name that corresponds to the given index.

GetPropertyNameLength overload methods

Gets the number of characters for the given property name.

GetSubProperties overload methods

Gets the sub-properties of the provided property by index.

GetType overload methods

Gets the D2D1_PROPERTY_TYPE of the selected property.

GetValue overload methods

Gets the value of the property by index.

GetValueByName overload methods

Gets the property value by name.

GetValueSize overload methods

Gets the size of the property value in bytes, using the property index.

SetValue overload methods

Sets the corresponding property by index.

SetValueByName overload methods

Sets the named property to the given value.

 

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/indexProperty typeProperty description
CLSID / D2D1_PROPERTY_CLSIDD2D1_PROPERTY_TYPE_CLSIDThe CLSID of the effect.
DisplayName / D2D1_PROPERTY_DISPLAYNAMED2D1_PROPERTY_TYPE_STRINGA displayable, localized name for the effect.
Author / D2D1_PROPERTY_AUTHORD2D1_PROPERTY_TYPE_STRINGThe author of the effect.
Category / D2D1_PROPERTY_CATEGORYD2D1_PROPERTY_TYPE_STRINGThe category of the effect.
Description / D2D1_PROPERTY_DESCRIPTIOND2D1_PROPERTY_TYPE_STRINGA description of the effect.
Inputs / D2D1_PROPERTY_INPUTSD2D1_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/indexProperty typeProperty description
DisplayName / D2D1_SUBPROPERTY_DISPLAYNAMED2D1_PROPERTY_TYPE_STRING

A displayable, localized name for the parent property.

This sub-property is present on all top-level properties.

IsReadOnly / D2D1_SUBPROPERTY_ISREADONLYD2D1_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_DEFAULTSame as parent property.

The default value for the property.

This sub-property is optionally present on all properties.

Min / D2D1_SUBPROPERTY_MINSame as parent property.

Note  Applicable only to numeric-type properties.

The minimum value that the parent property supports being set to.

Max / D2D1_SUBPROPERTY_MINSame as parent property.

Note  Applicable only to numeric-type properties.

The maximum value that the parent property supports being set to.

Fields / D2D1_SUBPROPERTY_FIELDSArray / 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 nameProperty indexProperty description
Property.00First element of the property array.
.........
Property.NNNth 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 nameProperty indexProperty description
Property.FieldsD2D1_SUBPROPERTY_FIELDSAn array type property that gives information about each field in the enumeration.
Property.Fields.NNAn array element that gives the name of the Nth enumeration value.
Property.Fields.N.IndexD2D1_SUBPROPERTY_INDEXThe index which corresponds to the Nth enumeration value.

 

Requirements

Minimum supported client

Windows 8 and Platform Update for Windows 7 [desktop apps | Windows Store apps]

Minimum supported server

Windows Server 2012 and Platform Update for Windows Server 2008 R2 [desktop apps | Windows Store apps]

Minimum supported phone

Windows Phone 8.1 [Windows Phone Silverlight 8.1 and Windows Runtime apps]

Header

D2d1_1.h

DLL

D2d1.dll

See also

ID2D1Effect

 

 

Community Additions

ADD
Show:
© 2014 Microsoft