.\"##
.\" $XConsortium: server.irm,v 5.2 94/04/17 20:05:44 rws Exp $
.\"##
.\"## 
$XMCOPY
.\"## Copyright (c) 1990, 1991 by Sun Microsystems, Inc. 
.\"## 
.\"##                         All Rights Reserved
.\"## 
.\"## Permission to use, copy, modify, and distribute this software and its 
.\"## documentation for any purpose and without fee is hereby granted, 
.\"## provided that the above copyright notice appear in all copies and that
.\"## both that copyright notice and this permission notice appear in 
.\"## supporting documentation, and that the name of Sun Microsystems,
.\"## not be used in advertising or publicity 
.\"## pertaining to distribution of the software without specific, written 
.\"## prior permission.  
.\"## 
.\"## SUN MICROSYSTEMS DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, 
.\"## INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
.\"## EVENT SHALL SUN MICROSYSTEMS BE LIABLE FOR ANY SPECIAL, INDIRECT OR
.\"## CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
.\"## USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
.\"## OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
.\"## PERFORMANCE OF THIS SOFTWARE.
.PL FULL
.H C "The PEX-SI Server Side"
.IX "server extension" "" "" "" PAGE MAJOR
.H 2 "Server Side Overview"
.IX "Model Extension"
.IX "PEX-ME"
.LP
The server-side support in \s-1PEX-SI\s+1 is a Model Extension (\s-1PEX-ME\s+1)
to the \s-1X\s+1 sample server.  \s-1PEX-ME\s+1 provides additional code
that is linked with the \s-1X11\s+1 sample server and processes \s-1PEX\s+1 protocol
requests.
\s-1PEX-ME\s+1 follows the guidelines for implementing an extension
to the \s-1X\s+1 sample server as described in the \fIDefinition of the
Porting Layer for the X v11 Sample Server\fR (1 March 1988).
.LP 
.IX "X11R4"
The \s-1PEX\s+1 protocol defines two subsets of \s-1PEX\s+1 that
provide different mechanisms for generating 3D graphics.
These subsets are defined in Appendix A of the \fIPEX Protocol Specification\fR.
The ``\s-1PHIGS\s+1 workstation subset'' of \s-1PEX\s+1 provides the
resources needed to support a \s-1PHIGS\s+1 workstation, server-side structures,
picking, and incremental spatial searching.
This subset also includes a mechanism for traversing and rendering structure
elements within the server.
The ``immediate mode rendering subset'' provides the resources and
rendering capabilities needed to support the immediate display
of output commands.
.LP 
The \s-1PEX\s+1 protocol also specifies that the structure elements defined for
the \s-1PHIGS\s+1 workstation subset are identical to the output commands
defined for the immediate mode rendering subset.
In fact, structure elements can be thought of as stored output commands.
A consequence of this specification is that structure elements can be rendered
in the same way as output commands.
.LP 
\s-1PEX-ME\s+1 is designed to take advantage of the \s-1PEX\s+1 subset
definitions;  it provides a mechanism for implementing both of the \s-1PEX\s+1
subsets in a server, and at the same time maximizes the amount of code
that can be shared between the subsets.
Following the architecture of the \s-1X\s+1 sample server model,
\s-1PEX-ME\s+1 is divided into three functional areas:\ \ 
device-independent \s-1PEX\s+1 (di\s-1PEX\s+1), device-dependent \s-1PEX\s+1
(dd\s-1PEX\s+1), and operating system-dependent \s-1PEX\s+1 (os\s-1PEX\s+1).
The goals and interactions of these three parts are described in this chapter.
Details on the implementation of \s-1PEX-ME\s+1 are given in the
\fI\s-1PEX-SI\s+1 Porting Guide\fR.
.H 3 "Goals and Constraints"
.LP
The following are the design goals of \s-1PEX-ME\s+1:
.BP
Provide an easy mechanism for building servers that support
both \s-1PEX\s+1 subsets.
.BP
Use the same lookup table, name set, and font resource implementations
for both \s-1PEX\s+1 subsets.
.BP
.IX "rendering pipeline"
Use the same rendering pipeline for both \s-1PEX\s+1 subsets.
.BP
.IX "porting"
Provide an easy mechanism for porting the rendering pipeline.
.BP
Separate \s-1X\s+1 resource management from the resource implementations.
.BP
Separate resource implementations from rendering.
.BP
Provide an easy mechanism for porting resource implementations.
.BP
Provide a well-defined interface between di\s-1PEX\s+1 and dd\s-1PEX\s+1.
.BP
Provide an extension that can be linked to the \s-1X\s+1 sample server and
run with minimal effort.
.LP
One constraint was defined to achieve the goal of ease of porting to existing
\s-1X11R4\s+1 servers:
.BP
\s-1PEX-ME\s+1 must use the \s-1X11R4\s+1 ddx interface as its rendering foundation.
.LP
.H 2 "diPEX"
.IX "diPEX" "" "" "" PAGE MAJOR
.IX "device independence"
.LP
di\s-1PEX\s+1 provides the device-independent functionality of \s-1PEX-ME\s+1.
The anticipation that support of the \s-1PEX\s+1 protocol will be ported
to native high-end graphics engines has lead to the design of a
di\s-1PEX\s+1 layer that is as thin as possible.
It performs the following functions:
.BP
Performs byte-swapping and floating-point conversions for requests and replies.
.BP
Provides all \s-1X\s+1 resource identifier to resource data de-referencing.
.BP
Implements search context, pipeline context, and renderer resources.
.BP
.IX "errors" "diPEX"
Isolates device-independent errors and generates error messages as
necessary.
.BP
Sends replies and error messages to the client.
.LP  
.IX "data flow" "diPEX"
di\s-1PEX\s+1 receives \s-1PEX\s+1 packets, unpacks them,
and translates them into the correct (server-native) byte-ordered
form and floating-point format.
di\s-1PEX\s+1 checks for errors and if none are found, dispatches the
translated requests to the appropriate dd\s-1PEX\s+1 module.
In addition, di\s-1PEX\s+1 handles replies to the client
and performs resource management functions.
.H 2 "osPEX" ospex
.IX "operating system dependence"
.IX "osPEX" "" "" "" PAGE MAJOR
.LP
os\s-1PEX\s+1 provides the \s-1PEX-ME\s+1 functionality that is heavily dependent on
the target operating system.
os\s-1PEX\s+1 performs the following operating system-dependent functions:
.BP
Locates a \s-1PEX\s+1 font file in a specified directory.
.BP
Loads a \s-1PEX\s+1 font from a \s-1PEX\s+1 font file.
.LP
Only 4.2 \s-1BSD\s+1 implementations of these functions are provided in \s-1PEX-ME\s+1.
.H 2 "ddPEX" ddpex
.IX "device dependence"
.IX "ddPEX" "" "" "" PAGE MAJOR
.LP
dd\s-1PEX\s+1 provides the non-\s-1OS\s+1-related porting layers of \s-1PEX-ME\s+1.
dd\s-1PEX\s+1 is designed to provide portability to a wide range of graphics hardware, 
from simple frame buffers, to display-list devices, to advanced graphics engines.
To achieve this, dd\s-1PEX\s+1 performs the following functions:
.BP
Renders individual structure elements and output commands.
.BP
Controls the internal storage format of server-side structures.
.BP
Edits the contents of server-side structures.
.BP
Traverses the structures for rendering, picking, and spatial search.
.BP
Performs hit-tests for picking and spatial search traversals.
.BP
Maintains workstation and renderer state information.
.BP
Maintains lookup tables and name sets.
.BP
Loads \s-1PEX\s+1 font definitions.
.LP
The support for these dd\s-1PEX\s+1 functions is divided into five modules.
Each module is designed to be as functionally independent of the
other modules as possible.
The modules are divided such that one module implements
only those resources that support the \s-1PHIGS\s+1
workstation subset; a second module implements those resources
that are shared by both \s-1PEX\s+1 subsets; a third module provides
rendering control for both subsets; and two modules form
the rendering pipeline for both subsets. 
.IX "rendering pipeline"
.LP
The five modules of dd\s-1PEX\s+1 are the following:
.BP
PHIGS Workstation Module
.IX "Level 4" "" "" "" PRINT "See \s-1PHIGS\s+1 Workstation Module"
.BP
Shared Resources Module
.BP
Rendering Control Module
.IX "Level 3" "" "" "" PRINT "See Rendering Control Module"
.BP
Transformation Module
.IX "Level 2" "" "" "" PRINT "See Transformation Module"
.BP
3D Rendering Module
.IX "Level 1" "" "" "" PRINT "See 3D Rendering Module"
.LP
.IX "X11R4"
.IX "ddx"
The \s-1X11R4\s+1 ddx serves as the bottom rendering layer for \s-1PEX-ME\s+1.
.IX "Level 0" "" "" "" PRINT "See ddx"
.IX "foundation layer"
.LP
.IX "data flow" "ddPEX" "" "" PAGE START
.IX "PHIGS Workstation Module"
The first two modules implement \s-1PEX\s+1 resources.
The \s-1PHIGS\s+1 Workstation Module implements the \s-1PHIGS\s+1 workstation,
structure, and pick measure resources.
It calls into the Transformation Module to reformat structure elements into the
device-dependent format used during rendering.
The \s-1PHIGS\s+1 Workstation Module also provides a structure traverser that
traverses structure elements.
This structure  traverser calls into the Rendering Control and Transformation Modules
to realize the draw, pick, and incremental spatial search operations on
the structure elements.
.IX "Shared Resources Module"
.LP
The Shared Resources Module implements the lookup table, name set, and
\s-1PEX\s+1 font resources.
These resources are used in both \s-1PEX\s+1 subsets.
Most of the procedures in the \s-1PHIGS\s+1 Workstation Module and the
Shared Resources Module are called by di\s-1PEX\s+1.
.LP
The resources supported in the \s-1PHIGS\s+1 Workstation and Shared Resources
Modules are implemented as independently as possible, so that the support
for a specific type of resource can be modified or replaced with minimal
effect on the other resources.
The \s-1PHIGS\s+1 Workstation and Shared Resources Modules are
discussed in further detail in Sections
.XR @NumberOf(wks) and
.XR @NumberOf(shared).
.LP
.IX "Rendering Control Module"
.IX "rendering pipeline"
The Rendering Control Module provides control of the rendering pipeline.
This includes initializing the device-dependent rendering state,
tracking the rendering state, and processing output commands for
immediate mode rendering.
The Rendering Control Module initializes the rendering pipeline for the drawing,
picking, or search operations.
Most of the procedures in the Rendering Control Module are called by di\s-1PEX\s+1.
Further details on the Rendering Control Module are given in Section
.XR @NumberOf(immed_render).
.LP
.IX "Transformation Module"
.IX "3D Rendering Module"
The Transformation and 3D Rendering Modules are dedicated to
supporting the rendering pipeline in \s-1PEX-ME\s+1.
These modules are not exposed to di\s-1PEX\s+1.
The Transformation Module reformats output commands and
structure elements to an internal device-dependent rendering format.
It updates the device-dependent rendering state according to the
attribute-setting commands it receives.
The Transformation Module also supports geometric transformations, and the
lighting and clipping of the reformatted primitives.
It passes the transformed primitives to the completely
subordinate 3D Rendering Module, and performs hit-testing for picking and spatial search.
Further details on the Transformation Module are described in Section
.XR @NumberOf(transformation).
.LP
The 3D Rendering Module takes the transformed primitives from the
Transformation Module and prepares the data for rendering by ddx.
Further details on the 3D Rendering Module are given in Section
.XR @NumberOf(three_d).
.LP 
Figure 
.XR @NumberOf(ddpex_arch) 
shows the architecture of dd\s-1PEX\s+1 and how it fits into the
overall \s-1PEX-ME\s+1 architecture.
All client requests are received by dix, which examines and dispatches
them appropriately.  \s-1PEX\s+1 requests are passed to di\s-1PEX\s+1.
.LP 
di\s-1PEX\s+1 unpacks the requests, and dispatches them to the appropriate
dd\s-1PEX\s+1 modules.
di\s-1PEX\s+1 calls into the \s-1PHIGS\s+1 Workstation and Shared Resources Modules
to dispatch requests that are part of the \s-1PHIGS\s+1 workstation subset
of \s-1PEX\s+1.
The \s-1PHIGS\s+1 Workstation Module subsequently calls into the Transformation
Module to reformat and render output commands.
.LP 
di\s-1PEX\s+1 calls into the Shared Resources and Rendering
Control Modules when dispatching requests that are part of the
immediate mode rendering subset of \s-1PEX\s+1.
The Rendering Control Module subsequently calls into the Transformation Module
to reformat and render output commands.
.sp 2
.KS
.FN "Server Architecture" ddpex_arch
.sp 2
.PS
arrowht = .06i
arrowwid = .06i
##-------------Server Architecture-------------##

