An is abstract. Concrete instances can be created through and .

Images are evaluated lazily. If the type of image passed in is concrete, then the image can be directly sampled from. Other images can act only as a source of pixels and can produce content only as a result of calling .

A DIP is 1/96?of an inch. To retrieve the size in device pixels, use the method.

This method does not update the size of the current bitmap. If the contents of the source bitmap do not fit in the current bitmap, this method fails. Also, note that this method does not perform format conversion, and will fail if the bitmap formats do not match.

Calling this method may cause the current batch to flush if the bitmap is active in the batch. If the batch that was flushed does not complete successfully, this method fails. However, this method does not clear the error state of the render target on which the batch was flushed. The failing and tag state will be returned at the next call to EndDraw or Flush.

Starting with Windows?8.1, this method supports block compressed bitmaps. If you are using a block compressed format, the end coordinates of the srcRect parameter must be multiples of 4 or the method returns E_INVALIDARG.

This method does not update the size of the current bitmap. If the contents of the source bitmap do not fit in the current bitmap, this method fails. Also, note that this method does not perform format conversion, and will fail if the bitmap formats do not match.

Calling this method may cause the current batch to flush if the bitmap is active in the batch. If the batch that was flushed does not complete successfully, this method fails. However, this method does not clear the error state of the render target on which the batch was flushed. The failing and tag state will be returned at the next call to EndDraw or Flush.

All clips and layers must be popped off of the render target before calling this method. The method returns if any clips or layers are currently applied to the render target.

This method does not update the size of the current bitmap. If the contents of the source bitmap do not fit in the current bitmap, this method fails. Also, note that this method does not perform format conversion; the two bitmap formats should match.

If this method is passed invalid input (such as an invalid destination rectangle), can produce unpredictable results, such as a distorted image or device failure.

Calling this method may cause the current batch to flush if the bitmap is active in the batch. If the batch that was flushed does not complete successfully, this method fails. However, this method does not clear the error state of the render target on which the batch was flushed. The failing and tag state will be returned at the next call to EndDraw or Flush.

Starting with Windows?8.1, this method supports block compressed bitmaps. If you are using a block compressed format, the end coordinates of the srcRect parameter must be multiples of 4 or the method returns E_INVALIDARG.

A DIP is 1/96?of an inch. To retrieve the size in device pixels, use the method.

If the bitmap was created without specifying a color context, the returned context is null.

The bitmap used must have been created from a DXGI surface render target, a derived render target, or a device context created from an .

The returned surface can be used with Microsoft Direct3D or any other API that interoperates with shared surfaces. The application must transitively ensure that the surface is usable on the Direct3D device that is used in this context. For example, if using the surface with Direct2D then the Direct2D render target must have been created through or on a device context created on the same device.

Note??You can't use bitmaps for some purposes while mapped. Particularly, the method doesn't work if either the source or destination bitmap is mapped.

The bitmap must have been created with the flag specified.

Any memory returned from the Map call is now invalid and may be reclaimed by the operating system or used for other purposes.

The bitmap must have been previously mapped.

If the bitmap was created without specifying a color context, the returned context is null.

The bitmap used must have been created from a DXGI surface render target, a derived render target, or a device context created from an .

The returned surface can be used with Microsoft Direct3D or any other API that interoperates with shared surfaces. The application must transitively ensure that the surface is usable on the Direct3D device that is used in this context. For example, if using the surface with Direct2D then the Direct2D render target must have been created through or on a device context created on the same device.

A bitmap brush is used to fill a geometry with a bitmap. Like all brushes, it defines an infinite plane of content. Because bitmaps are finite, the brush relies on an "extend mode" to determine how the plane is filled horizontally and vertically.

An is a device-dependent resource: your application should create bitmap brushes after it initializes the render target with which the bitmap brush will be used, and recreate the bitmap brush whenever the render target needs recreated. (For more information about resources, see Resources Overview.)

Brush space in Direct2D is specified differently than in XPS and Windows Presentation Foundation (WPF). In Direct2D, brush space is not relative to the object being drawn, but rather is the current coordinate system of the render target, transformed by the brush transform, if present. To paint an object as it would be painted by a WPF brush, you must translate the brush space origin to the upper-left corner of the object's bounding box, and then scale the brush space so that the base tile fills the bounding box of the object.

For more information about brushes, see the Brushes Overview.

When you paint with a brush, it paints in the coordinate space of the render target. Brushes do not automatically position themselves to align with the object being painted; by default, they begin painting at the origin (0, 0) of the render target.

You can "move" the gradient defined by an to a target area by setting its start point and end point. Likewise, you can move the gradient defined by an by changing its center and radii.

To align the content of an to the area being painted, you can use the SetTransform method to translate the bitmap to the desired location. This transform only affects the brush; it does not affect any other content drawn by the render target.

The following illustrations show the effect of using an to fill a rectangle located at (100, 100). The illustration on the left illustration shows the result of filling the rectangle without transforming the brush: the bitmap is drawn at the render target's origin. As a result, only a portion of the bitmap appears in the rectangle.

The illustration on the right shows the result of transforming the so that its content is shifted 50 pixels to the right and 50 pixels down. The bitmap now fills the rectangle.

When the brush transform is the identity matrix, the brush appears in the same coordinate space as the render target in which it is drawn.

When the brush transform is the identity matrix, the brush appears in the same coordinate space as the render target in which it is drawn.

Sometimes, the bitmap for a bitmap brush doesn't completely fill the area being painted. When this happens, Direct2D uses the brush's horizontal (SetExtendModeX) and vertical (SetExtendModeY) extend mode settings to determine how to fill the remaining area.

The following illustration shows the results from every possible combination of the extend modes for an : (CLAMP), (WRAP), and D2D1_EXTEND_MIRROR (MIRROR).

Sometimes, the bitmap for a bitmap brush doesn't completely fill the area being painted. When this happens, Direct2D uses the brush's horizontal (SetExtendModeX) and vertical (SetExtendModeY) extend mode settings to determine how to fill the remaining area.

The following illustration shows the results from every possible combination of the extend modes for an : (CLAMP), (WRAP), and D2D1_EXTEND_MIRROR (MIRROR).

