DC_READ_8_BIT Function

PV-WAVE Foundation > Reference Guide > Procedure and Function Reference: D > DC_READ_8_BIT Function

Reads an 8-bit image file.

Usage

status = DC_READ_8_BIT(filename, imgarr)

Input Parameters

filename — A string containing the pathname and filename of the 8-bit image file.

Output Parameters

imgarr — The byte array into which the 8-bit image data is read.

Returned Value

status — The value returned by DC_READ_8_BIT; expected values are:

< 0 — Indicates an error, such as an invalid filename.

0 — Indicates a successful read.

Keywords

XSize — The width (size in the x direction) of imgarr. XSize is computed and output if imgarr is not explicitly dimensioned. XSize is returned as an integer.

YSize — The height (size in the y direction) of imgarr. YSize is computed and output if imgarr is not explicitly dimensioned. YSize is returned as an integer.

Discussion

DC_READ_8_BIT handles many steps that you have to do yourself when using other PV-WAVE functions and procedures. These steps include: 1) opening the file, 2) assigning it a logical unit number (LUN), and 3) closing the file when you are done reading the data.

If the dimensions of the byte array imgarr are not known, DC_READ_8_BIT makes a “best guess” about the width and height of the image. It guesses by checking the number of bytes in the file and comparing that number to the number of bytes associated with the common image sizes shown in Table 5-1: Common Image Sizes.

If no match is found, DC_READ_8_BIT assumes that the image is square, and returns XSize and YSize as the square root of the number of bytes in the file.

note	You do not need to explicitly dimension imgarr, but if your image data is not one of the standard sizes shown above, you will get more predictable results if you dimension imgarr yourself.

Example

If whirlpool.img is a 512-by-512 image file, the function call:

status = DC_READ_8_BIT(!Dir + '/demo/gallery3/data/whirlpool.img', $

   whirlpool, XSize=xdim, YSize=ydim)

reads the binary data in the file whirlpool.img and transfers it to a variable named whirlpool. It also returns xdim=512 and ydim=512, since these keywords were provided in the function call.

On the other hand, if whirlpool.img is a 200-by-350 image file, the values returned are xdim=264 and ydim=264. The keyword results xdim and ydim are computed by taking the square root of the number of bytes in the file. This conversion is done because 200-by-350 is not a “common” image size for which DC_READ_8_BIT checks.