Server_outer_box:
	box ht 4.25i wid 5i 
	"\fB\s-1PEX-ME\s+1\fR" at Server_outer_box.n above 

Dix:
	box invis ht 1i wid 1i with .nw at Server_outer_box.nw "dix"

Ddx:
	box invis ht 4.25i wid 1i with .sw at Server_outer_box.sw "ddx"

Dipex:
	box invis ht 1i wid 4i with .ne at Server_outer_box.ne "di\s-1PEX\s+1"

Hardware:
	box ht .5i wid 5i with .nw at Ddx.sw "Device"

Ddpex:
	box invis ht .25i wid .5i with .se at Hardware.ne "dd\s-1PEX\s+1"

Ospex:
	box ht .75i wid .625i with .nw at Dix.se "os\s-1PEX\s+1"

Osx:
	box ht .325i wid .325i with .ne at Ospex.nw "osx"

line from Dix.ne to Ddx.se
line from Dix.sw to Dipex.se

Position_1:
	box invis ht .25i wid 4i with .n at Dipex.s

Phigs_WS:
	box ht .5i wid 2i with .n at Position_1.s "\s-1PHIGS\s+1 Workstation"

Position_2:
	box invis ht .25i wid 2i with .n at Phigs_WS.s

Shared:
	box ht .5i wid 1.25i with .n at Position_2.sw "Shared Resources"

Immed_Mode:
	box ht .5i wid 1.25i with .n at Position_2.se 
	"Rendering" "Control" at Immed_Mode.c

Position_3:
	box invis ht .25i wid 2i with .nw at Shared.s

Transform:
	box ht .5i wid 2i with .n at Position_3.s "Transformation"

Position_4:
	box invis ht .25i wid 2i with .n at Transform.s

Three_D:
	box ht .5i wid 2i with .n at Position_4.s "3D Rendering"

##----------Arrows----------##
Ospex_shared:
	box invis wid .375i ht .25i with .nw at Ospex.s
	line <-> from Ospex_shared.n to Ospex_shared.s
Dix_dipex:
	box invis wid .5i ht .25i with .c at Dix.e
	line <-> from Dix_dipex.w to Dix_dipex.e 
ThreeD_ddx:
	box invis wid 1.25i ht .25i with .e at Three_D.w
	line <- from ThreeD_ddx.w to ThreeD_ddx.e 
Dix_ddx:
	box invis wid .25i ht .5i with .c at Dix.s
	line <-> from Dix_ddx.s to Dix_ddx.n
