TextureBrush::TextureBrush(Image*,WrapMode,constRect&) method (gdiplusbrush.h)

Article
08/31/2022

Creates a TextureBrush object based on an image, a wrap mode, and a defining rectangle.

Syntax

void TextureBrush(
  [in]      Image        *image,
  [in]      WrapMode     wrapMode,
  [in, ref] const Rect & dstRect
);

Parameters

[in] image

Type: Image*

Pointer to an Image object that contains the bitmap of the image to use.

[in] wrapMode

Type: WrapMode

Element of the WrapMode enumeration that specifies how repeated copies of an image are used to tile an area when it is painted with this texture brush.

[in, ref] dstRect

Type: const Rect

Reference to a rectangle that defines the size of this texture brush and the portion of the image to be used by this texture brush. If the Image object is created from a metafile, the brush uses the entire image, which is scaled to fit the size of the brush.

Return value

None

Remarks

The width and height of a texture brush are defined by the width and height of the dstRect rectangle. A texture brush is always oriented at (0, 0). The upper-left point, width, and height of the rectangle specify the starting point, width, and height of the portion of the image to be used by a texture brush.

How this constructor uses the dstRect rectangle with nonmetafile images

If the dimensions of the dstRect rectangle are smaller than those of the image on which the brush is based, the brush's image is cropped — it is a portion of the image. If the dimensions of the dstRect rectangle are equal to those of the image, the brush's image is identical to the image. The dstRect rectangle must not include areas outside the dimensions of the image. Doing so will either produce unpredictable behavior or generate a run-time error. For example, suppose you have an image that is 256 ×256 pixels and you create a TextureBrush object based on this image, passing as the dstRect parameter. The brush will use the lower left portion of the image. The lower-left corner of this portion is also the lower-left corner of the image. Now suppose that you create another TextureBrush object based on the same image, passing as the dstRect parameter. Note that this rectangle has its uppermost coordinate at 157 instead of 156. This rectangle extends one unit beyond the height of the image and will most likely generate an access violation.

How this constructor uses the dstRect rectangle with metafile images

If the dimensions of the dstRect rectangle are different from those of the image, the brush's image is scaled smaller or larger as needed to fit the rectangle. For example, suppose you have a metafile image that is 256 ×256 pixels and you create a TextureBrush object, passing as the dstRect parameter. The brush's image will include all of the metafile image but will be scaled to fit the brush: It will be squished vertically and stretched horizontally. If the dimensions of the rectangle are equal to those of the image, the brush's image is identical to the image.

How this constructor uses the wrap mode

An area that extends beyond the boundaries of the brush is tiled with repeated copies of the brush. A texture brush may have alternate tiles flipped in a certain direction, as specified by the wrap mode. Flipping has the effect of reversing the brush's image.

Requirements

Requirement	Value
Minimum supported client	Windows XP, Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	gdiplusbrush.h (include Gdiplus.h)
Library	Gdiplus.lib
DLL	Gdiplus.dll