This method sets the interpolation mode for a bitmap, which is an enum value that is specified in the enumeration type. represents nearest neighbor filtering. It looks up the nearest bitmap pixel to the current rendering pixel and chooses its exact color. represents linear filtering, and interpolates a color from the four nearest bitmap pixels.

The interpolation mode of a bitmap also affects subpixel translations. In a subpixel translation, bilinear interpolation positions the bitmap more precisely to the application requests, but blurs the bitmap in the process.

This method specifies the bitmap source that this brush uses to paint. The bitmap is not resized or rescaled automatically to fit the geometry that it fills. The bitmap stays at its native size. To resize or translate the bitmap, use the SetTransform method to apply a transform to the brush.

The native size of a bitmap is the width and height in bitmap pixels, divided by the bitmap DPI. This native size forms the base tile of the brush. To tile a subregion of the bitmap, you must generate a new bitmap containing this subregion and use SetBitmap to apply it to the brush.

Like all brushes, defines an infinite plane of content. Because bitmaps are finite, it relies on an extend mode to determine how the plane is filled horizontally and vertically.

Like all brushes, defines an infinite plane of content. Because bitmaps are finite, it relies on an extend mode to determine how the plane is filled horizontally and vertically.

This method gets the interpolation mode of a bitmap, which is specified by the enumeration type. represents nearest neighbor filtering. It looks up the bitmap pixel nearest to the current rendering pixel and chooses its exact color. represents linear filtering, and interpolates a color from the four nearest bitmap pixels.

The interpolation mode of a bitmap also affects subpixel translations. In a subpixel translation, linear interpolation positions the bitmap more precisely to the application request, but blurs the bitmap in the process.

Like all brushes, defines an infinite plane of content. Because bitmaps are finite, it relies on an extend mode to determine how the plane is filled horizontally and vertically.

Like all brushes, defines an infinite plane of content. Because bitmaps are finite, it relies on an extend mode to determine how the plane is filled horizontally and vertically.

This method gets the interpolation mode of a bitmap, which is specified by the enumeration type. represents nearest neighbor filtering. It looks up the bitmap pixel nearest to the current rendering pixel and chooses its exact color. represents linear filtering, and interpolates a color from the four nearest bitmap pixels.

The interpolation mode of a bitmap also affects subpixel translations. In a subpixel translation, linear interpolation positions the bitmap more precisely to the application request, but blurs the bitmap in the process.

If both dpiX and dpiY are 0, the dpi of the bitmap will be set to the desktop dpi if the device context is a windowed context, or 96 dpi for any other device context.

The command list does not include static copies of resources with the recorded set of commands. All bitmaps, effects, and geometries are stored as references to the actual resource and all the brushes are stored by value. All the resource creation and destruction happens outside of the command list. The following table lists resources and how they are treated inside of a command list.

?

The command sink can be implemented by any caller of the API.

If the caller makes any design-time failure calls while a command list is selected as a target, the command list is placed in an error state. The stream call fails without making any calls to the passed in sink.

Sample use:

