DRAW Dialect Reference

Preliminary Document
Subject to Change
Updated: 11-Aug-2005

Contents:

The DRAW dialect

DRAW commands are a dialect of REBOL.

DRAW blocks consist of a sequence of commands followed by arguments. DRAW commands may set attributes and modes that are used by commands that follow.

The DRAW block is not reduced, but word lookup is allowed. This is a change from prior versions of REBOL.

This change allows drawings that use the DRAW block to be embedded in messages (such as in View desktop icons, IOS conference, or AltME messages) without security concerns (because normal REBOL functions cannot be executed).

For example, this is allowed (because only words need to be evaluated):

draw [pen color box offset margin]

But this is not allowed (because block evaluation is needed):

draw [pen color / 2  box offset offset + size]

If you need that, you will need to perform REDUCE or COMPOSE yourself, prior to using the DRAW block:

reduce  ['pen color / 2  'box offset offset + size]
compose [pen (color / 2)  box offset (offset + size)]

Trying Examples

To try any of the examples below, you can write a program as simple as this:

view layout [box 400x400 black effect [draw [...]]]

Just cut and paste the DRAW command into the ... block above. For example:

view layout [box 400x400 black effect [draw [
    fill-pen 3 0x0 0 400 0 1 1 blue blue green red red
    box 0x0 400x400
]]]

You can also create a simple test function like this:

test: func [spec] [
    view layout [box 400x400 black effect [draw spec]]
]

test [fill-pen radial 0x0 0 400 0 1 1 blue green red red box]

Or add another level so you can just copy examples to the clipboard and read them automatically to run them:

