XieGetImage(3X) — Subroutines
Digital
NAME
XieGetImage − This routine creates a client XieImage from an existing server image with image data optional.
C Format
image = XieGetImage(pho_id, compres, cmpprm, cmp_org, pxl_mod,
scn_mod, mode)
C Argument Information
XieImage image;
XiePhoto pho_id;
unsigned char compres;
unsigned long cmpprm;
unsigned char cmp_org;
unsigned char pxl_mod;
unsigned char scn_mod;
unsigned char mode;
RETURN VALUES
The routine returns the newly created XieImage in the image argument. You can free the image using the XieFreeImage routine.
PARAMETERS
pho_idThe pho_id argument specifies the identifier of the source image. The source image can be an unbound photomap, a photoflo, or a phototap or photomap bound to the photoflo. The photoflo is specified explicitly if the source image is a photoflo, or implicitly if the source image is a phototap or a photomap bound to the photoflo.
compresThe compres argument specifies the compression scheme for the newly created XieImage.
cmpprmThe cmpprm argument specifies a parameter required for the DCT compression scheme.
cmp_orgThe cmp_org argument specifies the component organization for the XieImage.
pxl_modThe pxl_mod argument specifies the image pixel stride modulo. The pixel stride modulo is the modulo of the number of bits between the starting points of adjacent pixels on a scanline. For example, a pixel stride modulo of 8 indicates the pixel stride is a multiple of a byte. If you specify a value of less than 2 for this argument, the routine does not add padding bits.
scn_modThe scn_mod argument specifies the image scanline stride modulo. The scanline stride modulo is the modulo of the number of bits between the starting points of adjacent scanlines. For example, a scanline stride modulo of 32 indicates that the scanline stride is a multiple of a longword. If you specify a scanline stride modulo of less than 2, the routine does not add scanline padding bits.
modeThe mode argument specifies the disposition of image data in the new XieImage.
| Symbol | Status of Image Data in the New XieImage |
| XieK_DataNone | Zero image data pointers |
| XieK_DataAlloc | Allocate new image buffers containing no data |
| XieK_DataCopy | Allocate new image buffers and fetch data, if available |
DESCRIPTION
This routine creates a client XieImage from an existing server image with image data optional. The attributes of the new XieImage are the same as the attributes of the source image and the image data format is that specified by the cmp_org argument. Transport of image data to the new XieImage depends on the value of the mode argument.
If you specify a value of XieK_DataNone or XieK_DataAlloc for the mode argument, no data is transported and you are responsible for transporting all planes of the image data, using the desired compression scheme and component organization. If you specify a value of XieK_DataCopy, an attempt is made to transport all image data planes using the specified compression scheme and component organization. The stream field of the returned XieImageRec indicates the status of the requested data as follows:
| Symbol Returned | Meaning |
| XieK_StreamFinal | All of the image has been retrieved |
| XieK_StreamEmpty | Some or all of the image is unavailable -- try again later using the XieGetImageData routine |
| XieK_StreamError | A server error occurred while retrieving the data |
When requesting data from a photoflo, the returned status is normally XieK_StreamEmpty. In this case, use the XieGetImageData routine, either during or after photoflo execution, to retrieve image data created by the photoflo.
XIE Events and Error Messages
Protocol Messages: X_ieQueryResource
X_ieSetTransport for XieK_DataCopy mode only
X_ieGetStream 1 or more times per plane for the XieK_DataCopy mode only
XIE event returned: None
XieLib errors: Reply error, BadLength
Fatal, invalid mode argument
Returns null if the source image is invalid
XieServer errors: BadIDChoice -- Invalid identifier