RISC OS  OPEN

Programmer’s Reference Manuals

» Part 8 – Non-kernel input/output

» Draw Module

» Technical Details

Definitions

1. A path element is a sequence of words. The first word denotes a command number, called the element type, in the bottom byte. The remaining words in the sequence are parameters for the particular element type.
2. A subpath is a sequence of path elements that define a single connected polygon or curve. If the subpath joins the initial path element it is said to be closed. If it does not, it is said to be a open. A subpath can cross itself or other subpaths within the same path.
3. A path is a sequence of subpaths, each of which is a sequence of elements.
4. A Bezier curve is a type of smooth curve connecting two endpoints, with both the direction and curvature specified by two control points.
5. Flattening is the process of converting a Bezier curve into a series of straight lines when outputting.
6. Flatness is used to specify how closely the outputted lines will resemble the original Bezier curve. The flatness is the maximum distance that a line is allowed to be from a Bezier curve when flattening it.
7. A transformation matrix is the standard mathematical tool for two-dimensional transformations using a three by three dimensional array. This allows for rotating, scaling and translating.
8. Stroke is a term that means to draw a thickened line centred on a particular path.
9. A gap is transparent line segment in a subpath. If the subpath is stroked, the piece around the gap will not be plotted. Gaps are used by Draw to implement dashed lines.
10. Line caps are placed at ends of open subpaths and at the ends of dashes in a dashed line when they are stroked. They can be butted, round, squared or triangular.
11. Joins occur between adjacent lines, and between the start and end of a closed subpath. They can be mitred, round or bevelled.
12. Fill is simply to draw everything within a particular path.
13. Interior is a term used to specify which pixels are to be filled.
14. Exterior is a term used to specify which pixels must not be filled.
15. Winding number rule is the method used to determine what is interior or exterior to a path when filling.
16. Boundary pixels are those that would be drawn if the line were stroked with a minimum thickness for the screen.
17. Thickening a path is used to convert it to a particular thickness.

Measurement Systems

Great care must be taken when using the SWIs provided by the Draw Module because four different units of measurement are used.

OS Units

OS units is the measurement system used by the Window Manager for specifying output to the screen. This is also used by the Draw module when it strokes a path onto the screen.

Internal Draw Units

Draw uses its own measurement system for its own internal calculations. They are 1/256^th of an OS unit. This measurement system is only used for its own internal calculations.

A 32-bit number is used to represent the internal Draw unit. The first 24 bits are used to specify the integer part of the number, and the bottom 8 bits are used to represent the fractional part of the OS unit.

User Units

Co-ordinates of a path can use any measurement system, as they are converted by the transformation matrix into internal Draw units when generating the output.

However, because it is a fixed point system, scaling problems can occur if the measurement system used is differs too much from Draw own internal measurement system.

To avoid scaling issues, it is recommended not to use a numbering system greater than 8, compared to the Internal Draw unit measurement system.

Transform Units

Transform units are only used to specify some numbers in the transformation matrix. The top two bytes specify the integer part of the number, and the bottom two bytes specify the fractional element.

The Transformation Matrix

The transformation matrix is the method used to perform numerous functions on lines, such as scaling, rotating and transforming. It consists of a three by three array. A full explanation of how it is used can be found here.

Winding Rule

The winding rule is used by the Draw module to determine which pixels are interior or exterior, that is, which pixels should be filled.

Four different methods of determining this are provided.

Even-Odd	Specifies that an area should be filled if it is enclosed by an even number of subpaths. This results in an area never having two adjacent areas of the same state. i.e filled or unfilled
Non-Zero	Determines whether an area should be filled based on the direction of the surrounding subpaths were constructed. If an equal number of subpaths in each direction surround the area, then the area is not filled, otherwise it is
Positive	Fill an area if it is surrounded by more anti-clockwise subpaths than clockwise
Negative	Fill an area if it is surrounded by more clockwise subpaths than anti-clockwise

Note: The even-odd and non-zero winding rules are printer driver compatible, whereas the positive and negative are not.