Dipex_p_s_i:  [
	Posit_1: box invis wid 2.5i ht .25i with .s at Dipex.s
	Posit_2: box invis wid 2.5 ht .25i with .n at Phigs_WS.s
	line <-> from Posit_1.nw to Posit_2.sw
	line <-> from Posit_1.ne to Posit_2.se
	line <-> from Posit_1.n to Phigs_WS.n
] with .s at Position_2.s

Position_5: box invis wid 1.5i ht 1i with .n at Phigs_WS.s
Phigs_s_i_trans:  [
	Posit_3: box invis wid 1.5 ht 1i 
	Posit_4: box invis wid 1.5i ht .5i with .c at Posit_3.c
	line -> from Posit_3.nw to Posit_4.nw   # PWKS to Shared
	line -> from Posit_3.ne to Posit_4.ne	# PWKS to Immed Rend
#	line -> from Posit_4.sw to Posit_3.sw	# Shared to Trans
	line -> from Posit_4.se to Posit_3.se	# Immed Rend to Trans
] with .c at Position_5.c

Phigs_trans:
	line -> from Phigs_WS.s to Transform.n
Shared_Immed:
	line <- from Shared.e to Immed_Mode.w
Trans_Three:
	line -> from Transform.s to Three_D.n
To_HW:  [
	Posit_5: box invis ht .4i wid 2.5i 
	line -> from Posit_5.nw to Posit_5.sw
#	line -> dashed from Posit_5.ne to Posit_5.se 
] with .ne at Three_D.s

Dix_client:
	box invis wid .5i ht .25i with .c at Dix.w 
	"Client" rjust at Dix_client.w
	line <-> from Dix_client.e to Dix_client.w
.PE
.KE
.IX "data flow" ddPEX" "" "" PAGE END
.H 3 "Communication Between diPEX and ddPEX" di_dd_Com
.IX "communication" "diPEX/ddPEX"
.LP
di\s-1PEX\s+1 and dd\s-1PEX\s+1 communicate through a stable, well-defined interface.
The interface defines the dd\s-1PEX\s+1 procedures called by di\s-1PEX\s+1.
It is expected to be useful to any \s-1PEX-ME\s+1 implementation and is not
intended to be changed.
A general description of the di\s-1PEX\s+1/dd\s-1PEX\s+1 interface is given in the
remaining sections of this chapter.
The C binding and the \s-1PEX-SI\s+1 implementation details are given in the
\fIPEX-SI Porting Guide\fR.
.LP
The interfaces to the Transformation and 3D Rendering Modules are 
dd\s-1PEX\s+1-internal interfaces.
These interfaces can be modified to support alternate data formats.
.LP
Because some of the replies generated by dd\s-1PEX\s+1 are variable in length,
di\s-1PEX\s+1 cannot know how much space is needed for the
reply data and thus cannot allocate the space specifically.
To handle this, di\s-1PEX\s+1 passes a buffer pointer to dd\s-1PEX\s+1.
di\s-1PEX\s+1 also passes the size of the buffer and 
the offset into the buffer where dd\s-1PEX\s+1 should put the data.
dd\s-1PEX\s+1 places the data into the buffer at the specified offset and returns 
the buffer and an active data count.
dd\s-1PEX\s+1 is always responsible for properly formatting the data returned
to di\s-1PEX\s+1 to conform to the encoding requirements of the \s-1PEX\s+1 protocol.
.IX "PEX packets"
With this scheme, di\s-1PEX\s+1 can pass dd\s-1PEX\s+1 the buffer that is used 
for the reply packet, and dd\s-1PEX\s+1 can then fill in the reply data
in the format expected by the client.
This reduces the amount of data copied by di\s-1PEX\s+1 when creating the reply packet.
.LP
A utility procedure is provided in di\s-1PEX\s+1 for reallocating an existing
buffer at a new size.
dd\s-1PEX\s+1 can use this procedure if the buffer is not large enough to hold
the data to be returned.
.H 2 "PEX-ME Resource Support" resources
.IX "resources" "" "" "" PAGE START
.LP
\s-1PEX-ME\s+1 fully supports the nine resource types defined for the
\s-1PEX\s+1 Protocol.  They are:
.IP "\fB\s-1PHIGS\s+1 Workstation\fR" 20
A large, complex resource that embodies much of \s-1PHIGS\s+1 policy.
.IP "\fBSearch Context\fR" 20
A resource used in performing searching operations on structure networks.
.IP "\fBPick Measure\fR" 20
A resource used in conjunction with a \s-1PHIGS\s+1 workstation
resource to perform graphical selection of primitives.
.IP "\fBLookup Table\fR" 20
Tables of values (of various categories).
.IP "\fBName Set\fR" 20
Filters used for picking, highlighting, and visibility when rendering.
.IP "\fBStructure\fR" 20
Repositories of output commands, structures may be linked hierarchically
into structure networks.
.IP "\fBRenderer\fR" 20
The basic drawing mechanism.
.IP "\fBPipeline Context\fR" 20
A table of initial rendering attributes for a renderer.
.IP "\fB\s-1PEX\s+1 Font\fR" 20
Stroke fonts and bitmap fonts.
.LP
Some of this resource support is implemented in di\s-1PEX\s+1.
Table
.XR @NumberOf(resource_mgrs) 
shows which modules utilize which resources, and how.
.KS
.TN "Resource Types and Their Utilization" resource_mgrs
.TS
center box tab(@);
cfBI | cfBI cfBI cfBI cfBI
cfBI | cfBI cfBI cfBI cfBI
l | c c c c.
@@PHIGS@Shared@Rendering
Resource@diPEX@Workstation@Resources@Control
=
Search Context@M@A@
_
Pipeline Context@M@@@E
_
Renderer@M@@@A
=
\s-1PHIGS\s+1 Workstation@@M@@@
_
Structure@@M@@@
_
Pick Measure@@M@@@
=
\s-1PEX\s+1 Font@@@M@@
_
Lookup Table@@@M@@
_
Name Set@@@M@@
.TE
.IP "Legend:" 8
The table shows which modules affect or utilize which resources.
The letters M, A, and E indicate that the module:
.br
.ta .5iR +.25i
.nf
	M	Manages or owns the resource.
	A	Can alter the data in the resource.
	E	Is exposed to the resource, but cannot manage or alter it.