draw-test: does [test load read clipboard://]

Alpha Channel

Anywhere you specify a color, you can provide alpha channel information to control the transparency of the result. For example:

pen navy fill-pen yellow
box 20x20 80x80
fill-pen 0.200.0.150
pen maroon
box 30x30 90x90

Or:

image logo.gif 50x50 200x150 pen none line-width 0
fill-pen 200.0.0.128 box 50x50  100x150
fill-pen 0.200.0.128 box 100x50 150x150
fill-pen 0.0.200.128 box 150x50 200x150

Standard Commands

ANTI-ALIAS

Turns anti-aliasing on or off; it is on by default

Arg	Type	Description	Values
active	[logic!]	The new value for anti-aliasing behavior

Notes and Examples

Compare this:

anti-alias off  line-width 10  circle 200x200 100

to this:

anti-alias on   line-width 10  circle 200x200 100

The ANTI-ALIAS command currently affects the entire DRAW effect; the last value you set it to is what will be used for all draw commands in the block. (TBD will be changing to keeping last setting in effect until changed)

anti-alias off  line-width 10  circle 150x150 100
anti-alias on   line-width 10  circle 250x250 100

ARC

The ARC command draws a partial section of an ellipse (or circle).

Arg	Type	Description	Values
center	[pair!]	The center of the circle
radius	[pair!]	The radius of the circle
angle-begin	[decimal!]	The angle where the arc begins, in degrees
angle-length	[decimal!]	The length of the arc in degrees
closed	[word!]	Optional, must be the word closed	closed - close the arc

Notes and Examples

For angle-begin, 0° is to right of the center point, on the horizontal axis.

Arcs are drawn in a clockwise direction from the angle-begin point.

Simple open arcs, beginning at 0°.

arc 200x25  100x100 0  90
arc 200x125 100x100 0 135
arc 200x250 100x100 0 180

Simple open arcs, beginning at different angles, but all with the same length.

arc 200x25  100x100 0  120 
arc 200x125 100x100 45 120
arc 200x250 100x100 90 120

A closed arc. The arcs is closed by drawing lines to the center point of the circle that defines the arc.

arc 100x100 100x100 0 90  closed

fill-pen red    arc 100x100 90x90 135 180
fill-pen green  arc 300x100 90x90 225 180
fill-pen blue   arc 100x300 90x90 45  180
fill-pen yellow arc 300x300 90x90 315 180

fill-pen red    arc 150x250 90x90 0   180
fill-pen green  arc 150x150 90x90 90  180
fill-pen blue   arc 250x150 90x90 180 180
fill-pen yellow arc 250x250 90x90 270 180

Closed arcs are an easy way to draw wedges for pie charts.

fill-pen red    arc 200x200 90x90 0   90 closed
fill-pen green  arc 200x200 90x90 90  90 closed
fill-pen blue   arc 200x200 90x90 180 90 closed
fill-pen yellow arc 200x200 90x90 270 90 closed

By changing the center point, you can draw exploded pie charts.

pen white line-width 2
fill-pen red    arc 204x204 150x150   0  90 closed
fill-pen green  arc 196x204 150x150  90  30 closed
fill-pen blue   arc 180x190 150x150 120 150 closed
fill-pen yellow arc 204x196 150x150 270  90 closed

See: Viewtop REBOL/tests/arc-angle.r

ARROW

Set the arrow mode

Arg	Type	Description	Values
arrow-mode	[pair!]	Possible numbers for combination in pair!	0 - none 1 - head 2 - tail

Notes and Examples

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.

Arg	Type	Description	Values
upper-left-point	[pair!]
lower-right-point	[pair!]
corner-radius	[decimal!]	Rounds corners

Notes and Examples

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 yellow
line-pattern 50 30
line-width 30
line-join round
box 50x50 350x350

CIRCLE

Draws a circle or ellipse

Arg	Type	Description	Values
center	[Pair!]
radius-x	[decimal!]	Used for both X and Y radii if radius-y isn't provided
radius-y	[decimal!]	Optional. Used to create an ellipse

Notes and Examples

A simple circle

pen yellow line-width 5 circle 200x200 150

A circle using an image as the pen

pen logo.gif circle 200x200 150

A circle using an image as the fill-pen

line-width 2 pen yellow fill-pen logo.gif
circle 200x200 150

CLIP

Specifies a clipping region; drawing will only occur inside the region.

Arg	Type	Description	Values
upper-left-point	[pair!]	The upper-left point of the bounding box defining the clipping region.
lower-right-point	[pair!]	The lower-right point of the bounding box defining the clipping region.

Notes and Examples

The box would go to 200x200, but we clip it.

line-width 2 pen yellow fill-pen blue
clip 10x10 70x90
box 20x20 200x200

Clipping other shapes can produce interesting effects.

pen yellow fill-pen red
clip 50x50 125x200
circle 50x50 100

To turn clipping off, use none as the argument to clip.

pen yellow  fill-pen red   clip 50x50 125x200
circle 50x50 100
pen green   fill-pen blue  clip none
circle 125x75 50

CURVE

Draws a smooth Bezier curve to fit the points provided.

Arg	Type	Description	Values
point1	[pair!]	End point A
point2	[pair!]	Control point A
point3	[pair!]	End point B, or control point B
point4	[pair!]	End point B

Notes and Examples

Either three or four points should be specified. With three points, it is a cubic Bezier curve with two endpoints and one control point. With four points it allows two control points, and it can create more complicated curves such as circular and elliptical arcs.

A curve with one control point

curve 20x150 60x250 200x50

A curve with two control points

curve 20x20 80x300 140x20 200x300

A thick curve with a patterened line

pen yellow red line-pattern 5 5 line-width 4
curve 20x150 60x250 200x50

A thick curve with two control points, a patterened line, and a fill pen.

pen yellow red line-pattern 5 5 line-width 4 fill-pen blue
curve 20x20 80x300 140x20 200x300

ELLIPSE

Draws an ellipse

Arg	Type	Description	Values
center	[pair!]	The center of the ellipse
radius	[pair!]	X and Y radius is specified by a pair! which is different than the CIRCLE command

Notes and Examples

Three overlapping ellipses

fill-pen red   ellipse 100x125 50x100
fill-pen white ellipse 200x200 100x100
fill-pen blue  ellipse 275x300 100x50

FILL-PEN

Sets the color for area filling. The fill-pen color will remain in effect until it is set again.

Arg	Type	Description	Values
color	[tuple!]
grad-mode	[word!]	The gradient style	radial conic diamond linear diagonal cubic
grad-offset	[pair!]
grad-start-rng	[decimal!]
grad-stop-rng	[decimal!]
grad-angle	[decimal!]
grad-scale-x	[decimal!]
grad-scale-y	[decimal!]
grad-color1	[tuple!]
grad-color2	[tuple!]
grad-color3	[tuple!]
...	-	Any number of colors may be used.
image	[image!]	Fill pattern

Notes and Examples

PENDING! We need a LOT more docs on this, particularly with regard to gradient fills.

fill-pen blue

The fill-pen can also be used to set a gradient fill pattern with any number of colors.

fill-pen radial 200x200 0 100 0 1 1 blue green red yellow  box 0x0 400x400

fill-pen radial 200x200 0 200 0 1 1 blue green red yellow  box 0x0 400x400

fill-pen radial 200x200 0 300 0 1 1 blue green red yellow  box 0x0 400x400

fill-pen radial 200x200 0 400 0 1 1 blue green red yellow  box 0x0 400x400

fill-pen linear 0x0 0 300 25 1 1 red yellow green cyan blue magenta
box 100x100 300x300

To clear the fill-pen, set it to none.

fill-pen blue  box 100x100 200x200
fill-pen none  box 200x200 350x350

fill-pen radial 200x200 0 50 0 1 1 0.32.200 0.92.250 0.128.255 0.64.225 box 0x0 400x400

FILL-RULE

Determines the algorithm used to determine what area to fill, if a path that intersects itself or one subpath encloses another. For non-intersecting paths, you shouldn't need to use this.

Arg	Type	Description	Values
mode	[word!]	Fill algorithm	non-zero - This rule determines the "insideness" of a point on the canvas by drawing a ray from that point to infinity in any direction and then examining the places where a segment of the shape crosses the ray. Starting with a count of zero, add one each time a path segment crosses the ray from left to right and subtract one each time a path segment crosses the ray from right to left. After counting the crossings, if the result is zero then the point is outside the path. Otherwise, it is inside. even-odd - This rule determines the "insideness" of a point on the canvas by drawing a ray from that point to infinity in any direction and counting the number of path segments from the given shape that the ray crosses. If this number is odd, the point is inside; if even, the point is outside.

Notes and Examples

The following page has drawings that drawing illustrates the rules:

http://www.w3.org/TR/SVG/painting.html#FillProperties

FONT

Sets the current font used for drawing text.

Arg	Type	Description	Values
font-object	[object!]

Notes and Examples

To use fonts, you create them outside the draw block, then reference them. For security reasons, the draw dialect doesn't allow evaluation, but it does allow word lookup; that's how fonts can be referenced.

font-A: make face/font [style: 'bold size: 16]
font-B: make face/font [style: [bold italic] size: 20]
font-C: make face/font [style: [bold italic underline] size: 24]

The font setting stays in effect until it is set to another value. You can't reset the font by setting it to none, but you can set it to the REBOL face/font value.

text "Default font" 50x75

font font-A text "16 pt, bold" 50x125

font font-B text "20 pt, bold italic" 50x175

font font-C text "24 pt, bold italic underline" 50x225

font face/font text "face/font" 50x275

GAMMA

Sets the gamma correction value. Useful for antialiased graphics.

Arg	Type	Description	Values
gamma-value	[decimal!]

Notes and Examples

See also: http://www.poynton.com/notes/Timo/index.html

INVERT-MATRIX

Applies an algebraic matrix inversion operation on the current transformation matrix.

IMAGE

Draws an image, with optional scaling, borders, and color keying.

Arg	Type	Description	Values
image	[image!]
upper-left-point	[pair!]	Optional
upper-right-point	[pair!]	Optional; this is the lower-right point if only two points are provided
lower-left-point	[pair!]	Optional
lower-right-point	[pair!]	Optional
key-color	[tuple!]	Optional; color to be rendered as transparent
border	[word!]	Optional; must be the word 'border

Notes and Examples

A normal image:

image logo.gif

An image at a specific location:

image logo.gif 100x100

An scaled image at a specific location:

image logo.gif 100x100 300x200

An image with a border using line attributes.

pen yellow red line-width 5 line-pattern 5 5
image logo.gif 100x100 border

An image with a patterened border and a key color.

pen yellow red line-width 5 line-pattern 5 5
image logo.gif 100x100 254.254.254 border

If you provide four points, the image will be scaled to fit those positions. This can be use to create perspective images or other simple distortions:

image logo.gif 50x100 400x00 400x400 50x200

image logo.gif 10x10 350x200 250x300 50x300

IMAGE-FILTER

Specifies type of algorithm used when an image is scaled.

Arg	Type	Description	Values
filter-type	[word!]	Filter algorithm	nearest - Uses 'nearest neighbour' algorithm to scale image bilinear - Uses 'bilinear filtering' for scaling

Notes and Examples

LINE

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

Arg	Type	Description	Values
point1	[pair!]
point2	[pair!]
point3	[pair!]
...	-

Notes and Examples

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 red line-width 8 line-pattern 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.

Arg	Type	Description	Values
mode	[word!]	Cap style	butt square round

Notes and Examples

line-width 15
line-cap butt
pen red     line 20x20 150x20
pen yellow  line 150x20 150x150
pen red     line 150x150 20x150
pen yellow  line 20x150 20x20

line-width 15
line-cap square
pen red     line 20x20 150x20
pen yellow  line 150x20 150x150
pen red     line 150x150 20x150
pen yellow  line 20x150 20x20

line-width 15
line-cap round
pen red     line 20x20 150x20
pen yellow  line 150x20 150x150
pen red     line 150x150 20x150
pen yellow  line 20x150 20x20

LINE-JOIN

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

Arg	Type	Description	Values
mode	[word!]	Join style	miter miter-bevel round bevel

Notes and Examples

This will show four boxes with different line-join styles, so you can compare them. The thick, patterened, line helps show how the joins work.

line-pattern 130 130
pen red yellow
line-width 15
line-join miter        box 20x20 150x150
line-join miter-bevel  box 220x20 350x150
line-join round        box 22x220 150x350
line-join bevel        box 220x220 350x350

LINE-PATTERN

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

Arg	Type	Description	Values
stroke-size	[decimal!]
dash-size	[decimal!]
stroke-size	[decimal!]
dash-size	[decimal!]
...	-

Notes and Examples

Set it to 5 of yellow and 5 of red.

pen yellow red
line-pattern 5 5

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

pen none yellow
line-pattern 7 2

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

line-pattern none

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

pen blue red
line-pattern 7 2 4 4 3 6

line-width 3
pen red yellow
line-pattern 1 5
line 10x10 390x10
;line-pattern none
line 10x20 390x20
line 10x30 390x30
line-pattern 1 4 4 4
box 10x40 390x80

line-width 3  pen red yellow
line-pattern 1 5  line 10x10 390x10
line-pattern 4 4  line 10x20 390x20

LINE-WIDTH

Sets the line width.

Arg	Type	Description	Values
width	[number!]	Zero, or negative values, produce a line-width of 1

Notes and Examples

line-width .5 line 10x10 20x50 30x0 4x40
line-width 3  line 50x50 70x100 80x50 25x90
line-width 15 line 150x150 200x300 300x150 125x250

MATRIX

Premultiply the current transformation matrix with the given block.

Arg	Type	Description	Values
matrix-setup	[block!]

Notes and Examples

MATRIX [a b c d e f]

The block values are used internally for building following transformation matrix:

|a c e| |b d f| |0 0 1|

For more information about transformations see: http://www.w3.org/TR/SVG/coords.html#EstablishingANewUserSpace

PEN

Sets the foreground color and background color for outline rendering (line, circle, polygon, curve, box).

Arg	Type	Description	Values
stroke-color	[tuple!]	Primary line color
dash-color	[tuple!]	Used for patterned lines
image	[image!]

Notes and Examples

The colors can include an alpha channel value for transparency.

Setting pen to none will set the pen color to fully transparent.

pen yellow  line-width 5  box 20x20 200x200
pen yellow red  line-width 5 line-pattern 20 10 box 50x50 250x250

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.

Arg	Type	Description	Values
point1	[pair!]
point2	[pair!]
point3	[pair!]
...	-

Notes and Examples

polygon 100x100 100x200 200X100 200X200

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

PUSH

Stores the current matrix setup in stack

Arg	Type	Description	Values
draw-block	[block!]

Notes and Examples

The new AGG based DRAW implementation uses a transformation matrix stack for storing different matrix setups. If the PUSH command is used, the current transformation matrix is copied into the stack. You can then change the current transformation matrix inside the PUSH command block but all commands AFTER the PUSH command block will use the matrix setup stored by the PUSH command.

line-width 3
pen red
transform 200x200 30 1 1 0x0
box 100x100 300x300
push [
    reset-matrix
    pen green
    box 100x100 300x300
    transform 200x200 60 1 1 0x0
    pen blue
    box 100x100 300x300
]
pen white
box 150x150 250x250

RESET-MATRIX

Resets the current transformation matrix to its default values.

Notes and Examples

The default transformation matrix is a unit matrix. That is:

|1 0 0| |0 1 0| |0 0 1|

If you make changes with scale, skew, or rotate, this is how you would reset them.

ROTATE

Sets the clockwise rotation, in degrees, for drawing commands.

Arg	Type	Description	Values
angle	[decimal!]

Notes and Examples

Negative numbers can be used for counter-clockwise rotation.

fill-pen blue box 100x100 300x300
rotate  30 fill-pen red box 100x100 300x300
rotate -60 fill-pen yellow box 100x100 300x300

See also: http://www.w3.org/TR/SVG/coords.html#EstablishingANewUserSpace

SCALE

Sets the scale for drawing commands.

Arg	Type	Description	Values
scale-x	[decimal!]
scale-y	[decimal!]

Notes and Examples

The values given are multipliers; use values greater than one to increase the scale; use values less than one to decrease it. Negative values

fill-pen blue box 100x100 200x200
scale 2  .5  fill-pen red box 100x100 200x200
reset-matrix  ; Reset the scale.
scale .5 1.5 fill-pen yellow box 100x100 200x200

Another way to reset the scale is to use the PUSH command:

fill-pen blue box 100x100 200x200
push [scale 2  .5  fill-pen red box 100x100 200x200]
scale .5 1.5 fill-pen yellow box 100x100 200x200

See also: http://www.w3.org/TR/SVG/coords.html#EstablishingANewUserSpace

SHAPE

Draws shapes using the SHAPE sub-dialect

Arg	Type	Description	Values
shape-cmd-block	[block!]

Notes and Examples

line-width 4
pen red
shape [move 100x100 hline 50]
pen yellow
shape [move 2x2 vline 50]

line-width 4
pen red
shape [move 100x100 hline 50 vline 50]

pen yellow line-width 4 fill-pen red shape [
    move 100x100
    arc 200x100
    line 100x100
]

pen yellow line-width 4 fill-pen red shape [
    move 100x100
    arc  100 200x100 false true
    line 100x100
    move 100x200
    arc 100 200x200 true true
    line 100x200
]

pen yellow line-width 4 fill-pen red shape [
    move 100x10
    'line 100x0
    'arc 0x100
    'line -100x0
    'arc 0x-100 true
]

pen yellow fill-pen red line-width 4 shape [
    move 100x100
    line 200x100
    curve 200x150 250x100 250x150
    curve 250x200 200x250 200x300
    line 100x300
]

pen yellow fill-pen red line-width 4 shape [
    move 100x100
    hline 200
    vline 200
    hline 100
    vline 100
]

SKEW

Sets a coordintate system skewed from the original by the given number of radians (TBD will be changing to degrees).

Arg	Type	Description	Values
val	[decimal!]

Notes and Examples

Positive numbers skew to the right; negative numbers skew to the left.

fill-pen blue box 100x100 200x200
skew .25 fill-pen red box 150x150 250x250
reset-matrix
skew -.25 fill-pen yellow box 200x200 300x300

Another way to reset the skew is to use the PUSH command:

fill-pen blue box 100x100 200x200
push [skew .25 fill-pen red box 150x150 250x250]
skew -.25 fill-pen yellow box 200x200 300x300

See also: http://www.w3.org/TR/SVG/coords.html#EstablishingANewUserSpace

SPLINE

The spline command lets you draw a curve through any number of points. The smoothness of the curve will be determined by the segment factor that you specify.

Arg	Type	Description	Values
segmentation	[integer!]	Optional. Number of segments between each point; default is 1.
closed	[word!]	Optional. 'closed will cause the path to be closed between the start and end points.
point1	[pair!]
point2	[pair!]
...	-	Any number of points may be used.

Notes and Examples

spline 20x20 200x70 150x200 50x230 50x300 80x300 200x200

spline 3 20x20 200x70 150x200 50x230 50x300 80x300 200x200

spline 10 closed 20x20 200x70 150x200 50x230 50x300 80x300 200x200

TEXT

Draws a string of text.

Arg	Type	Description	Values
text-string	[string!]
offset	[pair!]
render-mode	[word!]	How text will be rendered	anti-aliased vectorial - Can be transformed with stroke/dashes, filled with fill-pens, etc. aliased

Notes and Examples

PENDING! Do we need to discuss what Type 1 and Type 2 fonts are?

To run some of these tests, you'll need to define the following font objects:

bold20: make face/font [style: 'bold size: 20]
bold32: make face/font [style: 'bold size: 32]

Basic text isn't too exciting to look at.

text "This is a string of text  - Default size (12)" 50x25

text vectorial "This is a string of text 1" 50x75

text aliased "This is a string of text 2" 50x125

font bold20 text anti-aliased "Font Size 20" 50x175

font bold20 text vectorial "Font Size 20, type 1" 50x225

font bold20 text aliased "Font Size 20, type 2" 50x275

Vectorial text supports the pen, fill-pen, line-width, and line-pattern settings.

font bold32 pen yellow red line-pattern 5 5 line-width 2
text vectorial "Patterned Text" 50x150

With vectorial text you can also define a spline using pairs, which is used as a path the text will follow. If only one pair is given, it acts as a normal text offset.

font bold32
line-width 2
pen snow
fill-pen linear 10x10 0 400 0 1 1 0.0.255 0.0.255 0.255.0 255.0.0 255.0.0
text vectorial 20x300 150x30 250x300 420x140 "Curved text rendered by DRAW!" 500

You can also close the path:

font bold32
line-width 2
pen snow
fill-pen 3 10x10 radial 400 0 1 1 0.0.255 0.0.255 0.255.0 255.0.0 255.0.0
text vectorial 60x60 240x110 190x240 90x270 "Curved text rendered by DRAW!" 500 closed

TRANSFORM

You can apply a transformation such as translation, scaling, and rotation to any DRAW result.

Arg	Type	Description	Values
angle	[decimal!]
center	[pair!]
scale-x	[decimal!]
scale-y	[decimal!]
translation	[pair!]

Notes and Examples

See also:

• Viewtop REBOL/tests/draw-matrix.r
• http://www.w3.org/TR/SVG/coords.html#TransformAttribute

TRANSLATE

Sets the origin for drawing commands.

Arg	Type	Description	Values
offset	[pair!]

Notes and Examples

Multiple translate commands will have a cumulative effect:

fill-pen blue box 50x50 150x150
translate 50x50 fill-pen red box 50x50 150x150
translate 50x50 fill-pen yellow box 50x50 150x150

You can use RESET-MATRIX to avoid that if you want:

fill-pen blue box 50x50 150x150
translate 50x50 fill-pen red box 50x50 150x150
reset-matrix
translate 50x50 fill-pen yellow box 100x100 300x300

Another way to reset the skew is to use the PUSH command:

fill-pen blue box 50x50 150x150
push [translate 50x50 fill-pen red box 50x50 150x150]
translate 50x50 fill-pen yellow box 100x100 300x300

See also: http://www.w3.org/TR/SVG/coords.html#EstablishingANewUserSpace

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.

Arg	Type	Description	Values
vertex1	[pair!]
vertex2	[pair!]
vertex3	[pair!]
color1	[tuple!]
color2	[tuple!]
color3	[tuple!]
dilation	[decimal!]	This is useful for eliminating anitaliased edges

Notes and Examples

This should make it easy to see where each triangle is:

pen none
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

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

pen none
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 none
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

TBD

Need docs on the order of gradient colors.

SHAPE commands

The goal of the SHAPE command is to allow more complex shape descriptions (imagine a path description that describes the shape of the REBOL logo, for example). The shape commands were designed to be compatible with SVG path commands.

Look at http://www.w3.org/TR/SVG11/paths.html for more details;

When you use a shape command in the DRAW dialect, the argument it takes is, itself, a block of commands. These commands use a specialized SHAPE dialect, which is not the same as the DRAW dialect.

By supplying this information within a block, programs can easily delimit the path itself, and it can even be specified outside of the draw block and referenced through a variable. The use of words like move and line (rather than single characters as in SVG) is not significant in memory because they are symbols (references), and for very large files the source format can use compress and the longer names will not be a factor (compressors find those kinds of patterns easily).

The shape is closed automatically, i.e. as a polygon, unless you specify a move command at the end of the shape block.

Relative positioning

Path commands can be absolute or relative. Within SVG this is represented by character casing. However, shape avoids symbol casing issues; instead, it uses literal words for relative commands. For example:

[move 100x100]  ; is absolute
['move 100x100] ; is relative

Regarding the construction and semantic issues of such forms, because we are dealing with a pure dialect of REBOL (no direct interpretation of REBOL functions), constructing and handling such blocks is quite easy. There is also the benefit from the fact that absolute and relative commands are different datatypes, so operations that search are kept simple. e.g. find lit-word! can be used to find relative path commands.

Examples

pen yellow line-width 4 fill-pen red shape [
    move 100x175
    arc  75 200x175 false true
    line 100x175
    move 100x200
    arc 100 200x200 true true
    line 100x200
]

pen yellow line-width 4 fill-pen red shape [
    move 100x100
    'line 100x0
    'arc 0x100
    'line -100x0
    'arc 0x-100 true
]

pen yellow fill-pen red line-width 4 shape [
    move 100x100
    line 200x100
    curve 200x150 250x100 250x150
    curve 250x200 200x250 200x300
    line 100x300
]

Converting SVG path commands to shape commands

Some people in the REBOL community are already working on this.

Here is a reference to the BNF grammar for SVG paths:

http://www.w3.org/TR/SVG11/paths.html#PathDataBNF

Shape block commands

ARC

Draws an elliptical arc from the current point.

Arg	Type	Description	Values
point1	[pair!]
radius-x	[decimal!]
radius-y	[decimal!]
angle	[decimal!]
sweep	[logic!]
large	[logic!]

Notes and Examples

LARGE and SWEEP should be keywords too

Set SWEEP to draw arcs in a "positive-angle" direction.

pen yellow line-width 4 shape [
    move 100x200
    arc  75 200x200 false false
]
pen red shape [
    move 100x205
    arc 75 200x205 true false
]

Set LARGE for arc sweeps greater than 180°.

pen yellow line-width 4 shape [
    move 100x200
    arc  75 200x200 false true
]
pen red shape [
    move 100x205
    arc 75 200x205 true true
]

CURV

Smooth CURVE shortcut.

Arg	Type	Description	Values
point1	[pair!]
point2	[pair!]
point1	[pair!]
...	-

Notes and Examples

From http://www.w3.org/TR/SVG11/paths.html:

"The first control point is assumed to be the reflection of the second control point on the previous command relative to the current point. (If there is no previous curve command, the first control point is the current point.)"

CURVE

Draws a cubic Bézier curve.

Arg	Type	Description	Values
point1	[pair!]
point2	[pair!]
point3	[pair!]
point1	[pair!]
...	-

Notes and Examples

A cubic Bézier curve is defined by a start point, an end point, and two control points.

HLINE

Draws a horizontal line from the current point.

Arg	Type	Description	Values
end-x	[decimal!]

Notes and Examples

Using absolute coordinates:

line-width 4
shape [
    move 100x100  hline 300
    move 100x150  hline 250
    move 100x200  hline 200
]

Using relative coordinates:

line-width 4
shape [
    move 100x100   'hline 200
    'move -200x50  'hline 150
    'move -150x50  'hline 100
]

LINE

Draws a line from the current point through the given points, the last of which becomes the new current point.

Arg	Type	Description	Values
point1	[pair!]
point2	[pair!]
point3	[pair!]
point4	[pair!]
...	-

MOVE

Set's the starting point for a new path without drawing anything.

Arg	Type	Description	Values
point1	[pair!]

Notes and Examples

The effect is as if the "pen" were lifted and moved to a new location.

Used at the end of a SHAPE command, MOVE prevents the shape from being drawn as a closed polygon.

line-width 4
pen red
shape [
    move 100x100
    line 20x20 150x50
    move 0x0
]
pen blue
shape [
    move 100x200
    line 20x120 150x150
]

Using relative coordinates for the second shape:

line-width 4
pen red
shape [
    move 100x100
    line 20x20 150x50
    move 0x0
]
pen blue
shape [
    move 100x100
    'move 0x100
    'line -80x-80 130x30
    'move 0x0
]

QCURV

Smooth QCURVE shortcut.

Arg	Type	Description	Values
point1	[pair!]

Notes and Examples

Draws a cubic Bézier curve from the current point to point1.

See: http://www.w3.org/TR/SVG11/paths.html and CURV

QCURVE

Draws quadratic Bézier curve.

Arg	Type	Description	Values
point1	[pair!]
point2	[pair!]
point1	[pair!]
...	-

Notes and Examples

A quadratic Bézier curve is defined by a start point, an end point, and one control point.

VLINE

Draws a vertical line from the current point.

Arg	Type	Description	Values
end-y	[decimal!]

Notes and Examples

Using absolute coordinates:

line-width 4
shape [
    move 100x100  vline 300
    move 150x100  vline 250
    move 200x100  vline 200
]

Using relative coordinates:

line-width 4
shape [
    move 100x100   'vline 200
    'move 50x-200  'vline 150
    'move 50x-150  'vline 100
]