





X Image Extension
Protocol Reference Manual




Publication Description:

This document describes the protocol of the X WINDOW SYSTEM IMAGE EXTENSION.














Version 5.0

X Consortium Standard

X Version 11, Release 6

April 7, 1994































Copyright (c) 1988, 1989, 1990, 1991, 1992  Digital Equipment Corporation

Copyright (c) 1990, 1991, 1992, 1993, 1994  X Consortium

Copyright (c) 1992, 1993, 1994  AGE Logic, Inc.


Permission to use, copy, modify, distribute, and sell this documentation for any purpose is 
hereby granted without fee, provided that the above copyright notices and this permis-
sion notice appear in all copies. Digital, X Consortium, and AGE Logic make no represen-
tations about the suitability for any purpose of the information in this document. This 
documentation is provided as is without express or implied warranty.




Contents
Contents	iii
Preface	x
Related Documents	x
Participants	xi
Authors:	xi
Contributors:	xi
Revision History	xi
Organization	xii
Introduction	xii
Protocol Parameter Types and Syntax	xii
Protocol Requests and Replies	xii
Pipeline Elements	xii
Events and Errors	xii
Techniques	xii
Service Classes	xii
Protocol Encodings	xii
Acknowledgments	xiii
Introduction	1-1
Scope and Purpose	1-1
Terminology	1-1
Techniques	1-1
Service Classes	1-1
Specification Syntax	2-1
General Syntax	2-1
Request Syntax	2-2
Requests without a Reply:	2-2
Requests with a Reply:	2-2
Syntax of Photo Elements	2-3
Photo Elements:	2-3
Syntax of Events	2-4
Events generated by Photo Elements:	2-4
Syntax of Errors	2-4
Core X errors	2-4
XIE non-Photoflo errors:	2-4
XIE Photoflo related errors:	2-4
Syntax of Protocol Encodings	2-5
Requests	2-5
Replies	2-5
PhotoElements	2-5
Events	2-6
Errors	2-6
Parameter Types	3-1
XIE and Core X Types	3-1
Techniques	3-1
Definitions	3-2
XieTypAlignment	3-2
XieTypArithmeticOp	3-2
XieTypColorAllocTechnique	3-3
XieTypColorList	3-3
XieTypCompareOp	3-3
XieTypConstant	3-4
XieTypConstrainTechnique	3-5
XieTypConvertFromRGBTechnique	3-5
XieTypConvertToRGBTechnique	3-5
XieTypConvolveTechnique	3-6
XieTypDataClass	3-6
XieTypDataStream	3-6
XieTypDataType	3-6
XieTypDecodeTechnique	3-7
XieTypDitherTechnique	3-7
XieTypEncodeTechnique	3-8
XieTypExecutable	3-8
XieTypExportNotify	3-9
XieTypExportState	3-9
XieTypFloat	3-9
XieTypGamutTechnique	3-10
XieTypGeometryTechnique	3-10
XieTypHistogramData	3-11
XieTypHistogramShape	3-11
XieTypInterleave	3-11
XieTypLevels	3-12
XieTypLUT	3-12
XieTypMathOp	3-12
XieTypMatrix	3-12
XieTypOrientation	3-13
XieTypPhotoElement	3-14
XieTypPhotoflo	3-14
XieTypPhotofloOutcome	3-14
XieTypPhotofloState	3-15
XieTypPhotomap	3-15
XieTypPhotospace	3-15
XieTypPhototag	3-15
XieTypProcessDomain	3-16
XieTypRectangle	3-16
XieTypROI	3-16
XieTypServiceClass	3-17
XieTypTechniqueGroup	3-17
XieTypTechniqueRec	3-18
XieTypTile	3-18
XieTypTripletoftype	3-18
XieTypWhiteAdjustTechnique	3-19
Resources	4-1
Overview	4-1
Binding Resources to Photoflos	4-1
ColorList resources	4-1
LUT, Photomap, and ROI resources	4-1
Resource destruction	4-2
Synchronizing resource access	4-2
Capability Acquisition	4-3
QueryImageExtension	4-3
Technique Acquisition	4-4
QueryTechniques	4-4
ColorList	4-5
CreateColorList	4-5
DestroyColorList	4-5
PurgeColorList	4-6
QueryColorList	4-6
LUT	4-7
CreateLUT	4-7
DestroyLUT	4-7
Photomap	4-8
CreatePhotomap	4-8
DestroyPhotomap	4-8
QueryPhotomap	4-9
ROI	4-10
CreateROI	4-10
DestroyROI	4-10
Pipelined Processing	5-1
What is a Photoflo?	5-1
Two kinds of Photoflos	5-2
Multi-client Photoflos	5-2
Photoflo States	5-3
Flo'ing Data to a Resource	5-3
Name space	5-4
CreatePhotospace	5-4
DestroyPhotospace	5-4
Immediate Photoflos	5-5
ExecuteImmediate	5-5
Stored Photoflos	5-6
CreatePhotoflo	5-6
DestroyPhotoflo	5-6
ExecutePhotoflo	5-7
ModifyPhotoflo	5-8
RedefinePhotoflo	5-8
Sending Data to the Server	5-9
PutClientData	5-9
Retrieving Data from the Server	5-10
GetClientData	5-10
Status	5-11
QueryPhotoflo	5-11
Synchronization	5-12
Await	5-12
Termination	5-12
Abort	5-12
Import Elements	6-1
Overview	6-1
Element categories	6-1
Multi-source images	6-1
Events generated	6-1
Import from Client	6-1
ImportClientLUT	6-2
ImportClientPhoto	6-3
ImportClientROI	6-4
Import from Resource	6-5
ImportDrawable	6-5
ImportDrawablePlane	6-6
ImportLUT	6-7
ImportPhotomap	6-8
ImportROI	6-9
Process Elements	7-1
Overview	7-1
Limiting the Process	7-1
Process Selected Bands	7-1
Process Intersecting Pixels	7-1
Process Selected Pixels	7-2
Data Types	7-2
Process Categories	7-3
Process Definitions	7-3
Arithmetic	7-4
BandCombine	7-5
BandExtract	7-6
BandSelect	7-7
Blend	7-8
Compare	7-9
Constrain	7-11
ConvertFromIndex	7-12
ConvertFromRGB	7-13
ConvertToIndex	7-14
ConvertToRGB	7-15
Convolve	7-16
Dither	7-17
Geometry	7-18
Logical	7-20
MatchHistogram	7-22
Math	7-23
PasteUp	7-24
Point	7-25
Unconstrain	7-26
Export Elements	8-1
Element categories	8-1
Export to Client	8-1
Events generated	8-1
ExportClientHistogram	8-2
ExportClientLUT	8-3
ExportClientPhoto	8-4
ExportClientROI	8-5
Export to Resource	8-6
ExportDrawable	8-6
ExportDrawablePlane	8-7
ExportLUT	8-8
ExportPhotomap	8-9
ExportROI	8-10
Events and Errors	9-1
Events	9-1
ColorAlloc	9-1
DecodeNotify	9-2
ExportAvailable	9-2
ImportObscured	9-3
PhotofloDone	9-3
Resource Errors	9-4
Photoflo errors	9-5
Techniques	A-1
Standard and Private Techniques	A-1
Technique numbers	A-1
Technique names	A-1
Default Techniques	A-2
Technique parameters	A-2
Technique information	A-2
Color Allocation Techniques	A-3
Constrain Techniques	A-4
Convert From RGB	A-5
Convert To RGB	A-6
Convolution Edge Techniques	A-8
Decode Techniques	A-9
Dithering Techniques	A-13
Encode Techniques	A-14
Gamut Compression Techniques	A-18
Geometry Techniques	A-19
Histogram Shapes	A-27
White Point Adjustment Techniques	A-28
Service Class	B-1
Full	B-1
DIS	B-1
Service Class Summary	B-2
Protocol Encodings	C-1
Extension Name	C-1
Types	C-1
Requests and Replies	C-9
Import Elements	C-15
Process Elements	C-17
Export Elements	C-22
Technique Parameters	C-24
Events	C-32
Errors	C-34
Figures and Tables
Figure 1-1   Service Classes defined in this document	1-2
Figure 4-1   Creating and populating a new Photomap	4-1
Figure 4-2   Process image from Photomap a, place result into Photomap b	4-2
Figure 4-3   Process image from Photomap a "in-place\	4-2
Figure 5-1   Photoflo element input and output connections	5-1
Figure 5-2   Example Photoflo	5-2
Figure 5-3   Photoflo states	5-3
Figure 7-1   Combining two sources using a control plane - Logical:  NoOp	7-2
Figure 7-2   A sample geometric transform: crop and scale	7-18
Figure 7-3   Background fill used for pixels beyond the edge	7-19
Figure 7-4   Point's algorithm for computing combined LUT indices	7-25
Figure A-1   Diagram of the ErrorDiffusion algorithm	A-13
Figure A-2   Effect of sampling technique when scaling to a lower pixel density	A-20
Figure A-3   Illustration of an output pixel mapping back to the input image	A-21
Figure A-4   Sequence producing an antialiased image using a low-pass filter	A-22
Figure B-1   DIS sources, operators, and destinations	B-1

Table 3-1   Technique naming and numbering conventions	3-1
Table 3-2   Treatment of floating point parameters passed through the protocol	3-4
Table 5-1   Examples of two element Photoflo usage	5-3
Table 6-1   Relationship between LUT class and image class	6-2
Table 7-1   Compare parameter and DataClass dependencies	7-9
Table 9-1   XIE Error codes	9-4
Table 9-2   Photoflo error sub-codes	9-5
Table B-1   Types itemized by ServiceClass	B-2
Table B-2   Techniques itemized by ServiceClass	B-4
Table B-3   Requests itemized by ServiceClass	B-5
Table B-4   Import elements itemized by ServiceClass	B-6
Table B-5   Process elements itemized by ServiceClass	B-6
Table B-6   Export elements itemized by ServiceClass	B-6
Table B-7   Events itemized by ServiceClass	B-7
Table B-8   Errors itemized by ServiceClass	B-7




Preface
The X architecture was a major step towards defining open, interactive application display services. X 
pried apart the tightly coupled, private interconnect which has existed between application and display 
subsystem by specifying a minimal, structured service set.
To retain a consistent, minimal core service set and yet accommodate evolving application require-
ments, X provides a method for extending the core protocol with additional domain specific requests. 
This document defines an X extension for the imaging domain.  It is the fifth version of the X Image 
Extension Protocol proposal and, as prior readers will immediately recognize, it is a lineal descendent of 
the other four. 
Since the purpose of this document is to provide a clear, concise articulation of the protocol, expository 
materials have been pared to a bare minimum.  It is assumed that the reader has a measure of conceptual 
knowledge about imaging. 
Readers who lack familiarity with the X Window System are encouraged to begin with a selection from 
the related documents given below. 
Related Documents
  X Window System (Scheifler & Gettys)
The complete reference to Xlib, X protocol (and extension conventions), ICCCM, XLFD.
Digital Press
  X Protocol Reference Manual (Nye, editor)
The Definitive Guides to the X Window System, Volume 0.
O'Reilly & Associates, Inc.
  The X Window System Server (Israel & Fortune)
Guide to the MIT X sample server: architecture, porting and tuning, writing extensions.
Digital Press
  XIE Sample Implementation Architecture (Shelley, Verheiden & Fahy)
An overview of the architecture of the XIE sample implementation.
AGE Logic, Inc.
  XIElib Specification (Rogers)
Reference pages for the XIE client library functions.
AGE Logic, Inc.


Participants
Authors: 
Robert NC Shelley 	shelley@age.com
Robert W. Scheifler 	rws@x.org
Ben Fahy 	jbenfahy@netcom.com
Jim Fulton 	jim@ncd.com
Keith Packard4	keithp@ncd.com
Joe Mauro 	mauro@optic.enet.dec.com
Richard Hennessy 	rich_hennessy@mac.avid.com
Tom Vaughan5	vaughan@edwin.enet.dec.com 
Contributors: 
Gary Grebus5
Larry Hare1
Peter Kaczowka 
Jeffrey Siegal 
Al Tabayoyon 
John Weber 
Revision History
rev v1.0	August 1, 1988 first protocol draft
rev v2.0	April 12, 1989 major changes based upon consortia review
rev v2.1	November 1, 1989 changes based upon FT1 implementation
rev v2.2	March 15, 1990 changes based upon FT2 implementation (pipes)
rev v3.0	October 1, 1990 changes in preparation for consortia review
rev v4.0	June 1, 1991 changes based upon consortia technical review
rev v4.08	May 29, 1992 preliminary imagework review copy
rev v4.09	June 9, 1992 imagework review copy for meeting at San Jose
rev v4.10	September 10, 1992 pre-review of encodings and contributions
rev v4.11	October 31, 1992 imagework review with initial definition of DIS
rev v4.12	December 23, 1992 initial Public Review copy
rev v4.13	May 19, 1993 changes made during Alpha phase of sample implementation
rev v4.14	October 20, 1993 changes made during Beta phase of sample implementation
rev v4.15	December 15, 1993 changes made prior to final release of sample implementation
rev V5.0	January 10, 1994 final draft
rev V5.0	April 1, 1994 cosmetic cleanup prior to releasing X11 R6


Organization
This document is organized into the following chapters and appendices:
Introduction
Chapter 1	explains the purpose of the X Image Extension.
Protocol Parameter Types and Syntax
Chapter 2	defines protocol syntax (how the protocol is encoded on the wire).
Chapter 3	defines types for protocol parameters.
Protocol Requests and Replies
Chapter 4	describes the resources used by the extension.
Chapter 5	describes pipelines, client data transport, and pipeline utility requests.
Pipeline Elements
Chapter 6	describes pipeline elements used for data import.
Chapter 7	describes the general processing elements used in pipelines.
Chapter 8	describes pipeline elements used for data export.
Events and Errors
Chapter 9	describes events and errors returned from XIE.
Techniques
Appendix A	describes the XIE standard techniques and their parameters.
Service Classes
Appendix B	summarizes required, optional, and excluded items for each XIE service class. 
Protocol Encodings
Appendix C	presents the complete protocol encoding for all XIE: types, requests, replies, ele-
ments, techniques, events, and errors.


Acknowledgments
We are all indebted to Digital Equipment Corporation where the X Image Extension was originally 
conceived.  They persevered through numerous protocol reviews and revisions and provided the initial 
sample implementations.  Their efforts contributed greatly towards promoting XIE into the Public Re-
view process. 
This document evolved from original specifications authored by Joe Mauro.  We hope that it still shows 
some of his architectural strength and elegance.  The majority of the current document (through version 
4.11) was authored by Bob Shelley while employed at Digital.  Subsequent revisions were made at AGE 
Logic.
The current view of pipelines emerged almost completely intact from a single, terse email message from 
Bob Scheifler and Keith Packard. 
The need for robust geometric transforms was first promoted by Ben Fahy.  We are grateful that he has 
provided us with detailed documentation for the basic geometry element and several retrospective 
sampling algorithms. 
While one could debate that XIE is too big or too small, we can thank Jim Fulton for spearheading the 
effort to define a smaller gentler XIE, the Document Imaging Subset. 
























almost blank


 	AGE Logic, Inc.
 	X Consortium, Inc.
 	Visionary Software, Inc.
 	Network Computing Devices, Inc.
 	Digital Equipment Corporation
 	Avid Technology, Inc.
 	Hewlett-Packard Co.
 	Congruent Corporation
 	North Valley Research, Inc.
 	Big Time Software, Inc.



xii



1
Introduction
Scope and Purpose
This document specifies the X wire protocol for the X Image Extension (XIE).  It defines the syntax, 
structure, and semantics of XIE protocol elements.  It does not contain background material on imaging 
concepts which the protocol extension enables, nor does it contain any language specific bindings. 
Terminology
This specification contains a certain amount of descriptive terminology that is commonly used within 
the image processing community.  There is also parametric terminology that is used to describe the pa-
rameter types recognized by the core X protocol and the image extension protocol.  The image exten-
sion protocol types are defined in this document.
Techniques
For some XIE operations, there are several recognized algorithms or techniques which offer varying 
tradeoffs between quality of results and performance.  Also, in some cases, different techniques are re-
quired due to an image's class or content.  In order to accommodate some flexibility in this area, such 
XIE operations accept a technique parameter.  A description of the techniques specified in this docu-
ment can be found in Appendix A.  Individual implementations may extend XIE's capabilities by provid-
ing additional techniques to provide for particular market needs. 
Service Classes
For some environments, such as simple document image viewing, the full set of services provided by 
XIE may include features that are not needed by the target applications. In such situations (particularly 
for entry-level monochrome displays), server implementors may wish to provide only a subset of the full 
XIE protocol.
Subsets are arranged in a nested hierarchy of service classes.  Each service class includes all of the 
features of any subsets that it surrounds (similar to the layers of an onion).  Thus, applications written 
to use a given subset of the protocol will function correctly when running on servers that implement an 
enveloping service class.


This version of the XIE protocol defines two class: the full protocol (Full), and a document imaging 
subset (DIS).  Future versions of the XIE protocol may define additional service classes. 
 
Figure 1-1   Service Classes defined in this document
A complete list of types, techniques, protocol requests, pipeline elements, events, and errors that are 
included in DIS can be found in Appendix B.

Introduction   1-1


2
Specification Syntax
This section presents syntactic conventions which are adhered to throughout this specification. 
General Syntax
In general, the extension package follows the X11 protocol syntax conventions. Additions to this 
syntax are:
*	The syntax ( . . . ) encloses a set of alternative values.
*	The syntax [ . . . ] encloses a set of structure components.
*	Within definitions the following prefixes are used:
-	XieReq:	protocol request/reply	(e.g. XieReqCreatePhotoflo)
-	XieFlo:	Photoflo element	(e.g. XieFloConvolve)
-	XieEvn:	protocol event	(e.g. XieEvnPhotofloDone)
-	XieErr:	protocol error	(e.g. XieErrPhotospace)
-	XieTyp:	protocol type	(e.g. XieTypProcessDomain)
-	XieVal:	alternative value	(e.g. XieValBandByPixel)
*	Outside of definitions the prefixes are generally not used:
-	alternative values are italicized and bold	(e.g. BandByPixel)
-	all others are capitalized and bold	(e.g. CreatePhotoflo)
*	Core X types are displayed in upper-case	(e.g. COLORMAP, WINDOW)


Request Syntax
Requests without a Reply:
XieReqRequestName
arg-1	type-1	1st argument for RequestName
 . . .
arg-N	type-N	N-th argument for RequestName
Errors:	none or list of errors specific to RequestName (e.g. FloID)
Events:	none or list of events generated by RequestName (e.g. PhotofloDone)
Overview	describes the basic function of the request.
Parameters	lists the parameters and gives a brief description of each.
Semantics	interrelationships between input data, parameters, and output results.
Errors	table of errors that can be generated and their causes:
Error	Cause
error-1	circumstances that generate error-1
. . .	
error-N	circumstances that generate error-N
Requests with a Reply:
XieReqRequestName
arg-1	type-1	1st argument for RequestName
 . . .
arg-N	type-N	N-th argument for RequestName
*
result-1	type-1	1st reply result from RequestName
 . . .
result-M	type-M	M-th reply result from RequestName
Errors:	none or list of errors specific to RequestName (e.g. Photomap)
Events:	none or list of events generated by RequestName (e.g. EventName)
Overview	describes the basic function of the request.
Parameters	lists the parameters and gives a brief description of each.
Reply data	lists the parameters and gives a brief description of each.
Semantics	interrelationships between input data, parameters, and output results.
Errors	table of errors that can be generated and their causes:
Error	Cause
error-1	circumstances that generate error-1
. . .
error-N	circumstances that generate error-N
Syntax of Photo Elements
PhotoElements occur within XIE pipelines (see following chapters for clarification).  The syntax of these 
elements is shown below.
Photo Elements:
XieFloElementName
src-1	src-type-1	1st source for ElementName (if required)
 . . .
src-N	src-type-N	N-th source for ElementName (if required)
param-1	param-type-1	1st parameter for ElementName
 . . .
param-M	param-type-M	M-th parameter for ElementName
Errors:	none or list of errors specific to ElementName (e.g. FloAlloc)
Events:	none or list of events generated by ElementName (e.g. ExportAvailable)
Attributes	table of PhotoElement output attributes:
Attribute	Value
class	DataClass of output data
		SingleBand	achromatic or index
		TripleBand	trichromatic
type	DataType:
		Constrained	quantization levels is levels (integer data)
		Unconstrained	quantization levels is unknown (may be float data)
