R3 Draw - Line Related Commands

	Contents
Concept Arrow Box Line Line-cap Line-join Line-pattern Line-width Polygon Shape Triangle

See also:

• R3 View - Graphics Draw Dialect
• R3 Draw - Setup and Attribute Commands
• R3 Draw - Curve Related Commands
• R3 Draw - Shape Sub-Commands

Concept

This section describes draw commands that are related to lines, line segments, vertices, polygons and basic shapes.

All of these are part of the draw dialect, a REBOL sub-language for describing scalar vector graphics (SVG). The dialect consists of a number of command keywords, as listed in this document below.

Each command can be followed by its arguments, all of which are optional. Their names, datatypes, and descriptions are provided in the "argument" table for each command section below.

Arrow

Set the arrow mode.

Argument	Datatype	Description
arrow-mode	pair!	Possible numbers for combination. 0 for none, 1 for head, 2 for tail.
arrow-color	tuple!	color of the head/tail of the arrow

The arrow-mode numbers can be:

Arrow marks are drawn at end-points, but not between the line that closes polygons, closed splines, etc.

arrow 1x2
line 20x20 100x100

arrow 1x2
curve 50x50 300x50 50x300 300x300

arrow 1x2
spline 3 20x20 200x70 150x200 50x300 80x300 200x200

arrow 1x2
spline closed 3 20x20 200x70 150x200 50x300 80x300 200x200

arrow 1x2
polygon 20x20 200x70 150x200 50x300

arrow 1x2
box 20x20 150x200

Box

The box command provides a shortcut for a rectangular polygon. Only the upper-left and lower-right points are needed to draw the box.

Argument	Datatype	Description
upper-left-point	pair!
lower-right-point	pair!
corner-radius	decimal!	Rounds corners

A solid fill-pen will fill the box with that color.

fill-pen blue
box 20x20 200x200

An image used as the fill-pen will be repeated as the background.

fill-pen logo.gif
box 20x20 200x200

line widths, patterns, joins are fully supported.

pen red
line-pattern yellow 50 30
line-width 30
line-join round
box 50x50 350x350

Line

The line command draws a line between two points using the current pen, line-width, and line-pattern (if it is set).

Argument	Datatype	Description
point1	pair!	Starting point
point2	pair!	End point or vertex point
point3	pair!	Next point
...	pair!	More points

line 10x10 100x50

If more than two points are given multiple lines are drawn in a connected fashion:

line 10x10 20x50 30x0 4x40

Note that the end point is not connected to the first point. To do that, see the polygon command.

An example using pens and line attributes:

pen yellow line-width 8 line-pattern red 5 5
line 10x10 20x50 30x0 4x40

pen yellow  line-width 5  line-cap round
line 100x100 100x200 200X100 200X200

Line-cap

Sets the style that will be used when drawing the ends of lines.

Argument	Datatype	Description
mode	word!	Cap style

The cap style can be: butt, square, or rounded.

line-cap butt
pen yellow
line-width 1
line 20x20 150x20
line-width 3
line 20x40 150x40
line-width 5
line 20x60 150x60
line-width 7
line 20x80 150x80
line-width 9
line 20x100 150x100
line-width 11
line 20x120 150x120

translate 0x140

line-cap square
pen yellow
line-width 1
line 20x20 150x20
line-width 3
line 20x40 150x40
line-width 5
line 20x60 150x60
line-width 7
line 20x80 150x80
line-width 9
line 20x100 150x100
line-width 11
line 20x120 150x120

translate 160x-70

line-cap rounded
pen yellow
line-width 1
line 20x20 150x20
line-width 3
line 20x40 150x40
line-width 5
line 20x60 150x60
line-width 7
line 20x80 150x80
line-width 9
line 20x100 150x100
line-width 11
line 20x120 150x120

Line-join

Sets the style that will be used where lines are joined.

Argument	Datatype	Description
mode	word!	Join style

The join style can be: miter, miter-bevel, round, and bevel.

pen yellow
line-width 15

line-join miter
polygon 20x20 180x130 10x100

translate 0x140

line-join miter-bevel
polygon 20x20 180x130 10x100

translate 200x-140

line-join round
polygon 20x20 180x130 10x100

translate 0x140
line-join bevel
polygon 20x20 180x130 10x100

Additional notes about LINE-CAP and LINE-JOIN

How are lines drawn:

line	draws single lines (even if multiple line points is specified)
spline	draws 'connected' lines but the 'head' and 'tail' is splitted (until you specify CLOSED keyword)
polygon	always draws 'connected' lines in form of closed shape

Effects of LINE-CAP and LINE-JOIN:

line	shape of 'head' and 'tail' is affected by LINE-CAP mode
spline	shape of 'line joins' is affected by LINE-JOIN mode; if CLOSED is defined shape of 'head' and 'tail' is affected by LINE-CAP mode
polygon	shape of all 'line joins' is affected by LINE-JOIN mode

Line-pattern

Set the line pattern. The line pattern will remain in effect until it is set to a new value or disabled using off.

Argument	Datatype	Description
dash-color	tuple!
stroke-size	decimal!
dash-size	decimal!
stroke-size	decimal!
dash-size	decimal!
...	decimal!

Set it to 5 of yellow and 5 of red.

anti-alias off
pen yellow
line-pattern red 5 5
line-width 3
box 20x20 200x200