Class MyCommandSink : public 	
            {	
            public: // All of the  methods implemented here.	
            }; 	
            StreamToMyCommandSink( __in  *pCommandList  )	
            {  hr = ; MyCommandSink *pCommandSink = new MyCommandSink(); hr = pCommandSink ?  : E_OUTOFMEMORY; if (SUCCEEDED(hr)) { // Receive the contents of the command sink streamed to the sink. hr = pCommandList->Stream(pCommandSink); } SafeRelease(&pCommandSink); return hr; }

This method returns if it has already been called on the command list. If an error occurred on the device context during population, the method returns that error. Otherwise, the method returns .

If the Close method returns an error, any future use of the command list results in the same error.

Transform nodes are type-less and only define the notion of an object that accepts a number of inputs and is an output. This interface limits a topology to single output nodes.

Transform nodes are type-less and only define the notion of an object that accepts a number of inputs and is an output. This interface limits a topology to single output nodes.

You can use the method to see if buffer precision is supported.

The available channel depth and precision depend on the capabilities of the underlying Microsoft Direct3D device.

If the extend mode enumeration is invalid, this operation is ignored.

If the extend mode enumeration is invalid, this operation is ignored.

The support transform can be used for two different reasons.

• To indicate that a region of its input image is already transparent black. The expanded area will be treated as transparent black.

  This can increase efficiency for rendering bitmaps.

• To increase the size of the input image.

?

?

This can be used to allocate a buffer to receive the color profile bytes associated with the context.

If profileSize is insufficient to store the entire profile, profile is zero-initialized before this method fails.

This can be used to allocate a buffer to receive the color profile bytes associated with the context.

The can be implemented to receive a play-back of the commands recorded in a command list. This interface is typically used for transforming the command list into another format where some degree of conversion between the Direct2D primitives and the target format is required.

The interface does not have any resource creation methods. The resources are logically bound to the Direct2D device on which the was created and will be passed in to the implementation.

Not all methods implemented by are present.

The can be implemented to receive a play-back of the commands recorded in a command list. This interface is typically used for transforming the command list into another format where some degree of conversion between the Direct2D primitives and the target format is required.

The interface does not have any resource creation methods. The resources are logically bound to the Direct2D device on which the was created and will be passed in to the implementation.

Not all methods implemented by are present.

The active at the end of the command list will be returned.

It allows the calling function or method to indicate a failure back to the stream implementation.

The transform will be applied to the corresponding device context.

The unit mode changes the interpretation of units from DIPs to pixels or vice versa.

The clear color is restricted by the currently selected clip and layer bounds.

If no color is specified, the color should be interpreted by context. Examples include but are not limited to:

• Transparent black for a premultiplied bitmap target.
• Opaque black for an ignore bitmap target.
• Containing no content (or white) for a printer page.

DrawText and DrawTextLayout are broken down into glyph runs and rectangles by the time the command sink is processed. So, these methods aren't available on the command sink. Since the application may require additional callback processing when calling DrawTextLayout, this semantic can't be easily preserved in the command list.

Ellipses and rounded rectangles are converted to the corresponding ellipse and rounded rectangle geometries before calling into the DrawGeometry method.

The destinationRectangle parameter defines the rectangle in the target where the bitmap will appear (in device-independent pixels (DIPs)). This is affected by the currently set transform and the perspective transform, if set. If you specify null, then the destination rectangle is (left=0, top=0, right = width(sourceRectangle), bottom = height(sourceRectangle).

The sourceRectangle defines the sub-rectangle of the source bitmap (in DIPs). DrawBitmap clips this rectangle to the size of the source bitmap, so it's impossible to sample outside of the bitmap. If you specify null, then the source rectangle is taken to be the size of the source bitmap.

The perspectiveTransform is specified in addition to the transform on device context.

Because the image can itself be a command list or contain an effect graph that in turn contains a command list, this method can result in recursive processing.

The targetOffset defines the offset in the destination space that the image will be rendered to. The entire logical extent of the image is rendered to the corresponding destination. If you don't specify the offset, the destination origin will be (0, 0). The top, left corner of the image will be mapped to the target offset. This will not necessarily be the origin.

The opacity mask bitmap must be considered to be clamped on each axis.

If the opacity brush is specified, the primary brush will be a bitmap brush fixed on both the x-axis and the y-axis.

Ellipses and rounded rectangles are converted to the corresponding geometry before being passed to FillGeometry.

If the current world transform is not preserving the axis, clipRectangle is transformed and the bounds of the transformed rectangle are used instead.

The transform changes the state on this render information to specify the compute shader and its dependent resources.

This interface is used by a transform implementation to first describe and then indicate changes to the rendering pass that corresponds to the transform.

The input description must be matched correctly by the effect shader code.

If the output precision of the transform is not specified, then it will default to the precision specified on the Direct2D device context. The maximum of 16bpc UNORM and 16bpc FLOAT is 32bpc FLOAT.

The output channel depth will match the maximum of the input channel depths if the channel depth is .

There is no global output channel depth, this is always left to the control of the transforms.

The instruction count may be set according to the number of instructions in the shader. This information is used as a hint when rendering extremely large images. Calling this API is optional, but it may improve performance if you provide an accurate number.

Note??Instructions that occur in a loop should be counted according to the number of loop iterations.

The instruction count may be set according to the number of instructions in the shader. This information is used as a hint when rendering extremely large images. Calling this API is optional, but it may improve performance if you provide an accurate number.

Note??Instructions that occur in a loop should be counted according to the number of loop iterations.

This interface can be implemented by either an or an .

The output of the transform will be copied to CPU-accessible memory by the imaging effects system before being passed to the implementation.

If this call fails, the corresponding instance is placed into an error state and fails to draw.

The transform implements the normal Shatzis methods by implementing . In addition, the caller is passed an ID2D1ComputeRenderInfo to describe the compute pass that the transform should execute.

Transforms are aggregated by effect authors. This interface provides a common interface for implementing the Shantzis rectangle calculations which is the basis for all the transform processing in Direct2D imaging extensions. These calculations are described in the paper A model for efficient and flexible image computing.

The transform implementation must ensure that any pixel shader or software callback implementation it provides honors this calculation.

The transform implementation must regard this method as purely functional. It can base the mapped input and output rectangles on its current state as specified by the encapsulating effect properties. However, it must not change its own state in response to this method being invoked. The DirectImage renderer implementation reserves the right to call this method at any time and in any sequence.

The transform implementation must ensure that any pixel shader or software callback implementation it provides honors this calculation.

The transform implementation must regard this method as purely functional. It can base the mapped input and output rectangles on its current state as specified by the encapsulating effect properties. However, it must not change its own state in response to this method being invoked. The Direct2D renderer implementation reserves the right to call this method at any time and in any sequence.

The transform implements the normal Shatzis methods by implementing . In addition, the caller is passed an ID2D1ComputeRenderInfo to describe the compute pass that the transform should execute.

Transforms are aggregated by effect authors. This interface provides a common interface for implementing the Shantzis rectangle calculations which is the basis for all the transform processing in Direct2D imaging extensions. These calculations are described in the paper A model for efficient and flexible image computing.

The transform implementation must ensure that any pixel shader or software callback implementation it provides honors this calculation.

The transform implementation must regard this method as purely functional. It can base the mapped input and output rectangles on its current state as specified by the encapsulating effect properties. However, it must not change its own state in response to this method being invoked. The Direct2D renderer implementation reserves the right to call this method at any time and in any sequence.

The transform implementation must ensure that any pixel shader or software callback implementation it provides honors this calculation.

Unlike the MapOutputRectToInputRects and MapInvalidRect functions, this method is explicitly called by the renderer at a determined place in its rendering algorithm. The transform implementation may change its state based on the input rectangles and use this information to control its rendering information. This method is always called before the MapInvalidRect and MapOutputRectToInputRects methods of the transform.

The transform implementation must regard MapInvalidRect as purely functional. The transform implementation can base the mapped input rectangle on the transform implementation's current state as specified by the encapsulating effect properties. But the transform implementation can't change its own state in response to a call to MapInvalidRect. Direct2D can call this method at any time and in any sequence following a call to the MapInputRectsToOutputRect method.

If this method fails, fails.

If this call fails, the corresponding instance is placed into an error state and fails to draw.

Windows Phone 8.1: This API is supported.

Windows Phone 8.1: This API is supported.

Windows Phone 8.1: This API is supported.

Rotation occurs in the plane of the 2-D surface.

Windows Phone 8.1: This API is supported.

The interface provides the starting point for Direct2D. In general, objects created from a single instance of a factory object can be used with other resources created from that instance, but not with resources created by other factory instances.

Windows Phone 8.1: This API is supported.

Windows Phone 8.1: This API is supported.

This function will also create a new that can be retrieved through .

If the creation properties are not specified, then d2dDevice will inherit its threading mode from dxgiDevice and debug tracing will not be enabled.

Windows Phone 8.1: This API is supported.

Windows Phone 8.1: This API is supported.

Windows Phone 8.1: This API is supported.

This function will also create a new that can be retrieved through .

This function will also create a new that can be retrieved through .

The DXGI device will be specified implicitly through dxgiSurface.

The created device context will have exactly the same behavior as if ID2D1DeviceContext::SetTargetSurface were called with the corresponding surface.

If creationProperties are not specified, the Direct2D device will inherit its threading mode from the DXGI device implied by dxgiSurface and debug tracing will not be enabled.

Windows Phone 8.1: This API is supported.

Windows Phone 8.1: This API is supported.

Formally, if M is the input matrix, this method will return the maximum value of |V * M| / |V| for all vectors V, where |.| denotes length.

Note??Since this describes how M affects vectors (rather than points), the translation components (_31 and _32) of M are ignored.

Windows Phone 8.1: This API is supported.

The new device context will not have a selected target bitmap. The caller must create and select a bitmap as the target surface of the context.

Note??Direct2D may exceed the maximum texture memory you set with this method for a single frame if necessary to render the frame.

Calling this method affects the rendering priority of all device contexts associated with the device. This method can be called at any time, but is not guaranteed to take effect until the beginning of the next frame. The recommended usage is to call this method outside of BeginDraw and EndDraw blocks. Cycling this property frequently within drawing blocks will effectively reduce the benefits of any throttling that is applied.

Any resource created from a device context can be shared with any other resource created from a device context when both contexts are created on the same device.

Your application should create render targets once and hold onto them for the life of the application or until the render target's EndDraw method returns the error. When you receive this error, you need to recreate the render target (and any resources it created).

Before Direct2D can load a WIC bitmap, that bitmap must be converted to a supported pixel format and alpha mode. For a list of supported pixel formats and alpha modes, see Supported Pixel Formats and Alpha Modes.

The CreateSharedBitmap method is useful for efficiently reusing bitmap data and can also be used to provide interoperability with Direct3D.

The bitmap render target created by this method is not compatible with GDI.

Regardless of whether a size is initially specified, the layer automatically resizes as needed.

To populate a mesh, use its Open method to obtain an . To draw the mesh, use the render target's FillMesh method.

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawLine) failed, check the result returned by the or methods.

When this method fails, it does not return an error code. To determine whether a drawing method (such as DrawRectangle) failed, check the result returned by the or method.

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as FillRectangle) failed, check the result returned by the or methods.

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawRoundedRectangle) failed, check the result returned by the or methods.

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as FillRoundedRectangle) failed, check the result returned by the or methods.

