Draw dialect

1. Abstract

Draw is a dialect (DSL) of Red language that provides a simple declarative way to specify 2D drawing operations. Such operations are expressed as lists of ordered commands (using blocks of values), which can be freely constructed and changed at run-time.

Draw blocks can be rendered directly on top of an image using the draw function, or inside a View face using the draw facet (see View documentation).

2. Commands

Commands can either be drawing instructions or settings for the drawing instructions. When a mode is set, it will affect all subsequent operations in the current Draw session (or until changed).

Most Draw commands require coordinates to be specified. The 2D coordinate system used is:

  • x axis: increasing from left to right of the display.

  • y axis: increasing from top to bottom of the display.

Some drawing commands require lengths to be specified. The length required is number of pixels.

Coord-system

2.1. Line

Syntax

line <point> <point> ...

<point> : coordinates of a point (pair!).

Description

Draws a line between two points. If more points are specified, additional lines are drawn, connecting each point in the provided order.

2.2. Triangle

Syntax

triangle <point> <point> <point>

<point> : coordinates of a vertex of the triangle (pair!).
Note
A vertex is the point at which two lines meet. They are points where edges join.

Description

Draws a triangle with edges between the supplied vertices.

2.3. Box

Syntax

box <top-left> <bottom-right>
box <top-left> <bottom-right> <corner>

<top-left>     : coordinates of the top-left of the box (pair!).
<bottom-right> : coordinates of the bottom-right of the box (pair!).
<corner>       : (optional) radius of the arc used to draw a round corner (integer!).

Description

Draws a box using the top-left (first argument) and bottom-right (second argument) vertices. An optional radius can be provided for making round corners.

2.4. Polygon

Syntax

polygon <point> <point> ...

<point> : coordinates of a vertex (pair!).

Description

Draws a polygon using the provided vertices. The last point does not need to be the starting point, an extra line will be drawn anyway to close the polygon. Minimal number of points to be provided is 3.

2.5. Circle

Syntax

circle <center> <radius>
circle <center> <radius-x> <radius-y>

<center>   : coordinates of the circle's center (pair!).
<radius>   : radius of the circle (integer! float!).
<radius-x> : (ellipse mode) radius of the circle along X axis (integer! float!).
<radius-y> : (ellipse mode) radius of the circle along Y axis (integer! float!).

Description

Draws a circle from the provided center and radius values. The circle can be distorted to form an ellipse by adding an optional integer indicating the radius along Y axis (the other radius argument then becomes the radius along X).

2.6. Ellipse

Syntax

ellipse <top-left> <size>

<top-left> : coordinates of the ellipse's bounding box top-left point (pair!).
<size>     : size of the bounding box (pair!).

Description

Draws an ellipse from the specified bounding box. The size argument represents the X and Y diameters of the ellipse.

Note
ellipse provide a more compact and box-oriented way to specify a circle/ellipse compared to circle command.

2.7. Arc

Syntax

arc <center> <radius> <begin> <sweep>
arc <center> <radius> <begin> <sweep> closed

<center> : coordinates of the circle's center (pair!).
<radius> : radius of the circle (pair!).
<begin>  : starting angle in degrees (integer!).
<sweep>  : angle between the starting and ending points of the arc in degrees (integer!).

Description

Draws the arc of a circle from the provided center and radius values. The arc is defined by two angles values. An optional closed keyword can be used to draw a closed arc using two lines coming from the center point.

2.8. Curve

Syntax

curve <end-A> <control-A> <end-B>
curve <end-A> <control-A> <control-B> <end-B>

<end-A>     : end point A (pair!).
<control-A> : control point A (pair!).
<control-B> : control point B (pair!).
<end-B>     : end point B (pair!).

Description

Draws a Bezier curve from 3 or 4 points:

  • 3 points: 2 end points, 1 control point.

  • 4 points: 2 end points, 2 control points.

Four points allow more complex curves to be created.

2.9. Spline

Syntax

spline <point> <point> ...
spline <point> <point> ... closed

<point> : a control point (pair!).

Description

Draws a B-Spline curve from a sequence of points. At least 3 points are required to produce a spline. The optional closed keyword will draw an extra segment from the end point to the start point, in order to close the spline.

Note
2 points are accepted, but they will produce only a straight line.

2.10. Image

Syntax

image <image>
image <image> <top-left>
image <image> <top-left> <bottom-right>
image <image> <top-left> <top-right> <bottom-left> <bottom-right>
image <image> <top-left> <top-right> <bottom-left> <bottom-right> <color>
image <image> <top-left> <top-right> <bottom-left> <bottom-right> <color> border

