.if n .pH ref.pattern @(#)pattern	40.1

.ig
imagen 8/31/89
docformat -c -s4 -dqm4 -p1 pattern
..
.SO mstr.hdr
.ds Lb Shapes
.\" turn off automatic hyphenation -- JHevelin (08-09-89)
.am RT
.nh
..
.BK "Shapes Reference Manual"
.CH "Pattern Object" "12"
.H 1 "Pattern Object"
.H 2 "Introduction"
.P
.nh
The pattern object stores on/off sequences used
for patterns for vectors and curves.
The pattern is an array of float or fract values
and is applied in user-coordinate space
(that is, in units, not pixels).
.P
The pattern sequence repeats and \f2wraps
around\fP until the end of the vector or curve is
encountered.
The pattern can be started in the middle of the pattern array,
as determined by the arguments for PAT_OFFSET.
.IX "pattern object"
.H 4 "NAME"
.P
Copy_Pat \- Copies the pattern from the source to
a destination pattern object.
.IX "Copy_Pat"
.tm .CE U 3 "Copy_Pat" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Copy_Pat\f2(src, dst)\f1
.br
PATTERN src;
.br
PATTERN dst;
.H 4 "DESCRIPTION"
.P
Copies the pattern from the source pattern to the
destination pattern.
.P
\f2src\f1
The pattern object from which the pattern is to
be copied.
.P
\f2dst\f1
The pattern object to which the pattern is copied.
.H 4 "RETURNED VALUE"
.P
PATTERN
.H 4 "SEE ALSO"
.P
Create_Pat
.H 4 "NAME"
.P
Create_Pat \- Creates a pattern as specified by the data.
.IX "Create_Pat"
.tm .CE U 3 "Create_Pat" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Create_Pat\f2(type, data)\f1
.br
PAT_type type;
.br
int *data;
.H 4 "DESCRIPTION"
.P
Creates a pattern defined by type and containing
the given the specified data.
Once you have created the pattern data,
use Set_Context to attach the pattern to the context.
The attribute CTX_LINE_STYLE determines whether
the pattern is to be used.
.P
\f2type\f1
Specifies the type of pattern be created.
PAT_RANGE_FLOAT specifies the pattern of a line as an
array of non-negative floats containing the
lengths of consecutive on/off segments.
The segments are used cyclically:\ \&
when the end is reached,
the pattern is started over from the beginning.
The lengths are in user-coordinate units
(coordinates system prior to any transforms),
and the first segment is assumed to be on
(pen down).
A zero length segment is one pixel wide.
A negative segment indicates the end of the pattern.
A pattern with a single negative float results in a solid line.
.P
PAT_RANGE_FRACT allows you to specify the range numbers
as fract instead of float.
.P
\f2data\f1
Pointer to the data that creates the on/off
pixels of the pattern.
A value of NULL indicates a solid line pattern.
The simplest way to allocate the data is as an
array of floats or fracts.
.H 4 "RETURNED VALUE"
.P
PATTERN
.H 4 "SEE ALSO"
.P
Copy_Pat
.br
Destroy_Pat
.br
Read_Pat
.br
Write_Pat

.H 4 "NAME"
.P
Destroy_Pat \- Destroys the specified pattern and
frees the resources associated with it.
.IX "Destroy_Pat"
.tm .CE U 3 "Destroy_Pat" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Destroy_Pat\f2(pattern)\f1
.br
PATTERN pattern;
.H 4 "DESCRIPTION"
.P
Destroys the pattern object and frees the
resources associated with it.
If other objects reference the pattern,
the resources are not freed.
.P
\f2pattern\f1
The pattern object to be destroyed.
.H 4 "RETURNED VALUE"
.P
[None]
.H 4 "SEE ALSO"
.P
Create_Pat

.H 4 "NAME"
.P
Get_Pat \- Returns the setting of the specified
pattern attribute.
.IX "Get_Pat"
.tm .CE U 3 "Get_Pat" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Get_Pat\f2(pattern, attr)\f1
.br
PATTERN pattern;
.br
PAT_attr attr;
.H 4 "DESCRIPTION"
.P
Returns the setting of the specified pattern
attribute.
.P
\f2pattern\f1
Specifies the pattern for which the attribute
setting is to be returned.
.P
\f2attr\f1
Specifies the attribute for which the setting is
to be returned.
.H 4 "RETURNED VALUE"
.P
Attribute type
.H 4 "SEE ALSO"
.P
Set_Pat

.H 4 "NAME"
.P
Read_Pat \- Reads the line pattern data into a user data structure.
.IX "Read_Pat"
.tm .CE U 3 "Read_Pat" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Read_Pat\f2(pattern, data, format)\f1
.br
PATTERN pattern;
.br
int *data;
.br
PAT_type format;
.H 4 "DESCRIPTION"
.P
Reads the line pattern data into a user array.
.P
\f2pattern\f1
Specifies the pattern whose contents we want to read.
.P
\f2data\f1
Specifies the user array into which to read the line pattern.
It is assumed that this array is large enough to contain the
entire line pattern.
The array should be declared of a numeric type compatible
with the type requested by \f2format\f1\&.
.P
\f2format\f1
Specifies the numeric type for the line pattern data
(PAT_RANGE_FLOAT or PAT_RANGE_FRACT).
The line pattern data will be converted if necessary.
.H 4 "RETURNED VALUE"
.P
void
.H 4 "SEE ALSO"
.P
Write_Pat
.br
Create_Pat

.H 4 "NAME"
.P
Set_Pat \- Sets the specified pattern attribute.
.IX "Set_Pat"
.tm .CE U 3 "Set_Pat" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Set_Pat\f2(pattern, attr, setting)\f1
.br
PATTERN pattern;
.br
PAT_attr attr;
.br
<attribute type> setting;
.H 4 "DESCRIPTION"
.P
Sets the specified pattern attribute.
You may only set the attribute PAT_OFFSET.
.P
\f2pattern\f1
Specifies the pattern object for which the
attribute setting is to be set.
.P
\f2attr\f1
Specifies the attribute for which the setting is
to be set.
.P
\f2setting\f1
Specifies the setting for the specified attribute.
.H 4 "RETURNED VALUE"
.P
[None]
.H 4 "SEE ALSO"
.P
Get_Pat

.H 4 "NAME"
.P
Temp_Pat \- Creates a pattern as specified by the data.
.IX "Temp_Pat"
.tm .CE U 3 "Temp_Pat" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Temp_Pat\f2(type, data)\f1
.br
PAT_RANGE type;
.br
int *data;
.H 4 "DESCRIPTION"
.P
Creates a pattern defined by type with a reference
count of zero.
.P
\f2type\f1
Specifies the type of pattern is be created.
See Create_Pat.
.P
\f2data\f1
See Create_Pat.
.H 4 "RETURNED VALUE"
.P
PATTERN
.H 4 "SEE ALSO"
.H 4 "NAME"
.P
Write_Pat \- Writes the line pattern data from a user data structure.
.IX "Write_Pat"
.tm .CE U 3 "Write_Pat" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Write_Pat\f2(pattern, data, format)\f1
.br
PATTERN pattern;
.br
float *data;
.br
-or-
.br
fract *data;
.br
PAT_type format;
.H 4 "DESCRIPTION"
.P
Writes the line pattern data from a user array.
.P
\f2pattern\f1
Specifies the pattern whose contents we want to write.
.P
\f2data\f1
Specifies the user array from which the line pattern is written.
The original size of the line pattern determined at creation time
(PAT_SIZE) provides an upper limit for the size of the line pattern.
No more than PAT_SIZE range entries will be copied;
the line pattern is not dynamically extended.
If the data array is prematurely terminated with \(mi1,
the line pattern will end there,
but the pattern size will be left alone.
The array should be declared of a numeric type compatible
with the type designated by \f2format\f1\&.
.P
\f2format\f1
Specifies the numeric type for the line pattern data
(PAT_RANGE_FLOAT or PAT_RANGE_FRACT).
.H 4 "RETURNED VALUE"
.P
void
.H 4 "SEE ALSO"
.P
Read_Pat
.br
Create_Pat

.H 2 "Pattern Attributes"
.H 4 "NAME"
.P
PAT_OFFSET
.IX "PAT_OFFSET"
.tm .CE U 3 "PAT_OFFSET" \n(PN
.H 4 "DESCRIPTION"
.P
Offset into the pattern to start drawing.
The offset is specified in world coordinates and
is only specified as a floating point number.
.H 4 "RETURNED VALUE"
.P
float

.H 4 "SEE ALSO"
.H 4 "NAME"
.P
PAT_SIZE
.IX "PAT_SIZE"
.tm .CE U 3 "PAT_SIZE" \n(PN
.H 4 "DESCRIPTION"
.P
Maximum number of range entries stored in the pattern data area.
This size is determined at creation time based on the size of
the original pattern data array.
The line pattern can never get larger than this,
but it may be smaller if it is overwritten with new values
by Write_Pat.
.H 4 "RETURNED VALUE"
.P
int
.H 4 "SEE ALSO"
.P
Create_Pat
.br
Write_Pat

.H 4 "NAME"
.P
PAT_TYPE
.IX "PAT_TYPE"
.tm .CE U 3 "PAT_TYPE" \n(PN
.H 4 "DESCRIPTION"
.P
Numeric type of the line pattern data.
It can be either PAT_RANGE_FLOAT,
indicating the line pattern is composed of
floating point numbers,
or PAT_RANGE_FRACT,
indicating a fract line pattern.
.P
PAT_TYPE is specified at pattern creation time by the
\f2type\fP argument passed to Create_Pat.
.H 4 "RETURNED VALUE"
.P
fract *
.H 4 "SEE ALSO"
.P
Create_Pat
.br
Read_Pat
.br
Write_Pat

