xil_get_storage_with_copy(3)

NAME

xil_get_storage_with_copy, xil_set_storage_with_copy − get and set the image’s storage through a copy to or from contiguous memory

SYNOPSIS

#include <xil/xil.h>

XilStorage xil_get_storage_with_copy (XilImage image);

int xil_set_storage_with_copy (XilImage image,
XilStorage storage);

DESCRIPTION

Use these calls as a convenient way of copying a contiguous memory buffer into an image or accessing a copy of an image’s storage as a contiguous memory buffer.

xil_get_storage_with_copy() provides a convenient way of retrieving storage for the image without having to loop over tiles. The returned XilStorage object has been filled in with the appropriate data layout information and a valid data pointer. The type of the storage can be ascertained through the xil_storage_is_type(3) call. The storage data pointer is to a copy of image’s storage and therefore no changes made to the storage will propogate to the image.

If the image is very large there will be a peformance penalty caused by a copy of the image data. This call returns a created and filled XilStorage object. It is not necessary to call xil_storage_create(3) before using this call, although the user is still expected to destroy the XilStorage object after use with a call to xil_storage_destroy(3).

xil_set_storage_with_copy() provides a convenient way to set the storage associated with image without having to loop over tiles. The data described by storage will be copied into the various storage tiles of the image and subsequent changes to the original data pointer will not affect image’s data. Before calling xil_set_storage_with_copy(), the user is expected to fill in the appropriate data layout fields for the storage type.

ERRORS

For a complete list of XIL error messages by number, consult Appendix B of the XIL Programmer’s Guide.

EXAMPLES

Retrieve a copy of the data associated with an XIL image. Copy the data to a file.

XilImage image;
int width, height, nbands;
XilDataType datatype;
XilStorage storage;
Xil_unsigned8∗ data;
unsigned int pstride;
unsigned int sstride;
Xil_unsigned8∗ scanline;
Xil_unsigned8∗ pixel;
/∗
∗ This is assuming a byte image
∗/
xil_get_info(image,&width,&height,&nbands,&datatype);
xil_export(image);
storage = xil_get_storage_with_copy(image);
/∗
∗ Optimize for the PIXEL_SEQUENTIAL case with packed
∗ data
∗/
if((xil_storage_is_type(XIL_PIXEL_SEQUENTIAL)) &&
   (xil_storage_get_pixel_stride(storage, 0) == nbands) &&
   (xil_storage_get_scanline_stride(storage, 0) == width∗nbands)) {
    /∗
     ∗ You only need to pick up the 0 band data ptr
     ∗ because information is consistent across all bands
     ∗/
     data = xil_storage_get_data(storage,0);
    /∗
     ∗ Copy from the data ptr to the file for
     ∗ nbands∗width∗height bytes
     ∗/
} else {
/∗
∗ A general case to handle any type of storage
∗/
    for(h=0; h<height; h++) {
       for(w=0; w<width; w++) {
           for(b=0; b<nbands; b++) {
              /∗
               ∗ Get the information for this band.
               ∗/
               Xil_unsigned8∗ data =
                              (Xil_unsigned8∗)xil_storage_get_data(storage, b);
               unsigned int   sstride =
                              xil_storage_get_scanline_stride(storage, b);
               unsigned int   pstride =
                              xil_storage_get_pixel_stride(storage, b);
               /∗
               ∗ Get the byte we’re expected to write for
               ∗ this band.
               ∗/
               Xil_unsigned8 val = ∗(data + h∗sstride + w∗pstride);
               /∗ write the byte to the output file ∗/
           }
       }
   }
}
xil_storage_destroy(storage);
xil_import(image,FALSE);
Copy data from a file on disk into an XilImage.
XilImage image;
XilStorage storage;
/∗
∗ Gain access to input file via mmap....
∗ Then create a storage object.
∗/
storage = xil_storage_create(state,image);
/∗
∗ Describe the storage to XIL.
∗ In this case it’s an XIL_PIXEL_SEQUENTIAL, XIL_BYTE image
∗/
xil_storage_set_pixel_stride(storage, 0, nbands);
xil_storage_set_scanline_stride(storage, 0, nbands∗width);
xil_storage_set_data(storage, 0, mmap_ptr, NULL);
/∗
∗ Export the image to gain control of storage
∗/
xil_export(image);
xil_set_storage_with_copy(image, storage);
/∗
∗ Cleanup by destroying the storage object and unmapping the file.
∗/
xil_storage_destroy(storage);
xil_import(image, TRUE);

Museum