<image>        : image to display (image! word!).
<top-left>     : (optional) coordinate of top left edge of the image (pair!).
<top-right>    : (optional) coordinate of top right edge of the image (pair!).
<bottom-left>  : (optional) coordinate of bottom left edge of the image (pair!).
<bottom-right> : (optional) coordinate of bottom right edge of the image (pair!).
<color>        : (optional) key color to be made transparent (tuple! word!).

Description

Paints an image using the provided information for position and width. If the image has positioning information provided, then the image is painted at 0x0 coordinates. A color value can be optionally provided, it will be used for transparency.

NOTE:

  • Four points mode is not yet implemented. It will allow to stretch the image using 4 arbitrary-positioned edges.

  • border optional mode is not yet implemented.

2.11. Text

Syntax

text <position> <string>

<position> : coordinates where the string is printed (pair!).
<string>   : text to print (string!).

Description

Prints a text string at the provided coordinates using the current font.

Note
If no font is selected or if the font color is set to none, then the pen color is used instead.

2.12. Font

Syntax

font <font>

<font> : new font object to use (object! word!).

Description

Selects the font to be used for text printing. The font object is a clone of font!.

2.13. Pen

Syntax

pen <color>

<color> : new color to use for drawing or `off` for no color (tuple! word!).

Description

Selects the color to be used for line drawing operations.

2.14. Fill-pen

Syntax

fill-pen <color>
fill-pen <grad-type> <grad-offset> <grad-start-rng> <grad-stop-rng>
         <grad-angle> <grad-scale-x> <grad-scale-y> <grad-color> <offset>
         <grad-color> <offset> ...
fill-pen off

<color>          : new color to use for filling (tuple! word!).
<grad-type>      : gradient type (word!).
<grad-offset>    : offset from where should the gradient be rendered (pair!).
<grad-start-rng> : beginning of the gradient range (integer!).
<grad-stop-rng>  : end of the gradient range (integer!).
<grad-angle>     : (optional) rotation of the gradient in degrees (integer! float!).
<grad-scale-x>   : (optional) scale X factor (integer! float!).
<grad-scale-y>   : (optional) scale Y factor (integer! float!).
<grad-color>     : color to use for gradient filling (tuple! word!).
<offset>         : (optional) offset of gradient color (float!).

Description

Selects the color or color gradient to be used for filling operations. All closed shapes will get filled by the selected color until the fill pen is set to off.

Sets the gradient type, the following values are accepted:

  • linear

  • radial

  • diamond

For example:

fill-pen linear 0x100 0 400 red green blue box 0x100 400x300
Grad-pen
Note
the gradient can be defined by up to 256 colors.

2.15. Line-width

Syntax

line-width <value>

<value> : new line width in pixels (integer!).

Description

Sets the new width for line operations.

2.16. Line-join

Syntax

line-join <mode>

<mode> : new line joining mode (word!).

Description

Sets the new line joining mode for line operations. Following values are accepted:

  • miter (default)

  • round

  • bevel

  • miter-bevel

Line-join
Note
miter-bevel mode selects automatically one or the other joining mode depending on the miter length (See this page for detailed explanation) .

2.17. Line-cap

Syntax

line-cap <mode>

<mode> : new line cap mode (word!).

Description

Sets the new line’s ending cap mode for line operations. Following values are accepted:

  • flat (default)

  • square

  • round

Line-cap

2.18. Anti-alias

Syntax

anti-alias <mode>

<mode> : `on` to enable it or `off` to disable it.

Description

Turns on/off the anti-aliasing mode for following Draw commands.

Note
Anti-aliasing gives nicer visual rendering, but degrades performance.

2.19. Matrix

Syntax

matrix <matrix-setup>

<matrix-setup> : the matrix which is post-multiplied to current matrix (block!).

Description

Performs matrix multiplication. The current transformation matrix is post-multiplied by this matrix.

The matrix-setup block must have 6 numbers (number!) in it.

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|

2.20. Reset-matrix

Syntax

reset-matrix

Description

Resets the current transformation matrix to a unit matrix.

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

2.21. Invert-matrix

Syntax

invert-matrix

Description

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

2.22. Push

Syntax

push <draw-block>

<draw-block> : block of Draw commands (block!).

Description

Saves the current state (transformations, clipping region, and pen settings) on the stack. You can then change the current transformation matrix, pens etc. inside the PUSH command block. After the PUSH command block, the current state is restored by pop from the stack. The PUSH command can be nested.

2.23. Rotate

Syntax

rotate <angle> <center>

<angle>  : the angle in degrees (integer! float!).
<center> : (optional) center of rotation (pair!).

Description

Sets the clockwise rotation about a given point, in degrees. If optional center is not supplied, the rotate is about the origin of the current user coordinate system. Negative numbers can be used for counter-clockwise rotation.

2.24. Scale

Syntax

scale <scale-x> <scale-y>

<scale-x> : the scale amount in X (number!).
<scale-y> : the scale amount in Y (number!).