To draw a dashed line, with a transparent pen, the off pen color must come first.

To clear the current line pattern, set it to off.

anti-alias off
pen off
line-width 4
line-pattern yellow 7 2
box 20x20 200x200
line-pattern off
box 40x40 240x240
pen blue
box 60x60 260x260

Complex patterns can be specified by repeating values for stroke and dash sizes

anti-alias off
line-width 4
pen blue
line-pattern red 7 2 4 4 3 6
box 20x20 380x380
pen red
line-pattern yellow 1 5
box 40x40 360x360
line-pattern off
box 60x60 340x340
line-pattern blue 10 20 40 80
box 80x80 320x320
line-pattern green 1 4 4 4
box 100x100 300x300
line-pattern yellow 4 8 12 16
box 120x120 280x280
line-pattern yellow 4 4
box 140x140 260x260

Line-width

Sets the line width.

Argument	Datatype	Description
width	number!	Zero, or negative values, produce a line-width of 1.
fixed-width	word!	If fixed is specified. Line width is not changed during scaling.

Default dynamic line width example:

line-width 3
pen yellow
reset-matrix
scale 1.5 1.5
translate 100x100
polygon 50x5 62x40 95x40 68x60 80x95 50x74 20x95 32x60 5x40 38x40

reset-matrix        
translate 100x100
polygon 50x5 62x40 95x40 68x60 80x95 50x74 20x95 32x60 5x40 38x40

reset-matrix
scale .5 .5
translate 100x100
polygon 50x5 62x40 95x40 68x60 80x95 50x74 20x95 32x60 5x40 38x40

reset-matrix
scale .2 .2
translate 100x100
polygon 50x5 62x40 95x40 68x60 80x95 50x74 20x95 32x60 5x40 38x40

Fixed line width example:

line-width 3 fixed
pen yellow
reset-matrix
scale 1.5 1.5
translate 100x100
polygon 50x5 62x40 95x40 68x60 80x95 50x74 20x95 32x60 5x40 38x40

reset-matrix        
translate 100x100
polygon 50x5 62x40 95x40 68x60 80x95 50x74 20x95 32x60 5x40 38x40

reset-matrix
scale .5 .5
translate 100x100
polygon 50x5 62x40 95x40 68x60 80x95 50x74 20x95 32x60 5x40 38x40

reset-matrix
scale .2 .2
translate 100x100
polygon 50x5 62x40 95x40 68x60 80x95 50x74 20x95 32x60 5x40 38x40

Polygon

The polygon command lets you draw a closed area of line segments. It is similar to the line command, but the first and last points are connected.

Argument	Datatype	Description
point1	pair!
point2	pair!
point3	pair!
...	pair!

polygon 100x100 100x200 200X100 200X200

pen yellow fill-pen orange
line-width 5 line-join round
polygon 100x100 100x200 200X100 200X200

Shape

Draws shapes using the SHAPE sub-dialect

Argument	Datatype	Description
shape-cmd-block	block!

For a description of the SHAPE sub-commands along with many examples, see R3 Draw - Shape Sub-Commands.

A selected example is:

pen yellow
line-width 3
shape [
    move 0x399
    line 42x357
    arc 84x315 25 20 -45 sweep
    line 126x273
    arc  168x231 25 40 -45 sweep
    line 210x189
    arc  252x147 25 60 -45 sweep
    line 294x105
    arc  336x63 25 80 -45 sweep
    line 399x0
    move 0x0
]

Triangle

The TRIANGLE command provides a shortcut for a triangular polygon with optional shading parameters (Gouraud shading). The three vertices of the triangle are used to specify it.

Argument	Datatype	Description
vertex1	pair!
vertex2	pair!
vertex3	pair!
color1	tuple!
color2	tuple!
color3	tuple!
dilation	decimal!	This is useful for eliminating anitaliased edges

Simple triangle:

fill-pen red
triangle 50x150 150x50 150x150

A group of triangles. This should make it easy to see where each triangle is:

pen off

triangle 50x150 150x50 150x150 red green blue
triangle 150x50 250x150 150x150 green yellow blue
triangle 250x150 150x350 150x150 yellow orange blue
triangle 150x350 50x150 150x150 orange red blue
translate 200x-15

The same triangle group but slightly rotated to show for what the dilation parameter can be used:

pen off
rotate 5

triangle 50x150 150x50 150x150 red green blue
triangle 150x50 250x150 150x150 green yellow blue
triangle 250x150 150x350 150x150 yellow orange blue
triangle 150x350 50x150 150x150 orange red blue
translate 200x-15

triangle 50x150 150x50 150x150 red green blue 0.33
triangle 150x50 250x150 150x150 green yellow blue 0.33
triangle 250x150 150x350 150x150 yellow orange blue 0.33
triangle 150x350 50x150 150x150 orange red blue 0.33

This gives you a much more subtle blending in the middle:

pen off
triangle 50x150  150x50  150x150 red    green  gray
triangle 150x50  250x150 150x150 green  yellow gray
triangle 250x150 150x350 150x150 yellow orange gray
triangle 150x350 50x150  150x150 orange red    gray

And this shows simple highlighting/shading:

pen off
triangle 50x150  150x50  150x150 water sky   sky
triangle 150x50  250x150 150x150 water coal  sky
triangle 250x150 150x350 150x150 coal  coal  sky
triangle 150x350 50x150  150x150 coal  water sky