The DrawEllipse method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawEllipse) failed, check the result returned by the or methods.

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as FillEllipse) failed, check the result returned by the or methods.

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawGeometry) failed, check the result returned by the or methods.

If the opacityBrush parameter is not null, the alpha value of each pixel of the mapped opacityBrush is used to determine the resulting opacity of each corresponding pixel of the geometry. Only the alpha value of each color in the brush is used for this processing; all other color information is ignored. The alpha value specified by the brush is multiplied by the alpha value of the geometry after the geometry has been painted by brush.

When this method fails, it does not return an error code. To determine whether a drawing operation (such as FillGeometry) failed, check the result returned by the or method.

The current antialias mode of the render target must be when FillMesh is called. To change the render target's antialias mode, use the SetAntialiasMode method.

FillMesh does not expect a particular winding order for the triangles in the ; both clockwise and counter-clockwise will work.

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as FillMesh) failed, check the result returned by the or methods.

For this method to work properly, the render target must be using the antialiasing mode. You can set the antialiasing mode by calling the method.

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as FillOpacityMask) failed, check the result returned by the or methods.

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawBitmap) failed, check the result returned by the or methods.

To create an object, create an and call its CreateTextFormat method.

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawText) failed, check the result returned by the or methods.

When drawing the same text repeatedly, using the DrawTextLayout method is more efficient than using the DrawText method because the text doesn't need to be formatted and the layout processed with each call.

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawTextLayout) failed, check the result returned by the or methods.

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawGlyphRun) failed, check the result returned by the or methods.

To specify the antialiasing mode for text and glyph operations, use the SetTextAntialiasMode method.

If the settings specified by textRenderingParams are incompatible with the render target's text antialiasing mode (specified by SetTextAntialiasMode), subsequent text and glyph drawing operations will fail and put the render target into an error state.

If the settings specified by textRenderingParams are incompatible with the render target's text antialiasing mode (specified by SetTextAntialiasMode), subsequent text and glyph drawing operations will fail and put the render target into an error state.

The labels specified by this method are printed by debug error messages. If no tag is set, the default value for each tag is 0.

If the same address is passed for both parameters, both parameters receive the value of the second tag.

The PushLayer method allows a caller to begin redirecting rendering to a layer. All rendering operations are valid in a layer. The location of the layer is affected by the world transform set on the render target.

Each PushLayer must have a matching PopLayer call. If there are more PopLayer calls than PushLayer calls, the render target is placed into an error state. If Flush is called before all outstanding layers are popped, the render target is placed into an error state, and an error is returned. The error state can be cleared by a call to EndDraw.

A particular resource can be active only at one time. In other words, you cannot call a PushLayer method, and then immediately follow with another PushLayer method with the same layer resource. Instead, you must call the second PushLayer method with different layer resources.

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as PushLayer) failed, check the result returned by the or methods.

A PopLayer must match a previous PushLayer call.

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as PopLayer) failed, check the result returned by the or methods.

This command does not flush the device that is associated with the render target.

Calling this method resets the error state of the render target.

The clipRect is transformed by the current world transform set on the render target. After the transform is applied to the clipRect that is passed in, the axis-aligned bounding box for the clipRect is computed. For efficiency, the contents are clipped to this axis-aligned bounding box and not to the original clipRect that is passed in.

The following diagrams show how a rotation transform is applied to the render target, the resulting clipRect, and a calculated axis-aligned bounding box.

1. Assume the rectangle in the following illustration is a render target that is aligned to the screen pixels.

2. Apply a rotation transform to the render target. In the following illustration, the black rectangle represents the original render target and the red dashed rectangle represents the transformed render target.

3. After calling PushAxisAlignedClip, the rotation transform is applied to the clipRect. In the following illustration, the blue rectangle represents the transformed clipRect.

