.\"##
.\" $Xorg: api.irm,v 1.3 2000/08/17 19:42:14 cpqbld Exp $
.\"##
.\"## 
.\"## 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.
.\"##
.\"## Copyright (c) 1990, 1991 X Consortium
.\"##
.\"## Permission is hereby granted, free of charge, to any person obtaining
.\"## a copy of this software and associated documentation files (the
.\"## "Software"), to deal in the Software without restriction, including
.\"## without limitation the rights to use, copy, modify, merge, publish,
.\"## distribute, sublicense, and/or sell copies of the Software, and to
.\"## permit persons to whom the Software is furnished to do so, subject to
.\"## the following conditions:
.\"##
.\"## The above copyright notice and this permission notice shall be
.\"## included in all copies or substantial portions of the Software.
.\"##
.\"## THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
.\"## EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
.\"## MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
.\"## IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
.\"## OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
.\"## ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
.\"## OTHER DEALINGS IN THE SOFTWARE.
.\"##
.\"## Except as contained in this notice, the name of the X Consortium shall
.\"## not be used in advertising or otherwise to promote the sale, use or
.\"## other dealings in this Software without prior written authorization
.\"## from the X Consortium.
.\"##
.H C "The PEX-SI Client Side"
.IX "Application Programmer's Interface, API" "" "" "" PAGE START
.H 2 "Client Side Overview"
.LP
The \s-1PEX-SI\s+1 client side is made up primarily\** of the 
Application Program Interface (\s-1API\s+1) and the \s-1PHIGS\s+1 Monitor
(\s-1PM\s+1).
The goals and constraints that led to this design, and the resultant architecture,
are described in this chapter.
.FS
\s-1PEX-SI\s+1 also provides a number of clients that use the
\s-1PEX-SI API\s+1 to demonstrate
its effectiveness in the sample implementation.
The \s-1PEX-SI\s+1 clients are not described in this document.
Descriptions of the \s-1PEX-SI\s+1 clients can be found in 
the \fI\s-1PEX-SI\s+1 User Guide\fR.
.FE
.IX "PHIGS" 
.IX "PHIGS PLUS" 
.IX "C binding"
.LP
The Application Program Interface to \s-1PEX\s+1 is provided by the \s-1PHIGS\s+1 
and \s-1PHIGS PLUS\s+1 C bindings.  
The \s-1API\s+1 is based on the \s-1IS\s0 version of the binding.
The \s-1PHIGS PLUS\s+1 C binding effort has just begun in \s-1ISO\s+1, so there
is no working draft.  The \s-1API\s+1 has developed an interim version to use until a
working draft (or better) is available.  This version follows the same 
conventions used by the \s-1DIS PHIGS\s+1 binding.
.LP
All instances of ``\s-1PHIGS\s+1'' in this document refer to both \s-1PHIGS\s+1
and \s-1PHIGS PLUS\s+1 unless otherwise specified.
.H 3 "Goals"
.LP
The primary goal of the \s-1API\s+1 is to provide a programmatic 
interface to \s-1PEX\s+1.  A number of other goals 
drive the design, however:
.BP
The implementation of a conforming and efficient \s-1PHIGS\s+1 using \s-1X\s+1
and \s-1PEX\s+1.
.BP
To the extent possible, the smooth running of the \s-1PHIGS\s+1 application
in the window system, with no restriction on the window system operations the
operator can perform on the \s-1PHIGS\s+1 workstation windows.
.BP
The support of multiple simultaneous workstations.
These workstations can exist on any combination of servers with which the
client can connect.
.BP
.IX "tool kit support"
The targeting of two broad types of \s-1PHIGS\s+1 applications:\ \ those that
do not have or want any window system knowledge and those that do.
The former is a \fIvanilla\fP \s-1PHIGS\s+1 application that does not know
it is running in a window system.  The latter is a window-system-literate
(or toolkit-literate) application that wants to use \s-1PHIGS\s+1
in conjunction with its own use of the window system.
.BP
The provision of \s-1PHIGS\s+1 output and input to both application types.
The incorporation of optimizations for those applications that only require
output.
.BP
The shielding of the vanilla \s-1PHIGS\s+1 application 
from the window system, but still using the window system to its advantage.
.BP
Allowing window-system-literate applications to use the window system 
in conjunction with \s-1PHIGS\s+1, without losing any \s-1PHIGS\s+1
functionality or conformance.
.BP
.IX "redraw events"
.IX "resize events"
Providing default redraw and resize event responses that are transparent to
the application, but allowing the disabling of this automatic response if the
\s-1PHIGS\s+1 client so chooses.
.BP
Implementing \s-1PHIGS\s+1 policies within the ``policy-free'' environment of \s-1X\s+1.
.BP
Providing some limited support for synchronizing \s-1PHIGS API\s+1
output with \s-1X\s+1 events delivered by the \s-1X\s+1 server to the application.
.H 3 "Constraints"
.LP
The \s-1PEX-SI API\s+1 was designed under the following constraints:
.BP
To enhance portability, features not widely available should not be used.
.BP
.IX "PHIGS" "event queue"
The \s-1API\s+1 should not compete with the application for resources, 
services, or process control.  The \s-1API\s+1 assumes that a 
window-system-literate \s-1PHIGS\s+1 application will be monitoring
\s-1X\s+1 events, either directly or through a tool kit.
In order to avoid competition for events, the \s-1API\s+1 cannot monitor
events on the same stream (server connection) as the application.
The \s-1API\s+1 should not preempt use of any operating system or toolkit
functionality.
.BP
.IX "data flow" "flow of control, client side"
.IX "flow of control, client side"
The \s-1API\s+1 only has the flow of control infrequently (when the
application calls a \s-1PHIGS\s+1 function).  The \s-1API\s+1 cannot
count on regaining the flow of control from the application at any 
particular point in time.
.BP
Both the \s-1API\s+1 and the \s-1PHIGS\s+1 input devices need access to the
\s-1PHIGS\s+1 event queue.
The \s-1API\s+1 needs this access to inquire about the queue's state and to retrieve events.
The input devices need access to place events in the queue
and to determine if the queue has overflowed.
(The input devices must indicate to the operator whether or not events
from the devices are successfully placed in the queue.)
.BP
.IX "PHIGS" "input devices"
\s-1PHIGS\s+1 locator, stroke, and pick input device events need to be resolved
immediately so that the \s-1PHIGS\s+1 event corresponds to the state of the
workstation and Central Structure Store when the event occurred.
These events cannot be resolved when they are removed from the queue by the
\s-1API\s+1 or the application \(em by then it will be too late to resolve them correctly.
.H 2 "General Architecture"
.LP
To meet many of the above goals and constraints, it is necessary to have
two separate threads of control:\ \ one for the application and one for the
\s-1API\s+1.  The \s-1API\s+1 thread of control allows the \s-1API\s+1
to manage input device events, the \s-1PHIGS\s+1 input queue, and window events 
independent of the application.
.IX "PHIGS Monitor, PM"
To achieve separate threads of control, the \s-1PEX-SI API\s+1
is implemented in two logical parts \(em one residing in the client's 
process and one residing in a separate process.  This separate process contains
the \s-1PHIGS\s+1 Monitor (\s-1PM\s+1).\**
.FS
Another means of realizing two separate threads of control is through the
\s-1UNIX\s+1 signal handling mechanism.  The second of the two threads is 
invoked upon the receipt of a signal (usually \s-1SIGIO\s+1)
generated by some input device or pending input on the \s-1X\s+1
event stream.  While this method may work, it has a number of problems
associated with it that can be avoided with the two-process scheme.
Among these problems are the non-portability of
performing memory allocation during signal handling, the additional
logic required to detect when interrupts have occurred in normal
processing and respond accordingly, the preemption of a portion
of the signal handling mechanism (the \s-1API\s+1
takes away the ability of the application to trap
certain signals, most likely \s-1SIGIO\s+1), and the potential
conflict of both the application and the \s-1API\s+1 reading
\s-1X\s+1 events from the same event stream.
.PP
\s-1PEX-SI\s+1 has weighed the advantages and disadvantages of
both methods and has chosen the two-process method.  Its advantages are 
that it avoids the above problems, does not preempt any use of operating 
system, window system, or toolkit functionality, can take advantage of 
parallelism on multi-processor machines, allows input and window events 
to be monitored and managed through conventional means,
and allows the most flexibility with regard to changing input
device realizations and window event response policy.
.FE
.LP
.IX "Application Programmer's Interface, API" "" "" "" PAGE MAJOR
The Client Side \s-1API\s+1 code consists of the binding and an interface
layer to the \s-1PM\s+1 and the \s-1X/PEX\s+1 server (\s-1PEX-ME\s+1).
The interface layer coordinates the various requests and replies to
the \s-1PM\s+1 and to \s-1PEX-ME\s+1.
It issues the \s-1PEX\s+1 protocol for most \s-1API\s+1 functions and keeps 
the \s-1PM\s+1 informed of appropriate state changes.
.KS
.LP
.IX "PHIGS Monitor, PM" "" "" "" PAGE MAJOR
The \s-1PM\s+1 performs the following:
.BP
Processes window system and input device events associated with a
client's \s-1PHIGS\s+1 workstations.
.BP
Implements the window system event response policy.
.BP
Issues the required \s-1PEX\s+1 and \s-1X\s+1 calls to enforce that policy.
.KE
.BP
Maintains the \s-1PHIGS\s+1 input event queue, and services event
requests and inquiries from the client-side \s-1API\s+1 code.
.IX "Central Structure Store, CSS"
.BP
Manages the Central Structure Store for \s-1PHIGS\s+1
workstations that exist on servers not supporting structure storage (see
Section 
.XR @NumberOf(Css)
for more information).
.LP
There is one \s-1PHIGS\s+1 Monitor for each \s-1PHIGS\s+1 client.
The \s-1PM\s+1 monitors all \s-1PHIGS\s+1 workstations opened by a particular
client regardless of what server each workstation is on (one \s-1PHIGS\s+1
client may have workstations open on more than one server).
The \s-1PM\s+1 is started (via \s-1UNIX\s+1 \fIexec(2)\fR) when
\s-1OPEN PHIGS\s+1 is called and is terminated when either
\s-1CLOSE PHIGS\s+1 is called or the application terminates.
The \s-1PM\s+1 opens server connections as workstations are opened, using a
single connection to servers containing multiple \s-1PHIGS\s+1 workstations.
The \s-1PM\s+1 process always runs on the same machine as the client runs on.
.H 3 "Applications with No PHIGS Monitor"
.LP
If it is known by the application that no \s-1PM\s+1 functionality is
required (no \s-1PHIGS\s+1 input, no client-side \s-1CSS\s+1, 
and no \s-1API\s+1 handling of window events),
the execution of the \s-1PM\s+1 can be prevented by utilizing a flag specified in 
\fIpopen_pex()\fR.
For more information,
refer to the \fI\s-1PEX-SI\s+1 Graphics Library Manual Pages\fR.
.H 3 "Communication Between API and PM"
.IX "communication" "API/PM"
.LP
All communication between the client-side \s-1API\s+1 and the
\s-1PM\s+1 is initiated by the client code; the \s-1PM\s+1
does not issue asynchronous communication to the client-side \s-1API\s+1.
Any communication from the \s-1PM\s+1 is read by the client-side \s-1API\s+1
before control is returned to the application.
.LP
The \s-1PM\s+1 maintains only the state it needs to perform its duties.
The \s-1PM\s+1 is not informed of all changes in \s-1PHIGS\s+1
state, nor is it necessary for the \s-1API\s+1 to communicate with the
\s-1PM\s+1 during every \s-1PHIGS\s+1 function call.  Except when the
\s-1PM\s+1 is maintaining the client-side structure store,
the \s-1API\s+1 communicates only changes in input device state, some changes
in workstation state, and input-related requests.  However, when the \s-1PM\s+1
is maintaining the client-side structure store, the \s-1API\s+1
communicates with the \s-1PM\s+1 during the majority of \s-1PHIGS\s+1
function calls.  In this case, the \s-1API\s+1 to \s-1PM\s+1 protocol is dense; 
usually one \s-1PHIGS\s+1 function call causes one communication 
packet to be sent to the \s-1PM\s+1.
.LP
.IX "shared memory"
Communication between the \s-1PM\s+1 and the \s-1API\s+1 is through shared 
memory and a bidirectional socket.  If shared memory is not available, 
then all communication is through the socket.  When shared memory is 
available, the socket is used only for synchronization between the client
and the \s-1PM\s+1 and to communicate blocks of data too large to fit in 
a fixed-size shared-memory buffer.
.H 3 "API/PM Communication Protocol"
.LP
The protocol used between the client-side \s-1API\s+1 and the \s-1PM\s+1
is described by the structure definitions in the files \fIphgargs.h\fR
and \fIphgretdata.h\fR in the \s-1API\s+1's private \fL\s-1include\fR\s+1 directory.
These \fIphgargs.h\fR structures consist of an opcode, a fixed-size 
portion, and a variable-size portion.  The ``args'' structures are 
written to the \s-1PM\s+1 by the client-side \s-1API\s+1 code.
If shared memory is available, the structures are written directly
to a queue in shared memory.
.IX "sockets" "communication"
If shared memory is \fInot\fR available, they are written to the socket.
The \s-1PM\s+1 reads the structure contents from either location and 
performs the indicated operation.  If a reply is required, the
\s-1PM\s+1 writes the reply to either a location in shared memory or 
to the socket.  The client-side \s-1API\s+1 reads the reply data from 
either location.  Synchronization of access to the shared memory buffer 
is via a lock field in the buffer.  Because the client-side \s-1API\s+1
and the \s-1PM\s+1 run on the same machine, there are no special data 
format considerations.  The protocol is not intended to be
used across a network, between dissimilar machines, or between
dissimilar versions of the client-side \s-1API\s+1 and \s-1PM\s+1.
.H 3 "Error Reporting"
.IX "sockets" "errors"
.IX "errors" "client side"
.LP
The client-side \s-1API\s+1 and the \s-1PM\s+1 use an additional socket 
for error reporting so that all errors can be reported by the client-side
code via the \s-1PHIGS\s+1 error-handling mechanism.  All errors detected 
by the \s-1PM\s+1 are sent to the client-side \s-1API\s+1 through this 
error socket.  The \s-1PM\s+1 does not report any errors directly.  (See
Section 
.XR @NumberOf(Sync_Not)
for a discussion of the synchronization issues associated with this.)
.H 3 "Control"
.IX "flow of control, client side"
.IX "data flow" "flow of control, client side"
.LP
The client-side \s-1API\s+1 does not rely on regaining control of the 
application, nor does it rely on the application issuing an \s-1X\s+1
request that will cause an \s-1X\s+1 connection's buffer to be flushed.
The client-side \s-1API\s+1 ensures that all \s-1X\s+1 and \s-1PEX\s+1
requests necessary to service a \s-1PHIGS\s+1 function call are sent to the
server prior to returning control to the application.
.IX "Application Programmer's Interface, API" "" "" "" PAGE END
.H 3 "Window Events"
.IX "window events"
.LP
The \s-1PM\s+1 ensures that no \s-1PHIGS\s+1 state that is visible to the 
application is changed when it initiates a redraw.  The exception is that
changes to the Central Structure Store made subsequent to the last
update of the display surface may be reflected in the redraw.
.LP
Because the \s-1API\s+1 receives responses to window system events from the \s-1PM\s+1,
the application cannot replace the window system event response functions.
The application can only prevent their execution, in which case the application 
assumes responsibility for responding to the events.  Application developers may,
however, implement and supply their own specific \s-1PM\s+1 to replace the event response
functions.
.LP
.IX "PHIGS" "escapes"
The application uses the workstation description table modification
functions (\fIphg_ws_type_set()\fR, etc.) and \s-1PHIGS\s+1
escapes to control some of the interaction with the window system.
There is an escape to disable and enable the \s-1PM\s+1's handling
of window events.  If the application does not want the \s-1PM\s+1
to respond, then it is presumably monitoring the window events itself 
and responding as it sees fit.
.\".H 2 "Window Event Processing"
.LP
The following describes \s-1PM\s+1 responses to some window system events:
.LP
.IP "\fBWindow Move\fR" 17
No response.
.IP "\fBWindow Resize\fR" 17
\s-1PHIGS\s+1 retraverses the posted structures, clipping to the new
window size.
.IP "\fBWindow Close\fR" 17
No response.
.IP "\fBWindow Exposed\fR" 17
Redraw exposed portions of window by retraversing, but clip to only
the exposed regions.  The exposed portions may be more up-to-date 
than the unexposed portions if the workstation has not been updated because 
changes were made to the \s-1CSS\s+1 or workstation state list.
.IP "\fBWindow Occluded\fR" 17
No response.
.IP "\fBWindow Destroy\fR" 17
The PM exits by calling exit(3) with a value of 3. This also causes the
client process to exit with a value of 3.
.IX "window events"
.H 3 "PHIGS Input Queue"
.IX "input"
.LP
The \s-1PHIGS\s+1 input queue is maintained in the \s-1PM\s+1.
Applications retrieve \s-1PHIGS\s+1 events from the queue by
calling \fIpawit_event()\fR.
This function retrieves the event at the head of the queue, if any, and
puts it in the current event report in the client.
The event is read from the current event report with the appropriate \s-1GET\s+1
<class> function for the event type.
If the \s-1PM\s+1 is not used, \fIpawait_event()\fR returns immediately
without waiting for the timeout period specified in the function call.
.LP
.IX "event queue"
The \s-1PHIGS\s+1 event queue in the \s-1PM\s+1 holds 500 events.
If an attempt is made by the operator to place a \s-1PHIGS\s+1 event in the queue
when the event queue is full, the \s-1PM\s+1 calls the Xlib function \fIXBell()\fR.
.H 3 "Archival Support"
.IX "archival"
.LP
The archive file format used by \s-2PEX-SI\s+2 is used for the storage and 
subsequent retrieval of \s-2PHIGS\s+2 and \s-2PHIGS PLUS\s+2 structure elements.
The file format conforms to the required archive file specification in 
\s-2PHIGS\s+2 as to form and functionality of a generic set of archive element types.
However, since the \s-2PEX\s+2 archive file format is not a registered \s-2PHIGS\s+2 
format, it is classified as a private encoding.
This encoding may be submitted for \s-2ANSI\s+2 registration at some time in the future.
.LP 
The following guidelines were used in the design of the archive storage format: 
.BP
Define structure elements using the \s-2PEX\s+2 protocol encoding.
.BP
Conform to the \s-2PHIGS\s+2 archive file specification.
.BP
Allow all \s-2PEX\s+2 binary representations to be supported (written and read).
.BP
Allow efficient support of devices that provide random access.
.LP 
The \s-2PEX\s+2 protocol already encodes \s-2PHIGS\s+2 and 
\s-2PHIGS PLUS\s+2 structure elements for use in a byte stream representation.
The \s-2PEX\s+2 archive format uses this same encoding format for all structure elements.
.LP 
The \s-2PHIGS\s+2 archive interface supports any of the binary 
representations that the \s-2PEX\s+2 protocol can support.
By reformatting the binary values, implementations can read
and write files that are not written in the host computer's native format.
However, it is not intended that archives of
different binary representations be allowed within one archive file.
.LP
The archive file format supports random access devices completely.
It also allows sequential access, if necessary.
.LP
For more information on \s-1PEX-SI\s+1 archival support, refer to
Appendix C of the \fIPEX-SI User Guide\fR.
.H 3 "No Metafile Support"
.IX "metafiles"
.LP
\s-1PEX-SI\s+1 does not support metafiles.
.H 2 "Central Structure Store" Css
.IX "Central Structure Store, CSS" "" "" "" PAGE MAJOR
.LP
There are three structure storage situations supported by the \s-1API\s+1:\**
.FS
Actually there are four \(em the fourth being the ``Mixed Traversal'' case.
This case is not directly supported by \s-1PEX-SI\s+1.
.FE
.NP
All open workstations are associated with servers supporting 
the ``\s-1PHIGS\s+1 workstation subset.''
.NP
One or more workstations are associated with a server that supports only
the \s-1PEX\s+1 ``immediate mode rendering subset.''
.NP
There are no open workstations.
.LP
In the first case, the \s-1API\s+1 broadcasts most \s-1PEX\s+1
requests to all the involved servers; for example, structure editing operations 
are sent to all the servers.  In this case, the \s-1CSS\s+1
is duplicated on all involved servers; there is no attempt to store 
only those structures posted to workstations associated with a given server.
.LP
In the second case, the \s-1PM\s+1 contains a \s-1CSS\s+1 for all the 
servers not supporting workstation resources and structure storage.
This copy of the \s-1CSS\s+1 is treated similarly to those of servers 
supporting structure storage in that it contains a complete copy of the
\s-1CSS\s+1 and is updated with each relevant \s-1PHIGS\s+1 function call.
The \s-1PM\s+1 contains the \s-1PHIGS\s+1 workstation logic and provides 
the application with the \s-1PHIGS\s+1 workstation functionality.
.LP
The third case is the situation immediately after \s-1PHIGS\s+1 is opened,
but no workstations have yet been opened.
Because \s-1PHIGS CSS\s+1 operations can be performed regardless of whether 
any workstations are open, there needs to be a \s-1CSS\s+1 independent 
of any open workstation.  This \s-1CSS\s+1 exists in the \fIdefault server\fP.
The default server is specified prior to or during the call to 
\s-1OPEN PHIGS\s+1.  If the default server does not 
support structure storage, or there is no default server, a \s-1CSS\s+1
will be created in the \s-1PM\s+1.
.LP
The default server is generally expected to be the local server.
In many cases the local server will support structure storage and 
workstation resources, and all workstations will be opened on that server.
In such a case only one \s-1CSS\s+1 will be built and maintained.
If the local server does not support structure storage or
\s-1PHIGS\s+1 workstations, there will still be only one
\s-1CSS\s+1, but it will reside in the \s-1PM\s+1.
.LP
The \s-1API\s+1 will detect which of the above cases exists at any time 
and react accordingly.  For instance, when a workstation is opened 
on a new server that supports structure storage, the \s-1API\s+1
will copy the existing \s-1CSS\s+1 to that server.
When a workstation is opened on a server that does not support
structure storage, the \s-1API\s+1 will create a copy of the
\s-1CSS\s+1 in the \s-1PM\s+1.  Whenever all workstations are closed 
on a server other than the default, the \s-1CSS\s+1 copy on that server, 
if any, will be destroyed.  If there is a default server, it will retain 
a copy of the \s-1CSS\s+1 for the duration of the \s-1PHIGS\s+1 session 
\(em in other words, until \s-1CLOSE PHIGS\s+1 is called.
.H 2 "Workstations and Workstation Types"
.IX "workstations"
.IX "tool workstations"
.IX "drawable workstations"
.LP
The \s-1API\s+1 supports two general types of workstations:  
a \fItool\fP workstation and a \fIdrawable\fP workstation.
The major difference is that a tool workstation uses an
\s-1API\s+1-created window and a drawable workstation uses 
an application-created window.
.LP
A workstation type in \s-1PHIGS\s+1 is some unique identifier.
In the \s-1API\s+1, the identifier is a pointer to a data structure.
This data structure, which is not visible to the application, contains 
the Workstation Description Table (\s-1WDT\s+1) 
and other data associated with the workstation type.
(Additional workstation information is also kept in a corresponding data
structure in the \s-1PM\s+1.)
The \s-1API\s+1 augments the \s-1WDT\s+1 to contain window-system-specific 
information in addition to the \s-1WDT\s+1 information defined by
\s-1PHIGS\s+1.  The \s-1API\s0-defined information describes additional 
characteristics of the workstation, such as window size and placement, and the
environment in which it is operating.  Most of the \s-1API\s0-defined data 
in the description table can be changed by the application.
.LP
.IX "generic workstations"
.IX "specific workstations"
\s-1PHIGS\s+1 defines two classes of workstation types:\ \ \fIgeneric\fR and \fIspecific\fR.
Generic workstation types are those that are not associated with an open workstation.
The information contained in the \s-1WDT\s+1 is a description of the 
desired characteristics and capabilities of a workstation of that type.
In most cases, the \s-1WDT\s+1 reflects the actual capabilities a workstation 
of that type would have if it were opened.
.LP
Specific workstation types are those associated with an open workstation.
When a workstation is opened, the \s-1API\s+1 makes a copy of the 
description table associated with the specified workstation type.
This copy is then modified to reflect the actual capabilities of the 
display device and the characteristics of the environment.
A new, specific workstation type is created, and the modified description 
table is associated with it.
.H 2 "Workstation Description Tables"
.IX "Workstation Description Table, WDT"
.LP
As described previously, an augmented workstation description table 
(\s-1WDT\s+1) is associated with all workstation types.  The contents 
of the \s-1WDT\s+1 are mostly dependent on the display device on which 
a workstation of that type will appear.  To emphasize this, the 
\s-1API\s+1 associates generic workstation types with a particular 
display.  The display name is stored in the augmented \s-1WDT\s+1.
When a tool workstation is opened, it is opened on the display
specified in the augmented \s-1WDT\s+1.
.LP
When the \s-1API\s+1 is initialized (i.e., when \s-1PHIGS\s+1 is opened), 
the predefined workstation types are built using the capabilities of 
the default display.
.IX "workstations"
.H 2 "Double Buffering"
.IX "double buffering"
.LP
Double buffering in the \s-1PEX-SI API\s+1 is controlled with the 
workstation type attribute \fI\s-1PHIGS_DBL_BUF_MODE\s+1\fP.  This attribute 
sets the double buffering mode of the specified workstation type to the given
value.  A value of \s-1TRUE\s+1 requests double buffering.
A value of \s-1FALSE\s+1 requests that double buffering not be performed.
The \s-1API\s+1 does not directly realize double buffering.
If a workstation resource is used to implement the \s-1PHIGS\s+1
workstation, the \s-1API\s+1 just sets the double buffering mode of 
the workstation resource to the appropriate value.  If a workstation 
resource is not used \(em for example, when client-side structure storage 
is being used \(em the \s-1API\s+1 does nothing to realize double buffering.
The onus is on the client application to control buffering via some
exposed, compatible mechanism such as the proposed \s-1X\s+1 Consortium multi-buffering
extension.
.\".LP
.\"The \s-1PEX-SI\s+1 server does \fInot\fR implement double buffering, 
.\"although the buffer mode attribute for a \s-1PHIGS\s+1 workstation is supported.
.\"This attribute, when set, will be ignored by the \s-1PEX-SI\s+1 server.
.\"Refer to --Server Chapter-- for more details.
.H 2 "Error Reporting"
.IX "errors" "client side"
.LP
There are two classes of errors generated by the \s-1API\s+1:\ \ 
\s-1PHIGS\s+1 errors and \s-1X/PEX\s+1 errors.  All \s-1PHIGS\s+1 
errors are reported using the standard \s-1PHIGS\s+1 error 
reporting mechanism \(em a call to the function \fIperrorhand()\fR.
The \s-1API\s+1 attempts to trap some \s-1X\s+1 and \s-1PEX\s+1 errors 
generated by its use of \s-1X\s+1 and \s-1PEX\s+1 and report them via the 
\s-1PHIGS\s+1 error-handling mechanism.  Implementation-dependent 
\s-1PHIGS\s+1 errors are defined for the \s-1X\s+1 and \s-1PEX\s+1 errors 
that the \s-1API\s+1 could generate.  When it is not possible for the 
\s-1API\s+1 to trap X and \s-1PEX\s+1 errors, they are reported via 
the \s-1X\s+1 error-reporting mechanism \(em a call to the \s-1X\s+1 error handler.
The \s-1API\s+1 does not register its own \s-1X\s+1 error handler via 
\fIXSetErrorHandler()\fR.
.H 3 "Asynchronous Notification"
.LP
It is not practical to keep all \s-1PHIGS\s+1 state information in 
the portion of the \s-1API\s+1 that lies in the application's process; 
therefore, some errors are detected in the remote portion of the 
implementation.  Because performance is enhanced by buffering the 
processing of commands, and some errors are not detected until a 
command is processed, better performance can be achieved if 
notification of errors occurs asynchronously, such as during a function 
call made subsequent to the function that detected the error.
.LP 
This asynchronous notification is the default behavior.  Errors may 
not be reported before the detecting function returns.  They will be 
reported during a subsequent function call, and the report will contain 
the correct function identifier \(em the identifier of the function 
detecting the error, not the one during which the notification occurs.
.H 3 "Synchronous Notification" Sync_Not
.LP 
.IX "PHIGS" "escapes"
A dynamically settable escape function is provided for the application to
indicate that it requires synchronous error notification, so that
notification of errors is performed before the detecting function returns.
Because synchronous notification reduces \s-1API\s+1 performance, it should 
be used only when the application requires it.
.LP
Any pending errors are delivered when the escape is set.