D2Brush function

Requires: Direct2D.lg32

Purpose

Creates and returns a Direct2D brush for the current render target.

Syntax

Set brObj = D2Brush(arg [,OffX!][,OffY!][,Opacity!][,fUseDef])

arg	: integer expression or string expression or object expression
brObj	: Object variable
OffX!, OffY!, Opacity!	: floating-point expression
fUseDef	: boolean expression

Description

Before using D2Brush() make sure the proper render target is activated using D2SetRT.

A Direct2D brush can be created form different sources and depends on the type of the argument arg.

When arg specifies an integer the argument is interpreted as an ARGB color value and based on that color a solid color brush is returned. The Opacity! parameter may be given a value between 0.0 and 1.0 (default). OffX and OffY have no meaning.
When arg is a string it is interpreted as a filename or :Files resource name. The function loads the image file into a D2Bitmap object and than creates a D2Brush.
When arg is an object it must specify a D2Bitmap object which D2Brush() converts into a D2Brush object.

The brush object returned must be assigned to an Object variable, which can then be used with the drawing commands or with D2DefFill to set the current active brush.

In case the brush is created from an image the OffX and OffY parameters should be set to the shape's position the brush is used for. This isn't critical for simple pattern brushes, but images used as a brush need their offset set to top-left corner of the shape. By default a bitmap brush maps to the origin of the coordinate space (0,0), unless the coordinate space is moved (translated) using D2Transform.

The created brush (from an image) may also use Direct2D defaults for the D2D1_BITMAP_BRUSH_PROPERTIES by passing True for fUseDef, see Remarks.

By default, the Opacity is set to 1.0, but it can be any value between 0.0 and 1.0.

Example

' D2Brush sample (dpi-unaware)

$Library "direct2d"

Global Object Win1RT

OpenW 1, 0, 0, 320, 300, ~15

Global Object brHatch, brCol, bmpFish, brFish

Set Win1RT = D2GetRT()

' Here: create render target resources

' Brush from a :Files resource image

Set brHatch = D2Brush(":Hatch0")

' Brush from an argb color, opacity = 0.5

Set brCol = D2Brush(ARGB(0, 128, 0, 0), , , 0.5)

' Brush from a D2Bitmap, first get D2Bitmap

Set bmpFish = D2Bitmap(":goldfish")

' Create a brush and pass it the targetshape's coordinates

Set brFish = D2Brush(bmpFish, 10, 110)

Sleep

Until Me Is Nothing

Sub Win_1_Paint

D2BeginDraw Win1RT, D2C_White

' Filled rectangle with a hatch brush

D2DefFill brHatch

D2Box 15, 10, 100, 100

D2PBox 15, 10, 100, 100

' Colored box with brush's Opacity = 0.5

D2PBox 80, 10, 210, 100, brCol

' Box filled with goldfish brush

D2PBox 10, 110, 210, 110 + 200, brFish

D2EndDraw

EndSub

Sub Win_1_ReSize

D2ResizeRT Win1RT, _X, _Y

EndSub

NOTE: The above example will not run as it relies on an embedded file which is not present in the syntax. The programme with full resources can be found in GFABASIC/Samples/Direct2D/D2Brush.g32.

Remarks

A D2Brush is obtained from the render target COM object and can only be used on that render target. An application should not use a Direct2D brush from a different render target.

When converting a Direct2D bitmap to a Direct2D brush the ID2D1RenderTarget::CreateBitmapBrush method is invoked using the following values:

The extend modes are set to D2D1_EXTEND_MODE_WRAP and interpolation mode is set to D2D1_BITMAP_INTERPOLATION_MODE_NEAREST_NEIGHBOR. The application may use the Direct2D's defaults by setting fUseDef to True. In this case the extend modes are D2D1_EXTEND_MODE_CLAMP and the interpolation mode is D2D1_BITMAP_INTERPOLATION_MODE_LINEAR.