width	width  of output data (in pixels per band)
height	height of output data (in pixels per band)
levels	depends on type:
		Constrained	number of quantization levels (per band)
		Unconstrained	unknown
Overview	describes the basic function of the photo element.
Parameters	lists the parameters and gives a brief description of each.
Semantics	interrelationships between input data, parameters, and output results.
Errors	table of errors that can be generated and their causes:
Error	Cause
error-1	circumstances that generate error-1
. . .
error-N	circumstances that generate error-N


Syntax of Events
Events generated by Photo Elements:
XieEvnEventName
instance	XieTypExecutable	< Photoflo instance generating EventName >
phototag	XieTypPhototag	< event Phototag (0 for general Photoflo event) >
type	CARD16	< element type (0 for general Photoflo event) >
value-1	type-1	< 1st value returned by EventName >
 . . .		
value-N	type-N	< N-th value returned by EventName >
Overview	description of the event. 
Values returned	description of the values returned. 
Syntax of Errors
Errors can be associated with core X11 resources or XIE resources.  In the case of XIE specific error 
conditions, a distinction is made between errors related to a Photoflo and those that are not.
Core X errors
Normal X errors (with XIE major/minor opcodes) are used where appropriate (e.g. Alloc).
XIE non-Photoflo errors:
XieErrName
xie-error	XieErrName		< error code of Name, offset from first-error >
resource-id	XID		< resource to blame, e.g. Photomap >
detail			< 21 bytes available for additional error detail >
Overview	description of the error. 
Values returned	description of the values returned. 
XIE Photoflo related errors:
XieErrFloName
flo-error	XieErrName		< error code for Flo, offset from first-error >
flo-id	CARD32		< executable flo-id>
flo-code	XieErrFloName	< specific error type >
name-space	CARD32		< executable name-space>
phototag	CARD16		< erring Phototag (0 for general Photoflo error) >
type	CARD16	< element type (0 for general Photoflo error) >
detail			< 12 bytes available for additional error detail >

Overview	description of the error. 
Values returned	description of the values returned. 
Syntax of Protocol Encodings
Requests
# of Bytes	Value	Description
1	CARD8	XIE major opcode
1	CARD8	XIE minor opcode
2	CARD16	request length (total bytes divided by 4)
N		parameters required by the minor opcode
< 4		pad (if required)
Requests consist of four (4) bytes of header followed by zero (0) or more additional bytes of data.  If 
additional bytes of data are needed the entire request is padded to a multiple of four (4) bytes.  The 
common fields (major/minor opcode and length) are not included in XieReq request definitions.  Bytes 
not used by a specific minor opcode are not guaranteed to be zero.
Replies
# of Bytes	Value	Description
1	1	Reply
1		available for reply data
2	CARD16	sequence number of corresponding request
4	CARD32	reply length (extra data bytes divided by 4)
24		available for reply data
N		extra data beyond standard reply packet
< 4		pad (if required)
Replies consist of thirty-two (32) bytes followed by zero (0) or more extra bytes of data.  If extra bytes of 
data are needed the entire reply is padded to a multiple of four (4) bytes.  The common fields (Reply, 
sequence number, and length) are not included in XieReq reply definitions.  Bytes not used by the reply 
from a specific request are not guaranteed to be zero.
PhotoElements
# of Bytes	Value	Description
2	CARD16	element type
2	CARD16	element length (bytes divided by 4)
multiple of 2	XieTyp(Phototag|Tile)	element's data source(s) (if required)
N		parameters as required by element type
< 4		pad (if required)
A photo element consists of four (4) bytes of header, followed by zero (0) or more bytes of element in-
put connection definitions, followed by zero (0) or more bytes or additional data.  The entire element 
definition is padded to a multiple of four (4) bytes.  The common fields (element type and element 
length) are not included in XieFlo element definitions.  Bytes not used by a specific element type are 
not guaranteed to be zero.
Note: PhotoElements are not protocol requests, but rather sub-packets within another protocol request (i.e. 
ExecuteImmediate, CreatePhotoflo, ModifyPhotoflo, or RedefinePhotoflo). 
Events
# of Bytes	Value	Description
1	CARD8	XIE event code
1	<varies>	<event-specific>
2	CARD16	sequence number
4	TIMESTAMP	time
24	<varies>	<event-specific>
Events consist of thirty-two (32) bytes.  The common fields (event code, sequence number, and time) 
are not included in XieEvn definitions.  Bytes not used by a specific event code are not guaranteed to 
be zero. 
Errors
# of Bytes	Value	Description
1	0	Error
1	CARD8	XIE error code
2	CARD16	sequence number
4	<varies>	<error-specific (often a resource-id)>
2	CARD16	minor opcode
1	CARD8	major opcode
21	<varies>	<error-specific>
Errors consist of thirty-two (32) bytes.  Bytes not used by the specific error code are not guaranteed to 
be zero. 

Protocol Specification Syntax 2-6


3
Parameter Types
XIE and Core X Types
X Image Extension types are defined in this section.  All XIE parameters are defined as being either one of 
the extension types, or one of the core protocol types.  XIE makes use of the following core protocol types 
(defined in the X11 core protocol specification):
BITMAP	BOOL	CARD8	CARD16
CARD32	CHAR2B	COLORMAP	DRAWABLE
EVENT	GCONTEXT	INT8	INT16
INT32	PIXMAP	STRING8	TIMESTAMP
VISUAL	WINDOW	XID*
*  XID is used to refer to the core X11 type defined as the identifier for a resource.
Techniques
Several standard techniques are defined in this document.  Each is assigned a technique number and a de-
scriptive name string.  XIE can also be extended with private techniques that are implementation dependent.  
Private technique numbers are generated dynamically.  Private technique name strings include the name of 
the organization that defined the technique.  The organization name is encompassed by _ (underscore) 
characters.  Technique naming and numbering conventions are summarized in Table 3-1.


standard technique
private technique

name
<standard-technique-name>
example: ERROR-DIFFUSION
_<organization-name>_<private-technique-name>
example: _PHOTOCO_SQUASH-BITS

number
MS bit is zero (range: 0 - 32767)
MS bit is one (range: 32768 - 65535)

Table 3-1   Technique naming and numbering conventions
The technique number is supplied to pipeline elements to specify the desired technique.  Numbers for 
standard techniques can be hard-coded, whereas numbers for private techniques must be obtained using 
the QueryTechniques protocol request. 

For more information on techniques and a description of the techniques defined in this document, refer to Appendix A.  A 
list of techniques itemized by ServiceClass can be found in Appendix B.  Numbers assigned to standard techniques are encoded 
in Appendix C.
Definitions
XieTypAlignment
Alignment defines the valid pixel and scanline alignments allowed for image data transported through the 
protocol stream.  The server's Alignment attribute is returned by the QueryImageExtension protocol re-
quest.  
XieTypAlignment	{ XieValAlignable, XieValArbitrary }
*	Alignable	data units must fit evenly within a byte, or they must fill a byte, or fill a multiple
	of bytes (i.e. pixels may be 1, 2, 4, 8, 16, 24*, or 32* bits in the protocol stream).
*	Arbitrary	data units may fall at any bit address (i.e. 10 bit packed pixels are acceptable in
	the protocol stream). 
*	XIE supports pixels up to sixteen (16) bits per band for both SingleBand and TripleBand data.  In addition, 
SingleBand data are supported up to the depth of the deepest DRAWABLE supported by the server.


XieTypArithmeticOp
ArithmeticOp defines the valid operations for the Arithmetic process element. 
XieTypArithmeticOp	{	XieValAdd,
	XieValSub, XieValSubRev,
	XieValMul,
	XieValDiv, XieValDivRev,
	XieValMin, XieValMax,
	XieValGamma }
*	Add	src1 + src2	or  src1 + constant
*	Sub	src1 - src2	or  src1 - constant
*	SubRev	src2 - src1	or  constant - src1
*	Mul	src1 * constant
*	Div	src1 / constant
*	DivRev	constant / src1
*	Min	minimum( src1, src2 ) 	or  minimum( src1, constant )
*	Max	maximum( src1, src2 ) 	or  maximum( src1, constant )
*	Gamma	if src1 is Constrained	(levels - 1) * ((src1 / (levels - 1))constant)
	if src1 is Unconstrained	src1constant



XieTypColorAllocTechnique
ColorAllocTechnique defines the recognized color allocation techniques used by the ConvertToIndex 
element. 
XieTypColorAllocTechnique	{	XieValDefault,
XieValColorAlloc_AllocAll,
XieValColorAlloc_Match,
XieValColorAlloc_Requantize }
*	Default
ColorAlloc_AllocAll	ALLOC-ALL
ColorAlloc_Match	MATCH
ColorAlloc_Requantize	REQUANTIZE
private-technique-number	private-name-string
*	The server is required to support the Default technique which is bound to one of the standard techniques defined above or 
a private technique.

XieTypColorList
ColorList is the type for the XIE resource used to store COLORMAP allocations made by the ConvertTo-
Index element.  A ColorList is a permanent resource and as such must be created and destroyed by the 
client.  A ColorList contains a counted list of the pixel indices that were allocated, and the resource-id of the 
COLORMAP from which they were allocated. 
XieTypColorList	XID

XieTypCompareOp
CompareOp defines the operators for the Compare element. 
XieTypCompareOp	{	XieValLT,	XieValLE,
XieValEQ,	XieValNE,
XieValGT,	XieValGE }
*	LT		src1 <  src2	or  src1 < constant
*	LE		src1  src2	or  src1  constant
*	EQ		src1 = src2	or  src1 = constant
*	NE		src1  src2	or  src1  constant
*	GT		src1 > src2	or  src1 > constant
*	GE		src1  src2	or  src1  constant


XieTypConstant
Constant is typically used to supply per-band constant values.  All constants are passed as floats.  When a 
constant is to be used as a substitute for a Constrained image pixel, the constant is rounded to the nearest 
integer, and then hard-clipped to the range of levels that applies to the pixel for which it is a substitute.  In 
most other cases the constant is used as is (i.e. as a float).
XieTypConstant	XieTypTripletofXieTypFloat

Element	Op/arg/Tech	Type	Usage	If Constrained 
					
Arithmetic	Add	Constant	pixel value when monadic	round/hard-clip
	Sub	Constant	pixel value when monadic	round/hard-clip
	SubRev	Constant	pixel value when monadic	round/hard-clip
	Min	Constant	pixel value when monadic	round/hard-clip
	Max	Constant	pixel value when monadic	round/hard-clip
	Mul	Constant	multiplicand	use as is
	Div	Constant	divisor	use as is
	DivRev	Constant	dividend	use as is
	Gamma	Constant	exponent	use as is

BandExtract	coefficients	Constant	multipliers	use as is
	bias	Float	final offset	use as is

Blend	constant	Constant	pixel value when monadic	round/hard-clip
	alpha-constant	Float	constant alpha value	use as is

Compare	constant	Constant	pixel value when monadic	round/hard-clip

Constrain	ClipScale	Constant	scale src levels to dst levels 	use as is

Convert From/To RGB	CIElab	Matrix	conversion matrix	use as is
	CIElabShift	Constant	white-point	use as is
	CIEXYZ	Matrix	conversion matrix	use as is
	YCbCr	Constant	luma values and bias	use as is
	YCC	Constant	luma values	use as is
	YCC	Float	scale	use as is

ConvertToIndex	Match	Float	match-limit, gray-limit	use as is

Convolve	kernel	LISTofFloat	convolution kernel	use as is
	Constant	Constant	edge pixel value	round/hard-clip

Geometry	a,b,c,d,tx,ty	Float	coefficients [6]	use as is
	constant	Constant	fill pixel value	round/hard-clip
	Gaussian 	Float	sigma, normalize	use as is

Logical	constant	Constant	pixel value when monadic	round/hard-clip

MatchHistogram	Gaussian	Float	mean, sigma	use as is
	Hyperbolic	Float	constant	use as is

PasteUp	constant	Constant	fill pixel value	round/hard-clip

Table 3-2   Treatment of floating point parameters passed through the protocol


XieTypConstrainTechnique
ConstrainTechnique defines various methods of constraining data.  These techniques are applied by the 
Constrain element. 
XieTypConstrainTechnique	{	XieValConstrain_ClipScale,
XieValConstrain_HardClip }
Constrain_ClipScale	CLIP-SCALE
Constrain_HardClip	HARD-CLIP
private-technique-number	private-name-string

XieTypConvertFromRGBTechnique
ConvertFromRGBTechnique defines the trichromatic colorspaces known to the ConvertFromRGB element. 
XieTypConvertFromRGBTechnique	{	XieValConvertFromRGB_CIELab,
XieValConvertFromRGB_CIEXYZ,
XieValConvertFromRGB_YCbCr,
XieValConvertFromRGB_YCC }
ConvertFromRGB_CIELab	CIELAB
ConvertFromRGB_CIEXYZ	CIEXYZ
ConvertFromRGB_YCbCr	YCbCr
ConvertFromRGB_YCC	YCC
private-technique-number	private-name-string

XieTypConvertToRGBTechnique
ConvertToRGBTechnque defines the trichromatic colorspaces known to the ConvertToRGB element. 
XieTypConvertToRGBTechnique	{	XieValConvertToRGB_CIELab,
XieValConvertToRGB_CIEXYZ,
XieValConvertToRGB_YCbCr,
XieValConvertToRGB_YCC }
ConvertToRGB_CIELab	CIELAB
ConvertToRGB_CIEXYZ	CIEXYZ
ConvertToRGB_YCbCr	YCbCr
ConvertToRGB_YCC	YCC
private-technique-number	private-name-string


XieTypConvolveTechnique
ConvolveTechnique provides various methods of handling edge conditions in the Convolve element.  This 
technique determines what pixel values are used when Convolve requires data beyond the image bounds. 
XieTypConvolveTechnique	{	XieValDefault,
XieValConvolve_Constant,
XieValConvolve_Replicate }
*	Default
Convolve_Constant	CONSTANT
Convolve_Replicate	REPLICATE
private-technique-number	private-name-string
*	The server is required to support the Default technique which is bound to one of the standard techniques defined above or 
a private technique.

XieTypDataClass
DataClass defines the class of data being transported over the wire. 
XieTypDataClass	{	XieValSingleBand,
XieValTripleBand }
*	SingleBand	index data (e.g. ZPixmap format COLORMAP indices), or
achromatic data (bitonal or gray-scale)
*	TripleBand	non-index trichromatic data (RGB or other supported colorspaces)

XieTypDataStream
DataStream is a segmented stream of data units that are transported in either direction through the protocol 
stream.  Segments of image data are transported as an arbitrary number of unsigned bytes, whereas all other 
types of data (e.g. lookup table entries, rectangles, histogram counts, etc.) must be transported as one or 
more complete aggregates.  The status indicating the eventual end of data, is supplied in the associated 
protocol request or reply.  The interpretation of the data stream is determined by parameters specified to the 
PhotoElement accepting or generating the data. 
XieTypDataStream		LISTofCARD8

XieTypDataType
DataType defines the limits and processing model for the data. 
XieTypDataType	{	XieValConstrained,
XieValUnconstrained }
*	Constrained	pixels are integer values and are limited to the range [0, levels-1]
*	Unconstrained	pixels may be any arbitrary value


XieTypDecodeTechnique
DecodeTechnique defines the techniques that can be used to interpret uncompressed image data or decode 
compressed images.
XieTypDecodeTechnique	{	XieValDecode_UncompressedSingle,
XieValDecode_UncompressedTriple,
XieValDecode_CCITT-G31D,
XieValDecode_CCITT-G32D,
XieValDecode_CCITT-G42D,
XieValDecode_JPEG-Baseline,
XieValDecode_JPEG-Lossless,
XieValDecode_TIFF-2,
XieValDecode_TIFF-PackBits }
Decode_UncompressedSingle	UNCOMPRESSED-SINGLE
Decode_UncompressedTriple	UNCOMPRESSED-TRIPLE
Decode_CCITT-G31D	CCITT-G31D
Decode_CCITT-G32D	CCITT-G32D
Decode_CCITT-G42D	CCITT-G42D
Decode_JPEG-Baseline	JPEG-BASELINE
Decode_JPEG-Lossless	JPEG-LOSSLESS
Decode_TIFF-2	TIFF-2
Decode_TIFF-PackBits	TIFF-PACKBITS
private-technique-number	private-name-string

XieTypDitherTechnique
DitherTechnique defines the techniques that can be used to dither an image. 
XieTypDitherTechnique	{	XieValDefault,
XieValDither_ErrorDiffusion,
XieValDither_Ordered }
*	Default
Dither_ErrorDiffusion	ERROR-DIFFUSION
Dither_Ordered	ORDERED
private-technique-number	private-name-string
*	The server is required to support the Default technique which is bound to one of the standard techniques defined above or 
a private technique.


XieTypEncodeTechnique
EncodeTechnique defines the techniques that can be used to compress an image or format it as uncom-
pressed data. 
XieTypEncodeTechnique	{	XieValEncode_ServerChoice,
XieValEncode_UncompressedSingle,
XieValEncode_UncompressedTriple,
XieValEncode_CCITT-G31D,
XieValEncode_CCITT-G32D,
XieValEncode_CCITT-G42D,
XieValEncode_JPEG-Baseline,
XieValEncode_JPEG-Lossless,
XieValEncode_TIFF-2,
XieValEncode_TIFF-PackBits }
Encode_ServerChoice	(not returned by QueryTechniques)
Encode_UncompressedSingle	UNCOMPRESSED-SINGLE
Encode_UncompressedTriple	UNCOMPRESSED-TRIPLE
Encode_CCITT-G31D	CCITT-G31D
Encode_CCITT-G32D	CCITT-G32D
Encode_CCITT-G42D	CCITT-G42D
Encode_JPEG-Baseline	JPEG-BASELINE
Encode_JPEG-Lossless	JPEG-LOSSLESS
Encode_TIFF-2	TIFF-2
Encode_TIFF-PackBits	TIFF-PACKBITS
private-technique-number	private-name-string

XieTypExecutable
Executable is the type used to identify a specific Photoflo instance. 
XieTypExecutable
[	name-space	ServerIDSpace	or	XieTypPhotospace
	flo-id	XieTypPhotoflo	or	CARD32
]
Name-space identifies the execution domain used for a Photoflo.  Flo-id identifies a particular instance of a 
Photoflo.
For stored Photoflos name-space is always ServerIDSpace (the value zero) and flo-id is the Photo-
flo's resource-id. 
For immediate Photoflos name-space is a Photospace resource-id and flo-id  is a thirty-two (32) bit value 
that uniquely identifies the instance of the Photoflo within name-space. 


XieTypExportNotify
ExportNotify is used by ExportClient elements to control how ExportAvailable events are sent to the 
client.
XieTypExportNotify	{	XieValDisable
XieValFirstData
XieValNewData }
*	Disable	no events are sent
*	FirstData	a single event is sent when the first data is available
*	NewData	an event is sent each time the amount of available data changes from zero to non-zero

The end of data is signaled by a final flag in the GetClientData reply that is returned when the last segment of data is re-
trieved. 

XieTypExportState
ExportState is a status value returned from an ExportClient element in a reply to the corresponding 
GetClientData protocol request. 
XieTypExportState	{	XieValExportDone,
XieValExportMore,
XieValExportEmpty,
XieValExportError }
*	ExportDone	all data have been retrieved
*	ExportMore	more data currently available
*	ExportEmpty	no more data available at this time
*	ExportError	an error condition prevents data availability

XieTypFloat
Float specifies data is in the IEEE single-precision format as described in ANSI/IEEE  Standard 754-1985, 
IEEE Standard for Binary Floating-Point Arithmetic.  Float is used only for constant parameter values, 
matrix coefficients, etc., but never for transported image data.  The byte order of each Float is dealt with in 
the same manner as other numeric values; it is determined at core protocol connection setup time.


XieTypGamutTechnique
GamutTechnique defines the gamut compression techniques used by ConvertToRGB to deal with con-
verted colors which lie outside the gamut of the RGB space. 
XieTypGamutTechnique	{	XieValDefault,
XieValGamut_None,
XieValGamut_ClipRGB }
*	Default
Gamut_None	NONE
Gamut_ClipRGB	CLIP-RGB
private-technique-number	private-name-string
*	The server is required to support the Default technique which is bound to one of the standard techniques defined above or 
a private technique.