.fi
.KE
.H 3 "diPEX Resource Management" dipex_res_mgmt
.IX "X resource identifier"
.LP
di\s-1PEX\s+1 handles all \s-1PEX\s+1 resource \s-1ID\s+1 to data de-referencing.
All calls to the core \s-1X\s+1 server routine \fIAddResource\fR are done in di\s-1PEX\s+1.
Also, all \s-1PEX\s+1 resource \s-1ID\s+1s in a \s-1PEX\s+1 request are de-referenced
by di\s-1PEX\s+1 (via the core \s-1X\s+1 server routine \fILookupIDByType\fR) before
di\s-1PEX\s+1 calls dd\s-1PEX\s+1 to handle the request.
.LP
The \s-1PEX\s+1 resource support is divided into two groups based on which portion of 
\s-1PEX-ME\s+1 manages (or ``owns'') the internals of the resource, di\s-1PEX\s+1
or dd\s-1PEX\s+1.
The resources that di\s-1PEX\s+1 implements are called ``visible resources.''
The resources that dd\s-1PEX\s+1 implements are called ``semi-opaque resources.''
.KS
.LP
The visible resources are:
.IX "resources" "visible"
.IX "visible resources"
.RS
.BP
Renderers
.BP
Pipeline Contexts
.BP
Search Contexts
.RE
.KE
.LP
di\s-1PEX\s+1 contains support for the creation, freeing, copying,
modification, and inquiry of these resources.
dd\s-1PEX\s+1 uses these resources for other operations associated with them,
and may modify the contents of renderers and search contexts.
.LP
.KS
The semi-opaque resources are the following:
.IX "resources" "semi-opaque"
.IX "semi-opaque resources"
.RS
.BP
\s-1PHIGS\s+1 Workstations
.BP
Structures
.BP
Pick Measures
.BP
Lookup Tables
.BP
Name Sets
.BP
\s-1PEX\s+1 Fonts
.RE
.KE
.LP
The semi-opaque resources have a portion that is visible to di\s-1PEX\s+1,
but the bulk of their data is not utilized or managed by di\s-1PEX\s+1.
The visible part of semi-opaque resources contains the \s-1PEX\s+1 resource
\s-1ID\s+1 and possibly some other cached information, in order to simplify
the interface between di\s-1PEX\s+1 and dd\s-1PEX\s+1.  For example, the visible
part of a lookup table also includes the type of the lookup table.
.H 3 "Other diPEX Resources" other
.LP
di\s-1PEX\s+1 also manages two internal resource types, \fIContext\fR and \fIWksDrawable\fR.
These resources are used for di\s-1PEX\s+1 internal bookkeeping and are not
exposed through the protocol or to dd\s-1PEX\s+1.
.LP
The Context resource is associated with an individual client.
An instance of this resource is used to keep pointers to the swapping and floating point
conversion tables and routines that will be used to process requests from the client.
An instance of a Context resource is created when the first \s-1PEX\s+1 request
is received from each \s-1PEX\s+1 client.
The resource is freed when di\s-1PEX\s+1 receives notification of client shutdown.
.LP
The WksDrawable resource is used to detect deletion of a drawable resource that has
been associated with a \s-1PHIGS\s+1 workstation resource.
This is important because if a drawable is deleted before its
associated \s-1PHIGS\s+1 workstation resource, via either direct client program control
or during client cleanup in the server, the server needs to prevent any implicit
redrawing of the workstation's image onto the defunct drawable.
dd\s-1PEX\s+1 is notified of any relevant drawable destructions.
.H 3 "Resource Dependencies" resource_depend
.IX "subordinate resources"
.LP
\s-1PEX\s+1 resources often depend on the existence of other,
``subordinate'' \s-1PEX\s+1 resources.
For instance, a \s-1PHIGS\s+1 workstation resource contains references to 
the lookup table and name set resources.
A lookup table resource that is referenced by a 
\s-1PHIGS\s+1 workstation resource cannot be deleted until the workstation resource
no longer needs the lookup table.
These semantics are defined in the \fI\s-1PEX\s+1 Protocol Specification\fR
description for the \fIPEXFreeLookupTable\fR request 
and the other requests for freeing resources.
.LP
.IX "cross-referencing resources"
.IX "resources" "cross-referencing"
Resource dependencies such as these must be tracked by 
di\s-1PEX\s+1 and dd\s-1PEX\s+1.
The tracking of the resource dependencies is achieved by maintaining resource 
cross-references within each resource.
The cross-references may be in the form of a full list or a simple reference count.
Utility procedures that assist with the maintenance of the cross-references are
defined for each resource type.
These procedures add or remove a resource from the cross-reference list or count.
.LP
Resource dependencies in \s-1PEX-SI\s+1 are shown in Figure 
.XR @NumberOf(resources_fig).
The arrow from resource type A to resource type B (A\(->B) indicates that 
resource type A depends on resource type B.
.sp 2
.KS
.FN "PEX Resource Dependencies" resources_fig
.sp
.PS 
#
#----------- PEX Resource Dependencies -----------#
#
arrowwid = .06i
arrowht = .06i
#  STRUCTURE -- Outer Dashed Boxes and Legend  -- Made invisible now
dashwid = .05i
moveht = .125i
down
Box_1:
	box invis ht 1i wid 6i
move
Box_2:
	box invis same
move
Box_3:
	box invis same
move left .75i
move down .25i
Legend:
	box invis ht .375i wid 4i
#	"\s-1WKS\s+1 = \s-1PHIGS\s+1 Workstation" at Legend.nw ljust
#	"\s-1STR\s+1 = Structure" at Legend.w ljust
#	"\s-1SC\s+1 = Search Context" at Legend.sw ljust
#	"\s-1PICK\s+1 = Pick Measure" at Legend.n ljust
#	"\s-1FONT\s+1 = Font" at Legend.c ljust
#	"\s-1LUT\s+1 = Lookup Table" at Legend.s ljust
#	"\s-1NS\s+1 = Name Set" at Legend.ne ljust
#	"\s-1REND\s+1 = Renderer" at Legend.e ljust
#	"\s-1PC\s+1 = Pipeline Context" at Legend.se ljust
#
# RESOURCE DEPENDENCIES -- Block Diagram
#
Block_box:
	box invis ht 2.5i wid 5.25i with .c at Box_2.c
Block_Diagram: [
	boxht = .5i; boxwid = .75i; movewid = .375i
	right
	Dummy: box invis ""  # This is a kluge to get "PHIGS" to print in WKS
	#
	# LEFT TO RIGHT Zig-Zag with single line arrows
	#
	WKS: box ht .5i wid .77i "\s-1PHIGS\s+1" "Workstation"
	arrow ->
#	Arrow_box:
# 		box invis ht .125i wid .375i with .w at WKS.e
# 		arrow -> from Arrow_box.nw to Arrow_box.ne
#		arrow <- from Arrow_box.sw to Arrow_box.se

	STR: box "Structure" 
	arrow <-
	SC: box "Search" "Context"
	move
	Pick: box "Pick" "Measure"
	move down 1i; move left 5.5i; right
	Font: box "\s-1PEX\s+1 Font"
	arrow <-
	LUT: box "Lookup" "Table"
	move
	NS: box "Name Set"
	move down 1i; move left .75i; right
	REN: box "Renderer"
	arrow -> 
	PC: box "Pipeline" "Context"
	arrow from REN.n to NS.s
	#
	# ARROWS - 2 and 3 line arrows
	#
	Pick_WKS:
		box invis ht .2i wid 3.65i with .se at Pick.n
		line from Pick.n to Pick_WKS.ne to Pick_WKS.nw
		arrow from Pick_WKS.nw to Pick_WKS.sw
	Pick_STR:
		box invis ht .10i wid 2.125i with .sw at STR.n
		line from Pick_STR.nw to Pick_STR.ne to Pick_STR.se
		arrow from Pick_STR.nw to STR.n
	STR_STR:
		box invis ht .15i wid .375i with .n at STR.s
		line from STR_STR.ne to STR_STR.se to STR_STR.sw
		arrow from STR_STR.sw to STR_STR.nw
	WKS_NS:
		box invis ht .5i wid 1.125i with .se at NS.n
		line from WKS_NS.nw to WKS_NS.w to WKS_NS.e
		arrow from WKS_NS.e to WKS_NS.se
	SC_NS:
		box invis ht .75i wid 1.5i with .ne at SC.s
		line from SC.s to SC_NS.se
		arrow from SC_NS.se to NS.e
	Pick_NS:
		box invis ht .9i wid 2i with .ne at Pick.s
		line from Pick.s to Pick_NS.se
		arrow from Pick_NS.se to Pick_NS.sw
	WKS_LUT:
		box invis ht .5i wid .375i with .sw at LUT.nw
		arrow from WKS_LUT.n to WKS_LUT.s
	REN_LUT:
		box invis ht .75i wid .75i with .se at REN.w
		line from REN.w to REN_LUT.sw
		arrow from REN_LUT.sw to LUT.s
] with .c at Block_box.c
.PE
.KE
.IX "resources" "" "" "" PAGE END
.LP
As an example, consider a colour lookup table resource named \s-1C-LUT\s+1.
This resource has two cross-reference lists, one for \s-1PHIGS\s+1 workstations
and one for renderers.
Now, consider that a \s-1PHIGS\s+1 workstation resource named \s-1WKS-1\s+1 is created
and the \fIPEXCreatePhigsWks\fR request specifies that the colour lookup table
for this resource is \s-1C-LUT\s+1.
The dd\s-1PEX\s+1 procedure that creates the workstation resources calls
the lookup table cross-reference utility to add \s-1WKS-1\s+1 to the
\s-1PHIGS\s+1 workstation cross-reference list of \s-1C-LUT\s+1.
If a \fIPEXFreeLookupTable\fR request freeing \s-1C-LUT\s+1 is then received,
dd\s-1PEX\s+1 checks the \s-1PHIGS\s+1 workstation and renderer cross-reference lists
in \s-1C-LUT\s+1 to see if both lists are empty.
\s-1C-LUT\s+1 is immediately destroyed if the lists are empty.
In this example, dd\s-1PEX\s+1 sees that there is a workstation resource
\s-1WKS-1\s+1 using \s-1C-LUT\s+1.
Therefore, \s-1C-LUT\s+1 is not immediately destroyed, but a flag is set
in \s-1C-LUT\s+1 indicating that it can be destroyed as soon as both of
its cross-reference lists are empty.
.LP 
When a \fIPEXFreePhigsWKS\fR request freeing \s-1WKS-1\s+1 is received,
dd\s-1PEX\s+1 calls the lookup table cross-reference utility again to
remove \s-1WKS-1\s+1 from the \s-1PHIGS\s+1 workstation list in \s-1C-LUT\s+1.
The utility then checks for the flag that indicates if \s-1C-LUT\s+1 has been freed.
In this example, it finds the flag is set, and it finds that both
cross-reference lists of \s-1C-LUT\s+1 are empty.
So, the utility destroys \s-1C-LUT\s+1.
.LP 
.IX "subordinate resources"
In summary, a cross-reference \fIlist\fR is only needed when a subordinate resource needs to
notify its parent resource that a change has been made to the subordinate resource.
.\"For example, a workstation resource needs to
.\"be notified when a change is made to a bundle lookup table so that
.\"the workstation can update the display if necessary.
The subordinate resource maintains a cross-reference \fIcount\fR when no
notification is needed.
Further details on resource cross-references are given in the descriptions of each resource.
.H 2 "The PHIGS Workstation Module"wks
.IX "ddPEX porting layers" "1" "" "PHIGS Workstation Module" PAGE MAJOR
.IX "modules" "" "" "" PRINT "See \fIdd\s-1PEX\s+1 porting layers\fR"
.IX "PHIGS Workstation Module" "" "" "" PAGE MAJOR 
.LP
The \s-1PHIGS\s+1 Workstation Module implements the 
\s-1PHIGS\s+1 workstation, pick measure, and structure resources.
It also implements a structure traverser that passes structure elements
to the Transformation Module for rendering, picking, or spatial search.
.H 3 "PHIGS Workstation Resources" pwks
.IX "resources" "PHIGS workstation resources" "" "" PAGE MAJOR
.IX "PHIGS workstation resources" "" "" "" PAGE MAJOR
.IX "display dynamics, workstation"
.IX "workstation display dynamics"
.LP
A \s-1PHIGS\s+1 workstation resource contains information on the state of the 
workstation's display, on the rendering state used during structure 
traversal, and on the supported pick devices.
It updates the workstation display according to the current update mode
and dynamics of the workstation.
.LP
Updating the display may require an implicit traversal of the structures
posted to the workstation, as described by \s-1PHIGS\s+1 and \s-1PHIGS PLUS\s+1.
The rendering state information in the workstation resource is used by the 
rendering pipeline, which processes the structure elements traversed
when the display is updated.  
.IX "rendering pipeline"
.LP
\s-1PEX-ME\s+1 uses the same rendering pipeline to update the workstation
display that it uses for the immediate mode rendering of output commands in a renderer resource.
This rendering pipeline is designed to maintain its rendering state
in a renderer resource.
Thus, the \s-1PHIGS\s+1 workstation resource provides a renderer resource
to the rendering pipeline in \s-1PEX-SI\s+1.
(For more information on the rendering pipeline, see Section
.XR @NumberOf(immed_render)
on the Rendering Control Module, and Section
.XR @NumberOf(transformation)
on the Transformation Module.)
.LP
Other implementations may use a different rendering pipeline,
a hardware pipeline for example, to update the display.
The \fI\s-1PEX-SI\s+1 Porting Guide\fR explains how the workstation resource can
be modified to support a different rendering pipeline.
.LP
dd\s-1PEX\s+1 defines the procedures that support the \s-1PHIGS\s+1 workstation resources.
It defines a set of procedures that support the \s-1PEX\s+1 requests specified
in the \fI\s-1PEX\s+1 Protocol Specification\fR.
dd\s-1PEX\s+1 also defines utility procedures for updating the display and for
updating the resource cross-references in the workstation resources.
A general description of these procedures is given below.
The procedures that support the requests for pick devices are described
in Section 
.XR @NumberOf(pick) on pick measure resources. 
.LP
The dd\s-1PEX\s+1 procedures that support the \s-1PEX\s+1 requests for
\s-1PHIGS\s+1 workstation resources map one-to-one with the requests
specified in the \fIPEX Protocol Specification\fR.
di\s-1PEX\s+1 dispatches the requests to these procedures. 
.IX "cross-reference update procedure" "PHIGS workstation resources"
The cross-reference update procedure adds and removes resources from
the cross-references associated with workstation resources, as
explained in Section
.XR @NumberOf(resource_depend).
.LP
The only resources that depend on workstation resources are pick measure resources.
A workstation resource keeps a reference count of the number of pick measure
resources that are using it.
.IX "pick measure resources"
.IX "resources" "pick measure resources"
The update procedure is called by dd\s-1PEX\s+1 to increment or decrement the count
when a pick measure resource is created or destroyed.
This procedure is not called by di\s-1PEX\s+1.
.LP
The dynamics utility procedures handle the display dynamics of workstation resources.
These utilities are called by dd\s-1PEX\s+1 when changes are made to the
structure, name set, lookup table, and \s-1PHIGS\s+1 workstation resources. 
.IX "structure resources, STR"
.IX "lookup table resources"
.IX "resources" "structure resources"
.IX "resources" "lookup table resources"
.IX "name set resources"
.IX "resources" "name set resources"
The utilities determine how to update the workstation's display based on the
workstation's dynamics and update mode.
These utilities are not called by di\s-1PEX\s+1.
.H 3 "Structure Resources" structures
.IX "structure resources" "" "" "" PAGE MAJOR
.IX "resources" "structure resources" "" "" PAGE MAJOR
.LP
.IX "PHIGS workstation resources" 
.IX "search context resources" 
.IX "pick measure resources" 
.IX "resources" "PHIGS workstation resources" 
.IX "resources" "search context resources" 
.IX "resources" "pick measure resources" 
.IX "procedure tables"
.IX "Transformation Module"
.IX "structure elements"
.LP
Structure resources contain information on the structures that exist
in the server-side \s-1CSS\s+1.  The structure resources contain state
information on these structures and on all of the elements in the structures.
.LP
dd\s-1PEX\s+1 contains a set of procedures that support the \s-1PEX\s+1 protocol
requests defined for structure resources.
It also has procedures that support the interaction of structure resources with
other resources.
\s-1PEX\s+1 requests are handled by a set of procedures that map one-to-one with the
protocol requests specified in the \fIPEX Protocol Specification\fR, with the
exception of the \fIPEXDestroyStructures\fR request.
For this request, the dd\s-1PEX\s+1 procedure destroys only one structure at a time.
di\s-1PEX\s+1 calls this procedure for each structure specified in the 
\fIPEXDestroyStructures\fR request.
.LP 
Structure resources are part of a structure network.
The network hierarchy is defined by the existence of
\fIExecuteStructure\fR elements in the structures.
Structures maintain a cross-reference list of their
parent and offspring structures in this structure network.
This aids in maintaining the structure network and
handling some of the protocol requests for structures.
.LP 
Structure resources are subordinate to \s-1PHIGS\s+1 workstation,
search context, and pick measure resources.
A cross-reference update procedure is provided for structure resources to
maintain the cross-references of those resources that are using the structures.
This utility procedure adds resources to and removes resources from the cross-reference
lists and counts.
It is called by both di\s-1PEX\s+1 and dd\s-1PEX\s+1.
.LP
Structures are subordinate to the workstation resources on which they are posted.
A structure resource maintains a cross-reference list of these
workstation resources and notifies the workstation resource when the
structure has changed, so that the Workstation can update the display.
A structure resource maintains two cross-reference lists.
One list contains the workstation resources that the structure is directly posted to.
The other list contains the workstation resources that have an ancestor or
descendent of the structure posted to them.
.LP 
A structure resource keeps a reference count of the search context
and pick measure resources that specify the structure in their start paths.
A procedure is also provided that verifies that a path is valid
within a given structure network.
This procedure is called by both di\s-1PEX\s+1 and dd\s-1PEX\s+1.
.LP
In addition to the di\s-1PEX\s+1/dd\s-1PEX\s+1 interface just described,
an internal interface handles operations on structure elements.
This interface provides a mechanism that allows the storage format
of structure elements to be defined by the implementation.
The interface defines six operations on structure elements:\ \ 
create, destroy, copy, replace, inquire, and execute.
There is a procedure to support each operation for every structure element type.
The procedures are accessed through six procedure tables, each of which contains
an entry for every table type, plus one additional entry to handle out-of-range elements.
.LP
The \fIcreateCSSElement\fR operation creates a new structure element
from a given \s-1PEX\s+1 element.  This operation massages the data
into the device-dependent format and returns a pointer to the new
element.  All data must be copied from the \s-1PEX\s+1
request packet element to the structure elements because the request
buffer is volatile.
.LP
The \fIdestroyCSSElement\fR operation destroys the structure elements
created by the \fIcreate\fR or \fIcopy\fR procedures.
.LP
The \fIcopyCSSElement\fR operation creates a new element by copying the
data from the given element to the new element.
.LP
The \fIreplaceCSSElement\fR operation replaces the given element with a new element.
This operation is used only when an element is stored in replace mode 
and the element type being replaced is identical to the element being stored.
.LP
The \fIinquireCSSElement\fR operation converts the given element data to
\s-1PEX\s+1 Protocol format.
.LP
.IX "ExecuteOC" "" "\fIExecuteOC\fP"
The \fIexecuteCSSElement\fR operation performs the action required for the
given element during structure traversal.
This could be rendering, picking, or spatial search.
In \s-1PEX-ME\s+1, this operation is the Transformation Module's
\fIExecuteOC\fR operation (see Section
.XR @NumberOf(transformation)).
.LP
The structure storage format used in \s-1PEX-ME\s+1 is defined by the device-dependent
format used in the Transformation Module.
It is the same format that is used for rendering immediate mode output commands.
The procedures in the \s-1CSS\s+1 tables can call directly
into the corresponding Transformation Module procedures.
For more information on the Transformation Module, see Section 
.XR @NumberOf(transformation).
.IX "Transformation Module"
.H 3 "Search Context Resources" sc
.IX "search context resources" "" "" "" PAGE MAJOR
.IX "resources" "search context resources" "" "" PAGE MAJOR
.IX "spatial search"
.LP
Search context resources are defined and controlled by di\s-1PEX\s+1.
di\s-1PEX\s+1 handles all of the actions necessary to support the
create, free, get, and change operations on Search contexts.
dd\s-1PEX\s+1 has one procedure defined to handle the \fIPEXSearchNetwork\fR request.
This dd\s-1PEX\s+1 procedure controls structure traversal for the spatial search.
It turns on spatial search, traverses the structure network, and turns off
spatial search.
Turning on spatial search causes the rendering
procedures in the \fIexecuteCSSElement\fR table to be replaced with
procedures that do spatial search intersection, or hit testing.
This procedure also sets the traverser to test for a hit after every
graphics primitive is traversered.
When a hit occurs, the traverser sets the search path in the search context resource
and stops traversing.
.H 3 "Pick Measure Resources" pick
.IX "pick measure resources" "" "" "" PAGE MAJOR
.IX "resources" "pick measure resources" "" "" PAGE MAJOR
.LP
Pick devices are supported as part of the dd\s-1PEX PHIGS\s+1 workstation resources.
They provide device-dependent initialization values for pick measure resources.
dd\s-1PEX\s+1 has procedures to handle the \fIPEXGetPickDevice\fR and
\fIPEXChangePickDevice\fR requests.
The procedures are called by di\s-1PEX\s+1 when it dispatches these requests.
.IX "PHIGS workstation resources"
.IX "resources" "PHIGS workstation resources"
.LP
Pick measure resources are fully implemented in dd\s-1PEX\s+1.
There is one dd\s-1PEX\s+1 procedure to handle each pick measure protocol request.
di\s-1PEX\s+1 calls the procedures when it dispatches the requests.
.LP
The dd\s-1PEX\s+1 procedure that handles the \fIPEXUpdatePickMeasure\fR request
initiates structure traversal for the pick.
It calls procedures in the Rendering Control Module to set up the
graphics pipeline for picking before traversal, and to reset the
pipeline when the traversal is finished.
During traversal, the pipeline procedures for picking are called and
the traverser checks for a hit and sets the pick path in the
pick measure resource.
.LP
Hit testing is based on a ``Pick First'' algorithm.
.H 2 "The Shared Resources Module" shared
.IX "ddPEX porting layers" "3" "" "Shared Resources Module" PAGE MAJOR
.IX "Shared Resources Module" "" "" "" PAGE MAJOR
.IX "PHIGS Workstation Module"
.IX "Rendering Control Module"
.LP
The dd\s-1PEX\s+1 Shared Resources Module supports the lookup table, name set,
and \s-1PEX\s+1 font resources.
These resources are common to both the \s-1PHIGS\s+1 workstation subset and the 
immediate mode rendering subset, and are used in all \s-1PEX\s+1 server configurations
(\s-1PHIGS\s+1 workstation rendering, immediate mode rendering, or a combination of both).
.LP
The procedures for these functions map one-to-one with the \s-1PEX\s+1 requests 
for the lookup table, name set, and \s-1PEX\s+1 font resources.
The procedures provide the functionality specified in the
\fI\s-1PEX\s+1 Protocol Specification\fR.
The C binding and implementation details for these procedures are given in the 
\fI\s-1PEX-SI\s+1 Porting Guide\fR.
The Shared Resource Module interface is exposed to di\s-1PEX\s+1.
.H 3 "Lookup Table Resources" lut
.IX "resources" "lookup table resources" "" "" PAGE MAJOR
.IX "lookup table resources" "" "" "" PAGE MAJOR
.IX "cross-reference update procedure" "lookup table resources"
.LP
There are 12 types of lookup tables defined in the \fIPEX Protocol Specification\fR.
Each type of lookup table contains information that is used during rendering.
\s-1PEX-ME\s+1 defines one dd\s-1PEX\s+1 procedure for each lookup table request,
regardless of the table type.
All of these procedures are called by di\s-1PEX\s+1.
.LP
Lookup tables have cross-reference lists of the \s-1PHIGS\s+1 workstation and
renderer resources that use the tables.
.IX "PHIGS workstation resources"
.IX "renderer resources"
.IX "resources" "PHIGS workstation resources"
.IX "resources" "renderer resources"
There is a utility procedure called by di\s-1PEX\s+1 and dd\s-1PEX\s+1 to
update the lists.
A utility procedure also checks that a lookup table can be
used with a given drawable, based on the example drawable given when
the lookup table was created.
.IX "drawables"
The procedure is called by di\s-1PEX\s+1 and dd\s-1PEX\s+1 when a
lookup table is first referenced by a workstation or renderer
resource,  It checks to see if the table is compatible with the workstation's or
renderer's drawable.
.LP
Each time a lookup table is changed, each workstation and renderer in
the cross-reference lists is notified of the change through a
call-back procedure defined for this purpose.
The workstation call-back procedure updates the workstation state and the
picture as needed.
(For more information on the \s-1PHIGS\s+1 Workstation Module, see Section 
.XR @NumberOf(wks).)
The renderer call-back procedure sets the change flag in the renderer
that is used when the renderer is validated.
(For more information on the Rendering Control Module, see Section 
.XR @NumberOf(immed_render).)
.H 3 "Name Set Resources" ns
.IX "resources" "name set resources" "" "" PAGE MAJOR
.IX "name set resources" "" "" "" PAGE MAJOR
.LP
Name set resources contain the lists that are used for highlighting,
visibility, detectability filters, and the current name set.
There is one procedure in dd\s-1PEX\s+1 for each \s-1PEX\s+1 name set request.
These procedures are called by di\s-1PEX\s+1.
.LP
Name sets have a cross-reference list of workstation and renderer
resources.
.IX "cross-reference update procedure" "name set resources"
.IX "PHIGS workstation resources"
.IX "renderer resources"
.IX "resources" "PHIGS workstation resources"
.IX "resources" "renderer resources"
When a change is made to a name set, each workstation and
renderer in the cross-reference lists is notified of the change
through a call-back procedure.
The workstation call-back procedure updates the workstation state and the
picture as needed.
(For more information on the \s-1PHIGS\s+1 Workstation Module, see Section 
.XR @NumberOf(wks).)
The renderer call-back procedure sets the change flag in the renderer
that is used when the renderer is validated.
(For more information on the Rendering Control Module, 
see Section 
.XR @NumberOf(immed_render).)
.H 3 "PEX Font Resources"
.IX "resources" "PEX font resources" "" "" PAGE MAJOR
.IX "PEX font resources" "" "" "" PAGE MAJOR
.IX "font resources" "" "" "" PAGE MAJOR
.LP
The \s-1PEX\s+1 font resources contain the server native description of a \s-1PEX\s+1 font.
ddPEX procedures for font resources are found in the Shared Resources
Module of dd\s-1PEX\s+1 and in os\s-1PEX\s+1.
These procedures support each of the \s-1PEX\s+1 font requests.
.LP
.IX "cross-reference update procedure" "PEX font resources"
Font resources have a cross-reference count of the lookup tables that reference the fonts.
There is a utility procedure for updating the count
that is called by the dd\s-1PEX\s+1 lookup table code.
.IX "lookup table resources"
.IX "resources" "lookup table resources"
.H 2 "The Rendering Control Module" immed_render
.IX "Rendering Control Module" "" "" "" PAGE MAJOR
.IX "ddPEX porting layers" "2" "" "Rendering Control Module" PAGE MAJOR
.LP
.IX "immediate mode rendering"
The Rendering Control Module controls the beginning of the graphics
pipeline for the \s-1PHIGS\s+1 workstation and the immediate mode subsets of PEX.
This module maintains the device-dependent data in the renderer resources.
It controls initializing, changing, saving, and restoring the device
data during immediate mode rendering, workstation traversals, and
during rendering, picking, and searching traversals.
Each of the procedures defined for this are described in this section.
.H 3 "Pipeline Context Resources" pipeline
.IX "pipeline context resources" "" "" "" PAGE MAJOR
.IX "resources" "pipeline context resources" "" "" PAGE MAJOR
.LP
A pipeline context resource is used to specify the initial attribute state when
rendering begins.
As stated in the \fI\s-1PEX\s+1 Protocol Specification\fR, the attributes in a
pipeline context resource are copied to the renderer resource at that time.
No dd\s-1PEX\s+1 procedures are associated with pipeline context resource requests.
.H 3 "Renderer Resources" renderer
.IX "renderer resources" "" "" "" PAGE MAJOR
.IX "resources" "renderer resources" "" "" PAGE MAJOR
.LP
.IX "device dependence"
.IX "device independence"
The renderer resource contains device-independent and device-dependent information.
.LP
.IX "ExecuteOC" "" "\fIExecuteOC\fP"
.IX "ddContext" "" "\fIddContext\fP"
.IX "procedure tables"
dd\s-1PEX\s+1 manages the device-dependent information.
This includes a procedure table for the rendering procedures, called the \fIExecuteOC\fR
table, and a device-dependent rendering state structure, called the \fIddContext\fR.
The \fIExecuteOC\fR table is part of the Transformation Module interface and is described
in Section
.XR @NumberOf(transformation).
.IX "Transformation Module"
The \fIddContext\fR is designed to be what its name implies \(em 
a structure that can be replaced or modified 
to interface with the software and hardware dependencies used
in a particular \s-1PEX\s+1 server implementation.
\fIddContext\fR is dependent on the specific devices used to render
\s-1PEX\s+1 primitives.
\fIddContext\fR contains state information, caches, and so on, in a form suitable to 
the native implementation.
The attributes from the pipeline context resource and the device-independent part of 
the renderer resource are used to update the \fIddContext\fR.
.KS
.LP
The Rendering Control Module contains procedures to
create and destroy the \fIddContext\fR.
It also has procedures to support each of the following \s-1PEX\s+1 requests:\ \ 
.BP
\fIPEXGetRendererDynamics\fR
.BP
\fIPEXRenderOutputCommands\fR
.BP
\fIPEXBeginRendering\fR
.BP
\fIPEXEndRendering\fR
.BP
\fIPEXBeginStructure\fR
.BP
\fIPEXEndStructure\fR
.KE
.LP
These procedures have the required functionality for their matching \s-1PEX\s+1 requests.
All of these procedures are called by di\s-1PEX\s+1 and by dd\s-1PEX\s+1.
.LP
The \fIBeginRendering\fR and \fIEndRendering\fR procedures establish the graphics
pipeline as a rendering pipeline.
The graphics pipeline produces graphical output to the drawable.
.IX "drawables"
In addition to these procedures, this module contains procedures for controlling
the graphics pipeline for picking and for incremental spatial searches.
Procedures for \fIBeginPicking\fR, \fIEndPicking\fR, \fIBeginSearching\fR, and
\fIEndSearching\fR control those pipelines
just as \fIBeginRendering\fR and \fIEndRendering\fR do for the rendering
pipeline.
These control procedures load the \fIExecuteOC\fR table in the renderer
with the correct procedures for picking or searching.
In addition, there is a procedure for returning the status of the pick hit tests
done in the lower level modules and an equivalent procedure for returning the
status of the search hit tests.
.LP
The Rendering Control Module also has a utility procedure for
validating the renderer.
This procedure updates the \fIddContext\fR with the current rendering attributes
from the renderer and the pipeline context, lookup table, and name set resources
it references.
.IX "name set resources"
.IX "resources" "name set resources"
.IX "lookup table resources"
.IX "resources" "lookup table resources"
.IX "pipeline context resources"
.IX "resources" "pipeline context resources"
The validate procedure is called by the rendering control
procedures for \fIBeginRendering\fR, \fIBeginPicking\fR, \fIBeginSearching\fR,
and \fIRenderOutputCommand\fRs.
It looks at a set of bit masks, which are in the renderer, to see which
resources have been changed since the last time the renderer was validated.
The procedure then updates the \fIddContext\fR to reflect the changes according
to the dynamics of the renderer.
The bit masks are set by the call-back procedure, which notifies a renderer
whenever one of its subordinate resources is changed.
.H 2 "The Transformation Module" transformation
.IX "ddPEX porting layers" "4" "" "Transformation Module" PAGE MAJOR
.IX "Transformation Module" "" "" "" PAGE MAJOR
.LP
The Transformation Module performs the following major functions:
.BP
.IX "Central Structure Store, CSS"
Provides the device-dependent \s-1CSS\s+1 operations that create,
destroy, copy, replace, and inquire structure elements
for storage in device-dependent format.
.BP
.IX "immediate mode rendering"
Reformats output commands into device-dependent data formats
for immediate mode rendering.
.BP
Processes device-dependent output commands (provided as
structure elements or immediate mode output commands) for rendering.
.LP
.IX "structure elements"
The Transformation Module defines the procedures for transforming
structure elements and output commands into a device-dependent format.
It also defines other operations for manipulating structure
elements and provides the first steps in processing the data through
the graphics pipeline.
It provides a different set of procedures, if needed, for rendering,
picking, or searching operations.
.IX "graphics pipeline"
.LP
.IX "output commands, OC"
Because structure elements are simply stored output commands, and
structure elements are received by dd\s-1PEX\s+1 in the same
\s-1PEX\s+1 protocol formats as output commands, structure elements
and output commands are handled by dd\s-1PEX\s+1 in the same way.
Therefore, all references to output commands (\s-1OC\s+1s) in the rest of this document
apply to both structure elements and to immediate mode output commands.
.LP
Six operations are defined in this module for manipulating \s-1OC\s+1s:\ \  
create, destroy, copy, replace, inquire, and render.
.IX "server-side CSS"
All of these operations are used for server-side \s-1CSS\s+1,
as described in section 
.XR @NumberOf(structures).
Only the parse, destroy, and execute operations are used for immediate mode
output commands.
.IP "\fBparse\fR" 10
The parse operation reformats the \s-1PEX\s+1 output command to the 
device-dependent \s-1OC\s+1 format.
This operation also allocates the storage needed for storing the
device-dependent \s-1OC\s+1 in the internal \s-1CSS\s+1.
.IP "\fBdestroy\fR" 10
The destroy operation frees the storage allocated by the create operation.
.IP "\fBcopy\fR" 10
The copy operation allocates storage for a new
device-dependent \s-1OC\s+1 and copies the data from a
given device-dependent \s-1OC\s+1 to the new one.
.IP "\fBreplace\fR" 10
The replace operation copies the data from a \s-1PEX OC\s+1 to a given
device-dependent \s-1OC\s+1, thus replacing the contents of the
device-dependent \s-1OC\s+1.
.IP "\fBinquire\fR" 10
The inquire operation returns the original \s-1PEX\s+1 OC
from a given device-dependent \s-1OC\s+1.
.KS
.IP "\fBexecute\fR" 10
.IX "rendering pipeline"
The execute operation starts the \s-1OC\s+1 down the rendering pipeline.
For \s-1OC\s+1s that set a rendering attribute, this operation updates
the \fIddContext\fR of the renderer.
For output primitives, the execute operation performs geometric transformations, and
clipping, and applies lighting attributes to the primitives.
The primitives are then passed onto the 3D Rendering Module where
the rest of the rendering pipeline is implemented.
.KE
.LP
Each of these operations is implemented separately for each output command type.
.IX "procedure tables"
The procedures are accessed through six procedure tables:\ \ 
\fIParseOC\fR, \fIDestroyOC\fR, \fICopyOC\fR, \fIReplaceOC\fR, \fIInquireOC\fR, and
\fIExecuteOC\fR.
Each procedure table contains an entry point for each output command type.
\s-1PEX-SI\s+1 uses procedure tables to provide flexibility
for \s-1PEX-ME\s+1 implementers.
The default procedure tables supplied in \s-1PEX-ME\s+1 can
easily be modified to include implementation-specific procedures.
Or the default procedures can be replaced for a subset of the output
commands or all of the output commands.
A single procedure can also be used for more than one output command.
.LP
.IX "ParseOC" "" "\fIParseOC\fP"
.IX "CopyOC" "" "\fICopyOC\fP"
.IX "InquireOC" "" "\fIInquireOC\fP"
.IX "ReplaceOC" "" "\fIReplaceOC\fP"
.IX "DestroyOC" "" "\fIDestroyOC\fP"
The \fIParseOC\fR table provides the procedures for creating the 
device-dependent output command from the \s-1PEX\s+1 output command.
The \fIDestroyOC\fR table provides the procedures for destroying the
storage associated with output commands.
The \fICopyOC\fR, \fIReplaceOC\fR, and \fIInquireOC\fR tables provide
the procedures for copying, replacing, and inquiring the output commands,
respectively.
A table is defined in dd\s-1PEX\s+1 for each of these five operations. 
.LP
The \fIExecuteOC\fR table provides the procedures for rendering the
output commands.
.IX "ExecuteOC" "" "\fIExecuteOC\fP"
One \fIExecuteOC\fR table is associated with each renderer resource
(see Section
.XR @NumberOf(renderer)).
.IX "renderer resources"
.IX "resources" "renderer resources"
This allows for different rendering procedures to be used depending
on the current rendering state.
For instance, separate procedures could be provided for rendering hollow fill
areas and filled fill areas.
To do this, the procedures must be associated with the renderer resource
that contains the rendering state.
\s-1PEX-ME\s+1 uses the \fIExecuteOC\fR table to load different procedures
for drawing, picking, and incremental spatial searches of primitives.
.H 2 "The 3D Rendering Module" three_d
.IX "3D Rendering Module" "" "" "" PAGE MAJOR
.IX "ddPEX porting layers" "5" "" "3D Rendering Module" PAGE MAJOR
The 3D Rendering Module is the rendering layer for dd\s-1PEX\s+1.
The data received by this layer are either 3D or 2D
device coordinates with model/view, transformation/clipping, lighting,
and/or depth-cueing already applied.
.IX "device coordinates"
.IX "ddx"
Conceptually, this layer resembles an extended ddx.  In the case where
the data has been resolved to 2D coordinates with no other per-vertex
data, the input data can be passed directly to ddx.  However, when
interpolation is required for 3D vertices with per-vertex colour
information, and so on, significant data manipulation is necessary.
.LP
Alternatively, when the graphics pipeline is set up for picking or
searching, the 3D Rendering Module does the hit test for these
functions.  It does not call ddx to do this.
.LP
This module could be replaced completely if an application requires
the data to be passed to implementation-specific software or hardware
instead of ddx.
.H 2 "Miscellaneous ddPEX Functions and Errors"miscellaneous
.IX "ddPEX porting layers" "miscellaneous functions"
.LP
Four functions are defined to handle miscellaneous operations needed in all
\s-1PEX\s+1 implementations: 
.BP
.IX "enumerated types"
Two functions support the \fIPEXGetEnumeratedTypeInfo\fR and 
\fIPEXGetImpDepConstants\fR requests.
They return the implementation information for enumerated types and 
implementation-dependent constants.
.IX "implementation-dependent constants"
.BP
A third function initializes dd\s-1PEX\s+1 whenever the server is started or reset.
.IX "initializing ddPEX"
.BP
The fourth function is called when the server shuts down.
It cleans up after dd\s-1PEX\s+1.
.H 3 "Errors in ddPEX"
.IX "errors" "ddPEX"
dd\s-1PEX\s+1 returns an error code to di\s-1PEX\s+1 for each
dd\s-1PEX\s+1 procedure performed.
The error returned is the \s-1X\s+1- or \s-1PEX\s+1-defined error number
specified in the \s-1PEX\s+1 protocol for the particular condition.
