D2DefLine command

Requires: Direct2D.lg32

Purpose

Sets the appearance of the line for use with drawing commands.

Syntax

D2DefLine [style% ] [,thickness!] [,dashOffset!][,miterLimit!]
D2DefLine [D2Stroke] [,thickness!]

Style%	: integer expression
D2Stroke	: object expression
thickness!, dashOffset!, miterLimit!	: float expression

Description

D2DefLine sets the current stroke (line object) to a previously created D2Stroke object - created with D2Stroke() - or creates a stroke from the style% parameter. By omitting the first parameter and passing a value to thickness! only the line thickness is changed.

If the first argument (style) is a 32-bit integer D2DefLine creates and selects a new line object. The line objects are for use with D2 drawing commands. Creating a new line object does not require a render target (D2SetRT is not required).

The first parameter style% determines the appearance of the line as follows:

Style% = 0: solid line
style% = 1: dashed line, ----
style% = 2: dotted line, ....
style% = 3: dash-dot line, -.-.-.
style% = 4: dash-dot-dot line, -..-..

The start and end of the line default to rounded caps. The start- and end caps can be changed by ‘or-ing’ the following values to the style% parameter:

Style% = style% Or 256: start and end of the line will be square
style% = style% Or 512: start and end of the line will be flat

The joining of the lines default to round as well. The style of the joining of lines can be changed by ‘or-ing’ the following values to the style% parameter:

Style% = style% Or 4096: a bevel joining
style% = style% Or 8192: a miter joining

When using the style% parameter variant of D2DefLine the application may optionally pass a value for the dash offset dashOffset! and the miter. When D2DefLine is used with a D2Stroke object, the dash offset and miter are already included in the stroke object.

The thickness! parameter defines the width of the line, in device-independent pixels. The value must be greater than or equal to 0.0 (default is 1.0). To prevent the drawing of a pixel or lines set thickness to zero. This gives the same result as setting the GFA-BASIC command DefLine to PS_NUL, so replace DefLine PS_NUL to the Direct2D equivalent D2DefLine , 0).

When using D2DefLine omit the first parameter if the style doesn't change. Specifying an integer value from 0 .. 4 for the first parameter will always result in creating a new D2Stroke object. Omit this parameter if the style doesn't change. Passing an existing D2Stroke object won't hurt, because this will not create a new stroke object. You might want to cache D2DefLine stroke-objects by creating them in the program's initialization code.

Example

' D2DefLine sample

' (dpi-unaware)

$Library "direct2d"

Global Object Win1RT

OpenW 1, 0, 0, 320, 260, ~15

' Rendertarget same size as clientarea

' Here: Create Win_1 render target resources

Set Win1RT = D2GetRT(Me.hWnd, _X, _Y)

Sleep

Until Me Is Nothing

Sub Win_1_Paint

D2BeginDraw Win1RT, D2C_White

' Optionally, you may pass D2Line a brush to draw with.

' Otherwise, line is drawn using D2ForeColor.

Local Int i

For i = 0 To 4 ' five styles

D2DefLine i ' Line width = 1.0

D2Line 10, 5 + i * 10, _X - 10, 5 + i * 10

For i = 0 To 4

D2DefLine i Or 256, 4

D2Line 10, 75 + i * 10, _X - 10, 75 + i * 10

For i = 0 To 4

D2DefLine i Or 512, 1

D2Line 10, 145 + i * 10, _X - 10, 145 + i * 10

D2EndDraw

EndSub

Remarks

It seems, not all styles can be combined with a different end or start caps.

Direct2D refers to a line as a stroke. A stroke is created by calling the ID2D1Factory::CreateStrokeStyle method. The GB Direct2D library stores the stroke object in a global Object variable which is used in the drawing functions. Setting a stroke does not require a render target; D2SetRT is not required. The current line object is released by D2EndDraw. The thickness of the line (stroke) is also saved in a global variable. Both values are invalidated (reset) by D2EndDraw.