XieTypGeometryTechnique 
GeometryTechnique defines the retrospective image re-sampling techniques used by the Geometry element.
XieTypGeometryTechnique	{	XieValDefault,
XieValGeometry_Antialias,
XieValGeometry_AntialiasByArea,
XieValGeometry_AntialiasByLowpass,
XieValGeometry_BilinearInterpolation,
XieValGeometry_Gaussian,
XieValGeometry_NearestNeighbor }
*	Default
Geometry_Antialias	ANTIALIAS
Geometry_AntialiasByArea	ANTIALIAS-BY-AREA
Geometry_AntialiasByLowpass	ANTIALIAS-BY-LOWPASS
Geometry_BilinearInterpolation	BILINEAR-INTERPOLATION
Geometry_Gaussian	GAUSSIAN
Geometry_NearestNeighbor	NEAREST-NEIGHBOR
private-technique-number	private-name-string
*	The server is required to support the Default technique which is bound to one of the standard techniques defined above or 
a private technique.


XieTypHistogramData
HistogramData defines the organization of histogram entries created by the ExportClientHistogram 
element.
XieTypHistogramData
[	value	CARD32	
	count	CARD32	
]

XieTypHistogramShape
HistogramShape defines the various match-histogram shape techniques that can be requested in the 
MatchHistogram element. 
XieTypHistogramShape	{	XieValHistogram_Flat,
XieValHistogram_Gaussian,
XieValHistogram_Hyperbolic }
Histogram_Flat	FLAT
Histogram_Gaussian	GAUSSIAN
Histogram_Hyperbolic	HYPERBOLIC
private-technique-number	private-name-string

XieTypInterleave
Interleave defines the way in which bands of TripleBand data may be interleaved. 
XieTypInterleave	{	XieValBandByPixel,
XieValBandByPlane }
*	BandByPixel	the data for all bands are interleaved on a per-pixel basis and transmitted as a single data plane 
(e.g. for RGB data red, green, and blue values for a given pixel are immediately followed by the 
red, green, and blue values for the next pixel). BandByPixel is similar to the core protocol 
ZPixmap format.
*	BandByPlane	the data for each band are transmitted as separate data planes (e.g. for RGB data all red data are 
transmitted in one plane, all green data in a separate plane, and all blue data in another plane).

Interleave is generally used in conjunction with Orientation, which would define the order of the interleaved bands.


XieTypLevels 
Levels describes the potential dynamic range for the quantization levels associated with each band of an 
image. 
XieTypLevels	XieTypTripletofCARD32
	Note: for Constrained image data a value of zero (0) represents 232 (4,294,967,296) levels. 

XieTypLUT
LUT is the type for the XIE server resource used to hold arrays which map one set of values to another. The 
arrays are one-dimensional, and the resource holds either one or three arrays.  The ImportClientLUT and 
ImportLUT elements are used to import LUT data into a Photoflo, the Point element uses the data, the 
ExportLUT element is used to (re)populate the LUT resource, and the ExportClientLUT element is provided 
to facilitate sending the LUT data back to the client.
XieTypLUT	XID

XieTypMathOp
MathOp defines the valid mathematical operations that can be invoked through the Math element.  The 
MathOp is applied to each input pixel value to determine the output pixel value.
XieTypMathOp	{	XieValExp,	XieValLn,
XieValLog2,	XieValLog10,
XieValSquare,	XieValSqrt }
*	Exp	exponential
*	Ln		natural logarithm
*	Log2	logarithm base 2
*	Log10	logarithm base 10
*	Square	square
*	Sqrt	square root

XieTypMatrix
Matrix is a 3 x 3 matrix of floats that is used by some of the colorspace conversion techniques (e.g. con-
version between RGB and CIE colorspaces). 
XieTypMatrix	XieTypTripletofXieTypConstant


XieTypOrientation
Orientation defines the transmission order of image data units through the protocol stream.
XieTypOrientation	{	XieValLSFirst, XieValMSFirst }
Note: in the examples that follow, the order of bytes in the DataStream should be read from left to right.

encoded-order	Specifies the order of bits within bytes of encoded (compressed) data. 
Example:  showing 2 bytes (within each byte the first encoded bit is 0, last is bit 7)

LSFirst
MSFirst


76543210  76543210
01234567  01234567

fill-order	When multiple pixels are put in the same byte, or a pixel spans multiple bytes, fill-order 
specifies whether the pixels (or parts of a pixel) are packed into the most or least 
significant bits of a byte first.
Example:	showing 8 2-bit pixels (aa, bb, cc, etc.),  and 2 10-bit pixels: aaaaaaaaaa 
and bbbbbbbbbb)

LSFirst
MSFirst


ddccbbaa  hhggffee
aabbccdd  eeffgghh


aaaaaaaa  bbbbbbaa  xxxxbbbb
aaaaaaaa  aabbbbbb  bbbbxxxx

pixel-order	For pixels that span a byte boundary, pixel-order specifies whether the most or least 
significant bits of the pixel are put into the DataStream first.  Any pad bits that are 
present between pixels always follow the pixel data (i.e. pad bits are not considered to be 
either LS-bits or MS-bits of the pixel data).
Example: 	showing 2 10-bit pixels, each with 2 bits of pad  (within each pixel the LS-bits 
are 0 and a, the MS-bits are 9 and j, the pad bits are p)
fill-order
LSFirst (pixel-order)
MSFirst (pixel-order)

LSFirst
76543210  dcbapp98  ppjihgfe
98765432  jihgpp10  ppfedcba

MSFirst
76543210  98ppdcba  jihgfepp
98765432  10ppjihg  fedcbapp

band-order	Definition: at the protocol level, the least significant band of trichromatic data is the first 
band mentioned in the common name of the colorspace (e.g. red is the least significant 
band of RGB data).
	For BandByPixel data, band-order specifies whether this band is put in the least or most 
significant bits of a pixel.

LSFirst
MSFirst


B1B0G2G1G0R2R1R0
R2R1R0G2G1G0B1B0

	For BandByPlane data, band-order specifies whether this band corresponds with the 
least significant or most significant image plane.  Each plane is transported as a separate 
DataStream.
band
LSFirst
MSFirst

0
R7R6R5R4R3R2R1R0
B7B6B5B4B3B2B1B0

1
G7G6G5G4G3G2G1G0
G7G6G5G4G3G2G1G0

2
B7B6B5B4B3B2B1B0
R7R6R5R4R3R2R1R0

	For all other instances where a triplet of per-band information is conveyed  through the 
protocol (levels, constants, etc.), the first element of the triplet  corresponds with the 
least significant band as defined above.
XieTypPhotoElement
PhotoElement, or just element, is a generic type used for import, process, or export elements in a Photoflo.  
The syntax of a generic element was described in Chapter 2.  The actual element definitions are found in 
Chapters 6, 7, and 8.

XieTypPhotoflo 
Photoflo is the type for the XIE server resource which is used to represent a sequence of image processing 
operations. Stored Photoflos are permanent resources. As such they must be created and destroyed by 
the client.
XieTypPhotoflo	XID
For immediate Photoflos, see type Photospace and the ExecuteImmediate protocol request.

XieTypPhotofloOutcome
PhotofloOutcome is returned by the PhotofloDone event and indicates the reason why the Photoflo left the 
Active state. 
XieTypPhotofloOutcome	{	XieValFloSuccess, 
XieValFloError, 
XieValFloAbort }
*	FloSuccess	the Photoflo completed normally
*	FloError	the Photoflo terminated due to an error condition
*	FloAbort	the Photoflo was aborted by the client


XieTypPhotofloState
PhotofloState identifies the current execution state of a Photoflo.
XieTypPhotofloState	{	XieValInactive, 
XieValActive, 
XieValNonexistent }
*	Inactive	the state of a stored Photoflo prior to execution, after an error or abort, or after execution 
completes. Inactive stored Photoflos can be modified and redefined.
*	Active	the state of a stored or immediate Photoflo during execution.
		A Photoflo remains Active until:
			- all export elements have finished their task, and
			- all data exported for the client have been retrieved, or
			- an error prevents further progress, or
			- the client issues an abort request.  
*	Nonexistent	the state of a Photoflo that does not exist (never existed or has been destroyed).

XieTypPhotomap
Photomap is the type for the XIE resource used to store image data in the server.  A Photomap is a per-
manent resource that can be created and destroyed by the client.  ImportPhotomap is used to import per-
manent image data into a Photoflo.  ExportPhotomap is used to (re)populate the resource. 
XieTypPhotomap	XID

XieTypPhotospace
Photospace is the type for the XIE resource used to define a XIE name space within which immediate 
Photoflos may be executed. A Photospace is a permanent resource and as such must be created and de-
stroyed  by the client. 
XieTypPhotospace	XID

XieTypPhototag
Phototag is the position or index of a PhotoElement within a list of elements used to specify a Photoflo. The 
first element in the list has a Phototag value of one (1).  A Phototag value of zero (0) is reserved for special 
purposes, such as indicating an optional element input that is not connected, or indicating Photoflo errors 
that are not specific to an element. 
XieTypPhototag		CARD16
XieTypProcessDomain
ProcessDomain is a sub-structure inserted in many PhotoElement definitions.  It is used to restrict the 
element's processing to a subset of the source data pixels.  A ProcessDomain can be either a list-of-
rectangles or a control-plane. 
XieTypProcessDomain
[	offset-x	INT32
offset-y	INT32
domain	XieTypPhototag
]
Offset-x and offset-y specifies the spatial registration between the element's data source(s) and the 
ProcessDomain (i.e. offset relative to the origin of the source(s)).  Domain is the Phototag of the element 
providing the ProcessDomain data.
If the value zero (0) is specified for domain, processing is not restricted by the processing domain, other-
wise, domain references an element outputting a list-of-rectangles or image data which is used as a control-
plane. 
If domain is a list-of-rectangles, processing is restricted to the intersection of the data source(s) and any 
rectangle within the list (offset-x and offset-y are added to the x and y of each rectangle). 
If domain is a source of Constrained, SingleBand, bi-level image data (i.e. a control-plane), processing is 
restricted to the intersection of the data source(s) and non-zero locations within domain. 
ProcessDomain is not supported by DIS but is included in the subset because the Point element takes a 
ProcessDomain as a parameter (in this case domain must be zero). 

XieTypRectangle
Rectangle describes a rectangle used in XieTypROI. 
XieTypRectangle
[	x	INT32
y	INT32
width	CARD32
height	CARD32
]
X and y are the coordinates of the upper left hand corner of the rectangle within the ProcessDomain (the 
domain's x,y offset is also added to these coordinates to position the rectangle relative to the image being 
processed).  Width and height are the extent of the rectangle.

XieTypROI
ROI (Rectangles-Of-Interest) is the XIE resource used to contain a list-of-rectangles (input for a 
ProcessDomain).  A ROI resource is a permanent resource and as such must be created and destroyed by 
the client.  ImportClientROI and ImportROI elements are used to import a list-of-rectangles into a Photoflo, 
the ExportROI element is used to (re)populate an ROI resource, and the ExportClientROI element is 
provided to facilitate sending rectangles back to the client *.
XieTypROI	XID
*	The list-of-rectangles that can be retrieved by the client need not be identical to the original list that was received from 
the client, but it must be logically equivalent.
XieTypServiceClass
ServiceClass defines the recognized image processing service sets supported by this X Image Extension 
standard.
XieTypServiceClass	{ XieValFull, XieValDIS }
*	Full	supports the entire XIE protocol as defined in this document
*	DIS	supports the Document Image Subset, a proper subset of Full XIE
An itemized list of XIE types, techniques, protocol requests, elements, events, and errors that are included in each 
ServiceClass can be found in Appendix B.

XieTypTechniqueGroup
TechniqueGroup defines the standard technique group names that can be queried using the QueryTech-
niques protocol request. 
XieTypTechniqueGroup	{	XieValDefault,
XieValAll,
XieValColorAlloc,
XieValConstrain,
XieValConvertFromRGB,
XieValConvertToRGB,
XieValConvolve,
XieValDecode,
XieValDither,
XieValEncode,
XieValGamut,
XieValGeometry,
XieValHistogram,
XieValWhiteAdjust }
*	Default	select all default techniques
*	All	select all supported techniques
*	ColorAlloc	select color allocation techniques
*	Constrain	select techniques for constraining data
*	CovertFromRGB	select colorspace conversion techniques (for conversion from the RGB colorspace)
*	CovertToRGB	select colorspace conversion techniques (for conversion to the RGB colorspace)
*	Convolve	select techniques for handling convolution edge conditions
*	Decode	select image decoding (decompression) techniques
*	Dither	select dithering techniques
*	Encode	select image encoding (compression) techniques
*	Gamut	select colorspace conversion gamut compression techniques
*	Geometry	select geometric sampling techniques
*	Histogram	select match-histogram shapes
*	WhiteAdjust	select colorspace conversion white point adjustment techniques

If a vendor defined an additional private technique group, it could be discovered by querying for All groups.
XieTypTechniqueRec
TechniqueRec defines the information which is returned for each technique in the reply to a Query-
Techniques protocol request.
XieTypTechniqueRec
[	needs-parameters	BOOL
group	XieTypTechniqueGroup
number	CARD16
speed	CARD8
name	STRING8
]
Needs-parameters indicates that a technique requires additional parameters; or if false, the technique either 
takes no parameters, or its parameters are optional.  Group identifies which group the technique belongs to.  
Number is the numeric identifier assigned to the technique *.  Speed represents the server's view of the 
speed of this technique relative to the other techniques in the same group (0 is the slowest, and 255 is the 
fastest).  Name is the XIE compliant technique name string.
* Numbers assigned to standard techniques are encoded in Appendix C. 

XieTypTile
Tile defines a source data tile for the PasteUp element. 
XieTypTile
[	src	XieTypPhototag
dst-x	INT32
dst-y	INT32
]
Src is the Phototag of the element supplying source data.  Dst_x, dst_y specify the coordinates where the 
tile belongs in the output data.

XieTypTripletoftype
Tripletof is a generic type used to define a fixed sized array of 3 items* of the specified type. 
XieTypTripletof	[ v0, v1, v2 : (of type) ]
*	Tripletof is usually used to describe per-band attributes and parameters.  When dealing with SingleBand images, the value 
zero must be used for the nonexistent bands. 
XieTypWhiteAdjustTechnique
WhiteAdjustTechnique defines the white point adjustment techniques which can be used when converting 
to or from the RGB colorspace. 
XieTypWhiteAdjustTechnique	{	XieValDefault,
XieValWhiteAdjust_None,
XieValWhiteAdjust_CIELabShift }
*	Default
WhiteAdjust_None	NONE
WhiteAdjust_CIELabShift	CIELAB-SHIFT
private-technique-number	private-name-string
*	The server is required to support the Default technique which is bound to one of the standard techniques defined above or 
a private technique.























almost blank

Protocol Parameter Types   3-1


4
Resources
Overview
XIE resources are extension server objects created by the client which contain information used by the 
extension in carrying out various protocol requests.  There are protocol requests to create and destroy 
each resource type.  Resource identifiers are generated by the client as defined by the core protocol.  
All XIE resources are reference counted. 
Binding Resources to Photoflos
Each resource that is referenced from a Photoflo is bound to the Photoflo (and its reference count is 
incremented) when the Photoflo becomes Active. 
ColorList resources
A ColorList is purged of previous allocations when a Photoflo begins execution, and is populated with 
new allocations (via ConvertToIndex) as the Photoflo proceeds.  A ColorList can only be referenced by 
one Active Photoflo at a time.  The ColorList's reference count is decremented when the Photoflo is no 
longer Active. 
LUT, Photomap, and ROI resources
These XIE resources consist of two parts: one part contains the resource-id, the other part holds at-
tributes and data.  Figure 4-1 pictures the first part as a handle, and the second part as a bucket.  Upon 
resource creation only the handle exists.  The bucket is created when the Photoflo (referencing the 
handle via an ExportResource element) becomes Active.  The handle and bucket are joined when 
the Photoflo successfully completes.  Conceptually each part contains a separate reference count.
 
Figure 4-1   Creating and populating a new Photomap
In the case of ImportResource elements the handle and bucket are both bound to the Photoflo 
when it first becomes Active (initialization).  For ExportResource elements, only the handle is 
bound at this time and a new bucket is created to hold the forthcoming data.  This bucket's attributes 
are derived from the ExportResource element.
If an export handle is already connected to a bucket, the old bucket remains with its handle until suc-
cessful Photoflo completion.  Thus, the old bucket is preserved if the Photoflo terminates due to an error 
condition or if an Abort request is received from the client.  
The new bucket is filled with data as the Photoflo proceeds.  When the Photoflo successfully com-
pletes, old buckets can be freed if they have no other references, and the waiting handle is joined to the 
new bucket.  This is illustrated in figure 4-2.
 
Figure 4-2   Process image from Photomap a, place result into Photomap b
This model also allows pseudo in-place operations such as is illustrated in figure 4-3.  Here an image is 
imported from a Photomap, processed, and then the result is exported back to the same Photomap.  Note 
that upon completion the old handle is moved to the new bucket and the old bucket is destroyed. 
 
Figure 4-3   Process image from Photomap a in-place
Resource destruction
When a destroy request is received the resource-id is immediately disassociated from the resource and 
the resource's reference count(s) is(are) decremented.  For each reference count that goes to zero, the 
associated resources are freed (e.g. memory or colors). 
Synchronizing resource access
If multiple Photoflos reference the same resource, the client must synchronize access to the resource 
(e.g. Await completion of the Photoflo writing the resource before beginning execution of a Photoflo 
reading from the resource).  Core resources can be volatile, requiring the client to maintain the data 
integrity of the resource while the Photoflo is active. 
Capability Acquisition
QueryImageExtension
XieReqQueryImageExtension
client-major-version	CARD16
client-minor-version	CARD16
*
server-major-version	CARD16
server-minor-version	CARD16
service-class	XieTypServiceClass
alignment	XieTypAlignment
unconstrained-mantissa	CARD16
unconstrained-max-exp	INT32
unconstrained-min-exp	INT32
constrained-levels	LISTofCARD32
Errors:	Alloc
Events:	none
QueryImageExtension returns information about the XIE server's capabilities.  Each client should use 
QueryImageExtension to establish version compatibility between client and server prior to making any 
other XIE request.  If a client fails to first establish the desired version using QueryImageExtension, the 
behavior of other requests is undefined (which generally means that the server will use the version 
number of its own choice). 
Client-major-version and client-minor-version specify which version of the XIE protocol the client 
would like to use.  If the client can support multiple versions, the highest version should be given. 
The server-major-version and server-minor-version specify the version of the XIE protocol that the 
server expects from the client. If the server supports the version requested by the client, this version 
number will be returned.  If the client has requested a higher version than is supported by the server, 
the server's highest version will be returned.  Otherwise, if the client has requested a lower version than 
is supported by the server, the server's lowest version will be returned.  It is the client's responsibility to 
decide whether or not it can match the server's version of the protocol. 
Service-class specifies the ServiceClass supported by the XIE server .  Alignment specifies the image 
data alignment restrictions of the server (i.e. the alignment of pixels  and scanlines). 
The following parameters convey the approximate range and granularity of Unconstrained data in the 
XIE server.  For servers that represent Unconstrained data using floating point, unconstrained-
mantissa returns the number of bits in the server's floating point format (including the sign bit).  If the 
server uses fixed point, unconstrained-mantissa is 0.  Unconstrained-max-exp returns the largest value 
n such that 2n - 1 is representable in the server's Unconstrained data format.  Unconstrained-min-exp 
returns the smallest (most negative) value n such that 2n is representable in the server's Unconstrained 
data format.
Constrained-levels provides a hint about how the XIE server might process Constrained data most 
efficiently.  Constrained-levels returns a list of levels that are recommended for Constrained data by 
the server.  (a value of 0 means 232 levels). 
Error	Cause
Alloc	insufficient resources


Technique Acquisition
QueryTechniques
XieReqQueryTechniques
technique-group	XieTypTechniqueGroup
*
technique-information	ListofXieTypTechniqueRec
Errors:	Alloc, Value
Events:	none
QueryTechniques returns information about the standard and private techniques that are supported by 
the server.  The server may be queried for All techniques, all Default techniques, or a group of 
techniques that are functionally similar (e.g. all Geometry techniques). 
Technique-group specifies the group of techniques for which the server is to return information. 
Technique-information is a list of TechniqueRec entries which are returned in arbitrary order.  Each 
entry contains the following information:
needs-parameters	if true, indicates that the technique requires additional parameters; if 
false, the technique takes no parameters, or it has parameters that are 
optional.  If parameters are optional, they must be totally omitted, or 
they must all be supplied.
group 	identifies which group the technique belongs to.  
number	the numeric identifier assigned to the technique (MS bit is zero for 
standard techniques, or one for private techniques).
speed	the server's assessment of the speed of this technique relative to other 
techniques in the same group (0 :== slowest, 255 :== fastest).  
name	the XIE compliant technique name string of the form:
  <STANDARD-TECHNIQUE-NAME> or