Description

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

2.25. Translate

Syntax

translate <offset>

<offset> : the translation amounts (pair!).

Description

Sets the origin for drawing commands. Multiple translate commands will have a cumulative effect.

2.26. Skew

Syntax

skew <skew-x> <skew-y>

<skew-x> : skew along the x-axis in degrees (integer! float!).
<skew-y> : (optional) skew along the y-axis in degrees (integer! float!).

Description

Sets a coordinate system skewed from the original by the given number of degrees. If <skew-y> is not provided, it is assumed to be zero.

2.27. Transform

Syntax

transform <angle> <center> <scale-x> <scale-y> <translation>

<angle>       : the rotation angle in degrees (integer! float!).
<center>      : (optional) center of rotation (pair!).
<scale-x>     : the scale amount in X (number!).
<scale-y>     : the scale amount in Y (number!).
<translation> : the translation amounts (pair!).

Description

Sets a transformation such as translation, scaling, and rotation.

3. Default values

When a new Draw session starts, the following default values are used:

Property Value

background

white

pen color

black

filling

off

anti-alias

on

font

none

line width

1

line join

miter

line cap

flat

4. Sub blocks

Inside Draw code, commands can be arbitrarily grouped using blocks. Semantics remain unchanged, this is currently just a syntactic sugar allowing easier group manipulations of commands (notably group extraction/insertion/removal). Empty blocks are accepted.

5. Source position

Set-words can be used in the Draw code in-between commands to record the current position in Draw block and be able to easily access it later.

Note
if the Draw block length preceeding a set-word is changed, the recorded position is not updated.

6. Draw function

It is possible to render a Draw block directly to an image using the draw function.

Syntax

draw <size> <spec>
draw <image> <spec>

<size>  : size of a new image (pair!).
<image> : image to use as canvas (image!).
<spec>  : block of Draw commands (block!).

Description

Renders the provided Draw commands to an existing or a new image. The image value is returned by the function.

7. Graphics source code

The graphics in this documentation are generated using Red and Draw dialect, here is the source code (you can copy/paste it in a Red console to try/play/improve it):

Red [
	Title:	"Graphics generator for Draw documentation"
	Author: "Nenad Rakocevic"
	File:   %draw-graphics.red
	Needs:	View
]

Arial: make font! [name: "Consolas" style: 'bold]
small: make font! [size: 9 name: "Consolas" style: 'bold]

save %line-cap.png draw 240x240 [
	font Arial
	text 20x220  "Flat"
	text 90x220  "Square"
	text 180x220 "Round"

	line-width 20 pen gray
	line-cap flat	line 40x40  40x200
	line-cap square line 120x40 120x200
	line-cap round	line 200x40 200x200

	line-width 1 pen black
	line 20x40  220x40
	line 20x200 220x200
]

save %line-join.png draw 500x100 [
	font Arial
	text 10x20  "Miter"
	text 170x20 "Round"
	text 330x20 "Bevel"

	line-width 20 pen gray
	line-join miter line 140x20 40x80  140x80
	line-join round line 300x20 200x80 300x80
	line-join bevel line 460x20 360x80 460x80

	line-join miter
	line-width 1 pen black
	line 140x20 40x80  140x80
	line 300x20 200x80 300x80
	line 460x20 360x80 460x80
]

save %coord-system.png draw 240x240 [
	font small
	text 5x5 "0x0"
	line-width 2
	line 20x20 200x20 195x16
	line 200x20 195x24

	line 20x20 20x200 16x195
	line 20x200 24x195

	font Arial
	text 205x12 "X"
	text 12x205 "Y"
]

save %grad-pen.png draw 400x400 [
	pen off
	fill-pen linear 0x100 0 400 red green blue box 0x100 400x300
]

save %grad-pen-more.png draw 600x400 [
	pen off
	fill-pen linear 0x0 0 200 red green blue box 0x0 200x200
	fill-pen linear 200x0 0 200 255.0.0 255.255.0 0.255.0 0.255.255 0.0.255 box 200x0 400x200
	fill-pen linear 400x0 0 200 255.0.0 0.1 255.255.0 0.2 0.255.0 0.4 0.255.255 0.8 0.0.255 .9 255.0.255 1.0 box 400x0 600x200
	fill-pen blue box 0x200 200x400 fill-pen radial 100x300 0 100 255.0.0 0.255.0 0.0.255 box 0x200 200x400
	fill-pen blue box 200x200 400x400 fill-pen diamond 300x300 0 100 30 255.0.0 0.255.0 0.0.255 box 200x200 400x400
	fill-pen diamond 500x300 0 100 30 3.0 1.5 255.0.0 0.255.0 0.0.255 box 400x200 600x400
]

results matching ""

    No results matching ""