xil_get_memory_storage(3)

NAME

xil_get_memory_storage, xil_set_memory_storage − get and set memory storage

SYNOPSIS

#include <xil/xil.h>

Xil_boolean xil_get_memory_storage ( XilImage image,

XilMemoryStorage ∗storage);

void xil_set_memory_storage ( XilImage image,

XilMemoryStorage ∗storage);

DESCRIPTION

Use these functions when you want to get or set the data in an image.

xil_get_memory_storage () returns a description of how an exported image is stored in system memory. Storage for this description must be allocated by the user. xil_get_memory_storage () returns TRUE if the memory storage could be obtained, and FALSE otherwise. This can be used before calls such as fread(3S) to test whether the data is available for the desired operation. The information returned by xil_get_memory_storage () is valid only while the image remains exported. After the image is imported, both the address at which the image’s pixel values are located and the pixel layout in memory is likely to change. Thus, the information that was returned by xil_get_memory_storage () prior to the import is no longer valid. Trying to access pixel values using invalid pointers to the data or using invalid information about the pixel layout can cause serious problems in an application. In the XIL library, multibanded images - except for 1-bit images - are stored in a pixel-sequential format. The following attributes are only exposed to the application if the image is exported:

Distance to the same pixel on the next horizontal scanline (the vertical stride)
Distance to the next pixel on the same scanline (the pixel stride)
Starting address of the image

For 1-bit multibanded images, the data is stored in a band-sequential manner. The export of 1-bit images exposes four private attributes that define the image storage:

Distance in bytes to the byte of the same pixel in the next scanline
Distance in bytes to the same pixel of the next band
Number of bits to offset to the first pixel
Byte starting address of the image data

User data may be imported after image creation if it meets the layout and data type criteria described.

XilMemoryStorage is defined as follows:

typedef union XilMemoryStorageBit {
     struct {
Xil_unsigned8∗ data;/∗ pointer to first byte of image ∗/
unsigned short scanline_stride;/∗ the number of bytes between scanlines ∗/
unsigned long band_stride;/∗ the number of bytes between bands ∗/
unsigned char offset;/∗ the number of bits to the first pixel ∗/
     } bit;
     struct XilMemoryStorageByte {
Xil_unsigned8∗ data;/∗ pointer to the first byte of the image ∗/
unsigned long scanline_stride;/∗ the number of bytes between scanlines ∗/
unsigned short pixel_stride;/∗ the number of bytes between pixels ∗/
     } byte;

struct XilMemoryStorageShort {
Xil_signed16∗ data;/∗ pointer to the first word of the image ∗/
unsigned long scanline_stride;/∗ the number of 16 bit words between scanlines ∗/
unsigned short pixel_stride;/∗ the number of 16 bit words between pixels ∗/
} shrt;
}XilMemoryStorage;

When manipulating the data, it’s important to use the scanline_stride and pixel_stride information returned by xil_get_memory_storage (); you cannot make assumptions about the image’s format in memory storage. For example, some accelerators may not handle 3-banded RGB images while they do handle 4-banded (RGBA) images. For these accelerators, the memory storage code converts 3-banded images into 4-banded images when the first accelerator function is called on the image data. If the image is then exported, the XIL library returns a 3-banded child of a 4-banded image as the data layout for the 3-banded image that was imported. This means that the code written on the exported data cannot assume a 3-pixel layout and cannot skip to the beginning of the next pixel by simply doing a ∗src++.

xil_set_memory_storage () allows an application to specify the memory used for an image. This storage is specified with the same XilMemoryStorage structure that xil_get_memory_storage () uses. The memory must be both readable and writable. After xil_set_memory_storage () has been called, the image resides in the specified memory only while the image remains exported.

ERRORS

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

EXAMPLES

Fill an image with the contents of a file. Note that you must export the image before you can call xil_get_memory_storage(). Likewise, you must import it when you are done using the data.

XilImage image;
int width, height, nbands;
XilDataType datatype;
XilMemoryStorage storage;
Xil_boolean status;
char ∗infile = "input_image";
xil_export(image);
status = xil_get_memory_storage(image, &storage);
if(status == FALSE) {
/∗ XIL’s error handler will print an error msg to stderr ∗/
exit(1);
}
int h, w, n;
Xil_unsigned8∗ scanline = storage.byte.data;
xil_get_info(image, &width, &height, &nbands, &datatype);
/∗
∗ The following loop uses fread to read from an infile. The same
∗ loop could be used to write to an outfile by replacing fread with
∗ fwrite and replacing the infile with an outfile
∗/
for(h=0; h<height; h++) {
    Xil_unsigned8∗ row = scanline;
    for(w=0; w<width; w++) {
        fread((char∗)row, nbands, sizeof(Xil_unsigned8), infile);
        row += storage.byte.pixel_stride;
    }
    scanline += storage.byte.scanline_stride;
}
xil_import(image);

NOTES

The information returned from xil_get_memory_storage () or set by xil_set_memory_storage () is valid only as long as the image is exported. Memory resources allocated by the XIL library are freed by the XIL library. Memory resources allocated by an application are not freed by the XIL library.

Museum

Related Articles