_<ORGANIZATION-NAME>_<PRIVATE-TECHNIQUE-NAME>
The technique number is supplied to pipeline elements to specify a desired algorithm or technique.  
While numbers for standard techniques can be hard-coded (e.g. defined in an include file), numbers for 
private techniques must be obtained using the QueryTechniques protocol request prior to their use. 
Error	Cause
Alloc	insufficient resources
Value	unknown technique-group
A complete description of each technique and its parameters is given in Appendix A.  A summary of standard 
techniques itemized by service class can be found in Appendix B. Numbers assigned to standard techniques are encoded 
in Appendix C. 


ColorList
CreateColorList
XieReqCreateColorList
color-list	XieTypColorList
Errors:	Alloc, IDChoice
Events:	none
CreateColorList creates an unpopulated server resource which can be used to store the list of colors 
allocated by a ConvertToIndex element.  The COLORMAP allocations that are recorded in a ColorList 
belong to the client that executed the Photoflo that populated the resource (this is not necessarily the 
same client that created the ColorList).  A ColorList cannot be the target of more than one Active 
Photoflo at a time.
Color-list is the client supplied ColorList identifier to be assigned to this resource. 
Color-list is populated (or re-populated) with new COLORMAP allocations via a ConvertToIndex 
element as the Photoflo executes.  The contents of color-list may be queried using QueryColorList. 
The client may explicitly purge all allocated cells from color-list using PurgeColorList.  The client may 
cause an implicit deallocation of cells from color-list by making it the target of a Photoflo and com-
mencing its execution.  An implicit purge also takes place if the COLORMAP referenced by color-list is 
freed or if the client that owns the cells exits (i.e. the client that populated color-list).
Color-list can be destroyed using DestroyColorList. 
Error	Cause
Alloc	insufficient resources
IDChoice	invalid color-list


DestroyColorList
XieReqDestroyColorList
color-list	XieTypColorList
Errors:	ColorList
Events:	none
DestroyColorList disassociates the resource-id from color-list and decrements its reference count.  If 
there are no other references, it frees colors held in color-list, and then destroys the ColorList identi-
fied by color-list. 
Error	Cause
ColorList	invalid color-list


PurgeColorList
XieReqPurgeColorList
color-list	XieTypColorList
Errors:	Access, ColorList
Events:	none
PurgeColorList frees the colors from the ColorList identified by color-list. 
Error	Cause
Access	attempt to purge colors when color-list is being written by a Photoflo
ColorList	invalid color-list


QueryColorList
XieReqQueryColorList
color-list	XieTypColorList
*
colormap	COLORMAP
colors	LISTofCARD32
Errors:	Alloc, ColorList
Events:	none
QueryColorList returns a list of colors allocated by a ConvertToIndex element. 
Color-list is the ColorList resource to be queried. 
Colormap is the COLORMAP from which the colors were allocated.  Colors is the list of allocated 
COLORMAP indices. 
When there are no colors in color-list, the value zero (0) is returned for colormap, and the list of colors 
is of length zero. 
Error	Cause
Alloc	insufficient resources
ColorList	invalid color-list
Notes:
*	The COLORMAP was originally supplied by the client as a ConvertToIndex parameter.
*	The returned colors are owned by the server, and therefore, should not be freed via core X protocol requests (e.g. 
FreeColors)
*	The allocated colors can be freed by:
	- issuing a PurgeColorList or DestroyColorList request,
	- commencing execution of a Photoflo that targets color-list,
	- freeing colormap,
	- shutting down the client that populated color-list.


LUT
CreateLUT
XieReqCreateLUT
lut	XieTypLUT
Errors:	Alloc, IDChoice
Events:	none
CreateLUT creates a server resource which is used as a lookup table by the Point element.  A lookup 
table consists of one or three single dimension arrays, each long enough to contain an entry for all 
possible pixels values in the image data to which the Point element will be applied. 
Lut is the client supplied LUT identifier to be assigned to this resource. 
The LUT is populated (or re-populated) with lookup table entries after the successful execution of a 
Photoflo containing an ExportLUT element which targets lut.  Lookup table data can be imported into a 
Photoflo using an ImportLUT element. These data can be used by Point, and they can be exported to 
the client with the aid of an ExportClientLUT element.
Lut can be destroyed using DestroyLUT. 
Error	Cause
Alloc	insufficient resources
IDChoice	invalid lut
A LUT can be populated with a simple ExecuteImmediate( ImportClientLUT, ExportLUT ) Photoflo.  
PutClientData is then used to transport the lookup table entries.  See ImportClientLUT and Point for further 
information on LUTs 


DestroyLUT
XieReqDestroyLUT
lut	XieTypLUT
Errors:	LUT
Events:	none
DestroyLUT disassociates the resource-id from lut and decrements its reference count.  If there are no 
other references, it destroys the LUT identified by lut. 
Error	Cause
LUT	invalid lut


Photomap
CreatePhotomap
XieReqCreatePhotomap
photomap	XieTypPhotomap
Errors:	Alloc, IDChoice
Events:	none
Attribute	Value
class	undefined (see text)
type	undefined (see text)
width	undefined (see text)
height	undefined (see text)
levels	undefined (see text)
CreatePhotomap creates a server resource which is used to store image data.  Photomap data may be 
rendered for display or used as input to control or modify the rendition of another image. 
Photomap is the client supplied Photomap identifier to be assigned to this resource. 
Photomap attributes are defined when a Photoflo containing an ExportPhotomap element populates 
photomap with data. 
The Photomap is populated (or re-populated) with image data after the successful execution of a Pho-
toflo containing an ExportPhotomap element that targets photomap.  Photomap data can be imported 
into a Photoflo for rendition or control purposes using an ImportPhotomap element. It can also be 
exported back to the client with the aid of an ExportClientPhoto element.  Photomap attributes can be 
queried using QueryPhotomap.  Photomap can be destroyed using DestroyPhotomap. 
Error	Cause
Alloc	insufficient resources
IDChoice	invalid photomap
A Photomap can be populated with a simple ExecuteImmediate(ImportClientPhoto, ExportPhotomap) 
Photoflo.  PutClientData is then used to transport the image data.  See ImportClientPhoto and ExportPhotomap 
and their associated techniques for more information regarding the format of image data.
DestroyPhotomap
XieReqDestroyPhotomap
photomap	XieTypPhotomap
Errors:	Photomap
Events:	none
DestroyPhotomap disassociates the resource-id from photomap and decrements its reference count.  If 
there are no other references, it destroys the Photomap identified by photomap. 
Error	Cause
Photomap	invalid photomap
QueryPhotomap
XieReqQueryPhotomap
photomap	XieTypPhotomap
*
populated	BOOL
data-type	XieTypDataType
data-class	XieTypDataClass
width	XieTypTripletofCARD32
height	XieTypTripletofCARD32
levels	XieTypLevels
decode	XieTypDecodeTechnique
Errors:	Alloc, Photomap
Events:	none
QueryPhotomap returns the queriable attributes of a Photomap. 
Photomap is the Photomap to be queried. 
Populated is a Boolean that indicates that photomap has been populated with attributes and data.  If 
populated is false, all remaining fields contain zeros.  Data-type shows whether the number of quan-
tization levels is valid (Constrained) or unknown (Unconstrained).  Data-class is the class of image 
data (i.e. SingleBand or TripleBand).  Width and height are the dimensions of the image data in pixels 
(per band).  Levels is the potential dynamic range, or number of quantization levels (per band).  Decode 
is the DecodeTechnique that will be required to interpret or decompress the data.
If data-type is  Unconstrained, the returned values for levels are zeros.  If data-class is SingleBand, 
width, height, and levels for unused bands are returned as zeros.
Error	Cause
FloAlloc	insufficient resources
Photomap	invalid photomap


ROI
CreateROI
XieReqCreateROI
roi	XieTypROI
Errors:	Alloc, IDChoice
Events:	none
CreateROI creates a server ROI (Rectangles-Of-Interest) resource.  A ROI resource may be imported 
into a Photoflo and used in conjunction with a ProcessDomain specification to restrict processing to a 
subset of image data.  The ROI, when populated, will contain a list-of-rectangles (of type Rectangle).  
Roi is the client supplied ROI identifier to be assigned to this resource. 
The ROI is populated (or re-populated) with a list-of-rectangles after the successful execution of a 
Photoflo containing an ExportROI element which targets roi.  An ROI resource does not have any 
queriable attributes.  
ROI data can be imported into a Photoflo using an ImportROI element.  This data, which is  used by 
several of the PhotoElements defined in chapters 7 and 8, can also be exported back to the client with 
the aid of an ExportClientROI element.
Roi can be destroyed using DestroyROI. 
Error	Cause
Alloc	insufficient resources
IDChoice	invalid roi
An ROI can be populated with a simple ExecuteImmediate ( ImportClientROI, ExportROI ) Photoflo.  
PutClientData is then used to transport the list-of-rectangles. 
If the client uses ExportClientROI to retrieve a list-of-rectangles from the server, the number of rectangles and the 
content of the list that is returned may differ from original list that was obtained from the client, but its contents will 
be logically equivalent.


DestroyROI
XieReqDestroyROI
roi	XieTypROI
Errors:	ROI
Events:	none
DestroyROI disassociates the resource-id from roi and decrements its reference count.  If there are no 
other references, it destroys the ROI identified by roi. 
Error	Cause
ROI	invalid roi


 	ServiceClasses defined in this document include: Full XIE and DIS.
 

Resources   4-10


5
Pipelined Processing
What is a Photoflo?
A Photoflo is a directed acyclic graph. Each node has zero or more input connections, and zero or one 
output connection.  A node specifies the source for an input by identifying another upstream node.  A 
node's output connection can be used as a source for any number of downstream input connections.  A 
Photoflo is permitted to have taps and multiple final destinations.
The protocol representation of a Photoflo is a list of elements.  Since the entire list is sent to the server 
as a single protocol request, the total length of the list, including its protocol header, must fit within a 
maximum size protocol message (see, maximum-request-length, established by X11 connection setup).
Each element of the Photoflo is identified by its position in the list. This position, or index, is called a 
Phototag.  The first element in the list is index one (1).  The order of elements in the list does not have to 
match the Photoflo topology because there is no implicit coupling of output N to input N+1.  The 
source for each element's input connections are explicitly specified using the Phototags of upstream 
elements.
There are three types of elements.  Import elements bring data into the Photoflo from external resources 
or the client, have one output connection, and no input connections.  Process elements perform some 
operation on the data (e.g. convolution), have one or more input connections, and exactly one output 
connection.  Export elements emit data from the Photoflo to external resources or to the client, have one 
input connection, and no output connections.  A Photoflo should include at least one import element 
and one export element to be useful.


Import
Process
Export

Number of input connections
none
one or more
one

Number of output connections
one
one
none


 
 
 


Figure 5-1   Photoflo element input and output connections
All data external to the Photoflo (internal server data and client data), are accessed through import and 
export elements.  Therefore, for purposes of Photoflo definition and modification, X and XIE resource-
ids are considered element parameters rather than element sources or destinations. No element is 
permitted to reference a Photoflo for any reason.  It is also an error to specify an export element as an 
input to any element.
Figure 5-2 illustrates several capabilities of Photoflo construction.  An RGB image is imported from the 
client.  This image is saved in a Photomap for later re-use.  The blue band is selected and translated (to 
correct registration).  This result is exported back to the client.  A BandCombine element associates a 
single band imported from a Photomap (the red band), with the green band selected from the initial RGB 
image, and the re-registered blue band.  The combined image is then converted to index data and 
exported to a PIXMAP and to a WINDOW.  The color allocation results are saved in a ColorList. 
 
Figure 5-2   Example Photoflo
Two kinds of Photoflos
There are stored Photoflos and immediate Photoflos.  Stored Photoflos persist beyond execu-
tion and may be modified or totally redefined prior to subsequent executions. Immediate Photoflos 
are ephemeral - a single protocol request defines and begins its execution, then it is automatically 
destroyed upon completion.  Services common to both types of Photoflos are:
*	event notification
*	error notification
*	put data: send data from the client into a Photoflo
*	get data: return data exported from a Photoflo back to the client
*	query: return information about the Photoflo
*	await: block future client requests until the Photoflo completes
*	abort: terminate Photoflo execution prematurely
Multi-client Photoflos
A stored Photoflo can be executed by a client other than the client that created it.  It is also possible 
that the Photoflo may reference resources that belong to other clients, and data may be supplied and 
retrieved by various clients.  The following rules apply when multiple clients are involved in the execu-
tion of a Photoflo:
*	errors that stem from executing Photoflo elements are sent to the client executing the Photoflo,
*	errors that stem from executing client data put or get requests go to the client executing the request,
*	colors recorded in a ColorList resource belong to the client executing the Photoflo,
*	PhotofloDone events are sent to the client executing the Photoflo,
*	multiple clients can Await completion of a given Photoflo.
Photoflo States
Stored Photoflos enter the Inactive state upon creation and transition to the Active state when exe-
cution is requested.  Immediate Photoflos are both created and made Active by the execute request.  
A Photoflo remains Active until: all ImportClient elements have received a final flag, all export 
elements have finished their task, and all data exported for the client have been retrieved, or an error 
prevents further progress, or the client issues an Abort request.  After execution stored Photoflos 
return to the Inactive state, whereas immediate Photoflos are destroyed (become Nonexistent). The 
client may destroy a stored Photoflo at any time.
	Stored Photoflo	Immediate Photoflo
	 	 
Figure 5-3   Photoflo states
Flo'ing Data to a Resource
Besides image rendition and display, immediate or stored Photoflos are also used to populate XIE 
resources with data and attributes.  Some form of processing may be applied to the data, but in the 
simplest case, a two element import/export Photoflo is generally sufficient. 
Also all types of ephemeral client data may be imported and used directly by a Photoflo, without the 
necessity of first storing it in an XIE resource.  For example, simple transport of an image (compressed 
or uncompressed) to a WINDOW is expected.  
Import element	Export element	purpose
ImportClientPhoto	ExportPhotomap	populate a Photomap resource
ImportClientLUT	ExportLUT	populate a LUT resource (lookup table)
ImportClientROI	ExportROI	populate a ROI resource (list-of-rectangles)
ImportClientPhoto	ExportDrawablePlane	display a bitonal image in a WINDOW
ImportClientPhoto	ExportDrawable	display a COLORMAP index image in a WINDOW
ImportPhotomap	ExportDrawablePlane	copy an existing bitonal image to a PIXMAP
Table 5-1   Examples of two element Photoflo usage
Name space
For requests that only apply to stored Photoflos (Create, Modify, Redefine, Execute, and Destroy), 
the Photoflo is identified solely by its resource-id.  For all other requests, events, and errors that ref-
erence a Photoflo, the Photoflo is identified using type Executable, which is a tupple identifying the 
name-space and flo-id of the Photoflo.
Name-space for stored Photoflos is always ServerIDSpace (the value zero), and flo-id is the 
Photoflo's resource-id. 
Name-space for immediate Photoflos is a Photospace resource-id, and flo-id  is a thirty-two (32) bit 
value that uniquely identifies the instance of this Photoflo. 
CreatePhotospace
XieReqCreatePhotospace
name-space	XieTypPhotospace
Errors:	Alloc, IDChoice
Events:	none
CreatePhotospace defines a name-space in which immediate Photoflos may be executed.  Any client 
that needs to instantiate immediate Photoflos must create at least one Photospace.
Name-space is the resource-id for a new Photospace that can be used to accommodate immediate 
Photoflos instantiated by this client.  
Error	Cause
Alloc	insufficient resources
IDChoice	invalid name-space
DestroyPhotospace
XieReqDestroyPhotospace
name-space	XieTypPhotospace
Errors:	Photospace
Events:	none
DestroyPhotospace will destroy a Photospace.  Prior to destroying the Photospace, all Photoflos that are 
currently Active in the Photospace will be aborted, exported data pending client retrieval will be freed, 
and the Photoflos will be destroyed.
Name-space is the Photospace to be destroyed. 
Error	Cause
Photospace	invalid name-space


Immediate Photoflos
ExecuteImmediate
XieReqExecuteImmediate
instance	XieTypExecutable
notify	BOOL
element-list	LISTofXieTypPhotoElement
Errors:	FloAlloc, FloID, FloElement, Flo . . .
Events:	PhotofloDone
ExecuteImmediate defines and begins execution of an immediate Photoflo.  Execution is asyn-
chronous.  The Photoflo is destroyed after execution completes and all data exported for the client have 
been retrieved.  It is legal to have multiple unique instances of immediate Photoflos (and stored 
Photoflos) Active concurrently.
Instance specifies the Photospace/flo-id tupple by which this Photoflo will be identified in other re-
quests, events, or errors.  Notify specifies whether a PhotofloDone event should be sent upon comple-
tion.  Element-list defines the import, process, and export elements to be executed.
If any clients have blocked themselves during the execution of the Photoflo (see Await), they will be-
come unblocked when photoflo's state changes from Active to Nonexistent.  If notify is true, a Photo-
floDone event is also generated by this transition.  Finally, this instance is destroyed. 
Error	Cause
FloAlloc	insufficient resources
FloID	invalid Executable instance
FloElement	invalid element-type(s) in element-list
Flo . . .	see element descriptions for errors detected by elements in element-list

See ExecutePhotoflo for a general outline of the execution phases of a Photoflo.