4. The axis-aligned bounding box is calculated. The green dashed rectangle represents the bounding box in the following illustration. All contents are clipped to this axis-aligned bounding box.

Note??If rendering operations fail or if PopAxisAlignedClip is not called, clip rects may cause some artifacts on the render target. PopAxisAlignedClip can be considered a drawing operation that is designed to fix the borders of a clipping region. Without this call, the borders of a clipped area may be not antialiased or otherwise corrected.

The PushAxisAlignedClip and PopAxisAlignedClip must match. Otherwise, the error state is set. For the render target to continue receiving new commands, you can call Flush to clear the error.

A PushAxisAlignedClip and PopAxisAlignedClip pair can occur around or within a PushLayer and PopLayer, but cannot overlap. For example, the sequence of PushAxisAlignedClip, PushLayer, PopLayer, PopAxisAlignedClip is valid, but the sequence of PushAxisAlignedClip, PushLayer, PopAxisAlignedClip, PopLayer is invalid.

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as PushAxisAlignedClip) failed, check the result returned by the or methods.

A PushAxisAlignedClip/PopAxisAlignedClip pair can occur around or within a PushLayer/PopLayer pair, but may not overlap. For example, a PushAxisAlignedClip, PushLayer, PopLayer, PopAxisAlignedClip sequence is valid, but a PushAxisAlignedClip, PushLayer, PopAxisAlignedClip, PopLayer sequence is not.

PopAxisAlignedClip must be called once for every call to PushAxisAlignedClip.

For an example, see How to Clip with an Axis-Aligned Clip Rectangle.

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as PopAxisAlignedClip) failed, check the result returned by the or methods.

Direct2D interprets the clearColor as straight alpha (not premultiplied). If the render target's alpha mode is , the alpha channel of clearColor is ignored and replaced with 1.0f (fully opaque).

If the render target has an active clip (specified by PushAxisAlignedClip), the clear command is applied only to the area within the clip region.

Drawing operations can only be issued between a BeginDraw and EndDraw call.

BeginDraw and EndDraw are used to indicate that a render target is in use by the Direct2D system. Different implementations of might behave differently when BeginDraw is called. An may be locked between BeginDraw/EndDraw calls, a DXGI surface render target might be acquired on BeginDraw and released on EndDraw, while an may begin batching at BeginDraw and may present on EndDraw, for example.

The BeginDraw method must be called before rendering operations can be called, though state-setting and state-retrieval operations can be performed even outside of BeginDraw/EndDraw.

After BeginDraw is called, a render target will normally build up a batch of rendering commands, but defer processing of these commands until either an internal buffer is full, the Flush method is called, or until EndDraw is called. The EndDraw method causes any batched drawing operations to complete, and then returns an indicating the success of the operations and, optionally, the tag state of the render target at the time the error occurred. The EndDraw method always succeeds: it should not be called twice even if a previous EndDraw resulted in a failing .

If EndDraw is called without a matched call to BeginDraw, it returns an error indicating that BeginDraw must be called before EndDraw. Calling BeginDraw twice on a render target puts the target into an error state where nothing further is drawn, and returns an appropriate and error information when EndDraw is called.

Drawing operations can only be issued between a BeginDraw and EndDraw call.

BeginDraw and EndDraw are use to indicate that a render target is in use by the Direct2D system. Different implementations of might behave differently when BeginDraw is called. An may be locked between BeginDraw/EndDraw calls, a DXGI surface render target might be acquired on BeginDraw and released on EndDraw, while an may begin batching at BeginDraw and may present on EndDraw, for example.

The BeginDraw method must be called before rendering operations can be called, though state-setting and state-retrieval operations can be performed even outside of BeginDraw/EndDraw.

After BeginDraw is called, a render target will normally build up a batch of rendering commands, but defer processing of these commands until either an internal buffer is full, the Flush method is called, or until EndDraw is called. The EndDraw method causes any batched drawing operations to complete, and then returns an indicating the success of the operations and, optionally, the tag state of the render target at the time the error occurred. The EndDraw method always succeeds: it should not be called twice even if a previous EndDraw resulted in a failing .

If EndDraw is called without a matched call to BeginDraw, it returns an error indicating that BeginDraw must be called before EndDraw. Calling BeginDraw twice on a render target puts the target into an error state where nothing further is drawn, and returns an appropriate and error information when EndDraw is called.

This method specifies the mapping from pixel space to device-independent space for the render target. If both dpiX and dpiY are 0, the factory-read system DPI is chosen. If one parameter is zero and the other unspecified, the DPI is not changed.

For , the DPI defaults to the most recently factory-read system DPI. The default value for all other render targets is 96 DPI.

This method indicates the mapping from pixel space to device-independent space for the render target.

For , the DPI defaults to the most recently factory-read system DPI. The default value for all other render targets is 96 DPI.

This method returns the maximum texture size of the Direct3D device.

Note??The software renderer and WARP devices return the value of 16 megapixels (16*1024*1024). You can create a Direct2D texture that is this size, but not a Direct3D texture that is this size.

This method does not evaluate the DPI settings specified by the renderTargetProperties parameter.

If the settings specified by textRenderingParams are incompatible with the render target's text antialiasing mode (specified by SetTextAntialiasMode), subsequent text and glyph drawing operations will fail and put the render target into an error state.

This method returns the maximum texture size of the Direct3D device.

Note??The software renderer and WARP devices return the value of 16 megapixels (16*1024*1024). You can create a Direct2D texture that is this size, but not a Direct3D texture that is this size.

The new bitmap can be used as a target for SetTarget if it is created with .

Starting with Windows?8.1, the bitmapProperties parameter is optional. When it is not specified, the created bitmap inherits the pixel format and alpha mode from wicBitmapSource. For a list of supported pixel formats and alpha modes, see Supported Pixel Formats and Alpha Modes.

When the bitmapProperties parameter is specified, the value in bitmapProperties->pixelFormat must either be or must match the WIC pixel format in wicBitmapSource.

When bitmapProperties->pixelFormat.alphaMode is set to , the newly created bitmap inherits the alpha mode from wicBitmapSource. When bitmapProperties->pixelFormat.alphaMode is set to , , or , this forces the newly created bitmap to use the specified alpha mode.

