.\"##
.\" $XConsortium: p232,v 5.4 94/04/17 20:57:07 keith Exp $
.\"##
.\"## 
$XMCOPY
.\"## Copyright (c) 1990, 1991 by Sun Microsystems, Inc. 
.\"## 
.\"##                         All Rights Reserved
.\"## 
.\"## Permission to use, copy, modify, and distribute this software and its 
.\"## documentation for any purpose and without fee is hereby granted, 
.\"## provided that the above copyright notice appear in all copies and that
.\"## both that copyright notice and this permission notice appear in 
.\"## supporting documentation, and that the name of Sun Microsystems,
.\"## not be used in advertising or publicity 
.\"## pertaining to distribution of the software without specific, written 
.\"## prior permission.  
.\"## 
.\"## SUN MICROSYSTEMS DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, 
.\"## INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
.\"## EVENT SHALL SUN MICROSYSTEMS BE LIABLE FOR ANY SPECIAL, INDIRECT OR
.\"## CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
.\"## USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
.\"## OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
.\"## PERFORMANCE OF THIS SOFTWARE.
.T#
.TH "INTRO_PHIGS" 3P "15 August 1991"
.IX "X Window System" "INTRO_PHIGS" "X Window System" "INTRO_PHIGS"
.IX "Introduction" "INTRO_PHIGS"
.IX "Introduction to the \s-2PEX-SI\s0" "" "" "" 
.SH NAME
intro_phigs \- introduction to the \s-2PEX-SI\s0 graphics library
.SH DESCRIPTION
The \s-2PEX-SI\s+2 graphics library implements the \fIProgrammer's
Hierarchical Interactive Graphics System\fP (\s-2PHIGS\s+2) and portions of
the proposed \s-2PHIGS\s+2 extension (\s-2PHIGS PLUS\s+2).  This \s-2PHIGS\s+2
implementation is designed specifically and exclusively for use with \s-2X\s+2
servers that implement the \s-2PEX\s+2 extension.
.LP
These manual pages describe the syntax of each function in the \s-2PEX-SI\s+2 
graphics library. There is one entry for each function.
.SS Reserved Names
.IX "Reserved Names" description "" "" "" ""
\s-2PEX-SI\s0 applications should avoid using variable and function names 
that conflict with names that \s-2PEX-SI\s0 uses internally.
Since \s-2PEX-SI\s0 programs are linked to the Xlib library, 
do not use symbols that start with the prefixes reserved by that package, 
symbols in the Math library, or system calls.
The public symbol names provided by \s-2PEX-SI\s0 all start with \fIp\fP.
To avoid conflicts with the \s-2PEX-SI\s0 name space, do not define any 
of the following symbols:  
.sp .5
.RS
.br
\(bu  \s-2PHIGS\s+2 or \s-2PHIGS PLUS C\s+2 function names
.br
\(bu  Names with the prefixes \fBphigs\fP, \fBphg\fP,  \fBP\fP, or \fBp\fP.  
.br
\(bu  System library symbols, such as \fBtime\fP.  
.RE
.SS Abbreviations
.IX "Abbreviations" description "" "" "" ""
.LP
The following list describes the abbreviations used in this manual.  
.sp .5
.TS
center, box, tab(%);
cb | cb
l l.
Abbreviation%Name
_
.sp .3
ANSI%American National Standards Institute
ASF%aspect source flag
CSS%Central Structure Store
DC%device coordinates
GDP%generalized drawing primitive
GSE%generalized structure element
HLHSR%hidden line/hidden surface removal
ISO%International Organisation for Standards
MC%modelling coordinates
NPC%normalized projection coordinates
NURB%non-uniform rational B-spline
PDT%\s-2PHIGS\s+2 description table
PET%prompt/echo type
RGB%red/green/blue colour model
TLC%text local coordinates
WC%world coordinates
WS%workstation
.sp .3
.TE
.LP
\s-2PHIGS\s+2 has four operating state variables, 
each with two possible values:  
.sp .5
.TS
center, box, tab(%);
cb | cb | cb
l l l.
Variable Name%Open State Enumeraion Constant%Closed State Enumeration Constant
_
.sp .3
System State%PHOP%PHCL
Workstation State%WSOP%WSCL
Structure State%STOP%STCL
Archive State%AROP%ARCL
.sp .3
.TE
Each \s-2PHIGS\s+2 function requires that \s-2PHIGS\s+2 be in a certain
operating state before the function can be called.
The \fI\s-2SYNOPSIS\s+2\fP section of each function specifies the
required value that each of the four operating state variables must have
to call that function.
An asterisk (*) is used when an operating state variable 
may be in either state (that is, does not matter).
All of the operating state variables are initially set to the closed value.
.SS Extensions to the \s-2PHIGS\s+2 Standard
.IX "Extensions to the \s-2PHIGS\s+2 Standard" description "" "" "" ""
The \s-2PEX-SI\s0 library contains the following optional functions
that are not in the \s-2PHIGS\s+2 specification, but are extremely useful.
.sp .2
.in +.5i
.nf
\s-2WORKSTATION TYPE CREATE\s+2
\s-2WORKSTATION TYPE DESTROY\s+2
\s-2WORKSTATION TYPE GET\s+2
\s-2WORKSTATION TYPE SET\s+2
.fi
.sp .2
.in -.5i
.SS Include Files
.IX "Include Files" description "" "" "" ""
.LP
\s-2PEX-SI\s0 applications should use the constants and enumerated values 
defined in the \s-2PHIGS\s+2 files to decrease the possibility of 
passing bad data and avoid conflict with future changes.
C applications should include the file \fBphigs.h\fP.
See the example programs in Xsrc/extensions/clients/\s-2PEX\s+2/demo.
.SS C Binding Notes
.IX "C Binding Notes" description "" "" "" ""
The C binding used for the \s-2PEX-SI\s+2 graphics library matches the
\s-2PHIGS\s+2 C Binding (Draft \s-1ISO\s+1 \s-1DIS\s+1 9593-4:199x(E), 1 August 1990), 
for the \s-2PHIGS\s+2 standard functions, with several deviations.
These deviations either correct bugs in the \s-2DIS\s+2 binding
or anticipate changes that will be made when the \s-2DIS\s+2 is approved.
The following lists the \s-2PEX SI\s+2 deviations from the \s-2DIS\s+2 binding.
.IP 1.
In the definition of the data type Pcolr_rep, the name of the Phsv field is
\fIhsv\fR, not \fIhlv\fR.
.IP 2.
All Pdouble usage in the \s-2DIS\s+2 binding is Pfloat in the \s-2PEX-SI\s+2 binding.
.IP 3.
Everywhere the \s-2DIS\s+2 binding lists the parameter ``Pstore *store'',
\s-2PEX-SI\s+2 uses ``Pstore store''.  In other words, the store object is
passed directly, and not as a pointer the store object.
.IP 4.
The Pstring_data and Pstring_data3 structures in \s-2PEX-SI\s+2 are different 
from those specified in the \s-2DIS\s+2 binding.
Pstring_data and Pstring_data3 are defined as follows in \s-2PEX-SI\s+2:
.nf
.ta .5i +.5i +.5i +.5i
.sp .2
typedef struct {
.sp .2
	Pint	buffer_size;	/* input buffer size */
	Pint	init_pos;		/* initial editing position */
	union {
		Pint	unused;
	} pet_r1;
.sp .2
} Pstring_data;
.sp .4
typedef	Pstring_data	Pstring_data3;
.fi
.IP 5.
The following functions do not have the \fIin_buf_size\fR and \fIinit_pos\fR
parameters listed in the \s-2DIS\s+2 binding.
Those fields are instead in the Pstring_data (or Pstring_data3) structure
passed to these functions:
.nf
.SM "INITIALIZE STRING"
.SM "INITIALIZE STRING 3"
.SM "INQUIRE STRING DEVICE STATE"
.SM "INQUIRE STRING DEVICE STATE 3"
.SM "INQUIRE DEFAULT STRING DEVICE STATE"
.SM "INQUIRE DEFAULT STRING DEVICE STATE 3"
.fi
.IP 6.
The Pstroke_data and Pstroke_data3 structures in \s-2PEX-SI\s+2 are different
from those specified in the \s-2DIS\s+2 binding.
Pstroke_data and Pstroke_data3 are defined as follows in \s-2PEX-SI\s+2:
.nf
.ta .5i +.5i +.5i +.5i +.5i +1i
.sp .2
typedef struct {
.sp .2
	Pint	buffer_size;	/* input buffer size */
	Pint	init_pos;		/* initial editing position */
	Pfloat	x_interval;	/* x interval */
	Pfloat	y_interval;	/* y interval */
	Pfloat	time_interval;	/* time interval */
	union {
		struct {
			Pint	unused;
		} pet_r1;
		struct {
			Pint	unused;
		} pet_r2;
		struct {
			Pmarker_attrs	marker_attrs;	/* marker attributes */
		} pet_r3;
		struct {
			Pline_attrs	line_attrs;	/* line attributes */
		} pet_r4;
	} pets;
.sp .2
} Pstroke_data;
.sp .4
/* Pstroke_data3 -- stroke data record 3 */
typedef struct {
.sp .2
	Pint	buffer_size;	/* input buffer size */
	Pint	init_pos;		/* initial editing position */
	Pfloat	x_interval;	/* x interval */
	Pfloat	y_interval;	/* y interval */
	Pfloat	z_interval;	/* z interval */
	Pfloat	time_interval;	/* time interval */
	union {
		struct {
			Pint      unused;
		} pet_r1;
		struct {
			Pint      unused;
		} pet_r2;
		struct {
			Pmarker_attrs	marker_attrs;	/* marker attributes	*/
		} pet_r3;
		struct {
			Pline_attrs	line_attrs;	/* line attributes	*/
		} pet_r4;
	} pets;
.sp .2
} Pstroke_data3;
.fi
.IP 7.
The following functions do not have the \fIin_buf_size\fR and \fIinit_pos\fR
fields listed in the \s-2DIS\s+2 binding.
Those fields are instead in the Pstroke_data or Pstroke_data3 structure passed
to these functions:
.nf
.SM "INITIALIZE STROKE"
.SM "INITIALIZE STROKE 3"
.SM "INQUIRE STROKE DEVICE STATE"
.SM "INQUIRE STROKE DEVICE STATE 3"
.SM "INQUIRE DEFAULT STROKE DEVICE STATE"
.SM "INQUIRE DEFAULT STROKE DEVICE STATE 3"
.fi
.IP 8.
The Pval_data and Pval_data3 structures in \s-2PEX-SI\s+2 are different
from those specified in the \s-2DIS\s+2 binding.
Pval_data and Pval_data3 are defined as follows in \s-2PEX-SI\s+2:
.nf
.ta .5i +.5i +.5i +.5i +.5i +.5i
.sp .2
typedef struct {
.sp .2
	Pfloat	low;	/* low range limit */
	Pfloat	high;	/* high range limit */
	union {
		struct {
			Pint	unused;
		} pet_r1;
		struct {
			Pchar	*label;
			Pchar	*format;
			Pchar	*low_label;
			Pchar	*high_label;
		} pet_u1;
	} pets;
.sp .2
} Pval_data;
.sp .4
typedef	Pval_data	Pval_data3;
.fi
.IP 9.
The following functions do not have the \fIlow_value\fR and \fIhigh_value\fR
parameters  listed in the \s-2DIS\s+2 binding.
Those fields are instead in the Pval_data (or Pval_data3) structure passed
to these functions.
.nf
.SM "INITIALIZE VALUATOR"
.SM "INITIALIZE VALUATOR 3"
.SM "INQUIRE VALUATOR DEVICE STATE"
.SM "INQUIRE VALUATOR DEVICE STATE 3"
.SM "INQUIRE DEFAULT VALUATOR DEVICE STATE"
.SM "INQUIRE DEFAULT VALUATOR DEVICE STATE 3"
.fi
.IP 10.
The \s-2PEX-SI\s+2 binding uses ``char *'' instead of ``void *''.
.IP 11.
Pedge_attrs.colr_asf is Pedge_attrs.colr_ind_asf in \s-2PEX-SI\s+2.
.IP 12.
Pline_attrs.colr_asf is Pline_attrs.colr_ind_asf in \s-2PEX-SI\s+2.
.IP 13.
Pint_attrs.colr_asf is Pint_attrs.colr_ind_asf in \s-2PEX-SI\s+2.
.IP 14.
Pmarker_attrs.colr_asf is Pmarker_attrs.colr_ind_asf in \s-2PEX-SI\s+2.
.IP 15.
In \s-2INQUIRE ANNOTATION FACILITIES\s+2 the last parameter has been replaced with two
Pfloat pointers:
.nf
.ta 1i +1.75i
.sp .2
\fBpinq_anno_facs ( type, length, start, error_ind, styles, total_length, num_anno_char_hts,
          min_char_ht, max_char_ht )
Pwstype	type;	\fIworkstation type \fP
Pint	length;		\fIlength of application list \fP
Pint	start;	\fIstarting position \fP
Pint	*error_ind;	\fIOUT error indicator \fP
Pint_list	*styles;	\fIOUT list annotation styles \fP
Pint	*total_length;	\fIOUT length of list in PHIGS \fP
Pint	*num_anno_char_hts;	\fIOUT number of character heights \fP
Pfloat	*min_char_ht;	\fIOUT minimum character height\fP
Pfloat	*max_char_ht;	\fIOUT maximum character height\fR
.fi
.IP 16.
The second parameter to the function pset_pat_ref_point_vec is
"Pvec3  pat_ref_vec[2]", not "Pvec3  *pat_ref_vec[2]".
.IP 17. 
The connection identifier argument to the function pinq_ws_conn_type is
"Pconnid  *conn_id".
.IP 18.
The function identification numbers in the file \fIphigscfunc.h\fR do not all
agree with the numbers specified in the \s-2DIS C\s+2 binding.
the transformation utilities (numbers 90 through 109 in the \s-2DIS\s+2 binding)
do not have identification numbers in \s-2PEX-SI\s+2 because those functions
never invoke error handling.
See \fIphigscfun.h\fR for the function numbers that \s-2PEX-SI\s+2 assigns.
.IP
The macro names used in \fIphigscfunc.h\fR do correspond to those in the \s-2DIS\s+2
binding, but the numbers associated with each macro may be different.
If your application uses the defined macros, the differences in the
identification numbers should not cause any problems.
.LP
A definition of the binding is in the file
\fC\s-1Xsrc/extensions/lib/\s-1PEX\s+1/c_binding/phigs.c_bind\fR\s+1.  This file contains stubs 
for all of the binding functions and is used to build the lint library.
The data structures are defined in the file 
\fC\s-1Xsrc/extensions/lib/\s-1PEX\s+1/include/phigs.h\fR\s+1.
.SS Structure Storage
.IX "Structure Storage" description "" "" "" ""
The \s-2API\s+2 supports client side and server side \s-2CSS\s+2.
Client side \s-2CSS\s+2 is used if the connecting server does not support
structure storage.
.SS \s-2PHIGS\s+2 Monitor (\s-2PM\s+2)
.IX "PHIGS Monitor (\s-2PM\s+2)" description "" "" "" ""
To meet many of the goals and constraints of \s-2PHIGS\s+2, \s-2PHIGS PLUS\s+2, \s-2X\s+2,
and \s-2PEX\s+2, the \s-2PEX-SI\s+2 graphics library is implemented as two
processes. One process resides in the client's process and one resides in a separate
process called the \s-2PHIGS\s+2 Monitor (\s-2PM\s+2). The \s-2PM\s+2 processes window 
system and input device events associated with a client's \s-2PHIGS\s+2 workstations, 
implements the window system event queue, and services event requests and inquiries from 
the client-side \s-2API\s+2 code. The \s-2PM\s+2 also contains the \s-2CSS\s+2 for 
\s-2PHIGS\s+2 workstations that exist on the client side.
.LP
There is one \s-2PHIGS\s+2 monitor per \s-2PHIGS\s+2 client, and it
monitors all \s-2PHIGS\s+2 workstations opened by that client regardless
of what server each workstation is on. 
The \s-2PM\s+2 process always runs on the same machine as the client.
.SH SEE ALSO
.nf
.IP
.ta 0.5i
.SM "COLOUR(7)"
.SM "PHIGS DESCRIPTION TABLE(7)"
.SM "PHIGS TRAVERSAL STATE LIST(7)"
.SM "PHIGS WORKSTATION DESCRIPTION TABLE(7)"
.fi