Stored Photoflos
The following requests are used to: create, modify, redefine, execute, and destroy stored Photoflos.  
In these requests the Photoflo instance is identified only by its resource-id.  However, errors and events 
generated due to these requests identify the instance using type Executable (the name-space is 
ServerIDSpace and the flo-id is the Photoflo's resource-id). 
CreatePhotoflo
XieReqCreatePhotoflo
photoflo	XieTypPhotoflo
element-list	LISTofXieTypPhotoElement
Errors:	Alloc, IDChoice, FloAlloc, FloElement, Flo . . .
Events:	none
CreatePhotoflo creates a stored Photoflo resource, defines its complete contents, and sets it in the 
Inactive state.
Photoflo is a new resource-id by which this Photoflo will be identified in other requests, events, or er-
rors.  Element-list defines the import, process, and export elements to be stored for execution. 
Although resources and parameters are specified at creation, no action is taken to validate them at that 
time.  CreatePhotoflo will only store the Photoflo's definition and parameter validation is delayed until 
an execute request is received. 
Error	Cause
Alloc	insufficient resources for photoflo
IDChoice	invalid photoflo
FloAlloc	insufficient resources for element-list
FloElement	invalid element-type(s) in element-list
Flo . . .	see element descriptions for errors detected by elements in element-list
DestroyPhotoflo
XieReqDestroyPhotoflo
photoflo	XieTypPhotoflo
Errors:	Photoflo
Events:	none
DestroyPhotoflo will destroy a stored Photoflo.  If photoflo was Active, it is aborted and all exported 
data that are pending client retrieval are freed prior to destroying photoflo.
Photoflo is the Photoflo to be destroyed. 
Error	Cause
Photoflo	invalid photoflo
See also Abort, which terminates a Photoflo's execution without destroying it. 
ExecutePhotoflo
XieReqExecutePhotoflo
photoflo	XieTypPhotoflo
notify	BOOL
Errors:	Photoflo, FloAccess, FloAlloc
Events:	PhotofloDone
ExecutePhotoflo changes a stored Photoflo to the Active state.  Execution is asynchronous.  The 
Photoflo returns to the Inactive state when execution completes and all data exported for the client have 
been retrieved.  It is legal to have multiple stored Photoflos (and immediate Photoflos) Active 
concurrently.
Photoflo is the Photoflo to be executed.  Notify specifies whether a PhotofloDone event should be sent 
upon completion.
Conceptually, Photoflo execution is broken into at least three phases :
1.	Initialization:
a.	the Photoflo state is set Active,
b.	bind external inputs (XIE reference counts are incremented)
c.	imported attributes are propagated downstream
d.	attributes and element parameter values are validated
e.	lookup external destinations 
f.	create receptors for data to be exported to XIE resources2
2.	Execution:
a.	data from server resources, if any, is pulled into the Photoflo
b.	data from the client, if any, is pushed into the Photoflo (PutClientData)
c.	processed data is exported to server resources as required2
d.	processed data is made available for client retrieval (GetClientData) 
3.	Completion:
a.	unbind external inputs
b.	join exported data with associated XIE resources2 and unbind remaining resources
c.	report any error that occurred
d.	if notify is true, send a PhotofloDone event
e.	if Await has been requested, un-block client execution
f.	the Photoflo state is set Inactive
If an error occurs during any phase, the client is notified and the Photoflo is terminated.  Other events 
can be sent by individual elements, as specified in their descriptions.  
Error	Cause
Photoflo	invalid photoflo
FloAccess	attempt to execute photoflo when it is already Active
FloAlloc	insufficient resources
Flo . . .	see element descriptions for errors detected by photoflo elements
ModifyPhotoflo
XieReqModifyPhotoflo
photoflo	XieTypPhotoflo
start	XieTypPhototag
element-list	LISTofXieTypPhotoElement
Errors:	Photoflo, FloAlloc, FloElement, FloSource, Flo . . .
Events:	none
ModifyPhotoflo allows element parameters of a stored Photoflo to be modified.
Photoflo is the Photoflo to be modified.  Start specifies the Phototag where element replacement is to 
begin.  Element-list is a sequential list of elements which will replace existing elements. 
ModifyPhotoflo allows parameter modification only.  No topological changes are allowed.  Elements 
cannot be deleted, inserted, or appended. 
Error	Cause
Photoflo	invalid photoflo
FloAccess	attempt to change photoflo while it is Active
FloAlloc	insufficient resources
FloElement	attempt to change element-type(s) in element-list
attempt to append additional element(s) to photoflo
FloSource	invalid start
attempt to change Phototag input connections in element-list
Flo . . .	see element descriptions for errors detected by elements in element-list
Multiple ModifyPhotoflo requests can be sent in order to  edit individual elements, but, for greater efficiency and 
particularly when repetitive modify/execute requests are expected, elements can be grouped such that a single 
ModifyPhotoflo can perform multiple element modifications.
RedefinePhotoflo
XieReqRedefinePhotoflo
photoflo	XieTypPhotoflo
element-list	LISTofXieTypPhotoElement
Errors:	FloAccess, Photoflo. FloAlloc, FloElement, Flo . . .
Events:	none
RedefinePhotoflo allows all elements of a stored Photoflo to be removed and replaced with a new list.  
There are no restrictions on changing element types, Phototag sources, or the list's size.
Photoflo is the Photoflo to be redefined.  Element-list is a sequential list of elements which will replace 
all existing elements.
Error	Cause
Photoflo	invalid photoflo
FloAccess	attempt to change photoflo while it is Active
FloAlloc	insufficient resources
FloElement	invalid element-type(s) in element-list
Flo . . .	see element descriptions for errors detected by elements in element-list
RedefinePhotoflo may be considered a hint that the new list of  elements is in some way similar to those being 
replaced. RedefinePhotoflo can also be used as a means to conserve resource-ids. 
Sending Data to the Server
PutClientData
XieReqPutClientData
instance	XieTypExecutable
element	XieTypPhototag
final	BOOL
band-number	CARD8
data	XieTypDataStream
Errors:	FloAlloc, FloAccess, FloID, FloElement, FloValue
Events:	none
PutClientData sends a stream of data to an Active Photoflo.  Since the complete data object may be 
larger than can fit in a single protocol request, XIE allows the stream to be segmented; the last segment 
is signaled with a final flag. 
Instance and element identify the Photoflo and specific ImportClient element to receive the data.  
Final specifies that this is the last (or only) segment of data to be sent. 
If element is a band oriented element, band-number specifies which client band of data is being sent 
(interleave and band-order specified for the ImportClient element or technique determine how cli-
ent bands are mapped to server bands). 
Data is a counted list of bytes that comprises the data stream.  The organization and contents of the 
stream must match the parameters given to the ImportClient element or the results are undefined.
An arbitrary amount of image data can be sent per request, whereas for non-image data one or more 
complete aggregates must be sent per request (e.g. one or more LUT array entries).
If too many data are sent (e.g. too many rectangles, or too many scanlines), the unwanted data are 
discarded.  It is an error, however, to send too few data prior to signaling final. 
Error	Cause
FloAlloc	insufficient resources
FloAccess	Executable instance not Active
FloID	invalid Executable instance
FloElement	invalid Phototag or element-type specified by element
FloValue	invalid band-number 
for non-image data, data contains a partial aggregate
All types of client data (list-of-rectangles, lookup tables, and images) are transported to the server using 
PutClientData.  Tiled images can be transported using multiple ImportClientPhoto elements, which in turn feed a 
PasteUp element. 


Retrieving Data from the Server
GetClientData
XieReqGetClientData
instance	XieTypExecutable
element	XieTypPhototag
max-bytes	CARD32
terminate	BOOL
band-number	CARD8
*
new-state	XieTypExportState
data	XieTypDataStream
Errors:	FloAlloc, FloAccess, FloID, FloElement, FloValue
Events:	none
GetClientData retrieves data from an ExportClient element within an Active Photoflo.  Data are 
returned in a contiguous read-once byte stream, which can be requested in segments that are limited in 
size by the amount the client desires or the amount available.  The format of the data depends on the pa-
rameters given to the ExportClient element from which the data are requested. 
Instance and element identify the Photoflo and specific ExportClient element from which to re-
trieve data.  Max-bytes specifies the maximum number of data bytes that can be sent to the client.  
Terminate is a Boolean that can be used to indicate that no more data are wanted after this request has 
been satisfied.  Band-number specifies which client band is to be retrieved  (interleave and band-order 
parameters specified for the ExportClient element technique determine how server bands are 
mapped to client bands).
New-state indicates the data availability status of the ExportClient element after satisfying the cur-
rent request.  Data is the counted list of bytes that is returned. 
If terminate is true, new-state will be ExportDone (the ExportClient element will discard any 
remaining data and stop producing additional data). 
If new-state is ExportEmpty and notify (for the ExportClient element) was specified as NewData, 
another ExportAvailable event will be sent when additional data become availabile.
If the request is sent to an ExportClient element that either: does not have any data, was termi-
nated by a previous GetClientData request, or has already returned all its data (ExportDone sent), the 
request will return a zero length data stream. 
Image data are always retrieved from the server as a byte stream, whereas non-image data are always 
returned by the server as one or more complete aggregates (i.e. max-bytes is effectively rounded down 
by the server to the match the nearest aggregate size).

Error	Cause
FloAlloc	insufficient resources
FloAccess	Executable instance not Active
FloID	invalid Executable instance
FloElement	invalid Phototag or element-type specified by element
FloValue	invalid band-number
Servers are required to buffer a non-zero amount of data per ExportClient element.  Beyond that point execution 
may be suspended until the client retrieves sufficient data. 
Terminate may be used to prematurely terminate output from an ExportClient element.  If terminate is not used, 
all data produced by the ExportClient element must be retrieved before the Photoflo can leave the Active state.  


Status
QueryPhotoflo
XieReqQueryPhotoflo
instance	XieTypExecutable
*
state	XieTypPhotofloState
data-expected	LISTofXieTypPhototag
data-available	LISTofXieTypPhototag
Errors:	FloAlloc
Events:	none
QueryPhotoflo will return the current status of a Photoflo.
Instance identifies the Photoflo that is being queried.
State indicates the state of the Photoflo.  Data-expected is a list of ImportClient elements that are 
expecting data from the protocol stream.  Data-available is a list of ExportClient elements from 
which data for the protocol stream are available.  Either or both of these lists may be of length zero. 
Specifying an unknown or invalid instance will result in a reply state of nonexistent and zero length 
data-expected and data-available lists. 
Error	Cause
FloAlloc	insufficient resources


Synchronization
Await
XieReqAwait
instance	XieTypExecutable
Errors:	FloAlloc
Events:	none
Await blocks all further requests for this client connection from being honored by the server while the 
Photoflo is Active.  When the Photoflo transitions from the Active state, blocked requests are allowed 
to be processed in the order received. 
Instance identifies the Active Photoflo which is to block requests from the client issuing the Await.
If instance is invalid or the Photoflo is not Active no action is taken; it is not an error, and the client is 
not blocked. 
Error	Cause
FloAlloc	insufficient resources
If a Photoflo has no ExportClient elements, the client can call Await.  If a Photoflo has exactly one 
ExportClient element, the client can just read bytes or be event-driven.  If a Photoflo has multiple 
ExportClient elements, the client should be event-driven.
Warning:	calling Await before sending all import data (including a final flag) or before retrieving all export 
data, will block the client from sending or retrieving the remaining data.  This will also prevent completion 
of the Photoflo and prevent any and all protocol requests from this client from being honored.  This 
deadlock can only be broken by another client completing or  aborting the Photoflo (to release the Await), 
or by breaking the client connection.

Termination
Abort
XieReqAbort
instance	XieTypExecutable
Errors:	none
Events:	none
Abort will prematurely terminate execution of a Photoflo.
Instance identifies the Photoflo which is to be aborted.
Any output from the Photoflo that is pending client retrieval is freed.  If instance is a stored Photoflo 
it will return to the Inactive state.  Immediate Photoflos are destroyed. 
If instance is invalid or the Photoflo is not Active no action is taken; it is not an error, and nothing is 
destroyed. 

 	Optimization, an additional phase, would be roughly associated with the initialization phase.
 	For LUT, Photomap, and ROI resources refer to page 4-1 Binding Resources to Photoflos.
 	Completion is contingent upon all such data being retrieved by the client.
 

Pipelined Processing   5-4


6
Import Elements
Overview
Element categories
Import elements are used to bring external image data into a Photoflo.  Import elements have no Pho-
totag sources and have one output connection.  There are two types of import elements:
*	ImportResource	elements obtain data from a server resource (DRAWABLE, LUT, Photomap, or ROI).
*	ImportClient	elements require data from the client.  This data is transported to the server via the 
PutClientData protocol request.
Multi-source images
Multiple source images (e.g. tiled images, multi-client transport, ...) require a separate import element to 
describe each segment of the image.  The composite image can then be assembled using process ele-
ments (e.g. BandCombine, Blend, and PasteUp).
Events generated
Certain import elements can generate events to notify the client about abnormal behavior.  Two such 
events are defined:
*	DecodeNotify	notifies the client when anomalies are encountered while decoding a compressed image.  
It can also be returned if less data are sent than are required to complete an uncom-
pressed image.
*	ImportObscured	notifies the client that one or more regions to be imported from a WINDOW are 
obscured and unavailable from BACKINGSTORE.
Import from Client
ImportClient elements require data from the client.   Element parameters fully specify all the at-
tributes of the client data and describe the format or organization the data will have as it is transported 
through the protocol stream.  Data is sent to the ImportClient element via the PutClientData 
protocol request after the Photoflo becomes Active. 


ImportClientLUT
XieFloImportClientLUT
class	XieTypDataClass
band-order	XieTypOrientation
length	XieTypTripletofCARD32
levels	XieTypLevels
Errors:	FloAlloc, FloMatch, FloValue
Events:	none
ImportClientLUT accepts lookup table data from the protocol stream.  The transport of data through 
the protocol stream is accomplished using PutClientData. These data are accepted by the Point, Ex-
portLUT, and ExportClientLUT elements. 
Class indicates the number of lookup arrays to expect.  Length specifies the number of entries per array.  
Levels is the number of quantization levels represented per array.  Band-order declares the order of 
TripleBand arrays, or the order in which pixels from a TripleBand image should be combined to form 
indices for a SingleBand array .
The length of each array should match the number of source image levels that will be re-mapped 
through the array.  When a TripleBand image is to be re-mapped through a SingleBand array, the 
length of the array should match the product of the source image levels of all three bands1. Table 6-1 
summarizes the class of output data to expect from Point, based on the class of LUT and the class of 
image provided to Point. 
Table 6-1   Relationship between LUT class and image class
LUT class
Source image: SingleBand
Source image: TripleBand

SingleBand
( 1 array )
Output image: SingleBand
the single image band is re-
mapped through the single array
Usage examples:
achromatic --> achromatic
achromatic --> index
Output image: SingleBand
pixels from each image band are combined1 and 
then re-mapped through the single array
Usage examples:
trichromatic --> index
trichromatic --> achromatic

TripleBand
( 3 arrays )
Output image: TripleBand
the single image band is re-
mapped through each array sepa-
rately
Usage examples:
achromatic --> false-color
index----------> trichromatic
Output image: TripleBand
each image band is re-mapped through the 
corresponding array
Usage examples:
trichromatic --> trichromatic

The size of each array entry is either 1, 2, or 4 bytes; the smallest size into which the output quantization 
levels can be stored.  When array entries require multiple bytes, the byte order per entry is determined 
in the same manner as other numeric data: it is the byte orientation established at core X connection 
setup time. 
Error	Cause
FloAlloc	insufficient resources
FloMatch	levels is incompatible with the server's depth handling capabilities
FloValue	invalid class or band-order
When the client targets data at ImportClientLUT, one or more complete array entries must be sent per protocol 
request (see PutClientData).
ImportClientPhoto
XieFloImportClientPhoto
notify	BOOL
class	XieTypDataClass
width	XieTypTripletofCARD32
height	XieTypTripletofCARD32
levels	XieTypLevels
decode	XieTypDecodeTechnique
decode-params	<technique-dependent>
Errors:	FloAlloc, FloMatch, FloValue, FloTechnique
Events:	DecodeNotify
Attribute	Value
class	class of imported image
type	Constrained
width	width  of imported image (in pixels)
height	height of imported image (in pixels)
levels	levels  of imported image
ImportClientPhoto accepts image data from the protocol stream.  This data may be processed for 
display or used as ProcessDomain data.  The attributes and organization of the expected data stream 
are fully specified by the parameters.  The actual transport of image data through the protocol stream is 
requested using the PutClientData protocol request. 
Notify enables DecodeNotify events to be sent if anomalies are encountered while interpreting the 
imported image data (see DecodeNotify and DecodeTechnique descriptions).  Class specifies the 
DataClass of the data being imported.  Width and height are the  per-band image dimensions in pixels.  
Levels is the number of quantization levels per band.  Decode is the DecodeTechnique that will be 
required to decompress the image.  Decode-params is the list of additional parameters required by 
decode.
Only Constrained data can be sent through the protocol stream, therefore, levels must be valid.
Error	Cause
FloAlloc	insufficient resources
FloMatch	levels is incompatible with the server's depth handling capabilities
FloValue	invalid width, height, levels (zero)
invalid class
FloTechnique	invalid decode technique or decode-params
If the imported client data is compressed, ImportClientPhoto is generally responsible for decoding the data prior to 
forwarding the data to downstream elements.  An exception to this would be when an export element is a direct 
recipient of the data and the element desires data that are encoded using the same technique as decode. 
If individual bands of TripleBand data have different widths or heights (e.g. down-sampled YCbCr data), it is generally 
the client's responsibility to make inter-band dimensions match to render the image (e.g. use Geometry with 
appropriate band-mask and sample technique).  The JPEGBaseline technique that is described in Appendix A, includes 
a Boolean flag that allows an image that is interleaved BandByPixel to be up-sampled as part of the decode function.
All data and a final indication must be sent for each band before the Photoflo can leave the Active state.  The input 
data are sent by the client using the PutClientData protocol request.  If a subset of client bands are desired, the bands 
should be imported as individual SingleBand images. 


ImportClientROI
XieFloImportClientROI
rectangles	CARD32	
Errors:	FloAlloc
Events:	none
ImportClientROI accepts a list-of-rectangles from the protocol stream.  These data can be used as 
input to a ProcessDomain or an ExportROI or ExportClientROI element.  The actual transport of data 
through the protocol stream is accomplished using the PutClientData protocol request (the band-
number parameter of PutClientData is ignored).
Rectangles specifies the number of rectangles expected. 
Each rectangle is described using numeric values (see Rectangle), as such, the byte order of such data 
is determined at core protocol connection setup time.
Error	Cause
FloAlloc	insufficient resources
When the client targets data at ImportClientROI, one or more complete Rectangles must be sent per protocol 
request (see PutClientData).


Import from Resource
ImportResource elements obtain data from server resources: core DRAWABLEs, and XIE LUT, Pho-
tomap, and ROI resources. 
The attributes and data of XIE resources are bound to ImportResource elements when the Photoflo 
becomes Active.  The same resource may also be the target of an ExportResource element in the 
same Photoflo.  However, the association between the resource's identifier (XID) and the new attributes 
and data does not occur until the Photoflo successfully completes (i.e. leaves the Active state).   (See 
Binding Resources to Photoflos in Chapter 4.)
ImportDrawable
XieFloImportDrawable
notify	BOOL
drawable	DRAWABLE
src-x	INT16
src-y	INT16
width	CARD16
height	CARD16
fill	CARD32
Errors:	FloAlloc, FloDrawable, FloValue
Events:	ImportObscured
Attribute	Value
class	SingleBand
type	Constrained
width	width
height	height
levels	2depth (i.e. drawable depth)
ImportDrawable allows access to data existing in a DRAWABLE.  This data may be processed for 
display or, if drawable is a BITMAP, used as ProcessDomain data.  
Notify enables ImportObscured events to be sent if data for one or more regions of a WINDOW are 
obscured and unavailable from BACKINGSTORE (see ImportObscured).  Drawable is the DRAWABLE 
resource supplying the data.  Src-x, src-y, width, and height specify the region of data to be imported 
from drawable.  Fill is the COLORMAP index to use for all regions that are obscured. 
Error	Cause
FloAlloc	insufficient resources
FloDrawable	invalid drawable
FloValue	invalid region (src-x, src-y, width, height)
The data are imported as ZPixmap format COLORMAP indices (i.e. SingleBand index data).  Index data are 
appropriate for only a few process elements (e.g. where a nearest-neighbor technique is used).  ConvertFromIndex 
can be used to convert index data prior to feeding it to other process elements.  Compare can also be used to produce 
bitonal data from index data. 


ImportDrawablePlane
XieFloImportDrawablePlane
notify	BOOL
drawable	DRAWABLE
src-x	INT16
src-y	INT16
width	CARD16
height	CARD16
fill	CARD32
bit-plane	CARD32
Errors:	FloAlloc, FloDrawable, FloValue
Events:	ImportObscured
Attribute	Value
class	SingleBand
type	Constrained
width	width
height	height
levels	2
ImportDrawablePlane allows access to a single plane of data existing in a DRAWABLE.  This data may 
be processed for display or  used as ProcessDomain data.  
Notify enables ImportObscured events to be sent if data for one or more regions of a WINDOW are 
obscured and unavailable from BACKINGSTORE (see ImportObscured).  Drawable is the DRAWABLE 
resource supplying the data.  Src-x, src-y, width, and height specify the region of data to be imported 
from drawable.  Fill is the value to substitute for all regions that are obscured.  Bit-plane specifies the 
plane to be imported from drawable.
Bit-plane must have exactly one bit set to one (1), and the value of bit-plane must be less than 2n, 
where n is the depth of drawable.  This single bit selects the corresponding bit to be extracted from 
pixels within drawable.
Error	Cause
FloAlloc	insufficient resources
FloDrawable	invalid drawable
FloValue	invalid bit-plane or region (src-x, src-y, width, height)


ImportLUT
XieFloImportLUT
lut	XieTypLUT
Errors:	FloAlloc, FloAccess, FloLUT
Events:	none
ImportLUT allows access to lookup table data existing in a LUT resource.  These data are accepted by 
the Point, ExportLUT, and ExportLUT elements. 
Lut is the LUT resource supplying the lookup table. 
Attributes of the lookup table data are inherited from lut. 
Error	Cause
FloAlloc	insufficient resources
FloAccess	attempting to import from lut before it has been populated
FloLUT	invalid lut


ImportPhotomap
XieFloImportPhotomap
notify	BOOL
photomap	XieTypPhotomap
Errors:	FloAlloc, FloAccess, FloPhotomap
Events:	DecodeNotify
Attribute	Value
class	same as photomap
type	same as photomap
width	same as photomap
height	same as photomap
levels	same as photomap
ImportPhotomap allows access to image data existing in a Photomap.  This data may be processed for 
display or used as ProcessDomain data. 
Notify enables DecodeNotify events to be sent if anomalies are encountered while decoding com-
pressed data (see DecodeNotify and the DecodeTechnique descriptions).  Photomap is the Photomap 
resource supplying image data. 
Attributes of the source data are inherited from photomap. 
Error	Cause
FloAlloc	insufficient resources
FloAccess	attempting to import from photomap before it has been populated
FloPhotomap	invalid photomap
If the data imported from photomap are compressed, ImportPhotomap is generally responsible for decoding the data 
prior to forwarding the data to downstream elements.  An exception to this would be when an export element is a direct 
recipient of the data and the data are already encoded using the technique desired by the export element. 
If individual bands of TripleBand, BandByPlane data have different widths or heights (e.g. down-sampled YCbCr data), 
it is generally the client's responsibility to make inter-band dimensions match to render the image (e.g. use Geometry 
with appropriate band-mask and sample technique).  If ImportPhotomap's input data are TripleBand, BandByPixel, 
the dimensions of the output bands will match even if the encoded input data are down-sampled.



