home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Acorn User 10
/
AU_CD10.iso
/
Updates
/
Perl
/
RPC
/
Docs
/
RISCOS-Library-Docs
/
Draw.pm
< prev
next >
Wrap
Text File
|
1999-04-17
|
7KB
|
187 lines
NAME
RISCOS::Draw -- perl interface to the Draw module
SYNOPSIS
use RISCOS::Draw qw(what split_path_block path_bbox);
# Convert join name to number, default to bevelled
$join = what ('join', 'bevelled', $join);
# Split scalar containing path into array of path elements
@path = split_path_block $block;
$bbox = path_bbox $block, $width;
DESCRIPTION
`RISCOS::Draw' provides an interface to the Draw module, which
provides "an implementation of PostScript type drawing". At
present only functions necessary to calculate path bounding
boxes have been implemented, principally for use by the DrawFile
Path object.
Subroutines
what <type> <default> <values...>
`what' converts names of options into the appropriate
numeric constants. Arguments passed as numbers are faulted
if they do not correspond to a named option. *type* can
either be a reference to a typeglob (which supplies a hash
to convert from name to number and an array from number to
name) or a string to use lookup tables provided by this
package. `RISCOS::Draw' provides these tables:
non-zero 0
negative 1
even-odd 2
positive 3
non-boundary exterior 4
boundary exterior 8
boundary interior 16
non-boundary interior 32
butt 0
round 1
square 2
triangle 3
mitred 0
round 1
bevelled 2
end 0
continue 1
move 2
move_same_wind 3
close_gap 4
close 5
bezier 6
gap_same_sub 7
line 8
*default* is a default value (string or text) to use for any
undefined values passed as arguments. Numeric defaults are
deliberately not checked for validity. In array context
`what' returns an array corresponding to the converted
arguments. In scalar context `what' returns only the first
value.
unwhat <type> <default> <values...>
`unwhat' provides the reverse conversion to `what',
converting numeric values to text. Any undefined values are
converted to the (unchecked) supplied default.In scalar
context it returns the first conversion only, in array
context a list of conversions.
split_dash_block <block>
Splits a dash block into an array of integers, which should
be regarded as a single value followed by a list. The first
value is the offset of the start of the dash pattern in the
list. The list itself gives the length of dash segments in
user units.
pack_dash_block <packed_block>
pack_dash_block <array_ref>
pack_dash_block <start> <array_ref>
Packs an array of integers into a block to pass to `Draw'
SWIs or to store in a DrawFile. If a single array reference
is passed it is assumed to point to an array `($start,
@lengths)' (which is passed to shift). If two arguments are
passed the first is taken to be the start index, the second
a reference to an array of dash lengths. If a single scalar
is passed it is assumed to be already packed and is returned
verbatim.
split_path_block <path_block>
splits the scalar containing a series of `Draw' path
elements into an array, with each element containing the a
single move, line or curve. Concatenating the array with
`join ''' will give the original scalar, except that the
terminating end-of-path marker `"\0\0\0\0"' (and any
trailing garbage) will be absent. If passed a reference to
an array, then this array (or a reference to it) is
returned.
In array context returns this array, in scalar context
returns a reference to it.
pack_path_block <reference>
pack_path_block path elements...
packs the path block supplied. In scalar context returns the
path block, in array context returns the path block as if
split by `split_path_block'.
If the first argument is scalar reference it is assumed to
point to an already packed path block and `split_path_block'
is called if necessary.
If the first argument is an array reference, it is
dereferenced and replaces the argument list, else the
supplied argument list is processed.
For each entry in turn, if it is an array reference it is
assumed to point to an array of integer values to be used as
path/move type and co-ordinates, which are `pack'ed with the
template `'I*'' and added to the output array. Otherwise the
entry is assumed to be already packed and added to the
output array verbatim.
A final `"\0\0\0\0"' is added to the output list if
necessary.
In array context the output array is returned, in scalar
context it is concatenated with `join '''.
path_bbox <path> [<winding> <plot_type> <thickness> <join> <start_cap> <end_cap> <dash> <flatness> <transform>
calculates the bounding box of *path*, returning a reference
to an array in scalar context, or the array itself in array
context. `undef' or an empty list are returned if an error
occurs (including supplying an empty path). All arguments
except *path* are optional, and will default to sane values
if not supplied.
*path* is either a scalar if it is already packed as a
block, or a reference to be passed to `pack_path_block'.
*winding* defaults to 0 (non-zero), and is one of the four
values in the `Draw' winding table (distinct from the two
used by `DrawFile').
*plot* is the plot type to pass to the SWI, and defaults to
'boundary'.
*thickness* is the line thickness in user units, which
defaults to 0 (thin)
*join* is either a scalar to lookup in the join table
(default bevelled, mitre limit defaults to 10), or a scalar
reference to select mitred joins with this as the mitre
limit.
*start_cap* and *end_cap* are each either scalars to lookup
in the cap table (default butt, triangle is width × 1,
length × 2) or an array ref to select triangle caps with
`[width, length]'.
*dash* is either a scalar to be used verbatim as the dash
block, or an array reference of the form `[$Offset,
@Values]' to pass to `pack_dash_block'. The default is
continuous lines.
*flatness* defaults to 0, which is normally appropriate
*transform* is a reference to the transformation matrix to
use, defaulting to none
BUGS
Definitely not tested enough yet. Some bits not tested at all, I
believe. Bounding box calculations and sufficient
packing/unpacking to manipulate DrawFiles does work.
AUTHOR
Nicholas Clark <nick@unfortu.net>