The new color context can be used in to initialize the color context of a created bitmap.

When space is , profile and profileSize must be specified. Otherwise, these parameters should be set to null and zero respectively. When the space is , the model field of the profile header is inspected to determine if this profile is sRGB or scRGB and the color space is updated respectively. Otherwise the space remains custom.

The new color context can be used in to initialize the color context of a created bitmap. The model field of the profile header is inspected to determine whether this profile is sRGB or scRGB and the color space is updated respectively. Otherwise the space is custom.

The new color context can be used in to initialize the color context of a created bitmap. The model field of the profile header is inspected to determine whether this profile is sRGB or scRGB and the color space is updated respectively. Otherwise the space is custom.

If the bitmap properties are not specified, the following information is assumed:

• The bitmap DPI is 96.
• The pixel format matches that of the surface.
• The returned bitmap will inherit the bind flags of the DXGI surface.
  • However, only the subset of flags meaningful to Direct2D will be inherited. For example, D3D10_USAGE_DYNAMIC is not compatible with any public Direct2D flags.
• The color context is unknown.
• The alpha mode of the bitmap will be premultiplied (common case) or straight (A8).

If the bitmap properties are specified, the bitmap properties will be used as follows:

• The bitmap DPI will be specified by the bitmap properties.
• If both dpiX and dpiY are 0, the bitmap DPI will be 96.
• The pixel format must be compatible with the shader resource view or render target view of the surface.
• The bitmap options must be compatible with the bind flags of the DXGI surface. However, they may be a subset. This will influence what resource views are created by the bitmap.
• The color context information will be used from the bitmap properties, if specified.

If the created effect is a custom effect that is implemented in a DLL, this doesn't increment the reference count for that DLL. If the application deletes an effect while that effect is loaded, the resulting behavior is unpredictable.

This method linearly interpolates between the color stops. An optional color space conversion is applied post-interpolation. Whether and how this gamma conversion is applied is determined by the pre- and post-interpolation. This method will fail if the device context does not support the requested buffer precision.

In order to get the desired result, you need to ensure that the inputs are specified in the correct color space.

You must always specify colors in straight alpha, regardless of interpolation mode being premultiplied or straight. The interpolation mode only affects the interpolated values. Likewise, the stops returned by will always have straight alpha.

If you specify , then all stops are premultiplied before interpolation, and then un-premultiplied before color conversion.

Starting with Windows?8, the interpolation behavior of this method has changed.

The table here shows the behavior in Windows?7 and earlier.

?

The table here shows the behavior in Windows?8 and later.

?

The image brush can be used to fill an arbitrary geometry, an opacity mask or text.

This sample illustrates drawing a rectangle with an image brush.

	
            CreatePatternBrush( __in  *pDeviceContext, __deref_out  **ppImageBrush )	
            {  hr = ;  *pOldTarget = null; pDeviceContext->GetTarget(&pOldTarget);  *pCommandList = null; hr = pDeviceContext->CreateCommandList(&pCommandList); if (SUCCEEDED(hr)) {    pDeviceContext->SetTarget(pCommandList); hr = RenderPatternToCommandList(pDeviceContext); } pDeviceContext->SetTarget(pOldTarget);  *pImageBrush = null; if (SUCCEEDED(hr)) {         hr = pDeviceContext->CreateImageBrush( pCommandList, D2D1::ImageBrushProperties( D2D1::RectF(198, 298, 370, 470), , ,  ), &pImageBrush ); } // Fill a rectangle with the image brush. if (SUCCEEDED(hr)) { pDeviceContext->FillRectangle( D2D1::RectF(0, 0, 100, 100), pImageBrush); } SafeRelease(&pImageBrush); SafeRelease(&pCommandList); SafeRelease(&pOldTarget); return hr;	
            }

A can store Direct2D commands to be displayed later through or through an image brush.

You can use supported formats in the structure to create bitmaps and render targets. Direct2D doesn't support all DXGI formats, even though they may have some level of Direct3D support by the hardware.

The image bounds don't include multiplication by the world transform. They do reflect the current DPI, unit mode, and interpolation mode of the context. To get the bounds that include the world trasnfrom, use .

The returned bounds reflect which pixels would be impacted by calling DrawImage with a target offset of (0,0) and an identity world transform matrix.

The image bounds reflect the current DPI, unit mode, and world transform of the context. To get bounds which don't include the world transform, use .

The returned bounds reflect which pixels would be impacted by calling DrawImage with the same image and a target offset of (0,0). They do not reflect the current clip rectangle set on the device context or the extent of the context?s current target image.

The image bounds reflect the current DPI, unit mode, and world transform of the context.

The application can retrieve the device even if it is created from an earlier render target code-path. The application must use an interface and then call GetDevice. Some functionality for controlling all of the resources for a set of device contexts is maintained only on an object.

The target can be changed at any time, including while the context is drawing.

The target can be either a bitmap created with the flag, or it can be a command list. Other kinds of images cannot be set as a target. For example, you cannot set the output of an effect as target. If the target is not valid the context will enter the error state.

You cannot use SetTarget to render to a bitmap/command list from multiple device contexts simultaneously. An image is considered ?being rendered to? if it has ever been set on a device context within a BeginDraw/EndDraw timespan. If an attempt is made to render to an image through multiple device contexts, all subsequent device contexts after the first will enter an error state.

Callers wishing to attach an image to a second device context should first call EndDraw on the first device context.

Here is an example of the correct calling order.

pDC1->BeginDraw();	
            pDC1->SetTarget(pImage);	
            // ?	
            pDC1->EndDraw(); pDC2->BeginDraw();	
            pDC2->SetTarget(pImage);	
            // ?	
            pDC2->EndDraw();	
            

Here is an example of the incorrect calling order.

pDC1->BeginDraw();	
            pDC2->BeginDraw(); pDC1->SetTarget(pImage); // ... pDC1->SetTarget(null); pDC2->SetTarget(pImage); // This call is invalid, even though pImage is no longer set on pDC1. // ... pDC1->EndDraw(); // This EndDraw SUCCEEDs.	
            pDC2->EndDraw(); // This EndDraw FAILs 