ImportROI
XieFloImportROI
roi	XieTypROI
Errors:	FloAlloc, FloAccess, FloROI
Events:	none
ImportROI allows access to a list-of-rectangles existing in a ROI resource.  This data may be refer-
enced by a ProcessDomain.  
Roi is the ROI resource supplying the list-of-rectangles. 
Error	Cause
FloAlloc	insufficient resources
FloAccess	attempting to import from roi before it has been populated
FloROI	invalid roi























almost blank

 	For SingleBand LUTs, Point combines TripleBand src pixel values to provide a compact array indexing scheme.  
The algorithm is presented in Figure 7-4.
 

Import Elements   6-1


7
Process Elements
Overview
Process elements have one or more Phototag sources and have one output connection.  Each process 
element applies a specific operation to image data within an Active Photoflo.  Some process elements 
perform their operation on a single source of image data (e.g. Geometry).  Others, operate on either a 
pair of image sources or an image and a constant (e.g. Logical).  BandCombine associates bands from 
three SingleBand image sources to form a TripleBand image.  PasteUp can combine multiple images 
(tiles) to form a composite image.
The ConvertToIndex element can generate an event to notify the client about color allocation results. 
A process element will not be involved in the execution of a Photoflo if there is no eventual consumer of 
its output (i.e. no terminating export element). 
Limiting the Process
Processing may be limited to a subset of the bands present and a subset of pixels within the processed 
bands.  Data falling outside the selection criteria are passed through unaffected by the element's proc-
ess. 
Process Selected Bands
Some process elements accept a band-mask to restrict processing to a subset of the source data bands.  
Only bands selected by the band-mask are subject to processing.  Other bands present in the image are 
passed through to the output.  For example: a band-mask of 0012 indicates that only the least signifi-
cant band would be processed (see Orientation for a definition of band ordering). 
Process Intersecting Pixels
Dyadic process elements can accept a pair of data sources.  These sources are spatially registered at 
their origins (upper left corners).  Their class and type must match, but their dimensions (width and 
height) need not match.  The dimensions of the output are determined by src-1.  Processing is spatially 
restricted to the intersection of the sources on a per-band basis.  Data from src-1 that do not intersect 
with src-2 are passed through to the output. 
Process Selected Pixels
Some process elements accept a processing domain (ProcessDomain) to restrict processing to a subset 
of the source data pixels.  The processing domain represents either a list-of-rectangles or a bi-level 
SingleBand control-plane. 
A processing domain contains an x,y coordinate pair to spatially position the overall processing do-
main relative to the origin of the source(s).  It also contains a Phototag which references the import or 
process element that supplies the processing domain data.  The element referenced by the Phototag 
may provide a:
*	list-of-rectangles	imported using ImportROI or ImportClientROI.  Processing is restricted to the 
intersection of the data source(s) and any rectangle within the list.
*	control-plane	imported using ImportDrawable, ImportDrawablePlane, ImportPhotomap, or 
ImportClientPhoto; or the output of an upstream process element (e.g. Compare).  
Processing is restricted to the intersect of the data source(s) and non-zero locations 
within the control-plane.
Processing is not restricted if Phototag zero (0) is specified as the process domain's data source. 
 
