XIElib Specification Gary Rogers AGE Logic, Inc. This document contains reference pages for each XIElib function. Revision History Gary Rogers, AGE Logic, Inc., Public Review Draft, April, 1994 Syd Logan, NetManage, Inc., Minor technical edits, correction of errors, October, 1996 Copyright © 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 permission notice appear in all copies. AGE Logic makes no representations about the suitability for any purpose of the information in this document. This documentation is only a draft standard of the X consortium and is therefore subject to change. Acknowledgments XIElib was provided by the X Consortium, with cooperation from AGE Logic, Inc. of San Diego, CA. It is a C subroutine library that provides a low level C binding of all features that are defined by Version 5.0 of the XIE Protocol. Various parts of the text were borrowed from the Version 5.0 XIE Protocol Reference Manual, edited by Bob Shelley of AGE Logic, Inc.. Bob provided suggestions and comments that were invaluable in preparing this document. Dean Verheiden and Syd Logan, both of AGE Logic, Inc., graciously volunteered to review the original manuscript. The author would like to thank Ralph Mor of the X Consortium for his careful review of this document. Ralph designed the XIElib and wrote its sample implementation, and his technical advice was indispensable. Adrian Nye, Editor for O'Reilly & Associates, Inc., provided substantive assistance in the preparation of this document, for which the author is very thankful. Table of Contents Introduction 1 Startup Functions XieInitialize 3 XieQueryTechniques 5 XieCreateColorList 8 XieDestroyColorList 9 XiePurgeColorList 10 XieQueryColorList 11 LUT Functions XieCreateLUT 12 XieDestroyLUT 13 Photomap Functions XieCreatePhotomap 14 XieDestroyPhotomap 15 XieQueryPhotomap 16 ROI Functions XieCreateROI 18 XieDestroyROI 19 Photoflo Functions XieCreatePhotospace 20 XieDestroyPhotospace 21 XieExecuteImmediate 22 XieAllocatePhotofloGraph 24 XieCreatePhotoflo 25 XieDestroyPhotoflo 27 XieExecutePhotoflo 28 XieModifyPhotoflo 29 XieRedefinePhotoflo 31 XieQueryPhotoflo 32 Client Data Functions XiePutClientData 34 XieGetClientData 36 Abort and Await Functions XieAbort 38 XieAwait 39 Photoflo Element Functions XieFloImportClientLUT 40 XieFloImportClientPhoto 43 XieFloImportClientROI 46 XieFloImportDrawable 47 XieFloImportDrawablePlane 49 XieFloImportLUT 51 XieFloImportPhotomap 52 XieFloImportROI 54 XieFloArithmetic 55 XieFloBandCombine 58 XieFloBandExtract 60 XieFloBandSelect 62 XieFloBlend 63 XieFloCompare 66 XieFloConstrain 69 XieFloConvertFromIndex 71 XieFloConvertFromRGB 73 XieFloConvertToIndex 75 XieFloConvertToRGB 78 XieFloConvolve 80 XieFloDither 83 XieFloGeometry 85 XieFloLogical 88 XieFloMatchHistogram 91 XieFloMath 93 XieFloPasteUp 95 XieFloPoint 97 XieFloUnconstrain 99 XieFloExportClientHistogram 100 XieFloExportClientLUT 102 XieFloExportClientPhoto 104 XieFloExportClientROI 106 XieFloExportDrawable 108 XieFloExportDrawablePlane 110 XieFloExportLUT 112 XieFloExportPhotomap 114 XieFloExportROI 116 Technique Functions XieTecColorAllocAll 117 XieTecColorAllocMatch 118 XieTecColorAllocRequantize 120 XieTecRGBToCIELab 121 XieTecRGBToCIEXYZ 123 XieTecRGBToYCbCr 125 XieTecRGBToYCC 127 XieTecCIELabToRGB 129 XieTecCIEXYZToRGB 132 XieTecYCbCrToRGB 134 XieTecYCCToRGB 136 XieTecClipScale 138 XieTecConvolveConstant 140 XieTecDecodeUncompressedSingle 141 XieTecDecodeUncompressedTriple 143 XieTecDecodeG31D 146 XieTecDecodeG32D 148 XieTecDecodeG42D 150 XieTecDecodeTIFF2 152 XieTecDecodeTIFFPackBits 154 XieTecDecodeJPEGBaseline 156 XieTecDecodeJPEGLossless 158 XieTecDitherOrdered 160 XieTecEncodeUncompressedSingle 161 XieTecEncodeUncompressedTriple 163 XieTecEncodeG31D 166 XieTecEncodeG32D 168 XieTecEncodeG42D 170 XieTecEncodeServerChoice 172 XieTecEncodeJPEGBaseline 174 XieTecEncodeJPEGLossless 177 XieTecEncodeTIFF2 179 XieTecEncodeTIFFPackBits 181 XieTecGeomAntialiasByArea 183 XieTecGeomAntialiasByLowpass 185 XieTecGeomGaussian 187 XieTecGeomNearestNeighbor 189 XieTecHistogramGaussian 191 XieTecHistogramHyperbolic 192 XieTecWhiteAdjustCIELabShift 194 Free Functions XieFreeTechniques 195 XieFreePhotofloGraph 196 XieFreeEncodeJPEGBaseline 197 XieFreeEncodeJPEGLossless 198 XieFreePasteUpTiles 199 XIElib Events ColorAlloc Event Events-1 DecodeNotify Event Events-2 ExportAvailable Event Events-3 ImportObscured Event Events-4 PhotofloDone Event Events-5 XIElib Errors Resource Errors Errors-1 Photoflo Errors Errors-2 XIElib - Function Group Introduction The following pages describe the format of the reference pages for each XIElib function. Every effort has been made to maintain consistency with the format used in Xlib Reference Manual for Version 11 (A. Nye, ed., O'Reilly & Associates, Inc., 1992). The reader is also referred to X Image Extension Protocol Reference Manual, Version 5.0 (R. Shelley, ed., 1994) for a complete definition of the XIE protocol. Name XieFunctionName - brief description of the function Syntax The Syntax section presents the calling syntax for the routine, including the declarations of the arguments and the return type. For example: returntype XieFunctionName (arg1, arg2_ret) type1 arg1; type2 *arg2_ret; Arguments The Arguments section describes each of the arguments used by the function. There are two sorts of arguments: arguments to specify data to the function and arguments that return data from the function. An example of each type follows: arg1 Specifies information for XieFunctionName. The description for this type of argument always starts with the word "Specifies." arg2_ret Returns information from XieFunctionName. The description for this type of argument always starts with the word "Returns." Returns This section is present when XieFunctionName returns a value and describes what is returned. Description The Description section describes what the function does, what it returns, and what events or side effects it causes. It also may contain pertinent definitions, algorithms, and tables. A description of each XIE event structure is presented in the section XIElib Events. Output Attributes This section, which presents a table of element output attributes, is present if XieFloFunctionName specifies an element that produces output data. Class Data class of output data - single band (achromatic or index) - triple band (trichromatic) Type Data type - constrained (quantization levels is Levels) - unconstrained (quantization levels is unknown) Width Width of output (in pixels per band) Height Height of output (in pixels per band) Levels Depends on type - constrained: number of quantization levels - unconstrained: unknown Structures The Structures section contains the C definitions of the XIE-specific data types used by XieFunctionName as arguments or return values. It also contains definitions of important constants used by the function. Errors The Errors section is present when an action of XieFunctionName could generate an error. A table of errors that can be generated and their causes is presented. The full list of errors is presented in the section XIElib Errors. See Also This section lists other functions that contain information related to XieFunctionName. XIElib - Startup Functions XieInitialize Name XieInitialize - initialize the XIE extension Syntax Status XieInitialize (display, extinfo_ret) Display *display; XieExtensionInfo **extinfo_ret; Arguments display Specifies a connection to an X server. extinfo_ret Returns the pointer to an XieExtensionInfo structure, which contains information about the XIE server's capabilities. Returns Zero on failure, nonzero on success. Description XieInitialize initializes the interface to the XIE extension and returns information about the XIE server's capabilities. XieInitialize should be called to establish version compatibility between client and server prior to making any other XIE request. If successful, XieInitialize allocates and fills the XieExtensionInfo structure as follows: * The server_major_rev and server_minor_rev members are set to specify the highest version of the XIE protocol that the server supports. If the server version is higher than the XIElib version, the server will return the lower version, if it supports it. * The service_class member is set to the service-class supported by the XIE server. Service- class defines the recognized image-processing service sets supported by the X Image Extension standard; the two service classes currently defined are Full, the entire XIE protocol, and DIS, the Document Image Subset, a proper subset of Full XIE. The service_class member can be set to one of the standard values: xieValFull xieValDIS * The alignment member is set to the pixel and scanline alignment for image data supported by the server. Values for this member can be either xieValAlignable or xieValArbitrary. xieValAlignable data units must fit evenly within a byte, or they must fill a byte, or fill a multiple of bytes; xieValArbitrary data units may fall at any bit address. * The uncnst_mantissa member is set to the number of bits in the servers floating-point format (including the sign bit). If the server uses fixed point, uncnst_mantissa is set to zero. * The uncnst_min_exp member is set to the smallest (most negative) value n such that 2n is representable in the servers unconstrained data format. * The uncnst_max_exp member is set to the largest value n such that 2n - 1 is representable in the servers unconstrained data format. * The n_cnst_levels member is the number of items in the list cnst_levels. * The items in the list cnst_levels are set to the levels that are recommended for constrained data by the server. A value of zero means 232 levels. * The first_event member is set to the value from which subsequent XIE events values are based. * The first_error member is set to the value from which subsequent XIE error values are based. The memory allocated to extinfo_ret is freed when display is closed via XCloseDisplay; the client should not free this memory. If not successful, XieInitialize sets **extinfo_ret to NULL. Structures typedef struct { unsigned server_major_rev; unsigned server_minor_rev; XieServiceClass service_class; XieAlignment alignment; int uncnst_mantissa; int uncnst_min_exp; int uncnst_max_exp; int n_cnst_levels; unsigned long *cnst_levels; int major_opcode; int first_event; int first_error; } XieExtensionInfo; /* Definitions of Extension Name and Version Number */ #define xieMajorVersion 5 #define xieMinorVersion 0 #define xieEarliestMinorVersion 0 #define xieLatestMinorVersion 0 /* Definitions of ServiceClass */ #define xieValFull 1 #define xieValDIS 2 /* Definitions of Alignment */ #define xieValAlignable 1 #define xieValArbitrary 2 XIElib - Startup Functions XieQueryTechniques Name XieQueryTechniques - return information about the standard and private techniques that are supported by the server Syntax Status XieQueryTechniques (display, technique_group, ntechniques_ret, techniques_ret) Display *display; XieTechniqueGroup technique_group; int *ntechniques_ret; XieTechnique **techniques_ret; Arguments display Specifies a connection to an X server. technique_group Specifies the group of techniques for which the server is to return information. ntechniques_ret Returns the number of items in the list of XieTechnique structures. techniques_ret Returns the pointer to the list of XieTechnique structures, which contains the information about the selected group of techniques. Returns Zero on failure, nonzero on success. Description If successful, XieQueryTechniques allocates and fills each XieTechnique structure in the list as follows: * The member needs_param is set to True if the technique requires additional parameters; needs_param is set to False if the technique takes no parameters, or it has parameters that are optional. If parameters are optional, they must be totally omitted, or they must all be supplied. * The member group is set to the group the technique belongs to. * The member number is set to the numeric identifier assigned to the technique. * The member speed is set to the server's assessment of the speed of this technique relative to other techniques in the same group, where 0 is slowest and 255 is fastest. * The member name is set to the XIE compliant technique name string. To free the memory allocated to techniques_ret, use XieFreeTechniques. On failure, ntechniques_ret is set to zero and *techniques_ret is set to NULL. The standard technique group names that can be queried using XieQueryTechniques are: Technique group Meaning xieValDefault Select all default techniques xieValAll Select all supported techniques xieValColorAlloc Select color allocation techniques xieValConstrain Select techniques for constraining data xieValConvertFromRGB Select colorspace conversion techniques (for conversion from the RGB colorspace) xieValConvertToRGB Select colorspace conversion techniques (for conversion to the RGB colorspace) xieValConvolve Select techniques for handling convolution edge conditions xieValDecode Select image decoding (decompression) techniques xieValDither Select dithering techniques xieValEncode Select image encoding (compression) techniques xieValGamut Select colorspace conversion gamut compression techniques xieValGeometry Select geometric sampling techniques xieValHistogram Select match-histogram shapes xieValWhiteAdjust 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. Structures typedef unsigned XieTechniqueGroup; typedef struct { Bool needs_param; XieTechniqueGroup group; unsigned int number; unsigned int speed; char *name; } XieTechnique; /* Definitions for TechniqueGroups */ #define xieValDefault 0 #define xieValAll 1 #define xieValColorAlloc 2 #define xieValConstrain 4 #define xieValConvertFromRGB 6 #define xieValConvertToRGB 8 #define xieValConvolve 10 #define xieValDecode 12 #define xieValDither 14 #define xieValEncode 16 #define xieValGamut 18 #define xieValGeometry 20 #define xieValHistogram 22 #define xieValWhiteAdjust 24 Errors BadAlloc Insufficient resources BadValue Unknown technique_group See Also XieFreeTechniques XIElib - Color List Functions XieCreateColorList Name XieCreateColorList - create a color list Syntax XieColorList XieCreateColorList (display) Display *display; Arguments display Specifies a connection to an X server. Returns The color list identifier. Description XieCreateColorList creates a color list resource and returns its color list ID. The color list created is an unpopulated server resource that can be used to store the list of colors allocated by XieFloConvertToIndex. The Colormap allocations that are recorded in a color list belong to the client that executed the photoflo that populated the resource (this is not necessarily the same client that created the color list). A color list cannot be the target of more than one active photoflo at a time. The contents of a color list may be queried using XieQueryColorList. All allocated cells can be explicitly purged from a color list using XiePurgeColorList. A color list can be destroyed using XieDestroyColorList. Structures typedef XID XieColorList; Errors BadAlloc Insufficient resources BadIdChoice Invalid color list See Also XieDestroyColorList, XiePurgeColorList, XieQueryColorList, XieFloConvertToIndex XIElib - Color List Functions XieDestroyColorList Name XieDestroyColorList - destroy a color list Syntax void XieDestroyColorList (display, color_list) Display *display; XieColorList color_list; Arguments display Specifies a connection to an X server. color_list Specifies the color list to be destroyed. Description XieDestroyColorList destroys the color list resource identified by color_list. Once destroyed, color list ID is no longer valid. Structures typedef XID XieColorList; Errors xieErrNoColorlist Invalid color_list See Also XieCreateColorList XIElib - Color List Functions XiePurgeColorList Name XiePurgeColorList - purge all allocated cells from a color list Syntax void XiePurgeColorList (display, color_list) Display *display; XieColorList color_list; Arguments display Specifies a connection to an X server. color_list Specifies the color list to be purged. Description XiePurgeColorList frees the colors from the specified color list. Structures typedef XID XieColorList; Errors BadAccess Attempt to purge colors when color list is being written by a photoflo xieErrNoColorlist Invalid color_list See Also XieCreateColorList, XieDestroyColorList, XieQueryColorList, XieFloConvertToIndex XIElib - Color List Functions XieQueryColorList Name XieQueryColorList - obtain a list of allocated Colormap indices Syntax Status XieQueryColorList (display, color_list, colormap_ret, ncolors_ret, colors_ret) Display *display; XieColorList color_list; Colormap *colormap_ret; unsigned *ncolors_ret; unsigned long **colors_ret; Arguments display Specifies a connection to an X server. color_list Specifies the color list to query. colormap_ret Returns the Colormap from which the colors were allocated. ncolors_ret Returns the number of Colormap indices in the list. colors_ret Returns the list of allocated Colormap indices. Returns Zero on failure, nonzero on success. Description XieQueryColorList allocates and returns a list of colors allocated by a ConvertToIndex element. When there are no colors in color list, a zero status is returned, the value zero is returned for the colormap, and the list of colors is of length zero. The pointer to the list of allocated Colormap indices is set to NULL. To free the memory allocated to colors_ret, use XFree. Structures typedef XID XieColorList; Errors BadAlloc Insufficient resources xieErrNoColorlist Invalid color list See Also XieCreateColorList, XieDestroyColorList, XieQueryColorList, XieFloConvertToIndex XIElib - LUT Functions XieCreateLUT Name XieCreateLUT - create a lookup table Syntax XieLut XieCreateLUT (display) Display *display; Arguments display Specifies a connection to an X server. Returns The lookup table (LUT) identifier. Description XieCreateLUT creates a server resource that is used as a lookup table (LUT) by a 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. The LUT is populated (or repopulated) with lookup table entries after the successful execution of a photoflo containing an ExportLUT element that targets lut. LUT data can be imported into a photoflo using an ImportLUT element. Structures typedef XID XieLut; Errors BadAlloc Insufficient resources BadIDChoice Invalid LUT See Also XieDestroyLUT, XieFloImportLUT, XieFloExportLUT XIElib - LUT Functions XieDestroyLUT Name XieDestroyLUT - destroy a lookup table Syntax void XieDestroyLUT (display, lut) Display *display; XieLut lut; Arguments display Specifies a connection to an X server. lut Specifies the ID of the LUT to be destroyed. Description XieDestroyLUT destroys the lookup table (LUT) identified by lut. Once destroyed, LUT ID is no longer valid. Structures typedef XID XieLut; Errors xieErrNoLut The value for the lut argument does not name a defined LUT See Also XieDestroyLUT, XieFloImportLUT, XieFloExportLUT XIElib - Photomap Functions XieCreatePhotomap Name XieCreatePhotomap - create a photomap Syntax XiePhotomap XieCreatePhotomap (display) Display *display; Arguments display Specifies a connection to an X server. Returns The photomap identifier. Description XieCreatePhotomap creates a photomap, a server resource that stores image data. Photomap data may be rendered for display or used as input to control or modify the rendition of another image. Photomap attributes are defined when a photoflo containing an ExportPhotomap element populates the photomap with data. Structures typedef XID XiePhotomap; Errors BadAlloc Insufficient resources BadIdChoice Invalid photomap See Also XieDestroyPhotomap, XieQueryPhotomap, XieFloImportPhotomap, XieFloExportPhotomap XIElib - Photomap Functions XieDestroyPhotomap Name XieDestroyPhotomap - destroy a photomap Syntax void XieDestroyPhotomap (display, photomap) Display *display; XiePhotomap photomap; Arguments display Specifies a connection to an X server. photomap Specifies the ID of the photomap to be destroyed. Description XieDestroyPhotomap destroys the photomap identified by photomap. Once destroyed, the photomap ID is no longer valid. A photomap is the XIE resource used to store image data in the server. Structures typedef XID XiePhotomap; Errors xieErrNoPhotomap The value for the photomap argument does not name a defined photomap See Also XieCreatePhotomap , XieQueryPhotomap, XieFloImportPhotomap, XieFloExportPhotomap XIElib - Photomap Functions XieQueryPhotomap Name XieQueryPhotomap - return the queriable attributes of a photomap Syntax Status XieQueryPhotomap (display, photomap, populated_ret, datatype_ret, class_ret, decode_technique_ret, width_ret, height_ret, levels_ret) Display *display; XiePhotomap photomap; Bool *populated_ret; XieDataType *datatype_ret; XieDataClass *class_ret; XieDecodeTechnique *decode_technique_ret; XieLTriplet width_ret; XieLTriplet height_ret; XieLTriplet levels_ret; Arguments display Specifies a connection to an X server. photomap Specifies the photomap to be queried. populated_ret Returns the status of the photomap. datatype_ret Returns the type of data in the photomap. class_ret Returns the class of data in the photomap. decode_technique_ret Returns the decode technique required to interpret the data. width_ret Returns the width, in pixels per band. height_ret Returns the height, in pixels per band. levels_ret Returns the number of quantization levels per band. Returns Zero on failure, nonzero on success. Description A photomap is a server resource that stores image data. XieQueryPhotomap sets populated_ret to indicate whether or not photomap has been populated with attributes and data. If populated_ret is False, all remaining fields contain zeros. datatype_ret reports whether the photomap contains constrained or unconstrained data, and is set to one of the following standard data type values: xieValConstrained xieValUnconstrained class_ret is the class of image data (that is, single-band or triple-band) and is set to one of the following standard data class values: xieValSingleBand xieValTripleBand width_ret and height_ret are set to the dimensions of the image data in pixels (per band). levels_ret is set to the potential dynamic range, or number of quantization levels (per band). If datatype_ret is set to unconstrained, the returned values for levels are zeros. If class_ret is xieValSingleBand, width_ret, height_ret, and levels_ret are only valid for element 0 in each of these vectors; elements 1 and 2 are unused and are returned as zeros. decode_technique_ret is set to the decode technique that will be required to interpret or decompress the data. Decode techniques define the techniques that can be used to interpret uncompressed image data or decode compressed images. decode_technique_ret can be set to one of the following standard decode technique values: xieValDecodeUncompressedSingle xieValDecodeUncompressedTriple xieValDecodeG31D xieValDecodeG32D xieValDecodeG42D xieValDecodeJPEGBaseline xieValDecodeJPEGLossless xieValDecodeTIFF2 xieValDecodeTIFFPackBits If a vendor defined additional private decode techniques, decode_technique_ret can be set to the values given to these techniques. Structures typedef unsigned XieDataClass; typedef unsigned XieDataType; typedef unsigned XieDecodeTechnique; typedef unsigned long XieLTriplet[3]; typedef XID XiePhotomap; /* Definitions of DataType */ #define xieValConstrained 1 #define xieValUnconstrained 2 /* Definitions of DataClass */ #define xieValSingleBand 1 #define xieValTripleBand 2 /* Definitions for DecodeTechniques */ #define xieValDecodeUncompressedSingle 2 #define xieValDecodeUncompressedTriple 3 #define xieValDecodeG31D 4 #define xieValDecodeG32D 6 #define xieValDecodeG42D 8 #define xieValDecodeJPEGBaseline 10 #define xieValDecodeJPEGLossless 12 #define xieValDecodeTIFF2 14 #define xieValDecodeTIFFPackBits 16 Errors xieErrNoPhotomap The value for the photomap argument does not name a defined photomap. xieErrNoFloAlloc Insufficient resources (for exmple, memory) XIElib - ROI Functions XieCreateROI Name XieCreateROI - create a Rectangles-Of-Interest Syntax XieRoi XieCreateROI (display) Display *display; Arguments display Specifies a connection to an X server. Returns The ROI (Rectangles-Of-Interest) identifier. Description XieCreateROI creates a server ROI (Rectangles-Of-Interest) resource, and returns its resource ID to the client. Structures typedef XID XieRoi; Errors BadAlloc Insufficient resources BadIDChoice Invalid ROI See Also XieDestroyROI, XieFloImportROI, XieFloExportROI XIElib - ROI Functions XieDestroyROI Name XieDestroyROI - destroy a Rectangles-Of-Interest Syntax void XieDestroyROI (display, roi) Display *display; XieRoi roi; Arguments display Specifies a connection to an X server. roi Specifies the ID of the ROI to be destroyed. Description XieDestroyROI destroys the Rectangles-Of-Interest (ROI) identified by roi. Once destroyed, roi is no longer valid. Structures typedef XID XieRoi; Errors xieErrNoROI The value for the roi argument does not name a defined ROI See Also XieCreateROI XIElib - Immediate Photoflo Functions XieCreatePhotospace Name XieCreatePhotospace - create a photospace Syntax XiePhotospace XieCreatePhotospace (display) Display *display; Arguments display Specifies a connection to an X server. Returns The photospace identifier. Description XieCreatePhotospace returns a resource-id for a new photospace that can be used to accommodate immediate photoflos instantiated by a client. Any client that needs to instantiate immediate photoflos must create at least one photospace. Structures typedef XID XiePhotospace; Errors BadAlloc Insufficient resources BadIDChoice Invalid photospace See Also XieDestroyPhotospace, XieExecuteImmediate XIElib - Immediate Photoflo Functions XieDestroyPhotospace Name XieDestroyPhotospace - destroy a photospace Syntax void XieDestroyPhotospace (display, photospace) Display *display; XiePhotospace photospace; Arguments display Specifies a connection to an X server. photospace Specifies the ID of the photospace to be destroyed. Description XieDestroyPhotospace destroys 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. Structures typedef XID XiePhotospace; Errors xieErrNoPhotospace The value for the photospace argument does not name a defined photospace See Also XieCreatePhotospace XIElib - Immediate Photoflo Functions XieExecuteImmediate Name XieExecuteImmediate - define and begin execution of an immediate photoflo Syntax void XieExecuteImmediate (display, photospace, flo_id, notify, elem_list, elem_count) Display *display; XiePhotospace photospace; unsigned long flo_id; Bool notify; XiePhotoElement *elem_list; int elem_count; Arguments display Specifies a connection to an X server. photospace Specifies the ID of the photospace to be executed. flo_id Specifies a particular instance of the photoflo to be executed. notify Specifies whether a PhotofloDone event must be sent upon completion. elem_list Specifies the import, process, and export elements to be executed. elem_count Specifies the number of items in elem_list. Description XieExecuteImmediate begins the asynchronous execution of an immediate photoflo. The server does not save a copy of an immediate photoflo after the photoflo has completed execution and all data exported for the client have been retrieved. An immediate photoflo may therefore not be modified or totally redefined prior to subsequent executions. It is legal to have multiple unique instances of immediate photoflos (and stored photoflos) active concurrently. The photospace/flo_id argument pair specifies the instance by which this photoflo will be identified in other requests, events, or errors. notify specifies whether a PhotofloDone event must be sent upon completion. The PhotofloDone event notifies the client that a photoflo has left the active state: it is no longer executing. elem_list defines the import, process, and export elements to be executed. If any clients have blocked themselves during the execution of the photoflo (see XieAwait), they will become unblocked when the photoflo's state changes from active to nonexistent. Care should be taken that the argument pair elem_list/elem_count matches a returned value (an array of XiePhotoElement structures) and argument count from a call to XieAllocatePhotofloGraph. Structures typedef XID XiePhotospace; typedef struct { int elemType; /* union of ALL element types */ union { ... ... } data; } XiePhotoElement; Errors xieErrNoFloAlloc Insufficient resources (for example, memory) xieErrNoFloElement Invalid element type(s) in elem_list xieErrNoFloID Invalid photospace/flo_id argument pair has been specified xieErrNoFlo An error has been detected while defining, executing, or accessing a photoflo (See Photoflo Errors). See Also XieAwait, XieAllocatePhotofloGraph XIElib - Photoflo Functions XieAllocatePhotofloGraph Name XieAllocatePhotofloGraph - allocate an array of XiePhotoElement structures Syntax XiePhotoElement *XieAllocatePhotofloGraph (count); unsigned int count; Arguments count Specifies the number of XiePhotoElement structures to allocate. Returns The array of XiePhotoElement structures. Description XieAllocatePhotofloGraph allocates and returns a pointer to an array of XiePhotoElement structures; each field of each structure in the array is set to zero (0). To free the memory allocated to the list of XiePhotoElement structures, use XieFreePhotofloGraph . If XieAllocatePhotofloGraph is unable to create an XiePhotoElement array , it returns NULL. Structures typedef struct { int elemType; /* union of ALL element types */ union { ... ... } data; } XiePhotoElement; See Also XieFreePhotofloGraph, XieCreatePhotoflo, XieModifyPhotoflo, XieRedefinePhotoflo, XieExecutePhotoflo, XieExecuteImmediate XIElib - Stored Photoflo Functions XieCreatePhotoflo Name XieCreatePhotoflo - create a stored photoflo Syntax XiePhotoflo XieCreatePhotoflo (display, elem_list, elem_count) Display *display; XiePhotoElement *elem_list; int elem_count; Arguments display Specifies a connection to an X server. elem_list Specifies the defining array of XiePhotoElement structures. elem_count Specifies the number of XiePhotoElement structures in the array. Returns The photoflo identifier. Description XieCreatePhotoflo creates a stored photoflo resource, defines its complete contents using the contents of elem_list, sets it in the inactive state, and returns its resource-id. Stored photoflos persist beyond execution and may be modified or totally redefined prior to subsequent executions. The returned photoflo identifier is a new resource-id that, along with the execution domain used for the photoflo, identifies this photoflo in other requests, events, or errors. elem_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. XieCreatePhotoflo will only store the photoflo's definition: parameter validation is delayed until an execute request is received. Structures typedef XID XiePhotoflo; typedef struct { int elemType; /* union of ALL element types */ union { ... ... } data; } XiePhotoElement; Errors BadAlloc Insufficient resources BadIdChoice Invalid photoflo xieErrNoFloAlloc Insufficient resources (for example, memory) for elem_list xieErrNoFloElement Invalid element type(s) in elem_list xieErrNoFlo An error has been detected while defining, executing, or accessing a photoflo (see Photoflo Errors). See Also XieAllocatePhotofloGraph, XieFreePhotofloGraph, XieModifyPhotoflo, XieRedefinePhotoflo, XieExecutePhotoflo, XieQueryPhotoflo, XieDestroyPhotoflo XIElib - Stored Photoflo Functions XieDestroyPhotoflo Name XieDestroyPhotoflo - destroy a stored photoflo Syntax void XieDestroyPhotoflo (display, photoflo) Display *display; XiePhotoflo photoflo; Arguments display Specifies a connection to an X server. photoflo Specifies the photoflo to be destroyed. Description XieDestroyPhotoflo destroys a stored photoflo. If photoflo is active, that is, executing, it is aborted and all exported data that are pending client retrieval are freed prior to destroying photoflo. Structures typedef XID XiePhotoflo; Errors xieErrNoPhotoflo The value for the photoflo argument does not name a defined photoflo See Also XieCreatePhotoflo XIElib - Stored Photoflo Functions XieExecutePhotoflo Name XieExecutePhotoflo - execute a stored photoflo Syntax void XieExecutePhotoflo (display, photoflo, notify) Display *display; XiePhotoflo photoflo; Bool notify; Arguments display Specifies a connection to an X server. photoflo Specifies the photoflo to be executed. notify Specifies that a PhotofloDone event must be sent upon completion. Description XieExecutePhotoflo 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. notify specifies that a PhotofloDone event must be sent upon completion. A PhotofloDone event notifies the client that a photoflo has left the active state (it is no longer executing). Stored photoflos persist beyond execution and may be modified or totally redefined prior to subsequent executions. Structures typedef XID XiePhotoflo; Errors xieErrNoPhotoflo The value for the photoflo argument does not name a defined photoflo xieErrNoFloAccess Attempt to execute photoflo when it is already active xieErrNoFloAlloc Insufficient resources (for example, memory) xieErrNoFlo An error has been detected while defining, executing, or accessing a photoflo (see Photoflo Errors). See Also XieCreatePhotoflo, XieModifyPhotoflo, XieRedefinePhotoflo, XieQueryPhotoflo, XieDestroyPhotoflo, XieAbort, XieAwait, XieGetClientData, XiePutClientData XIElib - Stored Photoflo Functions XieModifyPhotoflo Name XieModifyPhotoflo - modify a stored photoflo Syntax void XieModifyPhotoflo (display, photoflo, start, elem_list, elem_count) Display *display; XiePhotoflo photoflo; int start; XiePhotoElement *elem_list; int elem_count; Arguments display Specifies a connection to an X server. photoflo Specifies the photoflo to be modified. start Specifies the index where element replacement is to begin. elem_list Specifies an array of elements that will replace existing elements. elem_count Specifies the number of items in elem_list. Description XieModifyPhotoflo allows element parameters of a stored photoflo to be modified. Stored photoflos persist beyond execution and may be modified prior to subsequent executions. start is the position or index of an element within an array of elements used to specify a photoflo; the first element in the array has a start value of one (1). XieModifyPhotoflo only allows parameter modification. No topological changes are allowed: elements cannot be deleted, inserted, or appended. Structures typedef XID XiePhotoflo; typedef struct { int elemType; /* union of ALL element types */ union { ... ... } data; } XiePhotoElement; Errors xieErrNoPhotoflo The value for the photoflo argument does not name a defined photoflo xieErrNoFloAccess Attempt to change photoflo when it is already active xieErrNoFloAlloc Insufficient resources (for example, memory) xieErrNoFloElement Invalid element type(s) in elem_list or attempt to append additional element(s) to photoflo xieErrNoFloSource An invalid start has been specified or attempt to change input connections of type XiePhototag in elem_list xieErrNoFlo An error has been detected while defining, executing, or accessing a photoflo (see Photoflo Errors). See Also XieAllocatePhotofloGraph, XieFreePhotofloGraph, XieCreatePhotoflo, XieRedefinePhotoflo, XieExecutePhotoflo, XieQueryPhotoflo, XieDestroyPhotoflo XIElib - Stored Photoflo Functions XieRedefinePhotoflo Name XieRedefinePhotoflo - redefine a stored photoflo Syntax void XieRedefinePhotoflo (display, photoflo, elem_list, elem_count) Display *display; XiePhotoflo photoflo; XiePhotoElement *elem_list; int elem_count; Arguments display Specifies a connection to an X server. photoflo Specifies the photoflo to be redefined. elem_list Specifies an array of elements that will replace all existing elements. elem_count Specifies the number of items in elem_list. Description XieRedefinePhotoflo allows all elements of a stored photoflo to be removed and replaced with a new list. Stored photoflos persist beyond execution and may be totally redefined prior to subsequent executions. There are no restrictions on changing element types or the array's size. Structures typedef XID XiePhotoflo; typedef struct { int elemType; /* union of ALL element types */ union { ... ... } data; } XiePhotoElement; Errors xieErrNoPhotoflo The value for the photoflo argument does not name a defined photoflo xieErrNoFloAccess Attempt to change photoflo when it is already active xieErrNoFloAlloc Insufficient resources (for example, memory) xieErrNoFloElement Invalid element type(s) in elem_list xieErrNoFlo An error has been detected while defining, executing, or accessing a photoflo (see Photoflo Errors). See Also XieAllocatePhotofloGraph, XieFreePhotofloGraph, XieCreatePhotoflo, XieModifyPhotoflo, XieExecutePhotoflo, XieQueryPhotoflo, XieDestroyPhotoflo XIElib - Photoflo Functions XieQueryPhotoflo Name XieQueryPhotoflo - return the current status of a photoflo Syntax XieQueryPhotoflo(display, name_space, flo_id, state_ret, data_expected_ret, nexpected_ret, data_available_ret, navailable_ret) Display *display; unsigned long name_space; unsigned long flo_id; XiePhotofloState *state_ret; XiePhototag **data_expected_ret; unsigned int *nexpected_ret; XiePhototag **data_available_ret; unsigned int *navailable_ret; Arguments display Specifies a connection to an X server. name_space Specifies the execution domain used for the photoflo to query. flo_id Specifies a particular instance of the photoflo to query. state_ret Returns the state of the photoflo. data_expected_ret Returns a list of ImportClient elements. nexpected_ret Returns the length of data_expected_ret. data_available_ret Returns a list of ExportClient elements. navailable_ret Returns the length of data_available_ret. Returns Zero on failure, nonzero on success. Description XieQueryPhotoflo will return the current status of a photoflo. The name_space/flo_id argument pair specifies the instance that identifies the photoflo that is being queried. state_ret indicates the state of the photoflo, and if XieQueryPhotoflo is successful, will return one of the following standard photoflo state values: xieValInactive xieValActive xieValNonexistent data_expected_ret is a list of ImportClient elements that are expecting data via XiePutClientData. data_available_ret is a list of ExportClient elements from which data are available (via XieGetClientData). Either or both of these lists may be of length zero, indicated by the returned values of nexpected_ret and navailable_ret. XieQueryPhotoflo allocates memory for the list of ImportClient elements and the list of ExportClient elements. To free the memory allocated to data_expected_ret and data_available_ret, use XFree. Specifying an unknown or invalid instance will return a state_ret of nonexistent and zero length data_expected_ret and data_available_ret lists. Structures typedef unsigned XiePhotofloState; /* Definitions of PhotofloState */ #define xieValInactive 1 #define xieValActive 2 #define xieValNonexistent 3 Errors xieErrNoFloAlloc Insufficient resources (for example, memory) See Also XieCreatePhotoflo, XieModifyPhotoflo, XieRedefinePhotoflo, XieExecutePhotoflo, XieDestroyPhotoflo, XieGetClientData, XiePutClientData XIElib - Client Data Functions XiePutClientData Name XiePutClientData - send a stream of data to an active photoflo Syntax void XiePutClientData (display, name_space, flo_id, element, final, band_number, data, nbytes) Display *display; unsigned long name_space; unsigned long flo_id; XiePhototag element; Bool final; unsigned band_number; unsigned char *data; unsigned nbytes; Arguments display Specifies a connection to an X server. name_space Specifies the execution domain used for the photoflo to receive the data. flo_id Specifies a particular instance of the photoflo to receive the data. element Specifies the element to receive the data. final Specifies if the data is the last segment of data to be sent. If True, then data represents the last data to be sent by the client. False indicates that more data will be sent (during a subsequent call to XiePutClientData). band_number Specifies which band of data is being sent. data Specifies a counted list of bytes that comprises the data stream. nbytes Specifies the count of bytes that comprises the data stream. Description XiePutClientData sends a stream of data to an active photoflo. Since the complete data object may be larger than can fit in a single protocol request, XIE allows the stream to be segmented; the last segment is signaled with a final flag. The organization and contents of the data stream must match the parameters given to the ImportClient element or the results are undefined. An arbitrary amount of image data can be sent per request, whereas for 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. For stored photoflos, name_space is always ServerIDSpace (the value zero) and flo_id is the photoflo's resource-id. For immediate photoflos name_space is a photospace resource-id and flo_id is 32-bit value that uniquely identifies the instance of the photoflo within name_space. Structures typedef unsigned XiePhototag; Errors xieErrNoFloAccess Executable photospace/flo_id argument pair not active xieErrNoFloAlloc Insufficient resources (for example, memory) xieErrNoFloElement Invalid element type specified by element xieErrNoFloID Invalid photospace/flo_id argument pair has been specified xieErrNoFloValue Invalid band_number or for nonimage data, data contains a partial aggregate See Also XieGetClientData, XieQueryPhotoflo, XieFloImportClientPhoto, XieFloImportClientROI, XieFloImportClientLUT XIElib - Client Data Functions XieGetClientData Name XieGetClientData - retrieve data from an ExportClient element within an active photoflo Syntax Status XieGetClientData (display, name_space, flo_id, element, max_bytes, terminate, band_number, new_state_ret, data_ret, nbytes_ret) Display *display; unsigned long name_space; unsigned long flo_id; XiePhototag element; unsigned max_bytes; Bool terminate; unsigned band_number; XieExportState *new_state_ret; unsigned char **data_ret; unsigned *nbytes_ret; Arguments display Specifies a connection to an X server. name_space Specifies the execution domain used for the photoflo from which to retrieve data. flo_id Specifies a particular instance of the photoflo from which to retrieve data. element Specifies the element from which to retrieve the data. max_bytes Specifies the maximum number of bytes that can be sent to the client. terminate Specifies whether more data are wanted after this request. band_number Specifies which band of data is being retrieved. new_state_ret Returns the status of the ExportClient element after this request. data_ret Returns a counted list of bytes that comprises the data stream. nbytes_ret Returns the count of bytes that comprises the data stream. Returns Zero on failure, nonzero on success. Description XieGetClientData returns data 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 of data available from the server. The format of the data depends on the parameters given to the ExportClient element from which the data are requested. new_state_ret returns the state of the ExportClient element after this request and can be set to one of the following standard export state values: xieValExportDone xieValExportMore xieValExportEmpty xieValExportError If the request is sent to an ExportClient element that either: does not have any data, was terminated by a previous XieGetClientData call, or has already returned all its data (ExportDone sent), the request will return a zero length data_ret 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. max_bytes is effectively rounded down by the server to the match the nearest aggregate size. For stored photoflos, name_space is always ServerIDSpace (the value zero) and flo_id is the photoflo'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. To free the memory allocated to data_ret, use XFree. Structures typedef unsigned XieExportState; typedef unsigned XiePhototag; /* Definitions of ExportState */ #define xieValExportDone 1 #define xieValExportMore 2 #define xieValExportEmpty 3 #define xieValExportError 4 Errors xieErrNoFloAccess Executable photospace/flo_id argument pair not active xieErrNoFloAlloc Insufficient resources (for example, memory) xieErrNoFloElement Invalid element type specified by element xieErrNoFloID Invalid photospace/flo_id argument pair has been specified xieErrNoFloValue Invalid band_number See Also XiePutClientData, XieQueryPhotoflo, XieExecutePhotoflo, XieFloExportClientHistogram, XieFloExportClientLUT, XieFloExportClientPhoto, XieFloExportClientROI XIElib - Abort and Await Functions XieAbort Name XieAbort - prematurely terminate execution of a photoflo Syntax void XieAbort (display, name_space, flo_id); Display *display; unsigned long name_space; unsigned long flo_id; Arguments display Specifies a connection to an X server. name_space Specifies the execution domain used for the photoflo to abort. flo_id Specifies a particular instance of the photoflo to abort. Description XieAbort will prematurely terminate execution of the photoflo specified by name_space and flo_id. Any output from the photoflo that is pending client retrieval is freed. Stored photoflos are returned to the inactive state; immediate photoflos are destroyed. If the photoflo specified by name_space and flo_id is either invalid or not active, no action is taken; it is not an error, and nothing is destroyed. For stored photoflos, name_space is always ServerIDSpace (the value zero) and flo_id is the photoflo's resource-id. For immediate photoflos name_space is a photospace resource-id and flo_id is 32-bit value that uniquely identifies the instance of the photoflo within name_space. See Also XieExecutePhotoflo, XieExecuteImmediate XIElib - Abort and Await Functions XieAwait Name XieAwait - block all further requests for this client connection from being honored by the server while the photoflo is active Syntax void XieAwait (display, name_space, flo_id); Display *display; unsigned long name_space; unsigned long flo_id; Arguments display Specifies a connection to an X server. name_space Specifies the execution domain used for the photoflo to block requests. flo_id Specifies a particular instance of the photoflo to block requests. Description XieAwait blocks all further requests for this client connection from being honored by the server while the photoflo, specified by name_space and flo_id, is active. When the photoflo transitions from the active state, blocked requests are allowed to be processed in the order received. If the photoflo specified by name_space and flo_id is either invalid or not active, no action is taken; it is not an error, and the client is not blocked. For stored photoflos, name_space is always ServerIDSpace (the value zero) and flo_id is the photoflo's resource-id. For immediate photoflos name_space is a photospace resource-id and flo_id is 32-bit value that uniquely identifies the instance of the photoflo within name_space. Warning Calling XieAwait before sending all import data or before retrieving all export data will block the client from sending or retrieving the remaining data. This also will prevent completion of the photoflo and prevent any and all protocol requests from this client from being honored. This deadlock can be broken only by another client completing or aborting the photoflo (to release the Await), or by breaking the client connection. Errors xieErrNoFloAlloc Insufficient resources (for example, memory) See Also XieExecutePhotoFlo, XieExecuteImmediate XIElib - Photoflo Element Functions XieFloImportClientLUT Name XieFloImportClientLUT - specify an ImportClientLUT element and set its parameters Syntax void XieFloImportClientLUT (element, data_class, band_order, length, levels) XiePhotoElement *element; XieDataClass data_class; XieOrientation band_order; XieLTriplet length; XieLevels levels; Arguments element Specifies the XiePhotoElement structure to use. data_class Specifies the number of lookup arrays to expect. band_order Specifies the order of triple band arrays. length Specifies the number of entries per array. levels Specifies the number of quantization levels represented per array. Description An ImportClientLUT element accepts lookup table data from the protocol stream. The transport of data through the protocol stream is accomplished using XiePutClientData. This data is accepted by the Point, ExportLUT, and ExportClientLUT elements. data_class, which specifies the number of lookup arrays to expect, can be set to one of the following standard data class values: xieValSingleBand xieValTripleBand The length of each array should match the number of source image levels that will be remapped through the array. When a triple band image is to be remapped through a single band array, the length of the array should match the product of the source image levels of all three bands; in this case, band_order specifies the order in which pixels from a triple band image should be combined to form indices for a single band array. band_order can be set to one of the following standard orientation values: xieValLSFirst xieValMSFirst 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. When one LUT array is used with triple band data, the algorithm for computing combined array indices, based on band_order, is: LUT band order LUT indexing algorithm for combining pixel values LSFirst index = value[0] + value[1] x levels[0] + value[2] x levels[0] x levels[1] MSFirst index = value[2] + value[1] x levels[2] + value[0] x levels[2] x levels[1] When three LUT arrays are used, band_order specifies whether this band corresponds with the least significant or most significant LUT array. Each array is transported as a separate data stream. For example, if the colorspace of the image data is RGB: band LSFirst MSFirst 0 Red array Blue array 1 Green array Green array 2 Blue array Red array Structures XieFloImportClientLUT sets the XiePhotoElement structure field elemType to xieElemImportClientLUT, which identifies the element as an ImportClientLUT, and sets the fields of the member structure ImportClientLUT using the arguments in the argument list. typedef unsigned XieDataClass; typedef unsigned XieOrientation; typedef unsigned long XieLTriplet[3]; typedef unsigned long XieLevels[3]; typedef struct { int elemType; union { ... struct { XieDataClass data_class; XieOrientation band_order; XieLTriplet length; XieLevels levels; } ImportClientLUT; ... } data; } XiePhotoElement; /* Definitions of DataClass */ #define xieValSingleBand 1 #define xieValTripleBand 2 /* Definitions of Orientation Types */ #define xieValLSFirst 1 #define xieValMSFirst 2 Errors xieErrNoFloAlloc Insufficient resources (for example, memory) xieErrNoFloMatch levels is incompatible with the server's depth-handling capabilities xieErrNoFloValue Invalid data_class or band_order See Also XiePutClientData, XieQueryPhotoflo, XieFloExportLUT, XieFloExportClientLUT, XieFloPoint, XieFloImportLUT XIElib - Photoflo Element Functions XieFloImportClientPhoto Name XieFloImportClientPhoto - specify an ImportClientPhoto element and set its parameters Syntax void XieFloImportClientPhoto (element, data_class, width, height, levels, notify, decode_tech, decode_param) XiePhotoElement *element; XieDataClass data_class; XieLTriplet width; XieLTriplet height; XieLevels levels; Bool notify; XieDecodeTechnique decode_tech; XiePointer decode_param; Arguments element Specifies the XiePhotoElement structure to use. data_class Specifies whether the data is single band or triple band. width Specifies the width of the image in pixels per band. height Specifies the height of the image in pixels per band. levels Specifies the number of quantization levels per band. notify Specifies whether to enable sending DecodeNotify events. decode_tech Specifies the decode technique required to interpret the image. decode_param Specifies the list of additional parameters required by decode_tech. Description An ImportClientPhoto element accepts image data from the protocol stream. This data may be processed for display or used as process domain data. A process domain is inserted in many element definitions and is used to restrict the element's processing to a subset of the source data pixels. 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 XiePutClientData. notify enables DecodeNotify events to be sent if anomalies are encountered while interpreting the imported image data: either an error has been encountered while decoding an image or the image data received does not satisfy the expected dimensions. Only constrained data can be sent through the protocol stream; therefore, levels must be valid. data_class specifies whether the data is single band or triple band and can be set to one of the following standard data class values: xieValSingleBand xieValTripleBand Decode techniques define the techniques that can be used to interpret uncompressed image data or decode compressed images. decode_tech can be assigned one of the following standard decode technique values: xieValDecodeUncompressedSingle xieValDecodeUncompressedTriple xieValDecodeG31D xieValDecodeG32D xieValDecodeG42D xieValDecodeJPEGBaseline xieValDecodeJPEGLossless xieValDecodeTIFF2 xieValDecodeTIFFPackBits If a vendor defined additional private decode techniques, the values given to these techniques can be assigned to decode_tech. Output Attributes 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 Structures XieFloImportClientPhoto sets the XiePhotoElement structure field elemType to xieElemImportClientPhoto, which identifies the element as an ImportClientPhoto, and sets the fields of the member structure ImportClientPhoto using the arguments in the argument list. typedef unsigned XieDataClass; typedef unsigned XieDecodeTechnique; typedef unsigned long XieLTriplet[3]; typedef unsigned long XieLevels[3]; typedef struct { int elemType; union { ... struct { XieDataClass data_class; XieLTriplet width; XieLTriplet height; XieLevels levels; Bool notify; XieDecodeTechnique decode_tech; XiePointer decode_param; } ImportClientPhoto; ... } data; } XiePhotoElement; /* Definitions of DataClass */ #define xieValSingleBand 1 #define xieValTripleBand 2 /* Definitions for DecodeTechniques */ #define xieValDecodeUncompressedSingle 2 #define xieValDecodeUncompressedTriple 3 #define xieValDecodeG31D 4 #define xieValDecodeG32D 6 #define xieValDecodeG42D 8 #define xieValDecodeJPEGBaseline 10 #define xieValDecodeJPEGLossless 12 #define xieValDecodeTIFF2 14 #define xieValDecodeTIFFPackBits 16 Errors xieErrNoFloAlloc Insufficient resources (for example, memory) xieErrNoFloMatch levels is incompatible with the server's depth-handling capabilities xieErrNoFloTechnique Invalid decode_tech or decode_param xieErrNoFloValue Invalid width, height, levels (zero) or invalid data_class See Also XieTecDecodeUncompressedSingle, XieTecDecodeUncompressedTriple, XieTecDecodeG31D, XieTecDecodeG32D, XieTecDecodeG42D, XieTecDecodeTIFF2, XieTecDecodeTIFFPackBits, XieTecDecodeJPEGBaseline, XieTecDecodeJPEGLossless XIElib - Photoflo Element Functions XieFloImportClientROI Name XieFloImportClientROI - specify an ImportClientROI element and set its parameters Syntax void XieFloImportClientROI (element, rectangles); XiePhotoElement *element; unsigned int rectangles; Arguments element Specifies the XiePhotoElement structure to use. rectangles Specifies the number of rectangles expected. Description An ImportClientROI element accepts a list of rectangles from the protocol stream. These data can be used as input to a process domain or an ExportROI or ExportClientROI element. A process domain is inserted in many element definitions and is used to restrict the element's processing to a subset of the source data pixels. The actual transport of data through the protocol stream is accomplished using XiePutClientData (the band_number parameter of XiePutClientData is ignored). Structures XieFloImportClientROI sets the XiePhotoElement structure field elemType to xieElemImportClientROI, which identifies the element as an ImportClientROI, and sets the fields of the member structure ImportClientROI using the arguments in the argument list. typedef struct { int elemType; union { ... struct { unsigned int rectangles; } ImportClientROI; ... } data; } XiePhotoElement; Errors xieErrNoFloAlloc Insufficient resources (for example, memory) See Also XiePutClientData, XieQueryPhotoflo XieFloExportROI, XieFloExportClientROI, XieFloImportROI XIElib - Photoflo Element Functions XieFloImportDrawable Name XieFloImportDrawable - specify an ImportDrawable element and set its parameters Syntax void XieFloImportDrawable (element, drawable, src_x, src_y, width, height, fill, notify) XiePhotoElement *element; Drawable drawable; int src_x; int src_y; unsigned int width; unsigned int height; unsigned long fill; Bool notify; Arguments element Specifies the XiePhotoElement structure to use. drawable Specifies the Drawable resource supplying the data. src_x Specifies the left corner of the region of the data to be imported. src_y Specifies the upper corner of the region of the data to be imported. width Specifies the width of the region of the data to be imported. height Specifies the height of the region of the data to be imported. fill Specifies the Colormap index to use for all regions that are obscured. notify Specifies whether to enable sending ImportObscured events. Description An ImportDrawable element allows access to data existing in a Drawable. This data may be processed for display or, if drawable is one bit deep, used as process domain data. A process domain is inserted in many element definitions and is used to restrict the element's processing to a subset of the source data pixels. notify enables ImportObscured events to be sent if data for one or more regions of a Window are obscured and cannot be retrieved from backing store. The arguments src_x, src_y, width, and height specify the region of data to be imported from drawable, where src_x and src_y define the upper-left corner of the region. Output Attributes Class single band Type constrained Width width Height height Levels 2depth (that is, drawable depth) Structures XieFloImportDrawable sets the XiePhotoElement structure field elemType to xieElemImportDrawable, which identifies the element as an ImportDrawable, and sets the fields of the member structure ImportDrawable using the arguments in the argument list. typedef struct { int elemType; union { ... struct { Drawable drawable; int src_x; int src_y; unsigned int width; unsigned int height; unsigned long fill; Bool notify; } ImportDrawable; ... } data; } XiePhotoElement; Errors xieErrNoFloAlloc Insufficient resources (for example, memory) xieErrNoFloDrawable Invalid drawable xieErrNoFloValue Invalid region width, height, src_x, src_y XIElib - Photoflo Element Functions XieFloImportDrawablePlane Name XieFloImportDrawablePlane - specify an ImportDrawablePlane element and set its parameters Syntax void XieFloImportDrawablePlane (element, drawable, src_x, src_y, width, height, fill, bit_plane, notify) XiePhotoElement *element; Drawable drawable; int src_x; int src_y; unsigned int width; unsigned int height; unsigned long fill; unsigned long bit_plane; Bool notify; Arguments element Specifies the XiePhotoElement structure to use. drawable Specifies the Drawable resource supplying the data. src_x Specifies the left corner of the region of the data to be imported. src_y Specifies the upper corner of the region of the data to be imported. width Specifies the width of the region of the data to be imported. height Specifies the height of the region of the data to be imported. fill Specifies the Colormap index to use for all regions that are obscured. bit_plane Specifies the plane to be imported from drawable. notify Specifies whether to enable sending ImportObscured events. Description An ImportDrawablePlane event allows access to a single plane of data existing in a Drawable. This data may be processed for display or used as process domain data. A process domain is inserted in many element definitions and is used to restrict the element's processing to a subset of the source data pixels. notify enables ImportObscured events to be sent if data for one or more regions of a Window are obscured and cannot be retrieved from backing store. The arguments src_x, src_y, width, and height specify the region of data to be imported from drawable, where src_x and src_y define the upper-left corner of the region. bit_plane must have exactly one bit set to one (1), and the value of bit_plane must be less than or equal to , where n is the depth of drawable. This single bit selects the corresponding bit to be extracted from pixels within drawable. Output Attributes Class single band Type constrained Width width Height height Levels 2 Structures XieFloImportDrawablePlane sets the XiePhotoElement structure field elemType to xieElemImportDrawablePlane, which identifies the element as an ImportDrawablePlane, and sets the fields of the member structure ImportDrawablePlane using the arguments in the argument list. typedef struct { int elemType; union { ... struct { Drawable drawable; int src_x; int src_y; unsigned int width; unsigned int height; unsigned long fill; unsigned long bit_plane; Bool notify; } ImportDrawablePlane; ... } data; } XiePhotoElement; Errors xieErrNoFloAlloc Insufficient resources (for example, memory) xieErrNoFloDrawable Invalid drawable xieErrNoFloValue Invalid bit_plane or region width, height, src_x, src_y XIElib - Photoflo Element Functions XieFloImportLUT Name XieFloImportLUT - specify an ImportLUT element and set its parameters Syntax void XieFloImportLUT (element, lut) XiePhotoElement *element; XieLut lut; Arguments element Specifies the XiePhotoElement structure to use. lut Specifies the LUT resource supplying the lookup table. Description An ImportLUT element allows access to lookup table data existing in a LUT resource. These data are accepted by the Point, ExportLUT, and ExportClientLUT elements. Attributes of the lookup table data are inherited from lut. Structures XieFloImportLUT sets the XiePhotoElement structure field elemType to xieElemImportLUT, which identifies the element as an ImportLUT, and sets the fields of the member structure ImportLUT using the arguments in the argument list. typedef XID XieLut; typedef struct { int elemType; union { ... struct { XieLut lut; } ImportLUT; ... } data; } XiePhotoElement; Errors xieErrNoFloAccess Attempt to import from lut before it has been populated xieErrNoFloAlloc Insufficient resources (for example, memory) xieErrNoFloLUT An unknown lut has been specified XIElib - Photoflo Element Functions XieFloImportPhotomap Name XieFloImportPhotomap - specify an ImportPhotomap element and set its parameters Syntax void XieFloImportPhotomap (element, photomap, notify) XiePhotoElement *element; XiePhotomap photomap; Bool notify; Arguments element Specifies the XiePhotoElement structure to use. photomap Specifies the photomap resource supplying image data. notify Specifies whether to enable sending DecodeNotify events. Description An ImportPhotomap element allows access to image data existing in a photomap; a photomap is a server resource that can be used to store image data. This data may be processed for display or used as process domain data (if its levels attribute is 2), or it may be used as source to ExportPhotomap or ExportClientPhoto or any other element which takes image data as input. A process domain is inserted in many element definitions and is used to restrict the element's processing to a subset of the source data pixels. notify enables DecodeNotify events to be sent if anomalies are encountered while decoding compressed data: either an error has been encountered while decoding an image or the image data received does not satisfy the expected dimensions. Attributes of the source data are inherited from photomap. Output Attributes Class same as photomap Type same as photomap Width same as photomap Height same as photomap Levels same as photomap Structures XieFloImportPhotomap sets the XiePhotoElement structure field elemType to xieElemImportPhotomap, which identifies the element as an ImportPhotomap, and sets the fields of the member structure ImportPhotomap using the arguments in the argument list. typedef XID XiePhotomap; typedef struct { int elemType; union { ... struct { XiePhotomap photomap; Bool notify; } ImportPhotomap; ... } data; } XiePhotoElement; Errors xieErrNoFloAccess Attempt to import from photomap before it has been populated xieErrNoFloAlloc Insufficient resources (for example, memory) xieErrNoFloPhotomap An unknown photomap has been specified See Also XieFloExportPhotomap, XIeFloExportClientPhoto XIElib - Photoflo Element Functions XieFloImportROI Name XieFloImportROI - specify an ImportROI element and set its parameters Syntax void XieFloImportROI (element, roi) XiePhotoElement *element; XieRoi roi; Arguments element Specifies the XiePhotoElement structure to use. roi Specifies the ID of the ROI supplying the list-of-rectangles. Description An ImportROI element allows access to a list-of-rectangles existing in a ROI resource. This data may be referenced by a process domain, or used as input to an ExportClientROI or ExportROI element. A process domain is inserted in many element definitions and is used to restrict the element's processing to a subset of the source data pixels. Structures XieFloImportROI sets the XiePhotoElement structure field elemType to xieElemImportROI, which identifies the element as an ImportROI, and sets the fields of the member structure ImportROI using the arguments in the argument list. typedef XID XieRoi; typedef struct { int elemType; union { ... struct { XieRoi roi; } ImportROI; ... } data; } XiePhotoElement; Errors xieErrNoFloAccess Attempt to import from roi before it has been populated xieErrNoFloAlloc Insufficient resources (for example, memory) xieErrNoFloPhotomap An unknown roi has been specified See Also XieFloExportROI, XieFloExportClientROI XIElib - Photoflo Element Functions XieFloArithmetic Name XieFloArithmetic - specify an Arithmetic element and set its parameters Syntax void XieFloArithmetic (element, src1, src2, domain, constant, operator, band_mask) XiePhotoElement *element; XiePhototag src1; XiePhototag src2; XieProcessDomain *domain; XieConstant constant; XieArithmeticOp operator; unsigned int band_mask; Arguments element Specifies the XiePhotoElement structure to use. src1 Specifies the phototag of the first data source. src2 Specifies the phototag of the second data source, or 0 if none. domain Specifies the subset of source data that will be operated on. constant Specifies the constant data source (if src2 is 0). operator Specifies the arithmetic operation to be performed. band_mask Specifies which bands are to be operated on. Description An Arithmetic element produces output data by performing an addition, subtraction, minimum, or maximum operation between two data sources or between a single data source and a constant. Furthermore, multiplication, division, or gamma correction may by applied to a single data source. When two sources are involved, src1 and src2 are the phototags of the elements supplying source data (constant is ignored). A phototag is the position or index of an element within an array of elements used to specify a photoflo; the first element in the array has a phototag value of one (1). If the operation is to involve a constant, src1 is one operand, src2 must be zero, and constant is used as the other operand. When two sources are involved, all attributes, other than width and height, must match; all output attributes are inherited from src1. In order to specify a subset of source data that will be operated on, the phototag, offset_x, and offset_y fields of the XieProcessDomain structure pointed to by domain must be supplied; XIElib does not provide a convenience function to create and/or fill in an XieProcessDomain structure. If the entire source data is to be operated on, a pointer to an XieProcessDomain structure must still be provided, with the phototag field set to zero (0); the offset_x and offset_y fields are ignored. Only bands selected by 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 significant band would be processed; operating on all bands requires a band_mask of 1112. Using band_mask to select source data that have two (2) or less levels is not permitted. 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). The valid operations for the Arithmetic process element are: Operator src1 (operator) src2 src1 (operator) constant xieValAdd src1 + src2 src1 + constant xieValSub src1 - src2 src1 - constant xieValSubRev src2 - src1 constant - src1 xieValMul src1 * constant xieValDiv src1 / constant xieValDivRev constant / src1 xieValMin minimum( src1, src2 ) minimum( src1, constant ) xieValMax maximum( src1, src2 ) maximum( src1, constant ) xieValGamma (constrained) (levels - 1) * ((src1 / (levels - 1))constant) xieValGamma (unconstrained) src1constant Output Attributes Class same as src1 Type same as src1 Width same as src1 Height same as src1 Levels same as src1 Structures XieFloArithmetic sets the XiePhotoElement structure field elemType to xieElemArithmetic, which identifies the element as an Arithmetic, and sets the fields of the member structure Arithmetic using the arguments in the argument list. typedef unsigned XiePhototag; typedef float XieConstant[3]; typedef unsigned XieArithmeticOp; typedef struct { int offset_x; int offset_y; XiePhototag phototag; } XieProcessDomain; typedef struct { int elemType; union { ... struct { XiePhototag src1; XiePhototag src2; XieProcessDomain domain; XieConstant constant; XieArithmeticOp operator; unsigned int band_mask; } Arithmetic; ... } data; } XiePhotoElement; /* Definitions of ArithmeticOperations */ #define xieValAdd 1 #define xieValSub 2 #define xieValSubRev 3 #define xieValMul 4 #define xieValDiv 5 #define xieValDivRev 6 #define xieValMin 7 #define xieValMax 8 #define xieValGamma 9 Errors xieErrNoFloAlloc Insufficient resources (for example, memory) xieErrNoFloDomain Invalid domain xieErrNoFloMatch Class, type, or levels differ between src1 and src2 or selected data source are bitonal xieErrNoFloOperator Invalid operator xieErrNoFloSource Invalid src1 or src2 or src2 has been specified with a monadic operator XIElib - Photoflo Element Functions XieFloBandCombine Name XieFloBandCombine - specify a BandCombine element and set its parameters Syntax void XieFloBandCombine (element, src1, src2, src3) XiePhotoElement *element; XiePhototag src1; XiePhototag src2; XiePhototag src3; Arguments element Specifies the XiePhotoElement structure to use. src1 Specifies the first element supplying source data. src2 Specifies the second element supplying source data. src3 Specifies the third element supplying source data. Description A BandCombine element merges three single band data sources to produce a triple band result. The arguments src1, src2, and src3 must be of the same type, and each source must be single band. Other attributes that are taken from the individual sources may differ. The output will be triple band. Output Attributes Class triple band Type same as src1 Width same as srcs Height same as srcs Levels same as srcs Structures XieFloBandCombine sets the XiePhotoElement structure field elemType to xieElemBandCombine, which identifies the element as a BandCombine, and sets the fields of the member structure BandCombine using the arguments in the argument list. typedef unsigned XiePhototag; typedef struct { int elemType; union { ... struct { XiePhototag src1; XiePhototag src2; XiePhototag src3; } BandCombine; ... } data; } XiePhotoElement; Errors xieErrNoFloAlloc Insufficient resources (for example, memory) xieErrNoFloMatch A source has more than one band or type differs between sources xieErrNoFloSource Invalid src1, src2, or src3 XIElib - Photoflo Element Functions XieFloBandExtract Name XieFloBandExtract - specify a BandExtract element and set its parameters Syntax void XieFloBandExtract (element, src, levels, bias, coefficients) XiePhotoElement *element; XiePhototag src; unsigned int levels; double bias; XieConstant coefficients; Arguments element Specifies the XiePhotoElement structure to use. src Specifies the element supplying source data. levels Specifies the number of quantization levels for the output. bias Specifies the value to be added to each output pixel. coefficients Specifies the proportion of each band in src to pixelsin the single band result. Description A BandExtract element produces single band output data from a triple band source by multiplying a pixel value from each source band by its corresponding coefficient and then summing the results with the bias value. coefficients is a three-element array that determines the proportion of each source band pixel that is used to form the output. 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 triple band, and all bands must have equal dimensions. The output data will be single band, with levels taken from the levels parameter, if the data type is constrained. All other attributes are inherited from src. Output Attributes Class single band Type same as src Width same as src Height same as src Levels levels if src is contrained, else unknown Structures XieFloBandExtract sets the XiePhotoElement structure field elemType to xieElemBandExtract, which identifies the element as a BandExtract, and sets the fields of the member structure BandExtract using the arguments in the argument list. typedef float XieConstant[3]; typedef unsigned XiePhototag; typedef struct { int elemType; union { ... struct { XiePhototag src; unsigned int levels; float bias; XieConstant coefficients; } BandExtract; ... } data; } XiePhotoElement; Errors xieErrNoFloAlloc Insufficient resources (for example, memory) xieErrNoFloMatch src is not triple band or unequal interband dimensions xieErrNoFloSource Invalid src XIElib - Photoflo Element Functions XieFloBandSelect Name XieFloBandSelect - specify a BandSelect element and set its parameters Syntax void XieFloBandSelect (element, src, band_number) XiePhotoElement *element; XiePhototag src; unsigned int band_number; Arguments element Specifies the XiePhotoElement structure to use. src Specifies the element supplying source data. band_number Specifies which src band is to be selected to provide the output data. Description A BandSelect element produces single band output data by selecting a single band from a triple band source. Output Attributes Class single band 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 Structures XieFloBandSelect sets the XiePhotoElement structure field elemType to xieElemBandSelect, which identifies the element as a BandSelect, and sets the fields of the member structure BandSelect using the arguments in the argument list. typedef unsigned XiePhototag; typedef struct { int elemType; union { ... struct { XiePhototag src; unsigned int band_number; } BandSelect; ... } data; } XiePhotoElement; Errors xieErrNoFloAlloc Insufficient resources (for example, memory) xieErrNoFloMatch src is not triple band xieErrNoFloSource Invalid src xieErrNoFloValue Invalid band_number XIElib - Photoflo Element Functions XieFloBlend Name XieFloBlend - specify a Blend element and set its parameters Syntax void XieFloBlend (element, src1, src2, src_constant, alpha, alpha_const, domain, band_mask) XiePhotoElement *element; XiePhototag src1; XiePhototag src2; XieConstant src_constant; XiePhototag alpha; double alpha_const; XieProcessDomain *domain; unsigned int band_mask; Arguments element Specifies the XiePhotoElement structure to use. src1 Specifies the phototag of the first data source. src2 Specifies the phototag of the second data source, else 0. src_constant Specifies a constant data source, if src2 is 0. alpha Specifies the blend proportion for each processed pixel. alpha_const Specifies the constant blend proportion for each processed pixel. domain Specifies the subset of source data that will be operated on. band_mask Specifies which bands are to be operated on. Description A Blend element produces output data from two data sources or a single data source and a constant. Each output pixel is a percentage combination of the source values, as controlled by an alpha input image or an alpha constant. When two sources are involved, src1 and src2 are the phototags of the elements supplying source data; src_constant is ignored. A phototag is the position or index of an element within an array of elements used to specify a photoflo; the first element in the array has a phototag value of one (1). If the operation is to involve a constant, src1 is one operand, src2 must be zero, and src_constant is used as the other operand. If alpha is nonzero, it controls the blend proportion for each pixel that is processed, otherwise alpha_const provides this control. Domain may control the subset of source data that will be operated on. 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 significant band would be processed; operating on all bands requires a band_mask of 1112. Using band_mask to select source data that have two (2) or less levels is not permitted. 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. In order to specify a subset of source data that will be operated on, the phototag, offset_x, and offset_y fields of the XieProcessDomain structure pointed to by domain must be supplied; XIElib does not provide a convenience function to create and/or fill in an XieProcessDomain structure. If the entire source data is to be operated on, a pointer to an XieProcessDomain structure must still be provided, with the phototag field set to zero (0); the offset_x and offset_y fields are ignored. Within the intersection of the source(s) and domain, each output pixel is a blend of the corresponding pixels from src1 and src2 (or src1 pixels blended with src_constant). The degree of blend is determined by the corresponding pixel taken from alpha or the value of alpha_const. If alpha is nonzero, the proportion of blend is further scaled by alpha_const: output = src1 * (1 - alpha / alpha_const) + src2 * (alpha / alpha_const) (where alpha_const is greater than 0.0) if alpha is zero: output = src1 * (1 - alpha_const) + src2 * alpha_const (where alpha_const is in the range [0.0, 1.0]) Output Attributes Class same as src1 Type same as src1 Width same as src1 Height same as src1 Levels same as src1 Structures XieFloBlend sets the XiePhotoElement structure field elemType to xieElemBlend, which identifies the element as a Blend, and sets the fields of the member structure Blend using the arguments in the argument list. typedef unsigned XiePhototag; typedef float XieConstant[3]; typedef struct { int offset_x; int offset_y; XiePhototag phototag; } XieProcessDomain; typedef struct { int elemType; union { ... struct { XiePhototag src1; XiePhototag src2; XieConstant src_constant; XiePhototag alpha; float alpha_constant; XieProcessDomain domain; unsigned int band_mask; } Blend; ... } data; } XiePhotoElement; Errors xieErrNoFloAlloc Insufficient resources (for example, memory) xieErrNoFloMatch Incompatible attributes between src1 and src2 or alpha is unconstrained or selected source data are bitonal xieErrNoFloSource Invalid src1, src2, or alpha xieErrNoFloValue alpha is zero and alpha_const is outside the range [0.0,1.0], or alpha is nonzero and alpha_const is nonpositive XIElib - Photoflo Element Functions XieFloCompare Name XieFloCompare - specify a Compare element and set its parameters Syntax void XieFloCompare (element, src1, src2, domain, constant, operator, combine, band_mask) XiePhotoElement *element; XiePhototag src1; XiePhototag src2; XieProcessDomain *domain; XieConstant constant; XieCompareOp operator; Bool combine; unsigned int band_mask; Arguments element Specifies the XiePhotoElement structure to use. src1 Specifies the first data source. src2 Specifies the second data source. domain Specifies the subset of source data that will be operated on. constant Specifies the constant data source. operator Specifies the logical predicate operator used in the comparison. combine Specifies whether the comparison should be done on a per-band or on an all-bands basis. band_mask Specifies which bands are to be operated on. Description A Compare element takes two data sources or a single data source and a constant and generates a Boolean bitmap output that reflects the results of a pointwise comparison. The output data has a value of one wherever the comparison is true, and a value of zero everywhere else (that is, comparison false or comparison not performed). The comparison may be performed on a per-band basis or for all bands taken together. When two sources are involved, src1 and src2 are the phototags of the elements supplying source data; constant is ignored. A phototag is the position or index of an element within an array of elements used to specify a photoflo; the first element in the array has a phototag value of one (1). If the operation is to involve a constant, src1 is one operand, src2 must be zero, and constant is used as the other operand. In order to specify a subset of source data that will be operated on, the phototag, offset_x, and offset_y fields of the XieProcessDomain structure pointed to by domain must be supplied; XIElib does not provide a convenience function to create and/or fill in an XieProcessDomain structure. If the entire source data is to be operated on, a pointer to an XieProcessDomain structure must still be provided, with the phototag field set to zero (0); the offset_x and offset_y fields are ignored. operator is the logical predicate operator used in the comparison. The valid operators for the Compare process element are: Operator src1 (operator) src2 src1 (operator) constant xieValLT src1 * src2 src1 * constant xieValLE src1 * src2 src1 * constant xieValEQ src1 * src2 src1 * constant xieValNE src1 * src2 src1 * constant xieValGT src1 * src2 src1 * constant xieValGE src1 * src2 src1 * constant combine is a Boolean that determines whether the comparison should be done on a per-band basis or on an all-bands basis. Only bands selected by 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 significant band would be processed; operating on all bands requires a band_mask of 1112. If combine is True or src1 is single band, the output data will form a single Boolean bitmap. If src1 is triple band and combine is False, the output data will yield three separate boolean bitmaps (for this case band_mask must specify all bands). If src1 is triple band and combine is True, only the EQ and NE operators are allowed; equality is established for each band selected by band_mask, and then the result is logically ANDed to derive equality (inequality is a logical NOT of this result). For this case, width and height must match for all bands selected by band_mask. The relationship between combine and data class dependencies is given in the following table: combine input class band_mask output class True single band n/a single band triple band selected bands single band False single band n/a single band triple band all bands triple band Output Attributes Class see Description Type constrained Width same as src1 Height same as src1 Levels 2 per band (see Description) Structures XieFloCompare sets the XiePhotoElement structure field elemType to xieElemCompare, which identifies the element as a Compare, and sets the fields of the member structure Compare using the arguments in the argument list. typedef unsigned XiePhototag; typedef float XieConstant[3]; typedef struct { int offset_x; int offset_y; XiePhototag phototag; } XieProcessDomain; typedef struct { int elemType; union { ... struct { XiePhototag src1; XiePhototag src2; XieProcessDomain domain; XieConstant constant; XieCompareOp operator; Bool combine; unsigned int band_mask; } Compare; ... } data; } XiePhotoElement; /* Definitions of Compare Operators */ #define xieValLT 1 #define xieValLE 2 #define xieValEQ 3 #define xieValNE 4 #define xieValGT 5 #define xieValGE 6 Errors xieErrNoFloAlloc Insufficient resources (for example, memory) xieErrNoFloDomain Invalid domain xieErrNoFloMatch Class differs between src1 and src2 or invalid combination of operator and combine or triple band, and combine is false, and band_mask incomplete xieErrNoFloOperator Invalid operator xieErrNoFloSource Invalid src1 or src2 XIElib - Photoflo Element Functions XieFloConstrain Name XieFloConstrain - specify a Constrain element and set its parameters Syntax void XieFloConstrain (element, src, levels, constrain_tech, constrain_param) XiePhotoElement *element; XiePhototag src; XieLevels levels; XieConstrainTechnique constrain_tech; XiePointer constrain_param; Arguments element Specifies the XiePhotoElement structure to use. src Specifies the element supplying source data. levels Specifies the number of quantization levels desired in the output data. constrain_tech Specifies the technique to be used when constraining the data. constrain_param Specifies the list of additional parameters required by constrain. Description A Constrain element applies a quantization model to the image data to convert the data to a fixed number of quantization levels. Application of the quantization model may involve steps such as range shifting, scaling, clipping, and rounding. src is the phototag of the element supplying source data. A phototag is the position or index of an element within an array of elements used to specify a photoflo; the first element in the array has a phototag value of one (1). Levels is the number of quantization levels desired in the output data. constrain_tech specifies the constrain technique to be used when constraining the data. constrain_param is the list of additional parameters required by constrain_tech. If the input image is already constrained, the data will be reconstrained. One of the following standard constrain technique values can be assigned to constrain_tech : xieValConstrainClipScale xieValConstrainHardClip If a vendor defined additional private constrain techniques, the values given to these techniques can be assigned to constrain_tech. Output Attributes Class same as src Type constrained Width same as src Height same as src Levels levels Structures XieFloConstrain sets the XiePhotoElement structure field elemType to xieElemConstrain, which identifies the element as a Constrain, and sets the fields of the member structure Constrain using the arguments in the argument list. typedef unsigned XiePhototag; typedef unsigned long XieLevels[3]; typedef unsigned XieConstrainTechnique; typedef struct { int elemType; union { ... struct { XiePhototag src; XieLevels levels; XieConstrainTechnique constrain_tech; XiePointer constrain_param; } Constrain; ... } data; } XiePhotoElement; /* Definitions for ConstrainTechniques */ #define xieValConstrainClipScale 2 #define xieValConstrainHardClip 4 Errors xieErrNoFloAlloc Insufficient resources (for example, memory) xieErrNoFloSource Invalid src xieErrNoFloTechnique Invalid constrain_tech or constrain_param See Also XieTecClipScale XIElib - Photoflo Element Functions XieFloConvertFromIndex Name XieFloConvertFromIndex - specify a ConvertFromIndex element and set its parameters Syntax void XieFloConvertFromIndex (element, src, colormap, data_class, precision) XiePhotoElement *element; XiePhototag src; Colormap colormap; XieDataClass data_class; unsigned int precision; Arguments element Specifies the XiePhotoElement structure to use. src Specifies the element supplying source data. colormap Specifies the Colormap from which to obtain output pixel values. data_class Specifies whether the output data is single band or triple band. precision Specifies the number of bits to be used from colormap's RGB values. Description A ConvertFromIndex element converts Colormap index data into achromatic or trichromatic data. data_class specifies whether the output data is single band or triple band and can be set to one of the following standard data class values: xieValSingleBand xieValTripleBand If data_class is single band and a trichromatic colormap is specified (static color, pseudo color, true color, or direct color), the gray shade for each pixel is taken from the red values in colormap. If data_class is triple band and an achromatic colormap is specified (static gray or gray scale), the red band will be replicated to populate the green and blue output bands. The depth of colormap must match the Levels attribute of src (that is, 2depth must equal Levels). Output Attributes Class data_class Type constrained Width same as src Height same as src Levels 2precision (per band) Structures XieFloConvertFromIndex sets the XiePhotoElement structure field elemType to xieElemConvertFromIndex, which identifies the element as a ConvertFromIndex, and sets the fields of the member structure ConvertFromIndex using the arguments in the argument list. typedef unsigned XieDataClass; typedef unsigned XiePhototag; typedef struct { int elemType; union { ... struct { XiePhototag src; Colormap colormap; XieDataClass data_class; unsigned int precision; } ConvertFromIndex; ... } data; } XiePhotoElement; /* Definitions of DataClass */ #define xieValSingleBand 1 #define xieValTripleBand 2 Errors xieErrNoFloAlloc Insufficient resources (for example, memory) xieErrNoFloColormap Invalid colormap xieErrNoFloMatch Levels of src do not match depth of colormap xieErrNoFloSource Invalid src xieErrNoFloValue Invalid data_class or precision XIElib - Photoflo Element Functions XieFloConvertFromRGB Name XieFloConvertFromRGB - specify a ConvertFromRGB element and set its parameters Syntax void XieFloConvertFromRGB (element, src, color_space, color_param) XiePhotoElement *element; XiePhototag src; XieColorspace color_space; XiePointer color_param; Arguments element Specifies the XiePhotoElement structure to use. src Specifies the element supplying source data (RGB assumed). color_space Specifies the technique to be used in the conversion. color_param Specifies the list of additional parameters required by color_space. Description A ConvertFromRGB element converts RGB source data to an alternate colorspace. The source data must be triple band, and all bands must have equal dimensions. The type and levels of the output data are determined by the color_space's technique parameters. All other attributes are inherited from src. ConvertFromRGB techniques define the trichromatic colorspaces known to a ConvertFromRGB element. One of the following standard ConvertFromRGB technique values can be assigned to color_space: xieValRGBToCIELab xieValRGBToCIEXYZ xieValRGBToYCbCr xieValRGBToYCC If a vendor defined additional private ConvertFromRGB techniques, the private technique values given to these techniques can be assigned to color_space. Output Attributes Class triple band Type color_space dependent Width same as src Height same as src Levels color_space dependent Structures XieFloConvertFromRGB sets the XiePhotoElement structure field elemType to xieElemConvertFromRGB, which identifies the element as a ConvertFromRGB, and sets the fields of the member structure ConvertFromRGB using the arguments in the argument list. typedef unsigned XiePhototag; typedef unsigned XieColorspace; typedef struct { int elemType; union { ... struct { XiePhototag src; XieColorspace color_space; XiePointer color_param; } ConvertFromRGB; ... } data; } XiePhotoElement; /* Definitions for Colorspace Conversions */ #define xieValRGBToCIELab 2 #define xieValRGBToCIEXYZ 4 #define xieValRGBToYCbCr 6 #define xieValRGBToYCC 8 Errors xieErrNoFloAlloc Insufficient resources (for example, memory) xieErrNoFloMatch src is not triple band or unequal inter-band dimensions xieErrNoFloSource Invalid src xieErrNoFloTechnique Invalid color_space or color_param See Also XieFloConvertToRGB, XieTecRGBToCIELab, XieTecRGBToCIEXYZ, XieTecRGBToYCbCr, XieTecRGBToYCC XIElib - Photoflo Element Functions XieFloConvertToIndex Name XieFloConvertToIndex - specify a ConvertToIndex element and set its parameters Syntax void XieFloConvertToIndex (element, src, colormap, color_list, notify, color_alloc_tech, color_alloc_param) XiePhotoElement *element; XiePhototag src; Colormap colormap; XieColorList color_list; Bool notify; XieColorAllocTechnique color_alloc_tech; XiePointer color_alloc_param; Arguments element Specifies the XiePhotoElement structure to use. src Specifies the element supplying the constrained source data. colormap Specifies the Colormap from which to obtain output pixel values. color_list Specifies the list where Colormap indices are to be stored. notify Specifies whether to enable sending ColorAlloc events. color_alloc_tech Specifies the desired color allocation technique. color_alloc_param Specifies the list of additional parameters required by color_alloc_tech. Description A ConvertToIndex element allocates and/or matches colors or gray shades, as required, from a Colormap. It produces pixel indices as output data, and records indices that it allocates in color_list. The specified color_alloc_tech technique may generate a ColorAlloc event to warn the client that results are of lesser fidelity than desired. Notify allows the client to be notified about inferior results from color allocation or matching. src is the phototag of the element supplying constrained source data. A phototag is the position or index of an element within an array of elements used to specify a photoflo; the first element in the array has a phototag value of one (1). Colormap is the Colormap from which colors or gray shades are allocated and/or matched. Color_list is the list where allocated Colormap indices are to be stored. color_alloc_tech specifies the desired color allocation technique. color_alloc_params is the list of additional parameters required by color_alloc_tech. color_list is purged of any colors it already contains when photoflo execution begins. Allocated Colormap indices can be freed using XiePurgeColorList, XieDestroyColorList, or by making color_list the target of an active photoflo. Care must be taken to ensure that color_list is not referenced by more than one executing photoflo at any time; it is a protocol error to allow more than one executing photoflo access the same color_list. ColorAlloc techniques define the recognized color allocation techniques used by the ConvertToIndex element. One of the following standard ColorAlloc technique values can be assigned to color_alloc_tech: xieValColorAllocDefault xieValColorAllocAll xieValColorAllocMatch xieValColorAllocRequantize If a vendor defined additional private ColorAlloc techniques, the private technique values given to these techniques can be assigned to color_alloc_tech. The server is required to support the default technique that is bound to one of the standard techniques defined or a private technique. Output Attributes Class single band Type constrained Width same as src Height same as src Levels 2depth (that is, colormap depth) Structures XieFloConvertToIndex sets the XiePhotoElement structure field elemType to xieElemConvertToIndex, which identifies the element as a ConvertToIndex, and sets the fields of the member structure ConvertToIndex using the arguments in the argument list. typedef unsigned XiePhototag; typedef XID XieColorList; typedef unsigned XieColorAllocTechnique; typedef struct { int elemType; union { ... struct { XiePhototag src; Colormap colormap; XieColorList color_list; Bool notify; XieColorAllocTechnique color_alloc_tech; XiePointer color_alloc_param; } ConvertToIndex; ... } data; } XiePhotoElement; /* Definitions for ColorAlloc Techniques */ #define xieValColorAllocDefault 0 #define xieValColorAllocAll 2 #define xieValColorAllocMatch 4 #define xieValColorAllocRequantize 6 Errors xieErrNoFloAccess color_list already being used by another active photoflo xieErrNoFloAlloc Insufficient resources (for example, memory) xieErrNoFloColorlist Invalid color_list xieErrNoFloColormap Invalid colormap xieErrNoFloMatch Unequal inter-band dimensions xieErrNoFloSource Invalid src xieErrNoFloTechnique Invalid color_alloc_tech or color_alloc_param See Also XieCreateColorList, XiePurgeColorList, XieDestroyColorList XieTecColorAllocAll, XieTecColorAllocMatch, XieTecColorAllocRequantize XIElib - Photoflo Element Functions XieFloConvertToRGB Name XieFloConvertToRGB - specify a ConvertToRGB element and set its parameters Syntax void XieFloConvertToRGB (element, src, color_space, color_param) XiePhotoElement *element; XiePhototag src; XieColorspace color_space; XiePointer color_param; Arguments element Specifies the XiePhotoElement structure to use. src Specifies the element supplying source data. color_space Specifies the technique that will be used for the conversion. color_param Specifies the list of additional parameters required by color_space. Description A ConvertToRGB element converts alternate colorspace source data into RGB data. The source data must be triple band, and all bands must have equal dimensions. The type and levels of the output data are determined by the color_space's technique parameters. All other attributes are inherited from src. ConvertToRGB techniques define the trichromatic colorspaces known to a ConvertToRGB element. One of the following standard ConvertFromRGB technique values can be assigned to color_space: xieValCIELabToRGB xieValCIEXYZToRGB xieValYCbCrToRGB xieValYCCToRGB If a vendor defined additional private ConvertToRGB techniques, the private technique values given to these techniques can be assigned to color_space. Output Attributes Class triple band Type color_space dependent Width same as src Height same as src Levels color_space dependent Structures XieFloConvertToRGB sets the XiePhotoElement structure field elemType to xieElemConvertToRGB, which identifies the element as a ConvertToRGB, and sets the fields of the member structure ConvertToRGB using the arguments in the argument list. typedef unsigned XieColorspace; typedef unsigned XiePhototag; typedef struct { int elemType; union { ... struct { XiePhototag src; XieColorspace color_space; XiePointer color_param; } ConvertToRGB; ... } data; } XiePhotoElement; /* Definitions for Colorspace Conversions */ #define xieValCIELabToRGB 2 #define xieValCIEXYZToRGB 4 #define xieValYCbCrToRGB 6 #define xieValYCCToRGB 8 Errors xieErrNoFloAlloc Insufficient resources (for example, memory) xieErrNoFloMatch src is not triple band or unequal inter-band dimensions xieErrNoFloSource Invalid src xieErrNoFloTechnique Invalid color_space or color_param See Also XieTecCIELabToRGB, XieTecCIEXYZToRGB, XieTecYCbCrToRGB, XieTecYCCToRGB, XieConvertFromRGB XIElib - Photoflo Element Functions XieFloConvolve Name XieFloConvolve - specify a Convolve element and set its parameters Syntax void XieFloConvolve (element, src, domain, kernel, kernel_size, band_mask, convolve_tech, convolve_param) XiePhotoElement *element; XiePhototag src; XieProcessDomain *domain; float *kernel; int kernel_size; unsigned int band_mask; XieConvolveTechnique convolve_tech; XiePointer convolve_param; Arguments element Specifies the XiePhotoElement structure to use. src Specifies the element supplying source data. domain Specifies the subset of the image that will be operated on. kernel Specifies the coefficients used in the convolution process. kernel_size Specifies the dimension of kernel. band_mask Specifies which bands are to be operated on. convolve_tech Specifies the technique for handling edge conditions. convolve_param Specifies the list of additional parameters required by convolve_tech. Description A Convolve element produces output data by convolving each input pixel value (and surrounding area) with the specified convolution kernel. In order to specify a subset of source data that will be operated on, the phototag, offset_x, and offset_y fields of the XieProcessDomain structure pointed to by domain must be supplied; XIElib does not provide a convenience function to create and/or fill in an XieProcessDomain structure. If the entire source data is to be operated on, a pointer to an XieProcessDomain structure must still be provided, with the phototag field set to zero (0); the offset_x and offset_y fields are ignored. kernel represents a square array of float data that has odd dimensions. Thus, a single dimension is used to specify kernel_size. 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 significant band would be processed; operating on all bands requires a band_mask of 1112. Using band_mask to select source data that have two (2) or less levels is not permitted. All output data attributes are inherited from the source data. Convolve techniques provide various methods of handling edge conditions. These techniques determine what pixel values are used when Convolve requires data beyond the image bounds. One of the following standard convolve technique values can be assigned to convolve_tech: xieValConvolveDefault xieValConvolveConstant xieValConvolveReplicate If a vendor defined additional private convolve techniques, the private technique values given to these techniques can be assigned to convolve_tech. The server is required to support the default technique that is bound to one of the standard techniques defined above or a private technique. Output Attributes Class same as src Type same as src Width same as src Height same as src Levels same as src Structures XieFloConvolve sets the XiePhotoElement structure field elemType to xieElemConvolve, which identifies the element as a Convolve, and sets the fields of the member structure Convolve using the arguments in the argument list. typedef unsigned XieConvolveTechnique; typedef unsigned XiePhototag; typedef struct { int offset_x; int offset_y; XiePhototag phototag; } XieProcessDomain; typedef struct { int elemType; union { ... struct { XiePhototag src; XieProcessDomain domain; float *kernel; int kernel_size; unsigned int band_mask; XieConvolveTechnique convolve_tech; XiePointer convolve_param; } Convolve; ... } data; } XiePhotoElement; /* Definitions for ConvolveTechniques */ #define xieValConvolveDefault 0 #define xieValConvolveConstant 2 #define xieValConvolveReplicate 4 Errors xieErrNoFloAlloc Insufficient resources (for example, memory) xieErrNoFloDomain Invalid domain xieErrNoFloMatch Selected source data are bitonal xieErrNoFloSource Invalid src xieErrNoFloTechnique Invalid convolve_tech or convolve_param xieErrNoFloValue Invalid kernel_size (for example, not odd) See Also XieTecConvolveConstant XIElib - Photoflo Element Functions XieFloDither Name XieFloDither - specify a Dither element and set its parameters Syntax void XieFloDither (element, src, band_mask, levels, dither_tech, dither_param) XiePhotoElement *element; XiePhototag src; unsigned int band_mask; XieLevels levels; XieDitherTechnique dither_tech; XiePointer dither_param; Arguments element Specifies the XiePhotoElement structure to use. src Specifies the element supplying source data. band_mask Specifies which bands are to be operated on. levels Specifies the number of levels desired in the output data. dither_tech Specifies the desired dither technique. dither_param Specifies the list of additional parameters required by dither_tech. Description The Dither element is used to reduce the number of quantization levels in an image. It accomplishes this by affecting adjacent pixels (area affect) to make up for the lack of depth resolution. 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 significant band would be processed; operating on all bands requires a band_mask of 1112. Using band_mask to select source data that have two (2) or less levels is not permitted. The source data must be constrained. Dither techniques define the technique that can be used to dither an image. One of the following standard dither technique values can be assigned to dither_tech: xieValDitherDefault xieValDitherErrorDiffusion xieValDitherOrdered If a vendor defined additional private dither techniques, the private technique values given to these techniques can be assigned to dither_tech. The server is required to support the default technique that is bound to one of the standard techniques defined or a private technique. Output Attributes Class same as src Type constrained Width same as src Height same as src Levels levels Structures XieFloDither sets the XiePhotoElement structure field elemType to xieElemDither, which identifies the element as a Dither, and sets the fields of the member structure Dither using the arguments in the argument list. typedef unsigned XiePhototag; typedef unsigned long XieLevels[3]; typedef unsigned XieDitherTechnique; typedef struct { int elemType; union { ... struct { XiePhototag src; XieLevels levels; unsigned int band_mask; XieDitherTechnique dither_tech; XiePointer dither_param; } Dither; ... } data; } XiePhotoElement; /* Definitions for DitherTechniques */ #define xieValDitherDefault 0 #define xieValDitherErrorDiffusion 2 #define xieValDitherOrdered 4 Errors xieErrNoFloAlloc Insufficient resources (for example, memory) xieErrNoFloDomain Invalid domain xieErrNoFloMatch Unconstrained src data or selected source data are bitonal xieErrNoFloSource Invalid src xieErrNoFloTechnique Invalid dither_tech or dither_param xieErrNoFloValue Invalid output levels: less than two or greater than src levels See Also XieTecDitherOrdered XIElib - Photoflo Element Functions XieFloGeometry Name XieFloGeometry - specify a Geometry element and set its parameters Syntax void XieFloGeometry (element, src, width, height, coefficients, constant, band_mask, sample_tech, sample_param) XiePhotoElement *element; XiePhototag src; unsigned int width; unsigned int height; float coefficients[6]; XieConstant constant; unsigned int band_mask; XieGeometryTechnique sample_tech; XiePointer sample_param; Arguments element Specifies the XiePhotoElement structure to use. src Specifies the element supplying source data. width Specifies the horizontal dimension of the output data. height Specifies the vertical dimension of the output data. coefficients Specifies an affine transformation to be applied to pixels in src. constant Specifies the fill value used for output pixels that do not map back to a src pixel. band_mask Specifies which bands are to be operated on. sample_tech Specifies the technique to be used for retrospectively resampling src. sample_param Specifies the list of additional parameters required by sample_tech. Description A Geometry element is used to perform geometric transformations on image data. Linear geometric resampling operations are implemented, such as: crop, mirror, scale, shear, rotate, translate, and combinations thereof. A Geometry element can be visualized as stepping through each possible output pixel location in turn and computing the location from which to obtain each input pixel value. Each pixel (x',y') in the output image is mapped to the coordinate location (x,y) in src by: The coordinate mapping coefficients (a,b,c,d,tx,ty), together with the output width and height, fully specify the geometric transformation. The following briefly (and approximately) summarizes the intuitive role of each parameter: a, d Scaling parameters. Increasing a and d will make the output image appear smaller, whereas decreasing them will make the output pixels appear larger. b, c Rotation/skew parameters. If b and c are zero, the output image will be a rectangular scaling of the input image. If a and d are both zero, b is one, and c is negative one, the image will appear rotated. The magnitude of b and c will affect scaling as well if a and d are zero. If more than two of (a,b,c,d) are nonzero, the effect is complicated. The image may appear skewed and scaled. tx, ty Translation parameters. Used to specify the offset between input and output coordinate systems. width, height These specify the output image dimensions of the selected band(s). Note that increasing the output image height and width over the input image size will not by itself cause magnification * if a and d are one (1) and b and c are zero (0), the output image will have the same appearance as the input, except that the borders will shrink or expand (as determined by width and height) and new areas of the image will be filled with constant. The region to be cropped in the input image is implicitly defined by the dimensions of the output image and the mapping from output to input coordinates. Depending on the size of the input and output images, the amount of scaling specified, and the amount of translation in the mapping, pixels in the output image may map off the edge of the input image and the constant value is used. Trichromatic image bands can be operated individually, all together, or in any combination, using band_mask. Since applying the same (a,b,c,d,tx,ty) mapping to inputs with diverse sizes will specify different transformations, operating on all bands in unison (band_mask of 1112) is most appropriate if the dimensions of all bands are equal. Often a given output pixel location (x,y) will not correspond exactly to a single pixel in the input image. The sample_tech technique is used to determine how the input data will be interpolated to produce each output pixel value. One of the following standard geometry technique values can be assigned to sample_tech: xieValGeomDefault xieValGeomAntialias xieValGeomAntialiasByArea xieValGeomAntialiasByLPF xieValGeomBilinearInterp xieValGeomGaussian xieValGeomNearestNeighbor If a vendor defined additional private geometry techniques, the private technique values given to these techniques can be assigned to sample_tech. The server is required to support the default technique that is bound to one of the standard techniques defined or a private technique. Output Attributes Class same as src Type same as src Width width Height height Levels same as src Structures XieFloGeometry sets the XiePhotoElement structure field elemType to xieElemGeometry, which identifies the element as a Geometry, and sets the fields of the member structure Geometry using the arguments in the argument list. typedef unsigned XiePhototag; typedef float XieConstant[3]; typedef unsigned XieGeometryTechnique; typedef struct { int elemType; union { ... struct { XiePhototag src; unsigned int width; unsigned int height; float coefficients[6]; XieConstant constant; unsigned int band_mask; XieGeometryTechnique sample_tech; XiePointer sample_param; } Geometry; ... } data; } XiePhotoElement; /* Definitions for GeometryTechniques */ #define xieValGeomDefault 0 #define xieValGeomAntialias 2 #define xieValGeomAntialiasByArea 4 #define xieValGeomAntialiasByLPF 6 #define xieValGeomBilinearInterp 8 #define xieValGeomGaussian 10 #define xieValGeomNearestNeighbor 12 Errors xieErrNoFloAlloc Insufficient resources (for example, memory) xieErrNoFloSource Invalid src xieErrNoFloTechnique Invalid sample_tech or sample_param xieErrNoFloValue Invalid coefficients See Also XieTecGeomAntialiasByArea, XieTecGeomAntialiasByLowpass, XieTecGeomGaussian, XieTecGeomNearestNeighbor XIElib - Photoflo Element Functions XieFloLogical Name XieFloLogical - specify a Logical element and set its parameters Syntax void XieFloLogical (element, src1, src2, domain, constant, operator, band_mask) XiePhotoElement *element; XiePhototag src1; XiePhototag src2; XieProcessDomain *domain; XieConstant constant; unsigned long operator; unsigned int band_mask; Arguments element Specifies the XiePhotoElement structure to use. src1 Specifies the first data source. src2 Specifies the second data source. domain Specifies the subset of source data that will be operated on. constant Specifies the constant data source. operator Specifies the logical operator to be used. band_mask Specifies which bands are to be operated on. Description A Logical element performs per-pixel bitwise operations on a single data source, or between two data sources, or between a single data source and a constant. When two sources are involved, src1 and src2 are the phototags of the elements supplying source data; constant is ignored. A phototag is the position or index of an element within an array of elements used to specify a photoflo; the first element in the array has a phototag value of one (1). If the operation is to involve a constant, src1 is one operand, src2 must be zero, and constant is used as the other operand. In order to specify a subset of source data that will be operated on, the phototag, offset_x, and offset_y fields of the XieProcessDomain structure pointed to by domain must be supplied; XIElib does not provide a convenience function to create and/or fill in an XieProcessDomain structure. If the entire source data is to be operated on, a pointer to an XieProcessDomain structure must still be provided, with the phototag field set to zero (0); the offset_x and offset_y fields are ignored. The value of operator matches the GC-function values defined by the core protocol specification for CreateGC. The output of a Logical element is determined by the number of data sources and operator: GC function monadic operation dyadic operation Clear 0 0 And constant AND src1 src2 AND src1 AndReverse constant AND (NOT src1) src2 AND (NOT src1) Copy constant src2 AndInverted (NOT constant) AND src1 (NOT src2) AND src1 NoOp src1 src1 Xor constant XOR src1 src2 XOR src1 Or constant OR src1 src2 OR src1 Nor (NOT constant) AND (NOT src1) (NOT src2) AND (NOT src1) Equiv (NOT constant) XOR src1 (NOT src2) XOR src1 Invert NOT src1 NOT src1 OrReverse constant OR (NOT src1) src2 OR (NOT src1) CopyInverted NOT constant NOT src2 OrInverted (NOT constant) OR src1 (NOT src2) OR src1 Nand (NOT constant) OR (NOT src1) (NOT src2) OR (NOT src1) Set 1 1 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 significant band would be processed; operating on all bands requires a band_mask of 1112. Output Attributes Class same as src1 Type constrained Width same as src1 Height same as src1 Levels same as src1 Structures XieFloLogical sets the XiePhotoElement structure field elemType to xieElemLogical, which identifies the element as a Logical, and sets the fields of the member structure Logical using the arguments in the argument list. typedef unsigned XiePhototag; typedef float XieConstant[3]; typedef struct { int offset_x; int offset_y; XiePhototag phototag; } XieProcessDomain; typedef struct { int elemType; union { ... struct { XiePhototag src1; XiePhototag src2; XieProcessDomain domain; XieConstant constant; int operator; unsigned int band_mask; } Logical; ... } data; } XiePhotoElement; Errors xieErrNoFloAlloc Insufficient resources (for example, memory) xieErrNoFloDomain Invalid domain xieErrNoFloMatch Class or levels differ between src1 and src2, or levels is not a power of 2, or src1 or src2 in not constrained xieErrNoFloOperator Invalid operator xieErrNoFloSource Invalid src1 or src2 XIElib - Photoflo Element Functions XieFloMatchHistogram Name XieFloMatchHistogram - specify a MatchHistogram element and set its parameters Syntax void XieFloMatchHistogram (element, src, domain, shape, shape_param) XiePhotoElement *element; XiePhototag src; XieProcessDomain *domain; XieHistogramShape shape; XiePointer shape_param; Arguments element Specifies the XiePhotoElement structure to use. src Specifies the element supplying source data. domain Specifies the subset of source data that will be operated on. shape Specifies the form of the desired output data histogram. shape_param Specifies the list of additional parameters required by shape. Description A MatchHistogram element produces output data that differ from the source data in terms of its pixel value distribution, or histogram. It allows the client to specify the desired shape of the resulting data's histogram (algorithmic description of resulting histogram shape). The source data must be constrained and single band, and it must have three or more levels. In order to specify a subset of source data that will be operated on, the phototag, offset_x, and offset_y fields of the XieProcessDomain structure pointed to by domain must be supplied; XIElib does not provide a convenience function to create and/or fill in an XieProcessDomain structure. Only data that intersects with the subset specified by domain is included in the histogram, and only that data will be affected in the result of the histogram matching operation: all other data will pass through unchanged. If the entire source data is to be operated on, a pointer to an XieProcessDomain structure must still be provided, with the phototag field set to zero (0); the offset_x and offset_y fields are ignored. HistogramShape defines the various match-histogram shape techniques that can be requested by a MatchHistogram element. One of the following standard match-histogram shape technique values can be assigned to shape: xieValHistogramFlat xieValHistogramGaussian xieValHistogramHyperbolic If a vendor defined additional private match-histogram shape techniques, the private technique values given to these techniques can be assigned to shape. Output Attributes Class single band Type constrained Width same as src Height same as src Levels same as src Structures XieFloMatchHistogram sets the XiePhotoElement structure field elemType to xieElemMatchHistogram, which identifies the element as a MatchHistogram, and sets the fields of the member structure MatchHistogram using the arguments in the argument list. typedef unsigned XiePhototag; typedef unsigned XieHistogramShape; typedef struct { int offset_x; int offset_y; XiePhototag phototag; } XieProcessDomain; typedef struct { int elemType; union { ... struct { XiePhototag src; XieProcessDomain domain; XieHistogramShape shape; XiePointer shape_param; } MatchHistogram; ... } data; } XiePhotoElement; /* Definitions for GeometryTechniques */ #define xieValGeomDefault 0 #define xieValGeomAntialias 2 #define xieValGeomAntialiasByArea 4 #define xieValGeomAntialiasByLPF 6 #define xieValGeomBilinearInterp 8 #define xieValGeomGaussian 10 #define xieValGeomNearestNeighbor 12 Errors xieErrNoFloAlloc Insufficient resources (for example, memory) xieErrNoFloDomain Invalid domain xieErrNoFloMatch Invalid src data: unconstrained, triple band, or bitonal xieErrNoFloSource Invalid src xieErrNoFloTechnique Invalid shape or shape_param See Also XieTecHistogramGaussian, XieTecHistogramHyperbolic XIElib - Photoflo Element Functions XieFloMath Name XieFloMath - specify a Math element and set its parameters Syntax void XieFloMath (element, src, domain, op