TextureBrush.TextureBrush(Image*, Rect, ImageAttributes*) constructor

  • Article

Applies to: desktop apps only

Creates a TextureBrush object based on an image, a defining rectangle, and a set of image properties.

Syntax

TextureBrush(
  [in]       Image *image,
  [in, ref]  Rect &dstRect,
  [in]       ImageAttributes *imageAttributes
);

Parameters

  • image [in]
    Type: Image*

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

  • dstRect [in, ref]
    Type: 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.

  • imageAttributes [in]
    Type: ImageAttributes*

    Optional. Pointer to an ImageAttributes object that contains properties of the image. The default value is NULL.

Remarks

The width and height of the dstRect rectangle define the width and height of a texture brush. 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 dstRectrectangle 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.

Requirements

Minimum supported client

 Windows XP, Windows 2000 Professional

Minimum supported server

 Windows 2000 Server

Product

 GDI+ 1.0

Header

 Gdiplusbrush.h (include Gdiplus.h)

Library

 Gdiplus.lib

DLL

 Gdiplus.dll

See also

TextureBrush

Image

ImageAttributes

Rect

Filling a Shape with an Image Texture

Brushes and Filled Shapes

 

 

Send comments about this topic to Microsoft

Build date: 3/6/2012