.\"##
.\" $Xorg: intro.irm,v 1.3 2000/08/17 19:42:15 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.
.\"##
.DN "PEX-SI Architecture Specification" 
.EF ''X11R5''
.OF ''X11R5''
.PL FULL
.\"
.H C "Introduction"
.LP 
This document describes the architecture of the \s-1PEX\s+1 Sample Implementation 
(\s-1PEX-SI\s+1).  \s-1PEX-SI\s+1 has been developed 
by a team of software engineers at Sun Microsystems in Mountain View, California.
This document describes the components of the sample implementation's
design, its architecture and features, and some functional details of the 
inner workings of its modules.  Finally, it gives pointers to other related 
references.
.LP
This document is not intended to serve as an aid to understanding 
\s-1PEX\s+1 protocol and encoding, the \s-1PHIGS\s+1 and \s-1PHIGS PLUS\s+1 
standards, or the \s-1X\s+1 Window System.
It is assumed that the reader has a fair knowledge of the terms
and the underlying technology of all three.
.\"
.H 2 "Audience"
.LP
The intended audience for this document consists of \s-1PEX\s+1 application 
developers and \s-1X\s+1 Window System programmers interested in achieving 
3D graphics within an \s-1X\s+1 environment.
Programmers who might be porting \s-1PEX-SI\s+1 to a specific environment
should also refer to the \fI\s-1PEX-SI\s+1 Porting Guide\fR.
.\"
.H 2 "Scope"
.LP
This document describes the following aspects of \s-1PEX-SI\s+1:\ \ 
.BP
Client Side Overview and Architecture
.RS
.BP
Application Programmer's Interface (\s-1API\s+1)
.BP
\s-1PHIGS\s+1 Monitor (\s-1PM\s+1)
.BP
\s-1PHIGS\s+1 Central Structure Store (\s-1CSS\s+1)
.BP
Workstations and Workstation Types
.BP
Window Event Processing
.BP
\s-1PHIGS\s+1 Input Queue Handling
.BP
Archival Support
.BP
Double Buffering
.BP
Error Reporting
.RE
.BP
Server Side Model Extension (\s-1ME\s+1) Overview and Architecture
.RS
.BP
di\s-1PEX\s+1 Implementation
.BP
dd\s-1PEX\s+1 Interface and Implementation
.BP
Resource Management and Dependencies
.BP
PHIGS Workstation Module
.BP
Shared Resources Module
.BP
Rendering Control Module
.BP
Transformation Module
.BP
3D Rendering Module
.RE
.\"
.H 2 "Overview of PEX-SI"
.LP
.IX "PHIGS"
.IX "PHIGS PLUS"
\s-1PEX-SI\s+1 is a sample implementation of support for the complete \s-1PEX\s+1
protocol as defined in the \fI\s-1PEX\s+1 Protocol Specification ver. 5.0P\fR 
and the \fI\s-1PEX\s+1 Protocol Encoding Document ver. 5.0P\fR.
The primary goal of \s-1PEX\s+1 is to provide 3D graphics capabilities based on 
\s-1PHIGS\s+1 and \s-1PHIGS PLUS\s+1 policies, within the policy-free 
\s-1X\s+1 Window System model.
To achieve these goals, \s-1PEX-SI\s+1 provides the following:\ \ 
.BP
A \s-1PHIGS/PHIGS PLUS\s+1 Application Programmer's Interface (\s-1API\s+1) 
for clients that support \s-1PHIGS/PHIGS PLUS\s+1 policies through the mechanisms 
defined by the \s-1PEX\s+1 protocol
.BP
.IX "server extension"
.IX "Model Extension"
.IX "PEX-ME" 
A Model Extension (\s-1PEX-ME\s+1) to the \s-1X\s+1 sample server that processes 
\s-1PEX\s+1 protocol requests
.LP
\s-1PEX-SI\s+1 has three major goals:\ \ 
.BP
Quick and easy handling of \s-1PEX\s+1 requests
.BP
.IX "porting"
Quick and easy integration into existing \s-1X\s+1 servers
.BP
Easy adaptation to a wide range of client and server platforms
.IX "data flow" "PEX-SI" "" "" PAGE START
.LP
.IX "PHIGS Monitor, PM"
.IX "Application Programmer's Interface, API"
Client-side support in \s-1PEX-SI\s+1 consists of the \s-1API\s+1 and an optional 
\s-1PHIGS\s+1 Monitor (\s-1PM\s+1).
The API supports a \s-1PHIGS/PHIGS PLUS\s+1 C language binding.
.IX "C binding"
The \s-1PM\s+1 is a separate process that is started by the \s-1API\s+1.
The \s-1PM\s+1 manages \s-1PHIGS\s+1 input, client-side structure storage, 
and \s-1X\s+1 window events.
The \s-1API\s+1 and the \s-1PM\s+1 generate the \s-1X\s+1 and \s-1PEX\s+1 requests 
required to support \s-1PHIGS\s+1 and \s-1PHIGS PLUS\s+1 within the \s-1X\s+1 environment.
.LP
.IX "PEX-ME"
.IX "X11R4"
Server-side support in \s-1PEX-SI\s+1 consists of a Model Extension (PEX-ME)
to the sample \s-1X11R4\s+1 server.
It follows the guidelines for implementing an extension to \s-1X\s+1 described in the 
\fIDefinition of the Porting Layer for the X v11 Sample Server\fR.
The sample \s-1X\s+1 server architecture has three functional areas:\ \ the
operating system-dependent code (os),
the device-independent code (dix), and the device-dependent code (ddx).
.IX "os"
.IX "dix"
.IX "ddx"
Similarly, \s-1PEX-ME\s+1 consists of 
operating system-dependent code (os\s-1PEX\s+1),
device-independent code (di\s-1PEX\s+1), and device-dependent code (dd\s-1PEX\s+1).
.IX "diPEX"
.IX "ddPEX"
.IX "osPEX"
.IX "simple frame buffer"
To ease porting, the dd\s-1PEX\s+1 code is further modularized, as described later in
this document.
The complete \s-1PEX-ME\s+1 generates output to simple frame buffer
hardware via the capabilities of \s-1X11R4\s+1's ddx.
.LP
Each of the main sections of the \s-1PEX-SI\s+1 code 
(\s-1API\s+1, \s-1PM\s+1, di\s-1PEX\s+1, dd\s-1PEX\s+1, os\s-1PEX\s+1)
is designed to be as independent as possible, with a clear, understandable,
and well-defined exchange of data between the sections.
This facilitates porting and tailoring of the code for a wide variety of 
\s-1PEX\s+1 implementations and graphics devices.
.LP 
.IX "Central Structure Store, CSS"
.IX "client-side CSS"
.IX "server-side CSS"
.IX "client-side traversal"
.IX "server-side traversal"
.IX "mixed traversal"
Because \s-1PEX\s+1 is a two-process model, and because \s-1PHIGS\s+1 has the concept 
of a Central Structure Store (\s-1CSS\s+1), \s-1PEX-SI\s+1 has to deal with
the issue of ``where'' to implement the \s-1CSS\s+1.\**
The \s-1PEX\s+1 protocol allows the \s-1CSS\s+1 to be implemented in either the client
side (client-side \s-1CSS\s+1), or the server side (server-side \s-1CSS\s+1).
The \s-1PEX\s+1 protocol also defines client-side traversal, server-side traversal, 
and mixed traversal.
Client-side traversal occurs on the client side and sends output commands to the server.
Server-side traversal occurs in the server.  Mixed traversal allows one client
to use both client-side and server-side traversal methods.
.FS
See the \fIPEX Introduction and Overview\fR for a complete description
of structure storage models.
.FE
.LP
\s-1PEX-SI\s+1 implements both \s-1CSS\s+1 models, and both client and 
server-side traversal.  \s-1PEX-SI\s+1 does not support mixed traversal.
.LP
Figure 
.XR @NumberOf(high_level)
presents a high level view of the processes comprising
a simple \s-1PEX-SI\s+1 user environment.
The data exchanged between the client and server is transmitted and received 
via \s-1X\s+1 and \s-1PEX\s+1 protocol packets.
.IX "PEX packets"
.IX "X packets"
This diagram shows the general data flow between the client and server.
Communication between the client and server involves much more than
generating the simplified data shown in this figure.
The rest of this document and the \fI\s-1PEX-SI\s+1 Porting Guide\fR describe 
the client and server code design and structure in more detail.
.sp .2
.KS
.FN "High-Level Diagram" high_level
.sp 
.PS
arrowwid = .06i
arrowht = .06i
#
#----------------High-Level Diagram------------------#
#
# PEX-SI API BOX
#
API_outer_box:
	box ht 1.5 wid 2i 
	"\s-1\fBPEX-SI API\fR\s+1" at API_outer_box.n above