Note??Changing the target does not change the bitmap that an render target presents from, nor does it change the bitmap that a DC render target blts to/from.

This API makes it easy for an application to use a bitmap as a source (like in DrawBitmap) and as a destination at the same time. Attempting to use a bitmap as a source on the same device context to which it is bound as a target will put the device context into the error state.

It is acceptable to have a bitmap bound as a target bitmap on multiple render targets at once. Applications that do this must properly synchronize rendering with Flush or EndDraw.

You can change the target at any time, including while the context is drawing.

You can set the target to null, in which case drawing calls will put the device context into an error state with . Calling SetTarget with a null target does not restore the original target bitmap to the device context.

If the device context has an outstanding , the context will enter the error state. The target will not be changed.

If the bitmap and the device context are not in the same resource domain, the context will enter \ error state. The target will not be changed.

returns the size of the current target bitmap (or 0, 0) if there is no bitmap bound). returns the pixel size of the current bitmap scaled by the DPI of the render target. SetTarget does not affect the DPI of the render target.

returns the pixel format of the current target bitmap (or , if there is none).

copies from the currently bound target bitmap.

If a target is not associated with the device context, target will contain null when the methods returns.

If the currently selected target is a bitmap rather than a command list, the application can gain access to the initial bitmaps created by using one of the following methods:

• CreateHwndRenderTarget
• CreateDxgiSurfaceRenderTarget
• CreateWicBitmapRenderTarget
• CreateDCRenderTarget
• CreateCompatibleRenderTarget

It is not possible for an application to destroy these bitmaps. All of these bitmaps are bindable as bitmap targets. However not all of these bitmaps can be used as bitmap sources for methods.

CreateDxgiSurfaceRenderTarget will create a bitmap that is usable as a bitmap source if the DXGI surface is bindable as a shader resource view.

CreateCompatibleRenderTarget will always create bitmaps that are usable as a bitmap source.

will copy from the to the original bitmap associated with it. will copy from the original bitmap to the .

objects will be locked in the following circumstances:

• BeginDraw has been called and the currently selected target bitmap is a WIC bitmap.
• A WIC bitmap is set as the target of a device context after BeginDraw has been called and before EndDraw has been called.
• Any of the ID2D1Bitmap::Copy* methods are called with a WIC bitmap as either the source or destination.

objects will be unlocked in the following circumstances:

• EndDraw is called and the currently selected target bitmap is a WIC bitmap.
• A WIC bitmap is removed as the target of a device context between the calls to BeginDraw and EndDraw.
• Any of the ID2D1Bitmap::Copy* methods are called with a WIC bitmap as either the source or destination.

Direct2D will only lock bitmaps that are not currently locked.

Calling QueryInterface for ID2D1GdiInteropRenderTarget will always succeed. ID2D1GdiInteropRenderTarget::GetDC will return a device context corresponding to the currently bound target bitmap. GetDC will fail if the target bitmap was not created with the GDI_COMPATIBLE flag set.

will return if there are any outstanding references to the original target bitmap associated with the render target.

Although the target can be a command list, it cannot be any other type of image. It cannot be the output image of an effect.

The rendering controls allow the application to tune the precision, performance, and resource usage of rendering operations.

The primitive blend will apply to all of the primitive drawn on the context, unless this is overridden with the compositeMode parameter on the DrawImage API.

The primitive blend applies to the interior of any primitives drawn on the context. In the case of DrawImage, this will be implied by the image rectangle, offset and world transform.

If the primitive blend is anything other than then ClearType rendering will be turned off. If the application explicitly forces ClearType rendering in these modes, the drawing context will be placed in an error state. will be returned from either EndDraw or Flush.

This method will affect all properties and parameters affected by SetDpi and GetDpi. This affects all coordinates, lengths, and other properties that are not explicitly defined as being in another unit. For example:

• SetUnitMode will affect a coordinate passed into ID2D1DeviceContext::DrawLine, and the scaling of a geometry passed into ID2D1DeviceContext::FillGeometry.
• SetUnitMode will not affect the value returned by , or how the desiredPixelSize parameter is interpreted in ID2D1DeviceContext::CreateCompatibleBitmap.

The glyphRunDescription is ignored when rendering, but can be useful for printing and serialization of rendering commands, such as to an XPS or SVG file. This extends , which lacked the glyph run description.

If interpolationMode is D2D1_INTERPOLATION_MODE_HIGH_QUALITY, different scalers will be used depending on the scale factor implied by the world transform.

Any invalid rectangles accumulated on any effect that is drawn by this call will be discarded regardless of which portion of the image rectangle is drawn.

If compositeMode is D2D1_COMPOSITE_MODE_DEFAULT, DrawImage will use the currently selected primitive blend specified by . If compositeMode is not D2D1_COMPOSITE_MODE_DEFAULT, the image will be extended to transparent up to the current axis-aligned clip.

If there is an image rectangle and a world transform, this is equivalent to inserting a clip effect to represent the image rectangle and a 2D affine transform to take into account the world transform.

The destinationRectangle parameter defines the rectangle in the target where the bitmap will appear (in device-independent pixels (DIPs)). This is affected by the currently set transform and the perspective transform, if set. If null is specified, then the destination rectangle is (left=0, top=0, right = width(sourceRectangle), bottom = height(sourceRectangle)).

The sourceRectangle parameter defines the sub-rectangle of the source bitmap (in DIPs). DrawBitmap will clip this rectangle to the size of the source bitmap, thus making it impossible to sample outside of the bitmap. If null is specified, then the source rectangle is taken to be the size of the source bitmap.

If you specify perspectiveTransform it is applied to the rect in addition to the transform set on the render target.

Note??Direct2D does not automatically use these invalid rectangles to reduce the region of an effect that is rendered.

You can use the InvalidateEffectInputRectangle method to specify invalidated rectangles for Direct2D to propagate through an effect graph.

If multiple invalid rectangles are requested, the rectangles that this method returns may overlap. When this is the case, the rectangle count might be lower than the count that GetEffectInvalidRectangleCount.

