get_buf - Reads a 2-D buffer of data from an image

SYNTAX

#include "worgen.h"

int get_buf(buffer, nlbuf, nsbuf, nlav, nsav, sli, ssi, nli, nsi, nlb, nsb, slcb, sscb, nextflg, band, fill, fdesc, host, dtype)

     unsigned char      *buffer;
     long               *nlbuf;
     long               *nsbuf;
     long               *nlav;
     long               *nsav;
     long               *sli;
     long               *ssi;
     long               *nli;
     long               *nsi;
     long               *nlb;
     long               *nsb;
     long               *slcb;
     long               *sscb;
     long               *nextflg;
     long               *band;
     long               *fill;
     struct FDESC       **fdesc;
     char               *host;
     long               *dtype;

PARAMETERS

buffer (output, byte array)

Buffer of data to be returned. Buffer will be returned as data of the type specified by 'dtype' below.

nlbuf (input, integer)

The total number of lines in 'buffer'.

nsbuf (input, integer)

The total number of samples in 'buffer'.

nlav (output, integer)

The number of lines of actual valid data in 'buffer'.

nsav (output, integer)

The number of samples of actual valid data in 'buffer'.

sli (input, integer)

The starting line of the window within the image.

ssi (input, integer)

The starting sample of the window within the image.

nli (input, integer)

The number of lines within the image window.

nsi (input, integer)

The number of samples within the image window.

nlb (input, integer)

The number of lines in the boundary (top, bottom).

nsb (input, integer)

The number of samples in the boundary (right, left).

slcb (input/output, integer)

The starting line of the data within the image. This is the starting line of the data NOT including any boundary values which may be read from the image.

sscb (input/output, integer)

The starting sample of the data within the image. This is the starting sample of the data NOT including any boundary values which may be read from the image.

nextflg (input, integer)

Next flag. Allowable values are:

     = INIT  (0):     This is the first call to get_buf() for this 
                      image.  The image will need to be opened before
                      reading data.
     = CURNT (1):     Previous call to get_buf() has been made.  Read
                      the data from the image without relocating.  
                      Useful for reading multiple bands without 
                      relocating within the image.
     = NEXT  (2):     Previous call to get_buf() has been made.  
                      Relocate to the 'next' data block (reopening the
                      image if necessary), then read the block of data.

band (input, integer)

The number of the band within the image to read.

fill (input, integer)

Fill technique specification flag:

     = NOFIL (0):     Don't do any boundary filling.  If boundary pixels 
                      exist, their values will be undetermined. 

= MIRR (1): Fill boundary pixels by mirroring adjoining image data.

fdesc (input/output, pointer to struct FDESC pointer)

Pointer to the file descriptor pointer obtained from c_eopenr().

host (input, character string, length(CMLEN))

Host name of the image file.

dtype (input/output, integer)

Data type. Allowable data types are:

     = EBYTE (1):     unsigned byte data
     = EWORD (2):     signed two byte data
     = ELONG (3):     signed four byte data
     = EREAL (4):     four byte floating point data
The parameter dtype specifies the data type of the file that the calling program would like to see. If this data type is not the same as that of the actual file, then upon reading, the data will be converted to this data type before being placed in the user's buffer. If dtype = 0 (zero), the actual data type of the image file is specified and returned.

DESCRIPTION

The function get_buf() allows the application programmer to read a block of data from an image using random access image I/O without implementing all of the low-level details.

Error checking is performed on the input parameters, where appropriate. Space for the return buffer must be allocated prior to calling get_buf().

An entire image can be processed using get_buf(), or a subset of an image (a window), may be specified.

The buffer returned by get_buf() should be thought of as a 2-D array, a 'center buffer' of data surrounded by a 'boundary' of data. The boundaries may be specified to be zero (no boundaries). All of the boundary pixels that can be read from the image will be pixels which lie outside the specified image window will NOT be read from the image. Boundary pixels may be determined by using a fill algorithm if they cannot be read from the image.

The function get_buf() was designed such that the application programmer can read an entire image by simply making multiple calls to get_buf() acquiring consecutive blocks of data from the image. The origin, or beginning location of the data on the image must be specified. The 'nextflg' parameter determines whether to relocate to the 'next block' of data on the image before reading, or to read at the current origin. For the sake of efficiency, the application programmer may want to read multiple bands of data before moving on to the next data block (each call to get_buf() returns data from one band only). All of the image file opening, closing, and reopening is performed by get_buf() except the final closing of the file. The final closing of the image file must be done by the application programmer using the random access routine eclose().

If the application programmer is 'jumping around' within an image (reading blocks of data in a random fashion), then the image must be closed by calling eclose() every time a move to a new location within the image is anticipated. Consequently, disk access time is optimized by taking advantage of the 'next' capability, and reading consecutive blocks of data.

When the programmer is taking advantage of the 'next flag' capability, the data blocks within an image are consecutive on a column-first basis (the first 'n' blocks are read from the first column, then the block at the top of the second column is read, etc). This sequencing scheme optimizes the efficiency of the low-level random image I/O functions. Partial buffers of data will be returned, when appropriate (when incomplete data blocks on the bottom or right-hand side of the image window are encountered). The actual number of lines and samples is always returned, informing the user of the amount of actual data being returned. Even if a partial buffer of data is returned, the boundaries surrounding the 'center buffer' will always be full-sized boundaries.

Warning: If a partial buffer of data is returned, the values may not lie in contiguous memory locations. This is because C stores 2-D arrays in a row-first manner. The buffer of data returned by get_buf() is to be thought of as a 2-D array. To be specific, if the number of samples returned in the buffer is less than the total number of samples allocated to the buffer, the values will not reside in contiguous memory locations (i.e. there will be 'gaps' in the memory locations).

If the fill flag is specified to be 0 (zero), the value of the pixels lying within the boundaries are undetermined (note that the boundary locations still do exist). The value of the number of actual valid lines and samples being returned will include the 'garbage' boundary pixels.

RETURN VALUE

get_buf() returns

       E_SUCC (0)  --> success
       E_FAIL (-1) --> failure
       E_EOIW (1)  --> read origin beyond image window