ISO:
	box invis ht .75i wid 1.25i \
	with .nw at API_outer_box.nw \
	"\s-1PHIGS ISO\s+1" "(Draft)" "C Binding"
PM:
	box invis same with .sw at API_outer_box.sw \
	"PM" "Interface"
Server_IF:
	box invis ht 1.25i wid 0.75i \
	with .se at API_outer_box.se \
	"Server" "Interface"
line from ISO.se to ISO.sw
line from Server_IF.sw to Server_IF.nw to Server_IF.ne
#
API_Server_arrow:
	Left:	box invis ht 0.125i wid 0.8i with .sw at API_outer_box.e
	Right:	box invis same with .sw at Left.n
	arrow <-> from Left.w to Left.e to Right.w to Right.e
	L_text:	box invis ht 0.25i wid 0.7i with .n at Left.s 
#		"\s-1X/PEX\s+1" "\s-1Reply\s+1" 
	R_text:	box invis same with .s at Right.n 
#		"\s-1X/PEX\s+1" "\s-1Request\s+1  " 
#
# PEX-SI SERVER BOX
#
Arrow_Text:
	box invis ht .5i wid 1.2i with .nw at API_Server_arrow.sw
	"X/PEX" at Arrow_Text.n below
	"Packets" at Arrow_Text.c
	