The application can retrieve the device even if it is created from an earlier render target code-path. The application must use an interface and then call GetDevice. Some functionality for controlling all of the resources for a set of device contexts is maintained only on an object.

If a target is not associated with the device context, target will contain null when the methods returns.

If the currently selected target is a bitmap rather than a command list, the application can gain access to the initial bitmaps created by using one of the following methods:

• CreateHwndRenderTarget
• CreateDxgiSurfaceRenderTarget
• CreateWicBitmapRenderTarget
• CreateDCRenderTarget
• CreateCompatibleRenderTarget

It is not possible for an application to destroy these bitmaps. All of these bitmaps are bindable as bitmap targets. However not all of these bitmaps can be used as bitmap sources for methods.

CreateDxgiSurfaceRenderTarget will create a bitmap that is usable as a bitmap source if the DXGI surface is bindable as a shader resource view.

CreateCompatibleRenderTarget will always create bitmaps that are usable as a bitmap source.

will copy from the to the original bitmap associated with it. will copy from the original bitmap to the .

objects will be locked in the following circumstances:

• BeginDraw has been called and the currently selected target bitmap is a WIC bitmap.
• A WIC bitmap is set as the target of a device context after BeginDraw has been called and before EndDraw has been called.
• Any of the ID2D1Bitmap::Copy* methods are called with a WIC bitmap as either the source or destination.

objects will be unlocked in the following circumstances:

• EndDraw is called and the currently selected target bitmap is a WIC bitmap.
• A WIC bitmap is removed as the target of a device context between the calls to BeginDraw and EndDraw.
• Any of the ID2D1Bitmap::Copy* methods are called with a WIC bitmap as either the source or destination.

Direct2D will only lock bitmaps that are not currently locked.

Calling QueryInterface for ID2D1GdiInteropRenderTarget will always succeed. ID2D1GdiInteropRenderTarget::GetDC will return a device context corresponding to the currently bound target bitmap. GetDC will fail if the target bitmap was not created with the GDI_COMPATIBLE flag set.

will return if there are any outstanding references to the original target bitmap associated with the render target.

Although the target can be a command list, it cannot be any other type of image. It cannot be the output image of an effect.

This method is used in conjunction with . The D2D1::ComputeFlatteningTolerance helper API may be used to determine the proper flattening tolerance.

If the provided stroke style specifies a stroke transform type other than , then the stroke will be realized assuming the identity transform and a DPI of 96.

This method is used in conjunction with . The D2D1::ComputeFlatteningTolerance helper API may be used to determine the proper flattening tolerance.

If the provided stroke style specifies a stroke transform type other than , then the stroke will be realized assuming the identity transform and a DPI of 96.

This method respects all currently set state (transform, DPI, unit mode, target image, clips, layers); however, artifacts such as faceting may appear when rendering the realizations with a large effective scale (either via the transform or the DPI). Callers should create their realizations with an appropriate flattening tolerance using either D2D1_DEFAULT_FLATTENING_TOLERANCE or ComputeFlatteningTolerance to compensate for this.

Create an object by using the function.

 if (SUCCEEDED(hr))	
            { hr = ( , __uuidof(), reinterpret_cast<**>(&pDWriteFactory_) );	
            } 

An object holds state information, such as font loader registration and cached font data. This state can be shared or isolated. Shared is recommended for most applications because it saves memory. However, isolated can be useful in situations where you want to have a separate state for some objects.

This function registers a font collection loader with DirectWrite. The font collection loader interface, which should be implemented by a singleton object, handles enumerating font files in a font collection given a particular type of key. A given instance can only be registered once. Succeeding attempts will return an error, indicating that it has already been registered. Note that font file loader implementations must not register themselves with DirectWrite inside their constructors, and must not unregister themselves inside their destructors, because registration and unregistraton operations increment and decrement the object reference count respectively. Instead, registration and unregistration with DirectWrite of font file loaders should be performed outside of the font file loader implementation.

This function is provided for cases when an application or a document needs to use a private font without having to install it on the system. fontFileReferenceKey has to be unique only in the scope of the fontFileLoader used in this call.

This function registers a font file loader with DirectWrite. The font file loader interface, which should be implemented by a singleton object, handles loading font file resources of a particular type from a key. A given instance can only be registered once. Succeeding attempts will return an error, indicating that it has already been registered. Note that font file loader implementations must not register themselves with DirectWrite inside their constructors, and must not unregister themselves inside their destructors, because registration and unregistraton operations increment and decrement the object reference count respectively. Instead, registration and unregistration with DirectWrite of font file loaders should be performed outside of the font file loader implementation.

This function unregisters font file loader callbacks with the DirectWrite font system. You should implement the font file loader interface by a singleton object. Note that font file loader implementations must not register themselves with DirectWrite inside their constructors and must not unregister themselves in their destructors, because registration and unregistraton operations increment and decrement the object reference count respectively. Instead, registration and unregistration of font file loaders with DirectWrite should be performed outside of the font file loader implementation.

The resulting text layout should only be used for the intended resolution, and for cases where text scalability is desired CreateTextLayout should be used instead.

The ellipsis will be created using the current settings of the format, including base font, style, and any effects. Alternate omission signs can be created by the application by implementing .

The glyph run analysis object contains the results of analyzing the glyph run, including the positions of all the glyphs and references to all of the rasterized glyphs in the font cache.

The font file loader interface is recommended to be implemented by a singleton object. Note that font file loader implementations must not register themselves with DirectWrite factory inside their constructors and must not unregister themselves in their destructors, because registration and unregistraton operations increment and decrement the object reference count respectively. Instead, registration and unregistration of font file loaders with DirectWrite factory should be performed outside of the font file loader implementation as a separate step.

The font file loader interface is recommended to be implemented by a singleton object. Note that font file loader implementations must not register themselves with DirectWrite factory inside their constructors and must not unregister themselves in their destructors, because registration and unregistraton operations increment and decrement the object reference count respectively. Instead, registration and unregistration of font file loaders with DirectWrite factory should be performed outside of the font file loader implementation as a separate step.

The resource is closed when the last reference to fontFileStream is released.