Stroking and Filling

Flattening is the process of converting a Bezier curve into a series of lines within a specified distance of the curve. The flatness is the term used to specify how closely the outputted lines will resemble the original Bezier curve.

The shorter the distance of line, the more accurate resemblance to the original Bezier curve. A longer line will hence, result in a less accurate approximation.

All moving and drawing is relative to the VDU graphics origin.

None of the Draw SWIs will plot outside the boundaries of the VDU graphics window.

All calls use the colour (both pixel pattern and dash pattern) set up for the VDU driver. Please note, that not all such colours are compatible with printer drivers.

Paths

The path is a sequence of subpaths, each of which is a sequence of elements. Each element is from one to seven words in length. The lower byte of the first word specifies the element type and the remaining three bytes are free for use. On output to an input path, the Draw module will leave the three bytes unchanged, but if output to an output path, the three bytes will store zeros.

A table showing the path structure is available here.

Open and Closed Subpaths

When stroking, if a subpath ends with a 4 or 5 then it is closed and the ends are joined.

If the subpath is a 2 or a 3, then it leaves the subpath open, and the loose ends are capped. These four path elements explicitly leave a stroked subpath open or closed.

If must be noted, that some operations close open subpaths. This, however, will be stated in the descriptions.

In addition, just because the ends of a subpath have the same co-ordinates does not mean that the subpath is closed.

Output Path

Certain SWIs has the ability to output to an output rather than to the screen. After a path has been written to an output path, it is identical to an input path. When the output path is first passed to a SWI as a parameter, the start of the block should contain an element type zero, followed by the number of available bytes. This is to ensure that it will not accidently overrun the buffer.

Flatness

Flattening_ is the process of converting a Bezier curve into a series of straight lines when outputting. Flatness is used to specify how closely the outputted lines will resemble the original Bezier curve. The flatness is the maximum distance that a line is allowed to be from a Bezier curve when flattening it.

To ensure a good approximation of the Bezier curve, it is recommended that the flatness value is between 0.5 and 1.0 pixel. Any less is unnoticeable, but any more and the curve becomes noticeably jaggy.

An easy way to calculate the flatness value is:

flatness = number of user units in x axis / number of pixels in x axis

A value of zero specifies the default flatness value, which provides a good balance between speed and accuracy (using default scaling).

If outputting a path to a high resolution printer instead of a screen, it is advisable to use a smaller flatness value, that results in a more accurate representation of the curve.

Line Thickness

The thickness of the line is specified in user co-ordinates rather than OS units or Draw’ own internal co-ordinate system. The following points must be noted when specifying the thickness.

• To use the default thickness value, a value of zero should be used. This draws the line with the minimum width that can be used given any particular screen resolution. i.e one pixel wide
• A value of 2 draws the line with a thickness of 1 user co-ordinate translated to pixels on either side of the theoretical line position
• A non-zero value, then the cap and join parameter must also be passed

Cap and Join Style

Cap and join styles specify how the cap and joins are displayed. Joins can be mitred, round or bevelled. Whereas caps can be butted, round, square or triangular.

More information on Cap and Join styles can be found here.

Dash Pattern

The dash pattern as the name suggests, specifies the pattern of dashes used to represent a given line.

More information on the dash pattern is provided here.

Floating Point

Draw uses fixed point arithmetic for speed, rather than floating point.

The SWIs used by the Draw module all use integer numbers, however, SWI names and numbers have been allocated to support future versions that support Floating Point. To use the floating point versions, the suffix ‘FP’ needs to be appended to the current SWI name.

The Floating Point numbers used in the specification are IEEE single precision floating point numbers.

Note: Not yet implemented and if used will result in an error if called.

Printing

If printing, it is important to note that not all features are compatible. As a general rule, the following features should be avoided:

• AND, OR and similar functions on colours when writing to the screen
• Choice of fill style. e.g fill excluding/including boundary, fill exterior etc…
• Positive and negative winding number rules
• Line cap enhancements, particulary differing leading and trailing caps and triangular caps