Position:
	box invis wid 1.2i with .nw at API_outer_box.ne 
Server_outer_box:
	box ht 2i wid 2i with .nw at Position.ne
	"\s-1X11/PEX-SI\s+1 Server" at Server_outer_box.n above
Dix:
	box invis ht 1i wid .75i with .nw at Server_outer_box.nw "dix"
Dipex:
	box invis ht 1i wid 1.25i with .ne at Server_outer_box.ne "\fBdi\s-1PEX\s+1\fR"
Ddx:
	box invis ht 1i wid .75i with .sw at Server_outer_box.sw "ddx"
Ddpex:
	box invis ht 1i wid 1.25i with .se at Server_outer_box.se "\fBdd\s-1PEX\fR\s+1"
line from Dix.ne to Ddx.se
line from Dix.sw to Dipex.se 
#
#
# PHIGS Monitor
#
move down 1i
move left 4i 
Shared_mem:
	box invis ht 0.5i wid 1.375i \
	"\s-1UNIX SOCKETS\s+1 and/or" "\s-1SHARED MEMORY\s+1"
	line dashed from Shared_mem.nw to Shared_mem.ne
	line dashed from Shared_mem.sw to Shared_mem.se
move left .25i down .4i
Pexsi_pm:
	box ht 1i wid 1i "\s-1\fBPEX-SI\fR\s+1" "\s-1\fBPM\fR\s+1"
arrow <-> from Pexsi_pm.n to Shared_mem.s 
arrow <-> from Shared_mem.n to PM.s
arrow <-> from Pexsi_pm.ne up 1.2i right 1.2i then \
	down .1i left .25i then \
	up .7i right .8i 
Position_text:
	box invis ht .5i wid 1.3i with .ne at Ddx.nw 
PM_Server_text:
	box invis ht .7i wid 1.3i with .n at Position_text.s
#	"\s-1X/PEX\s+1" "\s-1Request\s+1" at PM_Server_text.n 
#	"\s-1X/PEX\s+1" "\s-1Reply\s+1" at PM_Server_text.s 
#
# Client/Server Side Boxes
#
Position_2:
	box invis ht 1i wid .9i with .s at Position.n 
Client:
	box dashed ht 5i wid 2.5i with .ne at Position_2.nw
	"\fBClient Side\fR" at Client.n above
Server:
	box dashed ht 3.65i wid 2.5i with .nw at Position_2.ne
	"\fBServer Side\fR" at Server.n above
Position_3:
	box invis ht .25 wid 2i with .n at Client.n
Application:
	box ht .375i wid 2i with .n at Position_3.s \
	"Client Application"
Position_4:
	box invis ht .375 wid .375i with .sw at Application.sw
arrow <-> from Position_4.se to ISO.n
#
# Operating System functions
#
Osx:
	box ht .325i wid .375i with .ne at Ddpex.nw "osx"
Ospex:
	box ht .325i wid .5i with .nw at Osx.ne "\fBos\s-1PEX\s+1\fR"