Figure 7-1   Combining two sources using a control plane - Logical:  Copy
Data Types
In XIE, an image consists of one or three arrays of pixels, each of which is measured in terms of its 
width, height, and depth.  Each array, which represents a chromatic band of image data, is dimensioned 
independently.  The depth component of each array is expressed in quantization levels, or, the potential 
dynamic range of the pixels.  All process elements within XIE are capable of operating on image data 
that have a fixed number of quantization levels.  These data are said to be Constrained, such that the 
minimum possible intensity value of a pixel is zero (0), and the maximum possible intensity level is the 
number of quantization levels minus one. 
With the exception of operations that specifically change the number of quantization levels (e.g. Dither) 
all other operations that are performed on Constrained data will maintain the levels attribute from input 
to output.  An operation that computes a negative pixel value will set the resulting pixel to zero.  
Likewise, an operation that computes a pixel value that would exceed the levels attribute of the data, will 
saturate the resulting pixel at its maximum allowable value (i.e. levels-1).  This method of constraining 
image data is equivalent to the HardClip Constrain technique.
For some operations (e.g. Arithmetic operations), it is desirable to allow pixel values to stray beyond 
their Constrained values.  Such data are said to be Unconstrained, and may contain negative values, 
fractional values, or other values that might be beyond the normal display capabilities of a frame buffer. 
Performing a sequence of image operations on Unconstrained image data allows the maximum degree of 
precision to be maintained throughout the process (although there may be a cost in performance, 
depending on the server's capabilities).  Several XIE process elements are capable of operating on either 
Constrained or Unconstrained data.  These elements always output the same DataType as they are fed 
at their inputs.  An exception to this rule is that certain colorspace conversion techniques can accept 
either DataType, but are only capable of outputting Unconstrained data.

XIE provides a complementary pair of elements for converting image data between these two process-
ing styles.  The Unconstrain element simply removes the normal levels restrictions from the data.  The 
Constrain element provides a means of bringing the data back into a Constrained range.  A variety of 
techniques are available for this purpose that allow the pixel values to be level-shifted, scaled, clipped, 
rounded, etc.
Process Categories
*	Area elements
-	Convolve	an area of input pixels is involved in producing each output pixel 
(controlled by a convolution kernel)
*	Format conversion elements
-	ConvertFromIndex	convert index data to achromatic or trichromatic data
-	ConvertFromRGB	convert RGB data to another trichromatic colorspace
-	ConvertToIndex	convert achromatic or trichromatic data to index data
-	ConvertToRGB	convert non-RGB trichromatic data to RGB data
*	Dyadic elements: process either two images or an image and a constant
-	Arithmetic	an arithmetic operation is performed between two images or an image 
and a constant
-	Blend	combine two images or an image and a constant
-	Compare 	two images, or an image and a constant, are compared to generate a 
Boolean bitmap result
-	Logical	perform logical bit-wise operations on an image, between two images, 
or between an image and a constant
*	Geometric elements
-	Geometry	general affine transform (provides: crop, mirror, scale, shear, rotate, 
translate, and combinations thereof)
-	PasteUp	an N-input translate operation which reconstructs an image from 
various source tiles
*	Point elements
-	Math	apply a mathematical operation to each pixel
-	Point	re-map each pixel value through a lookup table
*	Radiometric elements
-	BandCombine	merge three SingleBand images
-	BandExtract	extract SingleBand data from a trichromatic source
-	BandSelect	select a single band of data from a trichromatic source
-	Constrain	constrain an image to a fixed number of quantization levels
-	Dither	reduce image quantization levels through an area technique
-	MatchHistogram	transform an image to have a specific histogram shape
-	Unconstrain	remove the normal levels restrictions from the image data
Process Definitions
The complete list of process PhotoElements follows in alphabetical order. 
Arithmetic
XieFloArithmetic
src-1	XieTypPhototag
src-2	XieTypPhototag
domain	XieTypProcessDomain
constant	XieTypConstant
operator	XieTypArithmeticOp
band-mask	CARD8
Errors:	FloAlloc, FloSource, FloDomain, FloMatch, FloOperator, FloValue
Events:	none
Attribute	Value
class	same as src-1
type	same as src-1
width	same as src-1
height	same as src-1
levels	same as src-1
Arithmetic produces output data by performing an addition, subtraction, minimum, or maximum op-
eration between two data sources or between a single data source and a constant.  Furthermore, multipli-
cation, division, or gamma correction may by applied to a single data source.
When two sources are involved, src-1 and src-2 are the Phototags of the elements supplying source 
data (constant is ignored). If the operation is to involve a constant, src-1 is one operand, src-2 must be 
zero, and constant is used as the other operand.  Domain may control the subset of source data that 
will be operated upon.  Operator is the arithmetic operation to be performed.  Band-mask specifies 
which bands are to be operated upon. 
When two sources are involved, all attributes, other than width and height, must match; all output at-
tributes are inherited from src-1.
Pixel computations that would lead to errors, will yield valid server-dependent values (e.g. dividing by a 
Constrained pixel value of zero might result in a value of levels-1) .  Using band-mask to select source 
data that have two (2) or less levels is not permitted.
Error	Cause
FloAlloc	insufficient resources
FloSource	invalid src-1 or src-2 
src-2 has been specified with a monadic  operator (e.g. Div or Gamma)
FloDomain	invalid domain
FloMatch	class, type, or levels differs between src-1 and src-2
selected source data are bitonal (i.e. 2 or less levels)
FloOperator	invalid operator


BandCombine
XieFloBandCombine
src-1	XieTypPhototag
src-2	XieTypPhototag
src-3	XieTypPhototag
Errors:	FloAlloc, FloSource, FloMatch
Events:	none
Attribute	Value
class	TripleBand
type	same as src-1
width	same as srcs
height	same as srcs
levels	same as srcs
BandCombine merges three SingleBand data sources to produce a TripleBand result.
Src-1, src-2, and src-3 are the Phototags of the elements supplying source data.
All three sources must be of the same type, and each source must be SingleBand.  Other attributes 
which are taken from the individual sources may differ.  The output will be TripleBand.
No subsetting by ProcessDomain is provided. 
Error	Cause
FloAlloc	insufficient resources
FloSource	invalid src-1, src-2, or src-3
FloMatch	a source has more than one band
type differs between sources


BandExtract
XieFloBandExtract
src	XieTypPhototag
coefficients	XieTypConstant
bias	XieTypFloat
levels	CARD32
Errors:	FloAlloc, FloSource, FloMatch
Events:	none
Attribute	Value
class	SingleBand
type	same as src
width	same as src
height	same as src
levels	levels or unknown (see text)
BandExtract produces SingleBand output data from a TripleBand source by multiplying a pixel value 
from each source band by its corresponding coefficient and then summing the results with the bias 
value. 
Src is the Phototag of the element supplying source data.  Coefficients is a three (3) element array that 
determines the proportion of each source band pixel that is used to form the output.  The bias value is 
added to each output pixel.  Levels is used as the levels attribute of the output data if the src data are 
Constrained, otherwise it is ignored. 
The source data must be TripleBand, and all bands must have equal dimensions. The output data will 
be SingleBand, with levels taken from the levels parameter, if type is Constrained.  All other attributes 
are inherited from src.
No subsetting by ProcessDomain is provided (the entire image is processed). 
Error	Cause
FloAlloc	insufficient resources
FloSource	invalid src
FloMatch	src is not TripleBand
unequal inter-band dimensions (width or height)
BandExtract can be used to extract a band of luminance data from an RGB image.  It can also be used to compute 
COLORMAP indices in cases where the contents of the COLORMAP is well ordered (e.g. a Standard-COLORMAP or a 
TrueColor visual).


BandSelect
XieFloBandSelect
src	XieTypPhototag
band-number	CARD8
Errors:	FloAlloc, FloSource, FloMatch, FloValue
Events:	none
Attribute	Value
class	SingleBand
type	same as src
width	same as band selected from src
height	same as band selected from src
levels	same as band selected from src
BandSelect produces SingleBand output data by selecting a single band from a TripleBand source.
Src is the Phototag of the element supplying source data.  Band-number specifies which src band is to 
be selected to provide the output data.
No subsetting by ProcessDomain is provided.
Error	Cause
FloAlloc	insufficient resources
FloSource	invalid src
FloMatch	src is not TripleBand
FloValue	invalid band-number


Blend
XieFloBlend
src-1	XieTypPhototag
src-2	XieTypPhototag
alpha	XieTypPhototag
constant	XieTypConstant
alpha-const	XieTypConstant
domain	XieTypProcessDomain
band-mask	CARD8
Errors:	FloAlloc, FloSource, FloDomain, FloMatch, FloValue
Events:	none
Attribute	Value
class	same as src-1
type	same as src-1
width	same as src-1
height	same as src-1
levels	same as src-1
Blend produces output data from two data sources or a single data source and a constant.  Each output 
pixel is a percentage combination of the source values, as controlled by the alpha input or the alpha 
constant. 
When two sources are involved, src-1 and src-2 are the Phototags of the elements supplying source 
data (constant is ignored).  If the operation is to involve a constant, src-1 is one operand, src-2 must be 
zero, and constant is used as the other operand.  If alpha is non-zero, it controls the blend proportion 
for each pixel that is processed, otherwise alpha-const provides this control.  Domain may control the 
subset of source data that will be operated upon.  Band-mask specifies which bands are to be operated 
upon. 
When two sources are involved, all attributes, other that width and height, must match. If alpha is non-
zero, it must be a source of Constrained data. Using band-mask to select source data that have two (2) 
or less levels is not permitted.
Within the intersection of the source(s) and domain, each output pixel is a blend of the corresponding 
pixels from src-1 and src-2 (or src-1 pixels blended with constant).  The degree of blend is determined 
by the corresponding value taken from alpha or the value of alpha-const.  If alpha is non-zero, the pro-
portion of blend is further scaled by alpha-const: 
	output = src-1 * (1 - alpha / alpha-const) + src-2 * (alpha / alpha-const)
		(where alpha-const is greater than 0.0).
If alpha is zero:
	output = src-1 * (1 - alpha-const) + src-2 * alpha-const 
		(where alpha-const is in the range [0.0, 1.0]).
Error	Cause
FloAlloc	insufficient resources
FloSource	invalid src-1, src-2, or alpha
FloDomain	invalid domain
FloMatch	incompatible attributes between src-1 and src-2
alpha is Unconstrained
selected source data are bitonal (i.e. 2 or less levels)
FloValue	alpha is zero and alpha-const is outside the range [0.0, 1.0]
alpha is non-zero and alpha-const is zero or negative
Compare
XieFloCompare
src-1	XieTypPhototag
src-2	XieTypPhototag
domain	XieTypProcessDomain
constant	XieTypConstant
operator	XieTypCompareOp
combine	BOOL
band-mask	CARD8
Errors:	FloAlloc, FloSource, FloDomain, FloMatch, FloOperator
Events:	none
Attribute	Value
class	see text
type	Constrained
width	same as src-1
height	same as src-1
levels	2 per band (see text)
Compare takes two data sources or a single data source and a constant and generates a Boolean bitmap 
output which reflects the results of a point-wise comparison.  The output data has a value of 1 wherever 
the comparison is true, and a value of 0 everywhere else (i.e. comparison false or comparison not per-
formed).  Compare may be requested on a per-band basis, or for all bands taken together. 
When two sources are involved, src-1 and src-2 are the Phototags of the elements supplying source 
data (constant is ignored). If the operation is to involve a constant, src-1 is one operand, src-2 must be 
zero, and constant is used as the other operand.  Domain may control the subset of source data that 
will be compared.  Operator is the logical predicate operator used in the comparison. Combine is a 
Boolean which determines if the comparison should be done on a per-band basis, or on an all bands 
basis.  Band-mask specifies which bands are to be involved. 
If combine is true or src-1 is SingleBand, the output data will form a single Boolean bitmap.  If src-1 is 
TripleBand and combine is false, the output data will yield three separate Boolean bitmaps (for this 
case band-mask must specify all bands).
If src-1 is TripleBand and combine is true, only the EQ and NE operators are allowed;  equality is 
established for each band selected by band-mask, and then the result is logically ANDed to derive 
equality (inequality is a logical NOT of this result).  For this case, width and height must match for all 
bands selected by band-mask.
combine
input class
band-mask
output class

True
SingleBand
TripleBand
n/a
selected bands
SingleBand
SingleBand

False
SingleBand
TripleBand
n/a
all bands
SingleBand
TripleBand

Table 7-1   Compare parameter and DataClass dependencies
When two sources are involved, all attributes, other than width and height, must match.  The com-
parison is performed over the intersect of the source(s) as restricted by domain.  All points not com-
pared are given the value zero (0). 
Error	Cause
FloAlloc	insufficient resources
FloSource	invalid src-1 or src-2
FloDomain	invalid domain
FloOperator	invalid operator
FloMatch	class differs between src-1 and src-2
invalid combination of operator and combine
TripleBand, and combine is false, and band-mask incomplete
Compare does not support inter-band distance metrics, therefore combined  LT, LE, GT, and GE operators are not 
supported. Clients may implement these using other elements in concert with Compare. 
Typical uses for Compare include: creating data to be used as a control-plane for a ProcessDomain, and converting 
index data into bitonal image data. 


Constrain
XieFloConstrain
src	XieTypPhototag
levels	XieTypLevels
constrain	XieTypConstrainTechnique
constrain-params	<technique-dependent>
Errors:	FloAlloc, FloSource, FloTechnique
Events:	none
Attribute	Value
class	same as src
type	Constrained
width	same as src
height	same as src
levels	levels
Constrain applies a quantization model to the image data to convert the data to a fixed number of 
quantization levels.  Application of the quantization model may involve steps such as range shifting, 
scaling, clipping, and rounding. 
Src is the Phototag of the element supplying source data.  Levels is the number of quantization levels 
desired in the output data.  Constrain specifies the ConstrainTechnique to be used when constraining 
the data.  Constrain-params is the list of additional parameters required by constrain. 
If the input image is already Constrained the data will be re-Constrained. 
No subsetting by band mask or ProcessDomain is provided (the entire image is Constrained). 
Error	Cause
FloAlloc	insufficient resources
FloSource	invalid src
FloTechnique	invalid constrain technique or constrain-params


ConvertFromIndex
XieFloConvertFromIndex
src	XieTypPhototag
colormap	COLORMAP
class	XieTypDataClass
precision	CARD8
Errors:	FloAlloc, FloSource, FloColormap, FloMatch, FloValue
Events:	none
Attribute	Value
class	class
type	Constrained
width	same as src
height	same as src
levels	2precision (per band)
ConvertFromIndex converts COLORMAP index data into achromatic or trichromatic data. 
Src is the Phototag of the element supplying source data.  Colormap is the COLORMAP from which to 
obtain the value for each output pixel.  Class specifies the DataClass of the desired output data.  
Precision specifies how many bits (most significant) are to be used from the red, green, and blue values 
found in colormap. 
If class is SingleBand and a trichromatic colormap is specified (StaticColor, PseudoColor, 
TrueColor, or DirectColor), the gray shade for each pixel is taken from the red values in col-
ormap. 
If class is TripleBand and an achromatic colormap is specified (StaticGray or GrayScale), the 
red band will be replicated to populate the green and blue output bands. 
The depth of colormap must match the levels attribute of src (i.e. 2depth must equal levels). 
No subsetting by band mask or ProcessDomain is provided (the entire image is converted). 
Error	Cause
FloAlloc	insufficient resources
FloSource	invalid src
FloColormap	invalid colormap
FloMatch	levels of src do not match depth of colormap
FloValue	invalid class or precision
To achieve predictable results, the client should not modify colormap cells referenced by the source data while the 
Photoflo is Active (see Await for synchronization help). 
A value of bitsPerRGBValue or less (defined in the VISUAL of colormap) is usually appropriate for precision.
Compare can be used to convert index data into bitonal data.  Use ConvertFromIndex followed by BandExtract to 
convert colored index data into full fidelity achromatic data. 


ConvertFromRGB
XieFloConvertFromRGB
src	XieTypPhototag
convert	XieTypConvertFromRGBTechnique
convert-params	<technique-dependent>
Errors:	FloAlloc, FloSource, FloMatch, FloTechnique
Events:	none
Attribute	Value
class	TripleBand
type	convert technique dependent
width	same as src
height	same as src
levels	convert technique dependent
ConvertFromRGB converts RGB source data to an alternate colorspace. 
Src is the Phototag of the element supplying source data (RGB assumed).  Convert is the Convert-
FromRGBTechnique that will be used in the conversion to the destination colorspace.  Convert-
params is the list of additional parameters required by convert. 
In addition to colorspace conversion, some techniques allow for adjusting the white point of the output 
data (refer to Appendix A Convert From RGB Technique, for more information on conversion 
techniques). 
The source data must be TripleBand, and all bands must have equal dimensions. The type and levels 
of the output data are determined by convert technique parameters.  All other attributes are inherited 
from src.
No subsetting by ProcessDomain is provided (the entire image is processed). 
Error	Cause
FloAlloc	insufficient resources
FloSource	invalid src
FloMatch	src is not TripleBand
unequal inter-band dimensions (width or height)
FloTechnique	invalid convert or convert-params


ConvertToIndex
XieFloConvertToIndex
notify	BOOL
src	XieTypPhototag
colormap	COLORMAP
color-list	XieTypColorList
color-alloc	XieTypColorAllocTechnique
color-alloc-params	<technique-dependent>
Errors:	FloAlloc, FloSource, FloColormap, FloColorList, FloMatch, FloValue
Events:	none
Attribute	Value
class	SingleBand
type	Constrained
width	same as src
height	same as src
levels	2depth (i.e. colormap depth)
ConvertToIndex allocates and/or matches colors or gray shades, as required, from a COLORMAP.  It 
produces pixel indices as output data, and records indices that it allocates in a ColorList.  The specified 
color-alloc technique may generate a ColorAlloc event to warn the client that results are of lesser fidel-
ity than desired. 
Notify allows the client to be notified about inferior results from color allocation or matching.  Src is the 
Phototag of the element supplying Constrained source data.  Colormap is the COLORMAP from which 
colors or gray shades are allocated and/or matched.  Color-list is the ColorList where allocated COL-
ORMAP indices are to be stored.  Color-alloc specifies the desired ColorAllocTechnique.  Color-alloc-
params is the list of additional parameters required by color-alloc. 
Color-list is purged of any colors it already contains when Photoflo execution begins.  Allocated 
COLORMAP indices can be freed using PurgeColorList, DestroyColorList, or by making color-list the 
target of an Active Photoflo. 
Error	Cause
FloAlloc	insufficient resources
FloSource	invalid src
FloColormap	invalid colormap
FloColorList	invalid color-list
FloAccess	color-list is already being used by another Active Photoflo
FloMatch	unequal inter-band dimensions (width or height)
FloTechnique	invalid color-alloc technique or color-alloc-params
ConvertToIndex is usually a preparatory step for an ExportDrawable element.  Alternatively, continuous-tone data 
can be converted to a fixed palette of COLORMAP index entries using Point.  Or BandExtract can be used if the 
COLORMAP contains a ramp of colors or gray shades (e.g. a Standard-COLORMAP or a TrueColor visual).  
Bitonal image data can be presented directly to ExportDrawablePlane, allowing the GCONTEXT mechanism to 
translate ones and zeros in the image into foreground and background colors in the DRAWABLE. 
If colormap is static, image colors or gray shades must be matched to those available in colormap.  Since no cells 
are actually allocated, color-list can be specified as zero (0).  Of the three standard techniques defined in this document 
only ColorAlloc_Match is appropriate for static COLORMAPs.  If colormap is dynamic, image colors or gray 
shades may be matched or allocated from colormap depending on the color-alloc technique; colormap and the list of 
cells actually allocated are stored in color-list.
Although the three standard techniques defined in this document allocate read-only cells, ConvertToIndex could be 
extended with private techniques that allocate, match, or write into read-write cells.


ConvertToRGB
XieFloConvertToRGB
src	XieTypPhototag
convert	XieTypConvertToRGBTechnique
convert-params	<technique-dependent>
Errors:	FloAlloc, FloSource, FloTechnique
Events:	none
Attribute	Value
class	TripleBand
type	convert technique dependent
width	same as src
height	same as src
levels	convert technique dependent
ConvertToRGB converts alternate colorspace source data into RGB data. 
Src is the Phototag of the element supplying source data.  Convert is the ConvertFromRGBTechnique 
that will be used in the conversion from the source colorspace.  Convert-params is the list of additional 
parameters required by convert.  
In addition to colorspace conversion, some techniques allow for adjusting the white point of the source 
data prior to conversion and compressing the gamut of the output data (refer to Appendix A Convert 
To RGB Technique, for more information on conversion techniques). 
The source data must be TripleBand, and all bands must have equal dimensions. The type and levels 
of the output data are determined by convert technique parameters.  All other attributes are inherited 
from src.
No subsetting by band mask or ProcessDomain is provided (the entire image is converted). 
Error	Cause
FloAlloc	insufficient resources
FloSource	invalid src
FloMatch	src is not TripleBand
unequal inter-band dimensions (width or height)
FloTechnique	invalid convert or convert-params
Arithmetic or Point can be used to gamma-correct the resulting data prior to displaying it. 


Convolve
XieFloConvolve
src	XieTypPhototag
domain	XieTypProcessDomain
kernel	LISTofXieTypFloat
kernel-size	CARD8
band-mask	CARD8
convolve	XieTypConvolveTechnique
convolve-params	<technique-dependent>
Errors:	FloAlloc, FloSource, FloDomain, FloMatch, FloValue, FloTechnique
Events:	none
Attribute	Value
class	same as src
type	same as src
width	same as src
height	same as src
levels	same as src
Convolve produces output data by convolving each input pixel value (and surrounding area) with the 
specified convolution kernel.
Src is the Phototag of the element supplying source data.  Domain may control the subset of the image 
that will be operated upon.  Kernel contains the coefficients used in the convolution process.  Kernel-
size specifies the dimension of kernel.  Band-mask specifies which bands are to be operated upon.   
Convolve specifies the ConvolveTechnique for handling edge conditions (when kernel requires data 
outside of src).  Convolve-params is the list of additional parameters required by convolve.  
Kernel represents a square array of float data which has odd dimensions.  Thus, a single dimension is 
used to specify, kernel-size. 
Using band-mask to select source data that have two (2) or less levels is not permitted.
All output data attributes are inherited from the source data. 
Error	Cause
FloAlloc	insufficient resources
FloSource	invalid src
FloDomain	invalid domain
FloMatch	selected source data are bitonal (i.e. 2 or less levels)
FloValue	invalid kernel-size (e.g. not odd)
FloTechnique	invalid convolve edge handling technique or convolve-params
For TripleBand data, convolution using the same kernel is permuted over all three bands.


Dither
XieFloDither
src	XieTypPhototag
levels	XieTypLevels
band-mask	CARD8
dither	XieTypDitherTechnique
dither-params	<technique-dependent>
Errors:	FloAlloc, FloSource, FloValue, FloMatch, FloTechnique
Events:	none
Attribute	Value
class	same as src
type	Constrained
width	same as src
height	same as src
levels	levels
Dither is used to reduce the number of quantization levels in an image.  It accomplishes this by af-
fecting adjacent pixels (area affect) to make up for the lack of depth resolution. 
Src is the Phototag of the element supplying source data.  Levels is the number of levels desired in the 
output data.  Band-mask specifies which bands are to be operated upon.  Dither specifies the desired 
DitherTechnique.  Dither-params is the list of additional parameters required by dither. 
The source data must be Constrained.  Using band-mask to select source data that have two (2) or less 
levels is not permitted.
No subsetting by band mask or ProcessDomain is provided (the entire image is processed). 
Error	Cause
FloAlloc	insufficient resources
FloSource	invalid src
FloMatch	Unconstrained src data
selected source data are bitonal (i.e. 2 or less levels)
FloValue	invalid output levels: less than two, or greater than src levels
FloTechnique	invalid dither technique or dither-params


Geometry
XieFloGeometry
src	XieTypPhototag
width	CARD32
height	CARD32
coefficients	XieTypFloat[6]
constant	XieTypConstant
band-mask	CARD8
sample	XieTypGeometryTechnique
sample-params	<technique-dependent>
Errors:	FloAlloc, FloSource, FloValue, FloTechnique
Events:	none
Attribute	Value
class	same as src
type	same as src
width	width
height	height
levels	same as src
Geometry is used to perform geometric transformations on image data.  Linear geometric resampling 
operations are implemented, such as: crop, mirror, scale, shear, rotate, translate, and combinations 
thereof. 
Src is the Phototag of the element supplying source data.  Width and height specify the dimensions of 
the output data.  Coefficients is a list of values (a,b,c,d,tx,ty) that control the geometric transforma-
tion.  Constant is a fill value used for output pixels that do not map back to a src pixel.  Band-mask 
specifies which bands are to be operated upon.  Sample is the GeometryTechnique to be used for ret-
rospectively resampling src.  Sample-params is the list of additional parameters required by sample. 
Figure 7-2 shows a combined crop and scale for a src with dimensions w and h, and output width w' 
and height h'. The mapping between the coordinate systems is specified from output back to src: that 
is, for each output pixel (x',y'),  the coordinate location (x,y) at which to sample src is given by:

  
Geometry can be visualized as stepping through each possible output pixel location in turn, and 
computing the location from which to obtain each input pixel value.  Often a given output pixel location 
(x',y'), will not correspond exactly to a single pixel in the input image.  The sample technique is used 
to determine how the input data will be interpolated to produce each output pixel value.
 
Figure 7-2   A sample geometric transform: crop and scale
The region to be cropped in the input image is implicitly defined by the dimensions of the output image 
and the mapping from output to input coordinates.  Depending on the size of the input and output 
images, the amount of scaling specified, and the amount of translation in the mapping,  the shadow of 
the output image may extend beyond the boundaries of the input image, as in Figure 7-3.  Pixels in the 
output image which map off the edge of the input image will be assigned the constant value.
 
Figure 7-3   Background fill used for pixels beyond the edge
Transformation Coefficients
The coordinate mapping (a,b,c,d,tx,ty), together with the output width and height, fully specify the 
geometric transformation.   To aid in computing the desired transform, one might:
*	Draw a picture of the input and output images.  Label  the corners of the output image A,B,C,D.  They will have 
coordinates x',y' at (0,0),  (width-1,0),  (0,height-1), and (width-1,height-1),
*	Next compute or deduce the coordinates (x,y) of A,B,C,D in the input coordinate space,
*	For three corners (preferably those with a 0 for either x' or y'), write down the basic mapping equation with 
known (x,y) and (x',y') specified.  Each corner will give two equations, and simultaneously solving the six 
equations for the three corners will allow (a,b,c,d,tx,ty) to be deduced. The remaining corner may be used to 
check that these parameters have been derived correctly.
The following briefly (and approximately) summarizes the intuitive role of each parameter:
a,d	Scaling parameters. Increasing a and d will make the output image appear smaller, 
whereas decreasing them will make the output pixels appear larger.
b,c	Rotation/skew parameters. If b and c are zero, the output image will be a 
rectangular scaling of the input image.  If a and d are both zero, b is one and c is 
negative one, the image will appear rotated.  The magnitude of b and c will affect 
scaling as well, if a and d are zero.  If  more than two of (a,b,c,d) are non-zero, 
the effect is complicated. The image may appear skewed and scaled. 
tx,ty	Translation parameters. Used to specify the offset between input and output 
coordinate systems.
width,height	These specify the output image dimensions of the selected band(s).  Note that 
increasing the output image height and width over the input image size will not by 
itself cause magnification  if a and d are one (1) and b and c are zero (0),  the 
output image will have the same appearance as the input, except that the borders 
will shrink or expand (as determined by width and height) and new areas of the im-
age will be filled with constant. 

Trichromatic image bands can be operate individually, all together, or in any combination, using band-
mask. Since applying the same (a,b,c,d,tx,ty) mapping to inputs with diverse sizes will specify 
different transformations, operating on all bands in unison (band-mask of 1112) is most appropriate if 
the dimensions of all bands are equal.  No subsetting by ProcessDomain is provided (selected bands 
are processed in their entirety). 
Error	Cause
FloAlloc	insufficient resources
FloSource	invalid src
FloValue	invalid coefficients
FloTechnique	invalid sample technique or sample-params
Logical
XieFloLogical
src-1	XieTypPhototag
src-2	XieTypPhototag
domain	XieTypProcessDomain
constant	XieTypConstant
operator	GCfunction*
band-mask	CARD8
Errors:	FloAlloc, FloSource, FloDomain, FloMatch, FloOperator, FloValue
Events:	none
Attribute	Value
class	same as src-1
type	Constrained
width	same as src-1
height	same as src-1
levels	same as src-1
Logical performs per-pixel bit-wise operations on a single data source, or between two data sources, or 
between a single data source and a constant. 
When two sources are involved, src-1 and src-2 are the Phototags of the elements supplying source 
data (constant is ignored). If the operation is to involve a constant, src-1 is one operand, src-2 must be 
zero, and constant is used as the other operand.  Domain may control the subset of source data that 
will be operated upon.  Operator is the logical operator to be used.  Band-mask specifies which bands 
are to be operated upon. 
The value of operator matches the GC-function  values defined by the core protocol 
specification for CreateGC.  The output of Logical is determined by the number of data sources and 
operator:
GC-function1	monadic operation	dyadic operation
Clear	0	0
And	constant AND src-1	src-2 AND src-1
AndReverse	constant AND (NOT src-1)	src-2 AND (NOT src-1)
Copy	constant	src-2
AndInverted	(NOT constant) AND src-1	(NOT src-2) AND src-1
NoOp	src-1	src-1
Xor	constant XOR src-1	src-2 XOR src-1
Or	constant OR src-1	src-2 OR src-1
Nor	(NOT constant) AND (NOT src-1)	(NOT src-2) AND (NOT src-1)
Equiv	(NOT constant) XOR src-1	(NOT src-2) XOR src-1
Invert	NOT src-1	NOT src-1
OrReverse	constant OR (NOT src-1)	src-2 OR (NOT src-1)
CopyInverted	NOT constant	NOT src-2
OrInverted	(NOT constant) OR src-1	(NOT src-2) OR src-1
Nand	(NOT constant) OR (NOT src-1)	(NOT src-2) OR (NOT src-1)
Set	1	1
When two sources are involved, all attributes, other than width and height, must match.  All source 
data must be Constrained, and levels must be a power of two.  Output attributes are inherited from src-
1.
Error	Cause
FloAlloc	insufficient resources
FloSource	invalid src-1 or src-2
FloDomain	invalid domain
FloOperator	invalid operator
FloMatch	src-1 or src-2 is not Constrained
levels or class differs between src-1 and src-2 
levels is not a power of 2


MatchHistogram
XieFloMatchHistogram
src	XieTypPhototag
domain	XieTypProcessDomain
shape	XieTypHistogramShape
tech-params	<technique-dependent>
Errors:	FloSource, FloDomain, FloAlloc, FloMatch, FloTechnique
Events:	none
Attribute	Value
class	SingleBand
type	Constrained
width	same as src
height	same as src
levels	same as src
MatchHistogram produces output data which differs from the source data in terms of its pixel value 
distribution, or histogram. It allows the client to specify the desired state of the resulting data's histo-
gram (algorithmic description of resulting histogram shape). 
Src is the Phototag of the element supplying source data.  Domain may control the subset of the source 
data to operated upon.  Shape is a HistogramShape that specifies the form of the desired output data 
histogram.  Shape-params is the list of additional parameters required by shape. 
The source data must be Constrained and SingleBand, and it must have three (3) or more levels.
When a ProcessDomain is used, only data that intersects with domain is included in the histogram, 
and only that data will be affected in the result of the histogram matching operation (all other data will 
pass-through unchanged).
Error	Cause
FloAlloc	insufficient resources
FloSource	invalid src
FloDomain	invalid domain
FloMatch	invalid src data: Unconstrained or TripleBand or bitonal
FloTechnique	invalid histogram shape or shape-params
The Point element can also be used to re-shape an image's histogram using an appropriate LUT. 


Math
XieFloMath
src	XieTypPhototag
domain	XieTypProcessDomain
operator	XieTypMathOp
band-mask	CARD8
Errors:	FloAlloc, FloSource, FloDomain, FloMatch, FloOperator, FloValue
Events:	none
Attribute	Value
class	same as src
type	same as src
width	same as src
height	same as src
levels	same as src
Math applies a single operand mathematical operation to the source data on a point-wise basis. 
Src is the Phototag of the element supplying source data.  Domain may control the subset of the image 
which will be operated upon.  Operator is the mathematical operation to be applied.  Band-mask speci-
fies which bands are to be operated upon. 
Pixel computations that would lead to errors will yield valid server-dependent values (e.g. the log of a 
Constrained pixel value of zero might result in a value of zero).  Using band-mask to select source data 
that have two (2) or less levels is not permitted.
All output data attributes are inherited from the source data. 
Error	Cause
FloAlloc	insufficient resources
FloSource	invalid src
FloDomain	invalid domain
FloMatch	selected source data are bitonal (i.e. 2 or less levels)
FloOperator	invalid operator


PasteUp
XieFloPasteUp
tiles	LISTofXieTypTile
width	CARD32
height	CARD32
constant	XieTypConstant
Errors:	FloAlloc, FloSource, FloMatch
Events:	none
Attribute	Value
class	same as tiles
type	same as tiles
width	width
height	height
levels	same as tiles
PasteUp is an N-input translate operation which outputs data constructed from various source data tiles 
or a constant value. 
Each of the tiles specifies a src (the Phototag of the element supplying source data), and the coordi-
nates, dst-x and dst-y, where the tile belongs in the output data.  Width and height specify the full extent 
of the output data.  Constant is the fill value to as the output data for any region that is not specified as 
a tile.
Each region of the output data is defined by a tile's destination coordinates, dst-x and dst-y, and its src 
dimensions.  For output regions where no tile provides input, the value of constant is used.  If tiles 
overlap, a stacking order rule defines which pixel value will be output: the last tile (involved in the 
overlap) in the list of tiles will provide the output pixel. 
At least one tile must be supplied.  Except for width and height, all attributes of each source tile must 
match.  In addition, for TripleBand input, inter-band dimensions within each tile must match.
No subsetting by band mask or ProcessDomain is provided.
Error	Cause
FloAlloc	insufficient resources
FloSource	invalid source tiles
no tiles were specified
FloMatch	incompatible attributes between tiles
unequal inter-band dimensions within a tile (width or height)


Point
XieFloPoint
src	XieTypPhototag
lut	XieTypPhototag
domain	XieTypProcessDomain
band-mask	CARD8
Errors:	FloAlloc, FloSource, FloDomain, FloMatch
Events:	none
Attribute	Value
class	same as lut
type	Constrained
width	same as src
height	same as src
levels	same as lut
Point maps source pixel values to output pixel values using a lookup table (LUT) .
Src is the Phototag of the element supplying Constrained source data.  Lut is the Phototag of the 
element supplying the lookup table array(s).  Domain may control the subset of source data which will 
be operated upon.  Band-mask specifies which bands are to be operated upon (all bands must be 
specified if lut is SingleBand and src is TripleBand).
The output is Constrained, with the width and height taken from src, and class and levels taken from 
lut.  When src is SingleBand and lut is TripleBand, for the bands that are indicated by band-mask, the 
output bands are re-mapped through their respective lut bands, whereas the other bands are just 
replications of the single src band.  If domain is used, the class and levels of lut must match those of 
src.
Each lut array must contain sufficient entries so that all potential pixel values found in src can form a 
valid index into the array.  Generally each src pixel value is used directly as an index into a lut array. 
When TripleBand src data are re-mapped through a SingleBand lut however, pixel values from all three 
src bands are combined to form an array index (for this case, width and height must match for all 
bands).  Figure 7-4 presents the algorithm for computing combined array indices.

LUT band-order
LUT indexing algorithm for combining pixel values from TripleBand data

LSFirst
index = value[0] + value[1] x levels[0] + value[2] x levels[0] x levels[1]

MSFirst
index = value[2] + value[1] x levels[2] + value[0] x levels[2] x levels[1]

Figure 7-4   Point's algorithm for computing combined LUT indices
Error	Cause
FloAlloc	insufficient resources
FloSource	invalid src or lut
FloDomain	invalid domain (e.g. attempting to use domain with ServiceClass DIS)
FloMatch	Unconstrained src data
lut does not contain enough entries (i.e. length less than src levels)
lut is SingleBand and src is TripleBand, but band-mask is incomplete
domain is being used, but lut class or levels do not match those of src
Unconstrain
XieFloUnconstrain
src	XieTypPhototag
Errors:	FloAlloc, FloSource, FloMatch
Events:	none
Attribute	Value
class	same as src
type	Unconstrained
width	same as src
height	same as src
levels	unknown
Unconstrain takes Constrained source data and produces Unconstrained data. 
Src is the Phototag of the element supplying Constrained source data.
No subsetting by band mask or ProcessDomain is provided (the entire image is Unconstrained). 
Error	Cause
FloAlloc	insufficient resources
FloSource	invalid src
FloMatch	Unconstrained src

 	GC-function is not a defined type in the core X protocol documentation.  This table is taken from the list of 
alternative function values defined for the CreateCG protocol request.
 	Figure 6-1 illustrates the relationship between LUT class and image class and presents some usage examples.
 

Process Elements   7-26


8
Export Elements
Element categories
Export elements are used to send image data out of a Photoflo.  Each export element has a single Photo-
tag source but does not provide an output connection.  There are two types of export elements:
  ExportResource elements export data to a server resource (DRAWABLE, LUT, Photomap, or ROI).
  ExportClient elements produce data for client retrieval. They provide the input data for the GetClient-
Data protocol request.
Export to Client
ExportClient elements provide data for the client. Element parameters fully describe the format or 
organization the data is to have as it is transported through the protocol stream.  The data itself must be 
retrieved using the GetClientData protocol request while the Photoflo is Active. 
Servers are required to buffer a non-zero amount of data per ExportClient element.  Beyond that 
point execution may be suspended until the client retrieves sufficient data. 
Events generated
ExportClient elements can generate ExportAvailable events to notify the client when the data is 
available for retrieval.  ExportAvailable events may be:
  disabled (i.e. no event is sent),
  enabled only when data first becomes available from the element,
  enabled each time the element's data buffer transitions from empty to non-empty.


ExportClientHistogram
XieFloExportClientHistogram
notify	XieTypExportNotify
src	XieTypPhototag
domain	XieTypProcessDomain
Errors:	FloAlloc, FloSource, FloDomain, FloMatch, FloValue
Events:	none
ExportClientHistogram generates a histogram of the pixel values found in the source data.  It prepares 
histogram data that can be retrieved by the client using the GetClientData protocol request.  An event 
can be requested that will notify the client when histogram data becomes available.
Notify allows the client to be notified when the histogram data becomes available.  Src is the Phototag 
of the element supplying SingleBand Constrained source data.  Domain may control the subset of the 
source data from which the distribution will be generated.  
The data generated for the client is a list of HistogramData where each entry consists of an value (i.e. a 
pixel value) followed by the count of pixels found with that value.  If the number of pixels for a given 
value exceeds the capacity of count (type CARD32), that count will be returned at the maximum value 
(i.e. 232-1).  Pixel values that are not found in the data are not included in the histogram data (i.e. no 
entries are returned where count is zero). 
If notify is true, the total number of histogram entries are reported in the data field of the ExportAvail-
able event. 
The histogram is returned as numeric values (see HistogramData), as such, the byte order of the data is 
determined at core protocol connection setup time.
Error	Cause
FloAlloc	insufficient resources
FloSource	invalid src
FloDomain	invalid domain
FloMatch	Unconstrained src data
TripleBand src data
FloValue	invalid notify
All data that are generated by ExportClientHistogram must be retrieved by the client using GetClientData before 
the Photoflo can exit from the Active state. 
Histograms of TripleBand images are not supported directly.  However, BandSelect may be used to choose a single 
band of data, or BandExtract may be used to combine data from multiple bands into a single band of data.  A histogram 
of this single band of data could then be generated using ExportClientHistogram. 


ExportClientLUT
XieFloExportClientLUT
notify	XieTypExportNotify
src	XieTypPhototag
band-order	XieTypOrientation
start	XieTypTripletofCARD32
length	XieTypTripletofCARD32
Errors:	FloAlloc, FloSource, FloValue
Events:	none
ExportClientLUT allows data imported from an ImportLUT or ImportClientLUT element to be retrieved 
by the client.  The actual transport of lookup table data through the protocol stream is requested using 
the GetClientData protocol request. 
Notify allows the client to be notified when data become available.  Src is the Phototag of the element 
supplying lookup table data.  Band-order is the order in which TripleBand arrays are transmitted 
through the protocol stream.  Start is the index of the first array entry that should be returned.  Length 
is the number of array entries that should be returned.
If notify is requested, the ExportAvailable event's data field will report the total number of array entries 
that can be retrieved from the band specified by the event.
The size of each array entry is either 1, 2, or 4 bytes; the smallest size into which the output quantization 
levels can be stored.  When array entries require multiple bytes, the byte order per entry is determined 
in the same manner as other numeric data: it is the byte orientation established at core X connection 
setup time. 
Error	Cause
FloAlloc	insufficient resources
FloSource	invalid src
FloMatch	start + length exceeds number of entries in an array
FloValue	invalid notify or band-order
When the client attempts to retrieve data from an ExportClientLUT element, the server responds with one or more 
complete array entries per protocol reply (see GetClientData).  All data must be retrieved by the client before the 
Photoflo can leave the Active state. 


ExportClientPhoto
XieFloExportClientPhoto
notify	XieTypExportNotify
src	XieTypPhototag
encode	XieTypEncodeTechnique
encode-params	<technique-dependent>
Errors:	FloAlloc, FloSource, FloMatch, FloValue, FloTechnique
Events:	none
ExportClientPhoto makes image data available to the protocol stream.  The attributes of the exported 
data are determined by the attributes of the source data.  The format of the data is specified by the en-
code technique and encode-params.  The actual transport of image data through the protocol stream is 
requested using the GetClientData protocol request. 
Notify allows the client to be notified when image data become available.  Src is the Phototag of the 
element supplying Constrained data.  Encode is the EncodeTechnique that will be used to compress of 
format the exported data.  Encode-params is the list of additional parameters required by encode. 
Error	Cause
FloAlloc	insufficient resources
FloSource	invalid src
FloMatch	Unconstrained src data
FloValue	invalid notify
FloTechnique	invalid encode technique or encode-params
ServerChoice is not a valid encode technique for ExportClientPhoto.
Depending on encode, the export process may cause the data to be decoded, encoded, or otherwise reformatted by the 
server.  If ExportClientPhoto is fed directly from an ImportClientPhoto or ImportPhotomap element, and the 
attributes of the raw data that are given to the import element match the requirements of the encode technique, the 
raw data can bypass the normal decode function of the import element and be forwarded directly to ExportPhotomap 
(this is an implementation-specific optimization).
If TripleBand data are given to an encode technique that will interleave the output data BandByPixel, the dimensions 
of each src band must match.
All data must be retrieved by the client, using the GetClientData protocol request, before the Photoflo can exit from 
the Active state. 



ExportClientROI
XieFloExportClientROI
notify	XieTypExportNotify
src	XieTypPhototag
Errors:	FloAlloc, FloSource, FloValue
Events:	none
ExportClientROI allows a list-of-rectangles, imported from an ImportROI or ImportClientROI element, 
to be retrieved by the client.  The actual transport of lookup table data through the protocol stream is 
requested using the GetClientData protocol request. 
Notify allows the client to be notified when data become available.  Src is the Phototag of the element 
supplying the list-of-rectangles. 
If notify is requested, the ExportAvailable event's data field will report the total number of rectangles 
that can be retrieved.
Each rectangle is described using numeric values (see Rectangle), as such, the byte order of the data is 
determined at core protocol connection setup time.
Error	Cause
FloAlloc	insufficient resources
FloSource	invalid src
FloValue	invalid notify
When the client attempts to retrieve data from an ExportClientROI element, the server responds with one or more 
complete Rectangles per protocol reply (see GetClientData).  All data must be retrieved by the client before the 
Photoflo can leave the Active state. 


Export to Resource
ExportResource elements emit data to server resources: either core X DRAWABLEs, or XIE LUT, 
Photomap, or ROI resources. 
For ExportResource elements that assign attributes to XIE resources, the association between the 
resource identifier (XID) and the new attributes and data does not occur until the Photoflo successfully 
completes (i.e. leaves the Active state).   (See LUT, Photomap, and ROI resources in Chapter 4.)
ExportDrawable
XieFloExportDrawable
src	XieTypPhototag
drawable	DRAWABLE
gc	GCONTEXT
dst-x	INT16
dst-y	INT16
Errors:	FloAlloc, FloSource, FloDrawable, FloGC, FloMatch, FloValue
Events:	none
ExportDrawable allows COLORMAP index data to be exported to a WINDOW or PIXMAP. 
Src is the Phototag of the element supplying Constrained source data (index data assumed).  Drawable 
is the WINDOW or PIXMAP into which the data will be written.  Gc is the GCONTEXT to be used when 
transferring pixels to drawable.  Dst-x and dst-y specify where the data should be placed in drawable. 
The following components are used from gc: function, plane-mask, subwindow-mode, 
clip-x-origin, clip-y-origin, and clip-mask. 
The levels of src must exactly match the depth of drawable and gc (i.e. levels must be 2depth). 
Error	Cause
FloAlloc	insufficient resources
FloSource	invalid src
FloDrawable	invalid drawable
FloGC	invalid gc
FloMatch	invalid src data (TripleBand, levels doesn't match depth, or Unconstrained)
ExportDrawable assumes its input is COLORMAP index data.  Sources of such data include: ImportClientPhoto, 
ImportDrawable, ImportPhotomap, BandExtract, ConvertToIndex, Point, and elements that have processed 
index data. 


ExportDrawablePlane
XieFloExportDrawablePlane
src	XieTypPhototag
drawable	DRAWABLE
gc	GCONTEXT
dst-x	INT16
dst-y	INT16
Errors:	FloAlloc, FloSource, FloDrawable, FloGC, FloMatch, FloValue
Events:	none
ExportDrawablePlane allows SingleBand single bit (bitonal) data to be exported to a WINDOW, 
PIXMAP, or BITMAP. 
Src is the Phototag of the element supplying Constrained bitonal source data.  Drawable is the WIN-
DOW, PIXMAP, or BITMAP into which the data will be written.  Gc is the GCONTEXT to be used when 
transferring pixels to drawable.  Dst-x and dst-y specify where the data should be placed in drawable. 
The following components are used from gc: function, plane-mask, foreground, back-
ground, fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and clip-
mask.  For the fill-style component of gc, values of FillSolid and FillTiled are treated 
as synonyms for FillOpaqueStippled. 
Error	Cause
FloAlloc	insufficient resources
FloSource	invalid src
FloDrawable	invalid drawable
FloGC	invalid gc
FloMatch	invalid src data (TripleBand, levels > 2, or not Constrained)
Bitonal data can be exported to a DRAWABLE of any depth if an appropriate GCONTEXT is supplied.  The 
foreground and background pixel values of gc can be used to map image pixels to COLORMAP colors during the 
export process. 


ExportLUT
XieFloExportLUT
src	XieTypPhototag
lut	XieTypLUT
merge	BOOL
start	XieTypTripletofCARD32
Errors:	FloAlloc, FloSource
Events:	none
ExportLUT allows data imported from an ImportLUT or ImportClientLUT element to be saved in an ex-
isting LUT resource. 
Src is the Phototag of the element supplying lookup table data.  Lut is the LUT to receive the data.  
Merge specifies that new array entries from src should replace entries that already exist within lut.  Start 
is the index of the first array entry that should be written in lut.
If merge is false, start must be 0 for each band.  In this case, lut will inherit the attributes of src and be 
populated with its data.  The previous attributes and data of lut are overwritten when the photoflo 
completes. 
If merge is true and lut has existing attributes, the data from src will replace the data from lut, beginning 
at position start.  The attributes of src must match those of lut, and the combination of start and the 
length of src must specify a valid sub-range existing within lut.  If merge is true but lut has not yet been 
populated, it is an error.
Error	Cause
FloAlloc	insufficient resources
FloSource	invalid src
FloLUT	invalid lut
FloMatch	merge true and attributes do not match between src and lut
merge true and start + src length is not a sub-range of lut
FloValue	merge false and start is non-zero


ExportPhotomap
XieFloExportPhotomap
src	XieTypPhototag
photomap	XieTypPhotomap
encode	XieTypEncodeTechnique
encode-params	<technique-dependent>
Errors:	FloAlloc, FloSource, FloPhotomap, FloTechnique
Events:	none
ExportPhotomap allows data resulting from Photoflo operations to be saved in an existing Photomap. 
Src is the Phototag of the element supplying source data.  Photomap is the Photomap to receive the 
data.  Encode is the EncodeTechnique by which the image is to be compressed or formatted. Encode-
params is the list of additional parameters required by encode. 
Photomap will inherit the attributes of src and be populated with its data.  The previous attributes and 
data of photomap are overwritten when the Photoflo completes. 
Error	Cause
FloAlloc	insufficient resources
FloSource	invalid src
FloPhotomap	invalid photomap
FloTechnique	invalid encode technique or encode-params
Depending on encode, the export process may cause the data to be decoded, encoded, or otherwise reformatted by the 
server.  If ExportPhotomap is fed directly from an ImportClientPhoto or ImportPhotomap element, and the 
attributes of the raw data that are given to the import element match the requirements of the encode technique, the 
raw data can bypass the normal decode function of the import element and be forwarded directly to ExportPhotomap 
(this is an implementation-specific optimization).
If encode is ServerChoice, the server is free to choose an encode technique for the exported data.  An optional hint 
can be provided to help the server make its choice, but the server can ignore the hint. PreferTime hints that retrieval 
performance is the desired metric, whereas PreferSpace indicates that frugal use of storage space is more important.  If 
ExportPhotomap is receiving data from an adjacent upstream import element, ServerChoice may choose to pass the 
import element's input data directly to the Photomap, otherwise a lossless technique will be chosen. The actual 
technique chosen by the server can be obtained using QueryPhotomap after the Photoflo completes.
If TripleBand data are given to an encode technique that will interleave the output data BandByPixel, the dimensions 
of each src band must match.


ExportROI
XieFloExportROI
src	XieTypPhototag
roi	XieTypROI
Errors:	FloAlloc, FloSource, FloROI
Events:	none
ExportROI allows data imported from an ImportROI or ImportClientROI element to be saved in an ex-
isting ROI. 
Src is the Phototag of the element supplying a list-of-rectangles.  Roi is the ROI to receive the data. 
Roi will be populated with new data.  The previous data of roi are overwritten after the Photoflo 
completes. 
Error	Cause
FloAlloc	insufficient resources
FloSource	invalid src
FloROI	invalid roi

Export Elements   8-1


9
Events and Errors
Events
ColorAlloc
XieEvnColorAlloc
instance	XieTypExecutable
src	XieTypPhototag
type	ConvertToIndex
color-list	XieTypColorList
color-alloc	XieTypColorAllocTechnique
data	CARD32
A ColorAlloc event notifies the client that a ConvertToIndex element has completed color allocation, 
but has produced a result of lesser fidelity than was requested using the technique that was specified 
for the ConvertToIndex element. 
Instance, src, and type identify the Photoflo and specific ConvertToIndex element from which the 
ColorAlloc event originated.  Color-list is the ColorList resource that received the allocated colors.  
Color-alloc is the ColorAllocTechnique specified to the ConvertToIndex element.  Data can be used 
for other information which is specific to color-alloc. 


DecodeNotify
XieEvnDecodeNotify
instance	XieTypExecutable
src	XieTypPhototag
type	{ ImportClientPhoto, ImportPhotomap }
decode	XieTypDecodeTechnique
data-width	CARD32
data-height	CARD32
band-number	CARD8
aborted	BOOL
A DecodeNotify event notifies the client that anomalies were encountered while decoding a compressed 
image (see the notify parameters of ImportClientPhoto and ImportPhotomap). Either an error has been 
encountered while decoding an image, or the image data received does not satisfy the expected 
dimensions. 
Instance, src, and type identify the Photoflo and element from which the DecodeNotify event originated. 
Decode is the DecodeTechnique being used.  Data-width and data-height are the dimensions 
discovered while decoding the data. Band-number associates the event with the band of the image 
where the problem was encountered.  Aborted is true if decoding was aborted, or false if recovery was 
possible. 
Recovery from a decode error may result in some missing or garbled image data. This may also cause 
the height of the decoded data to be less than was expected.  If data-width or data-height do not 
match the width and height specified to ImportClientPhoto, the image data is clipped or padded (with 
zeros), as required, to enforce the ImportClientPhoto specified dimensions.
ExportAvailable
XieEvnExportAvailable
instance	XieTypExecutable
src	XieTypPhototag
type	{	ExportClientHistogram,
ExportClientLUT,
ExportClientPhoto,
ExportClientROI }
band-number	CARD8
data	LISTofCARD32
An ExportAvailable event notifies the client that an ExportClient element has data available (see 
the notify parameter of the applicable ExportClient element).  If notify was specified as FirstData, 
this event will only be sent the first time data become available from the ExportClient element.  
Otherwise (i.e. NewData was specified) this event will be generated each time the amount of data 
available changes from zero to non-zero.
Instance, src, and type identify the Photoflo and specific ExportClient element from which the 
ExportAvailable event originated. Band-number associates the event with a specific band of the image 
or LUT.  Data is information specific to type (e.g. the number of LUT entries or ROI rectangles avail-
able).
Where there is a single ExportClient element, the client can just read bytes or be event-driven.  For Photoflos 
containing multiple ExportClient elements, the client should be event-driven.


ImportObscured
XieEvnImportObscured
instance	XieTypExecutable
src	XieTypPhototag
type	{ ImportDrawable, ImportDrawablePlane }
window	WINDOW
x	INT16
y	INT16
width	CARD16
height	CARD16
An ImportObscured event notifies the client an ImportDrawable or ImportDrawablePlane element has 
encountered obscured regions in a WINDOW that cannot be retrieved from BACKINGSTORE (see the 
notify parameter of the import element).  A separate ImportObscured event is returned for each affected 
region.
Instance and src identify the Photoflo and the specific import element from which the ImportObscured 
event originated.  Window identifies the WINDOW.  The obscured region of the window is specified by 
x, y, width, and height.
Note: image data within obscured regions will be populated with the fill value supplied to the import element. 
PhotofloDone
XieEvnPhotofloDone
instance	XieTypExecutable
outcome	XieTypPhotofloOutcome
A PhotofloDone event notifies the client that a Photoflo has left the Active state.  It is enabled by the 
notify parameter of the ExecutePhotoflo and ExecuteImmediate requests. 
Instance identifies the Photoflo from which the PhotofloDone event originated.  Outcome indicates the 
reason the Photoflo left the Active state. 
If the Photoflo terminated due to an error condition, the details concerning the error have preceded this event in an 
error message.


Resource Errors
The following error-codes are allocated from the extension error space to provide for the errors returned 
by XIE:
Table 9-1   XIE Error codes
Error	Cause
XieErrColorList	the value for a color-list argument does not name a defined ColorList
XieErrFlo . . .	an error has been detected while defining, executing, or accessing a Photoflo.
See Table 9-2 for additional detail.
XieErrLUT	the value for a lut argument does not name a defined LUT
XieErrPhotoflo	the value for a photoflo argument does not name a defined Photoflo
XieErrPhotomap	the value for a photomap argument does not name a defined Photomap
XieErrPhotospace	the value for a photospace argument does not name a defined Photospace
XieErrROI	the value for a roi argument does not name a defined ROI
XIE also uses the core protocol errors: Access, Alloc, IDChoice, Length, Request, and Value. 


Photoflo errors
If an error is detected while defining, executing, or accessing a Photoflo, a Flo-error is returned.  This 
single error-code is allocated from the extension error space for all Photoflo related errors.  The follow-
ing sub-codes are defined to provide the details of the error:
Table 9-2   Photoflo error sub-codes
Error	Cause
XieErrFloAccess	attempt to execute, modify, or redefine an Active Photoflo
attempt to Get/Put client data from/to an Inactive Photoflo
XieErrFloAlloc	insufficient resources (e.g. memory)
XieErrFloColormap	an unknown COLORMAP has been specified
XieErrFloColorList	an unknown ColorList has been specified
XieErrFloDomain	invalid domain Phototag:
	-	source data is not a list-of-rectangles or control-plane
	-	specified non-zero on a DIS server
XieErrFloDrawable	an unknown DRAWABLE has been specified
XieErrFloElement	an unknown PhotoElement type has been specified
invalid PhotoElement type for request (e.g. GetClientData from Math)
attempt to change or add a PhotoElement type using ModifyPhotoflo
XieErrFloGC	an unknown GCONTEXT has been specified
XieErrFloID	invalid Executable:
	-	an unknown Photoflo has been specified
	-	an unknown Photospace has been specified
XieErrFloLength	a PhotoElement was received with the incorrect number of bytes
XieErrFloLUT	an unknown LUT has been specified
XieErrFloMatch	some parameter or pair of parameters has the correct type and range, but it fails 
to match in some other way required by the PhotoElement
XieErrFloOperator	an unknown operator has been specified (e.g. ArithmeticOp, MathOp, ...)
XieErrFloPhotomap	an unknown Photomap has been specified
XieErrFloROI	an unknown ROI has been specified
XieErrFloSource	an invalid Phototag has been specified:
	-	zero, but a Phototag is required
	-	downstream from the particular PhotoElement
	-	beyond the bounds of the Photoflo
XieErrFloTechnique	an unknown technique has been specified
the wrong number of technique specific parameters have been supplied
invalid technique specific parameters have been specified
XieErrFloValue	some numeric value falls outside of the range of values accepted by the PhotoE-
lement
XieErrFloImplementation























almost blank

Events and Errors   9-1


