DC_READ_8_BIT Function
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 DC_READ_24_BIT Function.
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.
See Also
For more information on input and output of image data, see the PV‑WAVE Programmer’s Guide.