h6. [[Draw]] h6(. » Technical Details h4(#definitions). Definitions * 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. * 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. * A _path_ is a sequence of subpaths, each of which is a sequence of elements. * A _Bezier curve_ is a type of smooth curve connecting two endpoints, with both the direction and curvature specified by two _control points_. * _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. * 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. * _Stroke_ is a term that means to draw a thickened line centred on a particular path. * 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. * _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. * _Joins_ occur between adjacent lines, and between the start and end of a closed subpath. They can be mitred, round or bevelled. * _Fill_ is simply to draw everything within a particular path. * _Interior_ is a term used to specify which pixels are to be filled. _Exterior_ is a term used to specify which pixels must not be filled. * _Winding number rule_ is the method used to determine what is interior or exterior to a path when filling. * _Boundary_ pixels are those that would be drawn if the line were stroked with a minimum thickness for the screen. * _Thickening_ a path is used to convert it to a particular thickness. h4(#measurement). 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_ are the measurements 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_ 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_ are co-ordinates of a path using any compatible measurement system, as they are converted by the transformation matrix into internal Draw units when generating the output. 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_ are only used to specify some numbers in the transformation matrix. They are fixed point numbers, with the decimal point between bits 15 and 16. In other words, this means that the numbers are _&XXXX.XXXX_. That is, the top two bytes contains the whole part of the number, the bottom two bytes the fractional part. h4(#matrix). 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 [[Transformation Matrix|here]]. h4(#winding_rule). 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. h4(#stroking). 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. Note that not all such colours are compatible with printer drivers. h4(#paths). 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 [[Draw_Fill Path Block|here]]. h4(#subpaths). 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. h4(#output_path). 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. h4(#flatness). 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: <code>flatness = number of user units in x axis / number of pixels in x axis</code> 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. h4(#line_thickness). 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 h4(#join_style). 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 [[Draw_ProcessPath Join_Cap Block|here]]. h4(#dash_pattern). 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 [[Draw_ProcessPath Dash Block|here]]. h4(#floating_point). 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. h4(#printing). 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