.\"##
.\" $XConsortium: p011,v 5.2 94/04/17 20:54:19 rws Exp $
.\"##
.\"## 
$XMCOPY
.\"## Copyright (c) 1990, 1991 by Sun Microsystems, Inc. 
.\"## 
.\"##                         All Rights Reserved
.\"## 
.\"## Permission to use, copy, modify, and distribute this software and its 
.\"## documentation for any purpose and without fee is hereby granted, 
.\"## provided that the above copyright notice appear in all copies and that
.\"## both that copyright notice and this permission notice appear in 
.\"## supporting documentation, and that the name of Sun Microsystems,
.\"## not be used in advertising or publicity 
.\"## pertaining to distribution of the software without specific, written 
.\"## prior permission.  
.\"## 
.\"## SUN MICROSYSTEMS DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, 
.\"## INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
.\"## EVENT SHALL SUN MICROSYSTEMS BE LIABLE FOR ANY SPECIAL, INDIRECT OR
.\"## CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
.\"## USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
.\"## OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
.\"## PERFORMANCE OF THIS SOFTWARE.
.TH "CELL ARRAY" 3P "29 February 1991"
.SH NAME
CELL ARRAY \- create structure element specifying \s-2\&2D\s+2 cell array
.IX "Primitives, Special Primitives" "CELL ARRAY"
.IX "Special Primitives" "CELL ARRAY"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
void
pcell_array ( rectangle, colr_array )
Prect	*rectangle;	\fIcell rectangle\fP
Ppat_rep	colr_array;	\fIcolour array\fP
.fi
.ft R
.SS Required PHIGS Operating States
(PHOP, *, STOP, *)
.SH DESCRIPTION
.SS Purpose
The \s-2CELL ARRAY\s+2 function places a structure element containing
the full specification of a \s-2\&2D\s+2
cell array into the currently open structure,
according to the current edit mode.
A \s-2\&2D\s+2 cell array primitive is an array of cells with individual colours.
Its area is defined by two points in Modelling Coordinates
giving the opposite corners of a rectangle, which is taken to
be aligned with the modelling coordinate axes.
.LP
If the current edit mode is \s-2INSERT\s+2, the \s-2CELL ARRAY\s+2 element
is inserted into the open structure after the element pointed to by the
element pointer. If the edit mode is \s-2REPLACE\s+2, the \s-2CELL ARRAY\s+2
element replaces the element pointed to by the element pointer. In either
case, the element pointer is updated to point to the new \s-2CELL ARRAY\s+2
element.
.SS C Input Parameters
.IP \fIrectangle\fP
A pointer to a Prect structure giving the lower left and upper right corners
of the rectangle that defines the area of the \s-2CELL ARRAY\s+2 element.
The Prect structure is defined in phigs.h as:
.sp .4
.ta .5i +\w'Ppoint	'u +\w'p;	'u
.nf
typedef struct  {
.sp .2
	Ppoint	p;	/* lower left */
	Ppoint	q;	/* upper right */
.sp .2
} Prect;
.IP
.fi
The Ppoint structure is defined in phigs.h as:
.sp .4
.ta .5i +\w'Pfloat     'u +\w'x;     'u
.nf
typedef struct  {
.sp .2
	Pfloat	x;	/* x coordinate */
	Pfloat	y;	/* y coordinate */
.sp .2
} Ppoint;
.fi
.IP \fIcolr_array\fP
A pointer to the colour array.
The Ppat_rep structure is defined in phigs.h as:
.sp .4
.ta .5i +\w'Pint_size     'u +\w'colr_array;     'u
.nf
typedef struct  {
.sp .2
	Pint_size	dims;	/* patterns's dimensions */
	Pint	*colr_array;	/* colour index array */
.sp .2
} Ppat_rep;
.fi
.IP
Pint_size is defined in phigs.h as follows:
.sp .4
.ta .5i +\w'Pint	'u +\w'size_x;		'u
.nf
typedef struct {
	Pint	size_x;	/* x size */
	Pint	size_y;	/* y size */
} Pint_size;
.fi
.SS Execution
When the structure is traversed, the \s-2CELL ARRAY\s+2 element draws the transformed
boundaries of the cell rectangle, using the polyline attributes currently in effect.
This is the minimal simulation for cell arrays.  Applications should not depend on
this behavior to remain the same in future releases.
.LP
The aspect source flags (\s-2ASF\s+2s) for line type, line width scale factor,
and polyline colour index control whether the values used for these attributes
are taken from the polyline representation specified by 
\s-2POLYLINE INDEX (ASF - BUNDLED),\s+2 or from the individual specifications
set for these attributes \s-2(ASF - INDIVIDUAL)\s+2.
.LP
The coordinates used to specify the position of the \s-2CELL ARRAY\s+2
primitive are Modelling Coordinates.  These can be any coordinate units that
are convenient to the application.
At traversal, these coordinate values will be transformed by the current
Local and Global Modelling Tranformations, the view representation selected 
by the current view index, and the workstation transformation current
on the workstation to which the structure is posted.
.SS Attributes Applied
The current values of the following attributes will be used to display
the \s-2CELL ARRAY\s+2 primitive when the structure is traversed.  
The value of an attribute is modified with the appropriate \s-2SET\s+2 routine.
The Aspect Source Flags (\s-2ASF\s+2s) tell where to access the output
display attributes.  These attributes can come directly from the
traversal state list, or they can be accessed indirectly, using the
appropriate index in the traversal state list and the corresponding bundled
representation in the workstation state list.
.RS
.nf
.ta .5i +2i  +2i
.sp
	polyline colour	polyline colour index \s-2ASF\s+2
	linewidth scale factor	linewidth scale factor \s-2ASF\s+2
	linetype	linetype \s-2ASF\s+2
	polyline shading method	polyline shading method \s-2ASF\s+2
	polyline index	
	depth cue index	
	name set	
.fi
.RE
.sp .2
.SH ERRORS
.IP 005
Ignoring function, function requires state (\s-2PHOP, *, STOP, *\s+2)
.IP 113
Ignoring function, the colour index value is less than zero
.IP 117
Ignoring function, one of the dimensions of the colour index array
is less than zero
.SH SEE ALSO
.nf
.IP
.ta 0.5i
.SM "CELL ARRAY 3 (3P)"
.fi