X Image Extension Protocol Publication Description: This document describes the protocol of the X WINDOW SYSTEM IMAGE EXTENSION. Version 5.02 X Consortium Standard X Version 11, Release 6.3 December 16, 1996 Copyright © 1988, 1989, 1990, 1991, 1992 Digital Equipment Corporation Copyright © 1990, 1991, 1992, 1993, 1994 X Consortium, Inc. Copyright © 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, the X Consortium, and AGE Logic make no representations 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 subcodes 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 that 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. Because the purpose of this document is to provide a clear, concise articulation of the protocol, ex- pository 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. OReilly & Associates, Inc. The X Window System Server (Israel & Fortune) Guide to the 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 Digital Equipment Corporation Robert W. Scheifler X Consortium, Inc. Ben Fahy Visionary Software, Inc. Jim Fulton Network Computing Devices, Inc. Keith Packard Network Computing Devices, Inc. Joe Mauro Digital Equipment Corporation Richard Hennessy Avid Technology, Inc. Tom Vaughan Digital Equipment Corporation Contributors: Gary Grebus Digital Equipment Corporation Larry Hare NetManage, Inc. Peter Kaczowka Hewlett-Packard Co. Jeffrey Siegal Congruent Corporation Al Tabayoyon North Valley Research, Inc. John Weber Big Time Software, Inc. 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 18, 1994 cosmetic cleanup prior to releasing X11 R6 rev v5.01 July 5,1996 incorporate Digital Press edits rev v5.02 December 16, 1996, incorporate additional Digital Press edits and X11 R6.3 Organization This document is organized into the following chapters and appendices: Introduction Chapter 1 Explains the purpose of the X Image Extension (XIE). 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 XIE protocol and library. 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 Provides 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 ini- tial sample implementations. Their efforts contributed greatly towards promoting XIE into the Public Review 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 xiv 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 im- aging concepts that 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 parameter types recognized by the core X protocol and the image extension protocol. The image ex- tension protocol types are defined in this document. Techniques For some XIE operations, there are several recognized algorithms or techniques that offer varying tradeoffs between quality of results and performance. Also, in some cases, different techniques are required due to an image's class or content. To accommodate some flexibility in this area, such XIE operations accept a technique parameter. A description of the techniques specified in this document can be found in Appendix A. Individual implementations may extend XIE's capabilities by providing 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 For a complete list of types, techniques, protocol requests, pipeline elements, events, and errors that are included in DIS, see Appendix B. Introduction 1-1 2 Specification Syntax This section presents syntactic conventions that are adhered to throughout this specification. General Syntax In general, the extension package follows the X11 protocol syntax conventions. Additions to this syntax are as follows: * 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 (for example, XieReqCreatePhotoflo) XieFlo: Photoflo element (for example, XieFloConvolve) XieEvn: Protocol event (for example, XieEvnPhotofloDone) XieErr: Protocol error (for example, XieErrPhotospace) XieTyp: Protocol type (for example, XieTypProcessDomain) XieVal: Alternative value (for example, XieValBandByPixel) * Outside of definitions the prefixes are generally not used: Alternative values are italicized and bold (for example, BandByPixel) All others are capitalized and bold (for example, CreatePhotoflo) * Core X types are displayed in upper-case (for example, 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 (for example, FloID) Events: none or list of events generated by RequestName (for example, 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, for example: 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 (for example, Photomap) Events: none or list of events generated by RequestName (for example, 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, for example: 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 as follows: 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 (for example, FloAlloc) Events: none or list of events generated by ElementName (for example, ExportAvail able) Attributes Table of PhotoElement output attributes, for example: 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, for example: 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 (for example, Alloc). XIE non-Photoflo errors: XieErrName xie-error: XieErrName < error code of Name, offset from first-error > resource-id: XID < resource to blame, for example, 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 er- ror) > 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 and by zero (0) or more bytes or additional data. The entire element defi- nition 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, subpackets within another protocol request (that is, ExecuteImmediate, CreatePhotoflo, ModifyPhotoflo, or RedefinePhotoflo). Events # of Bytes Value Description 1 CARD8 XIE event code 1 2 CARD16 Sequence number 4 TIMESTAMP Time 24 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 2 CARD16 Minor opcode 1 CARD8 Major opcode 21 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-1 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 depend- ent. 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 example: ERROR-DIFFUSION __ 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, see Appendix A. For a list of techniques itemized by ServiceClass, see 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 Specifies data units must fit evenly within a byte, or they must fill a byte, or fill a multiple of bytes (that is, pixels may be 1, 2, 4, 8, 16, 24*, or 32* bits in the protocol stream). * Arbitrary Specifies data units may fall at any bit address (that is, 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 } Monadic Dyadic * Add src1 + constant src1 + src2 * Sub src1 - constant src1 - src2 * SubRev constant - src1 src2 - src1 * Mul src1 * constant * Div src1 / constant * DivRev constant / src1 * Min minimum( src1, constant ) minimum( src1, src2 ) * Max maximum( src1, constant ) maximum( src1, src2 ) * 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 that is bound to one of the standard techniques defined above or a private tech- nique. 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 (that is, 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 that is bound to one of the standard techniques defined above or a private tech- nique. XieTypDataClass DataClass defines the class of data being transported over the wire. XieTypDataClass { XieValSingleBand, XieValTripleBand } * SingleBand Specifies index data (for example, ZPixmap format COLORMAP indices) or achromatic data (bitonal or gray-scale). * TripleBand Specifies nonindex trichromatic data (RGB or other supported colorspaces). XieTypDataStream DataStream is a segmented stream of data units that are transported in either direction through the proto- col stream. Segments of image data are transported as an arbitrary number of unsigned bytes, whereas all other types of data (for example, lookup table entries, rectangles, histogram counts, and so on) must be transported as one or more complete aggregates. The status, indicating the eventual end of data, is sup- plied 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 Specifies pixels are integer values and are limited to the range [0, levels-1]. * Unconstrained Specifies 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 that is bound to one of the standard techniques defined above or a private tech- nique. 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 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 Specifies no events are sent. * FirstData Specifies a single event is sent when the first data is available. * NewData Specifies an event is sent each time the amount of available data changes from zero to nonz- ero. The end of data is signaled by a final flag in the GetClientData reply that is returned when the last segment of data is retrieved. 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 Specifies all data has been retrieved. * ExportMore Specifies more data currently is available. * ExportEmpty Specifies no more data is available at this time. * ExportError Specifies 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, and so on 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 that 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 that is bound to one of the standard techniques defined above or a private tech- nique. XieTypGeometryTechnique GeometryTechnique defines the retrospective image resampling techniques used by the Geometry ele- ment. 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 that is bound to one of the standard techniques defined above or a private tech- nique. 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 Specifies the data for all bands are interleaved on a per-pixel basis and transmitted as a sin- gle data plane (for example, 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 Specifies the data for each band are transmitted as separate data planes (for example, 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 that 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 pro- vided 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 (for exam- ple, conversion 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, and so on), 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 (that is, 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 (for example, 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 sepa- rate 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, and so on), 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 Pho- toflo. 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 that 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 Specifies the Photoflo completed normally. * FloError Specifies the Photoflo terminated due to an error condition. * FloAbort Specifies the Photoflo was aborted by the client. XieTypPhotofloState PhotofloState identifies the current execution state of a Photoflo. XieTypPhotofloState { XieValInactive, XieValActive, XieValNonexistent } * Inactive Specifies 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 Specifies the state of a stored or immediate Photoflo during execution. Specifies 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 Specifies 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 Photo- flo errors that are not specific to an element. XieTypPhototag CARD16 XieTypProcessDomain ProcessDomain is a substructure 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 (that is, offset relative to the origin of the source(s)). Domain is the Phototag of the ele- ment 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 that 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 (that is, a control-plane), process- ing is restricted to the intersection of the data source(s) and nonzero 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 domains 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 Specifies supports the entire XIE protocol as defined in this document. * DIS Specifies upports 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 Specifies select all default techniques. * ColorAlloc Specifies select color allocation techniques. * Constrain Specifies select techniques for constraining data. * ConvertFromRGB Specifies select colorspace conversion techniques (for conversion from the RGB color- space). * ConvertToRGB Specifies elect colorspace conversion techniques (for conversion to the RGB colorspace). * Convolve Specifies select techniques for handling convolution edge conditions. * Decode Specifies select image decoding (decompression) techniques. * Dither Specifies select dithering techniques. * Encode Specifies select image encoding (compression) techniques. * Gamut Specifies select colorspace conversion gamut compression techniques. * Geometry Specifies select geometric sampling techniques. * Histogram Specifies select match-histogram shapes. * WhiteAdjust Specifies 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 that is returned for each technique in the reply to a QueryTech- niques 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 ei- ther takes no parameters or its parameters are optional. Group identifies which group the technique be- longs 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 that 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 that is bound to one of the standard techniques defined above or a private tech- nique. almost blank Protocol Parameter Types 3-17 4 Resources Overview XIE resources are extension server objects created by the client that 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 refer- enced 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 buckets 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, that illustrated in figure 4-3. Here an im- age is imported from a Photomap, processed, and then the result is exported back to the same Pho- tomap. Note that upon completion the old handle is moved to the new bucket, and the old bucket is destroyed. irs 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 (for example, memory or colors). Synchronizing resource access If multiple Photoflos reference the same resource, the client must synchronize access to the resource (for example, 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 first to establish the desired version using Query- ImageExtension, 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 responsi- bility to decide whether or not it can match the servers version of the protocol. Service-class specifies the ServiceClass supported by the XIE server . Alignment specifies the image data alignment restrictions of the server (that is, 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 servers floating point format (including the sign bit). If the server uses fixed point, unconstrained-mantissa is zero. Unconstrained-max-exp returns the larg- est value n such that 2n - 1 is representable in the servers Unconstrained data format. Uncon- strained-min-exp returns the smallest (most negative) value n such that 2n is representable in the servers 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 zero 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 (for example, 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 that 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 omit- ted, 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: or __ The technique number is supplied to pipeline elements to specify a desired algorithm or technique. While numbers for standard techniques can be hard-coded (for example, 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 that can be used to store the list of colors allocated by a ConvertToIndex element. The COLORMAP allocations that are recorded in a Col- orList belong to the client that executed the Photoflo that populated the resource (this is not neces- sarily 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 repopulated) with new COLORMAP allocations via a ConvertToIndex ele- ment 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 commencing 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 (that is, 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 iden- tified 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 col- ors 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 (for example, 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 that 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 repopulated) with lookup table entries after the successful execution of a Photoflo containing an ExportLUT element that 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 that 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 at- tributes are defined when a Photoflo containing an ExportPhotomap element populates photomap with data. The Photomap is populated (or repopulated) with image data after the successful execution of a Pho- toflo containing an ExportPhotomap element that targets photomap. Photomap data can be im- ported 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 attrib- utes 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. PutClient- Data 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 (that is, 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 im- ported into a Photoflo and used in conjunction with a ProcessDomain specification to restrict proc- essing 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 that 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. Because 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 connec- tion 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 up- stream elements. There are three types of elements. Import elements bring data into the Photoflo from external re- sources or the client, have one output connection, and no input connections. Process elements per- form some operation on the data (for example, 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 re- source-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 reuse. The blue band is selected and trans- lated (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 reregistered blue band. The combined image is then converted to in- dex 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 possi- ble 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 execution 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 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 de- layed 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 ex- ported 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 Photoflos 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 resources.2 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 required.2 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, unblock 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 that 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 that 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. Rede- finePhotoflo 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. Because 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 client 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 unde- fined. An arbitrary amount of image data can be sent per request, whereas for nonimage data one or more complete aggregates must be sent per request (for example, one or more LUT array entries). If too many data are sent (for example, 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 nonimage 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 im- ages 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 parameters 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 current 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 nonimage data are always returned by the server as one or more complete aggregates (that is, 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 nonzero amount of data per ExportClient element. Beyond that point execution may be sus- pended 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 pro- duced 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 that 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 ele- ment, 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 cli- ent 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 that 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. Imme- diate 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-1 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 PutClient- Data protocol request. Multi-source images Multiple source images (for example, tiled images, multi-client transport, and so on) require a sepa- rate import element to describe each segment of the image. The composite image can then be assem- bled using process elements (for example, 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 uncompressed image. * ImportObscured Notifies the client that one or more regions to be imported from a WINDOW are obscured and un- available 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 trans- ported through the protocol stream. Data is sent to the ImportClient element via the PutClient- Data 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 ar- ray. 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 remapped through the array. When a TripleBand image is to be remapped 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 separately 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 quanti- zation levels can be stored. When array entries require multiple bytes, the byte order per entry is de- termined 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 PutCli- entData). ImportClientPhoto XieFloImportClientPhoto notify: BOOL class: XieTypDataClass width: XieTypTripletofCARD32 height: XieTypTripletofCARD32 levels: XieTypLevels decode: XieTypDecodeTechnique decode-params: 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 pix- els. 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 (for example, down-sampled YCbCr data), it is generally the client's responsibility to make inter-band dimensions match to render the image (for example, 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 individ- ual 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 PutCli- entData). Import from Resource ImportResource elements obtain data from server resources: core DRAWABLEs, and XIE LUT, Photomap, and ROI resources. The attributes and data of XIE resources are bound to ImportResource elements when the Photo- flo 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 at- tributes and data does not occur until the Photoflo successfully completes (that is, 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 (that is, 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 (that is, SingleBand index data). Index data are appropriate for only a few process elements (for example, 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 for- warding 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 (for example, down-sampled YCbCr data), it is generally the client's responsibility to make inter-band dimensions match to render the image (for example, use Geometry with ap- propriate band-mask and sample technique). If ImportPhotomaps 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-9 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 (for example, Geometry). Others, operate on either a pair of image sources or an image and a constant (for example, 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 (that is, 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 spa- tially restricted to the intersection of the sources on a per-band basis. Data from src-1 that do not in- tersect 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 that references the import or process element that supplies the processing domain data. The element referenced by the Phototag may provide the following: * 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 ImportCli- entPhoto; or the output of an upstream process element (for example, Compare). Processing is restricted to the intersection of the data source(s) and nonzero locations within the control-plane. Processing is not restricted if Phototag zero (0) is specified as the process domains 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 dimen- sioned 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 in- tensity level is the number of quantization levels minus one. With the exception of operations that specifically change the number of quantization levels (for ex- ample, 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 result- ing pixel to zero. Likewise, an operation that computes a pixel value that would exceed the levels at- tribute of the data will saturate the resulting pixel at its maximum allowable value (that is, levels-1). This method of constraining image data is equivalent to the HardClip Constrain technique. For some operations (for example, 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 capabili- ties of a frame buffer. Performing a sequence of image operations on Unconstrained image data al- lows 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 proc- essing 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 va- riety of techniques are available for this purpose that allow the pixel values to be level-shifted, scaled, clipped, rounded, and so on Process Categories * Area elements Convolve Specifies an area of input pixels is involved in producing each output pixel (controlled by a convolution kernel). * Format conversion elements ConvertFromIndex Specifies convert index data to achromatic or trichromatic data. ConvertFromRGB Specifies convert RGB data to another trichromatic colorspace. ConvertToIndex Specifies convert achromatic or trichromatic data to index data. ConvertToRGB Specifies convert non-RGB trichromatic data to RGB data. * Dyadic elements: process either two images or an image and a constant Arithmetic Specifies an arithmetic operation is performed between two images or an image and a constant. Blend Specifies combine two images or an image and a constant. Compare Specifies two images or an image and a constant are compared to generate a Boolean bitmap result. Logical Specifies perform logical bit-wise operations on an image, between two images, or between an image and a constant. * Geometric elements Geometry Specifies general affine transform (provides crop, mirror, scale, shear, rotate, translate, and combinations thereof). PasteUp Specifies an N-input translate operation that reconstructs an image from various source tiles. * Point elements Math Specifies apply a mathematical operation to each pixel. Point Specifies remap each pixel value through a lookup table. * Radiometric elements BandCombine Specifies merge three SingleBand images. BandExtract Specifies extract SingleBand data from a trichromatic source. BandSelect Specifies select a single band of data from a trichromatic source. Constrain Specifies constrain an image to a fixed number of quantization levels. Dither Specifies reduce image quantization levels through an area technique. MatchHistogram Specifies transform an image to have a specific histogram shape. Unconstrain Specifies 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, multi- plication, 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 (for example, 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 (for example, Div or Gamma) FloDomain Invalid domain FloMatch class, type, or levels differs between src-1 and src-2 Selected source data are bitonal (that is, 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 that 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 attrib- utes 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 in- dices in cases where the contents of the COLORMAP is well ordered (for example, 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: XieTypFloat 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 out- put pixel is a percentage combination of the source values, as controlled by the alpha input or the al- pha 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 nonzero, it controls the blend propor- tion for each pixel that is processed; otherwise, alpha-const provides this control. Domain may con- trol 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 nonzero, 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 deter- mined by the corresponding value taken from alpha or the value of alpha-const. If alpha is nonzero, the proportion 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 (that is, 2 or less levels) FloValue alpha is zero and alpha-const is outside the range [0.0, 1.0] alpha is nonzero 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 bit- map output that reflects the results of a point-wise comparison. The output data has a value of one (1) wherever the comparison is true, and a value of zero (0) everywhere else (that is, comparison false or comparison not performed). 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 t