.de YS
.br
.tm \\$1 \\n%
.nf
.ft CW
..
.de YM
.ft
.fi
.PP
..
.de YE
.sp 1
..
.\"	$Header: reference,v 4.300 91/06/08 01:54:10 root Rel41 $
.\"
.RP
.DA ""
.TL
CGINEWS \(em Function Reference Manual
.AU
.AI
Sony Corporation
.\"Software Research Associates, Inc.
.
.SH
1. Introduction
.DA "August 3, 1987"
.PP
This manual describes
.B CGINEWS
Release 1.0, which is an implementation of 
\fICGI*\fP(Computer Graphics Interface)
.FS
.nf
*\fICGI \(em Computer Graphics Interfacing Techniques,\fP
2nd Initial Draft, November 1985,
ISO TC97/SC21/WG2 N536
.FE
on the Sony NEWS machine.
.I CGI
is a graphics device interface being standardized by ISO
(International Organization for Standards).
In the context of ISO graphics standards, GKS (Graphical Kernel System),
GKS-3D, and PHIGS (Programmer's Hierarchical Interactive Graphics System)
specify the API (Application Program Interface), which is the interface
between application programs and graphics systems,
while
.I CGI
specifies the VDI (Virtual Device Interface), which is the interface
between graphics systems and graphics devices.
.PP
The
.I CGI
standard describes the abstract functions which any graphics device or graphics
device driver should provide to obtain device independence of the graphics
system.
.
.
.SH
1.1 Classification of CGI Functions
.PP
The
.I CGI
standard describes more than 200 functions, which are classified as follows.
.IP "(1) Control and negotiation functions"
.I "(a) virtual device management"
allows the application and the device
to initiate and terminate sessions of dialogue and to manage the graphics image
on the virtual device,
.I "(b) negotiation"
allows the graphics application system
to interrogate the device in order to learn its capabilities
and to select an appropriate mode of operation,
.I "(c) coordinate space control"
allows establishment of protocols
for the transmission of coordinate information,
placement of the picture on the view surface, and for the management
of clipping,
.I "(d) error management"
involves the detection of errors both at and below the level of
the parameters transmitted through
.I CGI
protocol, and
.I "(e) miscellaneous control elements"
include the external elements and protocols.

.IP "(2) Output and attribute functions"
.I "(a) graphical primitives"
describe the visual components of a picture,
.I "(b) attribute functions"
describe the appearance of graphical primitives,
.I "(c) control elements"
specify the modes of operation of certain other functions
and control some aspects of the device's operation,
.I "(d) interrogation functions"
(for output and attribute capabilities) allow the
.I CGI
user to determine what the device can do, and
.I "(e) inquiry functions"
(for output and attribute capabilities) allow the
.I CGI
user to obtain information about the current values in the
.I CGI
state list.

.IP "(3) Input functions"
The \fICGI\fP standard describes six input classes (CHOICE, LOCATOR, STROKE,
STRING, VALUATOR, and PICK), and four modes of operation (REQUEST, SAMPLE,
EVENT, and ECHO REQUEST).

.IP "(4) Segmentation functions"
These are functions for creating, modifying and manipulating segments.

.IP "(5) Raster operation functions"
The
.I CGI
user can select the drawing bitmap and display bitmap,
can create and delete bitmaps, and can change the contents of bitmaps
by BITBLT operations.

.
.
.PP
\fICGI\fP's
partitioning concept divides these functions among minimum required function
sets called CGIMIN and INPUT CGIMIN, and the following Option Sets:
.nf
.IP Output
.br
\(bu Settable Bundles Option Set
.br
\(bu Closed Figure Option Set
.IP Segmentation
.br
\(bu Segmentation Option Set
.IP Input
.br
\(bu Sample Option Set
.br
\(bu Event Option Set
.br
\(bu Remote Echo Option Set
.br
\(bu Echo Option Set
.br
\(bu Echo Output Option Set
.IP Raster
.br
Raster Option Set
.
.SH
1.2 IMPLEMENTATION
.PP
The current implementation of
.I CGI
on NEWS provides library functions which support a C language
program interface
and uses device drivers (\fBfb\fP(4), \fBmouse\fP(4))
to access the NEWS machine's graphics resources.
.PP
The
.I CGI
working document does not yet specify language bindings nor data stream
encoding.
Currently,
.I CGI
library function names are formed by concatenating
words used for abstract function names, preceded by `CGI_'.
For example, an abstract function specified in the
.I CGI
working document,
.DS
CIRCULAR ARC CENTER CLOSE
.DE
becomes
.DS
.ft CW
CGI_Circular_Arc_Center_Close
.ft
.DE
A version of the C language bindings using shorter names
is being developed
in reference to the proposed GKS C language bingings
and the Pascal language bindings.
.
.
.SH
1.3 USAGE
.PP
C language source programs which use
.I CGI
should include the header file cginews.h:
.DS
.B "#include <cginews.h>
.DE
To check the source programs against interface mismatch,
use lint(1) with the '-lcginews' option:
.DS
.B "% lint file.c ... -lcginews"
.DE
.
To load the
.I CGI
library with your programs, give the '-l option' when you load your programs:
.DS
.B "% ld file.o ... -lcginews"
.sp 0.5
\(em or \(em
.sp 0.5
.B "% cc file.o ... -lcginews"
.DE
.
.SH
1.4 RESTRICTION
.PP
The current implementation of
.I CGI
on NEWS has the following restrictions:
.
.IP \(bu
The pattern area specified by CGI_Pattern_Size() and the cell array area
must be rectangular.
.
.IP \(bu
Text functions do not accept any control characters.
.
.IP \(bu
Some input devices (valuator, stroke, pick) are not supported.
.
.IP \(bu
The event option set are not supported.
.
.IP \(bu
The segmentation option set are not supported.
.
.SH
1.5 Related documents
.PP
The on-line manual for CGINEWS is cginews(3) and the low-level device
interface for the frame buffer and mouse on NEWS are described in
fb(4) (the frame buffer,i.e. bitmap display, driver), and
mouse(4) (the mouse driver).
.\"	$Header: reference,v 4.300 91/06/08 01:54:10 root Rel41 $
.\"
.bp
.de tS
.DS
.ft CW
..
.de tE
.ft
.DE
.sp 1
..
.SH
2. Basic Type Definitions
.PP
This section provides a list of the basic types used by \fBcginews\fP.
The type definitions described here can be found in
.ft CW
<cgi_defs.h>.
.ft
.sp 1
.LP
The
.B Point
structure is used to specify position in VDC (virtual device coordinates) or
DC (device coordinates) space.
.LP
The
.B Rectangle
structure is used to define rectangular area, where
.I first
is one corner, and
.I second
is the opposite corner.
.LP
The
.B Vector
structure is used to specify vectors.
.tS
typedef	struct	{
	int	x;
	int	y;
}	Point;

typedef	struct	{
	Point	first;
	Point	second;
}	Rectangle;

typedef	struct	{
	int	x;
	int	y;
}	Vector;
.tE
.LP
The
.B DC
structure is used to specify length in DC space.
.tS
typedef	union	{
	struct	{
		float	x;
		float	y;
	}	Per;
	struct	{
		int	x;
		int	y;
	}	Dec;
	Point	Nat;
}	DC;
.tE
.LP
The
.B Colour_Direct
and the
.B Colour
structures are used to specify colours.
.LP
There are two ways to describe colours.
One is to specify the RGB values (\fIdirect mode\fP)
and another way is to specify colour table index (\fIindex mode\fP).
.B Colour_Direct
is used to describe colours in direct mode.
.B Colour
is used to describe colours in direct or index mode, which depends
on \fIcolour selection mode\fP.
.tS
typedef	struct	{
	int	red;
	int	green;
	int	blue;
}	Colour_Direct;

typedef	union	{
	Colour_Direct	Direct;
	int		Index;
}	Colour;
.tE
.LP
The
.B ER
structure is  used for error reports.
The
.B func_id
refers function name in which error occurred and
.B message
contains error codes.
.tS
typedef	struct	{
	char	*func_id;
	int	message;
}	ER;
.tE
.bp
.NH S 3
CGI FUNCTION LIST
.LP
.NH 2
CGI CONTROL
.LP
.NH 3
Virtual Device Management Functions
.LP
.YS CGI_Initialise
CGI_Initialise()
.YM
CGI_Initialise initialises the virtual device, leaving it ready to
receive CGI commands. It restores each attribute, mode, precision,
etc. to its default value. It also performs the CGI_Clear_View_Surface function.
.YE
.YS CGI_Reset_To_Defaults
CGI_Reset_To_Defaults()
.YM
CGI_Reset_To_Defaults restores the CGI's attribute values and operating
modes to their default states, but does not clear the view surface or
internal storage such as segments, colour tables, raster images or fonts
, or alter any state information external to the CGI.
.YE
.YS CGI_Terminate
CGI_Terminate()
.YM
CGI_Terminate terminates the current CGI session.
.YE
.YS CGI_Clear_View_Surface
CGI_Clear_View_Surface(soft, hard)
	int	soft; /* (CGI_CTL_SOFT_NOP, CGI_CTL_SOFT_CLEAR) */
	int	hard; /* (CGI_CTL_HARD_NOP, CGI_CTL_HARD_ADV_IF_DIRTY.
					 CGI_CTL_HARD_ADV_UNCONDITIONALLY) */
.YM
CGI_Clear_View_Surface performs a specified combination of clearing actions of
the display surface and/or an internally-stored display list.
The intended behaviour is as if a CGI_Make_Picture_Current were done
before the CGI_Clear_View_Surface, i.e., any pending buffers are flushed.
If the display device is a softcopy device then the 'soft' flag specifies
whether the function should be ignored or executed.
Similarly, if the device is a hardcopy device, the 'hard' flag specifies the
behaviour. In this case, the intent of the parameter value
'CGI_CTL_HARD_ADV_IF_DIRTY' is that if it is known that the display medium has
not been marked, an advance is not required. The cleared region is set to the
back ground colour.
.YE
.YS CGI_Background_Colour
CGI_Background_Colour(colour)
	Colour_Direct	colour;
.YM
CGI_Background_Colour defines the background colour to be used on the next
CGI_Clear_View_Surface function. It also redefines colour index 0 of the colour
table.
.YE
.NH 3
Coordinate Space Control Functions
.LP
.YS CGI_VDC_Extent
CGI_VDC_Extent(first, second)
	Point	first; /* first opposite corner of a VDC extent */
	Point	second;/* second opposite corner of a VDC extent */
.YM
CGI_VDC_Extent defines a rectangular extent in VDC space that is the "region of interest" for the succeeding CGI functions.
This region is mapped onto the effective viewport such that the 'first' of VDC
extent is mapped to the 'first' of the effective viewport, and the 'second' of
VDC extent is mapped to the 'second' of the effective viewport. The viewport may
itself be placed on the display surface inverted in either axis, leading to
mirroring or a 180-degree rotation. The mapping is done according to the
specifications of the current device viewport specification mapping.
.YE
.YS CGI_Device_Viewport
CGI_Device_Viewport(first, second)
	DC	first; /* first opposite corner of a device
		viewport */
	DC	second; /* second opposite corner of a device
		viewport */
.YM
CGI_Device_Viewport defines the specified viewport rectangle on the display
surface. The two parameters are specified in the unit system selected by
CGI_Device_Viewport_Specification_Units. The effective viewport is that area of
the display surface onto which the VDC extent rectangle is mapped. If the
current device viewport specification mapping forces isotropic mapping, the
effective viewport will be smaller than the specified viewport on one or other
axis (but not both). If the current device viewport specification mapping does
not force isotropic mapping, the effective viewport will be the same as the
specified viewport. Mirroring or 180 degree rotation of the image on the device
may be achieved by specifying the corners in some way other than that the first is below and to the left of the second.
.YE
.YS CGI_Device_Viewport_Specification_Units
CGI_Device_Viewport_Specification_Units(units)
	int	units; /* device viewport specification units
			(CGI_CTL_PERCENT_OF_DEFAULT,
			 CGI_CTL_LENGTH_FROM_DEFAULT,
			 CGI_CTL_PHYSICAL_DEVICE) */
.YM
CGI_Device_Viewport_Specification_Units determines the unit system for the
subsequent CGI_Device_Viewport functions. There are three system of units.
In the case of units = CGI_CTL_PERCENT_OF_DEFAULT, the unit is the percent of
default device viewport.
In the case of units = CGI_CTL_LENGTH_FROM_DEFAULT, the unit is deci-millimeters
from lower-left corner of default device viewport.
In the case of units = CGI_CTL_PHYSICAL_DEVICE, the unit is the display surface
coordinate.
.YE
.YS CGI_Device_Viewport_Specification_Mapping
CGI_Device_Viewport_Specification_Mapping(isotropy, horizontal,
		vertical)
	int	isotropy; /* isotropy flag
			(CGI_CTL_NOT_FORCED, CGI_CTL_FORCED */
	int	horizontal; /* horizontal alignment flag
			(CGI_CTL_LEFT, CGI_CTL_CENTER, CGI_CTL_RIGHT) */
	int	vertical; /* vertical alignment flag
			(CGI_CTL_BOTTOM, CGI_CTL_CENTER, CGI_CTL_TOP */
.YM
CGI_Device_Viewport_Specification_Mapping determines how the coordinate mapping
is derived from the VDC extent and the specified device viewport.
If 'isotropy' = CGI_CTL_FORCED, the isotropic mapping is forced. In this case,
the effective viewport is generally smaller than the specified viewport, and two
parameters 'horizontal' and 'vertical' determine how the effective viewport will
be positioned within the specified viewport. 'CGI_CTL_LEFT' and 'CGI_CTL_BOTTOM'
are interpreted as being towards the first corner of the specified device
viewport, regardless of any mirroring or rotation of the viewport on the
physical device.
If 'isotropy' = CGI_CTL_NOT_FORCED, the mapping is generally not isotropic.
.YE
.YS CGI_Clip_Rectangle
CGI_Clip_Rectangle(first, second)
	Point	first; /* first corner of clip rectangle (VDC) */
	Point	second; /* second corner of clip rectangle (VDC) */
.YM
CGI_Clip_Rectangle defines a clipping rectangle in VDC space, parallel to the
VDC extent. The rectangle used for clipping will be the intersection of three
rectangular regions, viz., the clipping rectangle, the display surface, and the
effective viewport. Clipping is always such that objects outside the active
clipping area are not displayed; reversing the two corners of the clip rectangle
does not cause the clip rectangle to become a shield. Whether the clip rectangle
is actually used for clipping is determined by the CGI_Clip_Indicator function.
Changing the device viewport or VDC extent (including by changing VDC type)
causes the clip rectangle to be set to the (new) VDC extent and hence to the
(new) effective viewport.
.YE
.YS CGI_Clip_Indicator
CGI_Clip_Indicator(indicator)
	int	indicator; /* clip indicator
	(CGI_CTL_CLIP_RECTANGLE, CGI_CTL_VIEW_SURFACE, CGI_CTL_OFF) */
.YM
CGI_Clip_Indicator selects the clipping region.
In the case of 'CGI_CTL_CLIP_RECTANGLE', the clipping region is defined by the
intersection of the clip rectangle (defined by CGI_Clip_Rectangle), the
effective viewport(defined by CGI_Device_Viewport), and the default viewport(
the outer limit of the display view surface).
In the case of 'CGI_CTL_VIEW_SURFACE', clipping is performed only at the default
viewport.
In the case of 'CGI_CTL_OFF', no clipping is performed.
.YE
.NH 3
Error Functions
.LP
.YS CGI_Inquire_Supported_Error_Capabilities
CGI_Inquire_Supported_Error_Capabilities(depth)
	int	*depth; /* [OUT] maximum error stack depth */
.YM
CGI_Inquire_Supported_Error_Capabilities returns the maximum size of the error
stack.
.YE
.YS CGI_Inquire_Error_Status
CGI_Inquire_Error_Status(depth, oldest, lost)
	int	*depth; /* [OUT] current error stack depth */
	ER	*oldest;/* [OUT] oldest error report */
	int	*lost;  /* [OUT] number of reports lost */
.YM
CGI_Inquire_Error_Status returns part of the error state list. If the error
stack is empty, then 'depth' is set to zero, and the contents of 'oldest' is
undefined.
.YE
.YS CGI_Pop_Error_Stack
CGI_Pop_Error_Stack(num, returned, reports)
	int	num;       /* Number of reports */
	int	*returned; /* [OUT] Number of reports returned */
	ER	reports[]; /* [OUT] Reports */
.YM
CGI_Pop_Error_Stack removes the most recent error reports from the error stack
and returns them. The number of reports removed is the lesser of the current
error stack depth and the input parameter 'num' . The parameter 'returned'
indicates the number actually returned (which may be zero if the stack was empty).
.YE
.YS CGI_Empty_Error_Stack
CGI_Empty_Error_Stack()
.YM
CGI_Empty_Error_Stack removes all error reports from the error stack, and clears
the 'lost' value in the error state list.
.YE
.NH 3
Miscellaneous Control Functions
.LP
.YS CGI_Escape
CGI_Escape(ident, record)
	int	ident; /* function identifier (ERROR_REACTION) */
	EscapeDataRecord record; /* Escape data record */
.YM
CGI_Escape gives non-standardized(not specified by CGI standard) use.
In this version, this function is used for printing error message when CGI error
occur. If record.error_Reaction is set to ON, the error message is not only
pushed on the error stack, but printed out for the display. This is useful for
debugging.
.YE
.YS CGI_Inquire_Escape
CGI_Inquire_Escape(ident, record, output_record)
	int	ident; /* function identifier (FONT_SIZE) */
	EscapeDataRecord record;
	EscapeOutputDataRecord *output_record; /* [OUT] */
.YM
CGI_Inquire_Escape is used for getting non-standardized informations.
In this version, CGI_Inquire_Escape gives the size of specified font.
.YE
.NH 3
Interrogation Functions
.LP
.YS CGI_Inquire_Device_Physical_Coordinate_System
CGI_Inquire_Device_Physical_Coordinate_System(bottom, top, width,
		height)
	DC	*bottom; /* [OUT] Bottom-left corner */
	DC	*top;    /* [OUT] Top-right corner */
	int	*width;  /* [OUT] Width in deci-millimeters */
	int	*height; /* [OUT] Height in deci-millimeters */
.YM
CGI_Inquire_Device_Physical_Coordinate_System returns the two coordinates and the width and height of the display surface. The two coordinates 'bottom' and
'top' specify the maximum rectangular device viewport which can be contained
in the display surface(default device viewport).
.YE
.YE
.NH 3
Current State Inquiry Functions
.LP
.YS CGI_Inquire_VDC_Extent
CGI_Inquire_VDC_Extent(first, second)
	Point	*first; /* [OUT] first point of VDC extent rectangle */
	Point	*second; /* [OUT] second point of VDC extent rectangle */
.YM
CGI_Inquire_VDC_Extent returns the current VDC extent.
.YE
.YS CGI_Inquire_Device_Viewport
CGI_Inquire_Device_Viewport(units, first, second)
	int *units; /* [OUT] Viewport Specification Units
		(CGI_CTL_PERCENT_OF_DEFAULT, CGI_CTL_LENGTH_FROM_DEFAULT,
		CGI_CTL_PHYSICAL_DEVICE) */
	DC *first; /* [OUT] first corner of device viewport rectangle */
	DC *second;/* [OUT] second corner of device viewport rectangle */
.YM
CGI_Inquire_Device_Viewport returns the current effective viewport and
the device viewport specification units value.
.YE
.YS CGI_Inquire_Device_Viewport_Specification_Units
CGI_Inquire_Device_Viewport_Specification_Units(units)
	int	*units; /* [OUT] viewport specification units
		(CGI_CTL_PERCENT_OF_DEFAULT, CGI_CTL_LENGTH_FROM_DEFAULT,
		CGI_CTL_PHYSICAL_DEVICE) */
.YM
CGI_Inquire_Device_Viewport_Specification_Units returns the current viewport specification units.
.YE
.YS CGI_Inquire_Device_Viewport_Specification_Mapping
CGI_Inquire_Device_Viewport_Specification_Mapping(isotropy,
		horizontal, vertical)
	int	*isotropy; /* [OUT] isotropy flag
			(CGI_CTL_NOT_FORCED, CGI_CTL_FORCED) */
	int	*horizontal;/* [OUT] horizontal alignment flag
			(CGI_CTL_LEFT, CGI_CTL_CENTRE, CGI_CTL_RIGHT) */
	int	*vertical;/* [OUT] vertical alignment flag
			(CGI_CTL_BOTTOM, CGI_CTL_CENTRE, CGI_CTL_TOP) */
.YM
CGI_Inquire_Device_Viewport_Specification_Mapping returns the current viewport specification mapping flags.
.YE
.YS CGI_Inquire_Clip_Rectangle
CGI_Inquire_Clip_Rectangle(first, second)
	Point	*first;/* [OUT] first corner of clip rectangle */
	Point	*second;/* [OUT] second corner of clip rectangle */
.YM
CGI_Inquire_Clip_Rectangle returns the current clip rectangle.
.YE
.YS CGI_Inquire_Clip_Indicator
CGI_Inquire_Clip_Indicator(indicator)
	int	*indicator;/* [OUT] clip indicator
		(CGI_CTL_CLIP_RECTANGLE, CGI_CTL_VIEWPORT, CGI_CTL_OFF) */
.YM
CGI_Inquire_Clip_Indicator returns the current mode of clipping.
.YE
.bp
.NH 2
CGI OUTPUT
.LP
.NH 3
Graphical Primitive Functions
.LP
.NH 4
Line functions
.LP
.YS CGI_Polyline
CGI_Polyline(np, pointList)
	int np; /* number of points */
	Point pointList[]; /* point list */
.YM
CGI_Polyline draws a polyline. It is drawn from the start point
pointList[0] to pointList[1], from pointList[1] to pointList[2], ...,
and from pointList[np -2] to the end point pointList[np-1].
.YE
.YS CGI_Disjoint_Polyline
CGI_Disjoint_Polyline(np, pointList)
	int np; /* number of points ( to be even ) */
	Point pointList[]; /* point list */
.YM
CGI_Disjoint_Polyline draws a disjoint polyline. It is drawn from the
start point pointList[0] to pointList[1], from pointList[2] to
pointList[3], ... , and from pointList[np-2] to the end point
pointList[np-1].
The number of points np is to be even , if it is odd, the function is ignored.
.YE
.YS CGI_Circular_Arc_3_Point
CGI_Circular_Arc_3_Point(startingPoint, intermediatePoint,
		endingPoint)
	Point	startingPoint; /* arc start point */
	Point	intermediatePoint; /* arc intermediate point */
	Point	endingPoint; /* arc end point */
.YM
CGI_Circular_Arc_3_Point draws a circular arc which is defined by three
points. It is drawn from 'startingPoint', through 'intermediatePoint',
to 'endingPoint'.
.YE
.YS CGI_Circular_Arc_Center
CGI_Circular_Arc_Center(center, startVector, endVector, radius)
	Point center; /* point of circle center */
	Vector	startVector; /* arc start direction specifier */
	Vector	endVector; /* arc end direction specifier */
	int radius; /* radius */
.YM
CGI_Circular_Arc_Center draws a circular arc which is defined as follows.
The radius 'radius' and the center point 'center' define a circle.
The arc is drawn in the positive angular direction (as defined by
CGI_VDC_Extent) from the intersection of the circle and the startVector
to the intersection of the circle and the endVector.
If the startVector and the endVector have the same slope, a 360-degree
arc is drawn.
.YE
.YS CGI_Elliptical_Arc
CGI_Elliptical_Arc(center, firstCDPendp, secondCDPendp, startVector,
	endVector)
	Point	center; /* center of ellipse */
	Point	firstCDPendp; /* first Conjugate Diameter Point */
	Point	secondCDPendp; /* second Conjugate Diameter Point */
	Vector	startVector; /* arc start direction specifier */
	Vector	endVector; /* arc end direction specifier */
.YM
CGI_Elliptical_Arc draws an elliptical arc which is defined as follows.
The 'center' specifies the center of an ellipse. The CDP endpoints
include one endpoint from each conjugate diameter; together with the
'center' they define the two conjugate diameters of the ellipse.
'startVector' and 'endVector' define two angles. The  drawing direction
of the elliptical arc is the direction from the firstCDPendp to the second-
CDPendp through the smaller of these two angles. The arc is drawn from
startVector to endVector in this direction.
If startVector and endVector have the same slope, the entire ellipse is
drawn.
.YE
.NH 4
Marker functions
.LP
.YS CGI_Polymarker
CGI_Polymarker(np, pointlist)
	int np; /* number of point */
	Point pointlist[]; /* point list */
.YM
CGI_Polymarker draws the markers at each of the points in the point list.
The marker is drawn centered at each of the alignments.
.YE
.NH 4
Text Functions
.LP
.YS CGI_Text
CGI_Text(point, flag, string)
	Point point; /* text location point */
	int flag;	/* FINAL or NOT_FINAL */
	char *string; /* string text to be displayed */
.YM
CGI_Text displays the text specified by 'string' at 'point' according to
various text attributes.
.PP
The characters are dimensioned according to the character height and
character expansion factor and are oriented according to character
orientation. The direction of the character placement in the string
relative to character orientation is according to text path.
The flag parameter is used to permit changing the following text
attributes within a string which will be aligned as a single block:
text font index, text precision, character expansion factor, character
spacing, text colour, character height, character set index,
alternate character set index, auxiliary colour, and text bundle index.
.PP
If the flag is set to NOT_FINAL, the characters in the string parameter
are accumulated, along with the current attribute settings.
In this case, only the attributes listed above are allowed to change
between this function and the CGI_Append_Text function. With the
exception of the CGI_Escape function, no other CGI functions of any type 	are allowed.
.PP
If the flag is set to FINAL, the string parameter constitutes the entire
string to be displayed. The position of the string relative to the text
point parameter is according to text alignment. Text functions with
a null string parameter are legal and may be followed by the allowed
text attributes and CGI_Append_Text as described above.
.YE
.YS CGI_Restricted_Text
CGI_Restricted_Text(extentx, extenty, point, flag, string)
	int	extentx; /* text extent x */
	int	extenty; /* text extent x */
	Point	point; /* text location point */
	int	flag;	/* FINAL or NOT_FINAL */
	char	*string; /* string text to be displayed */
.YM
CGI_Restricted_Text behaves as does CGI_Text, with the exception that
the text is constrained to be within a parallelogram determined by the
extent parameters, the position, and the text attributes.
The 'extentx' is measured parallel to the base vector of character
orientation, and 'extenty' is measured parallel to the up vector. A
parallelogram is formed whose sides are parallel to the vectors, and
which have lengths as in the extent parameter. The parallelogram is
placed at the position point and aligned according to the current text
alignment.
.PP
All text in the string is displayed within the resulting positioned
parallelogram. The text attributes character height, character expansion
factor, character spacing, text precision, and text font index are
varied if necessary, and only if necessary, to achieve the extent
restriction.
.YE
.YS CGI_Append_Text
CGI_Append_Text(flag, string)
	int flag;	/* FINAL or NOT_FINAL */
	char *string; /* text string to be displayed */
.YM
CGI_Append_Text appends the specified text to the string defined by
preceding CGI_TEXT, CGI_RESTRICTED_TEXT and CGI_APPEND_TEXT functions
whose flag parameter is NOT_FINAL, and displays the entire text as
CGI_Text does.
.PP
If CGI_Append_Text is received when there is no previous text functions
whose flag parameter is NOT_FINAL, it is ignored.
.YE
.NH 4
Fill Functions
.LP
.YS CGI_Polygon
CGI_Polygon(np, pointList)
	int np; /* number of point */
	Point pointList[]; /* point list */
.YM
CGI_Polygon draws a polygon. Its boundary is defined by connecting each vertex in the ordered point list to its successor with straight edges, and connecting the last vertex to the first.
.PP
A non-degenerate polygon (one with three or more vertices, not all of which are collinear) is displayed with interior as defined by the fill bundle index,
aspect source flags, interior style attributes, auxiliary colour and transparency. The appearance of the boundary is controlled by the edge attributes and by auxiliary colour and transparency.
.YE
.YS CGI_Polygon_Set
CGI_Polygon_Set(np, fplist)
	int		np; /* number of points */
	FlaggedPoint	*fplist; /* flagged point list
		edge out flag
		(INVISIBLE, VISIBLE, CLOSE_INVISIBLE, CLOSE_VISIBLE) */
.YM
CGI_Polygon_Set permits the filling of a set of closed polygons. Each
polygon is defined by a collection of straight edges which may be
visible or not visible.
.PP
The flagged point list is processed sequentially. The first point starts
the first polygon of the set, and is stored for later use in closure.
Each point in the list is connected either to its successor in the list, 	or to the current closure point (but not both) with either a visible or
invisible edge.
.PP
An edge out flag is associated with each point in the point list. This
flag value may be viewed as instructions for the edge coming out of that
point. The possible values for the flag and the corresponding actions
are:
.IP INVISIBLE:
The edge from point n to point n+1 defines a fill boundary which is not drawn.
.IP VISIBLE:
The edge from point n to point n+1 defines a fill boundary which is drawn.
.IP CLOSE_INVISIBLE:
The edge from point n to the current closure point defines a fill boundary which
is not drawn. The next point in the list begins a new polygon and becomes the
new current closure point. The next point in the list is not connected to any
previous point (that is, no line is drawn to it from a previous point, and the
edge to it does not constitute a fill boundary).
.IP CLOSE_VISIBLE:
Identical to close invisible, except that the closing edge added is drawn.
.PP
If the edge out flag of the last point in the list is VISIBLE, it is
treated as CLOSE_VISIBLE; if the flag is INVISIBLE, it is treated as
CLOSE_INVISIBLE.
.LP
The interior of the polygon set is filled according to the current
filled area attributes. The visible edges are drawn using the current
edge attributes. Note that an edge will be drawn only if it was
generated with either a VISIBLE or CLOSE_VISIBLE flag and edge
visibility is set to ON. Edge Visibility thus acts as an override on the
visibility of the edges specified in the polygon set, in that it can
turn off edges which were specified as VISIBLE, but cannot turn on edges
which were specified as INVISIBLE.
.YE
.YS CGI_Rectangle
CGI_Rectangle(point1, point2)
	Point point1, point2; /* diagonal opposite corner points */
.YM
CGI_Rectangle draws a rectangle whose opposite corners are specified by
point1 and point2.It is oriented parallel to the VDC axes. The rectangle
so defined is displayed with interior as defined by the filled area attributes.
.YE
.YS CGI_Circle
CGI_Circle(center, radius)
	Point center; /* circle center point */
	int radius; /* circle radius */
.YM
CGI_Circle draws a circle of the specified radius at the specified
position. It is displayed with interior as defined by the filled area
attributes.
.YE
.YS CGI_Circular_Arc_3_Point_Close
CGI_Circular_Arc_3_Point_Close(startingPoint, intermediatePoint,
	endingPoint, closeType)
	Point	startingPoint; /* arc start point */
	Point	intermediatePoint; /* arc intermediate point */
	Point	endingPoint; /* arc end point */
	int	closeType;	/* PIE or CHORD */
.YM
CGI_Circular_Arc_3_Point_Close draws a circular arc same as
CGI_Circular_Arc_3_Point draws except it is closed and filled.
If close type is CHORD, the segment defined by the arc and the chord
from the starting point to the ending point, or if close type is PIE,the
pie sector defined by the computed arc center, the specified starting
point, and the ending point, is displayed with interior as defined by
the filled area attributes.
.YE
.YS CGI_Circular_Arc_Center_Close
CGI_Circular_Arc_Center_Close(center, startVector, endVector,
	radius, closeType)
	Point center; /* arc center */
	Vector startVector; /* arc start directions specifier */
	Vector endVector; /* arc end directions specifier */
	int radius; /* arc radius */
	int closeType;	/* PIE or CHORD */
.YM
CGI_Circular_Arc_Center_Close draws a circular arc same as
CGI_Circular_Arc_Center draws except it is closed and filled.
.PP
If the close type is CHORD, the circular segment defined by the arc and 	the chord from the starting point to the ending point of the arc is
displayed.
.PP
If the close type is PIE, the circular sector defined by the arc and
the specified center point is displayed.
.PP
If startVector and endVector have the same direction, the circle is
drawn and filled. If the close type is PIE, and EDGE VISIBILITY is ON,
the line segments connecting the center to the circle along the start
and end vector is displayed.
.YE
.YS CGI_Ellipse
CGI_Ellipse(center, firstCDPendp, secondCDPendp)
	Point	center; /* ellipse center */
	Point	firstCDPendp; /* first Conjugate Diameter Point */
	Point	secondCDPendp; /* second Conjugate Diameter Point */
.YM
CGI_Ellipse draws a ellipse.
Its contour is same as defined by CGI_Elliptical_Arc. It is filled with interior defined by the filled area attributes.
.YE
.YS CGI_Elliptical_Arc_Close
CGI_Elliptical_Arc_Close(center, firstCDPendp, secondCDPendp,
	startVector, endVector, closeType)
	Point	center; /* center */
	Point	firstCDPendp; /* first Conjugate Diameter Point */
	Point	secondCDPendp; /* second Conjugate Diameter Point */
	Vector	startVector; /* arc start direction specifier */
	Vector	endVector; /* arc end direction specifier */
	int	closeType;	/* PIE or CHORD */
.YM
CGI_Elliptical_Arc_Close draws an elliptical arc same as
CGI_Elliptical_Arc_Close draws, except it is closed and filled.
.PP
If the close type is CHORD, the segment defined by the elliptical arc
and the chord from the starting point to the ending point is displayed.
.PP
If the close type is PIE, the elliptical pie sector defined by the
elliptical arc centerpoint, the starting point, and the ending point is
displayed.
.YE
.YS CGI_Cell_Array
CGI_Cell_Array(pointP, pointQ, pointR, nx, ny, localColourPrecision,
		cellColourSpecifiers)
	Point pointP, pointQ, pointR; /* three vertices of
		a parallelogram */
	int nx, ny;
	int localColourPrecision;
	Colour *cellColourSpecifiers;
.YM
CGI_Cell_Array draws a cell array.
.PP
In the general case P (pointP), Q (pointQ), and R (pointR) delimit an
arbitrary parallelogram. P and Q delimit the endpoints of a diagonal of 	the parallelogram, and R defines a third corner.
.PP
In the simplest case, the three corner points define a rectangular area
in VDC space. This area is subdivided into nx*ny contiguous rectangles as
follows. The edge from P to R is subdivided into nx equal intervals, and
the edge from R to Q is subdivided into ny equal intervals. The colour
list consists of nx*ny colour specifiers, conceptually a two-dimensional
array of dimensions nx and ny representing respectively the column and
row dimensions. Array element (1, 1) is mapped to the cell at corner P,
colour (nx, 1) is mapped to the cell at corner R, and colour (nx, ny) is mapped to the cell at corner Q. Hence the colour elements are mapped within rows running from P to R, and with the rows incrementing in order from R to Q.
.PP
The local colour precision parameter declares the precision of the cell
colour specifiers. The precision is for either indexed or direct colour,
according to the Colour Selection Mode. If the current Colour Selection
Mode is INDEXED, then the form of the parameter is the same as that of
Colour Index Precision. If the current colour selection mode is DIRECT,
then the form of the parameter is the same as that of colour precision.
.PP
.IP NOTE:
This implementation supports only rectangular cell array.
.YE
.NH 3
Attribute Functions
.LP
.NH 4
Line attribute functions
.LP
.YS CGI_Line_Bundle_Index
CGI_Line_Bundle_Index(index)
	int index;/* line bundle index */
.YM
CGI_Line_Bundle_Index sets the line bundle index. When subsequent line
functions occur, the values for line type, line width, and line colour
are taken from the corresponding components of the indexed bundle if the
ASFs for those attributes are set to 'bundled'.
If the ASF for a given attribute is INDIVIDUAL, this function does
not affect the value used for that attribute.
.PP
Line Functions are:
CGI_Polyline, CGI_Disjoint_Polyline, CGI_Circular_Arc_3_Point,
CGI_Circular_Arc_Center, CGI_Elliptical_Arc.
.YE
.YS CGI_Line_Type
CGI_Line_Type(type)
	int type; /* line type indicator
		(L_SOLID, L_DASH, L_DOT, L_DASH_DOT, L_DASH_DOT_DOT) */
.YM
CGI_Line_Type sets the line type. When the line type ASF is INDIVIDUAL,
subsequent line functions are displayed with this line type.
When the  Line Type ASF is BUNDLED, this function does not affect the
display of subsequent line functions.
.YE
.YS CGI_Line_Width
CGI_Line_Width(width)
	Size	width; /* line width specifier */
.YM
CGI_Line_Width sets the absolute line width or line width scale factor.
When the LINE WIDTH ASF is INDIVIDUAL, subsequent line functions are
displayed according to the width specification of this function.
When the LINE WIDTH ASF is BUNDLED, this function does not affect the
display of subsequent line functions.
.YE
.YS CGI_Line_Colour
CGI_Line_Colour(specifier)
	Colour specifier;
.YM
CGI_Line_Colour sets the line colour index or line colour value.
When the LINE COLOUR ASF is INDIVIDUAL, subsequent line functions are
drawn in this line colour.
when the LINE COLOUR ASF is BUNDLED, this function does not affect the
display of subsequent line functions.
.YE
.YS CGI_Line_Representation
CGI_Line_Representation(index, type, width, colour)
	int	index;  /* line bundle index */
	int	type;	/* line type */
	Size	width;	/* line width */
	Colour	colour;	/* line colour */
.YM
CGI_Line_Representation associates the line bundle index with the
specific parameters in the line bundle table.
Line type is specified and behaves as indicated in the CGI_Line_Type
function.
.PP
Line width is defined in the current line width specification mode, and
is stored in the bundle table along with that mode.
Line colour is defined in the current colour selection mode, and is
stored in the bundle table along with that mode.
.PP
Any table entry (including the predefined entries) may be redefined with
this function.
.YE
.NH 4
Marker attribute functions
.YS CGI_Marker_Bundle_Index
CGI_Marker_Bundle_Index(index)
	int index; /* marker bundle index */
.YM
CGI_Marker_Bundle_Index sets the marker bundle index.
When subsequent marker functions occur, the values for marker type,
marker size, and marker colour are taken from the corresponding
components of the indexed bundle if the ASFs for those attributes are
BUNDLED.
.LP
If the ASF for a given attribute is INDIVIDUAL, this function does not
affect the value used for that attribute.
.YE
.YS CGI_Marker_Type
CGI_Marker_Type(type)
	int type; /* marker type specifier
		(M_DOT, M_PLUS, M_ASTERISK, M_CIRCLE, M_CROSS */
.YM
CGI_Marker_Type sets the marker type.
When the MARKER TYPE ASF is INDIVIDUAL, this functions does not affect
the display of subsequent marker functions.
.YE
.YS CGI_Marker_Size
CGI_Marker_Size(size)
	Size	size; /* marker size specifier */
.YM
CGI_Marker_Size sets the absolute marker size or marker size scale factor. When the marker size ASF is INDIVIDUAL, subsequent marker functions are
displayed according to the size specification of this function.
When the Marker Size ASF is BUNDLED, this function does not affect the
display of subsequent marker functions.
.YE
.YS CGI_Marker_Colour
CGI_Marker_Colour(specifier)
	Colour specifier; /* marker colour specifier */
.YM
CGI_Marker_Colour sets the marker colour index or marker colour value.
When the MARKER COLOUR ASF is INDIVIDUAL, subsequent marker functions
are displayed with this marker colour.
When the MAKER COLOUR ASF is BUNDLED, this function does not affect the
display of subsequent marker functions.
.YE
.YS CGI_Marker_Representation
CGI_Marker_Representation(index, type, size, colour)
	int	index;  /* marker bundle index */
	int	type;	/* marker type */
	Size	size;	/* marker size */
	Colour	colour;	/* marker colour */
.YM
CGI_Marker_Representation associates the the given marker bundle index
with the specified parameters in the marker bundle table.
Marker type is specified and behaves as indicated in the CGI_Marker_Type
function.
.LP
Marker size is defined in the current  marker size specification mode,
and is stored in the bundle table along with that mode.
Marker colour is defined in the current colour selection mode, and is
stored in the bundle table along with that mode.
.LP
Any table entry (including the predefined entries) may be redefined
with this function.
.YE
.NH 4
Text Attribute Functions
.LP
.YS CGI_Text_Bundle_Index
CGI_Text_Bundle_Index(index)
	int index; /* text bundle index */
.YM
CGI_Text_Bundle_Index sets the text bundle index.
When subsequent text functions occur, the values for text font index,
text precision, character expansion, character spacing, and text colour
are taken from the corresponding components of the indexed bundle if the
ASFs for those attribute are set to BUNDLED.
.LP
If the ASFs for a given attribute is INDIVIDUAL, this function does not
affect the value used for that attribute.
.YE
.YS CGI_Text_Font_Index
CGI_Text_Font_Index(index)
	int	index; /* font index */
.YM
CGI_Text_Font_Index sets the text font index.
.LP
When the text font ASF is INDIVIDUAL, subsequent text functions are
displayed with this font index.
.LP
When the text font ASF is BUNDLED, this function does not affect the
display of subsequent text functions.
.YE
.YS CGI_Character_Expansion_Factor
CGI_Character_Expansion_Factor(factor)
	double	factor; /* character expansion factor */
.YM
CGI_Character_Expansion_Factor sets the character expansion factor.
When the character expansion factor ASF is INDIVIDUAL, subsequent text
functions are displayed with this character expansion factor.
When the character expansion factor ASF is BUNDLED, this function does
not affect the display of subsequent text functions.
.YE
.YS CGI_Character_Spacing
CGI_Character_Spacing(spacing)
	double	spacing; /* character spacing */
.YM
CGI_Character_Spacing sets the character spacing value.
When the character spacing ASF  is INDIVIDUAL, subsequent text functions
are displayed with this character spacing.
When the character spacing ASF is BUNDLED, this function does not affect
the display of subsequent text functions.
.LP
The parameter represents the desired space to be added between character
bodies of a text string, which is in addition to any intercharacter
spacing provided by the font within the character's body. It is
specified as a fraction of the current character height attribute. The
space is added along the text path. A negative value implies that
characters may overlap.
.LP
When text path is P_RIGHT or P_LEFT, the character spacing is scaled by the
ratio of the length of the character base vector to the length of the
character up vector.
.YE
.YS CGI_Text_Colour
CGI_Text_Colour(specifier)
	Colour	specifier; /*  text colour specifier */
.YM
CGI_Text_Colour sets the text colour index or text colour value.
When the TEXT COLOUR ASF is INDIVIDUAL, subsequent text functions are
displayed with this text colour.
When the TEXT COLOUR ASF is BUNDLED, this function does not affect the
display of subsequent text functions.
.YE
.YS CGI_Character_Height
CGI_Character_Height(height)
	int height;	/* in VDC units */
.YM
CGI_Character_Height sets the character height. Subsequent text
functions are displayed with this character height.
The parameter 'height' represents the desired height of the character
body, from baseline to capline, in VDC units; it must be a positive
number. It is measured along the character up vector. If the character
orientation vectors are not orthogonal, this will not be the
perpendicular distance between baseline and capline.
.YE
.YS CGI_Character_Orientation
CGI_Character_Orientation(upVector, baseVector)
	Vector	upVector; /* character up vector */
	Vector  baseVector; /* character base vector */
.YM
CGI_Character_Orientation defines the orientation and skew of the character body  in subsequent text functions by the two vectors. For purposes of
alignment and path, 'up' is in the direction of the character up vector and 'right' is in the direction of the character base vector.
The ratio of the length of the base vector to the length of the up
vector is used as a scaling factor for the
CGI_Character_Expansion_Factor and CGI_Character_Spacing functions.
.YE
.YS CGI_Text_Path
CGI_Text_Path(path)
	int	path;	/* text path(P_RIGHT, P_LEFT, P_UP, P_DOWN) */
.YM
CGI_Text_Path sets the text path. It specifies the writing direction of a text string relative to the character up vector and character base vector.
Subsequent text functions are displayed with this text path.
.LP
P_RIGHT (right) means in the direction of the character base vector.
.LP
P_LEFT (left) means 180 degrees from the character base vector.
.LP
P_UP (up) means in the direction of the character up vector.
.LP
P_DOWN (down) means 180 degrees from the character up vector.
.YE
.YS CGI_Text_Alignment
CGI_Text_Alignment(horizontalAlignment, verticalAlignment,
		continuousHorizontalAlignment, continuousVerticalAlignment)
	int horizontalAlignment; /* text horizontal alignment type
			(A_LEFT, A_CENTER, A_RIGHT, A_NORMAL_HORIZONTAL,
			CONTINUOUS_HORIZONTAL ) */
	int verticalAlignment; /* text vertical alignment type
			(A_TOP, A_CAP, A_HALF, A_BASE, A_BOTTOM,
			A_NORMAL_VERTICAL, A_CONTINUOUS_VERTICAL) */
	double continuousHorizontalAlignment;
		/* continuous horizontal alignment */
	double continuousVerticalAlignment;
		/* continuous vertical alignment */
.YM
CGI_Text_Alignment sets the text alignment.
Subsequent text strings are displayed with this text alignment.
If the horizontal alignment type is A_NORMAL_HORIZONTAL, or the vertical alignment type is A_NORMAL_VERTICAL, the text alignment is dependent on the text path as follows.
.DS
	path	horizontal alignment 	vertical alignment
	P_RIGHT		A_LEFT			A_BASE
	P_LEFT		A_RIGHT			A_BASE
	P_UP		A_CENTER		A_BASE
	P_DOWN		A_CENTER		A_TOP
.DE
.LP
If the horizontal alignment type is A_CONTINUOUS_HORIZONTAL, the
continuous horizontal parameter(which is a fraction of the side of
the text extent rectangle perpendicular to character up vector) becomes
significant.
If the vertical alignment type is A_CONTINUOUS_VERTICAL, the continuous
vertical alignment parameter (which is a fraction of the
side of the text extent rectangle parallel to character up vector)
becomes significant.
The continuous horizontal and vertical parameters may exceed the range
of 0.0 to 1.0 in order to align a string with a coordinate outside its
text rectangle.
.YE
.YS CGI_Text_Representation
CGI_Text_Representation(index, font, prec, spacing, exfactor, colour)
	int	index;		/* text bundle index */
	int	font;		/* text font */
	int	prec;		/* text precision */
	double	spacing;	/* character spacing */
	double	exfactor;	/* character expansion factor */
	Colour	colour;		/* text colour */
.YM
CGI_Text_Representation associates  the given text bundle index with
the specified parameters in the text bundle table,.
.YE
Fill attribute functions
.YS CGI_Fill_Bundle_Index
CGI_Fill_Bundle_Index(index)
	int index; /* text bundle index */
.YM
CGI_Fill_Bundle_Index sets the fill bundle index.
When subsequent filled-area functions occur, values for interior style,
fill colour, hatch index, and pattern index are taken from the
corresponding components of the indexed bundle, if the ASFs for these
attributes are set to BUNDLED. If the ASF for a given attribute is
INDIVIDUAL, this function does not affect the value used for that
attribute.
.YE
.YS CGI_Interior_Style
CGI_Interior_Style(style)
	int style; /* I_HOLLOW, I_SOLID, I_PATTERN, I_HATCH, I_EMPTY */
.YM
CGI_Interior_Style sets the interior style of the filled-area functions.
When the interior style ASF is INDIVIDUAL, filled-area functions are
displayed with this interior style.
When the interior style ASF is BUNDLED, this function does not affect
the display of fill-area functions.
.YE
.YS CGI_Fill_Colour
CGI_Fill_Colour(specifier)
	Colour specifier; /* fill colour specifier */
.YM
CGI_Fill_Colour sets the fill colour index or fill colour value parameter.
When the fill colour ASF is INDIVIDUAL, subsequent filled-area
functions are filled with this colour.
When the fill colour ASF is BUNDLED, this function does not affect the
display of these subsequent filled-area functions.
.YE
.YS CGI_Hatch_Index
CGI_Hatch_Index(index)
	int index; /* hatch index
		(H_HESPL, H_VESPL, PSESPL, H_NSESPL,
		H_HVC, H_PSNSC) */
.YM
CGI_Hatch_Index sets the hatch index.
The following hatch indices are assigned:
.DS
	index 			hatch pattern
	1 or H_HESPL		horizontal equally spaced parallel lines
	2 or H_VESPL		vertical equally spaced parallel lines
	3 or H_PSESPL		positive slope equally spaced parallel lines
	4 or H_NSESPL		negative slope equally spaced parallel lines
	5 or H_HVC		horizontal/vertical crosshatch
	6 or H_PSNSC		positive slope/negative slope crosshatch
		positive slope = +45 degrees
		negative slope = +135 degrees
.DE
.YE
.YS CGI_Pattern_Index
CGI_Pattern_Index(index)
	int	index; /* pattern index */
.YM
CGI_Pattern_Index sets the pattern index.
The following pattern indices are assigned:
.DS
	index 		pattern
	1		horizontal equally spaced parallel lines
	2		vertical equally spaced parallel lines
	3		grey pattern
.DE
.YE
.YS CGI_Fill_Reference_Point
CGI_Fill_Reference_Point(point)
	Point	point; /* fill reference point */
.YM
CGI_Fill_Reference_Point sets the fill reference point which defines the position of the start of the pattern or the hatch.
When the current interior style is I_PATTERN, this point is used in
conjunction with pattern size for displaying filled area primitives.
When the current interior style is I_HATCH, the fill reference point
provides a common origin  for the hatch patterns in all subsequent
hatched filled-areas.
Pattern is mapped onto the filled area by conceptually replicating the
pattern definition in directions parallel to the sides of the pattern
box until the interior of the complete filled-area is covered.
The common origin for hatched filled-areas means that separate
filled-areas that have the same hatch index and that abut have a
visually continuous hatch pattern across all of the filled-areas.
.YE
.YS CGI_Pattern_Table
CGI_Pattern_Table(index, nx, ny, localColourPrecision, pattern)
	int	index; /* pattern table index */
	int	nx, ny; /* column and row dimensions */
	int	localColourPrecision; /* local colour precision */
	Colour	*pattern; /* colour list */
.YM
CGI_Pattern_Table sets the pattern in the pattern table.
The colour list consists of nx * ny colour specifiers, conceptually a two-dimensional array of dimensions nx and ny representing respectively the column and row dimensions.
.LP
When interior style is I_PATTERN, the pattern is mapped to the interior of a filled-area function as described under the CGI_Pattern_Size function.
The local colour precision parameter declares the precision of the pattern colour specifiers. The precision is for either indexed or direct colour, according to the colour selection mode.
.LP
If the current colour selection mode is INDEXED, then the form of the parameter is the same as that of colour index precision.
.LP
If the current colour selection mode is DIRECT, then the form of the parameter is the same as that of colour precision.
.YE
.YS CGI_Pattern_Size
CGI_Pattern_Size(heightVector, widthVector)
	Vector	heightVector; /* pattern height vector */
	Vector	widthVector; /* pattern height vector */
.YM
CGI_Pattern_Size sets the pattern size.
When interior style is set to I_PATTERN, subsequent filled-area functions are displayed using this pattern size.
Pattern size is comprised of two vectors, a height vector and a width vector.
In the general case, the pattern size vectors and the fill reference point define a parallelogram located in VDC, the pattern box.
This pattern box is divided into cells, nx in the width vector direction and ny in the height vector direction, where nx and ny are the colour array dimensions of the pattern table entry selected by the current pattern index.
.IP NOTE: This implementation does not support general pattern.
	Only rectangular pattern is supported. That is, the pattern height vector and the pattern width vector must be vertical and horizontal respectively.
.LP
.YE
.YS CGI_Fill_Representation
CGI_Fill_Representation(index, interior, colour, hatch, pattern)
	int	index; 		/* fill area bundle index */
	int	interior;	/* interior style */
	Colour	colour;		/* fill colour */
	int	hatch;		/* hatch index */
	int	pattern;	/* pattern index */
.YM
CGI_Fill_Representation associates the given fill bundle index is associated with the specified parameters, in the fill bundle table.
Interior style is specified and behaves as indicated in the CGI_Interior_Style function.
Hatch index indicator is specified and behaves as indicated in the CGI_Pattern_Index function.
Fill colour is defined in the current colour selection mode, and is stored in the bundle table along with that mode.
Any table entry (including predefined entries) may be redefined with this function.
.YE
.NH 4
Edge attribute functions
.LP
.YS CGI_Edge_Bundle_Index
CGI_Edge_Bundle_Index(index)
	int index;	/* edge bundle index */
.YM
CGI_Edge_Bundle_Index sets the edge bundle index.
When subsequent filled-area functions occur, values for edge type, and edge width, and edge colour are taken from the corresponding components of the indexed bundle, if the ASFs for these attributes are set to BUNDLED.
If the ASF for a given attribute is INDIVIDUAL, this function does not affect the value used for that attribute.
.YE
.YS CGI_Edge_Type
CGI_Edge_Type(type)
	int type; /* edge type (L_SOLID, L_DASH, L_DOT,
		L_DASH_DOT, L_DASH_DOT_DOT) */
.YM
CGI_Edge_Type sets the edge type. When the edge type ASF is INDIVIDUAL, subsequent filled area functions are displayed with this edge type.
When the edge type ASF is BUNDLED, this function does not affect the display of subsequent filled area functions.
.YE
.YS CGI_Edge_Width
CGI_Edge_Width(width)
	Size	width; /* edge width specifier */
.YM
CGI_Edge_Width sets the absolute edge width or edge width scale factor.
When the edge width ASF is INDIVIDUAL, subsequent filled area functions are displayed according to the width specification of this function.
When the edge width ASF is BUNDLED, this function does not affect the display of subsequent filled area functions.
.YE
.YS CGI_Edge_Colour
CGI_Edge_Colour(specifier)
	Colour specifier; /* edge colour specifier */
.YM
CGI_Edge_Colour sets the edge colour.
When the edge colour ASF is BUNDLED, this function gives no effect.
CGI_Edge_Colour sets the edge colour index or edge colour value.
When the edge colour ASF is INDIVIDUAL, subsequent filled area functions are drawn in this line colour.
when the edge colour ASF is BUNDLED, this function does not affect the display of subsequent filled area  functions.
.YE
.YS CGI_Edge_Visibility
CGI_Edge_Visibility(flag)
	int flag;	/* (ON, OFF) */
.YM
CGI_Edge_Visibility specifies whether the edge of a filled-area
functions is displayed.
The edge is never displayed if the current value is OFF. If the current
value is ON it is displayed for all primitives except CGI_Polygon_Set.
For CGI_Polygon_Set, individual edges are displayed if and only if the
current value of edge visibility is ON and the edge flag indicates a
visible edge.
.YE
.YS CGI_Edge_Representation
CGI_Edge_Representation(index, type, width, colour)
	int	index;	/* edge bundle index */
	int	type;	/* edge type */
	Size	width;	/* edge width */
	Colour	colour;	/* edge colour */
.YM
CGI_Edge_Representation associates the given edge bundle index with the specified parameters, in the edge bundle table.
Edge type is specified and behaves as indicated in the EDGE TYPE attribute function.
Edge width is defined in the current edge width specification mode, and is stored in the bundle table along with that mode.
Edge colour is defined in the current colour selection mode, and is stored in the bundle table along with that mode.
 Any table entry (including predefined entries) may be redefined with this function.
.YE
.NH 3
Output & Attribute Control Functions
.LP
.YS CGI_Colour_Selection_Mode
CGI_Colour_Selection_Mode(mode)
	int	mode;	/* colour selection mode(DIRECT, INDEXED) */
.YM
CGI_Colour_Selection_Mode sets the colour selection mode.
.LP
If 'mode' is DIRECT, the colour is selected by red, green, blue colour values.
.LP
If 'mode' is INDEXED, the colour is selected by colour table index.
.YE
.YS CGI_Auxiliary_Colour
CGI_Auxiliary_Colour(colour)
	Colour	colour; /* auxiliary colour specifier */
.YM
CGI_Auxiliary_Colour sets the auxiliary colour index or value.
This auxiliary colour is used when transparency attribute is set to OFF.
.YE
.YS CGI_Transparency
CGI_Transparency(trans)
	int	trans;	/* TRANSPARENT or OPAQUE */
.YM
CGI_Transparency sets the transparency.
When the transparency switch 'trans' is OFF, graphical output is
affected as described:
.IP 1.
Line functions: When line type is nonsolid, lines  alternate between the current line colour and the auxiliary colour.
.IP 2.
Filled area functions' edges: When edge type is nonsolid, edges alternate between the current edge colour and the auxiliary colour.
.IP 3.
Marker functions: For devices that display markers within raster cells, pixels that are not part of the marker definition are displayed in the AUXILIARY COLOUR.
.IP 4.
Text functions: For devices that display text within raster cells, pixels that are not part of the character definition are displayed in the AUXILIARY COLOUR.
.IP 5.
Filled-area functions' interior: When interior style is hatch, pixels in the interior that are not the hatch pattern are displayed in the auxiliary colour.
.LP
Turning the transparency switch to ON causes transparent to be substituted for auxiliary colour.
.YE
.YS CGI_Colour_Table
CGI_Colour_Table(startingIndex, ncolour, colourlist)
	int		startingIndex; /* colour table starting index */
	int		ncolour; /* number of colour table entry */
	Colour_Direct	colourlist[]; /* colour list */
.YM
CGI_Colour_Table sets the colour table.
.YE
.YS CGI_Aspect_Source_Flags
CGI_Aspect_Source_Flags(ASF_type, ASF_value)
	int ASF_type; /* ASF type (ASF_LINE_TYPE, ASF_LINE_WIDTH,
			ASF_LINE_COLOUR, ASF_MARKER_TYPE, ASF_MARKER_SIZE,
			ASF_MARKER_COLOUR, ASF_INTERIOR_STYLE, ASF_HATCH_INDEX,
			ASF_PATTERN_INDEX, ASF_FILL_COLOUR, ASF_EDGE_TYPE,
			ASF_EDGE_WIDTH, ASF_EDGE_COLOUR, ASF_TEXT_FONT_INDEX,
			ASF_TEXT_PRECISION. ASF_CHARACTER_EXPANSION_FACTOR,
			ASF_CHARACTER_SPACING, ASF_TEXT_COLOUR ) */
	int ASF_value; /* INDIVIDUAL or BUNDLED */
.YM
CGI_Aspect_Source_Flags sets the Aspect Source Flags (ASFs).
The following ASF types are assigned: line type, line width, line width line colour, marker type, marker size, marker colour, interior style, hatch index, pattern index, fill colour, edge type, edge width, edge colour, text font index, text precision, character expansion factor, character spacing, text colour.
The aspect source flags determine the attribute values that will be bound to a primitive.
If the ASF for a particular aspect of primitive is set to INDIVIDUAL, the value used is the value of the corresponding individually specified attribute of the primitive.
If the ASF is set to BUNDLED, the value used is the value of the corresponding aspect of the bundle pointed to by the current bundle index for the primitive.
.YE
.YS CGI_Font_List
CGI_Font_List(nname, fontnamelist)
	int	nname; /* number of entries in font name list */
	char	*fontnamelist[]; /* font name list */
.YM
CGI_Font_List permits the selection of named fonts via text font index.
The first font defined in the font list is assigned to index 1. The second to index 2, etc.
.LP
The usable fonts are as follows:
.IP
6x10, 6x13, 8x13, 9x15
.IP
accordbfx, accordbssx, accordbsx, accordfx, accordssx, accordsx
.IP
cmi5fx, cmi5ssx, cmi5sx
.IP
cmr7ssx, cmr7sx
.IP
cor20fx, corfx
.IP
ctl25ssx, ctl25sx
.IP
delgatfx
.IP
dotx1fx
.IP
doty4fx, doty4ssx, doty4sx, doty5fx, doty5ssx, doty5sx,
.IP
helv10bfx, helv10bssx, helv10bsx, helv10fx, helv10ssx, helv10sx, helv12bfx, helv12bssx, helv12bsx, helv12fx, helv12ifx, helv12issx, helv12isx, helv12ssx, helv12sx
.IP
kilter, kilter10, kilter28, kilter28b, kilter28u, kilterb, kiltercrn, kilterd, kilterdb, kilter28bu
.IP
micr25fx, micr25sx
.IP
nonb44fx, nonb44ssx, nonb44sx, noni44fx, noni44ssx, noni44sx
.IP
oldengfx, oldengssx, oldengsx
.IP
rogue-b, rogue-n
.IP
rom-ascii, rom-kanji
.IP
sbdi40fx, sbdi40ssx, sbdi40sx
.IP
sbdr40fx, sbdr40ssx, sbdr40sx
.IP
sbdr66fx, sbdr66ssx, sbdr66sx
.IP
timrom10bfx, timrom10bssx, timrom10bsx, timrom10fx, timrom10ifx, timrom10issx, timrom10isx, timrom10ssx, timrom10sx, timrom12bfx, timrom12bssx, timrom12bsx, timrom12fx, timrom12ifx, timrom12issx, timrom12isx, timrom12ssx, timrom12sx
.IP
vsfont32(vector font)
.IP
vstadocfx, vstadocssx, vstadocsx
.IP
vtbold, vtdwidth, vtsingle
.YE
.NH 4
CGI CLOSED FIGURE OPTION SET
.LP
.YS CGI_Begin_Figure
CGI_Begin_Figure()
.YM
CGI_Begin_Figure enters the CGI to the state figure open. During the figure open state, a closed figure is constructed using line functions, edge attribute functions, CGI_Close function, and CGI_Implicit_Edge_Visibility function.
If the CGI is already in the figure open state, the previous portion of the closed figure boundary definition is discarded, and the CGI remains in the figure open state.
.YE
.YS CGI_End_Figure
CGI_End_Figure()
.YM
CGI_End_Figure causes transition out of the figure open state which was entered with CGI_Begin_Figure, and causes rendering of the closed figure constructed during the figure open state.
.LP
If the current region of the closed figure has not been explicitly closed, and the last point of the last line function is not coincident with the current closure point, an implicit closure is performed by connecting the last point of the preceding line function to the current closure point. The visibility of this line segment is controlled by CGI_Implicit_Edge_Visibility.
.LP
If the CGI is not in state figure open, no action occurs.
.YE
.YS CGI_Close
CGI_Close()
.YM
CGI_Close is used only within the figure open state, for control of subregion construction within closed figures.
.LP
If the current region has not yet been closed by a preceding CGI_Close function, and the last point of the last line function is not coincident with the current closure point, then the current subregion is closed by a line segment connecting the last point of the preceding line function to the current closure point.
.LP
If the region has been previously closed, is empty, or the last point of the last line function is coincident with the current closure point, then no line segment is generated by this function.
.LP
The visibility of this line segment is controlled by CGI_Implicit_Edge_Visibility.
The CGI remains in the state figure open.
The first point of the next line function following a CGI_Close function becomes the new closure point, starting a new subregion.
If the CGI is not in the figure open state, no action occurs.
.YE
.YS CGI_Implicit_Edge_Visibility
CGI_Implicit_Edge_Visibility(flag)
int	flag;	/* implicit edge visibility (ON, OFF) */
.YM
CGI_Implicit_Edge_Visibility specifies whether edges added implicitly during the construction of a closed figure are to be rendered as visible or invisible.
Edges are added implicitly when the following situations arise in the figure open state:
.IP 1.
The first point of a line function is not coincident with the last point of the preceding line functions.
.IP 2.
The CGI_Disjoint_Polyline function is used.
.IP 3.
A CGI_Close function is invoked, and the last point of the preceding line function is not coincident with the current closure point(and there has not been an explicit close previously on this region).
.IP 4.
An CGI_End_Figure function is invoked, and the last point of the preceding line function is not coincident with the current closure point (and there has not been an explicit close previously on this region).
.LP
In each of these cases, the edge connecting the two points is added to the boundary definition.
This function may be used anywhere within a picture.
.YE
.NH 3
Inquiry Functions
.LP
.YS CGI_Inquire_Aspect_Source_Flag
CGI_Inquire_Aspect_Source_Flag(type, value)
	int	type;	/* ASF type */
	int	*value;	/* [OUT] INDIVIDUAL or BUNDLED */
.YM
CGI_Inquire_Aspect_Source_Flag returned the current value of the specified ASF.
The current value of the aspect source flags determines whether graphical display attributes are obtained from individual attributes or from bundles.
.YE
.YS CGI_Inquire_Line_Bundle_Representation
CGI_Inquire_Line_Bundle_Representation(index, type, widthSpecMode,
	width, colourSelectionMode, colour)
	int	index;
	int	*type; /* [OUT] line type indicator */
	int	*widthSpecMode; /* [OUT] line width specification mode */
	Size	*width; /* [OUT] line width specifier */
	int	*colourSelectionMode; /* [OUT] colour selection mode */
	Colour	*colour; /* [OUT] line colour specifier */
.YM
CGI_Inquire_Line_Bundle_Representation provides the values for the realized attributes at the indicated line bundle index in the line bundle table.
The line width specification mode and colour selection mode returned are those which were in effect at the time this bundle index was specified with line representation, or those that correspond to the modes used in the predefined representation.
.YE
.YS CGI_Inquire_Line_Indices
CGI_Inquire_Line_Indices(size, nentry, rentry, definedIndices)
	int	size;			/* size of list */
	int	*nentry;		/* [OUT] bundle table size */
	int	*rentry;		/* [OUT] returned list size */
	int	definedIndices[];	/* [OUT] */
.YM
CGI_Inquire_Line_Indices provides the number of entries in the line bundle table and the list of defined indices as output values.
.YE
.YS CGI_Inquire_Line_Individual_Attributes
CGI_Inquire_Line_Individual_Attributes(type, widthSpecMode, width,
		colourSelectionMode, colour, index)
		int	*type;		/* [OUT] line type indicator */
	int	*widthSpecMode; /* [OUT] line width specification mode */
	Size	*width;		/* [OUT] line width specifier */
	int	*colourSelectionMode;/* [OUT] colour selection mode */
	Colour	*colour;	/* [OUT] line colour specifier */
	int	*index;		/* [OUT] bundle index */
.YM
CGI_Inquire_Line_Individual_Attributes returns the current realized values of the individual line type, line width and line colour attributes, along with the current line bundle index.
The line width specification mode and colour selection mode returned are those which were in effect at the time the attribute was last specified, or to the default if the attribute function has not been used since CGI_Initialise.
.YE
.YS CGI_Inquire_Marker_Bundle_Representation
CGI_Inquire_Marker_Bundle_Representation(index, type, sizeSpecMode,
	size, colourSelectionMode, colour)
	int	index;		/* marker bundle index */
	int	*type; 		/* [OUT] marker type indicator */
	int	*sizeSpecMode;	/* [OUT] marker specification mode */
	Size	*size;		/* [OUT] marker size specifier */
	int	*colourSelectionMode; /* [OUT] colour selection mode */
	Colour	*colour;	/* [OUT] marker colour specifier */
.YM
CGI_Inquire_Marker_Bundle_Representation provides the realized values for the attribute at the indicated marker bundle index in the marker bundle table.
The marker size specification mode and colour selection mode returned are those which were in effect at the time this bundle index was specified with marker representation,  or those that correspond to the modes used in the predefined representation.
.YE
.YS CGI_Inquire_Marker_Indices
CGI_Inquire_Marker_Indices(nentry, definedIndices)
	int	size; /* size of list */
	int	*nentry; /* [OUT] number of marker bundle table entries */
	int	*rentry; /* [OUT] returned list size */
	int	definedIndices[];/* [OUT] list of defined polymarker
		indices */
.YM
CGI_Inquire_Marker_Indices provides the number of entries in the marker bundle table and the list of defined indices as output values.
.YE
.YS CGI_Inquire_Marker_Individual_Attributes
CGI_Inquire_Marker_Individual_Attributes(type, sizeSpecMode,
	size, colourSelectionMode, colour, index)
	int	*type;	/* [OUT] marker type indicator */
	int	*sizeSpecMode; /* [OUT] marker size specification mode
				 (ABSOLUTE, SCALED) */
	Size	*size; /* [OUT] marker size specifier */
	int	*colourSelectionMode; /* [OUT] colour selection mode
					(INDEXED, DIRECT) */
	Colour	*colour; /* [OUT] marker colour specifier */
	int	*index; /* [OUT] bundle index */
.YM
CGI_Inquire_Marker_Individual_Attributes the current realized values of the individual marker type, marker size and marker colour attributes, along with the current marker bundle index.
The marker size specifier mode and colour selection mode returned are those which were in effect at the time the attribute was last specified, or to the default if the attribute function has not been used since CGI_Initialise.
.YE
.YS CGI_Inquire_Fill_Bundle_Representation
CGI_Inquire_Fill_Bundle_Representation(index, interior,
colourSelectionMode, colour, hatch, pattern)
	int	index; /* fill bundle index */
	int	*interior; /* [OUT] interior style */
	int	*colourSelectionMode; /* [OUT] colour selection mode */
	Colour	*colour; /* [OUT] fill colour specifier */
	int	*hatch; /* [OUT] hatch index */
	int	*pattern; /* [OUT] pattern index */
.YM
CGI_Inquire_Fill_Bundle_Representation provides the realized values for the attributes at the indicated fill bundle index in the fill bundle table.
The colour selection mode returned is that which was in effect at the time this bundle index was specified with fill representation, or that which corresponds to the mode used in the predefined representation.
.YE
.YS CGI_Inquire_Fill_Indices
CGI_Inquire_Fill_Indices(size, nentry, rentry, definedIndices)
	int	size;			/* size of list */
	int	*nentry;		/* [OUT] table size */
	int	*rentry;		/* [OUT] returned list size */
	int	definedIndices[];	/* [OUT] index list */
.YM
CGI_Inquire_Fill_Indices provides the number of entries in the fill bundle table and the list of defined indices as output values.
.YE
.YS CGI_Inquire_Fill_Individual_Attributes
CGI_Inquire_Fill_Individual_Attributes(interior, colourSelectionMode,
	colour, hatch, pattern, refpoint, patternsize, index)
	int	*interior; /* [OUT] interior style */
	int	*colourSelectionMode; /* [OUT] colour selection mode
		(INDEXED, DIRECT) */
	Colour	*colour; /* [OUT] fill colour specifier */
	int	*hatch; /* [OUT] hatch index */
	int	*pattern; /* [OUT] pattern index */
	Point	*refpoint; /* [OUT] fill reference point */
	PatternSize	*patternsize; /* [OUT] pattern size */
	int	*index; /* [OUT] fill bundle index */
.YM
CGI_Inquire_Fill_Individual_Attributes returns the current realized values of the individual interior style, fill colour, hatch index and pattern index attributes , along with the current values of the fill bundle index, pattern size, and fill reference point.
The colour selection mode returned is that which was in effect at the time the attribute was last specified, or to the default if the attribute function has not been used since CGI_Initialise.
.YE
.YS CGI_Inquire_Pattern_Indices
CGI_Inquire_Pattern_Indices(size, nentry, rentry, definedIndices)
	int	size;			/* size of list */
	int	*nentry;		/* [OUT] bundle table size */
	int	*rentry;		/* [OUT] returned list size */
	int	definedIndices[];	/* [OUT] defined pattern indices */
.YM
CGI_Inquire_Pattern_Indices returns the number of entries in the pattern table and the list of defined indices.
.YE
.YS CGI_Inquire_Pattern_Table
CGI_Inquire_Pattern_Table(index, row, column, colourSelectionMode,
	localColourPrecision, colourlist)
	int	index;		/* pattern table index */
	int	*row, *column;  /* [OUT] row count and column count */
	int	*colourSelectionMode; /* [OUT] colour specification mode
		(INDEXED, DIRECT) */
	int	*localColourPrecision; /* [OUT] local colour precision */
	Colour	**colourlist; /* [OUT] colour list */
.YM
CGI_Inquire_Pattern_Table returns the pattern specification stored at the specified pattern index.
.YE
.YS CGI_Inquire_Edge_Bundle_Representation
CGI_Inquire_Edge_Bundle_Representation(index, type, widthSpecMode,
	width, colourSelectionMode, colour)
	int	index; /* edge bundle index */
	int	*type; /* [OUT] edge type indicator */
	int	*widthSpecMode; /* [OUT] edge width specification mode */
	Size	*width; /* [OUT] edge width specifier */
	int	*colourSelectionMode; /* [OUT] colour selection mode */
	Colour	*colour; /* [OUT] edge colour specifier */
.YM
CGI_Inquire_Edge_Bundle_Representation provides the realized values for the attributes at the indicated edge bundle index in the fill bundle table.
The edge width specification mode and colour selection mode returned are those which were in effect at the time this bundle index was specified with edge representation, or those that correspond to the modes used in the predefined representation.
.YE
.YS CGI_Inquire_Edge_Indices
CGI_Inquire_Edge_Indices(size, nentry, rentry, definedIndices)
	int	size;			/* size of list */
	int	*nentry;		/* [OUT] bundle table size */
	int	*rentry;		/* [OUT] returned list size */
	int	definedIndices[];	/* [OUT] list of defined edge indices */
.YM
CGI_Inquire_Edge_Indices provides the number of entries in the edge bundle table and the list of defined edge indices as output values.
.YE
.YS CGI_Inquire_Edge_Individual_Attributes
CGI_Inquire_Edge_Individual_Attributes(visibility, type,
	widthSpecMode, width, colourSelectionMode, colour, index)
	int	*visibility; /* [OUT] edge visibility */
	int	*type; /* [OUT] edge type indicator */
	int	*widthSpecMode; /* [OUT] edge width specification mode
		(ABSOLUTE, SCALED) */
	Size	*width; /* [OUT] edge width specifier */
	int	*colourSelectionMode; /* [OUT] colour selection mode
		(INDEXED, DIRECT) */
	Colour	*colour;/* [OUT] edge colour specifier */
	int	*index; /* [OUT] edge bundle index */
.YM
CGI_Inquire_Edge_Individual_Attributes returns the current realized values of the individual edge visibility, edge type, edge width and edge colour attributes, along with the current value of the edge bundle index.
The edge width specification mode and colour selection mode returned are those which were in effect at the time the attribute was last specified, or to the default if the attribute function has not been used since CGI_Initialise.
.YE
.YS CGI_Inquire_Text_Bundle_Representation
CGI_Inquire_Text_Bundle_Representation(index, font, precision,
	exfactor, spacing, colourSelectionMode, colour)
	int	index; /* text bundle index */
	int	*font; /* [OUT] text font index */
	int	*precision; /* [OUT] text precision */
	float	*exfactor; /* [OUT] character expansion factor */
	float	*spacing; /* [OUT] character spacing */
	int	*colourSelectionMode; /* [OUT] colour selection mode */
	Colour	*colour; /* [OUT] text colour specifier */
.YM
CGI_Inquire_Text_Bundle_Representation provides the realized values for the attributes at the indicated text bundle index in the text bundle table.
The colour selection mode returned is that which was in effect at the time this bundle index was specified with text representation, or that which corresponds to the mode used in the predefined representation.
.YE
.YS CGI_Inquire_Text_Indices
CGI_Inquire_Text_Indices(size, nentry, rentry, definedIndices)
	int	size;		/* size of list */
	int	*nentry;	/* [OUT] bundle table size */
	int	*rentry;	/* [OUT] returned list size */
	int	definedIndices[]; /* [OUT] list of defined text indices */
.YM
CGI_Inquire_Text_Indices provides the number of entries in the text bundle table and the list of defined indices as output values.
.YE
.YS CGI_Inquire_Text_Individual_Attributes
CGI_Inquire_Text_Individual_Attributes(charset, altcharset, index,
	font, precision, exfactor, spacing, colourSelectionMode,
	colour, charheight, upVector, baseVector, path, hor_align,
	ver_align, cont_hor_align, cont_ver_align)
	int	*charset; /* [OUT] character set index */
	int	*altcharset; /* [OUT] alternate character set index */
	int	*index; /* [OUT] text bundle index */
	int	*font; /* [OUT] text font index */
	int	*precision; /* [OUT] text precision */
	float	*exfactor; /* [OUT] character expansion factor */
	float	*spacing; /* [OUT] character spacing */
	int	*colourSelectionMode; /* [OUT] colour selection mode */
	Colour	*colour; /* [OUT] text colour specifier */
	int	*charheight; /* [OUT] character height */
	Vector	*upVector; /* [OUT] character up vector */
	Vector	*baseVector; /* [OUT] character  base vector */
	int	*path; /* [OUT] text path */
	int	*hor_align; /* [OUT] horizontal text alignment */
	int	*ver_align; /* [OUT] vertical text alignment */
	float	*cont_hor_align; /* [OUT] continuous horizontal
		alignment */
	float	*cont_ver_align; /* [OUT] vertical horizontal
		alignment */
.YM
CGI_Inquire_Text_Individual_Attributes returns the current realized values of the individual text attributes, along with the current text  bundle index.
The colour selection mode returned is that which was in effect at the time the text colour was last specified, or that which corresponds to the mode used in the default value.
.YE
.YS CGI_Inquire_Colour_Table
CGI_Inquire_Colour_Table(index, nentry, rentry, value)
	int	index; /* starting colour index */
	int	nentry;		/* number of entries */
	int	*rentry;	/* [OUT] number of entries returned */
	Colour_Direct	value[]; /* [OUT] colour values */
.YM
CGI_Inquire_Colour_Table provides the colour values in the colour table for the indicated colour indices.
The number of entries returned will be less than or equal to the number of entries requested.
.YE
.YS CGI_Inquire_Colour_Selection_Mode
CGI_Inquire_Colour_Selection_Mode(colourSelectionMode)
	int	*colourSelectionMode;	/* [OUT] (DIRECT, INDEXED) */
.YM
CGI_Inquire_Colour_Selection_Mode returns the current colour selection mode.
.YE
.YS CGI_Inquire_Auxiliary_Colour_And_Transparency
CGI_Inquire_Auxiliary_Colour_And_Transparency(trans, colourMode,
	auxColor)
	int	*trans;		/* [OUT] (TRANSPARENT, OPAQUE) */
	int	*colourMode;	/* [OUT] colour selection mode.
		(DIRECT ,INDEXED) */
	Colour	*auxColor;	/* [OUT] auxiliary colour */
.YM
CGI_Inquire_Auxiliary_Colour_And_Transparency returns the current auxiliary colour and transparency.
The colour selection mode returned is that which was in effect at the time the auxiliary colour was last specified, or that which corresponds to the mode used in the default value.
.YE
.NH 3
Interrogation Functions
.LP
.YS CGI_Inquire_Supported_Colour
CGI_Inquire_Supported_Colour(nsimulcolour, navailcolour,
	colourtblsupport, background, overwrite, monochrome)
	int	*nsimulcolour;	/* [OUT] number of simultaneous colours */
	int	*navailcolour;	/* [OUT]  number of available colours */
	int	*colourtblsupport; /* [OUT] colour table supported */
	int	*background;	/* [OUT] background colour capability */
	int	*overwrite;	/* [OUT] colour overwrite capability */
	int	*monochrome;	/* [OUT] monochromatic device */
.YM
CGI_Inquire_Supported_Colour returns to the CGI data about how the device displays colours.
The drawing medium will always count as one colour, for both the 'nsimulcolour'  and the 'navailcolour'. Therefore, neither colour count may be less than two.
.YE
.YS CGI_Inquire_Closed_Figure_Support
CGI_Inquire_Closed_Figure_Support(nvert, edgeAttrChange)
	int	*nvert;/* [OUT] number of vertices */
	int	*edgeAttrChange;/* [OUT] Edge attribute changes (YES, NO) */
.YM
CGI_Inquire_Closed_Figure_Support returns details of support for the closed figure option set.
The number of vertices returned indicates how many points may be specified for a closed figure.
.LP
If the implementation supports rendering closed figures with portions of the edge taking on different edge attributes, it returns YES.
If it returns NO, then any edge attributes changed within the figure affect the CGI state list but are not stored with the boundary definition, and the closed figure is rendered with the set of edge attributes in effect at the time the CGI_Close function is received.
.YE
.bp
.NH 2
CGI INPUT
.LP
NOTE: The CGINEWS implementation does not support the input classes STROKE,
VALUATOR, and PICK.
.sp .5
.LP
The logical input devices correspond to physical devices as follows:
.sp .5
.TS
.if \n+(b.=1 .nr d. \n(.c-\n(c.-1
.de 35
.ps \n(.s
.vs \n(.vu
.in \n(.iu
.if \n(.u .fi
.if \n(.j .ad
.if \n(.j=0 .na
..
.nf
.nr #~ 0
.if n .nr #~ 0.6n
.ds #d .d
.if \(ts\n(.z\(ts\(ts .ds #d nl
.fc
.nr 33 \n(.s
.rm 80 81 82
.nr 80 0
.nr 38 \wInput Class
.if \n(80<\n(38 .nr 80 \n(38
.nr 38 \w\fILOCATOR\fR
.if \n(80<\n(38 .nr 80 \n(38
.nr 38 \w\fICHOICE\fR
.if \n(80<\n(38 .nr 80 \n(38
.nr 38 \w\fICHOICE\fR
.if \n(80<\n(38 .nr 80 \n(38
.nr 38 \w\fISTRING\fR
.if \n(80<\n(38 .nr 80 \n(38
.80
.rm 80
.nr 81 0
.nr 38 \wDevice Index
.if \n(81<\n(38 .nr 81 \n(38
.nr 38 \w0
.if \n(81<\n(38 .nr 81 \n(38
.nr 38 \w0
.if \n(81<\n(38 .nr 81 \n(38
.nr 38 \w1
.if \n(81<\n(38 .nr 81 \n(38
.nr 38 \w0
.if \n(81<\n(38 .nr 81 \n(38
.81
.rm 81
.nr 82 0
.nr 38 \wPhysical Input Device
.if \n(82<\n(38 .nr 82 \n(38
.nr 38 \wmouse
.if \n(82<\n(38 .nr 82 \n(38
.nr 38 \wmouse buttons
.if \n(82<\n(38 .nr 82 \n(38
.nr 38 \wkeyboard function keys
.if \n(82<\n(38 .nr 82 \n(38
.nr 38 \wkeyboard
.if \n(82<\n(38 .nr 82 \n(38
.82
.rm 82
.nr 38 1n
.nr 79 0
.nr 40 \n(79+(1*\n(38)
.nr 80 +\n(40
.nr 41 \n(80+(3*\n(38)
.nr 81 +\n(41
.nr 42 \n(81+(3*\n(38)
.nr 82 +\n(42
.nr TW \n(82
.nr TW +1*\n(38
.if t .if \n(TW>\n(.li .tm Table at line 1941 file Input is too wide - \n(TW units
.ne 5v+2p
.nr #I \n(.i
.in +(\n(.lu-\n(TWu-\n(.iu)/2u
.fc  
.nr #T 0-1
.nr #a 0-1
.nr #a 0-1
.eo
.de T#
.ds #d .d
.if \(ts\n(.z\(ts\(ts .ds #d nl
.mk ##
.nr ## -1v
.ls 1
.if \n(#T>=0 .nr #a \n(#T
.if \n(T. .vs \n(.vu-\n(.sp
.if \n(T. \h'|0'\s\n(33\l'|\n(TWu\(ul'\s0
.if \n(T. .vs
.if \n(#a>=0 .sp -1
.if \n(#a>=0 \h'|0'\s\n(33\h'-\n(#~u'\L'|\n(#au-1v'\s0\v'\n(\*(#du-\n(#au+1v'\h'|\n(TWu'
.if \n(#a>=0 .sp -1
.if \n(#a>=0 \h'|\n(TWu'\s\n(33\h'-\n(#~u'\L'|\n(#au-1v'\s0\v'\n(\*(#du-\n(#au+1v'
.ls
..
.ec
.nr 36 \n(.v
.vs \n(.vu-\n(.sp
\h'|0'\s\n(33\l'|\n(TWu\(ul'\s0
.vs \n(36u
.mk #a
.sp .3
.ta \n(80u \n(81u \n(82u 
.nr 31 \n(.f
.nr 35 1m
\&\h'|\n(40u'Input Class\h'|\n(41u'Device Index\h'|\n(42u'Physical Input Device
.sp .3
.nr 36 \n(.v
.vs \n(.vu-\n(.sp
\h'|0'\s\n(33\l'|\n(TWu\(ul'\s0
.vs \n(36u
.sp .3
.ta \n(80u \n(81u \n(82u 
.nr 31 \n(.f
.nr 35 1m
\&\h'|\n(40u'\fILOCATOR\fR\h'|\n(41u'0\h'|\n(42u'mouse
.ta \n(80u \n(81u \n(82u 
.nr 31 \n(.f
.nr 35 1m
\&\h'|\n(40u'\fICHOICE\fR\h'|\n(41u'0\h'|\n(42u'mouse buttons
.ta \n(80u \n(81u \n(82u 
.nr 31 \n(.f
.nr 35 1m
\&\h'|\n(40u'\fICHOICE\fR\h'|\n(41u'1\h'|\n(42u'keyboard function keys
.ta \n(80u \n(81u \n(82u 
.nr 31 \n(.f
.nr 35 1m
\&\h'|\n(40u'\fISTRING\fR\h'|\n(41u'0\h'|\n(42u'keyboard
.sp .3
.fc
.nr T. 1
.T# 1
.in \n(#Iu
.35
.nr #a 0
.TE
.if \n-(b.=0 .nr c. \n(.c-\n(d.-14
.sp .5
.NH 3
Required Input Functions
.NH 4
Input Functions
.LP
.YS CGI_Initialise_Input_Device
CGI_Initialise_Input_Device(input_Class, input_Device_Index)
	int input_Class; /* (CHOICE, LOCATOR, STRING) */
	int input_Device_Index;
.YM
CGI_Initialise_Input_Device sets the specified logical input device state to READY.
Any input actions are terminated.
The logical input device state list is set to its default initial values.
.YE
.YS CGI_Release_Input_Device
CGI_Release_Input_Device(input_Class, input_Device_Index)
	int input_Class; /* (CHOICE, LOCATOR, STRING) */
	int input_Device_Index;
.YM
CGI_Release_Input_Device sets the specified logical input device state to RELEASED. Any input actions are terminated.
.YE
.YS CGI_Set_Current_Value
CGI_Set_Current_Value(input_Class, input_Device_Index, value)
	int input_Class; /* (CHOICE, LOCATOR, STRING) */
	int input_Device_Index;
	InputValue value;
.YM
CGI_Set_Current_Value updates the current value of the specified logical input
device.
.YE
.YS CGI_Set_Input_Device_Data
CGI_Set_Input_Device_Data(input_Class, input_Device_Index,
	input_Device_Data_Record)
	int input_Class; /* (CHOICE, LOCATOR, STRING) */
	int input_Device_Index;
	InputDataRecord input_Device_Data_Record;
.YM
CGI_Set_Input_Device_Data updates the input device data of the specified logical
input device.
.YE
.YS CGI_Request
CGI_Request(input_Class, input_Device_Index, timeout, request_Status,
		validity_Status, trigger, value)
	int input_Class; /* (CHOICE, LOCATOR, STRING) */
	int input_Device_Index;
	int timeout;
	int *request_Status; /* [OUT] (TRIGGER_FIRED, BREAK, TIMEOUT) */
	int *validity_Status; /* [OUT] (VALUE_OK, VALUE_INVALID) */
	int *trigger; /* [OUT] */
	InputValue *value; /* [OUT] */
.YM
CGI_Request returns the logical input device value, the validity status, the
trigger fired, and the request status of the specified logical input device.
.LP
This implementation does not provide the timeout capability. If the timeout
value is less than zero, then a value is not returned until one of two events
occurs:
.LP
- a trigger associated with the specified logical input device fires, or
.LP
- a break action occurs.
.LP
If the timeout value is zero or greater than zero, this function returns
immediately, with the request status set to TIMEOUT.
If  the request status is BREAK or TIMEOUT the logical input device value and
the validity state are not defined.
If the validity state is set to VALUE_INVALID the logical input device value is
not defined.
.YE
.NH 4
Interrogation Functions
.LP
.YS CGI_Inquire_Input_Capabilities
CGI_Inquire_Input_Capabilities(error, number_Of_Choice_Input_Device,
		number_Of_Locator_Input_Device, number_Of_Pick_Input_Device,
		number_Of_String_Input_Device, number_Of_Stroke_Input_Device,
		number_Of_Valuator_Input_Device, number_Of_Triggers)
	int *error; /* [OUT] */
	int *number_Of_Choice_Input_Device; /* [OUT] */
	int *number_Of_Locator_Input_Device; /* [OUT] */
	int *number_Of_Pick_Input_Device; /* [OUT] */
	int *number_Of_String_Input_Device; /* [OUT] */
	int *number_Of_Stroke_Input_Device; /* [OUT] */
	int *number_Of_Valuator_Input_Device; /* [OUT] */
	int *number_Of_Triggers; /* [OUT] */
.YM
CGI_Inquire_Input_Capabilities returns the virtual device input description table.
.YE
.YS CGI_Inquire_Capabilities
CGI_Inquire_Capabilities(input_Class,
		input_Device_Index, error,
		list_Of_Supported_Echo_Types,
		list_Of_Supported_Prompt_Types,
		list_Of_Supported_Acknowledgement_Types,
		inputMaxima)
	int input_Class; /* (CHOICE, LOCATOR, STRING) */
	int input_Device_Index;
	int *error; /* [OUT] */
	int **list_Of_Supported_Echo_Types; /* [OUT] */
	int **list_Of_Supported_Prompt_Types; /* [OUT] */
	int **list_Of_Supported_Acknowledgement_Types; /* [OUT] */
	InputMaxima *inputMaxima; /* [OUT] */
.YM
CGI_Inquire_Capabilities returns the specified Logical Input Device Description Table.
.YE
.NH 4
Inquiry Functions
.LP
.YS CGI_Inquire_Input_Device_State_List
CGI_Inquire_Input_Device_State_List(input_Class,
		input_Device_Index, error,
		input_Device_State, input_Device_Data_Record,
		prompt_State, prompt_Type,
		acknowledgement_State, acknowledgement_Type,
		echo_State, echo_Type,
		echoAreaFirst, echoAreaSecond, echo_Data_Record,
		list_Of_Associated_Triggers)
	int input_Class; /* (CHOICE, LOCATOR, STRING) */
	int input_Device_Index;
	int *error; /* [OUT] */
	int *input_Device_State; /*[OUT] (RELEASED, READY,
		TRIGGER_ARMED, MEASURE_PENDING, EVENTS) */
	Input_Device_Data_Record *input_Device_Data_Record; /* [OUT] */
	int *prompt_State; /* [OUT] (ON, OFF) */
	int *prompt_Type; /* [OUT] */
	int *acknowledgement_State; /* [OUT] (ON, OFF) */
	int *acknowledgement_Type; /* [OUT] */
	int *echo_State; /* [OUT] (ON, OFF) */
	int *echo_Type; /* [OUT] */
	DC *echoAreaFirst;
	DC *echoAreaSecond;
	EchoDataRecord *echo_Data_Record; /* [OUT] */
	int **list_Of_Associated_Triggers; /* [OUT] */
.YM
CGI_Inquire_Input_Device_State_List returns the contents of the logical input device state list for the specified logical input device.
.YE
.YS CGI_Inquire_Input_Device_State
CGI_Inquire_Input_Device_State(input_Class, input_Device_Index,
	error, input_Device_State)
	int input_Class; /* (CHOICE, LOCATOR, STRING) */
	int input_Device_Index;
	int *error; /* [OUT] */
	int *input_Device_State; /*[OUT] (RELEASED, READY,
		TRIGGER_ARMED, MEASURE_PENDING, EVENTS) */
.YM
CGI_Inquire_Input_Device_State returns the current input device state.
.YE
.YS CGI_Inquire_Input_Device_Data
CGI_Inquire_Input_Device_Data(input_Class, input_Device_Index,
	error, input_Device_Data_Record)
	int input_Class; /* (CHOICE, LOCATOR, STRING) */
	int input_Device_Index;
	int *error; /* [OUT] */
	InputDataRecord *input_Device_Data_Record; /* [OUT] */
.YM
CGI_Inquire_Input_Device_Data returns the current input device data record.
.YE
.YS CGI_Inquire_Associated_Triggers
CGI_Inquire_Associated_Triggers (input_Class, input_Device_Index,
	error, list_Of_Associated_Triggers)
	int input_Class; /* (CHOICE, LOCATOR, STRING) */
	int input_Device_Index;
	int *error; /* [OUT] */
	int **list_Of_Associated_Triggers; /* [OUT] */
.YM
CGI_Inquire_Associated_Triggers returns the list of triggers associated with the logical input device.
.YE
.NH 3
Sample Option Set Function
.LP
.YS CGI_Sample
CGI_Sample(input_Class, input_Device_Index, value, validity_Status)
	int input_Class; /* (CHOICE, LOCATOR, STRING) */
	int input_Device_Index;
	InputValue *value; /* [OUT] */
	int *validity_Status; /* [OUT] (VALUE_OK, VALUE_INVALID) */
.YM
CGI_Sample immediately returns the current value and validity status of the specified logical input device.
.YE
.NH 3
Echo Option Set Functions
.NH 4
Echo Functions
.LP
.YS CGI_Set_Acknowledgement_State
CGI_Set_Acknowledgement_State(input_Class, input_Device_Index,
	acknowledgement_State)
	int input_Class; /* (CHOICE, LOCATOR, STRING) */
	int input_Device_Index;
	int acknowledgement_State; /* (ON, OFF) */
.YM
CGI_Set_Acknowledgement_State updates the acknowledgement state of the specified logical input device.
.YE
.YS CGI_Set_Echo_Data
CGI_Set_Echo_Data(input_Class, input_Device_Index, echo_Type,
	prompt_Type, acknowledgement_Type,
	echoAreaFirst, echoAreaSecond, echo_Data_Record)
	int input_Class; /* (CHOICE, LOCATOR, STRING) */
	int input_Device_Index;
	int echo_Type;
	int prompt_Type;
	int acknowledgement_Type;
	DC echoAreaFirst;
	DC echoAreaSecond;
	EchoDataRecord echo_Data_Record;
.YM
CGI_Set_Echo_Data updates the echo, prompt, and acknowledgement data of the
specified logical input device.
.LP
The echo type defines the form of echoing output which appears when the echo
state is ON.
.LP
The prompt type defines the form of prompting output which occurs when the
prompt state is ON.
.LP
The acknowledgement type defines the form of acknowledgement output which occurs
when the acknowledgement state is ON.
.LP
For OUTIN virtual devices, the echo area defines a rectangular area in DC; echoing, prompting, and acknowledgement output may be restricted to remain within this area on the display surface of the OUTIN virtual device.
The contents of the echo data record depend upon the echo type, the prompt type, and the acknowledgement type.
.YE
.YS CGI_Set_Echo_State
CGI_Set_Echo_State(input_Class, input_Device_Index, echo_State)
	int input_Class; /* (CHOICE, LOCATOR, STRING) */
	int input_Device_Index;
	int echo_State; /* (ON, OFF) */
.YM
CGI_Set_Echo_State sets the echo state for the specified logical input device.
Setting the echo state to ON causes the echo for the specified logical input device to be shown, according to the echo type, echo area, echo data record, and the current value of the logical input device.
Setting the echo state to OFF causes the echo for the specified logical input device to be removed from view but does not affect the current value of the logical input device.
.YE
.YS CGI_Set_Prompt_State
CGI_Set_Prompt_State(input_Class, input_Device_Index, prompt_State)
	int input_Class; /* (CHOICE, LOCATOR, STRING) */
	int input_Device_Index;
	int prompt_State; /* (ON, OFF) */
.YM
CGI_Set_Prompt_State updates the prompt state of the specified logical input
device.
.YE
.NH 4
Inquiry Functions
.LP
.YS CGI_Inquire_Prompt_State
CGI_Inquire_Prompt_State(input_Class, input_Device_Index,
	error, prompt_State)
	int input_Class; /* (CHOICE, LOCATOR, STRING) */
	int input_Device_Index;
	int *error; /* [OUT] */
	int *prompt_State; /* [OUT] (ON, OFF) */
.YM
CGI_Inquire_Prompt_State returns the current prompt state.
.YE
.YS CGI_Inquire_Acknowledgement_State
CGI_Inquire_Acknowledgement_State(input_Class, input_Device_Index,
	error, acknowledgement_State)
	int input_Class; /* (CHOICE, LOCATOR, STRING) */
	int input_Device_Index;
	int *error; /* [OUT] */
	int *acknowledgement_State; /* [OUT] (ON, OFF) */
.YM
CGI_Inquire_Acknowledgement_State returns the current acknowledgement state.
.YE
.YS CGI_Inquire_Echo_Data
CGI_Inquire_Echo_Data(input_Class, input_Device_Index, error,
		acknowledgement_Type, prompt_Type, echo_Type, echoAreaFirst,
		echoAreaSecond, echo_Data_Record)
	int input_Class; /* (CHOICE, LOCATOR, STRING) */
	int input_Device_Index;
	int *error; /* [OUT] */
	int *acknowledgement_Type; /* [OUT] */
	int *prompt_Type; /* [OUT] */
	int *echo_Type; /* [OUT] */
	DC *echoAreaFirst; /* [OUT] */
	DC *echoAreaSecond; /* [OUT] */
	EchoDataRecord *echo_Data_Record; /* [OUT] */
.YM
CGI_Inquire_Echo_Data returns the echo, prompt and acknowledgement data items.
.YE
.YS CGI_Inquire_Echo_State
CGI_Inquire_Echo_State (input_Class, input_Device_Index,
	error, echo_State)
	int input_Class; /* (CHOICE, LOCATOR, STRING) */
	int input_Device_Index;
	int *error; /* [OUT] */
	int *echo_State; /* [OUT] (ON, OFF) */
.YM
CGI_Inquire_Echo_State returns the current echo state.
.YE
.NH 3
Remote Echo Option Set Functions
.LP
.YS CGI_Initialise_Echo_Request
CGI_Initialise_Echo_Request(input_Class, input_Device_Index, timeout)
	int input_Class; /* (CHOICE, LOCATOR, STRING) */
	int input_Device_Index;
	int timeout;
.YM
CGI_Initialise_Echo_Request arms all triggers associated with the specified
logical input device and sets the logical input device state to TRIGGER_ARMED.
This implementation does not provide the timeout capability; see
CGI_Echo_Request.
.YE
.YS CGI_Echo_Request
CGI_Echo_Request(input_Class, input_Device_Index, request_Status,
		validity_Status, trigger, value)
	int input_Class; /* (CHOICE, LOCATOR, STRING) */
	int input_Device_Index;
	int *request_Status; /* [OUT] (TRIGGER_FIRED, BREAK, TIMEOUT) */
	int *validity_Status; /* [OUT] (VALUE_OK, VALUE_INVALID) */
	int *trigger; /* [OUT] */
	InputValue *value; /* [OUT] */
.YM
CGI_Echo_Request is used for remote echoing. The logical input device value, the
validity status, the index of the trigger that fired, and the request status of
the specified logical input device are returned.
If the timeout value is zero or greater than zero, CGI_Echo_Request returns
immediately with the request status set to TIMEOUT.
If the timeout value is less than zero, parameters are not returned until one of
three events occurs:
.LP
- a trigger associated with the specified logical input device fires, or
.LP
- a break action occurs, or
.LP
- the current value of the logical input device changes.
.LP
If the request status is MEASURE_CHANGED or BREAK the trigger index returned is
undefined.
.YE
.NH 3
Echo Output Option Set Functions
.LP
.NH 4
Echo Output Functions
.LP
.YS CGI_Set_Echo_Output_Data
CGI_Set_Echo_Output_Data(inputClass, echoIndex, currentValue,
	ackType, promptType, echoType,
	echoAreaFirst, echoAreaSecond, echoDataRecord)
	int inputClass; /* (CHOICE, LOCATOR, STRING) */
	int echoIndex;
	InputValue currentValue;
	int ackType;
	int promptType;
	int echoType;
	DC echoAreaFirst;
	DC echoAreaSecond;
	EchoDataRecord echoDataRecord;
.YM
CGI_Set_Echo_Output_Data updates the values of the echo state list of the
specified echo output entity.
The current value defines the first input value to echo; subsequent values are given by CGI_Update_Echo_Output.
.LP
The echo type defines the form of echoing output which appears when the echo
state is ON.
.LP
The prompt type defines the form of prompting output which occurs when the prompt state is set to ON.
.LP
The acknowledgement type defines the form of acknowledgement output which occurs, when the acknowledgement state is set to ON.
.LP
The echo area defines a rectangular area in DC; echoing, prompting, and acknowledgement output may be restricted to remain within this area on the display surface of the virtual device.
The contents of the echo data record depend upon the echo type, the prompt type,
and the acknowledgement type.
.YE
.YS CGI_Set_Acknowledgement_Output_State
CGI_Set_Acknowledgement_Output_State(inputClass, echoIndex, ackState)
	int inputClass; /* (CHOICE, LOCATOR, STRING) */
	int echoIndex;
	int ackState; /* (ON, OFF) */
.YM
CGI_Set_Acknowledgement_Output_State updates the acknowledgement state for the
specified echo output entity.
.LP
Setting the acknowledgement state to ON causes acknowledgement output to be performed. The form of the acknowledgement output is determined by the current acknowledgement type.
.LP
Setting the acknowledgement state to OFF causes acknowledgement output to be removed from the display surface.
.YE
.YS CGI_Set_Echo_Output_State
CGI_Set_Echo_Output_State(inputClass, echoIndex, echoState)
	int inputClass; /* (CHOICE, LOCATOR, STRING) */
	int echoIndex;
	int echoState; /* (ON, OFF) */
.YM
CGI_Set_Echo_Output_State updates the echo state for the specified echo output
entity.
Setting the echo state to ON causes the echo output to be shown on the display surface, according to the current echo type.
Setting the echo state to OFF causes the specified echo to be removed from the display surface.
.YE
.YS CGI_Set_Prompt_Output_State
CGI_Set_Prompt_Output_State(inputClass, echoIndex, promptState)
	int inputClass; /* (CHOICE, LOCATOR, STRING) */
	int echoIndex;
	int promptState; /* (ON, OFF) */
.YM
CGI_Set_Prompt_Output_State updates the prompt state for the specified echo index.
Setting the prompt state to ON causes prompting output to be performed.
Setting the prompt state to OFF causes any prompting output to be removed from the display surface.
The form of prompting is determined by the current prompt type associated with
the echo output entity.
.YE
.YS CGI_Update_Echo_Output
CGI_Update_Echo_Output(inputClass, echoIndex, newValue)
	int inputClass; /* (CHOICE, LOCATOR, STRING) */
	int echoIndex;
	InputValue newValue;
.YM
CGI_Update_Echo_Output updates the specified echo output state list with the new value.
If the echo output state is ON, then the display surface is updated to show the new value.
This function will cause any previous echo output to be removed and replaced with the echo output for the new value.
.YE
.NH 4
Inquiry Functions
.LP
.YS CGI_Inquire_Echo_Output_Capabilities
CGI_Inquire_Echo_Output_Capabilities(maxEchoes, echoTypesSupported,
		promptTypesSupported, ackTypesSupported, maxStringLength,
		maxStrokePoints)
	int	**maxEchoes; /* [OUT] */
	int	(**echoTypesSupported)[MAX_ECHO_TYPES]; /* [OUT] */
	int	**promptTypesSupported; /* [OUT] */
	int	**ackTypesSupported; /* [OUT] */
	int	*maxStringLength; /* [OUT] */
	int	*maxStrokePoints; /* [OUT] */
.YM
CGI_Inquire_Echo_Output_Capabilities returns the echo output description table.
.YE
.YS CGI_Inquire_Echo_Output_State_List
CGI_Inquire_Echo_Output_State_List(inputClass, echoIndex,
		currentValue, echoState, echoType, promptState, promptType,
		ackState, ackType, echoAreaFirst, echoAreaSecond,
		echoDataRecord)
	int inputClass;
	int echoIndex;
	InputValue *currentValue;
	int *echoState; /* [OUT] echo state (ON, OFF) */
	int *echoType; /* [OUT] echo type */
	int *promptState; /* [OUT] prompt state (ON, OFF) */
	int *promptType; /* [OUT] prompt type */
	int *ackState; /* [OUT] acknowledgement state (ON, OFF) */
	int *ackType; /* [OUT] acknowledgement type */
	DC *echoAreaFirst; /* [OUT] */
	DC *echoAreaSecond; /* [OUT] */
	EchoDataRecord *echoDataRecord; /* [OUT] echo data record */
.YM
CGI_Inquire_Echo_Output_State_List returns the echo output state list.
.YE
.bp
.NH 2
CGI RASTER OPTION SET
.LP
.NH 3
Raster Output Functions
.LP
.YS CGI_Pixel_Array
CGI_Pixel_Array(org_p, xcnt, ycnt, vxcnt1, vxcnt2,
	vycnt1, vycnt2, col_prec, colours)
	Point	org_p;		/* origin point (P) */
	int	xcnt, ycnt;	/* xcount and ycount (2I) */
	int	vxcnt1, vxcnt2;	/* valid xcount (2I) */
	int	vycnt1, vycnt2;	/* valid ycount (2I) */
	int	col_prec; /* colour precision: 1, 4, 8 */
	unsigned short	*colours;
		/* colour specifiers  abs(xcount*ycount) */
.YM
CGI_Pixel_Array assigns a rectangular array of device independent colour specifiers to a rectangular array of pixels.
The absolute values of xcnt and ycnt dimension the rectangular array of device independent color specifiers.
Valid xcnt and valid ycnt specify the subrectangle within this array which is to be drawn.
The origin org_p is the location in VDC space at which the first color value is to be placed.
.LP
Xcnt defines how many pixels are in each row.
If xcount > 0, then the row extends toward increasing VDC x from the origin point.
If xcount < 0, then the row extends toward decreasing VDC x from the origin point.
.LP
Ycnt defines how many rows of pixel there are.
If ycnt > 0, then each new row is toward increasing VDC y.
If ycnt < 0, then each new row is toward decreasing VDC y.
.LP
If xcnt * ycnt = 0, nothing is drawn.
Valid xcnt and valid ycnt specify the first and last values of abs(xcnt) and abs(ycnt) which contain valid color specifiers.
.LP
If the entire array contains valid color specifiers, then valid xcnt = (1, abs(xcnt)) and valid xcnt = (1, abs(ycnt)).
Only pixels corresponding to the valid color specifiers should be drawn.
Valid xcnt = (0,0) or valid ycnt = (0,0) implies that none of the data is valid and thus nothing need be drawn.
.YE
.NH 3
Raster Attribute Functions
.LP
.YS CGI_Mapped_Bitmap_Foreground_Colour
CGI_Mapped_Bitmap_Foreground_Colour(colour)
	Colour	colour;	/* colour specifier */
.YM
CGI_Mapped_Bitmap_Foreground_Colour specifies the colour to be mapped to the "foreground" pixels of a mapped bitmap.
.YE
.NH 3
Raster Control Functions
.LP
.YS CGI_Create_Bitmap
CGI_Create_Bitmap(ext_p1, ext_p2, type, bm_idx)
	Point	ext_p1, ext_p2;	/* bitmap extent */
	int	type;		/* (MAPPED, FULL_DEPTH) */
	int	*bm_idx;	/* [OUT] bitmap index */
.YM
CGI_Create_Bitmap allocates a bitmap sufficient to contain the extent specified by the two points which define the diagonal corners of a rectangle in VDC space in the same manner as the two points used in CGI_VDC_Extent.
.LP
Full depth bitmaps represent each pixel with the same number of bits as does a displayable bitmap, thus full-depth bitmaps are able to represent the complete color capabilities of the device.
.LP
Mapped bitmaps are useful for certain common applications such as the storage of raster fonts.
A pixel in a mapped bitmap can only assume two values:"foreground" or "background".
Whenever a mapped bitmap is used in a bitblt operation, each foreground pixel is mapped into the current value of mapped bitmap foreground colour, and each background pixel is mapped into the current value of auxiliary colour.
.YE
.YS CGI_Delete_Bitmap
CGI_Delete_Bitmap(bm_idx)
	int	bm_idx;		/* bitmap index */
.YM
CGI_Delete_Bitmap deletes the specified bitmap.
.YE
.YS CGI_Select_Drawing_Bitmap
CGI_Select_Drawing_Bitmap(bm_idx)
	int	bm_idx;		/* bitmap index */
.YM
CGI_Select_Drawing_Bitmap selects the bitmap into which all future output primitives will draw.
.YE
.YS CGI_Display_Bitmap
CGI_Display_Bitmap(bm_idx)
	int	bm_idx;		/* bitmap index */
.YM
CGI_Display_Bitmap selects the displayable bitmap to be displayed.
.YE
.YS CGI_Two_Operand_Bitblt
CGI_Two_Operand_Bitblt(src_bm_idx, src_p, dest_p, xoff, yoff)
	int	src_bm_idx;	/* source bitmap */
	Point	src_p;		/* source origin */
	Point	dest_p;		/* destination origin */
	int	xoff;		/* X offset */
	int	yoff;		/* Y offset */
.YM
CGI_Two_Operand_Bitblt is used to move a rectangular subregion of the source bitmap to the destination bitmap (specified by the CGI_Select_Drawing_Bitmap primitive), using the current drawing mode and transparency.
.LP
The rectangular regions in the source and destination bitmaps are defined by two points representing the diagonal corners of a rectangle.
One corner in each bitmap is defined explicitly with the source/destination origin parameters.
The other corner point in each bitmap is found by adding the signed x and y offset parameters to the coordinates of the origin points.
.LP
The source data is not affected by the transfer unless the source and destination fields overlap.
In this case, the resulting source and destination fields will appear in the same way they would have had the source data first been copied to a temporary buffer and from there combined with the destination.
.YE
.YS CGI_Tile_Two_Operand_Bitblt
CGI_Tile_Two_Operand_Bitblt(pat_bm_idx, pat_p1, pat_p2,
	dest_p1, dest_p2)
	int	pat_bm_idx;	/* pattern bitmap */
	Point	pat_p1, pat_p2;	/* pattern region */
	Point	dest_p1, dest_p2; /* destination region */
.YM
CGI_Tile_Two_Operand_Bitblt fills a rectangular subregion of the destination bitmap with a repeating pattern, using the current drawing mode and transparency (with the pattern as the source).
Pattern region specifies the location and extent of the pattern in the pattern bitmap.
.LP
The fill area reference point primitive is used to specify the alignment of the first specified point of the pattern region in the destination.
Destination region specifies the VDC location and extent of the rectangular subregion of the destination bitmap (specified by select drawing bitmap) to be filled with the pattern.
.LP
The pattern data is not affected by the transfer unless the pattern and destination fields overlap.
.YE
.YS CGI_Drawing_Mode
CGI_Drawing_Mode(draw_mode)
	int	draw_mode;	/* drawing mode */
.YM
CGI_Drawing_Mode sets the drawing mode.
Drawing mode is an integer in the range [0..15] which defines the logical operation between the source and destination during all output operations except CGI_Tile_Two_Operand_Bitblt ( which has its own drawing mode passed as a parameter).
.LP
The 16 possible combinations are defined as follows
(d' = resulting destination bit value,
 d = original destination bit value,
 s = original source bit value):
.DS
	draw_mode   	Logical Operation
	-----------------------------------------
	    0		d' = 0
	    1 		d' = s AND d
	    2		d' = s AND (NOT d)
	    3		d' = s
	    4		d' = (NOT s) AND d
	    5		d' = d
	    6		d' = s XOR d
	    7		d' = s OR d
	    8		d' = NOT (s OR d)
	    9		d' = NOT (s XOR d)
	   10		d' = NOT d
	   11		d' = s OR (NOT d)
	   12		d' = NOT s
	   13		d' = (NOT s) OR d
	   14		d' = NOT (s AND d)
	   15		d' = 1
.DE
.YE
.NH 3
Interrogation Functions
.LP
.YS CGI_Inquire_Displayable_Bitmaps
CGI_Inquire_Displayable_Bitmaps(nbm)
	int	*nbm;	/* [OUT] number of displayable bitmaps */
.YM
CGI_Inquire_Displayable_Bitmaps returns the number of displayable bitmaps supported.
.YE
.YS CGI_Inquire_Bitmap_Formats
CGI_Inquire_Bitmap_Formats(bm_fmts)
	int	*bm_fmts;	/* [OUT] bitmap formats supported
		(CGI_FULL_DEPTH_ONLY, CGI_FULL_DEPTH_AND_RESTRICTED_MAPPED,
		CGI_FULL_DEPTH_AND_MAPPED) */
.YM
CGI_Inquire_Bitmap_Formats returns the bitmap formats supported.
.YE
.YS CGI_Inquire_Preferred_Bitblt_Pattern_Size
CGI_Inquire_Preferred_Bitblt_Pattern_Size(ext_x, ext_y)
	int	*ext_x;		/* [OUT] pattern X extent (VDC) */
	int	*ext_y;		/* [OUT] pattern Y extent (VDC) */
.YM
CGI_Inquire_Preferred_Bitblt_Pattern_Size specifies the pattern size which gives optimum performance for the device by pattern X extent and pattern Y extent.
.YE
.NH 3
Raster Inquiry Functions
.LP
.YS CGI_Inquire_Current_Drawing_Mode
CGI_Inquire_Current_Drawing_Mode(draw_mode)
	int	*draw_mode; /* [OUT] drawing_mode */
.YM
CGI_Inquire_Current_Drawing_Mode returns the current drawing mode.
.YE
.YS CGI_Inquire_Drawing_Bitmap
CGI_Inquire_Drawing_Bitmap(bm_idx)
	int	*bm_idx; /* [OUT] bitmap index */
.YM
CGI_Inquire_Drawing_Bitmap returns the bitmap index of the current drawing bitmap.
.YE
.YS CGI_Inquire_Display_Bitmap
CGI_Inquire_Display_Bitmap(bm_idx)
	int	*bm_idx; /* [OUT] bitmap index */
.YM
CGI_Inquire_Display_Bitmap returns the bitmap index of the currently displayed bitmap.
.YE
.YS CGI_Inquire_Mapped_Bitmap_Foreground_Colour
CGI_Inquire_Mapped_Bitmap_Foreground_Colour(colour)
	Colour	*colour; /* [OUT] colour */
.YM
CGI_Inquire_Mapped_Bitmap_Foreground_Colour returns the current bitmap foreground colour.
.YE
.YS CGI_Inquire_Pixel_Array
CGI_Inquire_Pixel_Array(org_p, xcnt, ycnt, vxcnt1, vxcnt2,
	vycnt1, vycnt2, col_prec, colours)
	Point	org_p;			/* origin point */
	int	xcnt, ycnt;		/* xcount and ycount */
	int	*vxcnt1, *vxcnt2;	/* [OUT] valid xcount */
	int	*vycnt1, *vycnt2;	/* [OUT] valid ycount */
 	int	col_prec; /* colour precision: 1, 4, 8 */
	unsigned short	*colours; /* colours abs(xcount*ycount) */
.YM
CGI_Inquire_Pixel_Array reads abs(xcnt * ycnt) color values from the device.
The origin is the location in VDC space at which the first color value is located.
.LP
Xcnt defines how many pixels are in each row. If xcnt > 0, then the row extents toward increasing VDC  X from the origin point. If xcnt < 0, then the row extents toward decreasing VDC X from the origin point.
.LP
Ycnt defines how many rows of pixels there are. If ycnt > 0, then each new row is toward increasing VDC Y. If ycnt < 0, then each new row is toward decreasing VDC Y.
.LP
Pixels are read in row-major order, beginning with the row specified by the origin point.
If xcnt * ycnt = 0, nothing is read.
Valid xcnt and valid ycnt specify the first and last values of abs(xcnt) and abs(ycnt) which contain valid color specifiers.
If the entire rectangle contains valid color specifiers, then valid xcnt = (1, abs(xcnt)) and valid ycnt = (1,abs(ycnt)).
.LP
If no data was returned, valid xcnt = (0,0) and valid ycnt = (0,0).
The clipping rectangle has no effect on this primitive.
.YE
.bp
.SH
Appendix A \- Sample Programs
.PP
This appendix shows some sample programs using \fBcginews\fP.
.SH
A.1 Spiral
.PP
The following program draws a spiral.
.sp 2
.ID
.ft CW
#include <math.h>
#include <cgi.h>

#define PI	3.141593

static Point	pointlist[200];

Point point(x, y)
{
	Point	p;
	p.x = x; p.y = y; return(p);
}

main()
{
	int		i;
	double		theta;

	/* first, initialise CGI */
	CGI_Initialise();

	/* set vdc-extent and clip-rectangle */
	CGI_VDC_Extent(point(0, 0), point(10000, 10000));
	CGI_Clip_Rectangle(point(0, 0), point(10000, 10000));

	for (i = 0; i < 200; i++) {
		theta = ((i % 40) / 40.0 * 2.0 * PI);
		pointlist[i].x = 5000 + cos(theta) * (i * 15);
		pointlist[i].y = 5000 + sin(theta) * (i * 15);
	}

	/* spiral */
	CGI_Line_Type(L_DASH);		/* default is L_SOLID */
	CGI_Polyline(200, pointlist);

	sleep(5);

	/* terminate CGI */
	CGI_Terminate();

	exit(0);
}
.ft
.DE
.bp
.SH
A.2 Pie Chart
.PP
The following program draws a simple pie chart.
.sp 2
.ID
.ft CW
#include <math.h>
#include <cgi.h>

#define PI	3.141593

static int	data[4] = { 45, 30, 15, 10 };	/* ( % ) */

Point point(x, y)
{
	Point	p;
	p.x = x; p.y = y; return(p);
}

main()
{
	static Point	cp = { 500, 500 };	/* center */
	Vector		vec[4];
	int		r = 400, sum = 0, i;
	double		theta;
	Point		point();

	/* first, initialise CGI */
	CGI_Initialise();

	/* force isotoropy mapping */
	CGI_Device_Viewport_Specification_Mapping(
		CGI_CTL_FORCED, CGI_CTL_CENTER, CGI_CTL_CENTER);

	/* set vdc-extent and clip-rectangle */
	CGI_VDC_Extent(point(0, 1000), point(1000, 0));
	CGI_Clip_Rectangle(point(0, 0), point(1000, 1000));

	for (i = 0; i < 4; i++) {
		theta = (sum / 100.0 * 2.0 * PI);
		vec[i].x = sin(theta) * 100.0;
		vec[i].y = cos(theta) * 100.0;
		sum += data[i];
	}

	/* draw arc */
	CGI_Edge_Visibility(ON);

	CGI_Interior_Style(I_SOLID);
	CGI_Circular_Arc_Center_Close(cp, vec[1], vec[0], r, PIE);
	
	CGI_Interior_Style(I_HATCH);
	CGI_Hatch_Index(H_PSNSC);	/* crosshatch */
	CGI_Circular_Arc_Center_Close(cp, vec[2], vec[1], r, PIE);

	CGI_Hatch_Index(H_PSESPL);	/* positive slope */
	CGI_Circular_Arc_Center_Close(cp, vec[3], vec[2], r, PIE);

	CGI_Hatch_Index(H_VESPL);	/* vertical */
	CGI_Circular_Arc_Center_Close(cp, vec[0], vec[3], r, PIE);

	/* print title */
	CGI_Text_Alignment(A_CENTER, A_BOTTOM, 0.0, 0.0);
	CGI_Text(point(500, 20), FINAL, "CGI Sample");

	sleep(10);

	/* terminate CGI */
	CGI_Terminate();

	exit(0);
}
.ft
.DE
.bp
.SH
A.3 Rectangle
.PP
This programs draws a rectangle.
It demonstrates the use of the input functions of \fBcginews\fP.
First, a small cross cursor appears on the screen and is moved with
the mouse. If mouse button is pressed, a rubber band rectangle
is displayed instead of cross cursor, and if mouse button is pressed again,
a hatched rectangle is drawn.
.sp 2
.ID
.ft CW
#include <cgi.h>

Point point(x, y)
{
	Point	p;
	p.x = x; p.y = y; return(p);
}

main()
{
	EscapeDataRecord	escapeDataRecord;
	DC				p0, p1;
	int				dmy1, dmy2;
	Rectangle			rect;
	int				stat, vstat, trig;
	InputValue	value;
	EchoDataRecord		echodata;
	DC			echoAreaFirst, echoAreaSecond;

	/* first, initialise CGI */
	CGI_Initialise();

	escapeDataRecord.error_Reaction = ON;
	CGI_Escape(ERROR_REACTION, escapeDataRecord);

	/* set echo area */
	CGI_Device_Viewport_Specification_Units(CGI_CTL_PHYSICAL_DEVICE);
	CGI_Inquire_Device_Physical_Coordinate_System(
			&p0, &p1, &dmy1, &dmy2);
	echoAreaFirst = p0;	/* echo area is full screen */
	echoAreaSecond = p1;

	/* set vdc-extent and clip-rectangle */
	CGI_VDC_Extent(point(0, 1000), point(1000, 0));
	CGI_Clip_Rectangle(point(0, 0), point(1000, 1000));

	/* initialise input device (mouse:locator) */
	CGI_Initialise_Input_Device(LOCATOR, 0);
	value.locator_Value.x = 500;
	value.locator_Value.y = 500;
	CGI_Set_Current_Value(LOCATOR, 0, value);	/* initial position */

	/* set echo-type tracking-cross */
	CGI_Set_Echo_Data(LOCATOR, 0, TRACKING_CROSS, PROMPT_TONE,
		ACK_TONE, echoAreaFirst, echoAreaSecond, echodata);
	CGI_Set_Echo_State(LOCATOR, 0, ON);	/* echo on */
	CGI_Set_Prompt_State(LOCATOR, 0, ON);	/* prompt on */

	/* get first corner */
	CGI_Request(LOCATOR, 0, -1, &stat, &vstat, &trig, &value);
	rect.first = value.locator_Value;

	/* set rubberband-rectangle first corner */
	echodata.echo.locator.echo5.initial_Position = rect.first;
	/* change echo-type to rubberband-rectangle */
	CGI_Set_Echo_Data(LOCATOR, 0, RUBBER_RECT, PROMPT_TONE,
		ACK_TONE, echoAreaFirst, echoAreaSecond, echodata);

	/* get second corner */
	CGI_Request(LOCATOR, 0, -1, &stat, &vstat, &trig, &value);
	rect.second = value.locator_Value;

	CGI_Set_Echo_State(LOCATOR, 0, OFF);	/* echo off */
	CGI_Set_Prompt_State(LOCATOR, 0, OFF);	/* prompt off */

	/* release input device (mouse) */
	CGI_Release_Input_Device(LOCATOR, 0);

	/* draw rectangle */
	CGI_Edge_Visibility(ON);		/* draw edge */
	CGI_Interior_Style(I_HATCH);
	CGI_Rectangle(rect.first, rect.second);

	/* terminate CGI */
	CGI_Terminate();

	sleep(5);

	exit(0);
}
.ft
.DE
