croak sprintf 'RISC OS bug - cannot use a buffer address %X with Draw_ProcessPath - must be less than &80000000', $outputaddr unless $outputaddr < 0x80000000;
return wantarray ? () : undef
unless defined kernelswi ($draw_pp, $path, $plot,
(defined $transblock ? $transblock : 0),
$flat, 0 + $thick, $joinblock, $dash,
0x80000000 | $outputaddr);
my $result = [];
@$result = unpack 'i4', $output;
wantarray ? @$result : $result;
}
$draw_pp;
__END__
=head1 NAME
RISCOS::Draw -- perl interface to the Draw module
=head1 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;
=head1 DESCRIPTION
C<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.
=head2 Subroutines
=over 4
=item what <type> <default> <values...>
C<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. I<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. C<RISCOS::Draw> provides these
tables:
=head3 winding
non-zero 0
negative 1
even-odd 2
positive 3
=head3 plot
non-boundary exterior 4
boundary exterior 8
boundary interior 16
non-boundary interior 32
=head3 cap
butt 0
round 1
square 2
triangle 3
=head3 join
mitred 0
round 1
bevelled 2
=head3 tagname
end 0
continue 1
move 2
move_same_wind 3
close_gap 4
close 5
bezier 6
gap_same_sub 7
line 8
I<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 C<what> returns an array corresponding to the converted
arguments. In scalar context C<what> returns only the first value.
=item unwhat <type> <default> <values...>
C<unwhat> provides the reverse conversion to C<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.
=item 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.
=item pack_dash_block <packed_block>
=item pack_dash_block <array_ref>
=item pack_dash_block <start> <array_ref>
Packs an array of integers into a block to pass to C<Draw> SWIs or to store in a
DrawFile. If a single array reference is passed it is assumed to point to an
array C<($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.
=item split_path_block <path_block>
splits the scalar containing a series of C<Draw> path elements into an array,
with each element containing the a single move, line or curve. Concatenating the
array with C<join ''> will give the original scalar, except that the terminating
end-of-path marker C<"\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.
=item pack_path_block <reference>
=item 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 C<split_path_block>.
If the first argument is scalar reference it is assumed to point to an already
packed path block and C<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
C<pack>ed with the template C<'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 C<"\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