Edit

Share via

ID2D1RenderTarget::PushAxisAlignedClip(constD2D1_RECT_F*,D2D1_ANTIALIAS_MODE) method (d2d1.h)

  • Article

Specifies a rectangle to which all subsequent drawing operations are clipped.

Syntax

void PushAxisAlignedClip(
  const D2D1_RECT_F   *clipRect,
  D2D1_ANTIALIAS_MODE antialiasMode
);

Parameters

clipRect

Type: [in] const D2D1_RECT_F*

The size and position of the clipping area, in device-independent pixels.

antialiasMode

Type: [in] D2D1_ANTIALIAS_MODE

The antialiasing mode that is used to draw the edges of clip rects that have subpixel boundaries, and to blend the clip with the scene contents. The blending is performed once when the PopAxisAlignedClip method is called, and does not apply to each primitive within the layer.

Return value

None

Remarks

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. Illustration of a rectangle (render target)
  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. Illustration of a rotated rectangle (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. Illustration of a small blue rectangle (transformed clipRect) inside a rotated rectangle
  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. Illustration of a green bounding box around a small blue rectangle inside a rotated rectangle
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 ID2D1RenderTarget::EndDraw or ID2D1RenderTarget::Flush methods.

Requirements

Requirement Value
Target Platform Windows
Header d2d1.h (include D2d1.h)
Library D2d1.lib
DLL D2d1.dll

See also

ID2D1RenderTarget