.PE
.KE
.LP
.IX "Xlib"
.IX "Athena widgets"
The client application communicates with the \s-1PEX-SI\s+1 library through the 
\s-1PHIGS/PHIGS PLUS\s+1 C binding in the \s-1API\s+1.
The \s-1API\s+1 maps \s-1PHIGS\s+1 library function calls to the appropriate
\s-1X\s+1, \s-1PEX\s+1, or \s-1PM\s+1 requests, and transmits the requests to
the \s-1PM\s+1 and the server.
The \s-1API\s+1 and the \s-1PM\s+1 use Xlib to generate \s-1X\s+1 requests when necessary.
.IX "PHIGS Monitor, PM"
.IX "Application Programmer's Interface, API"
The \s-1PM\s+1 uses Athena widgets to realize some input devices.
\s-1API\s+1 calls to the \s-1PM\s+1 are similarly mapped to \s-1X\s+1 or
\s-1PEX\s+1 requests by the \s-1PM\s+1.
The \s-1PM\s+1 also intercepts \s-1X\s+1 events;
it generates \s-1X\s+1 and \s-1PEX\s+1 requests to respond to the
events and relays information back to the \s-1API\s+1 when and as needed.
.LP
.IX "dix"
.IX "ddx"
.IX "server extension"
All requests coming to the server are received by dix, which determines if
the request is an \s-1X\s+1 or \s-1PEX\s+1 request.
\s-1X\s+1 requests are handled by dix and ddx in the usual manner.
\s-1PEX\s+1 requests are passed to di\s-1PEX\s+1.
di\s-1PEX\s+1 converts the requests to the correct (server native)
byte-ordered form and floating point format, and calls into dd\s-1PEX\s+1,
which then processes the request.  For requests that cause graphics
to be rendered, \s-1ddPEX\s+1 eventually passes the primitives (in device coordinates)
to ddx to be displayed.
.IX "diPEX"
.IX "ddPEX"
.LP
The data exchange between di\s-1PEX\s+1 and dd\s-1PEX\s+1 is described
in greater detail in Chapter 3, The \s-1PEX-SI\s+1 Server Side.
.IX "data flow" "PEX-SI" "" "" PAGE END
.H 2 "Porting PEX-SI"
.LP
.IX "porting" "" "" "" PAGE MAJOR
\s-1PEX-SI\s+1 is designed to be portable to a wide variety of software
and hardware environments.  \s-1PEX-SI\s+1 defines portability as a balance
of flexibility and adaptability.  \fIFlexibility\fR is achieved when the code
at every level is either documented well enough or is obvious enough in its
execution that it can be worked with easily.  \fIAdaptability\fR is achieved
when the code can also be optimized to perform well in a wide variety of 
environments.
.LP
.IX "X11R4"
Although it uses the fundamentals of the \s-1X11\s+1 architecture as a model,
\s-1PEX-SI\s+1 expands upon that model in its approach to portability.
The \s-1X11\s+1 architecture addresses an audience of users interested in creating 
original applications for the \s-1X\s+1 protocol, and hence it concentrates on making 
the client interface as portable as possible.  In addition, \s-1PEX-SI\s+1 
addresses an audience that is interested in adapting existing \s-1PHIGS\s+1 
applications to work as clients via the \s-1PEX\s+1 protocol over a network.  Where 
\s-1X11\s+1 only provides for server porting at either the highest (ddx) or lowest
(pixel read/write) levels, the \s-1PEX-ME\s+1 has been designed to allow
ease of porting to a greater range of devices with a diverse range of capabilities.
Thus, while \s-1X11R4\s+1 achieved its greatest level of portability in the client-side
code, \s-1PEX-SI\s+1 has also achieved a high level of portability in its server
implementation.
.LP
To accomplish this level of portability
\s-1PEX-SI\s+1 provides code that both runs efficiently in a specific 
implementation in a simple frame buffer environment, and 
lends itself well to performance improvements achieved by modifying 
or replacing the internal layers, or portions thereof, of the \s-1PEX-SI\s+1 code.
The \s-1PEX-SI\s+1 client-side and server-side code is divided into distinct layers
explicitly designed to ease porting.
.LP
The client side code is organized in such a way that the toolkit, operating system, 
and \s-1PEX\s+1 protocol-dependent portions are separated and isolated
into distinct modules and directories.
\s-1PEX-SI\s+1 presents the user with two workstation models
that allow applications to be independent of the toolkit used, or, alternatively,
to be closely tied to a particular toolkit thereby enhancing performance.
The creation of the \s-1PHIGS\s+1 Monitor (\s-1PM\s+1) provides 
applications the ability to fully handle asynchronous communication with the server.
The \s-1PM\s+1 is optional, however, suiting the requirements of synchronous
operating systems.
In addition, the \s-1API\s+1 is designed to utilize shared memory
and/or \s-1UNIX\s+1 sockets to accomodate both System V and \s-1BSD UNIX\s+1, and
non-\s-1UNIX\s+1 systems.  Finally, the \s-1API\s+1 code that uses the \s-1PEX\s+1
protocol is isolated in a single directory.
The majority of the \s-1API\s+1 code is \s-1PEX\s+1 independent.
.IX "device dependence"
.IX "operating system dependence"
.LP
\s-1PEX-SI\s+1 also provides several distinct porting layers in the server,
allowing for a wide range of possible performance improving ``short cuts''.
The portions of code most likely to be
changed to improve \s-1PEX-SI\s+1 performance in a particular environment (i.e.,
operating system or device-dependent structures) have been isolated into
separate directories and files.  In addition, the device-dependent code has been
further layered so that individual pieces can be independently
modified or replaced with implementation-specific software or hardware
interfacing components.
.LP
.IX "simple frame buffer"
\s-1PEX-SI\s+1 is designed to run on a platform judged to be the least common
denominator of all \s-1PEX\s+1 Consortium sponsors:\ \ the simple frame buffer.  Thus, 
\s-1PEX-SI\s+1 can be used as soon as it is installed; there is no requirement for any
initial porting, however, most users will want to customize and optimize the existing code.
In some cases this will mean adjusting compilation variables; in other cases, it
will mean complete replacement of certain modules of code.  To this end, the 
\fI\s-1PEX-SI\s+1 Porting Guide\fR provides the specific information required 
to customize and optimize \s-1PEX-SI\s+1 for a specific environment.
Refer to that document for specific implementation details.
The remainder of this document discusses the architecture of \s-1PEX-SI\s+1 
at a higher level.
.H 2 "Related References" 
.LP
\fI\s-1PEX\s+1 Introduction and Overview\fP (v 3.2; 10 October 1988):\ \   
an introduction to the goals and structure 
of the \s-1PEX\s+1 project, with a glossary of \s-1PEX\s+1 terms.
\fIIt is widely recognized that this document is out of date.\fR
.LP
\fI\s-1PEX\s+1 Protocol Specification\fP (v 5.0P; 14 September 1990):\ \ 
a description of the protocol extensions to the 
\s-1X\s+1 Window System that comprise \s-1PEX\s+1.
.LP
\fI\s-1PEX\s+1 Protocol Encoding Document\fP (v 5.0P; 14 September 1990):\ \ 
the bit bindings of the \s-1PEX\s+1 protocol.
.LP
\fIX11 Server Extensions\fP (28 August 1987):\ \   
a description of the interface between the MIT X11 
Sample Server and portable extensions in general.
.LP
.br
\fIDefinition of the Porting Layer for the \s-1X\s+1 v11 Sample Server\fP (1 March 1988) 
.LP
.br
\fIXlib \(em C Language \s-1X\s+1 Interface\fP (X v11 R4) 
.LP
.br
\fI\s-1X\s+1 Toolkit Intrinsics \(em C Language Interface\fP (X v11 R4, March 1988)
.LP
\fIISO/IEC 9592-1:1989(E), Information Processing Systems \(em Computer Graphics
\(em Programmer's Hierarchical Interactive Graphics System (\s-1PHIGS\s+1),
Part 1:\ \   Functional Description\fP
.LP
\fIDraft proposed PHIGS PLUS, ISO/IEC JTC1 SC24-N454\fP (20 March 1990)
.LP
\fIPEX-SI User Guide\fP (29 February 1991):\ \    
introductory information about the \s-1PEX-SI\s+1 clients, the \s-1API\s+1, 
and \s-1PEX-ME\s+1; instructions about installation and using the clients.
.LP
\fIPEX-SI Graphics Library Manual Pages\fP (29 February 1991):\ \    
reference manual for the API.
.LP
\fI\s-1PEX-SI\s+1 Porting Guide\fP (29 February 1991):\ \ 
detailed description of \s-1PEX-SI\s+1 with an emphasis on 
porting portions of \s-1PEX-SI\s+1 to various environments.